@checle/zones

zones

by Filip Dalüge

For a primer on zones in Dart, take a look at the Dart article. Find the complete API here.

Installation

Install using NPM:

npm install --save web-zones

Import zones:

import * as zones from 'web-zones'

Object.assign(global, zones) // Optionally, shim the host API (overrides setTimeout, Promise etc.)

Usage

Wait for operations spawned by a function

await zone.exec(initAppFunction)

Listen to state

zone.addEventListener('error', listener)

Cancel pending operations

zone.cancel()

Bind function

func = zone.bind(func)

Number of scheduled tasks

zone.tasks.size

Examples

• Instantiate a zone and listen for events
• Execute tasks parallely
• Asynchronous operations
• Extend zones
• Override run()
• Run untrusted code asynchronously

Instantiate a zone and listen for events

Create a zone object and listen for status events.

var zone = new Zone('custom-zone')

zone.addEventListener('finish', () => console.log('Zone has terminated'))
zone.addEventListener('error', error => console.log('Error occurred'))

function application () {
  setTimeout(() => null, 1000)
}

zone.run(application)

Asynchronous operations

Run an application that reads a file making use of asynchronous JS APIs. The result is then awaited, and its content printed.

import * as fs from 'fs'

// Application with unknown asynchronous operations
function application() {
  // Waits for a second
  setTimeout(readFile, 1000)

  function readFile () {
    // Read asynchronously
    fs.readFile('data.txt', data => {
      global.fileContent = data
    })
  }
}

try {
  // Call and wait for spawned tasks to terminate
  await global.zone.exec(application)

  console.log('This file content has been read: ' + global.fileContent)
} catch (error) {
  console.log('Either setTimeout or fs.readFile threw an uncatched error')
}

Execute tasks parallely

Run three processes using Promise.all and wait for them to finish. Cancel any other zones if one zone throws an error.

try {
  await Promise.all([
    zone.exec(app1),
    zone.exec(app2),
    zone.exec(app3),
  ])

  console.log('All tasks have concluded successfully')
} catch (error) {
  console.log('One zone errored:', error.zone.name)

  // Cancel all remaining zones
  zone.cancel()
}

Extend zones

Add custom properties to Zone.current by inheritance.

class CustomEnvironment extends Zone {
  constructor () {
    super('custom-environment')

    this.created = Date.now()
  }
}

function routine () {
  if (Zone.current instanceof CustomEnvironment) {
    console.log('My environment was created at ' + this.created)
  } else {
    console.log("I think I've been running forever")
  }
}

global.zone.run(routine) // "I think I've been running forever"

new CustomEnvironment().run(routine) // Prints the creation date

Override run()

You can hook into zone operations overriding run().

class MozillaZone extends Zone {
  run (func) {
    let previousDomain = global.domain

    try {
      global.domain = 'mozilla.org' // Switch global domain during run()

      return super.run(func)
    } finally {
      global.domain = previousDomain // Restore global domain
    }
  }
}

global.domain = 'example.com'

new MozillaZone().run(() => console.log(global.domain)) // "mozilla.org"

global.zone.run(() => console.log(global.domain)) // "example.com"

Run untrusted code asynchronously

Run code in a sandbox using NodeJS' vm module and print the result.

const vm = require('vm')

// Create sandbox
let sandbox = {
  setTimeout,
  setInterval,
  setImmediate,
  print: console.log
}

let applicationCode = `
  if (typeof console !== 'undefined') {
    console.log("I'm not that secure, it seems.")
  } else {
    print('Oh yes, I am.')
  }
`

try {
  // Use exec with vm to run a program in an isolated environment
  let result = await zone.exec(() => vm.runInNewContext(applicationCode, sandbox))

  console.log('Terminated successfully with result', result)
} catch (error) {
  console.log('An error occurred')
)

API

zone: Zone // Gets the current zone

interface Task extends Event {
  cancel?: Function
}

interface Zone extends EventTarget, Node {
  name: string
  root: Zone
  onerror?: Function
  onfinish?: Function

  readonly tasks: Map<any, Task>
  readonly children: Zone[]
  readonly root: Zone

  constructor (nameOrSpec?: any)

  addTask (task: Task): number
  setTask (id: any, task: Task): this
  getTask (id: any): Task
  hasTask (id: any): boolean
  removeTask (id: any): boolean
  cancelTask (id: any): Promise<void>

  run (entry: Function, thisArg?: any, ...args: any[]): any
  bind (fn: Function): Function
  // Cancels all tasks and child zones by default
  cancel (): Promise<void> 
  // Spawns a new child zone, runs `entry` in it and resolves when all new tasks have been worked off
  exec (entry: Function, thisArg?: any, ...args: any[]): Promise<any>

  addEventListener (type: 'finish' | 'error', listener: Function, options: any): void
  appendChild (node: Zone): this
}

function setTimeout (handler, timeout, ...args)
function setInterval (handler, timeout, ...args)
function clearTimeout (id)
function clearInterval (id)
function Promise (executor)

License

MIT © 2016 Filip Dalüge (license)