zone.d.ts 55 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158115911601161116211631164116511661167116811691170117111721173117411751176117711781179118011811182118311841185118611871188118911901191119211931194119511961197119811991200120112021203120412051206120712081209121012111212121312141215121612171218121912201221122212231224122512261227122812291230123112321233123412351236123712381239124012411242124312441245124612471248124912501251125212531254125512561257125812591260126112621263126412651266126712681269127012711272127312741275127612771278127912801281128212831284128512861287128812891290129112921293129412951296129712981299130013011302130313041305130613071308130913101311131213131314131513161317131813191320132113221323132413251326132713281329133013311332133313341335133613371338133913401341134213431344134513461347134813491350135113521353135413551356135713581359136013611362136313641365136613671368136913701371137213731374137513761377137813791380138113821383138413851386138713881389139013911392139313941395139613971398139914001401140214031404140514061407140814091410141114121413141414151416141714181419142014211422142314241425142614271428142914301431143214331434
  1. /**
  2. * @license
  3. * Copyright Google LLC All Rights Reserved.
  4. *
  5. * Use of this source code is governed by an MIT-style license that can be
  6. * found in the LICENSE file at https://angular.io/license
  7. */
  8. /**
  9. * Suppress closure compiler errors about unknown 'global' variable
  10. * @fileoverview
  11. * @suppress {undefinedVars}
  12. */
  13. /**
  14. * Zone is a mechanism for intercepting and keeping track of asynchronous work.
  15. *
  16. * A Zone is a global object which is configured with rules about how to intercept and keep track
  17. * of the asynchronous callbacks. Zone has these responsibilities:
  18. *
  19. * 1. Intercept asynchronous task scheduling
  20. * 2. Wrap callbacks for error-handling and zone tracking across async operations.
  21. * 3. Provide a way to attach data to zones
  22. * 4. Provide a context specific last frame error handling
  23. * 5. (Intercept blocking methods)
  24. *
  25. * A zone by itself does not do anything, instead it relies on some other code to route existing
  26. * platform API through it. (The zone library ships with code which monkey patches all of the
  27. * browsers's asynchronous API and redirects them through the zone for interception.)
  28. *
  29. * In its simplest form a zone allows one to intercept the scheduling and calling of asynchronous
  30. * operations, and execute additional code before as well as after the asynchronous task. The rules
  31. * of interception are configured using [ZoneConfig]. There can be many different zone instances in
  32. * a system, but only one zone is active at any given time which can be retrieved using
  33. * [Zone#current].
  34. *
  35. *
  36. *
  37. * ## Callback Wrapping
  38. *
  39. * An important aspect of the zones is that they should persist across asynchronous operations. To
  40. * achieve this, when a future work is scheduled through async API, it is necessary to capture, and
  41. * subsequently restore the current zone. For example if a code is running in zone `b` and it
  42. * invokes `setTimeout` to scheduleTask work later, the `setTimeout` method needs to 1) capture the
  43. * current zone and 2) wrap the `wrapCallback` in code which will restore the current zone `b` once
  44. * the wrapCallback executes. In this way the rules which govern the current code are preserved in
  45. * all future asynchronous tasks. There could be a different zone `c` which has different rules and
  46. * is associated with different asynchronous tasks. As these tasks are processed, each asynchronous
  47. * wrapCallback correctly restores the correct zone, as well as preserves the zone for future
  48. * asynchronous callbacks.
  49. *
  50. * Example: Suppose a browser page consist of application code as well as third-party
  51. * advertisement code. (These two code bases are independent, developed by different mutually
  52. * unaware developers.) The application code may be interested in doing global error handling and
  53. * so it configures the `app` zone to send all of the errors to the server for analysis, and then
  54. * executes the application in the `app` zone. The advertising code is interested in the same
  55. * error processing but it needs to send the errors to a different third-party. So it creates the
  56. * `ads` zone with a different error handler. Now both advertising as well as application code
  57. * create many asynchronous operations, but the [Zone] will ensure that all of the asynchronous
  58. * operations created from the application code will execute in `app` zone with its error
  59. * handler and all of the advertisement code will execute in the `ads` zone with its error handler.
  60. * This will not only work for the async operations created directly, but also for all subsequent
  61. * asynchronous operations.
  62. *
  63. * If you think of chain of asynchronous operations as a thread of execution (bit of a stretch)
  64. * then [Zone#current] will act as a thread local variable.
  65. *
  66. *
  67. *
  68. * ## Asynchronous operation scheduling
  69. *
  70. * In addition to wrapping the callbacks to restore the zone, all operations which cause a
  71. * scheduling of work for later are routed through the current zone which is allowed to intercept
  72. * them by adding work before or after the wrapCallback as well as using different means of
  73. * achieving the request. (Useful for unit testing, or tracking of requests). In some instances
  74. * such as `setTimeout` the wrapping of the wrapCallback and scheduling is done in the same
  75. * wrapCallback, but there are other examples such as `Promises` where the `then` wrapCallback is
  76. * wrapped, but the execution of `then` is triggered by `Promise` scheduling `resolve` work.
  77. *
  78. * Fundamentally there are three kinds of tasks which can be scheduled:
  79. *
  80. * 1. [MicroTask] used for doing work right after the current task. This is non-cancelable which is
  81. * guaranteed to run exactly once and immediately.
  82. * 2. [MacroTask] used for doing work later. Such as `setTimeout`. This is typically cancelable
  83. * which is guaranteed to execute at least once after some well understood delay.
  84. * 3. [EventTask] used for listening on some future event. This may execute zero or more times, with
  85. * an unknown delay.
  86. *
  87. * Each asynchronous API is modeled and routed through one of these APIs.
  88. *
  89. *
  90. * ### [MicroTask]
  91. *
  92. * [MicroTask]s represent work which will be done in current VM turn as soon as possible, before VM
  93. * yielding.
  94. *
  95. *
  96. * ### [MacroTask]
  97. *
  98. * [MacroTask]s represent work which will be done after some delay. (Sometimes the delay is
  99. * approximate such as on next available animation frame). Typically these methods include:
  100. * `setTimeout`, `setImmediate`, `setInterval`, `requestAnimationFrame`, and all browser specific
  101. * variants.
  102. *
  103. *
  104. * ### [EventTask]
  105. *
  106. * [EventTask]s represent a request to create a listener on an event. Unlike the other task
  107. * events they may never be executed, but typically execute more than once. There is no queue of
  108. * events, rather their callbacks are unpredictable both in order and time.
  109. *
  110. *
  111. * ## Global Error Handling
  112. *
  113. *
  114. * ## Composability
  115. *
  116. * Zones can be composed together through [Zone.fork()]. A child zone may create its own set of
  117. * rules. A child zone is expected to either:
  118. *
  119. * 1. Delegate the interception to a parent zone, and optionally add before and after wrapCallback
  120. * hooks.
  121. * 2. Process the request itself without delegation.
  122. *
  123. * Composability allows zones to keep their concerns clean. For example a top most zone may choose
  124. * to handle error handling, while child zones may choose to do user action tracking.
  125. *
  126. *
  127. * ## Root Zone
  128. *
  129. * At the start the browser will run in a special root zone, which is configured to behave exactly
  130. * like the platform, making any existing code which is not zone-aware behave as expected. All
  131. * zones are children of the root zone.
  132. *
  133. */
  134. interface Zone {
  135. /**
  136. *
  137. * @returns {Zone} The parent Zone.
  138. */
  139. parent: Zone | null;
  140. /**
  141. * @returns {string} The Zone name (useful for debugging)
  142. */
  143. name: string;
  144. /**
  145. * Returns a value associated with the `key`.
  146. *
  147. * If the current zone does not have a key, the request is delegated to the parent zone. Use
  148. * [ZoneSpec.properties] to configure the set of properties associated with the current zone.
  149. *
  150. * @param key The key to retrieve.
  151. * @returns {any} The value for the key, or `undefined` if not found.
  152. */
  153. get(key: string): any;
  154. /**
  155. * Returns a Zone which defines a `key`.
  156. *
  157. * Recursively search the parent Zone until a Zone which has a property `key` is found.
  158. *
  159. * @param key The key to use for identification of the returned zone.
  160. * @returns {Zone} The Zone which defines the `key`, `null` if not found.
  161. */
  162. getZoneWith(key: string): Zone | null;
  163. /**
  164. * Used to create a child zone.
  165. *
  166. * @param zoneSpec A set of rules which the child zone should follow.
  167. * @returns {Zone} A new child zone.
  168. */
  169. fork(zoneSpec: ZoneSpec): Zone;
  170. /**
  171. * Wraps a callback function in a new function which will properly restore the current zone upon
  172. * invocation.
  173. *
  174. * The wrapped function will properly forward `this` as well as `arguments` to the `callback`.
  175. *
  176. * Before the function is wrapped the zone can intercept the `callback` by declaring
  177. * [ZoneSpec.onIntercept].
  178. *
  179. * @param callback the function which will be wrapped in the zone.
  180. * @param source A unique debug location of the API being wrapped.
  181. * @returns {function(): *} A function which will invoke the `callback` through [Zone.runGuarded].
  182. */
  183. wrap<F extends Function>(callback: F, source: string): F;
  184. /**
  185. * Invokes a function in a given zone.
  186. *
  187. * The invocation of `callback` can be intercepted by declaring [ZoneSpec.onInvoke].
  188. *
  189. * @param callback The function to invoke.
  190. * @param applyThis
  191. * @param applyArgs
  192. * @param source A unique debug location of the API being invoked.
  193. * @returns {any} Value from the `callback` function.
  194. */
  195. run<T>(callback: Function, applyThis?: any, applyArgs?: any[], source?: string): T;
  196. /**
  197. * Invokes a function in a given zone and catches any exceptions.
  198. *
  199. * Any exceptions thrown will be forwarded to [Zone.HandleError].
  200. *
  201. * The invocation of `callback` can be intercepted by declaring [ZoneSpec.onInvoke]. The
  202. * handling of exceptions can be intercepted by declaring [ZoneSpec.handleError].
  203. *
  204. * @param callback The function to invoke.
  205. * @param applyThis
  206. * @param applyArgs
  207. * @param source A unique debug location of the API being invoked.
  208. * @returns {any} Value from the `callback` function.
  209. */
  210. runGuarded<T>(callback: Function, applyThis?: any, applyArgs?: any[], source?: string): T;
  211. /**
  212. * Execute the Task by restoring the [Zone.currentTask] in the Task's zone.
  213. *
  214. * @param task to run
  215. * @param applyThis
  216. * @param applyArgs
  217. * @returns {any} Value from the `task.callback` function.
  218. */
  219. runTask<T>(task: Task, applyThis?: any, applyArgs?: any): T;
  220. /**
  221. * Schedule a MicroTask.
  222. *
  223. * @param source
  224. * @param callback
  225. * @param data
  226. * @param customSchedule
  227. */
  228. scheduleMicroTask(source: string, callback: Function, data?: TaskData, customSchedule?: (task: Task) => void): MicroTask;
  229. /**
  230. * Schedule a MacroTask.
  231. *
  232. * @param source
  233. * @param callback
  234. * @param data
  235. * @param customSchedule
  236. * @param customCancel
  237. */
  238. scheduleMacroTask(source: string, callback: Function, data?: TaskData, customSchedule?: (task: Task) => void, customCancel?: (task: Task) => void): MacroTask;
  239. /**
  240. * Schedule an EventTask.
  241. *
  242. * @param source
  243. * @param callback
  244. * @param data
  245. * @param customSchedule
  246. * @param customCancel
  247. */
  248. scheduleEventTask(source: string, callback: Function, data?: TaskData, customSchedule?: (task: Task) => void, customCancel?: (task: Task) => void): EventTask;
  249. /**
  250. * Schedule an existing Task.
  251. *
  252. * Useful for rescheduling a task which was already canceled.
  253. *
  254. * @param task
  255. */
  256. scheduleTask<T extends Task>(task: T): T;
  257. /**
  258. * Allows the zone to intercept canceling of scheduled Task.
  259. *
  260. * The interception is configured using [ZoneSpec.onCancelTask]. The default canceler invokes
  261. * the [Task.cancelFn].
  262. *
  263. * @param task
  264. * @returns {any}
  265. */
  266. cancelTask(task: Task): any;
  267. }
  268. interface ZoneType {
  269. /**
  270. * @returns {Zone} Returns the current [Zone]. The only way to change
  271. * the current zone is by invoking a run() method, which will update the current zone for the
  272. * duration of the run method callback.
  273. */
  274. current: Zone;
  275. /**
  276. * @returns {Task} The task associated with the current execution.
  277. */
  278. currentTask: Task | null;
  279. /**
  280. * Verify that Zone has been correctly patched. Specifically that Promise is zone aware.
  281. */
  282. assertZonePatched(): void;
  283. /**
  284. * Return the root zone.
  285. */
  286. root: Zone;
  287. /**
  288. * load patch for specified native module, allow user to
  289. * define their own patch, user can use this API after loading zone.js
  290. */
  291. __load_patch(name: string, fn: _PatchFn, ignoreDuplicate?: boolean): void;
  292. /**
  293. * Zone symbol API to generate a string with __zone_symbol__ prefix
  294. */
  295. __symbol__(name: string): string;
  296. }
  297. /**
  298. * Patch Function to allow user define their own monkey patch module.
  299. */
  300. type _PatchFn = (global: Window, Zone: ZoneType, api: _ZonePrivate) => void;
  301. /**
  302. * _ZonePrivate interface to provide helper method to help user implement
  303. * their own monkey patch module.
  304. */
  305. interface _ZonePrivate {
  306. currentZoneFrame: () => _ZoneFrame;
  307. symbol: (name: string) => string;
  308. scheduleMicroTask: (task?: MicroTask) => void;
  309. onUnhandledError: (error: Error) => void;
  310. microtaskDrainDone: () => void;
  311. showUncaughtError: () => boolean;
  312. patchEventTarget: (global: any, api: _ZonePrivate, apis: any[], options?: any) => boolean[];
  313. patchOnProperties: (obj: any, properties: string[] | null, prototype?: any) => void;
  314. patchThen: (ctro: Function) => void;
  315. patchMethod: (target: any, name: string, patchFn: (delegate: Function, delegateName: string, name: string) => (self: any, args: any[]) => any) => Function | null;
  316. bindArguments: (args: any[], source: string) => any[];
  317. patchMacroTask: (obj: any, funcName: string, metaCreator: (self: any, args: any[]) => any) => void;
  318. patchEventPrototype: (_global: any, api: _ZonePrivate) => void;
  319. isIEOrEdge: () => boolean;
  320. ObjectDefineProperty: (o: any, p: PropertyKey, attributes: PropertyDescriptor & ThisType<any>) => any;
  321. ObjectGetOwnPropertyDescriptor: (o: any, p: PropertyKey) => PropertyDescriptor | undefined;
  322. ObjectCreate(o: object | null, properties?: PropertyDescriptorMap & ThisType<any>): any;
  323. ArraySlice(start?: number, end?: number): any[];
  324. patchClass: (className: string) => void;
  325. wrapWithCurrentZone: (callback: any, source: string) => any;
  326. filterProperties: (target: any, onProperties: string[], ignoreProperties: any[]) => string[];
  327. attachOriginToPatched: (target: any, origin: any) => void;
  328. _redefineProperty: (target: any, callback: string, desc: any) => void;
  329. nativeScheduleMicroTask: (func: Function) => void;
  330. patchCallbacks: (api: _ZonePrivate, target: any, targetName: string, method: string, callbacks: string[]) => void;
  331. getGlobalObjects: () => {
  332. globalSources: any;
  333. zoneSymbolEventNames: any;
  334. eventNames: string[];
  335. isBrowser: boolean;
  336. isMix: boolean;
  337. isNode: boolean;
  338. TRUE_STR: string;
  339. FALSE_STR: string;
  340. ZONE_SYMBOL_PREFIX: string;
  341. ADD_EVENT_LISTENER_STR: string;
  342. REMOVE_EVENT_LISTENER_STR: string;
  343. } | undefined;
  344. }
  345. /**
  346. * _ZoneFrame represents zone stack frame information
  347. */
  348. interface _ZoneFrame {
  349. parent: _ZoneFrame | null;
  350. zone: Zone;
  351. }
  352. interface UncaughtPromiseError extends Error {
  353. zone: Zone;
  354. task: Task;
  355. promise: Promise<any>;
  356. rejection: any;
  357. throwOriginal?: boolean;
  358. }
  359. /**
  360. * Provides a way to configure the interception of zone events.
  361. *
  362. * Only the `name` property is required (all other are optional).
  363. */
  364. interface ZoneSpec {
  365. /**
  366. * The name of the zone. Useful when debugging Zones.
  367. */
  368. name: string;
  369. /**
  370. * A set of properties to be associated with Zone. Use [Zone.get] to retrieve them.
  371. */
  372. properties?: {
  373. [key: string]: any;
  374. };
  375. /**
  376. * Allows the interception of zone forking.
  377. *
  378. * When the zone is being forked, the request is forwarded to this method for interception.
  379. *
  380. * @param parentZoneDelegate Delegate which performs the parent [ZoneSpec] operation.
  381. * @param currentZone The current [Zone] where the current interceptor has been declared.
  382. * @param targetZone The [Zone] which originally received the request.
  383. * @param zoneSpec The argument passed into the `fork` method.
  384. */
  385. onFork?: (parentZoneDelegate: ZoneDelegate, currentZone: Zone, targetZone: Zone, zoneSpec: ZoneSpec) => Zone;
  386. /**
  387. * Allows interception of the wrapping of the callback.
  388. *
  389. * @param parentZoneDelegate Delegate which performs the parent [ZoneSpec] operation.
  390. * @param currentZone The current [Zone] where the current interceptor has been declared.
  391. * @param targetZone The [Zone] which originally received the request.
  392. * @param delegate The argument passed into the `wrap` method.
  393. * @param source The argument passed into the `wrap` method.
  394. */
  395. onIntercept?: (parentZoneDelegate: ZoneDelegate, currentZone: Zone, targetZone: Zone, delegate: Function, source: string) => Function;
  396. /**
  397. * Allows interception of the callback invocation.
  398. *
  399. * @param parentZoneDelegate Delegate which performs the parent [ZoneSpec] operation.
  400. * @param currentZone The current [Zone] where the current interceptor has been declared.
  401. * @param targetZone The [Zone] which originally received the request.
  402. * @param delegate The argument passed into the `run` method.
  403. * @param applyThis The argument passed into the `run` method.
  404. * @param applyArgs The argument passed into the `run` method.
  405. * @param source The argument passed into the `run` method.
  406. */
  407. onInvoke?: (parentZoneDelegate: ZoneDelegate, currentZone: Zone, targetZone: Zone, delegate: Function, applyThis: any, applyArgs?: any[], source?: string) => any;
  408. /**
  409. * Allows interception of the error handling.
  410. *
  411. * @param parentZoneDelegate Delegate which performs the parent [ZoneSpec] operation.
  412. * @param currentZone The current [Zone] where the current interceptor has been declared.
  413. * @param targetZone The [Zone] which originally received the request.
  414. * @param error The argument passed into the `handleError` method.
  415. */
  416. onHandleError?: (parentZoneDelegate: ZoneDelegate, currentZone: Zone, targetZone: Zone, error: any) => boolean;
  417. /**
  418. * Allows interception of task scheduling.
  419. *
  420. * @param parentZoneDelegate Delegate which performs the parent [ZoneSpec] operation.
  421. * @param currentZone The current [Zone] where the current interceptor has been declared.
  422. * @param targetZone The [Zone] which originally received the request.
  423. * @param task The argument passed into the `scheduleTask` method.
  424. */
  425. onScheduleTask?: (parentZoneDelegate: ZoneDelegate, currentZone: Zone, targetZone: Zone, task: Task) => Task;
  426. onInvokeTask?: (parentZoneDelegate: ZoneDelegate, currentZone: Zone, targetZone: Zone, task: Task, applyThis: any, applyArgs?: any[]) => any;
  427. /**
  428. * Allows interception of task cancellation.
  429. *
  430. * @param parentZoneDelegate Delegate which performs the parent [ZoneSpec] operation.
  431. * @param currentZone The current [Zone] where the current interceptor has been declared.
  432. * @param targetZone The [Zone] which originally received the request.
  433. * @param task The argument passed into the `cancelTask` method.
  434. */
  435. onCancelTask?: (parentZoneDelegate: ZoneDelegate, currentZone: Zone, targetZone: Zone, task: Task) => any;
  436. /**
  437. * Notifies of changes to the task queue empty status.
  438. *
  439. * @param parentZoneDelegate Delegate which performs the parent [ZoneSpec] operation.
  440. * @param currentZone The current [Zone] where the current interceptor has been declared.
  441. * @param targetZone The [Zone] which originally received the request.
  442. * @param hasTaskState
  443. */
  444. onHasTask?: (parentZoneDelegate: ZoneDelegate, currentZone: Zone, targetZone: Zone, hasTaskState: HasTaskState) => void;
  445. }
  446. /**
  447. * A delegate when intercepting zone operations.
  448. *
  449. * A ZoneDelegate is needed because a child zone can't simply invoke a method on a parent zone. For
  450. * example a child zone wrap can't just call parent zone wrap. Doing so would create a callback
  451. * which is bound to the parent zone. What we are interested in is intercepting the callback before
  452. * it is bound to any zone. Furthermore, we also need to pass the targetZone (zone which received
  453. * the original request) to the delegate.
  454. *
  455. * The ZoneDelegate methods mirror those of Zone with an addition of extra targetZone argument in
  456. * the method signature. (The original Zone which received the request.) Some methods are renamed
  457. * to prevent confusion, because they have slightly different semantics and arguments.
  458. *
  459. * - `wrap` => `intercept`: The `wrap` method delegates to `intercept`. The `wrap` method returns
  460. * a callback which will run in a given zone, where as intercept allows wrapping the callback
  461. * so that additional code can be run before and after, but does not associate the callback
  462. * with the zone.
  463. * - `run` => `invoke`: The `run` method delegates to `invoke` to perform the actual execution of
  464. * the callback. The `run` method switches to new zone; saves and restores the `Zone.current`;
  465. * and optionally performs error handling. The invoke is not responsible for error handling,
  466. * or zone management.
  467. *
  468. * Not every method is usually overwritten in the child zone, for this reason the ZoneDelegate
  469. * stores the closest zone which overwrites this behavior along with the closest ZoneSpec.
  470. *
  471. * NOTE: We have tried to make this API analogous to Event bubbling with target and current
  472. * properties.
  473. *
  474. * Note: The ZoneDelegate treats ZoneSpec as class. This allows the ZoneSpec to use its `this` to
  475. * store internal state.
  476. */
  477. interface ZoneDelegate {
  478. zone: Zone;
  479. fork(targetZone: Zone, zoneSpec: ZoneSpec): Zone;
  480. intercept(targetZone: Zone, callback: Function, source: string): Function;
  481. invoke(targetZone: Zone, callback: Function, applyThis?: any, applyArgs?: any[], source?: string): any;
  482. handleError(targetZone: Zone, error: any): boolean;
  483. scheduleTask(targetZone: Zone, task: Task): Task;
  484. invokeTask(targetZone: Zone, task: Task, applyThis?: any, applyArgs?: any[]): any;
  485. cancelTask(targetZone: Zone, task: Task): any;
  486. hasTask(targetZone: Zone, isEmpty: HasTaskState): void;
  487. }
  488. type HasTaskState = {
  489. microTask: boolean;
  490. macroTask: boolean;
  491. eventTask: boolean;
  492. change: TaskType;
  493. };
  494. /**
  495. * Task type: `microTask`, `macroTask`, `eventTask`.
  496. */
  497. type TaskType = 'microTask' | 'macroTask' | 'eventTask';
  498. /**
  499. * Task type: `notScheduled`, `scheduling`, `scheduled`, `running`, `canceling`, 'unknown'.
  500. */
  501. type TaskState = 'notScheduled' | 'scheduling' | 'scheduled' | 'running' | 'canceling' | 'unknown';
  502. /**
  503. */
  504. interface TaskData {
  505. /**
  506. * A periodic [MacroTask] is such which get automatically rescheduled after it is executed.
  507. */
  508. isPeriodic?: boolean;
  509. /**
  510. * Delay in milliseconds when the Task will run.
  511. */
  512. delay?: number;
  513. /**
  514. * identifier returned by the native setTimeout.
  515. */
  516. handleId?: number;
  517. }
  518. /**
  519. * Represents work which is executed with a clean stack.
  520. *
  521. * Tasks are used in Zones to mark work which is performed on clean stack frame. There are three
  522. * kinds of task. [MicroTask], [MacroTask], and [EventTask].
  523. *
  524. * A JS VM can be modeled as a [MicroTask] queue, [MacroTask] queue, and [EventTask] set.
  525. *
  526. * - [MicroTask] queue represents a set of tasks which are executing right after the current stack
  527. * frame becomes clean and before a VM yield. All [MicroTask]s execute in order of insertion
  528. * before VM yield and the next [MacroTask] is executed.
  529. * - [MacroTask] queue represents a set of tasks which are executed one at a time after each VM
  530. * yield. The queue is ordered by time, and insertions can happen in any location.
  531. * - [EventTask] is a set of tasks which can at any time be inserted to the end of the [MacroTask]
  532. * queue. This happens when the event fires.
  533. *
  534. */
  535. interface Task {
  536. /**
  537. * Task type: `microTask`, `macroTask`, `eventTask`.
  538. */
  539. type: TaskType;
  540. /**
  541. * Task state: `notScheduled`, `scheduling`, `scheduled`, `running`, `canceling`, `unknown`.
  542. */
  543. state: TaskState;
  544. /**
  545. * Debug string representing the API which requested the scheduling of the task.
  546. */
  547. source: string;
  548. /**
  549. * The Function to be used by the VM upon entering the [Task]. This function will delegate to
  550. * [Zone.runTask] and delegate to `callback`.
  551. */
  552. invoke: Function;
  553. /**
  554. * Function which needs to be executed by the Task after the [Zone.currentTask] has been set to
  555. * the current task.
  556. */
  557. callback: Function;
  558. /**
  559. * Task specific options associated with the current task. This is passed to the `scheduleFn`.
  560. */
  561. data?: TaskData;
  562. /**
  563. * Represents the default work which needs to be done to schedule the Task by the VM.
  564. *
  565. * A zone may choose to intercept this function and perform its own scheduling.
  566. */
  567. scheduleFn?: (task: Task) => void;
  568. /**
  569. * Represents the default work which needs to be done to un-schedule the Task from the VM. Not all
  570. * Tasks are cancelable, and therefore this method is optional.
  571. *
  572. * A zone may chose to intercept this function and perform its own un-scheduling.
  573. */
  574. cancelFn?: (task: Task) => void;
  575. /**
  576. * @type {Zone} The zone which will be used to invoke the `callback`. The Zone is captured
  577. * at the time of Task creation.
  578. */
  579. readonly zone: Zone;
  580. /**
  581. * Number of times the task has been executed, or -1 if canceled.
  582. */
  583. runCount: number;
  584. /**
  585. * Cancel the scheduling request. This method can be called from `ZoneSpec.onScheduleTask` to
  586. * cancel the current scheduling interception. Once canceled the task can be discarded or
  587. * rescheduled using `Zone.scheduleTask` on a different zone.
  588. */
  589. cancelScheduleRequest(): void;
  590. }
  591. interface MicroTask extends Task {
  592. type: 'microTask';
  593. }
  594. interface MacroTask extends Task {
  595. type: 'macroTask';
  596. }
  597. interface EventTask extends Task {
  598. type: 'eventTask';
  599. }
  600. declare const Zone: ZoneType;
  601. /**
  602. * @license
  603. * Copyright Google LLC All Rights Reserved.
  604. *
  605. * Use of this source code is governed by an MIT-style license that can be
  606. * found in the LICENSE file at https://angular.io/license
  607. */
  608. /**
  609. * Additional `EventTarget` methods added by `Zone.js`.
  610. *
  611. * 1. removeAllListeners, remove all event listeners of the given event name.
  612. * 2. eventListeners, get all event listeners of the given event name.
  613. */
  614. interface EventTarget {
  615. /**
  616. *
  617. * Remove all event listeners by name for this event target.
  618. *
  619. * This method is optional because it may not be available if you use `noop zone` when
  620. * bootstrapping Angular application or disable the `EventTarget` monkey patch by `zone.js`.
  621. *
  622. * If the `eventName` is provided, will remove event listeners of that name.
  623. * If the `eventName` is not provided, will remove all event listeners associated with
  624. * `EventTarget`.
  625. *
  626. * @param eventName the name of the event, such as `click`. This parameter is optional.
  627. */
  628. removeAllListeners?(eventName?: string): void;
  629. /**
  630. *
  631. * Retrieve all event listeners by name.
  632. *
  633. * This method is optional because it may not be available if you use `noop zone` when
  634. * bootstrapping Angular application or disable the `EventTarget` monkey patch by `zone.js`.
  635. *
  636. * If the `eventName` is provided, will return an array of event handlers or event listener
  637. * objects of the given event.
  638. * If the `eventName` is not provided, will return all listeners.
  639. *
  640. * @param eventName the name of the event, such as click. This parameter is optional.
  641. */
  642. eventListeners?(eventName?: string): EventListenerOrEventListenerObject[];
  643. }
  644. /**
  645. * @license
  646. * Copyright Google LLC All Rights Reserved.
  647. *
  648. * Use of this source code is governed by an MIT-style license that can be
  649. * found in the LICENSE file at https://angular.io/license
  650. */
  651. /**
  652. * Interface of `zone.js` configurations.
  653. *
  654. * You can define the following configurations on the `window/global` object before
  655. * importing `zone.js` to change `zone.js` default behaviors.
  656. */
  657. interface ZoneGlobalConfigurations {
  658. /**
  659. * Disable the monkey patch of the `Node.js` `EventEmitter` API.
  660. *
  661. * By default, `zone.js` monkey patches the `Node.js` `EventEmitter` APIs to make asynchronous
  662. * callbacks of those APIs in the same zone when scheduled.
  663. *
  664. * Consider the following example:
  665. *
  666. * ```
  667. * const EventEmitter = require('events');
  668. * class MyEmitter extends EventEmitter {}
  669. * const myEmitter = new MyEmitter();
  670. *
  671. * const zone = Zone.current.fork({name: 'myZone'});
  672. * zone.run(() => {
  673. * myEmitter.on('event', () => {
  674. * console.log('an event occurs in the zone', Zone.current.name);
  675. * // the callback runs in the zone when it is scheduled,
  676. * // so the output is 'an event occurs in the zone myZone'.
  677. * });
  678. * });
  679. * myEmitter.emit('event');
  680. * ```
  681. *
  682. * If you set `__Zone_disable_EventEmitter = true` before importing `zone.js`,
  683. * `zone.js` does not monkey patch the `EventEmitter` APIs and the above code
  684. * outputs 'an event occurred <root>'.
  685. */
  686. __Zone_disable_EventEmitter?: boolean;
  687. /**
  688. * Disable the monkey patch of the `Node.js` `fs` API.
  689. *
  690. * By default, `zone.js` monkey patches `Node.js` `fs` APIs to make asynchronous callbacks of
  691. * those APIs in the same zone when scheduled.
  692. *
  693. * Consider the following example:
  694. *
  695. * ```
  696. * const fs = require('fs');
  697. *
  698. * const zone = Zone.current.fork({name: 'myZone'});
  699. * zone.run(() => {
  700. * fs.stat('/tmp/world', (err, stats) => {
  701. * console.log('fs.stats() callback is invoked in the zone', Zone.current.name);
  702. * // since the callback of the `fs.stat()` runs in the same zone
  703. * // when it is called, so the output is 'fs.stats() callback is invoked in the zone myZone'.
  704. * });
  705. * });
  706. * ```
  707. *
  708. * If you set `__Zone_disable_fs = true` before importing `zone.js`,
  709. * `zone.js` does not monkey patch the `fs` API and the above code
  710. * outputs 'get stats occurred <root>'.
  711. */
  712. __Zone_disable_fs?: boolean;
  713. /**
  714. * Disable the monkey patch of the `Node.js` `timer` API.
  715. *
  716. * By default, `zone.js` monkey patches the `Node.js` `timer` APIs to make asynchronous
  717. * callbacks of those APIs in the same zone when scheduled.
  718. *
  719. * Consider the following example:
  720. *
  721. * ```
  722. * const zone = Zone.current.fork({name: 'myZone'});
  723. * zone.run(() => {
  724. * setTimeout(() => {
  725. * console.log('setTimeout() callback is invoked in the zone', Zone.current.name);
  726. * // since the callback of `setTimeout()` runs in the same zone
  727. * // when it is scheduled, so the output is 'setTimeout() callback is invoked in the zone
  728. * // myZone'.
  729. * });
  730. * });
  731. * ```
  732. *
  733. * If you set `__Zone_disable_timers = true` before importing `zone.js`,
  734. * `zone.js` does not monkey patch the `timer` APIs and the above code
  735. * outputs 'timeout <root>'.
  736. */
  737. __Zone_disable_node_timers?: boolean;
  738. /**
  739. * Disable the monkey patch of the `Node.js` `process.nextTick()` API.
  740. *
  741. * By default, `zone.js` monkey patches the `Node.js` `process.nextTick()` API to make the
  742. * callback in the same zone when calling `process.nextTick()`.
  743. *
  744. * Consider the following example:
  745. *
  746. * ```
  747. * const zone = Zone.current.fork({name: 'myZone'});
  748. * zone.run(() => {
  749. * process.nextTick(() => {
  750. * console.log('process.nextTick() callback is invoked in the zone', Zone.current.name);
  751. * // since the callback of `process.nextTick()` runs in the same zone
  752. * // when it is scheduled, so the output is 'process.nextTick() callback is invoked in the
  753. * // zone myZone'.
  754. * });
  755. * });
  756. * ```
  757. *
  758. * If you set `__Zone_disable_nextTick = true` before importing `zone.js`,
  759. * `zone.js` does not monkey patch the `process.nextTick()` API and the above code
  760. * outputs 'nextTick <root>'.
  761. */
  762. __Zone_disable_nextTick?: boolean;
  763. /**
  764. * Disable the monkey patch of the `Node.js` `crypto` API.
  765. *
  766. * By default, `zone.js` monkey patches the `Node.js` `crypto` APIs to make asynchronous callbacks
  767. * of those APIs in the same zone when called.
  768. *
  769. * Consider the following example:
  770. *
  771. * ```
  772. * const crypto = require('crypto');
  773. *
  774. * const zone = Zone.current.fork({name: 'myZone'});
  775. * zone.run(() => {
  776. * crypto.randomBytes(() => {
  777. * console.log('crypto.randomBytes() callback is invoked in the zone', Zone.current.name);
  778. * // since the callback of `crypto.randomBytes()` runs in the same zone
  779. * // when it is called, so the output is 'crypto.randomBytes() callback is invoked in the
  780. * // zone myZone'.
  781. * });
  782. * });
  783. * ```
  784. *
  785. * If you set `__Zone_disable_crypto = true` before importing `zone.js`,
  786. * `zone.js` does not monkey patch the `crypto` API and the above code
  787. * outputs 'crypto <root>'.
  788. */
  789. __Zone_disable_crypto?: boolean;
  790. /**
  791. * Disable the monkey patch of the `Object.defineProperty()` API.
  792. *
  793. * Note: This configuration is available only in the legacy bundle (dist/zone.js). This module is
  794. * not available in the evergreen bundle (zone-evergreen.js).
  795. *
  796. * In the legacy browser, the default behavior of `zone.js` is to monkey patch
  797. * `Object.defineProperty()` and `Object.create()` to try to ensure PropertyDescriptor parameter's
  798. * configurable property to be true. This patch is only needed in some old mobile browsers.
  799. *
  800. * If you set `__Zone_disable_defineProperty = true` before importing `zone.js`,
  801. * `zone.js` does not monkey patch the `Object.defineProperty()` API and does not
  802. * modify desc.configurable to true.
  803. *
  804. */
  805. __Zone_disable_defineProperty?: boolean;
  806. /**
  807. * Disable the monkey patch of the browser `registerElement()` API.
  808. *
  809. * NOTE: This configuration is only available in the legacy bundle (dist/zone.js), this
  810. * module is not available in the evergreen bundle (zone-evergreen.js).
  811. *
  812. * In the legacy browser, the default behavior of `zone.js` is to monkey patch the
  813. * `registerElement()` API to make asynchronous callbacks of the API in the same zone when
  814. * `registerElement()` is called.
  815. *
  816. * Consider the following example:
  817. *
  818. * ```
  819. * const proto = Object.create(HTMLElement.prototype);
  820. * proto.createdCallback = function() {
  821. * console.log('createdCallback is invoked in the zone', Zone.current.name);
  822. * };
  823. * proto.attachedCallback = function() {
  824. * console.log('attachedCallback is invoked in the zone', Zone.current.name);
  825. * };
  826. * proto.detachedCallback = function() {
  827. * console.log('detachedCallback is invoked in the zone', Zone.current.name);
  828. * };
  829. * proto.attributeChangedCallback = function() {
  830. * console.log('attributeChangedCallback is invoked in the zone', Zone.current.name);
  831. * };
  832. *
  833. * const zone = Zone.current.fork({name: 'myZone'});
  834. * zone.run(() => {
  835. * document.registerElement('x-elem', {prototype: proto});
  836. * });
  837. * ```
  838. *
  839. * When these callbacks are invoked, those callbacks will be in the zone when
  840. * `registerElement()` is called.
  841. *
  842. * If you set `__Zone_disable_registerElement = true` before importing `zone.js`,
  843. * `zone.js` does not monkey patch `registerElement()` API and the above code
  844. * outputs '<root>'.
  845. */
  846. __Zone_disable_registerElement?: boolean;
  847. /**
  848. * Disable the monkey patch of the browser legacy `EventTarget` API.
  849. *
  850. * NOTE: This configuration is only available in the legacy bundle (dist/zone.js), this module
  851. * is not available in the evergreen bundle (zone-evergreen.js).
  852. *
  853. * In some old browsers, the `EventTarget` is not available, so `zone.js` cannot directly monkey
  854. * patch the `EventTarget`. Instead, `zone.js` patches all known HTML elements' prototypes (such
  855. * as `HtmlDivElement`). The callback of the `addEventListener()` will be in the same zone when
  856. * the `addEventListener()` is called.
  857. *
  858. * Consider the following example:
  859. *
  860. * ```
  861. * const zone = Zone.current.fork({name: 'myZone'});
  862. * zone.run(() => {
  863. * div.addEventListener('click', () => {
  864. * console.log('div click event listener is invoked in the zone', Zone.current.name);
  865. * // the output is 'div click event listener is invoked in the zone myZone'.
  866. * });
  867. * });
  868. * ```
  869. *
  870. * If you set `__Zone_disable_EventTargetLegacy = true` before importing `zone.js`
  871. * In some old browsers, where `EventTarget` is not available, if you set
  872. * `__Zone_disable_EventTargetLegacy = true` before importing `zone.js`, `zone.js` does not monkey
  873. * patch all HTML element APIs and the above code outputs 'clicked <root>'.
  874. */
  875. __Zone_disable_EventTargetLegacy?: boolean;
  876. /**
  877. * Disable the monkey patch of the browser `timer` APIs.
  878. *
  879. * By default, `zone.js` monkey patches browser timer
  880. * APIs (`setTimeout()`/`setInterval()`/`setImmediate()`) to make asynchronous callbacks of those
  881. * APIs in the same zone when scheduled.
  882. *
  883. * Consider the following example:
  884. *
  885. * ```
  886. * const zone = Zone.current.fork({name: 'myZone'});
  887. * zone.run(() => {
  888. * setTimeout(() => {
  889. * console.log('setTimeout() callback is invoked in the zone', Zone.current.name);
  890. * // since the callback of `setTimeout()` runs in the same zone
  891. * // when it is scheduled, so the output is 'setTimeout() callback is invoked in the zone
  892. * // myZone'.
  893. * });
  894. * });
  895. * ```
  896. *
  897. * If you set `__Zone_disable_timers = true` before importing `zone.js`,
  898. * `zone.js` does not monkey patch `timer` API and the above code
  899. * outputs 'timeout <root>'.
  900. *
  901. */
  902. __Zone_disable_timers?: boolean;
  903. /**
  904. * Disable the monkey patch of the browser `requestAnimationFrame()` API.
  905. *
  906. * By default, `zone.js` monkey patches the browser `requestAnimationFrame()` API
  907. * to make the asynchronous callback of the `requestAnimationFrame()` in the same zone when
  908. * scheduled.
  909. *
  910. * Consider the following example:
  911. *
  912. * ```
  913. * const zone = Zone.current.fork({name: 'myZone'});
  914. * zone.run(() => {
  915. * requestAnimationFrame(() => {
  916. * console.log('requestAnimationFrame() callback is invoked in the zone', Zone.current.name);
  917. * // since the callback of `requestAnimationFrame()` will be in the same zone
  918. * // when it is scheduled, so the output will be 'requestAnimationFrame() callback is invoked
  919. * // in the zone myZone'
  920. * });
  921. * });
  922. * ```
  923. *
  924. * If you set `__Zone_disable_requestAnimationFrame = true` before importing `zone.js`,
  925. * `zone.js` does not monkey patch the `requestAnimationFrame()` API and the above code
  926. * outputs 'raf <root>'.
  927. */
  928. __Zone_disable_requestAnimationFrame?: boolean;
  929. /**
  930. *
  931. * Disable the monkey patching of the `queueMicrotask()` API.
  932. *
  933. * By default, `zone.js` monkey patches the `queueMicrotask()` API
  934. * to ensure that `queueMicrotask()` callback is invoked in the same zone as zone used to invoke
  935. * `queueMicrotask()`. And also the callback is running as `microTask` like
  936. * `Promise.prototype.then()`.
  937. *
  938. * Consider the following example:
  939. *
  940. * ```
  941. * const zone = Zone.current.fork({name: 'myZone'});
  942. * zone.run(() => {
  943. * queueMicrotask(() => {
  944. * console.log('queueMicrotask() callback is invoked in the zone', Zone.current.name);
  945. * // Since `queueMicrotask()` was invoked in `myZone`, same zone is restored
  946. * // when 'queueMicrotask() callback is invoked, resulting in `myZone` being console logged.
  947. * });
  948. * });
  949. * ```
  950. *
  951. * If you set `__Zone_disable_queueMicrotask = true` before importing `zone.js`,
  952. * `zone.js` does not monkey patch the `queueMicrotask()` API and the above code
  953. * output will change to: 'queueMicrotask() callback is invoked in the zone <root>'.
  954. */
  955. __Zone_disable_queueMicrotask?: boolean;
  956. /**
  957. *
  958. * Disable the monkey patch of the browser blocking APIs(`alert()`/`prompt()`/`confirm()`).
  959. */
  960. __Zone_disable_blocking?: boolean;
  961. /**
  962. * Disable the monkey patch of the browser `EventTarget` APIs.
  963. *
  964. * By default, `zone.js` monkey patches EventTarget APIs. The callbacks of the
  965. * `addEventListener()` run in the same zone when the `addEventListener()` is called.
  966. *
  967. * Consider the following example:
  968. *
  969. * ```
  970. * const zone = Zone.current.fork({name: 'myZone'});
  971. * zone.run(() => {
  972. * div.addEventListener('click', () => {
  973. * console.log('div event listener is invoked in the zone', Zone.current.name);
  974. * // the output is 'div event listener is invoked in the zone myZone'.
  975. * });
  976. * });
  977. * ```
  978. *
  979. * If you set `__Zone_disable_EventTarget = true` before importing `zone.js`,
  980. * `zone.js` does not monkey patch EventTarget API and the above code
  981. * outputs 'clicked <root>'.
  982. *
  983. */
  984. __Zone_disable_EventTarget?: boolean;
  985. /**
  986. * Disable the monkey patch of the browser `FileReader` APIs.
  987. */
  988. __Zone_disable_FileReader?: boolean;
  989. /**
  990. * Disable the monkey patch of the browser `MutationObserver` APIs.
  991. */
  992. __Zone_disable_MutationObserver?: boolean;
  993. /**
  994. * Disable the monkey patch of the browser `IntersectionObserver` APIs.
  995. */
  996. __Zone_disable_IntersectionObserver?: boolean;
  997. /**
  998. * Disable the monkey patch of the browser onProperty APIs(such as onclick).
  999. *
  1000. * By default, `zone.js` monkey patches onXXX properties (such as onclick). The callbacks of onXXX
  1001. * properties run in the same zone when the onXXX properties is set.
  1002. *
  1003. * Consider the following example:
  1004. *
  1005. * ```
  1006. * const zone = Zone.current.fork({name: 'myZone'});
  1007. * zone.run(() => {
  1008. * div.onclick = () => {
  1009. * console.log('div click event listener is invoked in the zone', Zone.current.name);
  1010. * // the output will be 'div click event listener is invoked in the zone myZone'
  1011. * }
  1012. * });
  1013. * ```
  1014. *
  1015. * If you set `__Zone_disable_on_property = true` before importing `zone.js`,
  1016. * `zone.js` does not monkey patch onXXX properties and the above code
  1017. * outputs 'clicked <root>'.
  1018. *
  1019. */
  1020. __Zone_disable_on_property?: boolean;
  1021. /**
  1022. * Disable the monkey patch of the browser `customElements` APIs.
  1023. *
  1024. * By default, `zone.js` monkey patches `customElements` APIs to make callbacks run in the
  1025. * same zone when the `customElements.define()` is called.
  1026. *
  1027. * Consider the following example:
  1028. *
  1029. * ```
  1030. * class TestCustomElement extends HTMLElement {
  1031. * constructor() { super(); }
  1032. * connectedCallback() {}
  1033. * disconnectedCallback() {}
  1034. * attributeChangedCallback(attrName, oldVal, newVal) {}
  1035. * adoptedCallback() {}
  1036. * }
  1037. *
  1038. * const zone = Zone.fork({name: 'myZone'});
  1039. * zone.run(() => {
  1040. * customElements.define('x-elem', TestCustomElement);
  1041. * });
  1042. * ```
  1043. *
  1044. * All those callbacks defined in TestCustomElement runs in the zone when
  1045. * the `customElements.define()` is called.
  1046. *
  1047. * If you set `__Zone_disable_customElements = true` before importing `zone.js`,
  1048. * `zone.js` does not monkey patch `customElements` APIs and the above code
  1049. * runs inside <root> zone.
  1050. */
  1051. __Zone_disable_customElements?: boolean;
  1052. /**
  1053. * Disable the monkey patch of the browser `XMLHttpRequest` APIs.
  1054. *
  1055. * By default, `zone.js` monkey patches `XMLHttpRequest` APIs to make XMLHttpRequest act
  1056. * as macroTask.
  1057. *
  1058. * Consider the following example:
  1059. *
  1060. * ```
  1061. * const zone = Zone.current.fork({
  1062. * name: 'myZone',
  1063. * onScheduleTask: (delegate, curr, target, task) => {
  1064. * console.log('task is scheduled', task.type, task.source, task.zone.name);
  1065. * return delegate.scheduleTask(target, task);
  1066. * }
  1067. * })
  1068. * const xhr = new XMLHttpRequest();
  1069. * zone.run(() => {
  1070. * xhr.onload = function() {};
  1071. * xhr.open('get', '/', true);
  1072. * xhr.send();
  1073. * });
  1074. * ```
  1075. *
  1076. * In this example, the instance of XMLHttpRequest runs in the zone and acts as a macroTask. The
  1077. * output is 'task is scheduled macroTask, XMLHttpRequest.send, zone'.
  1078. *
  1079. * If you set `__Zone_disable_XHR = true` before importing `zone.js`,
  1080. * `zone.js` does not monkey patch `XMLHttpRequest` APIs and the above onScheduleTask callback
  1081. * will not be called.
  1082. *
  1083. */
  1084. __Zone_disable_XHR?: boolean;
  1085. /**
  1086. * Disable the monkey patch of the browser geolocation APIs.
  1087. *
  1088. * By default, `zone.js` monkey patches geolocation APIs to make callbacks run in the same zone
  1089. * when those APIs are called.
  1090. *
  1091. * Consider the following examples:
  1092. *
  1093. * ```
  1094. * const zone = Zone.current.fork({
  1095. * name: 'myZone'
  1096. * });
  1097. *
  1098. * zone.run(() => {
  1099. * navigator.geolocation.getCurrentPosition(pos => {
  1100. * console.log('navigator.getCurrentPosition() callback is invoked in the zone',
  1101. * Zone.current.name);
  1102. * // output is 'navigator.getCurrentPosition() callback is invoked in the zone myZone'.
  1103. * }
  1104. * });
  1105. * ```
  1106. *
  1107. * If set you `__Zone_disable_geolocation = true` before importing `zone.js`,
  1108. * `zone.js` does not monkey patch geolocation APIs and the above code
  1109. * outputs 'getCurrentPosition <root>'.
  1110. *
  1111. */
  1112. __Zone_disable_geolocation?: boolean;
  1113. /**
  1114. * Disable the monkey patch of the browser `canvas` APIs.
  1115. *
  1116. * By default, `zone.js` monkey patches `canvas` APIs to make callbacks run in the same zone when
  1117. * those APIs are called.
  1118. *
  1119. * Consider the following example:
  1120. *
  1121. * ```
  1122. * const zone = Zone.current.fork({
  1123. * name: 'myZone'
  1124. * });
  1125. *
  1126. * zone.run(() => {
  1127. * canvas.toBlob(blog => {
  1128. * console.log('canvas.toBlob() callback is invoked in the zone', Zone.current.name);
  1129. * // output is 'canvas.toBlob() callback is invoked in the zone myZone'.
  1130. * }
  1131. * });
  1132. * ```
  1133. *
  1134. * If you set `__Zone_disable_canvas = true` before importing `zone.js`,
  1135. * `zone.js` does not monkey patch `canvas` APIs and the above code
  1136. * outputs 'canvas.toBlob <root>'.
  1137. */
  1138. __Zone_disable_canvas?: boolean;
  1139. /**
  1140. * Disable the `Promise` monkey patch.
  1141. *
  1142. * By default, `zone.js` monkey patches `Promise` APIs to make the `then()/catch()` callbacks in
  1143. * the same zone when those callbacks are called.
  1144. *
  1145. * Consider the following examples:
  1146. *
  1147. * ```
  1148. * const zone = Zone.current.fork({name: 'myZone'});
  1149. *
  1150. * const p = Promise.resolve(1);
  1151. *
  1152. * zone.run(() => {
  1153. * p.then(() => {
  1154. * console.log('then() callback is invoked in the zone', Zone.current.name);
  1155. * // output is 'then() callback is invoked in the zone myZone'.
  1156. * });
  1157. * });
  1158. * ```
  1159. *
  1160. * If you set `__Zone_disable_ZoneAwarePromise = true` before importing `zone.js`,
  1161. * `zone.js` does not monkey patch `Promise` APIs and the above code
  1162. * outputs 'promise then callback <root>'.
  1163. */
  1164. __Zone_disable_ZoneAwarePromise?: boolean;
  1165. /**
  1166. * Define event names that users don't want monkey patched by the `zone.js`.
  1167. *
  1168. * By default, `zone.js` monkey patches EventTarget.addEventListener(). The event listener
  1169. * callback runs in the same zone when the addEventListener() is called.
  1170. *
  1171. * Sometimes, you don't want all of the event names used in this patched version because it
  1172. * impacts performance. For example, you might want `scroll` or `mousemove` event listeners to run
  1173. * the native `addEventListener()` for better performance.
  1174. *
  1175. * Users can achieve this goal by defining `__zone_symbol__UNPATCHED_EVENTS = ['scroll',
  1176. * 'mousemove'];` before importing `zone.js`.
  1177. */
  1178. __zone_symbol__UNPATCHED_EVENTS?: string[];
  1179. /**
  1180. * Define the event names of the passive listeners.
  1181. *
  1182. * To add passive event listeners, you can use `elem.addEventListener('scroll', listener,
  1183. * {passive: true});` or implement your own `EventManagerPlugin`.
  1184. *
  1185. * You can also define a global variable as follows:
  1186. *
  1187. * ```
  1188. * __zone_symbol__PASSIVE_EVENTS = ['scroll'];
  1189. * ```
  1190. *
  1191. * The preceding code makes all scroll event listeners passive.
  1192. */
  1193. __zone_symbol__PASSIVE_EVENTS?: string[];
  1194. /**
  1195. * Disable wrapping uncaught promise rejection.
  1196. *
  1197. * By default, `zone.js` wraps the uncaught promise rejection in a new `Error` object
  1198. * which contains additional information such as a value of the rejection and a stack trace.
  1199. *
  1200. * If you set `__zone_symbol__DISABLE_WRAPPING_UNCAUGHT_PROMISE_REJECTION = true;` before
  1201. * importing `zone.js`, `zone.js` will not wrap the uncaught promise rejection.
  1202. */
  1203. __zone_symbol__DISABLE_WRAPPING_UNCAUGHT_PROMISE_REJECTION?: boolean;
  1204. }
  1205. /**
  1206. * Interface of `zone-testing.js` test configurations.
  1207. *
  1208. * You can define the following configurations on the `window` or `global` object before
  1209. * importing `zone-testing.js` to change `zone-testing.js` default behaviors in the test runner.
  1210. */
  1211. interface ZoneTestConfigurations {
  1212. /**
  1213. * Disable the Jasmine integration.
  1214. *
  1215. * In the `zone-testing.js` bundle, by default, `zone-testing.js` monkey patches Jasmine APIs
  1216. * to make Jasmine APIs run in specified zone.
  1217. *
  1218. * 1. Make the `describe()`/`xdescribe()`/`fdescribe()` methods run in the syncTestZone.
  1219. * 2. Make the `it()`/`xit()`/`fit()`/`beforeEach()`/`afterEach()`/`beforeAll()`/`afterAll()`
  1220. * methods run in the ProxyZone.
  1221. *
  1222. * With this patch, `async()`/`fakeAsync()` can work with the Jasmine runner.
  1223. *
  1224. * If you set `__Zone_disable_jasmine = true` before importing `zone-testing.js`,
  1225. * `zone-testing.js` does not monkey patch the jasmine APIs and the `async()`/`fakeAsync()` cannot
  1226. * work with the Jasmine runner any longer.
  1227. */
  1228. __Zone_disable_jasmine?: boolean;
  1229. /**
  1230. * Disable the Mocha integration.
  1231. *
  1232. * In the `zone-testing.js` bundle, by default, `zone-testing.js` monkey patches the Mocha APIs
  1233. * to make Mocha APIs run in the specified zone.
  1234. *
  1235. * 1. Make the `describe()`/`xdescribe()`/`fdescribe()` methods run in the syncTestZone.
  1236. * 2. Make the `it()`/`xit()`/`fit()`/`beforeEach()`/`afterEach()`/`beforeAll()`/`afterAll()`
  1237. * methods run in the ProxyZone.
  1238. *
  1239. * With this patch, `async()`/`fakeAsync()` can work with the Mocha runner.
  1240. *
  1241. * If you set `__Zone_disable_mocha = true` before importing `zone-testing.js`,
  1242. * `zone-testing.js` does not monkey patch the Mocha APIs and the `async()/`fakeAsync()` can not
  1243. * work with the Mocha runner any longer.
  1244. */
  1245. __Zone_disable_mocha?: boolean;
  1246. /**
  1247. * Disable the Jest integration.
  1248. *
  1249. * In the `zone-testing.js` bundle, by default, `zone-testing.js` monkey patches Jest APIs
  1250. * to make Jest APIs run in the specified zone.
  1251. *
  1252. * 1. Make the `describe()`/`xdescribe()`/`fdescribe()` methods run in the syncTestZone.
  1253. * 2. Make the `it()`/`xit()`/`fit()`/`beforeEach()`/`afterEach()`/`before()`/`after()` methods
  1254. * run in the ProxyZone.
  1255. *
  1256. * With this patch, `async()`/`fakeAsync()` can work with the Jest runner.
  1257. *
  1258. * If you set `__Zone_disable_jest = true` before importing `zone-testing.js`,
  1259. * `zone-testing.js` does not monkey patch the jest APIs and `async()`/`fakeAsync()` cannot
  1260. * work with the Jest runner any longer.
  1261. */
  1262. __Zone_disable_jest?: boolean;
  1263. /**
  1264. * Disable monkey patch the jasmine clock APIs.
  1265. *
  1266. * By default, `zone-testing.js` monkey patches the `jasmine.clock()` API,
  1267. * so the `jasmine.clock()` can work with the `fakeAsync()/tick()` API.
  1268. *
  1269. * Consider the following example:
  1270. *
  1271. * ```
  1272. * describe('jasmine.clock integration', () => {
  1273. * beforeEach(() => {
  1274. * jasmine.clock().install();
  1275. * });
  1276. * afterEach(() => {
  1277. * jasmine.clock().uninstall();
  1278. * });
  1279. * it('fakeAsync test', fakeAsync(() => {
  1280. * setTimeout(spy, 100);
  1281. * expect(spy).not.toHaveBeenCalled();
  1282. * jasmine.clock().tick(100);
  1283. * expect(spy).toHaveBeenCalled();
  1284. * }));
  1285. * });
  1286. * ```
  1287. *
  1288. * In the `fakeAsync()` method, `jasmine.clock().tick()` works just like `tick()`.
  1289. *
  1290. * If you set `__zone_symbol__fakeAsyncDisablePatchingClock = true` before importing
  1291. * `zone-testing.js`,`zone-testing.js` does not monkey patch the `jasmine.clock()` APIs and the
  1292. * `jasmine.clock()` cannot work with `fakeAsync()` any longer.
  1293. */
  1294. __zone_symbol__fakeAsyncDisablePatchingClock?: boolean;
  1295. /**
  1296. * Enable auto running into `fakeAsync()` when installing the `jasmine.clock()`.
  1297. *
  1298. * By default, `zone-testing.js` does not automatically run into `fakeAsync()`
  1299. * if the `jasmine.clock().install()` is called.
  1300. *
  1301. * Consider the following example:
  1302. *
  1303. * ```
  1304. * describe('jasmine.clock integration', () => {
  1305. * beforeEach(() => {
  1306. * jasmine.clock().install();
  1307. * });
  1308. * afterEach(() => {
  1309. * jasmine.clock().uninstall();
  1310. * });
  1311. * it('fakeAsync test', fakeAsync(() => {
  1312. * setTimeout(spy, 100);
  1313. * expect(spy).not.toHaveBeenCalled();
  1314. * jasmine.clock().tick(100);
  1315. * expect(spy).toHaveBeenCalled();
  1316. * }));
  1317. * });
  1318. * ```
  1319. *
  1320. * You must run `fakeAsync()` to make test cases in the `FakeAsyncTestZone`.
  1321. *
  1322. * If you set `__zone_symbol__fakeAsyncAutoFakeAsyncWhenClockPatched = true` before importing
  1323. * `zone-testing.js`, `zone-testing.js` can run test case automatically in the
  1324. * `FakeAsyncTestZone` without calling the `fakeAsync()`.
  1325. *
  1326. * Consider the following example:
  1327. *
  1328. * ```
  1329. * describe('jasmine.clock integration', () => {
  1330. * beforeEach(() => {
  1331. * jasmine.clock().install();
  1332. * });
  1333. * afterEach(() => {
  1334. * jasmine.clock().uninstall();
  1335. * });
  1336. * it('fakeAsync test', () => { // here we don't need to call fakeAsync
  1337. * setTimeout(spy, 100);
  1338. * expect(spy).not.toHaveBeenCalled();
  1339. * jasmine.clock().tick(100);
  1340. * expect(spy).toHaveBeenCalled();
  1341. * });
  1342. * });
  1343. * ```
  1344. *
  1345. */
  1346. __zone_symbol__fakeAsyncAutoFakeAsyncWhenClockPatched?: boolean;
  1347. /**
  1348. * Enable waiting for the unresolved promise in the `async()` test.
  1349. *
  1350. * In the `async()` test, `AsyncTestZone` waits for all the asynchronous tasks to finish. By
  1351. * default, if some promises remain unresolved, `AsyncTestZone` does not wait and reports that it
  1352. * received an unexpected result.
  1353. *
  1354. * Consider the following example:
  1355. *
  1356. * ```
  1357. * describe('wait never resolved promise', () => {
  1358. * it('async with never resolved promise test', async(() => {
  1359. * const p = new Promise(() => {});
  1360. * p.then(() => {
  1361. * // do some expectation.
  1362. * });
  1363. * }))
  1364. * });
  1365. * ```
  1366. *
  1367. * By default, this case passes, because the callback of `p.then()` is never called. Because `p`
  1368. * is an unresolved promise, there is no pending asynchronous task, which means the `async()`
  1369. * method does not wait.
  1370. *
  1371. * If you set `__zone_symbol__supportWaitUnResolvedChainedPromise = true`, the above case
  1372. * times out, because `async()` will wait for the unresolved promise.
  1373. */
  1374. __zone_symbol__supportWaitUnResolvedChainedPromise?: boolean;
  1375. }
  1376. /**
  1377. * The interface of the `zone.js` runtime configurations.
  1378. *
  1379. * These configurations can be defined on the `Zone` object after
  1380. * importing zone.js to change behaviors. The differences between
  1381. * the `ZoneRuntimeConfigurations` and the `ZoneGlobalConfigurations` are,
  1382. *
  1383. * 1. `ZoneGlobalConfigurations` must be defined on the `global/window` object before importing
  1384. * `zone.js`. The value of the configuration cannot be changed at runtime.
  1385. *
  1386. * 2. `ZoneRuntimeConfigurations` must be defined on the `Zone` object after importing `zone.js`.
  1387. * You can change the value of this configuration at runtime.
  1388. *
  1389. */
  1390. interface ZoneRuntimeConfigurations {
  1391. /**
  1392. * Ignore outputting errors to the console when uncaught Promise errors occur.
  1393. *
  1394. * By default, if an uncaught Promise error occurs, `zone.js` outputs the
  1395. * error to the console by calling `console.error()`.
  1396. *
  1397. * If you set `__zone_symbol__ignoreConsoleErrorUncaughtError = true`, `zone.js` does not output
  1398. * the uncaught error to `console.error()`.
  1399. */
  1400. __zone_symbol__ignoreConsoleErrorUncaughtError?: boolean;
  1401. }