0
# Zone Specifications
1

2
Zone configuration system for customizing zone behavior through lifecycle hooks, error handling, and task interception.
3

4
## Capabilities
5

6
### ZoneSpec Interface
7

8
Configuration object that defines zone behavior through lifecycle hooks and properties.
9

10
```typescript { .api }
11
/**
12
 * Configuration object for customizing zone behavior
13
 */
14
interface ZoneSpec {
15
  /** Required: zone name for debugging and identification */
16
  name: string;
17
  
18
  /** Optional: key-value properties attached to the zone */
19
  properties?: {[key: string]: any};
20
  
21
  /** Hook called when this zone is forked to create child zones */
22
  onFork?: (
23
    parentZoneDelegate: ZoneDelegate,
24
    currentZone: Zone,
25
    targetZone: Zone,
26
    zoneSpec: ZoneSpec
27
  ) => Zone;
28
  
29
  /** Hook called when callbacks are wrapped for zone context */
30
  onIntercept?: (
31
    parentZoneDelegate: ZoneDelegate,
32
    currentZone: Zone,
33
    targetZone: Zone,
34
    delegate: Function,
35
    source: string
36
  ) => Function;
37
  
38
  /** Hook called when functions are executed in the zone */
39
  onInvoke?: (
40
    parentZoneDelegate: ZoneDelegate,
41
    currentZone: Zone,
42
    targetZone: Zone,
43
    delegate: Function,
44
    applyThis: any,
45
    applyArgs?: any[],
46
    source?: string
47
  ) => any;
48
  
49
  /** Hook called when errors occur in the zone */
50
  onHandleError?: (
51
    parentZoneDelegate: ZoneDelegate,
52
    currentZone: Zone,
53
    targetZone: Zone,
54
    error: any
55
  ) => boolean;
56
  
57
  /** Hook called when tasks are scheduled in the zone */
58
  onScheduleTask?: (
59
    parentZoneDelegate: ZoneDelegate,
60
    currentZone: Zone,
61
    targetZone: Zone,
62
    task: Task
63
  ) => Task;
64
  
65
  /** Hook called when tasks are executed in the zone */
66
  onInvokeTask?: (
67
    parentZoneDelegate: ZoneDelegate,
68
    currentZone: Zone,
69
    targetZone: Zone,
70
    task: Task,
71
    applyThis: any,
72
    applyArgs?: any[]
73
  ) => any;
74
  
75
  /** Hook called when tasks are cancelled in the zone */
76
  onCancelTask?: (
77
    parentZoneDelegate: ZoneDelegate,
78
    currentZone: Zone,
79
    targetZone: Zone,
80
    task: Task
81
  ) => any;
82
  
83
  /** Hook called when zone task state changes */
84
  onHasTask?: (
85
    parentZoneDelegate: ZoneDelegate,
86
    currentZone: Zone,
87
    targetZone: Zone,
88
    hasTaskState: HasTaskState
89
  ) => void;
90
}
91
```
92

93
**Usage Examples:**
94

95
```typescript
96
import 'zone.js';
97

98
// Basic zone with properties
99
const userZone = Zone.current.fork({
100
  name: 'user-zone',
101
  properties: {
102
    userId: 123,
103
    theme: 'dark'
104
  }
105
});
106

107
// Zone with error handling
108
const errorHandlingZone = Zone.current.fork({
109
  name: 'error-handler',
110
  onHandleError: (delegate, current, target, error) => {
111
    console.error('Zone error:', error);
112
    // Return true to prevent error propagation
113
    return true;
114
  }
115
});
116

117
// Zone with task tracking
118
const taskTrackingZone = Zone.current.fork({
119
  name: 'task-tracker',
120
  onScheduleTask: (delegate, current, target, task) => {
121
    console.log('Task scheduled:', task.type, task.source);
122
    return delegate.scheduleTask(target, task);
123
  },
124
  onHasTask: (delegate, current, target, hasTaskState) => {
125
    console.log('Task state changed:', hasTaskState);
126
  }
127
});
128
```
129

130
### ZoneDelegate Interface
131

132
Delegate object that provides access to parent zone operations within lifecycle hooks.
133

134
```typescript { .api }
135
/**
136
 * Delegate interface for accessing parent zone operations
137
 */
138
interface ZoneDelegate {
139
  /** Zone associated with this delegate */
140
  readonly zone: Zone;
141
  
142
  /** Delegate zone forking to parent */
143
  fork(targetZone: Zone, zoneSpec: ZoneSpec): Zone;
144
  
145
  /** Delegate callback interception to parent */
146
  intercept(targetZone: Zone, callback: Function, source: string): Function;
147
  
148
  /** Delegate function invocation to parent */
149
  invoke(
150
    targetZone: Zone,
151
    callback: Function,
152
    applyThis?: any,
153
    applyArgs?: any[],
154
    source?: string
155
  ): any;
156
  
157
  /** Delegate error handling to parent */
158
  handleError(targetZone: Zone, error: any): boolean;
159
  
160
  /** Delegate task scheduling to parent */
161
  scheduleTask(targetZone: Zone, task: Task): Task;
162
  
163
  /** Delegate task invocation to parent */
164
  invokeTask(targetZone: Zone, task: Task, applyThis?: any, applyArgs?: any[]): any;
165
  
166
  /** Delegate task cancellation to parent */
167
  cancelTask(targetZone: Zone, task: Task): any;
168
  
169
  /** Delegate task state notification to parent */
170
  hasTask(targetZone: Zone, isEmpty: HasTaskState): void;
171
}
172
```
173

174
### Lifecycle Hook Examples
175

176
Zone specifications enable powerful customization through lifecycle hooks.
177

178
```typescript { .api }
179
/**
180
 * Hook called when this zone is forked to create child zones
181
 * @param parentZoneDelegate - Delegate for parent zone operations
182
 * @param currentZone - Zone where the fork hook is declared
183
 * @param targetZone - Zone that will be the parent of the new zone
184
 * @param zoneSpec - Specification for the new child zone
185
 * @returns The newly created zone
186
 */
187
onFork?: (
188
  parentZoneDelegate: ZoneDelegate,
189
  currentZone: Zone,
190
  targetZone: Zone,
191
  zoneSpec: ZoneSpec
192
) => Zone;
193

194
/**
195
 * Hook called when callbacks are wrapped for zone context
196
 * @param parentZoneDelegate - Delegate for parent zone operations  
197
 * @param currentZone - Zone where the intercept hook is declared
198
 * @param targetZone - Zone where the callback will execute
199
 * @param delegate - Original callback function
200
 * @param source - Debug identifier for the operation
201
 * @returns Modified callback function
202
 */
203
onIntercept?: (
204
  parentZoneDelegate: ZoneDelegate,
205
  currentZone: Zone,
206
  targetZone: Zone,
207
  delegate: Function,
208
  source: string
209
) => Function;
210

211
/**
212
 * Hook called when functions are executed in the zone
213
 * @param parentZoneDelegate - Delegate for parent zone operations
214
 * @param currentZone - Zone where the invoke hook is declared  
215
 * @param targetZone - Zone where the function will execute
216
 * @param delegate - Function to execute
217
 * @param applyThis - 'this' context for the function
218
 * @param applyArgs - Arguments to pass to the function
219
 * @param source - Debug identifier for the operation
220
 * @returns Return value from the function
221
 */
222
onInvoke?: (
223
  parentZoneDelegate: ZoneDelegate,
224
  currentZone: Zone,
225
  targetZone: Zone,
226
  delegate: Function,
227
  applyThis: any,
228
  applyArgs?: any[],
229
  source?: string
230
) => any;
231
```
232

233
**Usage Examples:**
234

235
```typescript
236
// Profiling zone that measures execution time
237
const profilingZone = Zone.current.fork({
238
  name: 'profiler',
239
  onInvoke: (delegate, current, target, fn, thisArg, args, source) => {
240
    const start = performance.now();
241
    const result = delegate.invoke(target, fn, thisArg, args, source);
242
    const duration = performance.now() - start;
243
    console.log(`${source || 'unknown'} took ${duration}ms`);
244
    return result;
245
  }
246
});
247

248
// Logging zone that tracks all operations
249
const loggingZone = Zone.current.fork({
250
  name: 'logger',
251
  onIntercept: (delegate, current, target, callback, source) => {
252
    console.log('Intercepting:', source);
253
    return delegate.intercept(target, callback, source);
254
  },
255
  onScheduleTask: (delegate, current, target, task) => {
256
    console.log('Scheduling task:', task.type, task.source);
257
    return delegate.scheduleTask(target, task);
258
  }
259
});
260
```
261

262
### Built-in Zone Specifications
263

264
Zone.js provides several built-in zone specifications for common use cases.
265

266
```typescript { .api }
267
/**
268
 * Fake async test zone for controlling time in tests
269
 */
270
class FakeAsyncTestZoneSpec implements ZoneSpec {
271
  name: 'fakeAsync';
272
  tick(millis?: number, doTick?: (elapsed: number) => void): void;
273
  flush(maxTurns?: number): number;
274
  flushMicrotasks(): void;
275
}
276

277
/**
278
 * Async test zone that waits for all async operations to complete
279
 */
280
class AsyncTestZoneSpec implements ZoneSpec {
281
  name: 'async-test';
282
  whenStable(): Promise<any>;
283
}
284

285
/**
286
 * Proxy zone for test isolation
287
 */
288
class ProxyZoneSpec implements ZoneSpec {
289
  name: 'proxy';
290
  setDelegate(delegateSpec: ZoneSpec): void;
291
  getDelegate(): ZoneSpec;
292
  resetDelegate(): void;
293
}
294

295
/**
296
 * Task tracking zone for monitoring task execution
297
 */
298
class TaskTrackingZoneSpec implements ZoneSpec {
299
  name: 'task-tracking';
300
  readonly microTasks: Task[];
301
  readonly macroTasks: Task[];  
302
  readonly eventTasks: Task[];
303
  clear(): void;
304
}
305
```
306

307
### Error Handling Patterns
308

309
Zone specifications enable sophisticated error handling strategies.
310

311
```typescript { .api }
312
/**
313
 * Hook called when errors occur in the zone
314
 * @param parentZoneDelegate - Delegate for parent zone operations
315
 * @param currentZone - Zone where the error hook is declared
316
 * @param targetZone - Zone where the error occurred
317
 * @param error - The error that occurred
318
 * @returns true to handle the error, false to propagate to parent
319
 */
320
onHandleError?: (
321
  parentZoneDelegate: ZoneDelegate,
322
  currentZone: Zone,
323
  targetZone: Zone,  
324
  error: any
325
) => boolean;
326
```
327

328
**Usage Examples:**
329

330
```typescript
331
// Error reporting zone
332
const errorReportingZone = Zone.current.fork({
333
  name: 'error-reporter',
334
  onHandleError: (delegate, current, target, error) => {
335
    // Send error to monitoring service
336
    console.error('Zone error in', target.name, ':', error);
337
    
338
    // Could send to external service
339
    // errorService.report(error, { zone: target.name });
340
    
341
    // Return false to allow error to propagate
342
    return false;
343
  }
344
});
345

346
// Error isolation zone
347
const isolatedZone = Zone.current.fork({
348
  name: 'isolated',
349
  onHandleError: (delegate, current, target, error) => {
350
    console.log('Isolated error:', error.message);
351
    // Return true to prevent error propagation
352
    return true;
353
  }
354
});
355

356
isolatedZone.run(() => {
357
  setTimeout(() => {
358
    throw new Error('This error is isolated');
359
  }, 100);
360
  // Error won't propagate beyond this zone
361
});
362
```