@naturalcycles/js-lib 15.70.0 → 15.71.0

package/dist/asyncManager.d.ts

@@ -0,0 +1,50 @@
+import type { CommonLogger } from './log/commonLogger.js';
+import type { NumberOfMilliseconds } from './types.js';
+declare class AsyncManagerImpl {
+    logger: CommonLogger;
+    pendingOps: Set<Promise<unknown>>;
+    private onErrorHooks;
+    runInBackground(promise: Promise<unknown>): void;
+    onError(fn: OnErrorHook): void;
+    /**
+     * Resolves when all pending operations settle.
+     * They may resolve or reject, allDone will never throw.
+     * Errors (rejections) are reported to onErrorHooks (instead).
+     *
+     * If timeout is specified - it resolves if timeout has reached.
+     */
+    allDone(timeout?: NumberOfMilliseconds): Promise<void>;
+    reset(): void;
+    private fireOnErrorHooks;
+}
+/**
+ * Singleton which keeps track of async operations - "voided promise-returning functions"
+ * that should run in parallel to the main request.
+ *
+ * It is an alternative to do `void doSomeAnalytics()`, which should run in parallel
+ * and not block the request (not slow down nor fail the request on analytics api failure).
+ *
+ * At the same time, `void doSomeAnalytics()` gets completely detached and untracked,
+ * nothing awaits it, its rejection becomes unhandledRejection (and may kill Node.js process).
+ *
+ * With AsyncManager, you instead register all those "voided" calls like this:
+ *
+ * AsyncManager.runInBackground(doSomeAnalytics())
+ *
+ * Then, in a few places you may be interested to ensure that all async operations have been finished.
+ * The places can be:
+ * - Graceful shutdown of a backend service
+ * - Before the end of runScript
+ * - At the end of each unit test, to make sure async ops don't leak
+ *
+ * You ensure no pending async operations like this:
+ *
+ * await AsyncManager.allDone()
+ *
+ * which never throws, but instead awaits all operations to be settled.
+ *
+ * @experimental
+ */
+export declare const AsyncManager: AsyncManagerImpl;
+export type OnErrorHook = (err: Error) => any;
+export {};

package/dist/asyncManager.js

@@ -0,0 +1,83 @@
+class AsyncManagerImpl {
+    logger = console;
+    pendingOps = new Set();
+    onErrorHooks = [];
+    runInBackground(promise) {
+        const wrappedPromise = promise
+            .catch(err => this.fireOnErrorHooks(err))
+            .finally(() => this.pendingOps.delete(wrappedPromise));
+        this.pendingOps.add(wrappedPromise);
+    }
+    onError(fn) {
+        this.onErrorHooks.push(fn);
+    }
+    /**
+     * Resolves when all pending operations settle.
+     * They may resolve or reject, allDone will never throw.
+     * Errors (rejections) are reported to onErrorHooks (instead).
+     *
+     * If timeout is specified - it resolves if timeout has reached.
+     */
+    async allDone(timeout) {
+        const { size } = this.pendingOps;
+        if (!size)
+            return;
+        const { logger } = this;
+        const started = Date.now();
+        if (timeout) {
+            const result = await Promise.race([
+                Promise.allSettled(this.pendingOps),
+                new Promise(resolve => setTimeout(resolve, timeout, 'timeout')),
+            ]);
+            if (result === 'timeout') {
+                logger.warn(`AsyncManager.allDone timed out after ${timeout} ms with ${this.pendingOps.size} pending op(s)`);
+                return;
+            }
+        }
+        else {
+            await Promise.allSettled(this.pendingOps);
+        }
+        logger.log(`AsyncManager.allDone for ${size} op(s) in ${Date.now() - started} ms`);
+    }
+    reset() {
+        this.pendingOps.clear();
+        this.onErrorHooks = [];
+    }
+    fireOnErrorHooks(err) {
+        if (this.onErrorHooks.length) {
+            this.onErrorHooks.forEach(hook => hook(err));
+        }
+        else {
+            this.logger.error('AsyncManager unhandled rejection:', err);
+        }
+    }
+}
+/**
+ * Singleton which keeps track of async operations - "voided promise-returning functions"
+ * that should run in parallel to the main request.
+ *
+ * It is an alternative to do `void doSomeAnalytics()`, which should run in parallel
+ * and not block the request (not slow down nor fail the request on analytics api failure).
+ *
+ * At the same time, `void doSomeAnalytics()` gets completely detached and untracked,
+ * nothing awaits it, its rejection becomes unhandledRejection (and may kill Node.js process).
+ *
+ * With AsyncManager, you instead register all those "voided" calls like this:
+ *
+ * AsyncManager.runInBackground(doSomeAnalytics())
+ *
+ * Then, in a few places you may be interested to ensure that all async operations have been finished.
+ * The places can be:
+ * - Graceful shutdown of a backend service
+ * - Before the end of runScript
+ * - At the end of each unit test, to make sure async ops don't leak
+ *
+ * You ensure no pending async operations like this:
+ *
+ * await AsyncManager.allDone()
+ *
+ * which never throws, but instead awaits all operations to be settled.
+ *
+ * @experimental
+ */
+export const AsyncManager = new AsyncManagerImpl();

package/dist/browser/adminService.js

@@ -43,7 +43,6 @@ export class AdminService {
     stopListening() {
         if (isServerSide())
             return;
-        // oxlint-disable-next-line typescript/unbound-method
         document.removeEventListener('keydown', this.keydownListener);
         this.listening = false;
     }

package/dist/decorators/asyncMemo.decorator.js

@@ -10,7 +10,6 @@ import { jsonMemoSerializer } from './memo.util.js';
  *
  * @experimental consider normal `@_Memo` for most of the cases, it's stable and predictable
  */
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export const _AsyncMemo = (opt) => (target, key, descriptor) => {
     _assertTypeOf(descriptor.value, 'function', 'Memoization can be applied only to methods');
     const originalFn = descriptor.value;

package/dist/decorators/debounce.decorator.js

@@ -1,5 +1,4 @@
 import { _debounce, _throttle } from './debounce.js';
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export function _Debounce(wait, opt = {}) {
     return (_target, _key, descriptor) => {
         const originalFn = descriptor.value;
@@ -7,7 +6,6 @@ export function _Debounce(wait, opt = {}) {
         return descriptor;
     };
 }
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export function _Throttle(wait, opt = {}) {
     return (_target, _key, descriptor) => {
         const originalFn = descriptor.value;

package/dist/decorators/logMethod.decorator.js

@@ -16,7 +16,6 @@ import { _getArgsSignature, _getMethodSignature } from './decorator.util.js';
  * >> asyncMethod()
  * << asyncMethodThrow() took 10 ms ERROR: MyError
  */
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export function _LogMethod(opt = {}) {
     return (_target, key, descriptor) => {
         _assert(typeof descriptor.value === 'function', '@_LogMethod can be applied only to methods');

package/dist/decorators/memo.decorator.js

@@ -22,7 +22,6 @@ import { jsonMemoSerializer, MapMemoCache } from './memo.util.js';
  * http://inlehmansterms.net/2015/03/01/javascript-memoization/
  * https://community.risingstack.com/the-worlds-fastest-javascript-memoization-library/
  */
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export const _Memo = (opt = {}) => (target, key, descriptor) => {
     _assertTypeOf(descriptor.value, 'function', 'Memoization can be applied only to methods');
     const originalFn = descriptor.value;

package/dist/decorators/retry.decorator.js

@@ -1,5 +1,4 @@
 import { pRetryFn } from '../promise/pRetry.js';
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export function _Retry(opt = {}) {
     return (_target, _key, descriptor) => {
         const originalFn = descriptor.value;

package/dist/decorators/swarmSafe.decorator.js

@@ -7,7 +7,6 @@ import { _getTargetMethodSignature } from './decorator.util.js';
  * Does not support `cacheKey`.
  * So, the same Promise is returned, regardless of the arguments.
  */
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export const _SwarmSafe = () => (target, key, descriptor) => {
     if (typeof descriptor.value !== 'function') {
         throw new TypeError('@_SwarmSafe can be applied only to methods');

package/dist/decorators/timeout.decorator.js

@@ -1,7 +1,6 @@
 import { _assert } from '../error/assert.js';
 import { pTimeout } from '../promise/pTimeout.js';
 import { _getMethodSignature } from './decorator.util.js';
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export function _Timeout(opt) {
     return (_target, key, descriptor) => {
         _assert(typeof descriptor.value === 'function', '@_Timeout can be applied only to methods');

package/dist/error/tryCatch.js

@@ -34,7 +34,6 @@ export function _tryCatch(fn, opt = {}) {
         }
     };
 }
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export const _TryCatch = (opt = {}) => (_target, _key, descriptor) => {
     const originalFn = descriptor.value;
     descriptor.value = _tryCatch(originalFn, opt);

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export * from './abort.js';
+export * from './asyncManager.js';
 export * from './bot.model.js';
 export * from './define.js';
 export * from './enum.util.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export * from './abort.js';
+export * from './asyncManager.js';
 export * from './bot.model.js';
 export * from './define.js';
 export * from './enum.util.js';

package/dist/number/number.util.js

@@ -40,7 +40,6 @@ export function _isBetween(x, min, max, incl) {
     return true;
 }
 export function _clamp(x, minIncl, maxIncl) {
-    // oxlint-disable-next-line unicorn/prefer-math-min-max
     return x <= minIncl ? minIncl : x >= maxIncl ? maxIncl : x;
 }
 /**

package/dist/object/keySortedMap.js

@@ -1,5 +1,4 @@
 import { _assert } from '../error/index.js';
-// oxlint-disable-next-line no-unsafe-declaration-merging -- Map<K,V> workaround for oxlint TS2420 false positive
 export class KeySortedMap {
     map;
     #sortedKeys;

package/dist/object/lazyKeySortedMap.js

@@ -1,5 +1,4 @@
 import { _assert } from '../error/index.js';
-// oxlint-disable-next-line no-unsafe-declaration-merging -- Map<K,V> workaround for oxlint TS2420 false positive
 export class LazyKeySortedMap {
     map;
     maybeSortedKeys;

package/dist/string/safeJsonStringify.js

@@ -13,7 +13,6 @@ export function _safeJsonStringify(obj, replacer, spaces, cycleReplacer) {
         return JSON.stringify(obj, serializer(replacer, cycleReplacer), spaces);
     }
 }
-// oxlint-disable no-unused-expressions
 function serializer(replacer, cycleReplacer) {
     const stack = [];
     const keys = [];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/js-lib",
   "type": "module",
-  "version": "15.70.0",
+  "version": "15.71.0",
   "dependencies": {
     "tslib": "^2"
   },
@@ -17,7 +17,7 @@
     "@types/crypto-js": "^4",
     "@types/node": "^25",
     "@types/semver": "^7",
-    "@typescript/native-preview": "7.0.0-dev.20260201.1",
+    "@typescript/native-preview": "7.0.0-dev.20260301.1",
     "crypto-js": "^4",
     "dayjs": "^1",
     "@naturalcycles/dev-lib": "18.4.2"

package/src/asyncManager.ts

@@ -0,0 +1,96 @@
+import type { CommonLogger } from './log/commonLogger.js'
+import type { NumberOfMilliseconds } from './types.js'
+
+class AsyncManagerImpl {
+  logger: CommonLogger = console
+
+  pendingOps = new Set<Promise<unknown>>()
+
+  private onErrorHooks: OnErrorHook[] = []
+
+  runInBackground(promise: Promise<unknown>): void {
+    const wrappedPromise = promise
+      .catch(err => this.fireOnErrorHooks(err))
+      .finally(() => this.pendingOps.delete(wrappedPromise))
+    this.pendingOps.add(wrappedPromise)
+  }
+
+  onError(fn: OnErrorHook): void {
+    this.onErrorHooks.push(fn)
+  }
+
+  /**
+   * Resolves when all pending operations settle.
+   * They may resolve or reject, allDone will never throw.
+   * Errors (rejections) are reported to onErrorHooks (instead).
+   *
+   * If timeout is specified - it resolves if timeout has reached.
+   */
+  async allDone(timeout?: NumberOfMilliseconds): Promise<void> {
+    const { size } = this.pendingOps
+    if (!size) return
+    const { logger } = this
+
+    const started = Date.now()
+    if (timeout) {
+      const result = await Promise.race([
+        Promise.allSettled(this.pendingOps),
+        new Promise<'timeout'>(resolve => setTimeout(resolve, timeout, 'timeout')),
+      ])
+      if (result === 'timeout') {
+        logger.warn(
+          `AsyncManager.allDone timed out after ${timeout} ms with ${this.pendingOps.size} pending op(s)`,
+        )
+        return
+      }
+    } else {
+      await Promise.allSettled(this.pendingOps)
+    }
+    logger.log(`AsyncManager.allDone for ${size} op(s) in ${Date.now() - started} ms`)
+  }
+
+  reset(): void {
+    this.pendingOps.clear()
+    this.onErrorHooks = []
+  }
+
+  private fireOnErrorHooks(err: any): void {
+    if (this.onErrorHooks.length) {
+      this.onErrorHooks.forEach(hook => hook(err))
+    } else {
+      this.logger.error('AsyncManager unhandled rejection:', err)
+    }
+  }
+}
+
+/**
+ * Singleton which keeps track of async operations - "voided promise-returning functions"
+ * that should run in parallel to the main request.
+ *
+ * It is an alternative to do `void doSomeAnalytics()`, which should run in parallel
+ * and not block the request (not slow down nor fail the request on analytics api failure).
+ *
+ * At the same time, `void doSomeAnalytics()` gets completely detached and untracked,
+ * nothing awaits it, its rejection becomes unhandledRejection (and may kill Node.js process).
+ *
+ * With AsyncManager, you instead register all those "voided" calls like this:
+ *
+ * AsyncManager.runInBackground(doSomeAnalytics())
+ *
+ * Then, in a few places you may be interested to ensure that all async operations have been finished.
+ * The places can be:
+ * - Graceful shutdown of a backend service
+ * - Before the end of runScript
+ * - At the end of each unit test, to make sure async ops don't leak
+ *
+ * You ensure no pending async operations like this:
+ *
+ * await AsyncManager.allDone()
+ *
+ * which never throws, but instead awaits all operations to be settled.
+ *
+ * @experimental
+ */
+export const AsyncManager = new AsyncManagerImpl()
+
+export type OnErrorHook = (err: Error) => any

package/src/browser/adminService.ts

@@ -103,7 +103,6 @@ export class AdminService {
 
   stopListening(): void {
     if (isServerSide()) return
-    // oxlint-disable-next-line typescript/unbound-method
     document.removeEventListener('keydown', this.keydownListener)
     this.listening = false
   }

package/src/browser/analytics.util.ts

@@ -1,8 +1,6 @@
 import { isServerSide } from '../env.js'
 import { loadScript } from './script.util.js'
 
-// oxlint-disable no-var
-
 declare global {
   var dataLayer: any[]
   var gtag: (...args: any[]) => void

package/src/decorators/asyncMemo.decorator.ts

@@ -43,7 +43,6 @@ export interface AsyncMemoInstance {
  *
  * @experimental consider normal `@_Memo` for most of the cases, it's stable and predictable
  */
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export const _AsyncMemo =
   <FN>(opt: AsyncMemoOptions<FN>): MethodDecorator<FN> =>
   (target, key, descriptor) => {

package/src/decorators/debounce.decorator.ts

@@ -1,7 +1,6 @@
 import type { DebounceOptions, ThrottleOptions } from './debounce.js'
 import { _debounce, _throttle } from './debounce.js'
 
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export function _Debounce(wait: number, opt: DebounceOptions = {}): MethodDecorator {
   return (_target, _key, descriptor) => {
     const originalFn = descriptor.value
@@ -10,7 +9,6 @@ export function _Debounce(wait: number, opt: DebounceOptions = {}): MethodDecora
   }
 }
 
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export function _Throttle(wait: number, opt: ThrottleOptions = {}): MethodDecorator {
   return (_target, _key, descriptor) => {
     const originalFn = descriptor.value

package/src/decorators/logMethod.decorator.ts

@@ -71,7 +71,6 @@ export interface LogMethodOptions {
  * >> asyncMethod()
  * << asyncMethodThrow() took 10 ms ERROR: MyError
  */
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export function _LogMethod(opt: LogMethodOptions = {}): MethodDecorator {
   return (_target, key, descriptor) => {
     _assert(typeof descriptor.value === 'function', '@_LogMethod can be applied only to methods')

package/src/decorators/memo.decorator.ts

@@ -56,7 +56,6 @@ export interface MemoInstance {
  * http://inlehmansterms.net/2015/03/01/javascript-memoization/
  * https://community.risingstack.com/the-worlds-fastest-javascript-memoization-library/
  */
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export const _Memo =
   <FN>(opt: MemoOptions<FN> = {}): MethodDecorator<FN> =>
   (target, key, descriptor) => {

package/src/decorators/retry.decorator.ts

@@ -1,7 +1,6 @@
 import type { PRetryOptions } from '../promise/pRetry.js'
 import { pRetryFn } from '../promise/pRetry.js'
 
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export function _Retry(opt: PRetryOptions = {}): MethodDecorator {
   return (_target, _key, descriptor) => {
     const originalFn = descriptor.value

package/src/decorators/swarmSafe.decorator.ts

@@ -9,7 +9,6 @@ import { _getTargetMethodSignature } from './decorator.util.js'
  * Does not support `cacheKey`.
  * So, the same Promise is returned, regardless of the arguments.
  */
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export const _SwarmSafe = (): MethodDecorator => (target, key, descriptor) => {
   if (typeof descriptor.value !== 'function') {
     throw new TypeError('@_SwarmSafe can be applied only to methods')

package/src/decorators/timeout.decorator.ts

@@ -3,7 +3,6 @@ import type { PTimeoutOptions } from '../promise/pTimeout.js'
 import { pTimeout } from '../promise/pTimeout.js'
 import { _getMethodSignature } from './decorator.util.js'
 
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export function _Timeout(opt: PTimeoutOptions): MethodDecorator {
   return (_target, key, descriptor) => {
     _assert(typeof descriptor.value === 'function', '@_Timeout can be applied only to methods')

package/src/error/tryCatch.ts

@@ -65,7 +65,6 @@ export function _tryCatch<T extends AnyFunction>(fn: T, opt: TryCatchOptions = {
   } as any
 }
 
-// eslint-disable-next-line @typescript-eslint/naming-convention
 export const _TryCatch =
   (opt: TryCatchOptions = {}): MethodDecorator =>
   (_target, _key, descriptor) => {

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './abort.js'
+export * from './asyncManager.js'
 export * from './bot.model.js'
 export * from './define.js'
 export * from './enum.util.js'

package/src/number/number.util.ts

@@ -50,7 +50,6 @@ export function _isBetween<T extends number | string>(
 }
 
 export function _clamp(x: number, minIncl: number, maxIncl: number): number {
-  // oxlint-disable-next-line unicorn/prefer-math-min-max
   return x <= minIncl ? minIncl : x >= maxIncl ? maxIncl : x
 }
 

package/src/object/keySortedMap.ts

@@ -25,7 +25,6 @@ export interface KeySortedMapOptions<K> {
 // oxlint-disable-next-line no-unsafe-declaration-merging -- Map<K,V> workaround for oxlint TS2420 false positive
 export interface KeySortedMap<K, V> extends Map<K, V> {}
 
-// oxlint-disable-next-line no-unsafe-declaration-merging -- Map<K,V> workaround for oxlint TS2420 false positive
 export class KeySortedMap<K, V> {
   private readonly map: Map<K, V>
   readonly #sortedKeys: K[]

package/src/object/lazyKeySortedMap.ts

@@ -20,7 +20,6 @@ export interface LazyKeySortedMapOptions<K> {
 // oxlint-disable-next-line no-unsafe-declaration-merging -- Map<K,V> workaround for oxlint TS2420 false positive
 export interface LazyKeySortedMap<K, V> extends Map<K, V> {}
 
-// oxlint-disable-next-line no-unsafe-declaration-merging -- Map<K,V> workaround for oxlint TS2420 false positive
 export class LazyKeySortedMap<K, V> {
   private readonly map: Map<K, V>
   private readonly maybeSortedKeys: K[]

package/src/string/safeJsonStringify.ts

@@ -20,7 +20,6 @@ export function _safeJsonStringify(
   }
 }
 
-// oxlint-disable no-unused-expressions
 function serializer(replacer?: Reviver, cycleReplacer?: Reviver): Reviver {
   const stack: any[] = []
   const keys: string[] = []

package/src/types.ts

@@ -521,8 +521,6 @@ type ReadonlyObjectDeep<ObjectType extends object> = {
   readonly [KeyType in keyof ObjectType]: ReadonlyDeep<ObjectType[KeyType]>
 }
 
-// oxlint-enable
-
 /**
  Makes one property of T required instead of optional.
  @example