domain.d.ts (7810B)
1 /** 2 * **This module is pending deprecation.** Once a replacement API has been 3 * finalized, this module will be fully deprecated. Most developers should 4 * **not** have cause to use this module. Users who absolutely must have 5 * the functionality that domains provide may rely on it for the time being 6 * but should expect to have to migrate to a different solution 7 * in the future. 8 * 9 * Domains provide a way to handle multiple different IO operations as a 10 * single group. If any of the event emitters or callbacks registered to a 11 * domain emit an `'error'` event, or throw an error, then the domain object 12 * will be notified, rather than losing the context of the error in the`process.on('uncaughtException')` handler, or causing the program to 13 * exit immediately with an error code. 14 * @deprecated Since v1.4.2 - Deprecated 15 * @see [source](https://github.com/nodejs/node/blob/v16.9.0/lib/domain.js) 16 */ 17 declare module "domain" { 18 import EventEmitter = require("node:events"); 19 /** 20 * The `Domain` class encapsulates the functionality of routing errors and 21 * uncaught exceptions to the active `Domain` object. 22 * 23 * To handle the errors that it catches, listen to its `'error'` event. 24 */ 25 class Domain extends EventEmitter { 26 /** 27 * An array of timers and event emitters that have been explicitly added 28 * to the domain. 29 */ 30 members: Array<EventEmitter | NodeJS.Timer>; 31 /** 32 * The `enter()` method is plumbing used by the `run()`, `bind()`, and`intercept()` methods to set the active domain. It sets `domain.active` and `process.domain` to the domain, and implicitly 33 * pushes the domain onto the domain 34 * stack managed by the domain module (see {@link exit} for details on the 35 * domain stack). The call to `enter()` delimits the beginning of a chain of 36 * asynchronous calls and I/O operations bound to a domain. 37 * 38 * Calling `enter()` changes only the active domain, and does not alter the domain 39 * itself. `enter()` and `exit()` can be called an arbitrary number of times on a 40 * single domain. 41 */ 42 enter(): void; 43 /** 44 * The `exit()` method exits the current domain, popping it off the domain stack. 45 * Any time execution is going to switch to the context of a different chain of 46 * asynchronous calls, it's important to ensure that the current domain is exited. 47 * The call to `exit()` delimits either the end of or an interruption to the chain 48 * of asynchronous calls and I/O operations bound to a domain. 49 * 50 * If there are multiple, nested domains bound to the current execution context,`exit()` will exit any domains nested within this domain. 51 * 52 * Calling `exit()` changes only the active domain, and does not alter the domain 53 * itself. `enter()` and `exit()` can be called an arbitrary number of times on a 54 * single domain. 55 */ 56 exit(): void; 57 /** 58 * Run the supplied function in the context of the domain, implicitly 59 * binding all event emitters, timers, and lowlevel requests that are 60 * created in that context. Optionally, arguments can be passed to 61 * the function. 62 * 63 * This is the most basic way to use a domain. 64 * 65 * ```js 66 * import domain from 'node:domain'; 67 * import fs from 'node:fs'; 68 * const d = domain.create(); 69 * d.on('error', (er) => { 70 * console.error('Caught error!', er); 71 * }); 72 * d.run(() => { 73 * process.nextTick(() => { 74 * setTimeout(() => { // Simulating some various async stuff 75 * fs.open('non-existent file', 'r', (er, fd) => { 76 * if (er) throw er; 77 * // proceed... 78 * }); 79 * }, 100); 80 * }); 81 * }); 82 * ``` 83 * 84 * In this example, the `d.on('error')` handler will be triggered, rather 85 * than crashing the program. 86 */ 87 run<T>(fn: (...args: any[]) => T, ...args: any[]): T; 88 /** 89 * Explicitly adds an emitter to the domain. If any event handlers called by 90 * the emitter throw an error, or if the emitter emits an `'error'` event, it 91 * will be routed to the domain's `'error'` event, just like with implicit 92 * binding. 93 * 94 * This also works with timers that are returned from `setInterval()` and `setTimeout()`. If their callback function throws, it will be caught by 95 * the domain `'error'` handler. 96 * 97 * If the Timer or `EventEmitter` was already bound to a domain, it is removed 98 * from that one, and bound to this one instead. 99 * @param emitter emitter or timer to be added to the domain 100 */ 101 add(emitter: EventEmitter | NodeJS.Timer): void; 102 /** 103 * The opposite of {@link add}. Removes domain handling from the 104 * specified emitter. 105 * @param emitter emitter or timer to be removed from the domain 106 */ 107 remove(emitter: EventEmitter | NodeJS.Timer): void; 108 /** 109 * The returned function will be a wrapper around the supplied callback 110 * function. When the returned function is called, any errors that are 111 * thrown will be routed to the domain's `'error'` event. 112 * 113 * ```js 114 * const d = domain.create(); 115 * 116 * function readSomeFile(filename, cb) { 117 * fs.readFile(filename, 'utf8', d.bind((er, data) => { 118 * // If this throws, it will also be passed to the domain. 119 * return cb(er, data ? JSON.parse(data) : null); 120 * })); 121 * } 122 * 123 * d.on('error', (er) => { 124 * // An error occurred somewhere. If we throw it now, it will crash the program 125 * // with the normal line number and stack message. 126 * }); 127 * ``` 128 * @param callback The callback function 129 * @return The bound function 130 */ 131 bind<T extends Function>(callback: T): T; 132 /** 133 * This method is almost identical to {@link bind}. However, in 134 * addition to catching thrown errors, it will also intercept `Error` objects sent as the first argument to the function. 135 * 136 * In this way, the common `if (err) return callback(err);` pattern can be replaced 137 * with a single error handler in a single place. 138 * 139 * ```js 140 * const d = domain.create(); 141 * 142 * function readSomeFile(filename, cb) { 143 * fs.readFile(filename, 'utf8', d.intercept((data) => { 144 * // Note, the first argument is never passed to the 145 * // callback since it is assumed to be the 'Error' argument 146 * // and thus intercepted by the domain. 147 * 148 * // If this throws, it will also be passed to the domain 149 * // so the error-handling logic can be moved to the 'error' 150 * // event on the domain instead of being repeated throughout 151 * // the program. 152 * return cb(null, JSON.parse(data)); 153 * })); 154 * } 155 * 156 * d.on('error', (er) => { 157 * // An error occurred somewhere. If we throw it now, it will crash the program 158 * // with the normal line number and stack message. 159 * }); 160 * ``` 161 * @param callback The callback function 162 * @return The intercepted function 163 */ 164 intercept<T extends Function>(callback: T): T; 165 } 166 function create(): Domain; 167 } 168 declare module "node:domain" { 169 export * from "domain"; 170 }