@ls-stack/utils 3.9.1 → 3.10.0

package/lib/asyncQueue.cjs

@@ -21,23 +21,12 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var asyncQueue_exports = {};
 __export(asyncQueue_exports, {
   createAsyncQueue: () => createAsyncQueue,
-  createAsyncQueueWithId: () => createAsyncQueueWithId
+  createAsyncQueueWithMeta: () => createAsyncQueueWithMeta
 });
 module.exports = __toCommonJS(asyncQueue_exports);
 var import_evtmitter = require("evtmitter");
 var import_t_result = require("t-result");
 
-// src/assertions.ts
-function isObject(value) {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
-function isFunction(value) {
-  return typeof value === "function";
-}
-function isPromise(value) {
-  return isObject(value) && "then" in value && isFunction(value.then);
-}
-
 // src/promiseUtils.ts
 function defer() {
   let resolve;
@@ -74,38 +63,48 @@ var AsyncQueue = class {
     this.#queue.push(task);
     this.#size++;
   }
-  add(fn, options) {
+  async add(fn, options) {
+    if (this.#signal?.aborted) {
+      return import_t_result.Result.err(
+        this.#signal.reason instanceof Error ? this.#signal.reason : new DOMException("Queue aborted", "AbortError")
+      );
+    }
     const deferred = defer();
     const taskTimeout = this.#taskTimeout ?? options?.timeout;
     const task = {
       run: async (ctx) => {
-        if (isPromise(fn)) {
-          return fn;
-        }
-        return await fn(ctx);
+        return fn(ctx);
       },
       resolve: deferred.resolve,
       reject: deferred.reject,
       signal: options?.signal,
-      id: options?.id,
+      meta: options?.meta,
       timeout: taskTimeout
     };
     this.#enqueue(task);
     this.#processQueue();
-    return deferred.promise;
+    const r = await deferred.promise;
+    if (options?.onComplete) {
+      r.onOk(options.onComplete);
+    }
+    if (options?.onError) {
+      r.onErr(options.onError);
+    }
+    return r;
   }
   resultifyAdd(fn, options) {
     return this.add(
       (ctx) => (0, import_t_result.resultify)(async () => {
-        if (isPromise(fn)) {
-          return await fn;
-        }
         return fn(ctx);
       }),
       options
     );
   }
   async #processQueue() {
+    if (this.#signal?.aborted) {
+      this.clear();
+      return;
+    }
     if (this.#pending >= this.#concurrency || this.#queue.length === 0) {
       return;
     }
@@ -129,43 +128,52 @@ var AsyncQueue = class {
     let abortListener;
     try {
       if (signal?.aborted) {
-        const error = signal.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError");
+        const error = signal.reason instanceof Error ? signal.reason : new DOMException("This operation was aborted", "AbortError");
         throw error;
       }
       const signalAbortPromise = new Promise((_, reject) => {
         if (signal) {
-          const error = signal.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError");
+          const error = signal.reason instanceof Error ? signal.reason : new DOMException("This operation was aborted", "AbortError");
           abortListener = () => {
             reject(error);
           };
           signal.addEventListener("abort", abortListener, { once: true });
         }
       });
-      const taskRunPromise = task.run({ signal, id: task.id });
-      this.events.emit("start", { id: task.id });
+      const taskRunPromise = task.run({ signal, meta: task.meta });
+      this.events.emit("start", { meta: task.meta });
       const result = await Promise.race([taskRunPromise, signalAbortPromise]);
       if ((0, import_t_result.isResult)(result)) {
         task.resolve(result);
         if (result.error) {
           this.#failed++;
-          this.events.emit("error", { id: task.id, error: result.error });
+          this.events.emit("error", {
+            meta: task.meta,
+            error: result.error
+          });
         } else {
           this.#completed++;
-          this.events.emit("complete", { id: task.id, value: result.value });
+          this.events.emit("complete", {
+            meta: task.meta,
+            value: result.value
+          });
         }
       } else {
         const error = new Error("Response not a Result");
         task.resolve(import_t_result.Result.err(error));
         this.#failed++;
         this.events.emit("error", {
-          id: task.id,
+          meta: task.meta,
           error
         });
       }
     } catch (error) {
       task.resolve(import_t_result.Result.err(error));
       this.#failed++;
-      this.events.emit("error", { id: task.id, error: (0, import_t_result.unknownToError)(error) });
+      this.events.emit("error", {
+        meta: task.meta,
+        error: (0, import_t_result.unknownToError)(error)
+      });
     } finally {
       if (signal && abortListener) {
         signal.removeEventListener("abort", abortListener);
@@ -193,13 +201,9 @@ var AsyncQueue = class {
       this.#idleResolvers.push(resolve);
     });
   }
-  clear({ resetCounters = true } = {}) {
+  clear() {
     this.#queue = [];
     this.#size = 0;
-    if (resetCounters) {
-      this.#completed = 0;
-      this.#failed = 0;
-    }
     if (this.#pending === 0) {
       this.#resolveIdleWaiters();
     }
@@ -217,7 +221,7 @@ var AsyncQueue = class {
     return this.#size;
   }
 };
-var AsyncQueueWithId = class extends AsyncQueue {
+var AsyncQueueWithMeta = class extends AsyncQueue {
   constructor(options) {
     super(options);
   }
@@ -231,11 +235,11 @@ var AsyncQueueWithId = class extends AsyncQueue {
 function createAsyncQueue(options) {
   return new AsyncQueue(options);
 }
-function createAsyncQueueWithId(options) {
-  return new AsyncQueueWithId(options);
+function createAsyncQueueWithMeta(options) {
+  return new AsyncQueueWithMeta(options);
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createAsyncQueue,
-  createAsyncQueueWithId
+  createAsyncQueueWithMeta
 });

package/lib/asyncQueue.d.cts

@@ -6,51 +6,51 @@ type AsyncQueueOptions = {
     signal?: AbortSignal;
     timeout?: number;
 };
-type AddOptions<I> = {
+type AddOptions<I, T, E extends ResultValidErrors> = {
     signal?: AbortSignal;
     timeout?: number;
-    id?: I;
+    meta?: I;
+    onComplete?: (value: T) => void;
+    onError?: (error: E | Error) => void;
 };
 type RunCtx<I> = {
     signal?: AbortSignal;
-    id?: I;
+    meta?: I;
 };
-declare class AsyncQueue<T, E extends ResultValidErrors = Error, I = undefined> {
+declare class AsyncQueue<T, E extends ResultValidErrors = Error, I = unknown> {
     #private;
     events: evtmitter.Emitter<{
         error: {
-            id: I;
+            meta: I;
             error: E | Error;
         };
         complete: {
-            id: I;
+            meta: I;
             value: T;
         };
         start: {
-            id: I;
+            meta: I;
         };
     }>;
     constructor({ concurrency, signal, timeout: taskTimeout, }?: AsyncQueueOptions);
-    add(fn: ((ctx: RunCtx<I>) => Promise<Result<T, E>> | Result<T, E>) | Promise<Result<T, E>>, options?: AddOptions<I>): Promise<Result<T, E | Error>>;
-    resultifyAdd(fn: ((ctx: RunCtx<I>) => Promise<T> | T) | Promise<T>, options?: AddOptions<I>): Promise<Result<T, E | Error>>;
+    add(fn: (ctx: RunCtx<I>) => Promise<Result<T, E>> | Result<T, E>, options?: AddOptions<I, T, E>): Promise<Result<T, E | Error>>;
+    resultifyAdd(fn: (ctx: RunCtx<I>) => Promise<T> | T, options?: AddOptions<I, T, E>): Promise<Result<T, E | Error>>;
     onIdle(): Promise<void>;
-    clear({ resetCounters }?: {
-        resetCounters?: boolean;
-    }): void;
+    clear(): void;
     get completed(): number;
     get failed(): number;
     get pending(): number;
     get size(): number;
 }
-type AddOptionsWithId<I> = Omit<AddOptions<I>, 'id'> & {
-    id: I;
+type AddOptionsWithId<I, T, E extends ResultValidErrors> = Omit<AddOptions<I, T, E>, 'meta'> & {
+    meta: I;
 };
-declare class AsyncQueueWithId<T, I, E extends ResultValidErrors = Error> extends AsyncQueue<T, E, I> {
+declare class AsyncQueueWithMeta<T, I, E extends ResultValidErrors = Error> extends AsyncQueue<T, E, I> {
     constructor(options?: AsyncQueueOptions);
-    add(fn: ((ctx: RunCtx<I>) => Promise<Result<T, E>> | Result<T, E>) | Promise<Result<T, E>>, options?: AddOptionsWithId<I>): Promise<Result<T, E | Error>>;
-    resultifyAdd(fn: ((ctx: RunCtx<I>) => Promise<T> | T) | Promise<T>, options?: AddOptionsWithId<I>): Promise<Result<T, E | Error>>;
+    add(fn: (ctx: RunCtx<I>) => Promise<Result<T, E>> | Result<T, E>, options?: AddOptionsWithId<I, T, E>): Promise<Result<T, E | Error>>;
+    resultifyAdd(fn: (ctx: RunCtx<I>) => Promise<T> | T, options?: AddOptionsWithId<I, T, E>): Promise<Result<T, E | Error>>;
 }
 declare function createAsyncQueue<T, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueue<T, E>;
-declare function createAsyncQueueWithId<T, I, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueueWithId<T, I, E>;
+declare function createAsyncQueueWithMeta<T, I, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueueWithMeta<T, I, E>;
 
-export { createAsyncQueue, createAsyncQueueWithId };
+export { createAsyncQueue, createAsyncQueueWithMeta };

package/lib/asyncQueue.d.ts

@@ -6,51 +6,51 @@ type AsyncQueueOptions = {
     signal?: AbortSignal;
     timeout?: number;
 };
-type AddOptions<I> = {
+type AddOptions<I, T, E extends ResultValidErrors> = {
     signal?: AbortSignal;
     timeout?: number;
-    id?: I;
+    meta?: I;
+    onComplete?: (value: T) => void;
+    onError?: (error: E | Error) => void;
 };
 type RunCtx<I> = {
     signal?: AbortSignal;
-    id?: I;
+    meta?: I;
 };
-declare class AsyncQueue<T, E extends ResultValidErrors = Error, I = undefined> {
+declare class AsyncQueue<T, E extends ResultValidErrors = Error, I = unknown> {
     #private;
     events: evtmitter.Emitter<{
         error: {
-            id: I;
+            meta: I;
             error: E | Error;
         };
         complete: {
-            id: I;
+            meta: I;
             value: T;
         };
         start: {
-            id: I;
+            meta: I;
         };
     }>;
     constructor({ concurrency, signal, timeout: taskTimeout, }?: AsyncQueueOptions);
-    add(fn: ((ctx: RunCtx<I>) => Promise<Result<T, E>> | Result<T, E>) | Promise<Result<T, E>>, options?: AddOptions<I>): Promise<Result<T, E | Error>>;
-    resultifyAdd(fn: ((ctx: RunCtx<I>) => Promise<T> | T) | Promise<T>, options?: AddOptions<I>): Promise<Result<T, E | Error>>;
+    add(fn: (ctx: RunCtx<I>) => Promise<Result<T, E>> | Result<T, E>, options?: AddOptions<I, T, E>): Promise<Result<T, E | Error>>;
+    resultifyAdd(fn: (ctx: RunCtx<I>) => Promise<T> | T, options?: AddOptions<I, T, E>): Promise<Result<T, E | Error>>;
     onIdle(): Promise<void>;
-    clear({ resetCounters }?: {
-        resetCounters?: boolean;
-    }): void;
+    clear(): void;
     get completed(): number;
     get failed(): number;
     get pending(): number;
     get size(): number;
 }
-type AddOptionsWithId<I> = Omit<AddOptions<I>, 'id'> & {
-    id: I;
+type AddOptionsWithId<I, T, E extends ResultValidErrors> = Omit<AddOptions<I, T, E>, 'meta'> & {
+    meta: I;
 };
-declare class AsyncQueueWithId<T, I, E extends ResultValidErrors = Error> extends AsyncQueue<T, E, I> {
+declare class AsyncQueueWithMeta<T, I, E extends ResultValidErrors = Error> extends AsyncQueue<T, E, I> {
     constructor(options?: AsyncQueueOptions);
-    add(fn: ((ctx: RunCtx<I>) => Promise<Result<T, E>> | Result<T, E>) | Promise<Result<T, E>>, options?: AddOptionsWithId<I>): Promise<Result<T, E | Error>>;
-    resultifyAdd(fn: ((ctx: RunCtx<I>) => Promise<T> | T) | Promise<T>, options?: AddOptionsWithId<I>): Promise<Result<T, E | Error>>;
+    add(fn: (ctx: RunCtx<I>) => Promise<Result<T, E>> | Result<T, E>, options?: AddOptionsWithId<I, T, E>): Promise<Result<T, E | Error>>;
+    resultifyAdd(fn: (ctx: RunCtx<I>) => Promise<T> | T, options?: AddOptionsWithId<I, T, E>): Promise<Result<T, E | Error>>;
 }
 declare function createAsyncQueue<T, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueue<T, E>;
-declare function createAsyncQueueWithId<T, I, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueueWithId<T, I, E>;
+declare function createAsyncQueueWithMeta<T, I, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueueWithMeta<T, I, E>;
 
-export { createAsyncQueue, createAsyncQueueWithId };
+export { createAsyncQueue, createAsyncQueueWithMeta };

package/lib/asyncQueue.js

@@ -1,9 +1,6 @@
 import {
   defer
 } from "./chunk-DFXNVEH6.js";
-import {
-  isPromise
-} from "./chunk-3XCS7FVO.js";
 
 // src/asyncQueue.ts
 import { evtmitter } from "evtmitter";
@@ -37,38 +34,48 @@ var AsyncQueue = class {
     this.#queue.push(task);
     this.#size++;
   }
-  add(fn, options) {
+  async add(fn, options) {
+    if (this.#signal?.aborted) {
+      return Result.err(
+        this.#signal.reason instanceof Error ? this.#signal.reason : new DOMException("Queue aborted", "AbortError")
+      );
+    }
     const deferred = defer();
     const taskTimeout = this.#taskTimeout ?? options?.timeout;
     const task = {
       run: async (ctx) => {
-        if (isPromise(fn)) {
-          return fn;
-        }
-        return await fn(ctx);
+        return fn(ctx);
       },
       resolve: deferred.resolve,
       reject: deferred.reject,
       signal: options?.signal,
-      id: options?.id,
+      meta: options?.meta,
       timeout: taskTimeout
     };
     this.#enqueue(task);
     this.#processQueue();
-    return deferred.promise;
+    const r = await deferred.promise;
+    if (options?.onComplete) {
+      r.onOk(options.onComplete);
+    }
+    if (options?.onError) {
+      r.onErr(options.onError);
+    }
+    return r;
   }
   resultifyAdd(fn, options) {
     return this.add(
       (ctx) => resultify(async () => {
-        if (isPromise(fn)) {
-          return await fn;
-        }
         return fn(ctx);
       }),
       options
     );
   }
   async #processQueue() {
+    if (this.#signal?.aborted) {
+      this.clear();
+      return;
+    }
     if (this.#pending >= this.#concurrency || this.#queue.length === 0) {
       return;
     }
@@ -92,43 +99,52 @@ var AsyncQueue = class {
     let abortListener;
     try {
       if (signal?.aborted) {
-        const error = signal.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError");
+        const error = signal.reason instanceof Error ? signal.reason : new DOMException("This operation was aborted", "AbortError");
         throw error;
       }
       const signalAbortPromise = new Promise((_, reject) => {
         if (signal) {
-          const error = signal.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError");
+          const error = signal.reason instanceof Error ? signal.reason : new DOMException("This operation was aborted", "AbortError");
           abortListener = () => {
             reject(error);
           };
           signal.addEventListener("abort", abortListener, { once: true });
         }
       });
-      const taskRunPromise = task.run({ signal, id: task.id });
-      this.events.emit("start", { id: task.id });
+      const taskRunPromise = task.run({ signal, meta: task.meta });
+      this.events.emit("start", { meta: task.meta });
       const result = await Promise.race([taskRunPromise, signalAbortPromise]);
       if (isResult(result)) {
         task.resolve(result);
         if (result.error) {
           this.#failed++;
-          this.events.emit("error", { id: task.id, error: result.error });
+          this.events.emit("error", {
+            meta: task.meta,
+            error: result.error
+          });
         } else {
           this.#completed++;
-          this.events.emit("complete", { id: task.id, value: result.value });
+          this.events.emit("complete", {
+            meta: task.meta,
+            value: result.value
+          });
         }
       } else {
         const error = new Error("Response not a Result");
         task.resolve(Result.err(error));
         this.#failed++;
         this.events.emit("error", {
-          id: task.id,
+          meta: task.meta,
           error
         });
       }
     } catch (error) {
       task.resolve(Result.err(error));
       this.#failed++;
-      this.events.emit("error", { id: task.id, error: unknownToError(error) });
+      this.events.emit("error", {
+        meta: task.meta,
+        error: unknownToError(error)
+      });
     } finally {
       if (signal && abortListener) {
         signal.removeEventListener("abort", abortListener);
@@ -156,13 +172,9 @@ var AsyncQueue = class {
       this.#idleResolvers.push(resolve);
     });
   }
-  clear({ resetCounters = true } = {}) {
+  clear() {
     this.#queue = [];
     this.#size = 0;
-    if (resetCounters) {
-      this.#completed = 0;
-      this.#failed = 0;
-    }
     if (this.#pending === 0) {
       this.#resolveIdleWaiters();
     }
@@ -180,7 +192,7 @@ var AsyncQueue = class {
     return this.#size;
   }
 };
-var AsyncQueueWithId = class extends AsyncQueue {
+var AsyncQueueWithMeta = class extends AsyncQueue {
   constructor(options) {
     super(options);
   }
@@ -194,10 +206,10 @@ var AsyncQueueWithId = class extends AsyncQueue {
 function createAsyncQueue(options) {
   return new AsyncQueue(options);
 }
-function createAsyncQueueWithId(options) {
-  return new AsyncQueueWithId(options);
+function createAsyncQueueWithMeta(options) {
+  return new AsyncQueueWithMeta(options);
 }
 export {
   createAsyncQueue,
-  createAsyncQueueWithId
+  createAsyncQueueWithMeta
 };

package/lib/testUtils.cjs

@@ -21,7 +21,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var testUtils_exports = {};
 __export(testUtils_exports, {
   createLoggerStore: () => createLoggerStore,
-  getResultFn: () => getResultFn
+  getResultFn: () => getResultFn,
+  waitController: () => waitController
 });
 module.exports = __toCommonJS(testUtils_exports);
 
@@ -141,6 +142,17 @@ function omit(obj, keys) {
   return result;
 }
 
+// src/promiseUtils.ts
+function defer() {
+  let resolve;
+  let reject;
+  const promise = new Promise((_resolve, _reject) => {
+    resolve = _resolve;
+    reject = _reject;
+  });
+  return { resolve, reject, promise };
+}
+
 // src/testUtils.ts
 function createLoggerStore({
   filterKeys: defaultFilterKeys,
@@ -353,8 +365,23 @@ function getResultFn(fnGetter, wrapper) {
     }
   };
 }
+function waitController() {
+  const { promise, resolve } = defer();
+  return {
+    wait: promise,
+    stopWaiting: () => {
+      resolve();
+    },
+    stopWaitingAfter: (ms) => {
+      setTimeout(() => {
+        resolve();
+      }, ms);
+    }
+  };
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   createLoggerStore,
-  getResultFn
+  getResultFn,
+  waitController
 });

package/lib/testUtils.d.cts

@@ -34,5 +34,10 @@ declare function createLoggerStore({ filterKeys: defaultFilterKeys, rejectKeys:
     addMark: (label: string) => void;
 };
 declare function getResultFn<T extends (...args: any[]) => any>(fnGetter: () => T, wrapper?: (...args: any[]) => any): T;
+declare function waitController(): {
+    wait: Promise<void>;
+    stopWaiting: () => void;
+    stopWaitingAfter: (ms: number) => void;
+};
 
-export { createLoggerStore, getResultFn };
+export { createLoggerStore, getResultFn, waitController };

package/lib/testUtils.d.ts

@@ -34,5 +34,10 @@ declare function createLoggerStore({ filterKeys: defaultFilterKeys, rejectKeys:
     addMark: (label: string) => void;
 };
 declare function getResultFn<T extends (...args: any[]) => any>(fnGetter: () => T, wrapper?: (...args: any[]) => any): T;
+declare function waitController(): {
+    wait: Promise<void>;
+    stopWaiting: () => void;
+    stopWaitingAfter: (ms: number) => void;
+};
 
-export { createLoggerStore, getResultFn };
+export { createLoggerStore, getResultFn, waitController };

package/lib/testUtils.js

@@ -5,6 +5,9 @@ import {
 import {
   deepEqual
 } from "./chunk-JQFUKJU5.js";
+import {
+  defer
+} from "./chunk-DFXNVEH6.js";
 import {
   clampMin
 } from "./chunk-HTCYUMDR.js";
@@ -228,7 +231,22 @@ function getResultFn(fnGetter, wrapper) {
     }
   };
 }
+function waitController() {
+  const { promise, resolve } = defer();
+  return {
+    wait: promise,
+    stopWaiting: () => {
+      resolve();
+    },
+    stopWaitingAfter: (ms) => {
+      setTimeout(() => {
+        resolve();
+      }, ms);
+    }
+  };
+}
 export {
   createLoggerStore,
-  getResultFn
+  getResultFn,
+  waitController
 };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ls-stack/utils",
   "description": "Typescript utils",
-  "version": "3.9.1",
+  "version": "3.10.0",
   "license": "MIT",
   "files": [
     "lib"
@@ -198,7 +198,7 @@
     "tsc": "tsc -p tsconfig.prod.json",
     "tsc:watch": "tsc -p tsconfig.prod.json --watch",
     "eslint": "CI=true eslint src/ scripts/ --color --max-warnings=0",
-    "build": "pnpm test && pnpm lint && pnpm build:no-test && pnpm docs && pnpm build:update-exports",
+    "build": "pnpm test && pnpm lint && pnpm build:no-test && pnpm run docs && pnpm run docs:commit && pnpm build:update-exports",
     "build:no-test": "tsup",
     "build:update-exports": "tsm --no-warnings scripts/updatePackageExports.ts",
     "build-test": "tsup --config tsup.test.config.ts",
@@ -206,6 +206,7 @@
     "test:console-fmt": "tsm --no-warnings scripts/testConsoleFmt.ts",
     "bench:deepEqual": "tsm --no-warnings benchmarks/deepEqual.ts",
     "docs": "typedoc",
-    "docs:watch": "typedoc --watch"
+    "docs:watch": "typedoc --watch",
+    "docs:commit": "git add docs && git diff --cached --quiet docs || git commit -m 'docs: update docs'"
   }
 }