Package description
The zone.js package is a library that implements Zones for JavaScript. Zones are execution contexts that allow you to intercept and keep track of asynchronous operations in JavaScript. This is particularly useful for debugging, performance tracking, and managing multiple tasks in complex applications such as Angular.
Error Handling
Intercepts errors within a specific zone and allows custom error handling.
Zone.current.fork({
name: 'errorHandlingZone',
onHandleError: (parentZoneDelegate, currentZone, targetZone, error) => {
console.error('Error intercepted in zone:', error);
return false;
}
}).run(() => {
throw new Error('Test Error');
});Execution Context Tracking
Tracks the scheduling and execution of asynchronous tasks, providing insights into the application's asynchronous flow.
Zone.current.fork({
name: 'trackingZone',
onScheduleTask: (delegate, currentZone, targetZone, task) => {
console.log('Task scheduled:', task.source);
return delegate.scheduleTask(targetZone, task);
}
}).run(() => {
setTimeout(() => {
console.log('Timeout callback executed.');
}, 1000);
});Performance Monitoring
Measures the time taken to execute asynchronous tasks, which can be used for performance analysis.
Zone.current.fork({
name: 'performanceMonitoringZone',
onInvokeTask: (delegate, currentZone, targetZone, task, applyThis, applyArgs) => {
const start = performance.now();
delegate.invokeTask(targetZone, task, applyThis, applyArgs);
const duration = performance.now() - start;
console.log('Task took:', duration, 'ms');
}
}).run(() => {
setTimeout(() => {
console.log('Timeout callback executed.');
}, 1000);
});async_hooks is a core Node.js module that provides an API to track asynchronous resources. Unlike zone.js, which works in both browser and Node.js environments, async_hooks is specific to Node.js. It offers a lower-level API compared to zone.js and requires more manual handling.
cls-hooked is a Node.js package that uses async_hooks to provide continuation-local storage (CLS). It allows you to set and get context across async operations, similar to how zones work. However, cls-hooked focuses on context propagation rather than the broader range of interception capabilities that zone.js offers.
continuation-local-storage is another Node.js package that provides CLS functionality. It predates cls-hooked and async_hooks, and it uses a different mechanism to track context. It is less performant than cls-hooked and has been largely superseded by it, but it serves a similar purpose to zone.js in terms of context management.
Readme
Implements Zones for JavaScript.
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.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({
onZoneEnter: 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.
There are two kinds of examples:
For fully working examples:
python -m SimpleHTTPServer 3000).http://localhost:3000/example in your browserBelow are the aforementioned snippets.
Run some function at the end of each VM turn:
zone.fork({
onZoneLeave: function () {
// do some cleanup
}
}).run(function () {
// do stuff
});
var someZone = zone.fork({
onZoneLeave: function () {
console.log('goodbye');
}
});
someZone.fork({
onZoneLeave: function () {
console.log('cya l8r');
}
}).run(function () {
// do stuff
});
// logs: cya l8r
When 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({
onZoneLeave: function () {
console.log('goodbye');
}
});
someZone.fork({
$onZoneLeave: function (parentOnLeave) {
// return the hook
return function onZoneLeave() {
parentOnLeave();
console.log('cya l8r');
};
}
}).run(function () {
// do stuff
});
// logs: goodbye
// cya l8r
+ and - SugarMost 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({
onZoneLeave: function () {
console.log('goodbye');
}
});
someZone.fork({
'+onZoneLeave': function (parentOnLeave) {
console.log('cya l8r');
}
}).run(function () {
// do stuff
});
// logs: goodbye
// cya l8r
This frees you from writing boilerplate to compose a new hook.
Zone.js exports a single object: window.zone.
zone.runRuns a given function within the zone. Explained above.
zone.bindTransforms a function to run within the given zone.
zone.forkzone.fork({
onZoneEnter: function () {},
onZoneLeave: function () {},
onError: function () {},
setTimeout: function () {},
setInterval: function () {},
alert: function () {},
prompt: function () {},
addEventListener: function () {}
});
myZone.run(function () {
// woo!
});
Below describes the behavior of each of these hooks.
zone.onZoneCreatedRuns when a zone is forked.
zone.onZoneEnterBefore a function invoked with zone.run, this hook runs.
If zone.onZoneEnter throws, the function passed to run will not be invoked.
zone.onZoneLeaveAfter a function in a zone runs, the onZoneLeave hook runs.
This hook will run even if the function passed to run throws.
zone.onErrorThis hook is called when the function passed to run or the onZoneEnter hook throws.
zone.setTimeout, zone.setInterval, zone.alert, zone.promptThese 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.
zone.addEventListenerThis hook allows you to intercept calls to EventTarget.addEventListener.
setTimeout, setInterval, and addEventListener work in FF23, IE10, and Chrome.elt.onevent works in FF23, IE10, but not Chrome. There's a fix in the works though!Apache 2.0
FAQs
Zones for JavaScript
The npm package zone.js receives a total of 2,649,080 weekly downloads. As such, zone.js popularity was classified as popular.
We found that zone.js demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers have uncovered 3.7 million fake GitHub stars, highlighting a growing threat linked to scams, fraud, and malware, with these campaigns rapidly increasing over the last six months.
Security News
Deno's Standard Library has stabilized after four years of development, offering developers a collection of well-maintained tools compatible with Deno, Node.js, Cloudflare Workers, and browsers with bundlers.
Security News
Trivial packages, while convenient, can introduce significant risks such as dependency bloat, security vulnerabilities, and performance issues in modern software projects.