@ls-stack/utils 3.9.0 → 3.10.0

package/README.md

@@ -1 +1,82 @@
-# Generic typescript utils
+# @ls-stack/utils
+
+Generic TypeScript utilities for modern JavaScript/TypeScript projects.
+
+## Installation
+
+```bash
+npm install @ls-stack/utils
+# or
+pnpm add @ls-stack/utils
+# or
+yarn add @ls-stack/utils
+```
+
+## Usage
+
+Import specific utilities from their modules:
+
+```typescript
+import { createAsyncQueue } from '@ls-stack/utils/asyncQueue';
+import { deepEqual } from '@ls-stack/utils/deepEqual';
+import { debounce } from '@ls-stack/utils/debounce';
+```
+
+## Available Utilities
+
+This package includes a wide range of utilities for:
+
+- **Array manipulation** (`arrayUtils`) - sorting, grouping, filtering
+- **Async operations** (`asyncQueue`, `parallelAsyncCalls`, `promiseUtils`) - queue management and promise utilities
+- **Type assertions** (`assertions`) - runtime type checking
+- **Caching** (`cache`) - efficient caching with TTL support
+- **Concurrency control** (`concurrentCalls`, `createThrottleController`) - rate limiting and throttling
+- **Object utilities** (`objUtils`) - deep operations on objects
+- **String utilities** (`stringUtils`) - string manipulation and formatting
+- **Math utilities** (`mathUtils`) - mathematical operations and calculations
+- **And many more...**
+
+## Documentation
+
+Comprehensive API documentation is available in the [`docs/`](docs/) folder. Start with the [modules overview](docs/modules.md) to explore all available utilities.
+
+### Generating Documentation
+
+To regenerate the documentation after making changes:
+
+```bash
+pnpm docs
+```
+
+For continuous updates during development:
+
+```bash
+pnpm docs:watch
+```
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Run tests
+pnpm test
+
+# Run tests with UI
+pnpm test:ui
+
+# Build the library
+pnpm build
+
+# Lint code
+pnpm lint
+```
+
+## License
+
+MIT
+
+## Repository
+
+[github:lucasols/utils](https://github.com/lucasols/utils)

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,36 +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) {
-    const cb = async (ctx) => {
-      if (isPromise(fn)) {
-        return await fn;
-      }
-      return fn(ctx);
-    };
-    return this.add((ctx) => (0, import_t_result.resultify)(cb(ctx)), options);
+    return this.add(
+      (ctx) => (0, import_t_result.resultify)(async () => {
+        return fn(ctx);
+      }),
+      options
+    );
   }
   async #processQueue() {
+    if (this.#signal?.aborted) {
+      this.clear();
+      return;
+    }
     if (this.#pending >= this.#concurrency || this.#queue.length === 0) {
       return;
     }
@@ -125,45 +126,54 @@ var AsyncQueue = class {
     }
     const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
     let abortListener;
-    const signalAbortPromise = new Promise((_, reject) => {
-      if (signal) {
-        const error = signal.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError");
-        if (signal.aborted) {
-          reject(error);
-          return;
-        }
-        abortListener = () => {
-          reject(error);
-        };
-        signal.addEventListener("abort", abortListener, { once: true });
-      }
-    });
     try {
-      const taskRunPromise = task.run({ signal, id: task.id });
-      this.events.emit("start", { id: task.id });
+      if (signal?.aborted) {
+        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("This operation was aborted", "AbortError");
+          abortListener = () => {
+            reject(error);
+          };
+          signal.addEventListener("abort", abortListener, { once: true });
+        }
+      });
+      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,
-          error: (0, import_t_result.unknownToError)(error)
+          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);
@@ -191,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();
     }
@@ -215,7 +221,7 @@ var AsyncQueue = class {
     return this.#size;
   }
 };
-var AsyncQueueWithId = class extends AsyncQueue {
+var AsyncQueueWithMeta = class extends AsyncQueue {
   constructor(options) {
     super(options);
   }
@@ -229,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, undefined>;
-declare function createAsyncQueueWithId<T, I, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueueWithId<T, I, E>;
+declare function createAsyncQueue<T, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueue<T, 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, undefined>;
-declare function createAsyncQueueWithId<T, I, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueueWithId<T, I, E>;
+declare function createAsyncQueue<T, E extends ResultValidErrors = Error>(options?: AsyncQueueOptions): AsyncQueue<T, 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,36 +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) {
-    const cb = async (ctx) => {
-      if (isPromise(fn)) {
-        return await fn;
-      }
-      return fn(ctx);
-    };
-    return this.add((ctx) => resultify(cb(ctx)), options);
+    return this.add(
+      (ctx) => resultify(async () => {
+        return fn(ctx);
+      }),
+      options
+    );
   }
   async #processQueue() {
+    if (this.#signal?.aborted) {
+      this.clear();
+      return;
+    }
     if (this.#pending >= this.#concurrency || this.#queue.length === 0) {
       return;
     }
@@ -88,45 +97,54 @@ var AsyncQueue = class {
     }
     const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
     let abortListener;
-    const signalAbortPromise = new Promise((_, reject) => {
-      if (signal) {
-        const error = signal.reason instanceof Error ? signal.reason : new DOMException("Aborted", "AbortError");
-        if (signal.aborted) {
-          reject(error);
-          return;
-        }
-        abortListener = () => {
-          reject(error);
-        };
-        signal.addEventListener("abort", abortListener, { once: true });
-      }
-    });
     try {
-      const taskRunPromise = task.run({ signal, id: task.id });
-      this.events.emit("start", { id: task.id });
+      if (signal?.aborted) {
+        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("This operation was aborted", "AbortError");
+          abortListener = () => {
+            reject(error);
+          };
+          signal.addEventListener("abort", abortListener, { once: true });
+        }
+      });
+      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,
-          error: unknownToError(error)
+          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);
@@ -154,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();
     }
@@ -178,7 +192,7 @@ var AsyncQueue = class {
     return this.#size;
   }
 };
-var AsyncQueueWithId = class extends AsyncQueue {
+var AsyncQueueWithMeta = class extends AsyncQueue {
   constructor(options) {
     super(options);
   }
@@ -192,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/concurrentCalls.cjs

@@ -288,7 +288,7 @@ var ConcurrentCallsWithMetadata = class {
       `${failedProcessing.length}/${total} calls failed: ${truncateArray(
         failedProcessing.map((f) => truncateString(f.error.message, 20)),
         5,
-        (count) => `+${count} more`
+        "..."
       ).join("; ")}`
     ) : null;
     return {

package/lib/concurrentCalls.js

@@ -235,7 +235,7 @@ var ConcurrentCallsWithMetadata = class {
       `${failedProcessing.length}/${total} calls failed: ${truncateArray(
         failedProcessing.map((f) => truncateString(f.error.message, 20)),
         5,
-        (count) => `+${count} more`
+        "..."
       ).join("; ")}`
     ) : null;
     return {

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.0",
+  "version": "3.10.0",
   "license": "MIT",
   "files": [
     "lib"
@@ -179,6 +179,9 @@
     "prettier-plugin-organize-imports": "^4.1.0",
     "tsm": "^2.3.0",
     "tsup": "^8.3.5",
+    "typedoc": "^0.28.4",
+    "typedoc-plugin-markdown": "^4.6.3",
+    "typedoc-plugin-missing-exports": "^4.0.0",
     "typescript": "^5.7.3",
     "typescript-eslint": "^8.21.0",
     "vite": "^6.0.11",
@@ -195,12 +198,15 @@
     "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 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",
     "pre-publish": "./scripts/check-if-is-sync.sh && pnpm build",
     "test:console-fmt": "tsm --no-warnings scripts/testConsoleFmt.ts",
-    "bench:deepEqual": "tsm --no-warnings benchmarks/deepEqual.ts"
+    "bench:deepEqual": "tsm --no-warnings benchmarks/deepEqual.ts",
+    "docs": "typedoc",
+    "docs:watch": "typedoc --watch",
+    "docs:commit": "git add docs && git diff --cached --quiet docs || git commit -m 'docs: update docs'"
   }
 }