CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-zone-js

Execution context library that persists across asynchronous operations for JavaScript applications

Overview
Eval results
Files

configuration-api.mddocs/

Configuration API

Global configuration system for selectively disabling patches and customizing zone behavior across different environments and use cases.

Capabilities

Global Configuration Interface

Zone.js provides extensive configuration options to disable specific patches and customize behavior.

/**
 * Global configuration interface for Zone.js behavior
 */
interface ZoneGlobalConfigurations {
  // Core API patches
  /** Disable timer patches (setTimeout, setInterval) */
  __Zone_disable_timers?: boolean;
  
  /** Disable Promise patches */
  __Zone_disable_Promise?: boolean;
  
  /** Disable EventTarget patches */
  __Zone_disable_EventTarget?: boolean;
  
  /** Disable requestAnimationFrame patches */
  __Zone_disable_requestAnimationFrame?: boolean;
  
  /** Disable MutationObserver patches */
  __Zone_disable_MutationObserver?: boolean;
  
  /** Disable IntersectionObserver patches */
  __Zone_disable_IntersectionObserver?: boolean;
  
  /** Disable FileReader patches */
  __Zone_disable_FileReader?: boolean;
  
  /** Disable queueMicrotask patches */
  __Zone_disable_queueMicrotask?: boolean;
  
  /** Disable XMLHttpRequest patches */
  __Zone_disable_XHR?: boolean;
  
  /** Disable Fetch API patches */
  __Zone_disable_fetch?: boolean;
  
  /** Disable WebSocket patches */
  __Zone_disable_WebSocket?: boolean;
  
  /** Disable MessagePort patches */
  __Zone_disable_MessagePort?: boolean;
  
  // Browser-specific patches
  /** Disable canvas patches */
  __Zone_disable_canvas?: boolean;
  
  /** Disable Notification API patches */
  __Zone_disable_notification?: boolean;
  
  /** Disable ResizeObserver patches */
  __Zone_disable_ResizeObserver?: boolean;
  
  /** Disable WebRTC patches */
  __Zone_disable_RTCPeerConnection?: boolean;
  
  /** Disable getUserMedia patches */
  __Zone_disable_getUserMedia?: boolean;
  
  /** Disable custom elements patches */
  __Zone_disable_customElements?: boolean;
  
  // Node.js specific patches
  /** Disable Node.js fs patches */
  __Zone_disable_fs?: boolean;
  
  /** Disable EventEmitter patches */
  __Zone_disable_EventEmitter?: boolean;
  
  /** Disable crypto patches */
  __Zone_disable_crypto?: boolean;
  
  /** Disable process.nextTick patches */
  __Zone_disable_nextTick?: boolean;
  
  // Event configuration
  /** Events to skip patching entirely */
  __zone_symbol__UNPATCHED_EVENTS?: string[];
  
  /** Events to mark as passive */
  __zone_symbol__PASSIVE_EVENTS?: string[];
  
  /** Events to capture in the capturing phase */
  __zone_symbol__CAPTURING_EVENTS?: string[];
  
  // Advanced configuration
  /** Properties to ignore when patching objects */
  __Zone_ignore_on_properties?: Array<{
    target: any;
    ignoreProperties: string[];
  }>;
  
  /** Disable wrapping of uncaught promise rejections */
  __zone_symbol__DISABLE_WRAPPING_UNCAUGHT_PROMISE_REJECTION?: boolean;
  
  /** Enable or disable zone symbol event names */
  __zone_symbol__ENABLE_ZONE_SYMBOL_EVENT_NAMES?: boolean;
  
  /** Block all events rather than patching */
  __zone_symbol__BLOCK_ALL_EVENTS?: boolean;
}

Usage Examples:

// Configure before importing zone.js
(window as any).__Zone_disable_timers = true;
(window as any).__Zone_disable_Promise = true;
(window as any).__zone_symbol__UNPATCHED_EVENTS = ['click', 'mouseover'];

import 'zone.js'; // Zone.js will respect the configuration

// Alternatively, configure via global object
declare global {
  interface Window {
    __Zone_disable_timers: boolean;
    __Zone_disable_EventTarget: boolean;
    __zone_symbol__UNPATCHED_EVENTS: string[];
  }
}

window.__Zone_disable_timers = true;
window.__Zone_disable_EventTarget = true;
window.__zone_symbol__UNPATCHED_EVENTS = ['scroll', 'resize'];

Test Configuration Interface

Specific configuration options for testing environments.

/**
 * Test-specific configuration interface
 */
interface ZoneTestConfigurations {
  /** Disable Jasmine integration */
  __Zone_disable_jasmine?: boolean;
  
  /** Disable Mocha integration */
  __Zone_disable_mocha?: boolean;
  
  /** Disable Jest integration */
  __Zone_disable_jest?: boolean;
  
  /** Disable fakeAsync clock patching */
  __zone_symbol__fakeAsyncDisablePatchingClock?: boolean;
  
  /** Support waiting for unresolved chained promises */
  __zone_symbol__supportWaitUnResolvedChainedPromise?: boolean;
  
  /** Auto configure fakeAsync test environment */
  __zone_symbol__fakeAsyncAutoFakeAsyncWhenClockPatched?: boolean;
}

Usage Examples:

// Test configuration
(window as any).__Zone_disable_jasmine = true;
(window as any).__zone_symbol__fakeAsyncDisablePatchingClock = true;

import 'zone.js/testing';

// Custom test setup
describe('Custom Tests', () => {
  beforeEach(() => {
    // Configure test-specific behavior
    (window as any).__zone_symbol__supportWaitUnResolvedChainedPromise = true;
  });
});

Event Configuration

Detailed configuration for event handling behavior.

/**
 * Configure events to skip patching
 */
__zone_symbol__UNPATCHED_EVENTS?: string[];

/**
 * Configure events as passive
 */
__zone_symbol__PASSIVE_EVENTS?: string[];

/**
 * Configure events for capturing phase
 */
__zone_symbol__CAPTURING_EVENTS?: string[];

/**
 * Block all events rather than patching
 */
__zone_symbol__BLOCK_ALL_EVENTS?: boolean;

Usage Examples:

// Configure event behavior before Zone.js loads
(window as any).__zone_symbol__UNPATCHED_EVENTS = [
  'scroll',      // Don't patch scroll events
  'mousemove',   // Don't patch mousemove events
  'resize'       // Don't patch resize events
];

(window as any).__zone_symbol__PASSIVE_EVENTS = [
  'touchstart',  // Mark touchstart as passive
  'touchmove',   // Mark touchmove as passive
  'wheel'        // Mark wheel as passive
];

(window as any).__zone_symbol__CAPTURING_EVENTS = [
  'focus',       // Capture focus events
  'blur'         // Capture blur events
];

import 'zone.js';

// Events configured as unpatched won't trigger zone tasks
document.addEventListener('scroll', () => {
  // This runs outside of zone context
  console.log('Unpatched scroll event');
});

// Other events still work with zones
document.addEventListener('click', () => {
  // This runs in zone context
  console.log('Patched click event in:', Zone.current.name);
});

Property Patching Configuration

Configure which object properties should be ignored during patching.

/**
 * Ignore specific properties when patching objects
 */
__Zone_ignore_on_properties?: Array<{
  target: any;
  ignoreProperties: string[];
}>;

Usage Examples:

// Configure property patching before Zone.js loads
(window as any).__Zone_ignore_on_properties = [
  {
    target: HTMLElement.prototype,
    ignoreProperties: ['onscroll', 'onresize']
  },
  {
    target: XMLHttpRequest.prototype,
    ignoreProperties: ['onprogress']
  },
  {
    target: window,
    ignoreProperties: ['onerror', 'onunhandledrejection']
  }
];

import 'zone.js';

// Ignored properties won't be patched
const element = document.getElementById('myElement');
element.onscroll = () => {
  // This runs outside zone context due to configuration
  console.log('Ignored onscroll');
};

element.onclick = () => {
  // This runs in zone context (not ignored)
  console.log('Click in zone:', Zone.current.name);
};

Environment-Specific Configuration

Configure Zone.js behavior for different environments.

// Browser-only configuration
interface BrowserConfigurations {
  __Zone_disable_customElements?: boolean;
  __Zone_disable_canvas?: boolean;
  __Zone_disable_WebSocket?: boolean;
  __Zone_disable_notification?: boolean;
}

// Node.js-only configuration
interface NodeConfigurations {
  __Zone_disable_fs?: boolean;
  __Zone_disable_EventEmitter?: boolean;
  __Zone_disable_crypto?: boolean;
  __Zone_disable_nextTick?: boolean;
}

Usage Examples:

// Browser environment configuration
if (typeof window !== 'undefined') {
  (window as any).__Zone_disable_canvas = true;
  (window as any).__Zone_disable_WebSocket = true;
  (window as any).__zone_symbol__UNPATCHED_EVENTS = ['scroll', 'resize'];
}

// Node.js environment configuration
if (typeof global !== 'undefined') {
  (global as any).__Zone_disable_fs = true;
  (global as any).__Zone_disable_EventEmitter = false;
}

// Mixed environment configuration
import 'zone.js/mix';

Performance Optimization Configuration

Configuration options for optimizing Zone.js performance.

/**
 * Performance-related configuration options
 */
interface PerformanceConfigurations {
  /** Disable symbol event names for performance */
  __zone_symbol__ENABLE_ZONE_SYMBOL_EVENT_NAMES?: boolean;
  
  /** Block all events to avoid patching overhead */
  __zone_symbol__BLOCK_ALL_EVENTS?: boolean;
  
  /** Disable wrapping promise rejections */
  __zone_symbol__DISABLE_WRAPPING_UNCAUGHT_PROMISE_REJECTION?: boolean;
}

Usage Examples:

// High-performance configuration
(window as any).__zone_symbol__ENABLE_ZONE_SYMBOL_EVENT_NAMES = false;
(window as any).__zone_symbol__DISABLE_WRAPPING_UNCAUGHT_PROMISE_REJECTION = true;

// Disable expensive patches
(window as any).__Zone_disable_MutationObserver = true;
(window as any).__Zone_disable_IntersectionObserver = true;
(window as any).__Zone_disable_ResizeObserver = true;

// Use minimal event patching
(window as any).__zone_symbol__UNPATCHED_EVENTS = [
  'scroll', 'resize', 'mousemove', 'touchmove'
];

import 'zone.js';

Runtime Configuration

Some Zone.js behavior can be configured at runtime after loading.

/**
 * Runtime configuration methods
 */
interface RuntimeConfiguration {
  /** Check current configuration state */
  isPatched(api: string): boolean;
  
  /** Get configuration value */
  getConfig(key: string): any;
  
  /** Load additional patches at runtime */
  loadPatch(name: string, fn: PatchFn): void;
}

Usage Examples:

import 'zone.js';

// Check if specific APIs are patched
const isTimerPatched = !!(window as any).__Zone_symbol_setTimeout;
const isPromisePatched = !!(window as any).__Zone_symbol_Promise;

console.log('Timers patched:', isTimerPatched);
console.log('Promises patched:', isPromisePatched);

// Load additional patches at runtime
Zone.__load_patch('custom-runtime-patch', (global, Zone, api) => {
  console.log('Loading custom patch at runtime');
  // Custom patching logic
});

// Conditional patch loading
if (typeof window !== 'undefined' && window.customAPI) {
  Zone.__load_patch('custom-api', (global, Zone, api) => {
    // Patch custom API if available
  });
}

Configuration Best Practices

Recommended patterns for configuring Zone.js in different scenarios.

// Minimal configuration for performance-critical applications
const minimalConfig = {
  __Zone_disable_timers: false,        // Keep timers (usually needed)
  __Zone_disable_Promise: false,       // Keep promises (usually needed)
  __Zone_disable_EventTarget: false,   // Keep event target (usually needed)
  __Zone_disable_XHR: false,           // Keep XHR (usually needed)
  __Zone_disable_fetch: false,         // Keep fetch (usually needed)
  
  // Disable expensive patches
  __Zone_disable_MutationObserver: true,
  __Zone_disable_IntersectionObserver: true,
  __Zone_disable_ResizeObserver: true,
  __Zone_disable_canvas: true,
  
  // Optimize event handling
  __zone_symbol__UNPATCHED_EVENTS: [
    'scroll', 'resize', 'mousemove', 'touchmove'
  ],
  __zone_symbol__PASSIVE_EVENTS: [
    'touchstart', 'touchmove', 'wheel'
  ]
};

// Testing configuration
const testConfig = {
  __Zone_disable_jasmine: false,
  __zone_symbol__fakeAsyncDisablePatchingClock: false,
  __zone_symbol__supportWaitUnResolvedChainedPromise: true
};

// Node.js configuration
const nodeConfig = {
  __Zone_disable_fs: true,           // Often not needed in web apps
  __Zone_disable_EventEmitter: false, // Usually needed
  __Zone_disable_nextTick: false    // Usually needed
};

Install with Tessl CLI

npx tessl i tessl/npm-zone-js

docs

configuration-api.md

core-zone-api.md

index.md

patching-system.md

task-system.md

testing-utilities.md

zone-specifications.md

tile.json