Zone.js internals

@JiaLiPassion

Agenda

What's Zone.js and internal implementation
When and why you need Zone.js
Some features of Zone.js in Angular

What is Zone.js

A Zone is an execution context that persists across async tasks.

Created by Brian Ford inspired by Dart.

What zone.js can do

Provide execution context
Provide async task lifecycle hook
Provide error handler for async operations

Execution Context

const testObj = {
  testFunc: function() {
    console.log('this in testFunc is:', this);
  }
};

testObj.testFunc();

const newTestFunc = testObj.testFunc;
newTestFunc();

const newObj = {};
newTestFunc.apply(newObj);

const bindObj = {};
const boundFunc = testObj.testFunc.bind(bindObj);
boundFunc();

Execution context in zone.js

zone.run(function() {
  // function is in the zone
  // just like `this`, we have a zoneThis === zone
  expect(zoneThis).toBe(zone);
  setTimeout(function() {
    // the callback of async operation
    // will also have a zoneThis === zone
    // which is the zoneContext when this async operation
    // is scheduled.
    expect(zoneThis).toBe(zone);
  });
  Promise.resolve(1).then(function() {
    // all async opreations will be in the same zone
    // when they are scheduled.
    expect(zoneThis).toBe(zone);
  });
});

How to get `zoneThis`

zone.run(function() {
  expect(Zone.current).toBe(zone);
  setTimeout(function() {
    expect(Zone.current).toBe(zone);
  });
});

share context

const zone = Zone.current.fork({
  name: 'zone',
  properties: {a: 1}
});
zone.run(function() {
  expect(Zone.current.get('a')).toBe(1);
  setTimeout(function() {
    expect(Zone.current.get('a')).toBe(1);
  });
});

LifeCycle Interceptable Hooks

onFork
onIntercept
onInvoke
onHandleError
onScheduleTask
onInvokeTask
onCancelTask
onHasTask

setTimeout

setTimeout(function() {
  console.log('callback invoked');
}, 1000);

setTimeout in Zone

var zone = Zone.current.fork({
  name: 'hook',
  onScheduleTask: ...,
  onInvokeTask: ....,
  onHasTask: ...
});
zone.run(() => {
  setTimeout(() => {
    console.log('timer callback invoked');
  }, 100);
});

fork

zone.fork(zoneSpec);

interface ZoneSpec {
  name: string;
  onScheduleTask: ...,
  onInvokeTask: ...,
  onCancelTask: ...,
  onInvoke: ...,
  ...,
}

Propagation

const stackTraceZone = Zone.current.fork({
  name: 'stackTraceZone',
  onScheduleTask: ...
  onInvokeTask: ...
});

const logZone = stackTraceZone.fork({
  name: 'logZone',
  onInvokeTask: ...
});
  
logZone.run(() => {
  setTimeout(...)
});

Propagation

rootZone

stackTraceZone

logZone

onInvokeTask

Zone propagation can compose zone behaviors

Compose Parent Behavior

const stackTraceZone = Zone.fork({
  name: 'stackTraceZone',
  onInvokeTask: (...) => {
    console.log('stackTraceZone', Zone.current.name);
    return delegate.invokeTask(...)
  }
});

const logZone = Zone.fork({
  name: 'logZone',
  parentZone: stackTraceZone,
  onInvokeTask: (...) => {
    console.log('logZone', Zone.current.name); 
    return delegate.invokeTask(...)
  }
});
  
logZone.run(() => {
  setTimeout(...)
});
  
// logZone logZone
// stackTraceZone logZone

Class Inheritance?

class Zone { constructor(public parent, public name) {}}

class StackTraceZone extends Zone {
  constructor(parent) { super(parent, 'stackTraceZone');}
  onInvokeTask() {
    ...
    this.parent.onInvokeTask();
  }
}
class LogZone extends Zone {
  constructor(parent) {super(parent, 'logZone');}
  onInvokeTask() {
    ... 
    this.parent.onInvokeTask();
  }
}

const stackTraceZone = new StackTraceZone(rootZone);
const logZone = new LogZone(stackTraceZone);
// logZone logZone
// stackTraceZone stackTraceZone

ZoneDelegate

Zone

ZoneDelegate

name: stackTraceZone

parent: rootZone

name: logZone

run()

parent: stackTraceZone

onInvoke

onInvoke(parentDelegate, ...)

Zone StackFrame

const zoneA = Zone.current.fork({name: 'zoneA'});
const zoneB = Zone.current.fork({name: 'zoneB'});
zoneA.run(() => {
  // now we are in zoneA
  zoneB.run(() => {
    // now we are in zoneB
  });
  // now we are back in zoneA
  ...
});

Zone StackFrame

// currentZoneFrame = {parent: null, zone: rootZone}
zoneA.run(() => { // currentZoneFrame = {parent: currentZoneFrame, zone: zoneA}
  // now we are in zoneA
  zoneB.run(() => { // currentZoneFrame = {parent: currentZoneFrame, zone: zoneB}
    // now we are in zoneB
  }); // currentZoneFrame = currentZoneFrame.parent
  // now we are back in zoneA 
  ...
});
  
// implementation of Zone.current
get current() {
  return currentZoneFrame.zone;
}

currentZoneFrame: ZoneFrame;

interface ZoneFrame {
  parent: ZoneFrame;
  zone: Zone;
}

Async Error Handling

Zone.current.fork(
  {
    name: 'error',
    onHandleError: (delegate, curr, target, error) => {
       logger.error(error);
       return delegate.handleError(target, error);
    }
}).runGuarded(() => {
    setTimeout(() => {
       throw new Error('timeout error');
    });
    setTimeout(() => {
       throw new Error('another timeout error');
    });
});

Zone.wrap

function testFunc() {
  console.log('this in testFunc is:', this);
}

const bindTarget = {};
const boundFunc = testFunc.bind(bindTarget);
boundFunc.apply(newObj);

// ------------------------
// 
function testZoneFunc() {
  console.log('zoneThis in testFunc is:', Zone.current);
}

const zoneA = Zone.current.fork({name: 'zoneA'});
const wrappedTestZoneFunc = zoneA.wrap(testZoneFunc);

zoneB.run(wrappedTestZoneFunc);

Task

macroTask
- setTimeout
- setInterval
- XHR
- ...
microTask
- Promise.then
eventTask
- addEventListener
- on('event', fn)

zone.scheduleMicrotask

zone.scheduleMicroTask('myOwnMicroTask', callbackFn);

// looks like
Promise.resolve().then(() => {
  callbackFn();
});

// zone has it's own microTaskQueue
p.then(() => {});
p.then(() => {});
// without zone, there will be 2 microTasks in 
// native microTask queue

// with zone, there will be only 1 microTask in
// native microTask queue
drainMicroTaskQueue() {
  zoneMicroTasks.forEach(t => {
    t.zone.runTask(t);
  });
}

zone microTask queue

zone microTaskQueue

native

microTaskQueue

zoneTask1

zoneTask2

drainMicroTaskQueue

other tasks

zone.scheduleMacroTask('name', callback,
                       data, customSchedule, customCancel);
zone.scheduleEventTask('name', callback,
                       data, customSchedule, customCancel);

other methods

Zone.__symbol__ // will return a string starts with __symbol__
Zone.__symbol__('test') === '__zone_symbol__test';

Zone.__load_patch('myOwnAsyncApi',
                  (global, Zone, api) => {});

Monkey-Patch

// Save the original reference to setTimeout
let originalSetTimeout = window.setTimeout;
// Overwrite the API with a function which wraps callback in zone.
window.setTimeout = function(callback, delay) {
  // Invoke the original API but wrap the callback in zone.
  return originalSetTimeout(
    // Wrap the callback method
    Zone.current.wrap(callback), 
    delay
  );
}

When should we use Zone

Test
- Sync(Disallow Async)
- Async(Auto done, Auto cleanup)
- FakeAsync()
Debug
- LongStackTrace
- Task Tracing
Performance measure
Framework AutoRender
User Action Tracing
Resource Releasing

Demo: LongStackTrace

  function main () {
    b1.addEventListener('click', bindSecondButton);
  }

  /*
   * What if your stack trace could tell you what
   * order the user pushed the buttons from the stack trace?
   * What if you could log this back to the server?
   * Think of how much more productive your debugging could be!
   */
  function bindSecondButton () {
    b2.addEventListener('click', throwError);
  }


  function throwError () {
    throw new Error('aw shucks');
  }

  main();

Demo: Tracking: Counting

    function btnClicked () {
        recurRandonGenerateTimeout(10);
    }

    function recurRandonGenerateTimeout (x) {
      if (x > 0) {
        setTimeout(function () {
          for (var i = x; i < 8; i++) {
            recur(x - 1, Math.random()*100);
          }
        }, t);
      }
    }

Performance Profiling

    function btnClicked () {
        asyncHeavyWork1();
        asyncHeavyWork2();
        asyncHttpRequest();
    }

Auto releasing

const fs = require('fs');

fs.open('./test.txt', 'r', (err, fd) => {
  fs.fstat(fd, (err, stat) => {
    doSomething(fd, err => {});
    doSomethingElse(fd, err => {});
    // when to release fd?
  });
});

User Action Tracking

viewBtnClicked() {
  httpRequest(viewUrl);
  httpRequest(additionalInfoUrl);
}

orderBtnClicked() {
  httpRequest(orderUrl);
  httpRequest(transactionUrl);
}

errorBtnClicked() {
  throw new Error();
}

UI Auto Rendering

  function httpBtnClicked() {
    httpRequestUrl(viewUrl);
  }

  function timeoutBtnClicked() {
    setTimeout(() => {
      data.timeout = 'timeout';
    });
  }

  function addBtnClicked() {
    if (!data.num) {
      data.num = 0;
    }
    data.num ++;
  }

Async Test

const api = require('./async-lib');

describe('testAsync', () => {
  it('test async operation', (done) => {
    let a = 0;
    api.testAsync(a, r => {
      expect(r).toBe(1);
      done();
    });
  });
});

const api = require('./async-lib');

describe('testAsync', async(() => {
  it('test async operation', () => {
    let a = 0;
    api.testAsync(a, r => {
      expect(r).toBe(1);
    });
  });
}));

fakeAsync Test

describe('testAsync', () => {
  it('test long async operation', (done) => {
    setTimeout(() => {
      // ... expect something.
      done();
    }, 10000);
  });
});

describe('testAsync', () => {
  it('test long async operation', fakeAsync(() => {
    setTimeout(() => {
      // ... expect something.
    }, 10000);
    tick(10000);
  }));
});

ProxyZoneSpec

describe('testAsync', () => {
  it('async', async(() => {
  }));
  it('fakeAsync', fakeAsync(() => {
  }));
});
global.it = function(testFn) {
  runTestInProxyZone(testFn);
}
function async() {
  const asyncTestZoneSpec = new AsyncTestZoneSpec();
  getProxyZoneSpec().setDelegate(asyncTestZoneSpec);
}

ProxyZoneSpec

{delegate: delegateSpec,

onInvokeTask

...

}

realZoneSpec

onInvokeTask

Zone.js in Angular

NgZone

Tell when to trigger Change Detection

AsyncTest

FakeAsyncTest

SyncTest

Error Handling

Debug/Tracing

TaskTrackingZone

LongStackTraceZone

ngZone

ngZone.run(() => {
  // will be in angular zone
  // will trigger change detection
});

ngZone.runOutsideAngular(() => {
  // will be outside angular zone
  // "will not trigger change detection"
});

wtfZoneSpec

TaskTrackingZoneSpec

longStackTraceZoneSpec

angular

Features of zone.js in Angular

Module

Timer

Promise

EventTarget

...

requestAnimationFrame

Disable specified Module

(window as any).__Zone_disable_requestAnimationFrame = true;

Ionic v4

(window as any).__Zone_disable_customElements = true;

Disable Specified Event

// recommended variable name
__zone_symbol__UNPATCHED_EVENTS = ['scroll', 'mousemove'];

// deprecated variable name
// __zone_symbol__BLACK_LISTED_EVENTS = ['scroll', 'mousemove'];

Native Delegate

// ngZone.runOutsideAngular(() => {});

declare let Zone: any;
(window as any)[Zone.__symbol__('setTimeout')](() => {
  // will not in zone.
}, 100);

Promise

ZoneAwarePromise

Pass Promise A+ Test
Support Promise.prototype.finally and Promise.prototype.allSettled
Support Bluebird
- All Bluebird additional APIs will in the zone
Will support Promise.any soon
native async/await not supported :(

Error Handling

import 'zone.js/dist/zone-error';

Error Handling

import 'zone.js/dist/zone-error';
class MyError extends Error {
}

try {
  throw new MyError('myError');
} catch (error: Error) {
  if (error instanceof MyError) {
    // do some special error handling
  }
}

(window as any).__Zone_Error_BlacklistedStackFrames_policy
   = 'disable';

Electron

Browser
NodeJs

Menu
Screenshot
Shell
Main<->Render communication

import 'zone.js/dist/zone-mix';

import 'zone.js/dist/zone-patch-electron';

More APIs Support

MediaQuery
Notification
RTCPeerConnction
ShadyDom
Cordova
ResizeObserver
SocketIO
UserMedia
Jsonp Helper

FakeAsync: Date.now

will support performance api later

it('should advance Date with tick in fakeAsync', 
  fakeAsync(() => {
    const start = Date.now();
    tick(100);
    const end = Date.now();
    expect(end - start).toBe(100);
}));

FakeAsync: jasmine.clock

beforeEach(() => {
      jasmine.clock().install();
});
afterEach(() => {
      jasmine.clock().uninstall();
});
it('should get date diff correctly', () => {
      // automatically run into fake async zone,
      const start = Date.now();
      jasmine.clock().tick(100);
      const end = Date.now();
      expect(end - start).toBe(100);
});

__zone_symbol__fakeAsyncAutoFakeAsyncWhenClockPatched

FakeAsync: rxjs.scheduler

import 'zone.js/dist/zone-patch-rxjs-fake-async';

it('rxjs scheduler should be advanced by tick in fakeAsync', 
  fakeAsync(() => {
        observable.delay(1000).subscribe(v => {
          result = v;
        });
        expect(result).toBeNull();
        testZoneSpec.tick(1000);
        expect(result).toBe('hello');
}));

Better timeout message

it('should timeout', async(() => {
    setTimeout(() => {}, 10000);
    fixture.whenStable(() => {});
}));

Error: Timeout - Async callback was not invoked within timeout specified by jasmine.DEFAULT_TIMEOUT_INTERVAL.
--Pendng async tasks are: [type: macroTask, source: setTimeout, args: {handleId:3,isPeriodic:false,delay:10000,args:[]}

Differential Loading

<script src="zone.js/dist/zone-evergreen.js" 
  type="module"></script>
<script src="zone.js/dist/zone.js" nomodule></script>

Event Bubble Performance

<div (click)="doSomethingElse()">
  <button (click)="doSomething()">click me</button>
</div>

platformBrowserDynamic()
  .bootstrapModule(
  AppModule, 
  {
    ngZoneEventCoalescing: true
  }
)

Solution

Event Listeners

button.addEventListener('click', click1);
button.addEventListener('click', click2);
button.addEventListener('mousedown', mousedown1);

const clickListeners = button.eventListeners('click');
// will get click1 and click2

button.removeAllListeners('click');
// will remove click1 and click2

button.removeAllListeners();
// will remove all listeners for all events

Zone.js internals

Agenda

What is Zone.js

What zone.js can do

Execution Context

Execution context in zone.js

How to get `zoneThis`

share context

LifeCycle Interceptable Hooks

setTimeout

setTimeout in Zone

fork

Propagation

Propagation

Zone propagation can compose zone behaviors

Compose Parent Behavior

Class Inheritance?

ZoneDelegate

Zone StackFrame

Zone StackFrame

Async Error Handling

Zone.wrap

Task

zone.scheduleMicrotask

zone microTask queue

other tasks

other methods

Monkey-Patch

When should we use Zone

Demo: LongStackTrace

Demo: Tracking: Counting

Performance Profiling

Auto releasing

User Action Tracking

UI Auto Rendering

Async Test

fakeAsync Test

ProxyZoneSpec

Zone.js in Angular

ngZone

Features of zone.js in Angular

Module

Disable specified Module

Ionic v4

Disable Specified Event

Native Delegate

Promise

Error Handling

Error Handling

Electron

More APIs Support

FakeAsync: Date.now

FakeAsync: jasmine.clock

FakeAsync: rxjs.scheduler

Better timeout message

Differential Loading

Event Bubble Performance

Solution

Event Listeners

Zone.js is merged into angular mono repo and fully built with bazel

Thank you!