@xylabs/forget 5.0.80 → 5.0.81

package/README.md

@@ -17,7 +17,428 @@ Base functionality used throughout XY Labs TypeScript/JavaScript libraries
 
 ## Reference
 
-Reference generation failed.
+**@xylabs/forget**
+
+***
+
+## Classes
+
+- [ForgetPromise](#classes/ForgetPromise)
+
+## Interfaces
+
+- [ForgetNodeConfig](#interfaces/ForgetNodeConfig)
+
+## Variables
+
+- [defaultForgetNodeConfig](#variables/defaultForgetNodeConfig)
+
+## Functions
+
+- [forget](#functions/forget)
+
+### classes
+
+  ### <a id="ForgetPromise"></a>ForgetPromise
+
+[**@xylabs/forget**](#../README)
+
+***
+
+## Extends
+
+- `ForgetPromise`
+
+## Constructors
+
+### Constructor
+
+```ts
+new ForgetPromise(): ForgetPromiseNode;
+```
+
+### Returns
+
+`ForgetPromiseNode`
+
+### Inherited from
+
+```ts
+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
+```
+
+## Accessors
+
+### active
+
+### Get Signature
+
+```ts
+get static active(): boolean;
+```
+
+#### Returns
+
+`boolean`
+
+### Inherited from
+
+```ts
+ForgetPromise.active
+```
+
+## Methods
+
+### awaitInactive()
+
+```ts
+static awaitInactive(interval?, timeout?): Promise<number>;
+```
+
+### Parameters
+
+#### interval?
+
+`number` = `100`
+
+#### timeout?
+
+`number`
+
+### Returns
+
+`Promise`\<`number`\>
+
+### Inherited from
+
+```ts
+ForgetPromise.awaitInactive
+```
+
+***
+
+### exceptionHandler()
+
+```ts
+static exceptionHandler(
+   error, 
+   config, 
+   externalStackTrace?): void;
+```
+
+### Parameters
+
+#### error
+
+`Error`
+
+#### config
+
+[`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig)
+
+#### externalStackTrace?
+
+`string`
+
+### Returns
+
+`void`
+
+### Overrides
+
+```ts
+ForgetPromise.exceptionHandler
+```
+
+***
+
+### forget()
+
+```ts
+static forget<T>(promise, config?): void;
+```
+
+Used to explicitly launch an async function (or Promise) with awaiting it
+
+### Type Parameters
+
+#### T
+
+`T`
+
+### Parameters
+
+#### promise
+
+`Promisable`\<`T`\>
+
+The promise to forget
+
+#### config?
+
+[`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig)\<`T`\>
+
+Configuration of forget settings
+
+### Returns
+
+`void`
+
+### Overrides
+
+```ts
+ForgetPromise.forget
+```
+
+***
+
+### timeoutHandler()
+
+```ts
+static timeoutHandler(
+   time, 
+   config, 
+   externalStackTrace?): void;
+```
+
+### Parameters
+
+#### time
+
+`number`
+
+#### config
+
+[`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig)
+
+#### externalStackTrace?
+
+`string`
+
+### Returns
+
+`void`
+
+### Overrides
+
+```ts
+ForgetPromise.timeoutHandler
+```
+
+### functions
+
+  ### <a id="forget"></a>forget
+
+[**@xylabs/forget**](#../README)
+
+***
+
+```ts
+function forget<T>(promise, config?): void;
+```
+
+## Type Parameters
+
+### T
+
+`T`
+
+## Parameters
+
+### promise
+
+`Promisable`\<`T`\>
+
+### config?
+
+[`ForgetNodeConfig`](#../interfaces/ForgetNodeConfig)\<`T`\>
+
+## Returns
+
+`void`
+
+### interfaces
+
+  ### <a id="ForgetNodeConfig"></a>ForgetNodeConfig
+
+[**@xylabs/forget**](#../README)
+
+***
+
+## Extends
+
+- `ForgetConfig`\<`T`\>
+
+## Type Parameters
+
+### T
+
+`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;
+```
+
+### variables
+
+  ### <a id="defaultForgetNodeConfig"></a>defaultForgetNodeConfig
+
+[**@xylabs/forget**](#../README)
+
+***
+
+```ts
+const defaultForgetNodeConfig: ForgetNodeConfig<unknown>;
+```
+
 
 Part of [sdk-js](https://www.npmjs.com/package/@xyo-network/sdk-js)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xylabs/forget",
-  "version": "5.0.80",
+  "version": "5.0.81",
   "description": "Base functionality used throughout XY Labs TypeScript/JavaScript libraries",
   "keywords": [
     "forget",
@@ -31,33 +31,30 @@
       "types": "./dist/node/index.d.ts",
       "node": {
         "types": "./dist/node/index.d.ts",
-        "source": "./src/node/index.ts",
         "default": "./dist/node/index.mjs"
       },
-      "source": "./src/node/index.ts",
       "default": "./dist/node/index.mjs"
     },
     "./package.json": "./package.json"
   },
   "module": "./dist/node/index.mjs",
-  "source": "./src/node/index.ts",
   "types": "./dist/node/index.d.ts",
   "files": [
     "dist",
-    "src",
     "!**/*.bench.*",
     "!**/*.spec.*",
     "!**/*.test.*"
   ],
   "dependencies": {
-    "@xylabs/delay": "~5.0.80",
-    "@xylabs/logger": "~5.0.80",
-    "@xylabs/promise": "~5.0.80",
-    "@xylabs/typeof": "~5.0.80"
+    "@xylabs/delay": "~5.0.81",
+    "@xylabs/logger": "~5.0.81",
+    "@xylabs/promise": "~5.0.81",
+    "@xylabs/typeof": "~5.0.81"
   },
   "devDependencies": {
-    "@xylabs/ts-scripts-yarn3": "~7.3.2",
-    "@xylabs/tsconfig-dom": "~7.3.2",
+    "@xylabs/ts-scripts-yarn3": "~7.4.11",
+    "@xylabs/tsconfig": "~7.4.11",
+    "@xylabs/tsconfig-dom": "~7.4.11",
     "typescript": "~5.9.3",
     "vitest": "~4.0.18"
   },

package/src/ForgetConfig.ts

@@ -1,10 +0,0 @@
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export interface ForgetConfig<T = any> {
-  name?: string
-  onCancel?: () => void
-  onComplete?: (result: [T | undefined, Error | undefined]) => void
-  onException?: (error: Error) => void
-  timeout?: number
-}
-
-export const defaultForgetConfig: ForgetConfig<unknown> = { timeout: 30_000 }

package/src/ForgetNodeConfig.ts

@@ -1,13 +0,0 @@
-import { defaultForgetConfig, type ForgetConfig } from './ForgetConfig.ts'
-
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-export interface ForgetNodeConfig<T = any> extends ForgetConfig<T> {
-  terminateOnException?: boolean // terminate the process on an exception that happens outside of the promise being forgotten
-  terminateOnTimeout?: boolean // terminate the process if the promise times out
-}
-
-export const defaultForgetNodeConfig: ForgetNodeConfig<unknown> = {
-  ...defaultForgetConfig,
-  terminateOnTimeout: false,
-  terminateOnException: false,
-}

package/src/ForgetPromise.ts

@@ -1,116 +0,0 @@
-import { delay } from '@xylabs/delay'
-import type { Logger } from '@xylabs/logger'
-import type { Promisable, PromiseEx } from '@xylabs/promise'
-import { isPromise } from '@xylabs/promise'
-import { isNumber } from '@xylabs/typeof'
-
-import { defaultForgetConfig, type ForgetConfig } from './ForgetConfig.ts'
-
-type PromisableFunction<T> = () => Promisable<T>
-
-// eslint-disable-next-line unicorn/no-static-only-class
-export class ForgetPromise {
-  static activeForgets = 0
-  static exceptedForgets = 0
-  static logger: Logger = console
-
-  static get active() {
-    return this.activeForgets > 0
-  }
-
-  static async awaitInactive(interval = 100, timeout?: number) {
-    let timeoutRemaining = timeout
-    while (this.active) {
-      await delay(interval)
-      if (timeoutRemaining !== undefined) {
-        timeoutRemaining -= interval
-        if (timeoutRemaining <= 0) {
-          return this.activeForgets
-        }
-      }
-    }
-    return 0
-  }
-
-  static exceptionHandler(error: Error, { name }: ForgetConfig, externalStackTrace?: string) {
-    this.logger.error(`forget promise handler excepted [${name}]: ${error.message}`, error)
-    if (externalStackTrace !== undefined) {
-      this.logger.warn(`External Stack trace [${name}]:`, externalStackTrace)
-    }
-  }
-
-  /**
-   * Used to explicitly launch an async function (or Promise) with awaiting it
-   * @param promise The promise to forget
-   * @param config Configuration of forget settings
-   */
-  static forget<T>(promise: Promise<T> | PromiseEx<T> | PromisableFunction<T> | T, config?: ForgetConfig<T>) {
-    const externalStackTrace = (new Error('Stack')).stack
-
-    // default | global | provided priorities for config (not deep merge)
-    const resolvedConfig = {
-      ...defaultForgetConfig, ...globalThis.xy?.forget?.config, ...config,
-    }
-    const resolvedPromise = typeof promise === 'function' ? (promise as PromisableFunction<T>)() : promise
-    if (isPromise(resolvedPromise)) {
-      try {
-        let completed = false
-        this.activeForgets++
-
-        const promiseWrapper = async () => {
-          await resolvedPromise
-            .then((result: T) => {
-              this.activeForgets--
-              completed = true
-              resolvedConfig?.onComplete?.([result, undefined])
-            })
-            .catch((error) => {
-              this.activeForgets--
-              completed = true
-              this.logger.error(`forgotten promise excepted [${config?.name ?? 'unknown'}]: ${error.message}`, error)
-              resolvedConfig?.onComplete?.([undefined, error])
-            })
-        }
-
-        const promises = [promiseWrapper()]
-
-        // if there is a timeout, add it to the race
-        const timeout = resolvedConfig.timeout ?? defaultForgetConfig.timeout
-        if (isNumber(timeout)) {
-          const timeoutFunc = async () => {
-            await delay(timeout)
-            if (!completed) {
-              resolvedConfig.onCancel?.()
-              this.timeoutHandler(timeout, resolvedConfig, externalStackTrace)
-            }
-          }
-          promises.push(timeoutFunc())
-        }
-
-        const all = Promise.race(promises)
-
-        all
-          .then(() => {
-            return
-          })
-          .catch(() => {
-            return
-          })
-      } catch (ex) {
-        this.exceptedForgets += 1
-        resolvedConfig?.onException?.(ex as Error)
-        this.exceptionHandler(ex as Error, resolvedConfig, externalStackTrace)
-      }
-    } else {
-      // we do nothing here since if it was a non-promise, it already got invoked.
-      return
-    }
-  }
-
-  static timeoutHandler(time: number, { name = 'unknown' }: ForgetConfig, externalStackTrace?: string) {
-    this.logger.error(`forget promise timeout out after ${time}ms [Cancelling] [${name}]`)
-    if (externalStackTrace !== undefined) {
-      this.logger.warn(`External Stack trace [${name}]:`, externalStackTrace)
-    }
-  }
-}

package/src/ForgetPromiseNode.ts

@@ -1,34 +0,0 @@
-/// <reference types="node" />
-
-import type { Promisable } from '@xylabs/promise'
-
-import { defaultForgetNodeConfig, type ForgetNodeConfig } from './ForgetNodeConfig.ts'
-import { ForgetPromise } from './ForgetPromise.ts'
-
-export class ForgetPromiseNode extends ForgetPromise {
-  static override exceptionHandler(error: Error, config: ForgetNodeConfig, externalStackTrace?: string) {
-    // default | global | provided priorities for config (not deep merge)
-    super.exceptionHandler(error, config, externalStackTrace)
-    if (config?.terminateOnException === true) {
-      this.logger.error(`Attempting to terminate process [${config?.name ?? 'unknown'}]...`)
-      // eslint-disable-next-line unicorn/no-process-exit
-      process.exit(1)
-    }
-  }
-
-  static override forget<T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>) {
-    const resolvedConfig = {
-      ...defaultForgetNodeConfig, ...globalThis.xy?.forget?.config, ...config,
-    }
-    super.forget(promise, resolvedConfig)
-  }
-
-  static override timeoutHandler(time: number, config: ForgetNodeConfig, externalStackTrace?: string) {
-    super.timeoutHandler(time, config, externalStackTrace)
-    if (config?.terminateOnTimeout === true) {
-      this.logger.error(`Attempting to terminate process [${config?.name ?? 'unknown'}]...`)
-      // eslint-disable-next-line unicorn/no-process-exit
-      process.exit(2)
-    }
-  }
-}

package/src/forget.ts

@@ -1,9 +0,0 @@
-import { type Promisable } from '@xylabs/promise'
-
-import type { ForgetConfig } from './ForgetConfig.ts'
-import { ForgetPromise } from './ForgetPromise.ts'
-
-// used to explicitly launch an async function (or Promise) with awaiting it
-export const forget = <T>(promise: Promisable<T>, config?: ForgetConfig<T>) => {
-  ForgetPromise.forget<T>(promise, config)
-}

package/src/forgetNode.ts

@@ -1,9 +0,0 @@
-import { type Promisable } from '@xylabs/promise'
-
-import type { ForgetNodeConfig } from './ForgetNodeConfig.ts'
-import { ForgetPromiseNode } from './ForgetPromiseNode.ts'
-
-// used to explicitly launch an async function (or Promise) with awaiting it
-export const forgetNode = <T>(promise: Promisable<T>, config?: ForgetNodeConfig<T>) => {
-  ForgetPromiseNode.forget<T>(promise, config)
-}

package/src/index.ts

@@ -1 +0,0 @@
-export * from './node/index.ts'

package/src/neutral/index.ts

@@ -1,3 +0,0 @@
-export * from '../forget.ts'
-export * from '../ForgetConfig.ts'
-export * from '../ForgetPromise.ts'

package/src/node/index.ts

@@ -1,3 +0,0 @@
-export { forgetNode as forget } from '../forgetNode.ts'
-export * from '../ForgetNodeConfig.ts'
-export { ForgetPromiseNode as ForgetPromise } from '../ForgetPromiseNode.ts'

package/src/types/global-config-node.d.ts

@@ -1,9 +0,0 @@
-import type { ForgetNodeConfig } from './ForgetNodeConfig.ts'
-
-declare global {
-  var xy: {
-    forget: {
-      config: ForgetNodeConfig | undefined
-    } | undefined
-  } | undefined
-}

package/src/types/global-config.d.ts

@@ -1,9 +0,0 @@
-import type { ForgetConfig } from './ForgetConfig.ts'
-
-declare global {
-  var xy: {
-    forget: {
-      config: ForgetConfig | undefined
-    } | undefined
-  } | undefined
-}