can-zone

A library that tracks asynchronous activity and lets you know when it has completed. Useful when you need to call a function and wait for all async behavior to complete, such as when performing server-side rendering.

`new Zone()`

Creates a new Zone with no additional overrides. Can then call zone.run to call a function within the Zone.

var Zone = require("can-zone");

var zone = new Zone();

zone.run(function(){

    return "hello world";

}).then(function(data){
    data.result // -> "hello world"
});

*Note: See the <a href="can-zone/register.html" title="In order to do it's magic, can-zone has to register handlers for all of the common JavaScript async operations. If you have code (or a dependency with this code) that does: var st = setTimeout;

And this module loads before can-zone, any time st is used we won't be able to track that within the Zone. To work around this, can-zone/register is used as a script that you run before any other modules. In Node require("can-zone/register");

At the top of your entry-point script. In the Browser You can either add a script tag above all others: <script src="node_modules/can-zone/register.js"></script>

Or, if you're using a module loader / bundler, configure it so that can-zone/register is placed above all others in the bundle.">docs(https://github.com/canjs/can-zone/blob/master/docs/register.md) about ensuring can-zone is registered properly.*

`new Zone(zoneSpec)`

Create a new Zone using the provided ZoneSpec to configure the Zone. The following examples configures a Zone that will time out after 5 seconds.

var Zone = require("can-zone");

var timeoutSpec = function(){
    var timeoutId;

    return {
        created: function(){
            timeoutId = setTimeout(function(){
                Zone.error(new Error("This took too long!"));
            }, 5000);
        },
        ended: function(){
            clearTimeout(timeoutId);
        }
    };
};

var zone = new Zone(timeoutSpec);

Parameters

zoneSpec {ZoneSpec|makeZoneSpec(data)}:
A ZoneSpec object or a function that returns a ZoneSpec object.

These two are equivalent:
```
new Zone({
    created: function(){

    }
});

new Zone(function(){
    return {
        created: function(){

        }
    };
});
```
The latter form is useful so that you have a closure specific to that Zone.

Tasks

JavaScript uses various task queues (and a microtask queue) to run JavaScript in the event loop. See this article and this StackOverflow answer to learn more.

For can-zone to work we have to override various task-creating functionality, this is the list of what we currently implement:

Macrotasks

setTimeout
XMLHttpRequest

Microtasks

requestAnimationFrame
Promise
process.nextTick

Use

can-zone is a library that aids in tracking asynchronous calls in your application. To create a new Zone call it's constructor function with new:

var zone = new Zone();

This gives you a Zone from which you can run code using zone.run:

var Zone = require("can-zone");

new Zone().run(function(){

    setTimeout(function(){
        
    }, 29);

    setTimeout(function(){
        
    }, 13);

    var xhr = new XMLHttpRequest();
    xhr.open("GET", "http://chat.donejs.com/api/messages");
    xhr.onload = function(){
        
    };
    xhr.send();

}).then(function(){
    // All done!
});

The function you provide to run will be run within the Zone. This means any calls to asynchronous functions (in this example setTimeout) will be waited on.

Tasks

JavaScript uses various task queues (and a microtask queue) to run JavaScript in the event loop. See this article and this StackOverflow answer to learn more.

For can-zone to work we have to override various task-creating functionality, this is the list of what we currently implement:

Macrotasks

setTimeout
XMLHttpRequest

Microtasks

requestAnimationFrame
Promise
process.nextTick