Implements Zones for JavaScript, inspired by Dart.
A Zone is an execution context that persists across async tasks. You can think of it as thread-local storage for JavaScript VMs.
See this video from ng-conf 2014 for a detailed explanation:
You can run code within a zone with zone.run.
Tasks scheduled (with setTimeout, setInterval, or event listeners) stay within that zone.
zone.fork().run(function () {
zone.inTheZone = true;
setTimeout(function () {
console.log('in the zone: ' + !!zone.inTheZone);
}, 0);
});
console.log('in the zone: ' + !!zone.inTheZone);The above will log:
'in the zone: false'
'in the zone: true'
Note that the function delayed by setTimeout stays inside the zone.
Zones have a set of hooks that allow you to change the behavior of code running within that zone. To change a zone, you fork it to get a new one.
zone.fork({
beforeTask: function () {
console.log('hi');
}
}).run(function () {
// do stuff
});Hooks that you don't override when forking a zone are inherited from the existing one.
See the API docs below for more.
To start using Zones, you need to include the zone.js script in this package onto
your page. This script should appear in the <head> of your HTML file before any other
scripts, including shims/polyfills.
There are two kinds of examples:
- The kind you have to run
- Illustrative code snippets in this README
For fully working examples:
- Spawn a webserver in the root of the directory in which this repo lives.
(I like to use
python -m SimpleHTTPServer 3000). - Open
http://localhost:3000/examplein your browser
Below are the aforementioned snippets.
var someZone = zone.fork({
afterTask: function () {
console.log('goodbye');
}
});
someZone.fork({
afterTask: function () {
console.log('cya l8r');
}
}).run(function () {
// do stuff
});
// logs: cya l8rWhen you fork a zone, you'll often want to control how the parent zone's hook gets called.
Prefixing a hook with $ means that the hook will be passed the
parent zone's hook, and the hook will be expected to return the function to
be invoked rather than be the function itself.
var someZone = zone.fork({
afterTask: function () {
console.log('goodbye');
}
});
someZone.fork({
$afterTask: function (parentOnLeave) {
// return the hook
return function afterTask() {
parentOnLeave();
console.log('cya l8r');
};
}
}).run(function () {
// do stuff
});
// logs: goodbye
// cya l8rMost of the time, you'll want to run a hook before or after the parent's implementation.
You can prefix a hook with - for running before, and + for running after.
The above can be written like this:
var someZone = zone.fork({
afterTask: function () {
console.log('goodbye');
}
});
someZone.fork({
'+afterTask': function () {
console.log('cya l8r');
}
}).run(function () {
// do stuff
});
// logs: goodbye
// cya l8rThis frees you from writing boilerplate to compose a new hook.
Zone.js exports a single object: window.zone.
Runs a given function within the zone. Explained above.
Transforms a function to run within the given zone.
var myZone = zone.fork({
onZoneCreated: function () {},
beforeTask: function () {},
afterTask: function () {},
onError: function () {},
enqueueTask: function() {},
dequeueTask: function() {},
setTimeout: function () {},
setInterval: function () {},
alert: function () {},
prompt: function () {},
});
myZone.run(function () {
// woo!
});Below describes the behavior of each of these hooks.
Runs when a zone is forked.
Before a function invoked with zone.run, this hook runs.
If zone.beforeTask throws, the function passed to run will not be invoked.
After a function in a zone runs, the afterTask hook runs.
This hook will run even if the function passed to run throws.
This hook is called when the function passed to run or the beforeTask hook throws.
This hook is called when a function is registered with the VM.
For instance setTimeout and addEventListener.
This hook is called when a function is unregistered with the VM.
For instance clearTimeout and removeEventListener.
These hooks allow you to change the behavior of window.setTimeout, window.setInterval, etc.
While in this zone, calls to window.setTimeout will redirect to zone.setTimeout.
These hooks allow you to change the behavior of window.requestAnimationFrame(),
window.webkitRequestAnimationFrame, and window.mozRequestAnimationFrame.
By default the callback is executed in the zone where those methods have been called to avoid growing the stack size on each recursive call.
This hook allows you to intercept calls to EventTarget#addEventListener.
var clickListenerCount = 0;
zone.fork(
$addEventListener: function(parentAddEventListener) {
return function (type, listener) {
if (type === 'click') clickListenerCount++;
return parentAddEventListener.apply(this, arguments);
};
}
);
zone.run(function() {
myElement.addEventListener('click', listener);
myOtherElement.addEventListener('click', listener);
console.log(clickListenerCount); // 2
});This hook allows you to intercept calls to EventTarget#removeEventListener.
var clickListenerCount = 0;
zone.fork(
$removeEventListener: function(parentRemoveEventListener) {
return function (type, listener) {
if (type === 'click') clickListenerCount--;
return parentRemoveEventListener.apply(this, arguments);
};
}
);
zone.run(function() {
myElement.addEventListener('click', listener);
myElement.removeEventListener('click', listener);
console.log(clickListenerCount); // 0
});setTimeout,setInterval, andaddEventListenerwork in FF23, IE10, and Chrome.- stack trace rewrite is kinda ugly and may contain extraneous calls.
elt.oneventworks in FF23, IE10, but not Chrome. There's a fix in the works though!
- async-listener - a similar library for node
- Async stack traces in Chrome
- strongloop/zone
- vizone – control flow visualizer that uses zone.js
Apache 2.0