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