@xylabs/forget 5.0.94 → 5.0.96

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/README.md +266 -122
  2. package/dist/neutral/ForgetPromise.d.ts.map +1 -1
  3. package/dist/neutral/index.mjs +1 -2
  4. package/dist/neutral/index.mjs.map +1 -1
  5. package/dist/node/ForgetPromise.d.ts.map +1 -1
  6. package/dist/node/index.mjs +1 -2
  7. package/dist/node/index.mjs.map +1 -1
  8. package/package.json +11 -15
package/README.md CHANGED
@@ -1,55 +1,52 @@
1
1
  # @xylabs/forget
2
2
 
3
- [![logo][]](https://xylabs.com)
3
+ [![npm][npm-badge]][npm-link]
4
+ [![license][license-badge]][license-link]
4
5
 
5
- [![main-build][]][main-build-link]
6
- [![npm-badge][]][npm-link]
7
- [![npm-downloads-badge][]][npm-link]
8
- [![jsdelivr-badge][]][jsdelivr-link]
9
- [![npm-license-badge][]](LICENSE)
10
- [![codacy-badge][]][codacy-link]
11
- [![codeclimate-badge][]][codeclimate-link]
12
- [![snyk-badge][]][snyk-link]
13
- [![socket-badge][]][socket-link]
6
+ > Base functionality used throughout XY Labs TypeScript/JavaScript libraries
14
7
 
8
+ ## Install
15
9
 
16
- Base functionality used throughout XY Labs TypeScript/JavaScript libraries
10
+ Using npm:
17
11
 
12
+ ```sh
13
+ npm install {{name}}
14
+ ```
18
15
 
16
+ Using yarn:
19
17
 
20
- ## Reference
18
+ ```sh
19
+ yarn add {{name}}
20
+ ```
21
21
 
22
- **@xylabs/forget**
22
+ Using pnpm:
23
23
 
24
- ***
24
+ ```sh
25
+ pnpm add {{name}}
26
+ ```
25
27
 
26
- ## Classes
28
+ Using bun:
27
29
 
28
- | Class | Description |
29
- | ------ | ------ |
30
- | [ForgetPromise](#classes/ForgetPromise) | Node.js extension of ForgetPromise that can terminate the process on exceptions or timeouts. |
30
+ ```sh
31
+ bun add {{name}}
32
+ ```
31
33
 
32
- ## Interfaces
33
34
 
34
- | Interface | Description |
35
- | ------ | ------ |
36
- | [ForgetNodeConfig](#interfaces/ForgetNodeConfig) | Node.js-specific forget configuration that extends ForgetConfig with process termination options. |
35
+ ## License
37
36
 
38
- ## Variables
37
+ See the [LICENSE](LICENSE) file for license rights and limitations (LGPL-3.0-only).
39
38
 
40
- | Variable | Description |
41
- | ------ | ------ |
42
- | [defaultForgetNodeConfig](#variables/defaultForgetNodeConfig) | Default Node.js forget configuration with termination disabled. |
39
+ ## Reference
43
40
 
44
- ## Functions
41
+ ### packages
45
42
 
46
- | Function | Description |
47
- | ------ | ------ |
48
- | [forget](#functions/forget) | Node.js variant of forget that can optionally terminate the process on exceptions or timeouts. |
43
+ ### forget
49
44
 
50
- ### classes
45
+ ### .temp-typedoc
51
46
 
52
- ### <a id="ForgetPromise"></a>ForgetPromise
47
+ ### classes
48
+
49
+ ### <a id="ForgetPromise"></a>ForgetPromise
53
50
 
54
51
  [**@xylabs/forget**](#../README)
55
52
 
@@ -81,11 +78,51 @@ ForgetPromise.constructor
81
78
 
82
79
  ## Properties
83
80
 
84
- | Property | Modifier | Type | Default value | Description | Inherited from |
85
- | ------ | ------ | ------ | ------ | ------ | ------ |
86
- | <a id="activeforgets"></a> `activeForgets` | `static` | `number` | `0` | Number of currently active (unresolved) forgotten promises. | `ForgetPromise.activeForgets` |
87
- | <a id="exceptedforgets"></a> `exceptedForgets` | `static` | `number` | `0` | Number of forgotten promises that threw exceptions. | `ForgetPromise.exceptedForgets` |
88
- | <a id="logger"></a> `logger` | `static` | `Logger` | `console` | Logger instance used for error and warning output. | `ForgetPromise.logger` |
81
+ ### activeForgets
82
+
83
+ ```ts
84
+ static activeForgets: number = 0;
85
+ ```
86
+
87
+ Number of currently active (unresolved) forgotten promises.
88
+
89
+ ### Inherited from
90
+
91
+ ```ts
92
+ ForgetPromise.activeForgets
93
+ ```
94
+
95
+ ***
96
+
97
+ ### exceptedForgets
98
+
99
+ ```ts
100
+ static exceptedForgets: number = 0;
101
+ ```
102
+
103
+ Number of forgotten promises that threw exceptions.
104
+
105
+ ### Inherited from
106
+
107
+ ```ts
108
+ ForgetPromise.exceptedForgets
109
+ ```
110
+
111
+ ***
112
+
113
+ ### logger
114
+
115
+ ```ts
116
+ static logger: Logger = console;
117
+ ```
118
+
119
+ Logger instance used for error and warning output.
120
+
121
+ ### Inherited from
122
+
123
+ ```ts
124
+ ForgetPromise.logger
125
+ ```
89
126
 
90
127
  ## Accessors
91
128
 
@@ -114,17 +151,24 @@ ForgetPromise.active
114
151
  ### awaitInactive()
115
152
 
116
153
  ```ts
117
- static awaitInactive(interval?: number, timeout?: number): Promise<number>;
154
+ static awaitInactive(interval?, timeout?): Promise<number>;
118
155
  ```
119
156
 
120
157
  Waits until all forgotten promises have completed.
121
158
 
122
159
  ### Parameters
123
160
 
124
- | Parameter | Type | Default value | Description |
125
- | ------ | ------ | ------ | ------ |
126
- | `interval` | `number` | `100` | Polling interval in milliseconds. |
127
- | `timeout?` | `number` | `undefined` | Optional maximum wait time in milliseconds. |
161
+ #### interval?
162
+
163
+ `number` = `100`
164
+
165
+ Polling interval in milliseconds.
166
+
167
+ #### timeout?
168
+
169
+ `number`
170
+
171
+ Optional maximum wait time in milliseconds.
128
172
 
129
173
  ### Returns
130
174
 
@@ -144,20 +188,26 @@ ForgetPromise.awaitInactive
144
188
 
145
189
  ```ts
146
190
  static exceptionHandler(
147
- error: Error,
148
- config: ForgetNodeConfig,
149
- externalStackTrace?: string): void;
191
+ error,
192
+ config,
193
+ externalStackTrace?): void;
150
194
  ```
151
195
 
152
196
  Handles exceptions, optionally terminating the process based on config.
153
197
 
154
198
  ### Parameters
155
199
 
156
- | Parameter | Type |
157
- | ------ | ------ |
158
- | `error` | `Error` |
159
- | `config` | [`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig) |
160
- | `externalStackTrace?` | `string` |
200
+ #### error
201
+
202
+ `Error`
203
+
204
+ #### config
205
+
206
+ [`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig)
207
+
208
+ #### externalStackTrace?
209
+
210
+ `string`
161
211
 
162
212
  ### Returns
163
213
 
@@ -174,23 +224,26 @@ ForgetPromise.exceptionHandler
174
224
  ### forget()
175
225
 
176
226
  ```ts
177
- static forget<T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>): void;
227
+ static forget<T>(promise, config?): void;
178
228
  ```
179
229
 
180
230
  Forgets a promise using Node.js-specific configuration with process termination support.
181
231
 
182
232
  ### Type Parameters
183
233
 
184
- | Type Parameter |
185
- | ------ |
186
- | `T` |
234
+ #### T
235
+
236
+ `T`
187
237
 
188
238
  ### Parameters
189
239
 
190
- | Parameter | Type |
191
- | ------ | ------ |
192
- | `promise` | `Promisable`\<`T`\> |
193
- | `config?` | [`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig)\<`T`\> |
240
+ #### promise
241
+
242
+ `Promisable`\<`T`\>
243
+
244
+ #### config?
245
+
246
+ [`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig)\<`T`\>
194
247
 
195
248
  ### Returns
196
249
 
@@ -208,20 +261,26 @@ ForgetPromise.forget
208
261
 
209
262
  ```ts
210
263
  static timeoutHandler(
211
- time: number,
212
- config: ForgetNodeConfig,
213
- externalStackTrace?: string): void;
264
+ time,
265
+ config,
266
+ externalStackTrace?): void;
214
267
  ```
215
268
 
216
269
  Handles timeouts, optionally terminating the process based on config.
217
270
 
218
271
  ### Parameters
219
272
 
220
- | Parameter | Type |
221
- | ------ | ------ |
222
- | `time` | `number` |
223
- | `config` | [`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig) |
224
- | `externalStackTrace?` | `string` |
273
+ #### time
274
+
275
+ `number`
276
+
277
+ #### config
278
+
279
+ [`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig)
280
+
281
+ #### externalStackTrace?
282
+
283
+ `string`
225
284
 
226
285
  ### Returns
227
286
 
@@ -233,40 +292,47 @@ Handles timeouts, optionally terminating the process based on config.
233
292
  ForgetPromise.timeoutHandler
234
293
  ```
235
294
 
236
- ### functions
295
+ ### functions
237
296
 
238
- ### <a id="forget"></a>forget
297
+ ### <a id="forget"></a>forget
239
298
 
240
299
  [**@xylabs/forget**](#../README)
241
300
 
242
301
  ***
243
302
 
244
303
  ```ts
245
- function forget<T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>): void;
304
+ function forget<T>(promise, config?): void;
246
305
  ```
247
306
 
248
307
  Node.js variant of forget that can optionally terminate the process on exceptions or timeouts.
249
308
 
250
309
  ## Type Parameters
251
310
 
252
- | Type Parameter |
253
- | ------ |
254
- | `T` |
311
+ ### T
312
+
313
+ `T`
255
314
 
256
315
  ## Parameters
257
316
 
258
- | Parameter | Type | Description |
259
- | ------ | ------ | ------ |
260
- | `promise` | `Promisable`\<`T`\> | The promise or promisable value to forget. |
261
- | `config?` | [`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig)\<`T`\> | Optional Node.js-specific configuration including process termination options. |
317
+ ### promise
318
+
319
+ `Promisable`\<`T`\>
320
+
321
+ The promise or promisable value to forget.
322
+
323
+ ### config?
324
+
325
+ [`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig)\<`T`\>
326
+
327
+ Optional Node.js-specific configuration including process termination options.
262
328
 
263
329
  ## Returns
264
330
 
265
331
  `void`
266
332
 
267
- ### interfaces
333
+ ### interfaces
268
334
 
269
- ### <a id="ForgetNodeConfig"></a>ForgetNodeConfig
335
+ ### <a id="ForgetNodeConfig"></a>ForgetNodeConfig
270
336
 
271
337
  [**@xylabs/forget**](#../README)
272
338
 
@@ -280,72 +346,150 @@ Node.js-specific forget configuration that extends ForgetConfig with process ter
280
346
 
281
347
  ## Type Parameters
282
348
 
283
- | Type Parameter | Default type |
284
- | ------ | ------ |
285
- | `T` | `any` |
349
+ ### T
350
+
351
+ `T` = `any`
286
352
 
287
353
  ## Properties
288
354
 
289
- | Property | Type | Description | Inherited from |
290
- | ------ | ------ | ------ | ------ |
291
- | <a id="name"></a> `name?` | `string` | Optional name for identifying the forgotten promise in logs. | `ForgetConfig.name` |
292
- | <a id="oncancel"></a> `onCancel?` | () => `void` | Called when the promise is cancelled due to timeout. | `ForgetConfig.onCancel` |
293
- | <a id="oncomplete"></a> `onComplete?` | (`result`: \[`T` \| `undefined`, `Error` \| `undefined`\]) => `void` | Called when the promise completes, with a tuple of [result, error]. | `ForgetConfig.onComplete` |
294
- | <a id="onexception"></a> `onException?` | (`error`: `Error`) => `void` | Called when an exception occurs outside the promise itself. | `ForgetConfig.onException` |
295
- | <a id="timeout"></a> `timeout?` | `number` | Timeout in milliseconds after which the promise is considered timed out. | `ForgetConfig.timeout` |
296
- | <a id="terminateonexception"></a> `terminateOnException?` | `boolean` | Terminate the process on an exception that happens outside of the promise being forgotten. | - |
297
- | <a id="terminateontimeout"></a> `terminateOnTimeout?` | `boolean` | Terminate the process if the promise times out. | - |
355
+ ### name?
356
+
357
+ ```ts
358
+ optional name?: string;
359
+ ```
298
360
 
299
- ### variables
361
+ Optional name for identifying the forgotten promise in logs.
300
362
 
301
- ### <a id="defaultForgetNodeConfig"></a>defaultForgetNodeConfig
363
+ ### Inherited from
302
364
 
303
- [**@xylabs/forget**](#../README)
365
+ ```ts
366
+ ForgetConfig.name
367
+ ```
304
368
 
305
369
  ***
306
370
 
371
+ ### onCancel?
372
+
307
373
  ```ts
308
- const defaultForgetNodeConfig: ForgetNodeConfig<unknown>;
374
+ optional onCancel?: () => void;
309
375
  ```
310
376
 
311
- Default Node.js forget configuration with termination disabled.
377
+ Called when the promise is cancelled due to timeout.
312
378
 
379
+ ### Returns
313
380
 
314
- Part of [sdk-js](https://www.npmjs.com/package/@xyo-network/sdk-js)
381
+ `void`
315
382
 
316
- ## Maintainers
383
+ ### Inherited from
317
384
 
318
- - [Arie Trouw](https://github.com/arietrouw) ([arietrouw.com](https://arietrouw.com))
319
- - [Matt Jones](https://github.com/jonesmac)
320
- - [Joel Carter](https://github.com/JoelBCarter)
321
- - [Jordan Trouw](https://github.com/jordantrouw)
385
+ ```ts
386
+ ForgetConfig.onCancel
387
+ ```
322
388
 
323
- ## License
389
+ ***
324
390
 
325
- > See the [LICENSE](LICENSE) file for license details
391
+ ### onComplete?
326
392
 
327
- ## Credits
393
+ ```ts
394
+ optional onComplete?: (result) => void;
395
+ ```
328
396
 
329
- [Made with 🔥 and ❄️ by XYLabs](https://xylabs.com)
397
+ Called when the promise completes, with a tuple of [result, error].
330
398
 
331
- [logo]: https://cdn.xy.company/img/brand/XYPersistentCompany_Logo_Icon_Colored.svg
399
+ ### Parameters
332
400
 
333
- [main-build]: https://github.com/xylabs/sdk-js/actions/workflows/build.yml/badge.svg
334
- [main-build-link]: https://github.com/xylabs/sdk-js/actions/workflows/build.yml
335
- [npm-badge]: https://img.shields.io/npm/v/@xylabs/forget.svg
336
- [npm-link]: https://www.npmjs.com/package/@xylabs/forget
337
- [codacy-badge]: https://app.codacy.com/project/badge/Grade/c8e15e14f37741c18cfb47ac7245c698
338
- [codacy-link]: https://www.codacy.com/gh/xylabs/sdk-js/dashboard?utm_source=github.com&utm_medium=referral&utm_content=xylabs/sdk-js&utm_campaign=Badge_Grade
339
- [codeclimate-badge]: https://api.codeclimate.com/v1/badges/c5eb068f806f0b047ea7/maintainability
340
- [codeclimate-link]: https://codeclimate.com/github/xylabs/sdk-js/maintainability
341
- [snyk-badge]: https://snyk.io/test/github/xylabs/sdk-js/badge.svg?targetFile=package.json
342
- [snyk-link]: https://snyk.io/test/github/xylabs/sdk-js?targetFile=package.json
401
+ #### result
402
+
403
+ \[`T` \| `undefined`, `Error` \| `undefined`\]
404
+
405
+ ### Returns
406
+
407
+ `void`
408
+
409
+ ### Inherited from
410
+
411
+ ```ts
412
+ ForgetConfig.onComplete
413
+ ```
343
414
 
344
- [npm-downloads-badge]: https://img.shields.io/npm/dw/@xylabs/forget
345
- [npm-license-badge]: https://img.shields.io/npm/l/@xylabs/forget
415
+ ***
416
+
417
+ ### onException?
418
+
419
+ ```ts
420
+ optional onException?: (error) => void;
421
+ ```
422
+
423
+ Called when an exception occurs outside the promise itself.
424
+
425
+ ### Parameters
426
+
427
+ #### error
428
+
429
+ `Error`
346
430
 
347
- [jsdelivr-badge]: https://data.jsdelivr.com/v1/package/npm/@xylabs/forget/badge
348
- [jsdelivr-link]: https://www.jsdelivr.com/package/npm/@xylabs/forget
431
+ ### Returns
432
+
433
+ `void`
434
+
435
+ ### Inherited from
436
+
437
+ ```ts
438
+ ForgetConfig.onException
439
+ ```
440
+
441
+ ***
349
442
 
350
- [socket-badge]: https://socket.dev/api/badge/npm/package/@xylabs/forget
351
- [socket-link]: https://socket.dev/npm/package/@xylabs/forget
443
+ ### timeout?
444
+
445
+ ```ts
446
+ optional timeout?: number;
447
+ ```
448
+
449
+ Timeout in milliseconds after which the promise is considered timed out.
450
+
451
+ ### Inherited from
452
+
453
+ ```ts
454
+ ForgetConfig.timeout
455
+ ```
456
+
457
+ ***
458
+
459
+ ### terminateOnException?
460
+
461
+ ```ts
462
+ optional terminateOnException?: boolean;
463
+ ```
464
+
465
+ Terminate the process on an exception that happens outside of the promise being forgotten.
466
+
467
+ ***
468
+
469
+ ### terminateOnTimeout?
470
+
471
+ ```ts
472
+ optional terminateOnTimeout?: boolean;
473
+ ```
474
+
475
+ Terminate the process if the promise times out.
476
+
477
+ ### variables
478
+
479
+ ### <a id="defaultForgetNodeConfig"></a>defaultForgetNodeConfig
480
+
481
+ [**@xylabs/forget**](#../README)
482
+
483
+ ***
484
+
485
+ ```ts
486
+ const defaultForgetNodeConfig: ForgetNodeConfig<unknown>;
487
+ ```
488
+
489
+ Default Node.js forget configuration with termination disabled.
490
+
491
+
492
+ [npm-badge]: https://img.shields.io/npm/v/@xylabs/forget.svg
493
+ [npm-link]: https://www.npmjs.com/package/@xylabs/forget
494
+ [license-badge]: https://img.shields.io/npm/l/@xylabs/forget.svg
495
+ [license-link]: https://github.com/xylabs/sdk-js/blob/main/LICENSE
package/dist/neutral/ForgetPromise.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"ForgetPromise.d.ts","sourceRoot":"","sources":["../../src/ForgetPromise.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAI5D,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAE1E,kDAAkD;AAClD,KAAK,kBAAkB,CAAC,CAAC,IAAI,MAAM,UAAU,CAAC,CAAC,CAAC,CAAA;AAEhD;;GAEG;AAEH,qBAAa,aAAa;IACxB,kEAAkE;IAClE,MAAM,CAAC,aAAa,SAAI;IACxB,0DAA0D;IAC1D,MAAM,CAAC,eAAe,SAAI;IAC1B,yDAAyD;IACzD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAU;IAE/B,uDAAuD;IACvD,MAAM,KAAK,MAAM,YAEhB;IAED;;;;;OAKG;WACU,aAAa,CAAC,QAAQ,SAAM,EAAE,OAAO,CAAC,EAAE,MAAM;IAc3D,2EAA2E;IAC3E,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,YAAY,EAAE,kBAAkB,CAAC,EAAE,MAAM;IAOzF;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC;IA+DzG,gFAAgF;IAChF,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAgB,EAAE,EAAE,YAAY,EAAE,kBAAkB,CAAC,EAAE,MAAM;CAMpG"}
1
+ {"version":3,"file":"ForgetPromise.d.ts","sourceRoot":"","sources":["../../src/ForgetPromise.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAG5D,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAE1E,kDAAkD;AAClD,KAAK,kBAAkB,CAAC,CAAC,IAAI,MAAM,UAAU,CAAC,CAAC,CAAC,CAAA;AAEhD;;GAEG;AAEH,qBAAa,aAAa;IACxB,kEAAkE;IAClE,MAAM,CAAC,aAAa,SAAI;IACxB,0DAA0D;IAC1D,MAAM,CAAC,eAAe,SAAI;IAC1B,yDAAyD;IACzD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAU;IAE/B,uDAAuD;IACvD,MAAM,KAAK,MAAM,YAEhB;IAED;;;;;OAKG;WACU,aAAa,CAAC,QAAQ,SAAM,EAAE,OAAO,CAAC,EAAE,MAAM;IAc3D,2EAA2E;IAC3E,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,YAAY,EAAE,kBAAkB,CAAC,EAAE,MAAM;IAOzF;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC;IA+DzG,gFAAgF;IAChF,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAgB,EAAE,EAAE,YAAY,EAAE,kBAAkB,CAAC,EAAE,MAAM;CAMpG"}
package/dist/neutral/index.mjs CHANGED
@@ -10,8 +10,7 @@ var defaultForgetNodeConfig = {
10
10
 
11
11
  // src/ForgetPromise.ts
12
12
  import { delay } from "@xylabs/delay";
13
- import { isPromise } from "@xylabs/promise";
14
- import { isNumber } from "@xylabs/typeof";
13
+ import { isNumber, isPromise } from "@xylabs/typeof";
15
14
  var ForgetPromise = class {
16
15
  /** Number of currently active (unresolved) forgotten promises. */
17
16
  static activeForgets = 0;
package/dist/neutral/index.mjs.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../../src/ForgetConfig.ts","../../src/ForgetNodeConfig.ts","../../src/ForgetPromise.ts","../../src/ForgetPromiseNode.ts","../../src/forgetNode.ts"],"sourcesContent":["/**\n * Configuration options for fire-and-forget promises.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface ForgetConfig<T = any> {\n /** Optional name for identifying the forgotten promise in logs. */\n name?: string\n /** Called when the promise is cancelled due to timeout. */\n onCancel?: () => void\n /** Called when the promise completes, with a tuple of [result, error]. */\n onComplete?: (result: [T | undefined, Error | undefined]) => void\n /** Called when an exception occurs outside the promise itself. */\n onException?: (error: Error) => void\n /** Timeout in milliseconds after which the promise is considered timed out. */\n timeout?: number\n}\n\n/** Default forget configuration with a 30-second timeout. */\nexport const defaultForgetConfig: ForgetConfig<unknown> = { timeout: 30_000 }\n","import { defaultForgetConfig, type ForgetConfig } from './ForgetConfig.ts'\n\n/**\n * Node.js-specific forget configuration that extends ForgetConfig with process termination options.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface ForgetNodeConfig<T = any> extends ForgetConfig<T> {\n /** Terminate the process on an exception that happens outside of the promise being forgotten. */\n terminateOnException?: boolean\n /** Terminate the process if the promise times out. */\n terminateOnTimeout?: boolean\n}\n\n/** Default Node.js forget configuration with termination disabled. */\nexport const defaultForgetNodeConfig: ForgetNodeConfig<unknown> = {\n ...defaultForgetConfig,\n terminateOnTimeout: false,\n terminateOnException: false,\n}\n","import { delay } from '@xylabs/delay'\nimport type { Logger } from '@xylabs/logger'\nimport type { Promisable, PromiseEx } from '@xylabs/promise'\nimport { isPromise } from '@xylabs/promise'\nimport { isNumber } from '@xylabs/typeof'\n\nimport { defaultForgetConfig, type ForgetConfig } from './ForgetConfig.ts'\n\n/** A function that returns a promisable value. */\ntype PromisableFunction<T> = () => Promisable<T>\n\n/**\n * Manages fire-and-forget promises with tracking, timeouts, and error handling.\n */\n// eslint-disable-next-line unicorn/no-static-only-class\nexport class ForgetPromise {\n /** Number of currently active (unresolved) forgotten promises. */\n static activeForgets = 0\n /** Number of forgotten promises that threw exceptions. */\n static exceptedForgets = 0\n /** Logger instance used for error and warning output. */\n static logger: Logger = console\n\n /** Whether any forgotten promises are still active. */\n static get active() {\n return this.activeForgets > 0\n }\n\n /**\n * Waits until all forgotten promises have completed.\n * @param interval - Polling interval in milliseconds.\n * @param timeout - Optional maximum wait time in milliseconds.\n * @returns The number of remaining active forgets (0 if all completed).\n */\n static async awaitInactive(interval = 100, timeout?: number) {\n let timeoutRemaining = timeout\n while (this.active) {\n await delay(interval)\n if (timeoutRemaining !== undefined) {\n timeoutRemaining -= interval\n if (timeoutRemaining <= 0) {\n return this.activeForgets\n }\n }\n }\n return 0\n }\n\n /** Handles exceptions from forgotten promises by logging error details. */\n static exceptionHandler(error: Error, { name }: ForgetConfig, externalStackTrace?: string) {\n this.logger.error(`forget promise handler excepted [${name}]: ${error.message}`, error)\n if (externalStackTrace !== undefined) {\n this.logger.warn(`External Stack trace [${name}]:`, externalStackTrace)\n }\n }\n\n /**\n * Used to explicitly launch an async function (or Promise) with awaiting it\n * @param promise The promise to forget\n * @param config Configuration of forget settings\n */\n static forget<T>(promise: Promise<T> | PromiseEx<T> | PromisableFunction<T> | T, config?: ForgetConfig<T>) {\n const externalStackTrace = (new Error('Stack')).stack\n\n // default | global | provided priorities for config (not deep merge)\n const resolvedConfig = {\n ...defaultForgetConfig, ...globalThis.xy?.forget?.config, ...config,\n }\n const resolvedPromise = typeof promise === 'function' ? (promise as PromisableFunction<T>)() : promise\n if (isPromise(resolvedPromise)) {\n try {\n let completed = false\n this.activeForgets++\n\n const promiseWrapper = async () => {\n await resolvedPromise\n .then((result: T) => {\n this.activeForgets--\n completed = true\n resolvedConfig?.onComplete?.([result, undefined])\n })\n .catch((error) => {\n this.activeForgets--\n completed = true\n this.logger.error(`forgotten promise excepted [${config?.name ?? 'unknown'}]: ${error.message}`, error)\n resolvedConfig?.onComplete?.([undefined, error])\n })\n }\n\n const promises = [promiseWrapper()]\n\n // if there is a timeout, add it to the race\n const timeout = resolvedConfig.timeout ?? defaultForgetConfig.timeout\n if (isNumber(timeout)) {\n const timeoutFunc = async () => {\n await delay(timeout)\n if (!completed) {\n resolvedConfig.onCancel?.()\n this.timeoutHandler(timeout, resolvedConfig, externalStackTrace)\n }\n }\n promises.push(timeoutFunc())\n }\n\n const all = Promise.race(promises)\n\n all\n .then(() => {\n return\n })\n .catch(() => {\n return\n })\n } catch (ex) {\n this.exceptedForgets += 1\n resolvedConfig?.onException?.(ex as Error)\n this.exceptionHandler(ex as Error, resolvedConfig, externalStackTrace)\n }\n } else {\n // we do nothing here since if it was a non-promise, it already got invoked.\n return\n }\n }\n\n /** Handles timeout events for forgotten promises by logging timeout details. */\n static timeoutHandler(time: number, { name = 'unknown' }: ForgetConfig, externalStackTrace?: string) {\n this.logger.error(`forget promise timeout out after ${time}ms [Cancelling] [${name}]`)\n if (externalStackTrace !== undefined) {\n this.logger.warn(`External Stack trace [${name}]:`, externalStackTrace)\n }\n }\n}\n","/// <reference types=\"node\" />\n\nimport type { Promisable } from '@xylabs/promise'\n\nimport { defaultForgetNodeConfig, type ForgetNodeConfig } from './ForgetNodeConfig.ts'\nimport { ForgetPromise } from './ForgetPromise.ts'\n\n/**\n * Node.js extension of ForgetPromise that can terminate the process on exceptions or timeouts.\n */\nexport class ForgetPromiseNode extends ForgetPromise {\n /** Handles exceptions, optionally terminating the process based on config. */\n static override exceptionHandler(error: Error, config: ForgetNodeConfig, externalStackTrace?: string) {\n // default | global | provided priorities for config (not deep merge)\n super.exceptionHandler(error, config, externalStackTrace)\n if (config?.terminateOnException === true) {\n this.logger.error(`Attempting to terminate process [${config?.name ?? 'unknown'}]...`)\n // eslint-disable-next-line unicorn/no-process-exit\n process.exit(1)\n }\n }\n\n /** Forgets a promise using Node.js-specific configuration with process termination support. */\n static override forget<T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>) {\n const resolvedConfig = {\n ...defaultForgetNodeConfig, ...globalThis.xy?.forget?.config, ...config,\n }\n super.forget(promise, resolvedConfig)\n }\n\n /** Handles timeouts, optionally terminating the process based on config. */\n static override timeoutHandler(time: number, config: ForgetNodeConfig, externalStackTrace?: string) {\n super.timeoutHandler(time, config, externalStackTrace)\n if (config?.terminateOnTimeout === true) {\n this.logger.error(`Attempting to terminate process [${config?.name ?? 'unknown'}]...`)\n // eslint-disable-next-line unicorn/no-process-exit\n process.exit(2)\n }\n }\n}\n","import { type Promisable } from '@xylabs/promise'\n\nimport type { ForgetNodeConfig } from './ForgetNodeConfig.ts'\nimport { ForgetPromiseNode } from './ForgetPromiseNode.ts'\n\n/**\n * Node.js variant of forget that can optionally terminate the process on exceptions or timeouts.\n * @param promise - The promise or promisable value to forget.\n * @param config - Optional Node.js-specific configuration including process termination options.\n */\nexport const forgetNode = <T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>) => {\n ForgetPromiseNode.forget<T>(promise, config)\n}\n"],"mappings":"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","names":[]}
1
+ {"version":3,"sources":["../../src/ForgetConfig.ts","../../src/ForgetNodeConfig.ts","../../src/ForgetPromise.ts","../../src/ForgetPromiseNode.ts","../../src/forgetNode.ts"],"sourcesContent":["/**\n * Configuration options for fire-and-forget promises.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface ForgetConfig<T = any> {\n /** Optional name for identifying the forgotten promise in logs. */\n name?: string\n /** Called when the promise is cancelled due to timeout. */\n onCancel?: () => void\n /** Called when the promise completes, with a tuple of [result, error]. */\n onComplete?: (result: [T | undefined, Error | undefined]) => void\n /** Called when an exception occurs outside the promise itself. */\n onException?: (error: Error) => void\n /** Timeout in milliseconds after which the promise is considered timed out. */\n timeout?: number\n}\n\n/** Default forget configuration with a 30-second timeout. */\nexport const defaultForgetConfig: ForgetConfig<unknown> = { timeout: 30_000 }\n","import { defaultForgetConfig, type ForgetConfig } from './ForgetConfig.ts'\n\n/**\n * Node.js-specific forget configuration that extends ForgetConfig with process termination options.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface ForgetNodeConfig<T = any> extends ForgetConfig<T> {\n /** Terminate the process on an exception that happens outside of the promise being forgotten. */\n terminateOnException?: boolean\n /** Terminate the process if the promise times out. */\n terminateOnTimeout?: boolean\n}\n\n/** Default Node.js forget configuration with termination disabled. */\nexport const defaultForgetNodeConfig: ForgetNodeConfig<unknown> = {\n ...defaultForgetConfig,\n terminateOnTimeout: false,\n terminateOnException: false,\n}\n","import { delay } from '@xylabs/delay'\nimport type { Logger } from '@xylabs/logger'\nimport type { Promisable, PromiseEx } from '@xylabs/promise'\nimport { isNumber, isPromise } from '@xylabs/typeof'\n\nimport { defaultForgetConfig, type ForgetConfig } from './ForgetConfig.ts'\n\n/** A function that returns a promisable value. */\ntype PromisableFunction<T> = () => Promisable<T>\n\n/**\n * Manages fire-and-forget promises with tracking, timeouts, and error handling.\n */\n// eslint-disable-next-line unicorn/no-static-only-class\nexport class ForgetPromise {\n /** Number of currently active (unresolved) forgotten promises. */\n static activeForgets = 0\n /** Number of forgotten promises that threw exceptions. */\n static exceptedForgets = 0\n /** Logger instance used for error and warning output. */\n static logger: Logger = console\n\n /** Whether any forgotten promises are still active. */\n static get active() {\n return this.activeForgets > 0\n }\n\n /**\n * Waits until all forgotten promises have completed.\n * @param interval - Polling interval in milliseconds.\n * @param timeout - Optional maximum wait time in milliseconds.\n * @returns The number of remaining active forgets (0 if all completed).\n */\n static async awaitInactive(interval = 100, timeout?: number) {\n let timeoutRemaining = timeout\n while (this.active) {\n await delay(interval)\n if (timeoutRemaining !== undefined) {\n timeoutRemaining -= interval\n if (timeoutRemaining <= 0) {\n return this.activeForgets\n }\n }\n }\n return 0\n }\n\n /** Handles exceptions from forgotten promises by logging error details. */\n static exceptionHandler(error: Error, { name }: ForgetConfig, externalStackTrace?: string) {\n this.logger.error(`forget promise handler excepted [${name}]: ${error.message}`, error)\n if (externalStackTrace !== undefined) {\n this.logger.warn(`External Stack trace [${name}]:`, externalStackTrace)\n }\n }\n\n /**\n * Used to explicitly launch an async function (or Promise) with awaiting it\n * @param promise The promise to forget\n * @param config Configuration of forget settings\n */\n static forget<T>(promise: Promise<T> | PromiseEx<T> | PromisableFunction<T> | T, config?: ForgetConfig<T>) {\n const externalStackTrace = (new Error('Stack')).stack\n\n // default | global | provided priorities for config (not deep merge)\n const resolvedConfig = {\n ...defaultForgetConfig, ...globalThis.xy?.forget?.config, ...config,\n }\n const resolvedPromise = typeof promise === 'function' ? (promise as PromisableFunction<T>)() : promise\n if (isPromise(resolvedPromise)) {\n try {\n let completed = false\n this.activeForgets++\n\n const promiseWrapper = async () => {\n await resolvedPromise\n .then((result: T) => {\n this.activeForgets--\n completed = true\n resolvedConfig?.onComplete?.([result, undefined])\n })\n .catch((error) => {\n this.activeForgets--\n completed = true\n this.logger.error(`forgotten promise excepted [${config?.name ?? 'unknown'}]: ${error.message}`, error)\n resolvedConfig?.onComplete?.([undefined, error])\n })\n }\n\n const promises = [promiseWrapper()]\n\n // if there is a timeout, add it to the race\n const timeout = resolvedConfig.timeout ?? defaultForgetConfig.timeout\n if (isNumber(timeout)) {\n const timeoutFunc = async () => {\n await delay(timeout)\n if (!completed) {\n resolvedConfig.onCancel?.()\n this.timeoutHandler(timeout, resolvedConfig, externalStackTrace)\n }\n }\n promises.push(timeoutFunc())\n }\n\n const all = Promise.race(promises)\n\n all\n .then(() => {\n return\n })\n .catch(() => {\n return\n })\n } catch (ex) {\n this.exceptedForgets += 1\n resolvedConfig?.onException?.(ex as Error)\n this.exceptionHandler(ex as Error, resolvedConfig, externalStackTrace)\n }\n } else {\n // we do nothing here since if it was a non-promise, it already got invoked.\n return\n }\n }\n\n /** Handles timeout events for forgotten promises by logging timeout details. */\n static timeoutHandler(time: number, { name = 'unknown' }: ForgetConfig, externalStackTrace?: string) {\n this.logger.error(`forget promise timeout out after ${time}ms [Cancelling] [${name}]`)\n if (externalStackTrace !== undefined) {\n this.logger.warn(`External Stack trace [${name}]:`, externalStackTrace)\n }\n }\n}\n","/// <reference types=\"node\" />\n\nimport type { Promisable } from '@xylabs/promise'\n\nimport { defaultForgetNodeConfig, type ForgetNodeConfig } from './ForgetNodeConfig.ts'\nimport { ForgetPromise } from './ForgetPromise.ts'\n\n/**\n * Node.js extension of ForgetPromise that can terminate the process on exceptions or timeouts.\n */\nexport class ForgetPromiseNode extends ForgetPromise {\n /** Handles exceptions, optionally terminating the process based on config. */\n static override exceptionHandler(error: Error, config: ForgetNodeConfig, externalStackTrace?: string) {\n // default | global | provided priorities for config (not deep merge)\n super.exceptionHandler(error, config, externalStackTrace)\n if (config?.terminateOnException === true) {\n this.logger.error(`Attempting to terminate process [${config?.name ?? 'unknown'}]...`)\n // eslint-disable-next-line unicorn/no-process-exit\n process.exit(1)\n }\n }\n\n /** Forgets a promise using Node.js-specific configuration with process termination support. */\n static override forget<T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>) {\n const resolvedConfig = {\n ...defaultForgetNodeConfig, ...globalThis.xy?.forget?.config, ...config,\n }\n super.forget(promise, resolvedConfig)\n }\n\n /** Handles timeouts, optionally terminating the process based on config. */\n static override timeoutHandler(time: number, config: ForgetNodeConfig, externalStackTrace?: string) {\n super.timeoutHandler(time, config, externalStackTrace)\n if (config?.terminateOnTimeout === true) {\n this.logger.error(`Attempting to terminate process [${config?.name ?? 'unknown'}]...`)\n // eslint-disable-next-line unicorn/no-process-exit\n process.exit(2)\n }\n }\n}\n","import { type Promisable } from '@xylabs/promise'\n\nimport type { ForgetNodeConfig } from './ForgetNodeConfig.ts'\nimport { ForgetPromiseNode } from './ForgetPromiseNode.ts'\n\n/**\n * Node.js variant of forget that can optionally terminate the process on exceptions or timeouts.\n * @param promise - The promise or promisable value to forget.\n * @param config - Optional Node.js-specific configuration including process termination options.\n */\nexport const forgetNode = <T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>) => {\n ForgetPromiseNode.forget<T>(promise, config)\n}\n"],"mappings":"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","names":[]}
package/dist/node/ForgetPromise.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"ForgetPromise.d.ts","sourceRoot":"","sources":["../../src/ForgetPromise.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAI5D,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAE1E,kDAAkD;AAClD,KAAK,kBAAkB,CAAC,CAAC,IAAI,MAAM,UAAU,CAAC,CAAC,CAAC,CAAA;AAEhD;;GAEG;AAEH,qBAAa,aAAa;IACxB,kEAAkE;IAClE,MAAM,CAAC,aAAa,SAAI;IACxB,0DAA0D;IAC1D,MAAM,CAAC,eAAe,SAAI;IAC1B,yDAAyD;IACzD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAU;IAE/B,uDAAuD;IACvD,MAAM,KAAK,MAAM,YAEhB;IAED;;;;;OAKG;WACU,aAAa,CAAC,QAAQ,SAAM,EAAE,OAAO,CAAC,EAAE,MAAM;IAc3D,2EAA2E;IAC3E,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,YAAY,EAAE,kBAAkB,CAAC,EAAE,MAAM;IAOzF;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC;IA+DzG,gFAAgF;IAChF,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAgB,EAAE,EAAE,YAAY,EAAE,kBAAkB,CAAC,EAAE,MAAM;CAMpG"}
1
+ {"version":3,"file":"ForgetPromise.d.ts","sourceRoot":"","sources":["../../src/ForgetPromise.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAC5C,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAG5D,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAE1E,kDAAkD;AAClD,KAAK,kBAAkB,CAAC,CAAC,IAAI,MAAM,UAAU,CAAC,CAAC,CAAC,CAAA;AAEhD;;GAEG;AAEH,qBAAa,aAAa;IACxB,kEAAkE;IAClE,MAAM,CAAC,aAAa,SAAI;IACxB,0DAA0D;IAC1D,MAAM,CAAC,eAAe,SAAI;IAC1B,yDAAyD;IACzD,MAAM,CAAC,MAAM,EAAE,MAAM,CAAU;IAE/B,uDAAuD;IACvD,MAAM,KAAK,MAAM,YAEhB;IAED;;;;;OAKG;WACU,aAAa,CAAC,QAAQ,SAAM,EAAE,OAAO,CAAC,EAAE,MAAM;IAc3D,2EAA2E;IAC3E,MAAM,CAAC,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,EAAE,YAAY,EAAE,kBAAkB,CAAC,EAAE,MAAM;IAOzF;;;;OAIG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,GAAG,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC;IA+DzG,gFAAgF;IAChF,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAgB,EAAE,EAAE,YAAY,EAAE,kBAAkB,CAAC,EAAE,MAAM;CAMpG"}
package/dist/node/index.mjs CHANGED
@@ -10,8 +10,7 @@ var defaultForgetNodeConfig = {
10
10
 
11
11
  // src/ForgetPromise.ts
12
12
  import { delay } from "@xylabs/delay";
13
- import { isPromise } from "@xylabs/promise";
14
- import { isNumber } from "@xylabs/typeof";
13
+ import { isNumber, isPromise } from "@xylabs/typeof";
15
14
  var ForgetPromise = class {
16
15
  /** Number of currently active (unresolved) forgotten promises. */
17
16
  static activeForgets = 0;
package/dist/node/index.mjs.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../../src/ForgetConfig.ts","../../src/ForgetNodeConfig.ts","../../src/ForgetPromise.ts","../../src/ForgetPromiseNode.ts","../../src/forgetNode.ts"],"sourcesContent":["/**\n * Configuration options for fire-and-forget promises.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface ForgetConfig<T = any> {\n /** Optional name for identifying the forgotten promise in logs. */\n name?: string\n /** Called when the promise is cancelled due to timeout. */\n onCancel?: () => void\n /** Called when the promise completes, with a tuple of [result, error]. */\n onComplete?: (result: [T | undefined, Error | undefined]) => void\n /** Called when an exception occurs outside the promise itself. */\n onException?: (error: Error) => void\n /** Timeout in milliseconds after which the promise is considered timed out. */\n timeout?: number\n}\n\n/** Default forget configuration with a 30-second timeout. */\nexport const defaultForgetConfig: ForgetConfig<unknown> = { timeout: 30_000 }\n","import { defaultForgetConfig, type ForgetConfig } from './ForgetConfig.ts'\n\n/**\n * Node.js-specific forget configuration that extends ForgetConfig with process termination options.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface ForgetNodeConfig<T = any> extends ForgetConfig<T> {\n /** Terminate the process on an exception that happens outside of the promise being forgotten. */\n terminateOnException?: boolean\n /** Terminate the process if the promise times out. */\n terminateOnTimeout?: boolean\n}\n\n/** Default Node.js forget configuration with termination disabled. */\nexport const defaultForgetNodeConfig: ForgetNodeConfig<unknown> = {\n ...defaultForgetConfig,\n terminateOnTimeout: false,\n terminateOnException: false,\n}\n","import { delay } from '@xylabs/delay'\nimport type { Logger } from '@xylabs/logger'\nimport type { Promisable, PromiseEx } from '@xylabs/promise'\nimport { isPromise } from '@xylabs/promise'\nimport { isNumber } from '@xylabs/typeof'\n\nimport { defaultForgetConfig, type ForgetConfig } from './ForgetConfig.ts'\n\n/** A function that returns a promisable value. */\ntype PromisableFunction<T> = () => Promisable<T>\n\n/**\n * Manages fire-and-forget promises with tracking, timeouts, and error handling.\n */\n// eslint-disable-next-line unicorn/no-static-only-class\nexport class ForgetPromise {\n /** Number of currently active (unresolved) forgotten promises. */\n static activeForgets = 0\n /** Number of forgotten promises that threw exceptions. */\n static exceptedForgets = 0\n /** Logger instance used for error and warning output. */\n static logger: Logger = console\n\n /** Whether any forgotten promises are still active. */\n static get active() {\n return this.activeForgets > 0\n }\n\n /**\n * Waits until all forgotten promises have completed.\n * @param interval - Polling interval in milliseconds.\n * @param timeout - Optional maximum wait time in milliseconds.\n * @returns The number of remaining active forgets (0 if all completed).\n */\n static async awaitInactive(interval = 100, timeout?: number) {\n let timeoutRemaining = timeout\n while (this.active) {\n await delay(interval)\n if (timeoutRemaining !== undefined) {\n timeoutRemaining -= interval\n if (timeoutRemaining <= 0) {\n return this.activeForgets\n }\n }\n }\n return 0\n }\n\n /** Handles exceptions from forgotten promises by logging error details. */\n static exceptionHandler(error: Error, { name }: ForgetConfig, externalStackTrace?: string) {\n this.logger.error(`forget promise handler excepted [${name}]: ${error.message}`, error)\n if (externalStackTrace !== undefined) {\n this.logger.warn(`External Stack trace [${name}]:`, externalStackTrace)\n }\n }\n\n /**\n * Used to explicitly launch an async function (or Promise) with awaiting it\n * @param promise The promise to forget\n * @param config Configuration of forget settings\n */\n static forget<T>(promise: Promise<T> | PromiseEx<T> | PromisableFunction<T> | T, config?: ForgetConfig<T>) {\n const externalStackTrace = (new Error('Stack')).stack\n\n // default | global | provided priorities for config (not deep merge)\n const resolvedConfig = {\n ...defaultForgetConfig, ...globalThis.xy?.forget?.config, ...config,\n }\n const resolvedPromise = typeof promise === 'function' ? (promise as PromisableFunction<T>)() : promise\n if (isPromise(resolvedPromise)) {\n try {\n let completed = false\n this.activeForgets++\n\n const promiseWrapper = async () => {\n await resolvedPromise\n .then((result: T) => {\n this.activeForgets--\n completed = true\n resolvedConfig?.onComplete?.([result, undefined])\n })\n .catch((error) => {\n this.activeForgets--\n completed = true\n this.logger.error(`forgotten promise excepted [${config?.name ?? 'unknown'}]: ${error.message}`, error)\n resolvedConfig?.onComplete?.([undefined, error])\n })\n }\n\n const promises = [promiseWrapper()]\n\n // if there is a timeout, add it to the race\n const timeout = resolvedConfig.timeout ?? defaultForgetConfig.timeout\n if (isNumber(timeout)) {\n const timeoutFunc = async () => {\n await delay(timeout)\n if (!completed) {\n resolvedConfig.onCancel?.()\n this.timeoutHandler(timeout, resolvedConfig, externalStackTrace)\n }\n }\n promises.push(timeoutFunc())\n }\n\n const all = Promise.race(promises)\n\n all\n .then(() => {\n return\n })\n .catch(() => {\n return\n })\n } catch (ex) {\n this.exceptedForgets += 1\n resolvedConfig?.onException?.(ex as Error)\n this.exceptionHandler(ex as Error, resolvedConfig, externalStackTrace)\n }\n } else {\n // we do nothing here since if it was a non-promise, it already got invoked.\n return\n }\n }\n\n /** Handles timeout events for forgotten promises by logging timeout details. */\n static timeoutHandler(time: number, { name = 'unknown' }: ForgetConfig, externalStackTrace?: string) {\n this.logger.error(`forget promise timeout out after ${time}ms [Cancelling] [${name}]`)\n if (externalStackTrace !== undefined) {\n this.logger.warn(`External Stack trace [${name}]:`, externalStackTrace)\n }\n }\n}\n","/// <reference types=\"node\" />\n\nimport type { Promisable } from '@xylabs/promise'\n\nimport { defaultForgetNodeConfig, type ForgetNodeConfig } from './ForgetNodeConfig.ts'\nimport { ForgetPromise } from './ForgetPromise.ts'\n\n/**\n * Node.js extension of ForgetPromise that can terminate the process on exceptions or timeouts.\n */\nexport class ForgetPromiseNode extends ForgetPromise {\n /** Handles exceptions, optionally terminating the process based on config. */\n static override exceptionHandler(error: Error, config: ForgetNodeConfig, externalStackTrace?: string) {\n // default | global | provided priorities for config (not deep merge)\n super.exceptionHandler(error, config, externalStackTrace)\n if (config?.terminateOnException === true) {\n this.logger.error(`Attempting to terminate process [${config?.name ?? 'unknown'}]...`)\n // eslint-disable-next-line unicorn/no-process-exit\n process.exit(1)\n }\n }\n\n /** Forgets a promise using Node.js-specific configuration with process termination support. */\n static override forget<T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>) {\n const resolvedConfig = {\n ...defaultForgetNodeConfig, ...globalThis.xy?.forget?.config, ...config,\n }\n super.forget(promise, resolvedConfig)\n }\n\n /** Handles timeouts, optionally terminating the process based on config. */\n static override timeoutHandler(time: number, config: ForgetNodeConfig, externalStackTrace?: string) {\n super.timeoutHandler(time, config, externalStackTrace)\n if (config?.terminateOnTimeout === true) {\n this.logger.error(`Attempting to terminate process [${config?.name ?? 'unknown'}]...`)\n // eslint-disable-next-line unicorn/no-process-exit\n process.exit(2)\n }\n }\n}\n","import { type Promisable } from '@xylabs/promise'\n\nimport type { ForgetNodeConfig } from './ForgetNodeConfig.ts'\nimport { ForgetPromiseNode } from './ForgetPromiseNode.ts'\n\n/**\n * Node.js variant of forget that can optionally terminate the process on exceptions or timeouts.\n * @param promise - The promise or promisable value to forget.\n * @param config - Optional Node.js-specific configuration including process termination options.\n */\nexport const forgetNode = <T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>) => {\n ForgetPromiseNode.forget<T>(promise, config)\n}\n"],"mappings":";AAkBO,IAAM,sBAA6C,EAAE,SAAS,IAAO;;;ACJrE,IAAM,0BAAqD;AAAA,EAChE,GAAG;AAAA,EACH,oBAAoB;AAAA,EACpB,sBAAsB;AACxB;;;AClBA,SAAS,aAAa;AAGtB,SAAS,iBAAiB;AAC1B,SAAS,gBAAgB;AAWlB,IAAM,gBAAN,MAAoB;AAAA;AAAA,EAEzB,OAAO,gBAAgB;AAAA;AAAA,EAEvB,OAAO,kBAAkB;AAAA;AAAA,EAEzB,OAAO,SAAiB;AAAA;AAAA,EAGxB,WAAW,SAAS;AAClB,WAAO,KAAK,gBAAgB;AAAA,EAC9B;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,aAAa,cAAc,WAAW,KAAK,SAAkB;AAC3D,QAAI,mBAAmB;AACvB,WAAO,KAAK,QAAQ;AAClB,YAAM,MAAM,QAAQ;AACpB,UAAI,qBAAqB,QAAW;AAClC,4BAAoB;AACpB,YAAI,oBAAoB,GAAG;AACzB,iBAAO,KAAK;AAAA,QACd;AAAA,MACF;AAAA,IACF;AACA,WAAO;AAAA,EACT;AAAA;AAAA,EAGA,OAAO,iBAAiB,OAAc,EAAE,KAAK,GAAiB,oBAA6B;AACzF,SAAK,OAAO,MAAM,oCAAoC,IAAI,MAAM,MAAM,OAAO,IAAI,KAAK;AACtF,QAAI,uBAAuB,QAAW;AACpC,WAAK,OAAO,KAAK,yBAAyB,IAAI,MAAM,kBAAkB;AAAA,IACxE;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,OAAO,OAAU,SAAgE,QAA0B;AACzG,UAAM,qBAAsB,IAAI,MAAM,OAAO,EAAG;AAGhD,UAAM,iBAAiB;AAAA,MACrB,GAAG;AAAA,MAAqB,GAAG,WAAW,IAAI,QAAQ;AAAA,MAAQ,GAAG;AAAA,IAC/D;AACA,UAAM,kBAAkB,OAAO,YAAY,aAAc,QAAkC,IAAI;AAC/F,QAAI,UAAU,eAAe,GAAG;AAC9B,UAAI;AACF,YAAI,YAAY;AAChB,aAAK;AAEL,cAAM,iBAAiB,YAAY;AACjC,gBAAM,gBACH,KAAK,CAAC,WAAc;AACnB,iBAAK;AACL,wBAAY;AACZ,4BAAgB,aAAa,CAAC,QAAQ,MAAS,CAAC;AAAA,UAClD,CAAC,EACA,MAAM,CAAC,UAAU;AAChB,iBAAK;AACL,wBAAY;AACZ,iBAAK,OAAO,MAAM,+BAA+B,QAAQ,QAAQ,SAAS,MAAM,MAAM,OAAO,IAAI,KAAK;AACtG,4BAAgB,aAAa,CAAC,QAAW,KAAK,CAAC;AAAA,UACjD,CAAC;AAAA,QACL;AAEA,cAAM,WAAW,CAAC,eAAe,CAAC;AAGlC,cAAM,UAAU,eAAe,WAAW,oBAAoB;AAC9D,YAAI,SAAS,OAAO,GAAG;AACrB,gBAAM,cAAc,YAAY;AAC9B,kBAAM,MAAM,OAAO;AACnB,gBAAI,CAAC,WAAW;AACd,6BAAe,WAAW;AAC1B,mBAAK,eAAe,SAAS,gBAAgB,kBAAkB;AAAA,YACjE;AAAA,UACF;AACA,mBAAS,KAAK,YAAY,CAAC;AAAA,QAC7B;AAEA,cAAM,MAAM,QAAQ,KAAK,QAAQ;AAEjC,YACG,KAAK,MAAM;AACV;AAAA,QACF,CAAC,EACA,MAAM,MAAM;AACX;AAAA,QACF,CAAC;AAAA,MACL,SAAS,IAAI;AACX,aAAK,mBAAmB;AACxB,wBAAgB,cAAc,EAAW;AACzC,aAAK,iBAAiB,IAAa,gBAAgB,kBAAkB;AAAA,MACvE;AAAA,IACF,OAAO;AAEL;AAAA,IACF;AAAA,EACF;AAAA;AAAA,EAGA,OAAO,eAAe,MAAc,EAAE,OAAO,UAAU,GAAiB,oBAA6B;AACnG,SAAK,OAAO,MAAM,oCAAoC,IAAI,oBAAoB,IAAI,GAAG;AACrF,QAAI,uBAAuB,QAAW;AACpC,WAAK,OAAO,KAAK,yBAAyB,IAAI,MAAM,kBAAkB;AAAA,IACxE;AAAA,EACF;AACF;;;ACzHO,IAAM,oBAAN,cAAgC,cAAc;AAAA;AAAA,EAEnD,OAAgB,iBAAiB,OAAc,QAA0B,oBAA6B;AAEpG,UAAM,iBAAiB,OAAO,QAAQ,kBAAkB;AACxD,QAAI,QAAQ,yBAAyB,MAAM;AACzC,WAAK,OAAO,MAAM,oCAAoC,QAAQ,QAAQ,SAAS,MAAM;AAErF,cAAQ,KAAK,CAAC;AAAA,IAChB;AAAA,EACF;AAAA;AAAA,EAGA,OAAgB,OAAU,SAAwB,QAA8B;AAC9E,UAAM,iBAAiB;AAAA,MACrB,GAAG;AAAA,MAAyB,GAAG,WAAW,IAAI,QAAQ;AAAA,MAAQ,GAAG;AAAA,IACnE;AACA,UAAM,OAAO,SAAS,cAAc;AAAA,EACtC;AAAA;AAAA,EAGA,OAAgB,eAAe,MAAc,QAA0B,oBAA6B;AAClG,UAAM,eAAe,MAAM,QAAQ,kBAAkB;AACrD,QAAI,QAAQ,uBAAuB,MAAM;AACvC,WAAK,OAAO,MAAM,oCAAoC,QAAQ,QAAQ,SAAS,MAAM;AAErF,cAAQ,KAAK,CAAC;AAAA,IAChB;AAAA,EACF;AACF;;;AC7BO,IAAM,aAAa,CAAI,SAAwB,WAAiC;AACrF,oBAAkB,OAAU,SAAS,MAAM;AAC7C;","names":[]}
1
+ {"version":3,"sources":["../../src/ForgetConfig.ts","../../src/ForgetNodeConfig.ts","../../src/ForgetPromise.ts","../../src/ForgetPromiseNode.ts","../../src/forgetNode.ts"],"sourcesContent":["/**\n * Configuration options for fire-and-forget promises.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface ForgetConfig<T = any> {\n /** Optional name for identifying the forgotten promise in logs. */\n name?: string\n /** Called when the promise is cancelled due to timeout. */\n onCancel?: () => void\n /** Called when the promise completes, with a tuple of [result, error]. */\n onComplete?: (result: [T | undefined, Error | undefined]) => void\n /** Called when an exception occurs outside the promise itself. */\n onException?: (error: Error) => void\n /** Timeout in milliseconds after which the promise is considered timed out. */\n timeout?: number\n}\n\n/** Default forget configuration with a 30-second timeout. */\nexport const defaultForgetConfig: ForgetConfig<unknown> = { timeout: 30_000 }\n","import { defaultForgetConfig, type ForgetConfig } from './ForgetConfig.ts'\n\n/**\n * Node.js-specific forget configuration that extends ForgetConfig with process termination options.\n */\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface ForgetNodeConfig<T = any> extends ForgetConfig<T> {\n /** Terminate the process on an exception that happens outside of the promise being forgotten. */\n terminateOnException?: boolean\n /** Terminate the process if the promise times out. */\n terminateOnTimeout?: boolean\n}\n\n/** Default Node.js forget configuration with termination disabled. */\nexport const defaultForgetNodeConfig: ForgetNodeConfig<unknown> = {\n ...defaultForgetConfig,\n terminateOnTimeout: false,\n terminateOnException: false,\n}\n","import { delay } from '@xylabs/delay'\nimport type { Logger } from '@xylabs/logger'\nimport type { Promisable, PromiseEx } from '@xylabs/promise'\nimport { isNumber, isPromise } from '@xylabs/typeof'\n\nimport { defaultForgetConfig, type ForgetConfig } from './ForgetConfig.ts'\n\n/** A function that returns a promisable value. */\ntype PromisableFunction<T> = () => Promisable<T>\n\n/**\n * Manages fire-and-forget promises with tracking, timeouts, and error handling.\n */\n// eslint-disable-next-line unicorn/no-static-only-class\nexport class ForgetPromise {\n /** Number of currently active (unresolved) forgotten promises. */\n static activeForgets = 0\n /** Number of forgotten promises that threw exceptions. */\n static exceptedForgets = 0\n /** Logger instance used for error and warning output. */\n static logger: Logger = console\n\n /** Whether any forgotten promises are still active. */\n static get active() {\n return this.activeForgets > 0\n }\n\n /**\n * Waits until all forgotten promises have completed.\n * @param interval - Polling interval in milliseconds.\n * @param timeout - Optional maximum wait time in milliseconds.\n * @returns The number of remaining active forgets (0 if all completed).\n */\n static async awaitInactive(interval = 100, timeout?: number) {\n let timeoutRemaining = timeout\n while (this.active) {\n await delay(interval)\n if (timeoutRemaining !== undefined) {\n timeoutRemaining -= interval\n if (timeoutRemaining <= 0) {\n return this.activeForgets\n }\n }\n }\n return 0\n }\n\n /** Handles exceptions from forgotten promises by logging error details. */\n static exceptionHandler(error: Error, { name }: ForgetConfig, externalStackTrace?: string) {\n this.logger.error(`forget promise handler excepted [${name}]: ${error.message}`, error)\n if (externalStackTrace !== undefined) {\n this.logger.warn(`External Stack trace [${name}]:`, externalStackTrace)\n }\n }\n\n /**\n * Used to explicitly launch an async function (or Promise) with awaiting it\n * @param promise The promise to forget\n * @param config Configuration of forget settings\n */\n static forget<T>(promise: Promise<T> | PromiseEx<T> | PromisableFunction<T> | T, config?: ForgetConfig<T>) {\n const externalStackTrace = (new Error('Stack')).stack\n\n // default | global | provided priorities for config (not deep merge)\n const resolvedConfig = {\n ...defaultForgetConfig, ...globalThis.xy?.forget?.config, ...config,\n }\n const resolvedPromise = typeof promise === 'function' ? (promise as PromisableFunction<T>)() : promise\n if (isPromise(resolvedPromise)) {\n try {\n let completed = false\n this.activeForgets++\n\n const promiseWrapper = async () => {\n await resolvedPromise\n .then((result: T) => {\n this.activeForgets--\n completed = true\n resolvedConfig?.onComplete?.([result, undefined])\n })\n .catch((error) => {\n this.activeForgets--\n completed = true\n this.logger.error(`forgotten promise excepted [${config?.name ?? 'unknown'}]: ${error.message}`, error)\n resolvedConfig?.onComplete?.([undefined, error])\n })\n }\n\n const promises = [promiseWrapper()]\n\n // if there is a timeout, add it to the race\n const timeout = resolvedConfig.timeout ?? defaultForgetConfig.timeout\n if (isNumber(timeout)) {\n const timeoutFunc = async () => {\n await delay(timeout)\n if (!completed) {\n resolvedConfig.onCancel?.()\n this.timeoutHandler(timeout, resolvedConfig, externalStackTrace)\n }\n }\n promises.push(timeoutFunc())\n }\n\n const all = Promise.race(promises)\n\n all\n .then(() => {\n return\n })\n .catch(() => {\n return\n })\n } catch (ex) {\n this.exceptedForgets += 1\n resolvedConfig?.onException?.(ex as Error)\n this.exceptionHandler(ex as Error, resolvedConfig, externalStackTrace)\n }\n } else {\n // we do nothing here since if it was a non-promise, it already got invoked.\n return\n }\n }\n\n /** Handles timeout events for forgotten promises by logging timeout details. */\n static timeoutHandler(time: number, { name = 'unknown' }: ForgetConfig, externalStackTrace?: string) {\n this.logger.error(`forget promise timeout out after ${time}ms [Cancelling] [${name}]`)\n if (externalStackTrace !== undefined) {\n this.logger.warn(`External Stack trace [${name}]:`, externalStackTrace)\n }\n }\n}\n","/// <reference types=\"node\" />\n\nimport type { Promisable } from '@xylabs/promise'\n\nimport { defaultForgetNodeConfig, type ForgetNodeConfig } from './ForgetNodeConfig.ts'\nimport { ForgetPromise } from './ForgetPromise.ts'\n\n/**\n * Node.js extension of ForgetPromise that can terminate the process on exceptions or timeouts.\n */\nexport class ForgetPromiseNode extends ForgetPromise {\n /** Handles exceptions, optionally terminating the process based on config. */\n static override exceptionHandler(error: Error, config: ForgetNodeConfig, externalStackTrace?: string) {\n // default | global | provided priorities for config (not deep merge)\n super.exceptionHandler(error, config, externalStackTrace)\n if (config?.terminateOnException === true) {\n this.logger.error(`Attempting to terminate process [${config?.name ?? 'unknown'}]...`)\n // eslint-disable-next-line unicorn/no-process-exit\n process.exit(1)\n }\n }\n\n /** Forgets a promise using Node.js-specific configuration with process termination support. */\n static override forget<T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>) {\n const resolvedConfig = {\n ...defaultForgetNodeConfig, ...globalThis.xy?.forget?.config, ...config,\n }\n super.forget(promise, resolvedConfig)\n }\n\n /** Handles timeouts, optionally terminating the process based on config. */\n static override timeoutHandler(time: number, config: ForgetNodeConfig, externalStackTrace?: string) {\n super.timeoutHandler(time, config, externalStackTrace)\n if (config?.terminateOnTimeout === true) {\n this.logger.error(`Attempting to terminate process [${config?.name ?? 'unknown'}]...`)\n // eslint-disable-next-line unicorn/no-process-exit\n process.exit(2)\n }\n }\n}\n","import { type Promisable } from '@xylabs/promise'\n\nimport type { ForgetNodeConfig } from './ForgetNodeConfig.ts'\nimport { ForgetPromiseNode } from './ForgetPromiseNode.ts'\n\n/**\n * Node.js variant of forget that can optionally terminate the process on exceptions or timeouts.\n * @param promise - The promise or promisable value to forget.\n * @param config - Optional Node.js-specific configuration including process termination options.\n */\nexport const forgetNode = <T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>) => {\n ForgetPromiseNode.forget<T>(promise, config)\n}\n"],"mappings":"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","names":[]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@xylabs/forget",
3
- "version": "5.0.94",
3
+ "version": "5.0.96",
4
4
  "description": "Base functionality used throughout XY Labs TypeScript/JavaScript libraries",
5
5
  "keywords": [
6
6
  "forget",
@@ -33,12 +33,10 @@
33
33
  "types": "./dist/node/index.d.ts",
34
34
  "default": "./dist/node/index.mjs"
35
35
  },
36
- "import": "./dist/node/index.mjs",
37
36
  "default": "./dist/node/index.mjs"
38
37
  },
39
38
  "./package.json": "./package.json"
40
39
  },
41
- "types": "./dist/node/index.d.ts",
42
40
  "files": [
43
41
  "dist",
44
42
  "!**/*.bench.*",
@@ -47,22 +45,20 @@
47
45
  "README.md"
48
46
  ],
49
47
  "dependencies": {
50
- "@xylabs/promise": "~5.0.94",
51
- "@xylabs/delay": "~5.0.94",
52
- "@xylabs/logger": "~5.0.94",
53
- "@xylabs/typeof": "~5.0.94"
48
+ "@xylabs/promise": "~5.0.96",
49
+ "@xylabs/logger": "~5.0.96",
50
+ "@xylabs/delay": "~5.0.96",
51
+ "@xylabs/typeof": "~5.0.96"
54
52
  },
55
53
  "devDependencies": {
56
- "@types/node": "^25.5.2",
57
- "@xylabs/ts-scripts-common": "~7.7.3",
58
- "@xylabs/ts-scripts-pnpm": "~7.7.3",
59
- "@xylabs/tsconfig": "~7.7.3",
60
- "@xylabs/tsconfig-dom": "~7.7.3",
61
- "acorn": "^6.0.0 || ^7.0.0 || ^8.0.0",
54
+ "@types/node": "^25.6.0",
55
+ "@xylabs/toolchain": "~7.10.4",
56
+ "@xylabs/tsconfig": "~7.10.4",
57
+ "@xylabs/tsconfig-dom": "~7.10.4",
62
58
  "esbuild": "^0.28.0",
63
59
  "typescript": "^5",
64
- "vite": "^6.0.0 || ^7.0.0 || ^8.0.0",
65
- "vitest": "^4.1.2"
60
+ "vite": "^8.0.8",
61
+ "vitest": "^4.1.4"
66
62
  },
67
63
  "engines": {
68
64
  "node": ">=18"