eddca4280b
These changes are essentially the same as those introduced in
angular#45273, but they include backward compatibility
for applications that explicitly rely on the order in which microtasks are drained.
This is critically important for our code and other third-party code, which is
beyond our control, to work properly. If a microtask is scheduled within an event
listener to be executed "later", it should indeed be executed later and not synchronously,
as this would break the expected flow of code execution.
The simple code that reproduces the behavior that exists now:
```ts
Zone.current.fork({name: 'child'}).run(() => {
const div = document.createElement('div');
div.style.height = '200px';
div.style.width = '200px';
div.style.backgroundColor = 'red';
document.body.appendChild(div);
function listener() {
Promise.resolve().then(() => {
div.style.height = '400px';
});
}
div.addEventListener('fakeEvent', listener);
div.dispatchEvent(new Event('fakeEvent'));
console.log(div.getBoundingClientRect().height); // 400
});
```
The code above logs 400 as the height, but it should actually log 200 because the
height is updated in a microtask within the event listener.
When using Angular with microfrontend applications, especially when other apps might be
using React, zone.js can disrupt the classical order of operations. For example, when using a
`react-component/trigger`, it schedules a microtask within an event listener using
`Promise.resolve().then(...)` to determine whether the event needs to be re-dispatched.
The event is re-dispatched when the layout has changed, which is why a microtask is used.
With this change, we introduce a global configuration flag,
`__zone_symbol__enable_native_microtask_draining`, to allow consumers to enable
microtask draining within a browser microtask.
This flag is necessary to prevent any breaking changes resulting from this modification.
The previous attempt to address this issue caused a significant number of failures in g3.
Therefore, we are hiding that fix behind the configuration flag.
Closes angular#44446
Closes angular#55590
Closes angular#51328
(cherry picked from commit
|
||
|---|---|---|
| .. | ||
| bundles | ||
| doc | ||
| example | ||
| fesm2015 | ||
| lib | ||
| scripts | ||
| test | ||
| tools | ||
| .gitignore | ||
| BUILD.bazel | ||
| bundles.bzl | ||
| CHANGELOG.md | ||
| check-file-size.js | ||
| DEVELOPER.md | ||
| file-size-limit.json | ||
| karma-base.conf.js | ||
| karma-build-jasmine.conf.js | ||
| karma-build-jasmine.es2015.conf.js | ||
| karma-build-mocha.conf.js | ||
| karma-build-sauce-mocha.conf.js | ||
| karma-build-sauce-selenium3-mocha.conf.js | ||
| karma-build.conf.js | ||
| karma-dist-jasmine.conf.js | ||
| karma-dist-mocha.conf.js | ||
| karma-dist-sauce-jasmine.conf.js | ||
| karma-dist-sauce-jasmine.es2015.conf.js | ||
| karma-dist-sauce-jasmine3.conf.js | ||
| karma-dist-sauce-selenium3-jasmine.conf.js | ||
| karma-dist.conf.js | ||
| karma-evergreen-dist-jasmine.conf.js | ||
| karma-evergreen-dist-sauce-jasmine.conf.js | ||
| karma-evergreen-dist.conf.js | ||
| MODULE.md | ||
| NON-STANDARD-APIS.md | ||
| package.json | ||
| presentation.png | ||
| README.md | ||
| SAMPLE.md | ||
| sauce-evergreen.conf.js | ||
| sauce-selenium3.conf.js | ||
| sauce.conf.js | ||
| sauce.es2015.conf.js | ||
| simple-server.js | ||
| STANDARD-APIS.md | ||
| tools.bzl | ||
| tsconfig-test.json | ||
| tsconfig.json | ||
| zone.ts | ||
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
Development Status of Zone.js
As Angular moves towards a zoneless application development model, Zone.js is no longer accepting new features, including additional patches for native platform APIs. The team will also not be accepting any low priority bug fixes. Any critical bug fixes that relate to Angular's direct use of Zone.js will still be accepted.
While still a supported part of Angular, the Angular team strongly discourages using Zone.js outside of Angular application contexts.
NEW Zone.js POST-v0.6.0
See the new API here.
Read up on Zone Primer.
BREAKING CHANGES since Zone.js v0.11.1
Prior to v0.11.1, Zone.js provided two distribution bundle formats in the dist folder.
They were (1) ES5 bundle distributed as zone.js and (2) ES2015 bundle distributed as zone-evergreen.js.
Both of these bundles were in UMD format, and are used for Angular's differential-loading mechanism.
Starting with v0.11.1, Zone.js follows the Angular Package Format. Therefor the new Zone.js file layout is:
bundles:ES5bundle inUMDformat.fesm2015:ES5bundle inESMformat.dist:ES5bundle inUMDformat. This directory is present to keep backward compatibility.
If you are using Angular CLI, the polyfills.ts file will contain:
import 'zone.js/dist/zone';
Starting with Zone.js v0.11.1+ the import changes to:
import 'zone.js';
Prior to v0.11.1 the import would load the ES5 bundle in UMD format from dist/zone.js.
Starting with v0.11.1 the import loads the ES2015 bundle in ESM format instead.
This is a breaking change for legacy browsers such as IE11.
For backwards compatibility zone.js continues to distribute the same bundles under dist.
To restore the old behavior import from the dist directory instead like so:
import 'zone.js/dist/zone';
For details, please refer the changelog and the PR.
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
Starting with v0.11.0, zone.js uses Angular Package Format for bundle distribution.
(For backwards compatibility, all bundles can still be accessed from dist folder.)
| Bundle | Summary |
|---|---|
zone.js |
The default bundle. Contains the most used APIs such as setTimeout/Promise/EventTarget..., it also supports differential loading by importing this bundle using import zone.js. In legacy browsers it includes some additional patches such as registerElement and EventTarget like APIs. |
zone-testing.js |
The bundle for zone testing support of jasmine / mocha / jest. Also includes test utility functions async / fakeAsync / sync. |
zone-node.js |
The NodeJS support bundle. |
zone-mix.js |
A mixed bundle which supports both browser and NodeJS. Useful for mixed environment such as Electron. |
zone-externs.js |
the API definitions for closure compiler. |
Additional optional patches not included in the zone.js bundles which extend functionality.
The additional bundles can be found under zone.js/plugins folder.
To use these bundles, add the following code after importing zone.js bundle.
import 'zone.js';
// For example, import canvas patch
import 'zone.js/plugins/zone-patch-canvas';
| 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 adding zone information to stack frame, and also removing unrelated stack frames from zone.js internally |
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 |
helper 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 |
zone-patch-message-port.js |
patch for MessagePort API |
License
MIT