Core Zone API

/**
 * Global Zone constructor interface accessible via global Zone constant
 */
interface ZoneType {
  /** Current active zone - changes when zones are forked and run */
  readonly current: Zone;
  
  /** Current executing task, null if no task is running */
  readonly currentTask: Task | null;
  
  /** Root zone - the top-level zone from which all others inherit */
  readonly root: Zone;
  
  /** Verify that Zone has been correctly patched */
  assertZonePatched(): void;
  
  /** Load a patch for specified native module */
  __load_patch(name: string, fn: PatchFn, ignoreDuplicate?: boolean): void;
  
  /** Generate zone symbol with prefix */
  __symbol__(name: string): string;
}

/**
 * Zone interface for execution context management
 */
interface Zone {
  /** Parent zone reference, null for root zone */
  readonly parent: Zone | null;
  
  /** Zone name for debugging and identification */
  readonly name: string;
  
  /** Get property value from this zone or parent zones */
  get(key: string): any;
  
  /** Find zone in the parent chain that has the specified property */
  getZoneWith(key: string): Zone | null;
  
  /** Create a child zone with the given specification */
  fork(zoneSpec: ZoneSpec): Zone;
  
  /** Wrap a callback to run in this zone's context */
  wrap<F extends Function>(callback: F, source: string): F;
  
  /** Execute function in this zone's context */
  run<T>(callback: Function, applyThis?: any, applyArgs?: any[], source?: string): T;
  
  /** Execute function in this zone with error handling */
  runGuarded<T>(callback: Function, applyThis?: any, applyArgs?: any[], source?: string): T;
  
  /** Execute the Task by restoring the zone context */
  runTask<T>(task: Task, applyThis?: any, applyArgs?: any): T;
  
  /** Schedule a MicroTask in this zone */
  scheduleMicroTask(source: string, callback: Function, data?: TaskData, customSchedule?: (task: Task) => void): MicroTask;
  
  /** Schedule a MacroTask in this zone */
  scheduleMacroTask(source: string, callback: Function, data?: TaskData, customSchedule?: (task: Task) => void, customCancel?: (task: Task) => void): MacroTask;
  
  /** Schedule an EventTask in this zone */
  scheduleEventTask(source: string, callback: Function, data?: TaskData, customSchedule?: (task: Task) => void, customCancel?: (task: Task) => void): EventTask;
  
  /** Schedule an existing Task */
  scheduleTask<T extends Task>(task: T): T;
  
  /** Cancel a scheduled Task */
  cancelTask(task: Task): any;
}

import 'zone.js';

// Access current zone
console.log('Current zone:', Zone.current.name); // '<root>'

// Create child zone with properties
const userZone = Zone.current.fork({
  name: 'user-context',
  properties: { 
    userId: 123,
    requestId: 'req-456' 
  }
});

// Run code in zone context
userZone.run(() => {
  console.log('Zone name:', Zone.current.name); // 'user-context'
  console.log('User ID:', Zone.current.get('userId')); // 123
  
  // Nested zone
  const requestZone = Zone.current.fork({
    name: 'request-handler',
    properties: { step: 'processing' }
  });
  
  requestZone.run(() => {
    // Can access parent zone properties
    console.log('User ID:', Zone.current.get('userId')); // 123
    console.log('Step:', Zone.current.get('step')); // 'processing'
  });
});

/**
 * Get property value from this zone or parent zones
 * @param key - Property key to retrieve
 * @returns Property value or undefined if not found
 */
get(key: string): any;

/**
 * Find zone in the parent chain that has the specified property
 * @param key - Property key to search for
 * @returns Zone that contains the property or null if not found
 */
getZoneWith(key: string): Zone | null;

const parentZone = Zone.current.fork({
  name: 'parent',
  properties: { theme: 'dark', version: '1.0' }
});

const childZone = parentZone.fork({
  name: 'child', 
  properties: { component: 'button' }
});

childZone.run(() => {
  // Child zone can access parent properties
  console.log(Zone.current.get('theme')); // 'dark' (from parent)
  console.log(Zone.current.get('component')); // 'button' (from child)
  
  // Find which zone has a property
  const themeZone = Zone.current.getZoneWith('theme');
  console.log(themeZone?.name); // 'parent'
});

/**
 * Execute function in this zone's context
 * @param callback - Function to execute
 * @param applyThis - 'this' context for the function
 * @param applyArgs - Arguments to pass to the function
 * @param source - Debug identifier for the operation
 * @returns Return value from the callback function
 */
run<T>(callback: Function, applyThis?: any, applyArgs?: any[], source?: string): T;

/**
 * Execute function in this zone with automatic error handling
 * @param callback - Function to execute  
 * @param applyThis - 'this' context for the function
 * @param applyArgs - Arguments to pass to the function
 * @param source - Debug identifier for the operation
 * @returns Return value from the callback function
 */
runGuarded<T>(callback: Function, applyThis?: any, applyArgs?: any[], source?: string): T;

/**
 * Wrap a callback to run in this zone's context when invoked
 * @param callback - Function to wrap
 * @param source - Debug identifier for the operation
 * @returns Wrapped function that will execute in this zone
 */
wrap<F extends Function>(callback: F, source: string): F;

const myZone = Zone.current.fork({ name: 'myZone' });

// Direct execution
const result = myZone.run(() => {
  console.log('Running in:', Zone.current.name); // 'myZone'
  return 42;
}); // result = 42

// Wrapped callback execution  
const wrappedCallback = myZone.wrap(() => {
  console.log('Wrapped callback in:', Zone.current.name);
}, 'wrapped-callback');

// Later invocation maintains zone context
setTimeout(wrappedCallback, 100); // Will run in 'myZone'

// Error handling with runGuarded
myZone.runGuarded(() => {
  throw new Error('Test error');
  // Error will be handled by zone's error handling mechanism
});

/**
 * Generate zone symbol with __zone_symbol__ prefix
 * @param name - Base name for the symbol
 * @returns Prefixed symbol string
 */
__symbol__(name: string): string;

// Generate zone symbols
const eventSymbol = Zone.__symbol__('addEventListener');
console.log(eventSymbol); // '__zone_symbol__addEventListener'

// Used internally for patching
const originalMethod = window[Zone.__symbol__('originalMethod')];