@xylabs/forget 5.0.83 → 5.0.86

package/README.md

@@ -15,6 +15,8 @@
 
 Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
+
+
 ## Reference
 
 **@xylabs/forget**
@@ -23,19 +25,27 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
 ## Classes
 
-- [ForgetPromise](#classes/ForgetPromise)
+| Class | Description |
+| ------ | ------ |
+| [ForgetPromise](#classes/ForgetPromise) | Node.js extension of ForgetPromise that can terminate the process on exceptions or timeouts. |
 
 ## Interfaces
 
-- [ForgetNodeConfig](#interfaces/ForgetNodeConfig)
+| Interface | Description |
+| ------ | ------ |
+| [ForgetNodeConfig](#interfaces/ForgetNodeConfig) | Node.js-specific forget configuration that extends ForgetConfig with process termination options. |
 
 ## Variables
 
-- [defaultForgetNodeConfig](#variables/defaultForgetNodeConfig)
+| Variable | Description |
+| ------ | ------ |
+| [defaultForgetNodeConfig](#variables/defaultForgetNodeConfig) | Default Node.js forget configuration with termination disabled. |
 
 ## Functions
 
-- [forget](#functions/forget)
+| Function | Description |
+| ------ | ------ |
+| [forget](#functions/forget) | Node.js variant of forget that can optionally terminate the process on exceptions or timeouts. |
 
 ### classes
 
@@ -45,6 +55,8 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
 ***
 
+Node.js extension of ForgetPromise that can terminate the process on exceptions or timeouts.
+
 ## Extends
 
 - `ForgetPromise`
@@ -69,45 +81,11 @@ ForgetPromise.constructor
 
 ## Properties
 
-### activeForgets
-
-```ts
-static activeForgets: number = 0;
-```
-
-### Inherited from
-
-```ts
-ForgetPromise.activeForgets
-```
-
-***
-
-### exceptedForgets
-
-```ts
-static exceptedForgets: number = 0;
-```
-
-### Inherited from
-
-```ts
-ForgetPromise.exceptedForgets
-```
-
-***
-
-### logger
-
-```ts
-static logger: Logger = console;
-```
-
-### Inherited from
-
-```ts
-ForgetPromise.logger
-```
+| Property | Modifier | Type | Default value | Description | Inherited from |
+| ------ | ------ | ------ | ------ | ------ | ------ |
+| <a id="activeforgets"></a> `activeForgets` | `static` | `number` | `0` | Number of currently active (unresolved) forgotten promises. | `ForgetPromise.activeForgets` |
+| <a id="exceptedforgets"></a> `exceptedForgets` | `static` | `number` | `0` | Number of forgotten promises that threw exceptions. | `ForgetPromise.exceptedForgets` |
+| <a id="logger"></a> `logger` | `static` | `Logger` | `console` | Logger instance used for error and warning output. | `ForgetPromise.logger` |
 
 ## Accessors
 
@@ -119,6 +97,8 @@ ForgetPromise.logger
 get static active(): boolean;
 ```
 
+Whether any forgotten promises are still active.
+
 #### Returns
 
 `boolean`
@@ -134,23 +114,24 @@ ForgetPromise.active
 ### awaitInactive()
 
 ```ts
-static awaitInactive(interval?, timeout?): Promise<number>;
+static awaitInactive(interval?: number, timeout?: number): Promise<number>;
 ```
 
-### Parameters
-
-#### interval?
+Waits until all forgotten promises have completed.
 
-`number` = `100`
-
-#### timeout?
+### Parameters
 
-`number`
+| Parameter | Type | Default value | Description |
+| ------ | ------ | ------ | ------ |
+| `interval` | `number` | `100` | Polling interval in milliseconds. |
+| `timeout?` | `number` | `undefined` | Optional maximum wait time in milliseconds. |
 
 ### Returns
 
 `Promise`\<`number`\>
 
+The number of remaining active forgets (0 if all completed).
+
 ### Inherited from
 
 ```ts
@@ -163,24 +144,20 @@ ForgetPromise.awaitInactive
 
 ```ts
 static exceptionHandler(
-   error, 
-   config, 
-   externalStackTrace?): void;
+   error: Error, 
+   config: ForgetNodeConfig, 
+   externalStackTrace?: string): void;
 ```
 
-### Parameters
-
-#### error
-
-`Error`
-
-#### config
+Handles exceptions, optionally terminating the process based on config.
 
-[`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig)
-
-#### externalStackTrace?
+### Parameters
 
-`string`
+| Parameter | Type |
+| ------ | ------ |
+| `error` | `Error` |
+| `config` | [`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig) |
+| `externalStackTrace?` | `string` |
 
 ### Returns
 
@@ -197,30 +174,23 @@ ForgetPromise.exceptionHandler
 ### forget()
 
 ```ts
-static forget<T>(promise, config?): void;
+static forget<T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>): void;
 ```
 
-Used to explicitly launch an async function (or Promise) with awaiting it
+Forgets a promise using Node.js-specific configuration with process termination support.
 
 ### Type Parameters
 
-#### T
-
-`T`
+| Type Parameter |
+| ------ |
+| `T` |
 
 ### Parameters
 
-#### promise
-
-`Promisable`\<`T`\>
-
-The promise to forget
-
-#### config?
-
-[`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig)\<`T`\>
-
-Configuration of forget settings
+| Parameter | Type |
+| ------ | ------ |
+| `promise` | `Promisable`\<`T`\> |
+| `config?` | [`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig)\<`T`\> |
 
 ### Returns
 
@@ -238,24 +208,20 @@ ForgetPromise.forget
 
 ```ts
 static timeoutHandler(
-   time, 
-   config, 
-   externalStackTrace?): void;
+   time: number, 
+   config: ForgetNodeConfig, 
+   externalStackTrace?: string): void;
 ```
 
-### Parameters
-
-#### time
+Handles timeouts, optionally terminating the process based on config.
 
-`number`
-
-#### config
-
-[`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig)
-
-#### externalStackTrace?
+### Parameters
 
-`string`
+| Parameter | Type |
+| ------ | ------ |
+| `time` | `number` |
+| `config` | [`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig) |
+| `externalStackTrace?` | `string` |
 
 ### Returns
 
@@ -276,24 +242,23 @@ ForgetPromise.timeoutHandler
 ***
 
 ```ts
-function forget<T>(promise, config?): void;
+function forget<T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>): void;
 ```
 
-## Type Parameters
+Node.js variant of forget that can optionally terminate the process on exceptions or timeouts.
 
-### T
+## Type Parameters
 
-`T`
+| Type Parameter |
+| ------ |
+| `T` |
 
 ## Parameters
 
-### promise
-
-`Promisable`\<`T`\>
-
-### config?
-
-[`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig)\<`T`\>
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `promise` | `Promisable`\<`T`\> | The promise or promisable value to forget. |
+| `config?` | [`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig)\<`T`\> | Optional Node.js-specific configuration including process termination options. |
 
 ## Returns
 
@@ -307,125 +272,29 @@ function forget<T>(promise, config?): void;
 
 ***
 
+Node.js-specific forget configuration that extends ForgetConfig with process termination options.
+
 ## Extends
 
 - `ForgetConfig`\<`T`\>
 
 ## Type Parameters
 
-### T
-
-`T` = `any`
+| Type Parameter | Default type |
+| ------ | ------ |
+| `T` | `any` |
 
 ## Properties
 
-### name?
-
-```ts
-optional name: string;
-```
-
-### Inherited from
-
-```ts
-ForgetConfig.name
-```
-
-***
-
-### onCancel()?
-
-```ts
-optional onCancel: () => void;
-```
-
-### Returns
-
-`void`
-
-### Inherited from
-
-```ts
-ForgetConfig.onCancel
-```
-
-***
-
-### onComplete()?
-
-```ts
-optional onComplete: (result) => void;
-```
-
-### Parameters
-
-#### result
-
-\[`T` \| `undefined`, `Error` \| `undefined`\]
-
-### Returns
-
-`void`
-
-### Inherited from
-
-```ts
-ForgetConfig.onComplete
-```
-
-***
-
-### onException()?
-
-```ts
-optional onException: (error) => void;
-```
-
-### Parameters
-
-#### error
-
-`Error`
-
-### Returns
-
-`void`
-
-### Inherited from
-
-```ts
-ForgetConfig.onException
-```
-
-***
-
-### timeout?
-
-```ts
-optional timeout: number;
-```
-
-### Inherited from
-
-```ts
-ForgetConfig.timeout
-```
-
-***
-
-### terminateOnException?
-
-```ts
-optional terminateOnException: boolean;
-```
-
-***
-
-### terminateOnTimeout?
-
-```ts
-optional terminateOnTimeout: boolean;
-```
+| Property | Type | Description | Inherited from |
+| ------ | ------ | ------ | ------ |
+| <a id="name"></a> `name?` | `string` | Optional name for identifying the forgotten promise in logs. | `ForgetConfig.name` |
+| <a id="oncancel"></a> `onCancel?` | () => `void` | Called when the promise is cancelled due to timeout. | `ForgetConfig.onCancel` |
+| <a id="oncomplete"></a> `onComplete?` | (`result`: \[`T` \| `undefined`, `Error` \| `undefined`\]) => `void` | Called when the promise completes, with a tuple of [result, error]. | `ForgetConfig.onComplete` |
+| <a id="onexception"></a> `onException?` | (`error`: `Error`) => `void` | Called when an exception occurs outside the promise itself. | `ForgetConfig.onException` |
+| <a id="timeout"></a> `timeout?` | `number` | Timeout in milliseconds after which the promise is considered timed out. | `ForgetConfig.timeout` |
+| <a id="terminateonexception"></a> `terminateOnException?` | `boolean` | Terminate the process on an exception that happens outside of the promise being forgotten. | - |
+| <a id="terminateontimeout"></a> `terminateOnTimeout?` | `boolean` | Terminate the process if the promise times out. | - |
 
 ### variables
 
@@ -439,6 +308,8 @@ optional terminateOnTimeout: boolean;
 const defaultForgetNodeConfig: ForgetNodeConfig<unknown>;
 ```
 
+Default Node.js forget configuration with termination disabled.
+
 
 Part of [sdk-js](https://www.npmjs.com/package/@xyo-network/sdk-js)
 

package/dist/neutral/ForgetConfig.d.ts

@@ -1,9 +1,18 @@
+/**
+ * Configuration options for fire-and-forget promises.
+ */
 export interface ForgetConfig<T = any> {
+    /** Optional name for identifying the forgotten promise in logs. */
     name?: string;
+    /** Called when the promise is cancelled due to timeout. */
     onCancel?: () => void;
+    /** Called when the promise completes, with a tuple of [result, error]. */
     onComplete?: (result: [T | undefined, Error | undefined]) => void;
+    /** Called when an exception occurs outside the promise itself. */
     onException?: (error: Error) => void;
+    /** Timeout in milliseconds after which the promise is considered timed out. */
     timeout?: number;
 }
+/** Default forget configuration with a 30-second timeout. */
 export declare const defaultForgetConfig: ForgetConfig<unknown>;
 //# sourceMappingURL=ForgetConfig.d.ts.map

package/dist/neutral/ForgetConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ForgetConfig.d.ts","sourceRoot":"","sources":["../../src/ForgetConfig.ts"],"names":[],"mappings":"AACA,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,GAAG;IACnC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,EAAE,KAAK,GAAG,SAAS,CAAC,KAAK,IAAI,CAAA;IACjE,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,eAAO,MAAM,mBAAmB,EAAE,YAAY,CAAC,OAAO,CAAuB,CAAA"}
+{"version":3,"file":"ForgetConfig.d.ts","sourceRoot":"","sources":["../../src/ForgetConfig.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,GAAG;IACnC,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,EAAE,KAAK,GAAG,SAAS,CAAC,KAAK,IAAI,CAAA;IACjE,kEAAkE;IAClE,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IACpC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,6DAA6D;AAC7D,eAAO,MAAM,mBAAmB,EAAE,YAAY,CAAC,OAAO,CAAuB,CAAA"}

package/dist/neutral/ForgetNodeConfig.d.ts

@@ -1,7 +1,13 @@
 import { type ForgetConfig } from './ForgetConfig.ts';
+/**
+ * Node.js-specific forget configuration that extends ForgetConfig with process termination options.
+ */
 export interface ForgetNodeConfig<T = any> extends ForgetConfig<T> {
+    /** Terminate the process on an exception that happens outside of the promise being forgotten. */
     terminateOnException?: boolean;
+    /** Terminate the process if the promise times out. */
     terminateOnTimeout?: boolean;
 }
+/** Default Node.js forget configuration with termination disabled. */
 export declare const defaultForgetNodeConfig: ForgetNodeConfig<unknown>;
 //# sourceMappingURL=ForgetNodeConfig.d.ts.map

package/dist/neutral/ForgetNodeConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ForgetNodeConfig.d.ts","sourceRoot":"","sources":["../../src/ForgetNodeConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAG1E,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,YAAY,CAAC,CAAC,CAAC;IAChE,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B;AAED,eAAO,MAAM,uBAAuB,EAAE,gBAAgB,CAAC,OAAO,CAI7D,CAAA"}
+{"version":3,"file":"ForgetNodeConfig.d.ts","sourceRoot":"","sources":["../../src/ForgetNodeConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAE1E;;GAEG;AAEH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,YAAY,CAAC,CAAC,CAAC;IAChE,iGAAiG;IACjG,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,sDAAsD;IACtD,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B;AAED,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,EAAE,gBAAgB,CAAC,OAAO,CAI7D,CAAA"}

package/dist/neutral/ForgetPromise.d.ts

@@ -1,13 +1,28 @@
 import type { Logger } from '@xylabs/logger';
 import type { Promisable, PromiseEx } from '@xylabs/promise';
 import { type ForgetConfig } from './ForgetConfig.ts';
+/** A function that returns a promisable value. */
 type PromisableFunction<T> = () => Promisable<T>;
+/**
+ * Manages fire-and-forget promises with tracking, timeouts, and error handling.
+ */
 export declare class ForgetPromise {
+    /** Number of currently active (unresolved) forgotten promises. */
     static activeForgets: number;
+    /** Number of forgotten promises that threw exceptions. */
     static exceptedForgets: number;
+    /** Logger instance used for error and warning output. */
     static logger: Logger;
+    /** Whether any forgotten promises are still active. */
     static get active(): boolean;
+    /**
+     * Waits until all forgotten promises have completed.
+     * @param interval - Polling interval in milliseconds.
+     * @param timeout - Optional maximum wait time in milliseconds.
+     * @returns The number of remaining active forgets (0 if all completed).
+     */
     static awaitInactive(interval?: number, timeout?: number): Promise<number>;
+    /** Handles exceptions from forgotten promises by logging error details. */
     static exceptionHandler(error: Error, { name }: ForgetConfig, externalStackTrace?: string): void;
     /**
      * Used to explicitly launch an async function (or Promise) with awaiting it
@@ -15,6 +30,7 @@ export declare class ForgetPromise {
      * @param config Configuration of forget settings
      */
     static forget<T>(promise: Promise<T> | PromiseEx<T> | PromisableFunction<T> | T, config?: ForgetConfig<T>): void;
+    /** Handles timeout events for forgotten promises by logging timeout details. */
     static timeoutHandler(time: number, { name }: ForgetConfig, externalStackTrace?: string): void;
 }
 export {};

package/dist/neutral/ForgetPromise.d.ts.map

@@ -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,KAAK,kBAAkB,CAAC,CAAC,IAAI,MAAM,UAAU,CAAC,CAAC,CAAC,CAAA;AAGhD,qBAAa,aAAa;IACxB,MAAM,CAAC,aAAa,SAAI;IACxB,MAAM,CAAC,eAAe,SAAI;IAC1B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAU;IAE/B,MAAM,KAAK,MAAM,YAEhB;WAEY,aAAa,CAAC,QAAQ,SAAM,EAAE,OAAO,CAAC,EAAE,MAAM;IAc3D,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,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAgB,EAAE,EAAE,YAAY,EAAE,kBAAkB,CAAC,EAAE,MAAM;CAMpG"}
+{"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"}

package/dist/neutral/ForgetPromiseNode.d.ts

@@ -1,9 +1,15 @@
 import type { Promisable } from '@xylabs/promise';
 import { type ForgetNodeConfig } from './ForgetNodeConfig.ts';
 import { ForgetPromise } from './ForgetPromise.ts';
+/**
+ * Node.js extension of ForgetPromise that can terminate the process on exceptions or timeouts.
+ */
 export declare class ForgetPromiseNode extends ForgetPromise {
+    /** Handles exceptions, optionally terminating the process based on config. */
     static exceptionHandler(error: Error, config: ForgetNodeConfig, externalStackTrace?: string): void;
+    /** Forgets a promise using Node.js-specific configuration with process termination support. */
     static forget<T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>): void;
+    /** Handles timeouts, optionally terminating the process based on config. */
     static timeoutHandler(time: number, config: ForgetNodeConfig, externalStackTrace?: string): void;
 }
 //# sourceMappingURL=ForgetPromiseNode.d.ts.map

package/dist/neutral/ForgetPromiseNode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ForgetPromiseNode.d.ts","sourceRoot":"","sources":["../../src/ForgetPromiseNode.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACtF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,qBAAa,iBAAkB,SAAQ,aAAa;WAClC,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,kBAAkB,CAAC,EAAE,MAAM;WAUpF,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC;WAO9D,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,kBAAkB,CAAC,EAAE,MAAM;CAQnG"}
+{"version":3,"file":"ForgetPromiseNode.d.ts","sourceRoot":"","sources":["../../src/ForgetPromiseNode.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACtF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,aAAa;IAClD,8EAA8E;WAC9D,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,kBAAkB,CAAC,EAAE,MAAM;IAUpG,+FAA+F;WAC/E,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAO9E,4EAA4E;WAC5D,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,kBAAkB,CAAC,EAAE,MAAM;CAQnG"}

package/dist/neutral/forget.d.ts

@@ -1,4 +1,9 @@
 import { type Promisable } from '@xylabs/promise';
 import type { ForgetConfig } from './ForgetConfig.ts';
+/**
+ * Explicitly launches an async function or promise without awaiting it (fire-and-forget).
+ * @param promise - The promise or promisable value to forget.
+ * @param config - Optional configuration for timeout, error handling, and completion callbacks.
+ */
 export declare const forget: <T>(promise: Promisable<T>, config?: ForgetConfig<T>) => void;
 //# sourceMappingURL=forget.d.ts.map

package/dist/neutral/forget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"forget.d.ts","sourceRoot":"","sources":["../../src/forget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIrD,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,SAEzE,CAAA"}
+{"version":3,"file":"forget.d.ts","sourceRoot":"","sources":["../../src/forget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGrD;;;;GAIG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,SAEzE,CAAA"}

package/dist/neutral/forgetNode.d.ts

@@ -1,4 +1,9 @@
 import { type Promisable } from '@xylabs/promise';
 import type { ForgetNodeConfig } from './ForgetNodeConfig.ts';
+/**
+ * Node.js variant of forget that can optionally terminate the process on exceptions or timeouts.
+ * @param promise - The promise or promisable value to forget.
+ * @param config - Optional Node.js-specific configuration including process termination options.
+ */
 export declare const forgetNode: <T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>) => void;
 //# sourceMappingURL=forgetNode.d.ts.map

package/dist/neutral/forgetNode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"forgetNode.d.ts","sourceRoot":"","sources":["../../src/forgetNode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAI7D,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,gBAAgB,CAAC,CAAC,CAAC,SAEjF,CAAA"}
+{"version":3,"file":"forgetNode.d.ts","sourceRoot":"","sources":["../../src/forgetNode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAG7D;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,gBAAgB,CAAC,CAAC,CAAC,SAEjF,CAAA"}

package/dist/neutral/index.mjs

@@ -13,12 +13,22 @@ import { delay } from "@xylabs/delay";
 import { isPromise } from "@xylabs/promise";
 import { isNumber } from "@xylabs/typeof";
 var ForgetPromise = class {
+  /** Number of currently active (unresolved) forgotten promises. */
   static activeForgets = 0;
+  /** Number of forgotten promises that threw exceptions. */
   static exceptedForgets = 0;
+  /** Logger instance used for error and warning output. */
   static logger = console;
+  /** Whether any forgotten promises are still active. */
   static get active() {
     return this.activeForgets > 0;
   }
+  /**
+   * Waits until all forgotten promises have completed.
+   * @param interval - Polling interval in milliseconds.
+   * @param timeout - Optional maximum wait time in milliseconds.
+   * @returns The number of remaining active forgets (0 if all completed).
+   */
   static async awaitInactive(interval = 100, timeout) {
     let timeoutRemaining = timeout;
     while (this.active) {
@@ -32,6 +42,7 @@ var ForgetPromise = class {
     }
     return 0;
   }
+  /** Handles exceptions from forgotten promises by logging error details. */
   static exceptionHandler(error, { name }, externalStackTrace) {
     this.logger.error(`forget promise handler excepted [${name}]: ${error.message}`, error);
     if (externalStackTrace !== void 0) {
@@ -94,6 +105,7 @@ var ForgetPromise = class {
       return;
     }
   }
+  /** Handles timeout events for forgotten promises by logging timeout details. */
   static timeoutHandler(time, { name = "unknown" }, externalStackTrace) {
     this.logger.error(`forget promise timeout out after ${time}ms [Cancelling] [${name}]`);
     if (externalStackTrace !== void 0) {
@@ -104,6 +116,7 @@ var ForgetPromise = class {
 
 // src/ForgetPromiseNode.ts
 var ForgetPromiseNode = class extends ForgetPromise {
+  /** Handles exceptions, optionally terminating the process based on config. */
   static exceptionHandler(error, config, externalStackTrace) {
     super.exceptionHandler(error, config, externalStackTrace);
     if (config?.terminateOnException === true) {
@@ -111,6 +124,7 @@ var ForgetPromiseNode = class extends ForgetPromise {
       process.exit(1);
     }
   }
+  /** Forgets a promise using Node.js-specific configuration with process termination support. */
   static forget(promise, config) {
     const resolvedConfig = {
       ...defaultForgetNodeConfig,
@@ -119,6 +133,7 @@ var ForgetPromiseNode = class extends ForgetPromise {
     };
     super.forget(promise, resolvedConfig);
   }
+  /** Handles timeouts, optionally terminating the process based on config. */
   static timeoutHandler(time, config, externalStackTrace) {
     super.timeoutHandler(time, config, externalStackTrace);
     if (config?.terminateOnTimeout === true) {

package/dist/neutral/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/ForgetConfig.ts","../../src/ForgetNodeConfig.ts","../../src/ForgetPromise.ts","../../src/ForgetPromiseNode.ts","../../src/forgetNode.ts"],"sourcesContent":["// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface ForgetConfig<T = any> {\n  name?: string\n  onCancel?: () => void\n  onComplete?: (result: [T | undefined, Error | undefined]) => void\n  onException?: (error: Error) => void\n  timeout?: number\n}\n\nexport const defaultForgetConfig: ForgetConfig<unknown> = { timeout: 30_000 }\n","import { defaultForgetConfig, type ForgetConfig } from './ForgetConfig.ts'\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface ForgetNodeConfig<T = any> extends ForgetConfig<T> {\n  terminateOnException?: boolean // terminate the process on an exception that happens outside of the promise being forgotten\n  terminateOnTimeout?: boolean // terminate the process if the promise times out\n}\n\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\ntype PromisableFunction<T> = () => Promisable<T>\n\n// eslint-disable-next-line unicorn/no-static-only-class\nexport class ForgetPromise {\n  static activeForgets = 0\n  static exceptedForgets = 0\n  static logger: Logger = console\n\n  static get active() {\n    return this.activeForgets > 0\n  }\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  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  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\nexport class ForgetPromiseNode extends ForgetPromise {\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  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  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// used to explicitly launch an async function (or Promise) with awaiting it\nexport const forgetNode = <T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>) => {\n  ForgetPromiseNode.forget<T>(promise, config)\n}\n"],"mappings":"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","names":[]}
+{"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":[]}

package/dist/node/ForgetConfig.d.ts

@@ -1,9 +1,18 @@
+/**
+ * Configuration options for fire-and-forget promises.
+ */
 export interface ForgetConfig<T = any> {
+    /** Optional name for identifying the forgotten promise in logs. */
     name?: string;
+    /** Called when the promise is cancelled due to timeout. */
     onCancel?: () => void;
+    /** Called when the promise completes, with a tuple of [result, error]. */
     onComplete?: (result: [T | undefined, Error | undefined]) => void;
+    /** Called when an exception occurs outside the promise itself. */
     onException?: (error: Error) => void;
+    /** Timeout in milliseconds after which the promise is considered timed out. */
     timeout?: number;
 }
+/** Default forget configuration with a 30-second timeout. */
 export declare const defaultForgetConfig: ForgetConfig<unknown>;
 //# sourceMappingURL=ForgetConfig.d.ts.map

package/dist/node/ForgetConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ForgetConfig.d.ts","sourceRoot":"","sources":["../../src/ForgetConfig.ts"],"names":[],"mappings":"AACA,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,GAAG;IACnC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,EAAE,KAAK,GAAG,SAAS,CAAC,KAAK,IAAI,CAAA;IACjE,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,eAAO,MAAM,mBAAmB,EAAE,YAAY,CAAC,OAAO,CAAuB,CAAA"}
+{"version":3,"file":"ForgetConfig.d.ts","sourceRoot":"","sources":["../../src/ForgetConfig.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,YAAY,CAAC,CAAC,GAAG,GAAG;IACnC,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,IAAI,CAAA;IACrB,0EAA0E;IAC1E,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,GAAG,SAAS,EAAE,KAAK,GAAG,SAAS,CAAC,KAAK,IAAI,CAAA;IACjE,kEAAkE;IAClE,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IACpC,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,6DAA6D;AAC7D,eAAO,MAAM,mBAAmB,EAAE,YAAY,CAAC,OAAO,CAAuB,CAAA"}

package/dist/node/ForgetNodeConfig.d.ts

@@ -1,7 +1,13 @@
 import { type ForgetConfig } from './ForgetConfig.ts';
+/**
+ * Node.js-specific forget configuration that extends ForgetConfig with process termination options.
+ */
 export interface ForgetNodeConfig<T = any> extends ForgetConfig<T> {
+    /** Terminate the process on an exception that happens outside of the promise being forgotten. */
     terminateOnException?: boolean;
+    /** Terminate the process if the promise times out. */
     terminateOnTimeout?: boolean;
 }
+/** Default Node.js forget configuration with termination disabled. */
 export declare const defaultForgetNodeConfig: ForgetNodeConfig<unknown>;
 //# sourceMappingURL=ForgetNodeConfig.d.ts.map

package/dist/node/ForgetNodeConfig.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ForgetNodeConfig.d.ts","sourceRoot":"","sources":["../../src/ForgetNodeConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAG1E,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,YAAY,CAAC,CAAC,CAAC;IAChE,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B;AAED,eAAO,MAAM,uBAAuB,EAAE,gBAAgB,CAAC,OAAO,CAI7D,CAAA"}
+{"version":3,"file":"ForgetNodeConfig.d.ts","sourceRoot":"","sources":["../../src/ForgetNodeConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAE1E;;GAEG;AAEH,MAAM,WAAW,gBAAgB,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,YAAY,CAAC,CAAC,CAAC;IAChE,iGAAiG;IACjG,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,sDAAsD;IACtD,kBAAkB,CAAC,EAAE,OAAO,CAAA;CAC7B;AAED,sEAAsE;AACtE,eAAO,MAAM,uBAAuB,EAAE,gBAAgB,CAAC,OAAO,CAI7D,CAAA"}

package/dist/node/ForgetPromise.d.ts

@@ -1,13 +1,28 @@
 import type { Logger } from '@xylabs/logger';
 import type { Promisable, PromiseEx } from '@xylabs/promise';
 import { type ForgetConfig } from './ForgetConfig.ts';
+/** A function that returns a promisable value. */
 type PromisableFunction<T> = () => Promisable<T>;
+/**
+ * Manages fire-and-forget promises with tracking, timeouts, and error handling.
+ */
 export declare class ForgetPromise {
+    /** Number of currently active (unresolved) forgotten promises. */
     static activeForgets: number;
+    /** Number of forgotten promises that threw exceptions. */
     static exceptedForgets: number;
+    /** Logger instance used for error and warning output. */
     static logger: Logger;
+    /** Whether any forgotten promises are still active. */
     static get active(): boolean;
+    /**
+     * Waits until all forgotten promises have completed.
+     * @param interval - Polling interval in milliseconds.
+     * @param timeout - Optional maximum wait time in milliseconds.
+     * @returns The number of remaining active forgets (0 if all completed).
+     */
     static awaitInactive(interval?: number, timeout?: number): Promise<number>;
+    /** Handles exceptions from forgotten promises by logging error details. */
     static exceptionHandler(error: Error, { name }: ForgetConfig, externalStackTrace?: string): void;
     /**
      * Used to explicitly launch an async function (or Promise) with awaiting it
@@ -15,6 +30,7 @@ export declare class ForgetPromise {
      * @param config Configuration of forget settings
      */
     static forget<T>(promise: Promise<T> | PromiseEx<T> | PromisableFunction<T> | T, config?: ForgetConfig<T>): void;
+    /** Handles timeout events for forgotten promises by logging timeout details. */
     static timeoutHandler(time: number, { name }: ForgetConfig, externalStackTrace?: string): void;
 }
 export {};

package/dist/node/ForgetPromise.d.ts.map

@@ -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,KAAK,kBAAkB,CAAC,CAAC,IAAI,MAAM,UAAU,CAAC,CAAC,CAAC,CAAA;AAGhD,qBAAa,aAAa;IACxB,MAAM,CAAC,aAAa,SAAI;IACxB,MAAM,CAAC,eAAe,SAAI;IAC1B,MAAM,CAAC,MAAM,EAAE,MAAM,CAAU;IAE/B,MAAM,KAAK,MAAM,YAEhB;WAEY,aAAa,CAAC,QAAQ,SAAM,EAAE,OAAO,CAAC,EAAE,MAAM;IAc3D,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,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAgB,EAAE,EAAE,YAAY,EAAE,kBAAkB,CAAC,EAAE,MAAM;CAMpG"}
+{"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"}

package/dist/node/ForgetPromiseNode.d.ts

@@ -1,9 +1,15 @@
 import type { Promisable } from '@xylabs/promise';
 import { type ForgetNodeConfig } from './ForgetNodeConfig.ts';
 import { ForgetPromise } from './ForgetPromise.ts';
+/**
+ * Node.js extension of ForgetPromise that can terminate the process on exceptions or timeouts.
+ */
 export declare class ForgetPromiseNode extends ForgetPromise {
+    /** Handles exceptions, optionally terminating the process based on config. */
     static exceptionHandler(error: Error, config: ForgetNodeConfig, externalStackTrace?: string): void;
+    /** Forgets a promise using Node.js-specific configuration with process termination support. */
     static forget<T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>): void;
+    /** Handles timeouts, optionally terminating the process based on config. */
     static timeoutHandler(time: number, config: ForgetNodeConfig, externalStackTrace?: string): void;
 }
 //# sourceMappingURL=ForgetPromiseNode.d.ts.map

package/dist/node/ForgetPromiseNode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ForgetPromiseNode.d.ts","sourceRoot":"","sources":["../../src/ForgetPromiseNode.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACtF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD,qBAAa,iBAAkB,SAAQ,aAAa;WAClC,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,kBAAkB,CAAC,EAAE,MAAM;WAUpF,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC;WAO9D,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,kBAAkB,CAAC,EAAE,MAAM;CAQnG"}
+{"version":3,"file":"ForgetPromiseNode.d.ts","sourceRoot":"","sources":["../../src/ForgetPromiseNode.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,EAA2B,KAAK,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AACtF,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAA;AAElD;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,aAAa;IAClD,8EAA8E;WAC9D,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,gBAAgB,EAAE,kBAAkB,CAAC,EAAE,MAAM;IAUpG,+FAA+F;WAC/E,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAO9E,4EAA4E;WAC5D,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,kBAAkB,CAAC,EAAE,MAAM;CAQnG"}

package/dist/node/forget.d.ts

@@ -1,4 +1,9 @@
 import { type Promisable } from '@xylabs/promise';
 import type { ForgetConfig } from './ForgetConfig.ts';
+/**
+ * Explicitly launches an async function or promise without awaiting it (fire-and-forget).
+ * @param promise - The promise or promisable value to forget.
+ * @param config - Optional configuration for timeout, error handling, and completion callbacks.
+ */
 export declare const forget: <T>(promise: Promisable<T>, config?: ForgetConfig<T>) => void;
 //# sourceMappingURL=forget.d.ts.map

package/dist/node/forget.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"forget.d.ts","sourceRoot":"","sources":["../../src/forget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAIrD,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,SAEzE,CAAA"}
+{"version":3,"file":"forget.d.ts","sourceRoot":"","sources":["../../src/forget.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAGrD;;;;GAIG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,SAEzE,CAAA"}

package/dist/node/forgetNode.d.ts

@@ -1,4 +1,9 @@
 import { type Promisable } from '@xylabs/promise';
 import type { ForgetNodeConfig } from './ForgetNodeConfig.ts';
+/**
+ * Node.js variant of forget that can optionally terminate the process on exceptions or timeouts.
+ * @param promise - The promise or promisable value to forget.
+ * @param config - Optional Node.js-specific configuration including process termination options.
+ */
 export declare const forgetNode: <T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>) => void;
 //# sourceMappingURL=forgetNode.d.ts.map

package/dist/node/forgetNode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"forgetNode.d.ts","sourceRoot":"","sources":["../../src/forgetNode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAI7D,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,gBAAgB,CAAC,CAAC,CAAC,SAEjF,CAAA"}
+{"version":3,"file":"forgetNode.d.ts","sourceRoot":"","sources":["../../src/forgetNode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAG7D;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,SAAS,UAAU,CAAC,CAAC,CAAC,EAAE,SAAS,gBAAgB,CAAC,CAAC,CAAC,SAEjF,CAAA"}

package/dist/node/index.mjs

@@ -13,12 +13,22 @@ import { delay } from "@xylabs/delay";
 import { isPromise } from "@xylabs/promise";
 import { isNumber } from "@xylabs/typeof";
 var ForgetPromise = class {
+  /** Number of currently active (unresolved) forgotten promises. */
   static activeForgets = 0;
+  /** Number of forgotten promises that threw exceptions. */
   static exceptedForgets = 0;
+  /** Logger instance used for error and warning output. */
   static logger = console;
+  /** Whether any forgotten promises are still active. */
   static get active() {
     return this.activeForgets > 0;
   }
+  /**
+   * Waits until all forgotten promises have completed.
+   * @param interval - Polling interval in milliseconds.
+   * @param timeout - Optional maximum wait time in milliseconds.
+   * @returns The number of remaining active forgets (0 if all completed).
+   */
   static async awaitInactive(interval = 100, timeout) {
     let timeoutRemaining = timeout;
     while (this.active) {
@@ -32,6 +42,7 @@ var ForgetPromise = class {
     }
     return 0;
   }
+  /** Handles exceptions from forgotten promises by logging error details. */
   static exceptionHandler(error, { name }, externalStackTrace) {
     this.logger.error(`forget promise handler excepted [${name}]: ${error.message}`, error);
     if (externalStackTrace !== void 0) {
@@ -94,6 +105,7 @@ var ForgetPromise = class {
       return;
     }
   }
+  /** Handles timeout events for forgotten promises by logging timeout details. */
   static timeoutHandler(time, { name = "unknown" }, externalStackTrace) {
     this.logger.error(`forget promise timeout out after ${time}ms [Cancelling] [${name}]`);
     if (externalStackTrace !== void 0) {
@@ -104,6 +116,7 @@ var ForgetPromise = class {
 
 // src/ForgetPromiseNode.ts
 var ForgetPromiseNode = class extends ForgetPromise {
+  /** Handles exceptions, optionally terminating the process based on config. */
   static exceptionHandler(error, config, externalStackTrace) {
     super.exceptionHandler(error, config, externalStackTrace);
     if (config?.terminateOnException === true) {
@@ -111,6 +124,7 @@ var ForgetPromiseNode = class extends ForgetPromise {
       process.exit(1);
     }
   }
+  /** Forgets a promise using Node.js-specific configuration with process termination support. */
   static forget(promise, config) {
     const resolvedConfig = {
       ...defaultForgetNodeConfig,
@@ -119,6 +133,7 @@ var ForgetPromiseNode = class extends ForgetPromise {
     };
     super.forget(promise, resolvedConfig);
   }
+  /** Handles timeouts, optionally terminating the process based on config. */
   static timeoutHandler(time, config, externalStackTrace) {
     super.timeoutHandler(time, config, externalStackTrace);
     if (config?.terminateOnTimeout === true) {

package/dist/node/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/ForgetConfig.ts","../../src/ForgetNodeConfig.ts","../../src/ForgetPromise.ts","../../src/ForgetPromiseNode.ts","../../src/forgetNode.ts"],"sourcesContent":["// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface ForgetConfig<T = any> {\n  name?: string\n  onCancel?: () => void\n  onComplete?: (result: [T | undefined, Error | undefined]) => void\n  onException?: (error: Error) => void\n  timeout?: number\n}\n\nexport const defaultForgetConfig: ForgetConfig<unknown> = { timeout: 30_000 }\n","import { defaultForgetConfig, type ForgetConfig } from './ForgetConfig.ts'\n\n// eslint-disable-next-line @typescript-eslint/no-explicit-any\nexport interface ForgetNodeConfig<T = any> extends ForgetConfig<T> {\n  terminateOnException?: boolean // terminate the process on an exception that happens outside of the promise being forgotten\n  terminateOnTimeout?: boolean // terminate the process if the promise times out\n}\n\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\ntype PromisableFunction<T> = () => Promisable<T>\n\n// eslint-disable-next-line unicorn/no-static-only-class\nexport class ForgetPromise {\n  static activeForgets = 0\n  static exceptedForgets = 0\n  static logger: Logger = console\n\n  static get active() {\n    return this.activeForgets > 0\n  }\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  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  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\nexport class ForgetPromiseNode extends ForgetPromise {\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  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  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// used to explicitly launch an async function (or Promise) with awaiting it\nexport const forgetNode = <T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>) => {\n  ForgetPromiseNode.forget<T>(promise, config)\n}\n"],"mappings":"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","names":[]}
+{"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":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/forget",
-  "version": "5.0.83",
+  "version": "5.0.86",
   "description": "Base functionality used throughout XY Labs TypeScript/JavaScript libraries",
   "keywords": [
     "forget",
@@ -46,15 +46,15 @@
     "!**/*.test.*"
   ],
   "dependencies": {
-    "@xylabs/delay": "~5.0.83",
-    "@xylabs/logger": "~5.0.83",
-    "@xylabs/promise": "~5.0.83",
-    "@xylabs/typeof": "~5.0.83"
+    "@xylabs/delay": "~5.0.86",
+    "@xylabs/logger": "~5.0.86",
+    "@xylabs/promise": "~5.0.86",
+    "@xylabs/typeof": "~5.0.86"
   },
   "devDependencies": {
-    "@xylabs/ts-scripts-yarn3": "~7.4.11",
-    "@xylabs/tsconfig": "~7.4.11",
-    "@xylabs/tsconfig-dom": "~7.4.11",
+    "@xylabs/ts-scripts-yarn3": "~7.4.16",
+    "@xylabs/tsconfig": "~7.4.16",
+    "@xylabs/tsconfig-dom": "~7.4.16",
     "typescript": "~5.9.3",
     "vitest": "~4.0.18"
   },