zone.js

What is zone.js?

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.

What are zone.js's main functionalities?

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);
});

Other packages similar to zone.js

async_hooks

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

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

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

Zone.js

Implements Zones for JavaScript, inspired by Dart.

If you're using zone.js via unpkg (i.e. using https://unpkg.com/zone.js) and you're using any of the following libraries, make sure you import them first

• 'newrelic' as it patches global.Promise before zone.js does
• 'async-listener' as it patches global.setTimeout, global.setInterval before zone.js does
• 'continuation-local-storage' as it uses async-listener

NEW Zone.js POST-v0.6.0

See the new API here.

Read up on Zone Primer.

What's a Zone?

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:

See also

• async-listener - a similar library for node
• Async stack traces in Chrome
• strongloop/zone (Deprecated)
• vizone - control flow visualizer that uses zone.js

Standard API support

zone.js patched most standard web APIs (such as DOM events, XMLHttpRequest, ...) and nodejs APIs (EventEmitter, fs, ...), for more details, please see STANDARD-APIS.md.

Nonstandard API support

We are adding support to some nonstandard APIs, such as MediaQuery and Notification. Please see NON-STANDARD-APIS.md for more details.

Examples

You can find some samples to describe how to use zone.js in SAMPLE.md.

Modules

zone.js patches the async APIs described above, but those patches will have some overhead. Starting from zone.js v0.8.9, you can choose which web API module you want to patch. For more details, please see MODULE.md.

Bundles

There are several bundles under dist folder.

Bundle	Summary
zone.js	the default bundle, contains the most used APIs such as setTimeout/Promise/EventTarget..., also this bundle supports all evergreen and legacy (IE/Legacy Firefox/Legacy Safari) Browsers
zone-evergreen.js	the bundle for evergreen browsers, doesn't include the patch for legacy browsers such as IE or old versions of Firefox/Safari
zone-legacy.js	the patch bundle for legacy browsers, only includes the patch for legacy browsers such as IE or old versions of Firefox/Safari. This bundle must be loaded after zone-evergreen.js, zone.js=zone-evergreen.js + zone-legacy.js
zone-testing.js	the bundle for zone testing support, including jasmine/mocha support and async/fakeAsync/sync test utilities
zone-externs.js	the API definitions for closure compiler

And here are the additional optional patches not included in the main zone.js bundles

Patch	Summary
webapis-media-query.js	patch for MediaQuery APIs
webapis-notification.js	patch for Notification APIs
webapis-rtc-peer-connection.js	patch for RTCPeerConnection APIs
webapis-shadydom.js	patch for Shady DOM APIs
zone-bluebird.js	patch for Bluebird APIs
zone-error.js	patch for Error Global Object, supports remove Zone StackTrace
zone-patch-canvas.js	patch for Canvas API
zone-patch-cordova.js	patch for Cordova API
zone-patch-electron.js	patch for Electron API
zone-patch-fetch.js	patch for Fetch API
zone-patch-jsonp.js	utility for jsonp API
zone-patch-resize-observer.js	patch for ResizeObserver API
zone-patch-rxjs.js	patch for rxjs API
zone-patch-rxjs-fake-async.js	patch for rxjs fakeasync test
zone-patch-socket-io.js	patch for socket-io
zone-patch-user-media.js	patch for UserMedia API

Promise A+ test passed

License

MIT