@asaidimu/utils-sync 2.0.2 → 2.2.0

package/index.d.mts

@@ -1,3 +1,182 @@
+interface DebouncerOptions {
+    /**
+     * Quiet period in milliseconds. The last-enqueued function runs after
+     * no new calls have arrived for this duration.
+     * @default 300
+     */
+    delay?: number;
+    /**
+     * If true, also fires immediately on the leading edge (first call in a
+     * quiet period), then debounces subsequent calls normally.
+     *
+     * Leading-edge semantics: the leading call fires immediately and clears
+     * _pendingFn. Any calls arriving *while* the leading execution is in flight
+     * register as a new trailing call and will be resolved by the trailing timer
+     * when the quiet period expires. Calls arriving during the leading execution
+     * are never lost.
+     *
+     * @default false
+     */
+    leading?: boolean;
+}
+/**
+ * Result when the debounced function successfully executed.
+ */
+type DebouncerOk<T> = {
+    status: "ok";
+    value: T;
+};
+/**
+ * Result when the debounced function threw an error.
+ */
+type DebouncerError = {
+    status: "error";
+    error: unknown;
+};
+/**
+ * Result when the debounced call was cancelled before execution.
+ */
+type DebouncerCancelled = {
+    status: "cancelled";
+};
+/**
+ * Discriminated union of all possible Debouncer outcomes.
+ *
+ * - `DebouncerOk<T>`: function ran and returned a value.
+ * - `DebouncerError`: function ran and threw an error.
+ * - `DebouncerCancelled`: call was cancelled before it ran.
+ */
+type DebouncerResult<T> = DebouncerOk<T> | DebouncerError | DebouncerCancelled;
+/**
+ * Collapses rapid successive calls into a single execution.
+ *
+ * Each call to `do()` returns a promise that resolves with the result of the
+ * debounced execution — i.e. all callers within the same quiet window share
+ * the same result. The function that actually runs is always the *last* one
+ * enqueued before the delay expires.
+ *
+ * @example
+ * const debounced = new Debouncer({ delay: 200 });
+ * // Called rapidly three times — only the last fn runs.
+ * const [a, b, c] = await Promise.all([
+ *   debounced.do(() => fetch("/api/search?q=h")),
+ *   debounced.do(() => fetch("/api/search?q=he")),
+ *   debounced.do(() => fetch("/api/search?q=hel")),
+ * ]);
+ * // a.status === "ok" and a.value is the result of the third fetch.
+ * // b and c share the same result as a.
+ */
+declare class Debouncer<T = void> {
+    private _delay;
+    private _leading;
+    private _timer;
+    private _pendingFn;
+    private _pendingResolvers;
+    private _leadingFired;
+    constructor(options?: DebouncerOptions);
+    /**
+     * Enqueues a function and returns a promise that resolves with its result.
+     *
+     * All callers within the same quiet window share the same result — the
+     * function that actually runs is the *last* one enqueued before the delay
+     * expires. Use this when you need the return value of the debounced call.
+     *
+     * For fire-and-forget use (void fns, event handlers), prefer `fire()` to
+     * avoid unhandled-promise-rejection warnings and make intent explicit.
+     *
+     * @param fn - The function to debounce.
+     * @returns A promise resolving with a DebouncerResult discriminated union.
+     */
+    do(fn: () => Promise<T> | T): Promise<DebouncerResult<T>>;
+    /**
+     * Enqueues a function without returning a promise (fire-and-forget).
+     *
+     * Identical debounce semantics to `do()` — the last-enqueued function runs
+     * after the quiet period. Use this for void callbacks, DOM event handlers,
+     * or any caller that doesn't care about the result. No dangling promise,
+     * no unhandled-rejection risk.
+     *
+     * @param fn - The function to debounce.
+     */
+    fire(fn: () => Promise<T> | T): void;
+    /**
+     * Shared enqueue logic for both `do()` and `fire()`.
+     *
+     */
+    private _enqueue;
+    /**
+     * Immediately cancels any pending debounced execution.
+     * All waiting callers resolve with `{ status: "cancelled" }`.
+     */
+    cancel(): void;
+    /**
+     * Immediately executes the pending function (if any), bypassing the remaining delay.
+     * All waiting callers receive the result.
+     */
+    flush(): Promise<DebouncerResult<T> | null>;
+    /** Returns true if a debounced call is currently pending. */
+    pending(): boolean;
+    /**
+     * Executes the latest pending function and resolves all waiting callers.
+     */
+    private _fire;
+}
+
+/** Represents all errors within the sync system */
+declare class SyncError extends Error {
+    constructor(message: string, cause?: unknown);
+}
+declare class TimeoutError extends SyncError {
+    constructor(message?: string);
+}
+declare class OnceExecutionConflict extends SyncError {
+    constructor(cause?: unknown);
+}
+declare class SerializerExecutionDone extends SyncError {
+    constructor(cause?: unknown);
+}
+
+/**
+ * A one-shot gate that starts closed and opens exactly once.
+ *
+ * All current and future `wait()` callers resolve immediately once `open()` is
+ * called. Unlike Once, Latch carries no return value and has no retry logic —
+ * it is a pure signalling primitive.
+ *
+ * Typical use: coordinate startup, signal that an initialisation phase is done,
+ * or gate downstream work on a single event.
+ *
+ * @example
+ * const ready = new Latch();
+ * // Consumer
+ * await ready.wait();
+ * // Producer (elsewhere)
+ * ready.open();
+ */
+declare class Latch {
+    private _open;
+    private _resolve;
+    private _promise;
+    constructor();
+    /**
+     * Opens the latch. All current and future waiters resolve immediately.
+     * Calling open() more than once is a no-op.
+     */
+    open(): void;
+    /**
+     * Returns a promise that resolves when the latch is opened.
+     * If already open, resolves on the next microtask checkpoint.
+     *
+     * @param timeout - Optional maximum wait time in milliseconds.
+     * @throws {TimeoutError} If the latch does not open within the timeout.
+     */
+    wait(timeout?: number): Promise<void>;
+    /**
+     * Synchronously checks whether the latch has been opened.
+     */
+    isOpen(): boolean;
+}
+
 interface MutexOptions {
     /**
      * Maximum number of pending requests allowed in the queue.
@@ -64,61 +243,7 @@ declare class Mutex {
     /** Returns the number of operations waiting for the lock. */
     pending(): number;
 }
-interface SemaphoreOptions extends MutexOptions {
-    /**
-     * Number of concurrent holders allowed.
-     * Inherits `capacity` and `yieldMode` from MutexOptions.
-     * @default 1 (equivalent to a Mutex)
-     */
-    slots?: number;
-}
-/**
- * A counting semaphore — generalises Mutex to allow up to N concurrent holders.
- *
- * Useful for rate-limiting concurrency: e.g. "at most 3 in-flight HTTP requests".
- * With slots=1 it behaves identically to Mutex.
- *
- * Accepts the same `capacity` and `yieldMode` options as Mutex, plus `slots`.
- */
-declare class Semaphore {
-    private _slots;
-    private _available;
-    private _capacity;
-    private _yieldMode;
-    private waiters;
-    constructor(options?: SemaphoreOptions);
-    /**
-     * Acquires one slot. If all slots are taken, waits until one is released.
-     *
-     * @param timeout - Optional maximum wait time in milliseconds.
-     * @throws {TimeoutError} If a slot cannot be acquired within the timeout.
-     * @throws {Error} If the wait queue is full.
-     */
-    acquire(timeout?: number): Promise<void>;
-    /**
-     * Attempts to acquire a slot without waiting.
-     * @returns `true` if a slot was acquired, `false` otherwise.
-     */
-    tryAcquire(): boolean;
-    /**
-     * Releases one slot. If waiters are queued, the next one is scheduled
-     * according to yieldMode.
-     *
-     * @throws {Error} If no slot is currently held (release without acquire).
-     */
-    release(): void;
-    /**
-     * Runs a function with one acquired slot, releasing it when done.
-     * Convenience wrapper — prefer this over manual acquire/release.
-     */
-    run<T>(fn: () => Promise<T> | T, timeout?: number): Promise<T>;
-    /** Number of slots currently free. */
-    available(): number;
-    /** Number of callers waiting for a slot. */
-    pending(): number;
-    /** Total slot count (as configured). */
-    slots(): number;
-}
+
 type OnceResult<T> = {
     value: T | null;
     error?: unknown;
@@ -161,13 +286,6 @@ declare class Once<T = void> {
      * @returns The result of the execution.
      */
     doSync(fn: () => T): OnceResult<T>;
-    /**
-     * Returns true if the operation has completed (success or non-retryable failure)
-     * and the internal promise has been cleared.
-     *
-     * This is the canonical "safe to read" check — prefer it over `done()`.
-     */
-    ready(): boolean;
     /**
      * Returns true if the operation is currently executing.
      *
@@ -210,116 +328,18 @@ declare class Once<T = void> {
      */
     private _awaitWithTimeout;
 }
-type SerializerResult<T> = {
-    value: T | null;
-    error?: unknown;
-};
-interface SerializerOptions {
-    /**
-     * Max items in queue. If full, .do() returns an error immediately.
-     * @default 1000
-     */
-    capacity?: number;
+
+interface RWMutexOptions {
     /**
-     * Yield mode for the internal mutex. Defaults to "macrotask" for
-     * coarse-grained serializers. Use "microtask" for fine-grained
-     * latency-sensitive serializers.
-     */
-    yieldMode?: "macrotask" | "microtask";
-}
-/**
- * Ensures tasks are executed sequentially (FIFO).
- * Maintains the result of the last successful execution.
- * Includes backpressure protection via configurable queue capacity.
- */
-declare class Serializer<T = void> {
-    private mutex;
-    private _done;
-    private _lastValue;
-    private _lastError;
-    private _hasRun;
-    constructor(options?: SerializerOptions);
-    /**
-     * Enqueue a function to be executed after all previous tasks complete.
-     *
-     * @param fn - The function to execute.
-     * @param timeout - Max time to wait to acquire the lock.
-     * @returns Object containing the value or error.
-     */
-    do(fn: () => Promise<T> | T, timeout?: number): Promise<SerializerResult<T | null>>;
-    /**
-     * Returns the result of the last execution.
-     *
-     * Returns `{ value: null, error: undefined }` both when the serializer has
-     * never run and when it ran and returned null — use `hasRun()` to distinguish
-     * these two cases.
-     */
-    peek(): SerializerResult<T | null>;
-    /**
-     * Returns true if at least one task has been executed (successfully or not).
-     */
-    hasRun(): boolean;
-    /**
-     * Permanently closes the serializer.
-     * Subsequent calls to `do()` will fail immediately with SerializerExecutionDone.
-     */
-    close(): void;
-    /** Returns the number of tasks currently waiting. */
-    pending(): number;
-    /** Returns true if a task is currently executing. */
-    running(): boolean;
-}
-/**
- * A one-shot gate that starts closed and opens exactly once.
- *
- * All current and future `wait()` callers resolve immediately once `open()` is
- * called. Unlike Once, Latch carries no return value and has no retry logic —
- * it is a pure signalling primitive.
- *
- * Typical use: coordinate startup, signal that an initialisation phase is done,
- * or gate downstream work on a single event.
- *
- * @example
- * const ready = new Latch();
- * // Consumer
- * await ready.wait();
- * // Producer (elsewhere)
- * ready.open();
- */
-declare class Latch {
-    private _open;
-    private _resolve;
-    private _promise;
-    constructor();
-    /**
-     * Opens the latch. All current and future waiters resolve immediately.
-     * Calling open() more than once is a no-op.
-     */
-    open(): void;
-    /**
-     * Returns a promise that resolves when the latch is opened.
-     * If already open, resolves on the next microtask checkpoint.
-     *
-     * @param timeout - Optional maximum wait time in milliseconds.
-     * @throws {TimeoutError} If the latch does not open within the timeout.
-     */
-    wait(timeout?: number): Promise<void>;
-    /**
-     * Synchronously checks whether the latch has been opened.
-     */
-    isOpen(): boolean;
-}
-interface RWMutexOptions {
-    /**
-     * Controls how lock handoff is scheduled when a waiter is unblocked.
-     *
-     * - `"microtask"` (default): Uses queueMicrotask(fn). Near-zero latency
-     *   between handoffs. Appropriate for RWMutex because readers are woken in
-     *   bulk and writers are rarely contended enough to cause starvation.
-     *
-     * - `"macrotask"`: Uses setTimeout(fn, 0) to yield to the event loop between
-     *   handoffs. Use if you observe microtask starvation under extreme write
-     *   contention on this specific lock.
+     * Controls how lock handoff is scheduled when a waiter is unblocked.
+     *
+     * - `"microtask"` (default): Uses queueMicrotask(fn). Near-zero latency
+     *   between handoffs. Appropriate for RWMutex because readers are woken in
+     *   bulk and writers are rarely contended enough to cause starvation.
+     *
+     * - `"macrotask"`: Uses setTimeout(fn, 0) to yield to the event loop between
+     *   handoffs. Use if you observe microtask starvation under extreme write
+     *   contention on this specific lock.
      */
     yieldMode?: "macrotask" | "microtask";
 }
@@ -402,128 +422,121 @@ declare class RWMutex {
      */
     private _schedule;
 }
-interface DebouncerOptions {
-    /**
-     * Quiet period in milliseconds. The last-enqueued function runs after
-     * no new calls have arrived for this duration.
-     * @default 300
-     */
-    delay?: number;
+
+interface SemaphoreOptions extends MutexOptions {
     /**
-     * If true, also fires immediately on the leading edge (first call in a
-     * quiet period), then debounces subsequent calls normally.
-     *
-     * Leading-edge semantics: the leading call fires immediately and clears
-     * _pendingFn. Any calls arriving *while* the leading execution is in flight
-     * register as a new trailing call and will be resolved by the trailing timer
-     * when the quiet period expires. Calls arriving during the leading execution
-     * are never lost.
-     *
-     * @default false
+     * Number of concurrent holders allowed.
+     * Inherits `capacity` and `yieldMode` from MutexOptions.
+     * @default 1 (equivalent to a Mutex)
      */
-    leading?: boolean;
+    slots?: number;
 }
 /**
- * Result when the debounced function successfully executed.
- */
-type DebouncerOk<T> = {
-    status: "ok";
-    value: T;
-};
-/**
- * Result when the debounced function threw an error.
- */
-type DebouncerError = {
-    status: "error";
-    error: unknown;
-};
-/**
- * Result when the debounced call was cancelled before execution.
- */
-type DebouncerCancelled = {
-    status: "cancelled";
-};
-/**
- * Discriminated union of all possible Debouncer outcomes.
- *
- * - `DebouncerOk<T>`: function ran and returned a value.
- * - `DebouncerError`: function ran and threw an error.
- * - `DebouncerCancelled`: call was cancelled before it ran.
- */
-type DebouncerResult<T> = DebouncerOk<T> | DebouncerError | DebouncerCancelled;
-/**
- * Collapses rapid successive calls into a single execution.
+ * A counting semaphore — generalises Mutex to allow up to N concurrent holders.
  *
- * Each call to `do()` returns a promise that resolves with the result of the
- * debounced execution — i.e. all callers within the same quiet window share
- * the same result. The function that actually runs is always the *last* one
- * enqueued before the delay expires.
+ * Useful for rate-limiting concurrency: e.g. "at most 3 in-flight HTTP requests".
+ * With slots=1 it behaves identically to Mutex.
  *
- * @example
- * const debounced = new Debouncer({ delay: 200 });
- * // Called rapidly three times — only the last fn runs.
- * const [a, b, c] = await Promise.all([
- *   debounced.do(() => fetch("/api/search?q=h")),
- *   debounced.do(() => fetch("/api/search?q=he")),
- *   debounced.do(() => fetch("/api/search?q=hel")),
- * ]);
- * // a.status === "ok" and a.value is the result of the third fetch.
- * // b and c share the same result as a.
+ * Accepts the same `capacity` and `yieldMode` options as Mutex, plus `slots`.
  */
-declare class Debouncer<T = void> {
-    private _delay;
-    private _leading;
-    private _timer;
-    private _pendingFn;
-    private _pendingResolvers;
-    private _leadingFired;
-    constructor(options?: DebouncerOptions);
+declare class Semaphore {
+    private _slots;
+    private _available;
+    private _capacity;
+    private _yieldMode;
+    private waiters;
+    constructor(options?: SemaphoreOptions);
     /**
-     * Enqueues a function and returns a promise that resolves with its result.
-     *
-     * All callers within the same quiet window share the same result — the
-     * function that actually runs is the *last* one enqueued before the delay
-     * expires. Use this when you need the return value of the debounced call.
-     *
-     * For fire-and-forget use (void fns, event handlers), prefer `fire()` to
-     * avoid unhandled-promise-rejection warnings and make intent explicit.
+     * Acquires one slot. If all slots are taken, waits until one is released.
      *
-     * @param fn - The function to debounce.
-     * @returns A promise resolving with a DebouncerResult discriminated union.
+     * @param timeout - Optional maximum wait time in milliseconds.
+     * @throws {TimeoutError} If a slot cannot be acquired within the timeout.
+     * @throws {Error} If the wait queue is full.
      */
-    do(fn: () => Promise<T> | T): Promise<DebouncerResult<T>>;
+    acquire(timeout?: number): Promise<void>;
     /**
-     * Enqueues a function without returning a promise (fire-and-forget).
-     *
-     * Identical debounce semantics to `do()` — the last-enqueued function runs
-     * after the quiet period. Use this for void callbacks, DOM event handlers,
-     * or any caller that doesn't care about the result. No dangling promise,
-     * no unhandled-rejection risk.
+     * Attempts to acquire a slot without waiting.
+     * @returns `true` if a slot was acquired, `false` otherwise.
+     */
+    tryAcquire(): boolean;
+    /**
+     * Releases one slot. If waiters are queued, the next one is scheduled
+     * according to yieldMode.
      *
-     * @param fn - The function to debounce.
+     * @throws {Error} If no slot is currently held (release without acquire).
      */
-    fire(fn: () => Promise<T> | T): void;
+    release(): void;
     /**
-     * Shared enqueue logic for both `do()` and `fire()`.
+     * Runs a function with one acquired slot, releasing it when done.
+     * Convenience wrapper — prefer this over manual acquire/release.
+     */
+    run<T>(fn: () => Promise<T> | T, timeout?: number): Promise<T>;
+    /** Number of slots currently free. */
+    available(): number;
+    /** Number of callers waiting for a slot. */
+    pending(): number;
+    /** Total slot count (as configured). */
+    slots(): number;
+}
+
+type SerializerResult<T> = {
+    value: T | null;
+    error?: unknown;
+};
+interface SerializerOptions {
+    /**
+     * Max items in queue. If full, .do() returns an error immediately.
+     * @default 1000
+     */
+    capacity?: number;
+    /**
+     * Yield mode for the internal mutex. Defaults to "macrotask" for
+     * coarse-grained serializers. Use "microtask" for fine-grained
+     * latency-sensitive serializers.
+     */
+    yieldMode?: "macrotask" | "microtask";
+}
+/**
+ * Ensures tasks are executed sequentially (FIFO).
+ * Maintains the result of the last successful execution.
+ * Includes backpressure protection via configurable queue capacity.
+ */
+declare class Serializer<T = void> {
+    private mutex;
+    private _done;
+    private _lastValue;
+    private _lastError;
+    private _hasRun;
+    constructor(options?: SerializerOptions);
+    /**
+     * Enqueue a function to be executed after all previous tasks complete.
      *
+     * @param fn - The function to execute.
+     * @param timeout - Max time to wait to acquire the lock.
+     * @returns Object containing the value or error.
      */
-    private _enqueue;
+    do(fn: () => Promise<T> | T, timeout?: number): Promise<SerializerResult<T | null>>;
     /**
-     * Immediately cancels any pending debounced execution.
-     * All waiting callers resolve with `{ status: "cancelled" }`.
+     * Returns the result of the last execution.
+     *
+     * Returns `{ value: null, error: undefined }` both when the serializer has
+     * never run and when it ran and returned null — use `hasRun()` to distinguish
+     * these two cases.
      */
-    cancel(): void;
+    peek(): SerializerResult<T | null>;
     /**
-     * Immediately executes the pending function (if any), bypassing the remaining delay.
-     * All waiting callers receive the result.
+     * Returns true if at least one task has been executed (successfully or not).
      */
-    flush(): Promise<DebouncerResult<T> | null>;
-    /** Returns true if a debounced call is currently pending. */
-    pending(): boolean;
+    hasRun(): boolean;
     /**
-     * Executes the latest pending function and resolves all waiting callers.
+     * Permanently closes the serializer.
+     * Subsequent calls to `do()` will fail immediately with SerializerExecutionDone.
      */
-    private _fire;
+    close(): void;
+    /** Returns the number of tasks currently waiting. */
+    pending(): number;
+    /** Returns true if a task is currently executing. */
+    running(): boolean;
 }
 
-export { Debouncer, type DebouncerCancelled, type DebouncerError, type DebouncerOk, type DebouncerOptions, type DebouncerResult, Latch, Mutex, type MutexOptions, Once, type OnceResult, RWMutex, type RWMutexOptions, Semaphore, type SemaphoreOptions, Serializer, type SerializerOptions, type SerializerResult };
+export { Debouncer, type DebouncerCancelled, type DebouncerError, type DebouncerOk, type DebouncerOptions, type DebouncerResult, Latch, Mutex, type MutexOptions, Once, OnceExecutionConflict, type OnceResult, RWMutex, type RWMutexOptions, Semaphore, type SemaphoreOptions, Serializer, SerializerExecutionDone, type SerializerOptions, type SerializerResult, SyncError, TimeoutError };