@asaidimu/utils-sync 1.1.0 → 2.0.0

package/index.d.mts

@@ -11,14 +11,14 @@ interface MutexOptions {
      * - `"macrotask"` (default): Uses setTimeout(fn, 0) to yield to the event
      *   loop between handoffs. Prevents microtask starvation under heavy
      *   contention — I/O, rendering, and other macrotasks can run between
-     *   lock acquisitions. Use for invalidationSerializer and other
-     *   coarse-grained serializers.
+     *   lock acquisitions. Use for Serializer and other coarse-grained
+     *   serializers.
      *
      * - `"microtask"`: Uses queueMicrotask(fn) for handoff. Near-zero latency
      *   between acquisitions — no macrotask delay. Safe when you need
      *   back-to-back operations to complete as fast as possible and starvation
-     *   is not a concern (e.g. buildOnce, streamSerializer where builds are
-     *   infrequent and latency matters more than fairness).
+     *   is not a concern (e.g. Once, Semaphore where builds are infrequent
+     *   and latency matters more than fairness).
      */
     yieldMode?: "macrotask" | "microtask";
 }
@@ -51,6 +51,11 @@ declare class Mutex {
     tryLock(): boolean;
     /**
      * Releases the lock, scheduling the next waiter according to yieldMode.
+     *
+     * When a waiter exists, `_locked` intentionally remains `true` — ownership
+     * transfers directly to the next waiter without ever clearing the flag.
+     * Only when the queue is empty is `_locked` set to false.
+     *
      * @throws {Error} If the mutex is not currently locked.
      */
     unlock(): void;
@@ -59,6 +64,61 @@ 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;
@@ -92,14 +152,28 @@ declare class Once<T = void> {
      * @param timeout - Max wait time in ms (includes lock wait + execution time).
      */
     do(fn: () => Promise<T> | T, timeout?: number): Promise<OnceResult<T>>;
+    /**
+     * Executes the function synchronously if it hasn't been executed yet.
+     * If an async operation is pending or the lock is contended, it will fail immediately.
+     * The failure is returned as an error state, OR thrown if `throws: true` is configured.
+     *
+     * @param fn - The synchronous function to execute.
+     * @returns The result of the execution.
+     */
+    doSync(fn: () => T): OnceResult<T>;
     /**
      * Returns true if the operation has completed (success or non-retryable failure)
-     * and is not currently executing.
-     * Replaces the previous `done() && !running()` two-call pattern.
+     * and the internal promise has been cleared.
+     *
+     * This is the canonical "safe to read" check — prefer it over `done()`.
      */
     isReady(): boolean;
     /**
      * Returns true if the operation is currently executing.
+     *
+     * Uses isReady() as the canonical check: running is its logical complement
+     * when a promise is in flight. This correctly handles the brief window where
+     * _done=true but the promise hasn't been cleared yet in finally.
      */
     running(): boolean;
     /**
@@ -113,16 +187,27 @@ declare class Once<T = void> {
     get(): T | null;
     /**
      * Resets the instance, allowing the action to run again on the next call.
+     *
+     * @throws {Error} If called while an operation is currently executing,
+     * as this would leave the in-flight promise in an inconsistent state.
      */
     reset(): void;
     /**
-     * Returns the underlying promise if running or done, null otherwise.
+     * Returns the in-flight execution promise if one is currently running, null otherwise.
+     *
+     * Use this to join an in-progress operation without triggering a new one.
      */
-    resolved(): Promise<OnceResult<T>> | null;
+    currentExecution(): Promise<OnceResult<T>> | null;
     /**
      * Returns true if the operation has finished (success or final failure).
      */
     done(): boolean;
+    /**
+     * Awaits a promise with an optional timeout.
+     *
+     * We clear the timer on the winning branch, consistent with the
+     * Mutex/Semaphore/Latch timeout pattern throughout this module.
+     */
     private _awaitWithTimeout;
 }
 type SerializerResult<T> = {
@@ -137,8 +222,8 @@ interface SerializerOptions {
     capacity?: number;
     /**
      * Yield mode for the internal mutex. Defaults to "macrotask" for
-     * coarse-grained serializers (invalidationSerializer). Use "microtask"
-     * for fine-grained latency-sensitive serializers (streamSerializer).
+     * coarse-grained serializers. Use "microtask" for fine-grained
+     * latency-sensitive serializers.
      */
     yieldMode?: "macrotask" | "microtask";
 }
@@ -152,6 +237,7 @@ declare class Serializer<T = void> {
     private _done;
     private _lastValue;
     private _lastError;
+    private _hasRun;
     constructor(options?: SerializerOptions);
     /**
      * Enqueue a function to be executed after all previous tasks complete.
@@ -161,8 +247,18 @@ declare class Serializer<T = void> {
      * @returns Object containing the value or error.
      */
     do(fn: () => Promise<T> | T, timeout?: number): Promise<SerializerResult<T | null>>;
-    /** Returns the result of the last successful execution. */
+    /**
+     * 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.
@@ -173,5 +269,261 @@ declare class Serializer<T = void> {
     /** 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.
+     */
+    yieldMode?: "macrotask" | "microtask";
+}
+/**
+ * A read-write mutex with writer preference.
+ *
+ * - Multiple readers can hold the lock concurrently.
+ * - Writers get exclusive access — no readers or other writers.
+ * - Writer preference: once a writer is waiting, new readers queue behind it.
+ *   This prevents writer starvation under read-heavy loads.
+ *
+ * Readers should call `rlock()` / `runlock()`.
+ * Writers should call `lock()` / `unlock()`.
+ * Prefer the `read()` and `write()` convenience wrappers to avoid lock leaks.
+ */
+declare class RWMutex {
+    private _readers;
+    private _writeLocked;
+    private _pendingWriters;
+    private _yieldMode;
+    private readerWaiters;
+    private writerWaiters;
+    constructor(options?: RWMutexOptions);
+    /**
+     * Acquires a read lock. Blocks if a writer holds or is waiting for the lock.
+     *
+     * @param timeout - Optional maximum wait time in milliseconds.
+     * @throws {TimeoutError} If the read lock cannot be acquired within the timeout.
+     */
+    rlock(timeout?: number): Promise<void>;
+    /**
+     * Releases a read lock.
+     * @throws {Error} If no read lock is currently held.
+     */
+    runlock(): void;
+    /**
+     * Acquires the write lock. Blocks until all current readers and any prior
+     * writers have finished.
+     *
+     * @param timeout - Optional maximum wait time in milliseconds.
+     * @throws {TimeoutError} If the write lock cannot be acquired within the timeout.
+     */
+    lock(timeout?: number): Promise<void>;
+    /**
+     * Releases the write lock.
+     * Wakes the next pending writer if one exists; otherwise wakes all pending readers.
+     *
+     * @throws {Error} If no write lock is currently held.
+     */
+    unlock(): void;
+    /**
+     * Runs a function under a read lock, releasing it when done.
+     * Prefer this over manual rlock/runlock to avoid lock leaks.
+     */
+    read<T>(fn: () => Promise<T> | T, timeout?: number): Promise<T>;
+    /**
+     * Runs a function under the write lock, releasing it when done.
+     * Prefer this over manual lock/unlock to avoid lock leaks.
+     */
+    write<T>(fn: () => Promise<T> | T, timeout?: number): Promise<T>;
+    /** Returns true if the write lock is currently held. */
+    writeLocked(): boolean;
+    /** Returns the number of active read lock holders. */
+    readers(): number;
+    /** Returns the number of writers currently waiting for the lock. */
+    pendingWriters(): number;
+    /** Returns the number of readers currently waiting for the lock. */
+    pendingReaders(): number;
+    /**
+     * Wakes the next writer if the lock is free and a writer is waiting.
+     * Returns true if a writer was woken, false otherwise.
+     */
+    private _tryWakeWriter;
+    /**
+     * Wakes all pending readers (called when a writer releases and no writers are queued).
+     */
+    private _wakeAllReaders;
+    /**
+     * Schedules a waiter callback according to the configured yieldMode.
+     */
+    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;
+    /**
+     * 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;
+}
 
-export { Mutex, type MutexOptions, Once, type OnceResult, Serializer, type SerializerOptions, type SerializerResult };
+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 };

package/index.d.ts

@@ -11,14 +11,14 @@ interface MutexOptions {
      * - `"macrotask"` (default): Uses setTimeout(fn, 0) to yield to the event
      *   loop between handoffs. Prevents microtask starvation under heavy
      *   contention — I/O, rendering, and other macrotasks can run between
-     *   lock acquisitions. Use for invalidationSerializer and other
-     *   coarse-grained serializers.
+     *   lock acquisitions. Use for Serializer and other coarse-grained
+     *   serializers.
      *
      * - `"microtask"`: Uses queueMicrotask(fn) for handoff. Near-zero latency
      *   between acquisitions — no macrotask delay. Safe when you need
      *   back-to-back operations to complete as fast as possible and starvation
-     *   is not a concern (e.g. buildOnce, streamSerializer where builds are
-     *   infrequent and latency matters more than fairness).
+     *   is not a concern (e.g. Once, Semaphore where builds are infrequent
+     *   and latency matters more than fairness).
      */
     yieldMode?: "macrotask" | "microtask";
 }
@@ -51,6 +51,11 @@ declare class Mutex {
     tryLock(): boolean;
     /**
      * Releases the lock, scheduling the next waiter according to yieldMode.
+     *
+     * When a waiter exists, `_locked` intentionally remains `true` — ownership
+     * transfers directly to the next waiter without ever clearing the flag.
+     * Only when the queue is empty is `_locked` set to false.
+     *
      * @throws {Error} If the mutex is not currently locked.
      */
     unlock(): void;
@@ -59,6 +64,61 @@ 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;
@@ -92,14 +152,28 @@ declare class Once<T = void> {
      * @param timeout - Max wait time in ms (includes lock wait + execution time).
      */
     do(fn: () => Promise<T> | T, timeout?: number): Promise<OnceResult<T>>;
+    /**
+     * Executes the function synchronously if it hasn't been executed yet.
+     * If an async operation is pending or the lock is contended, it will fail immediately.
+     * The failure is returned as an error state, OR thrown if `throws: true` is configured.
+     *
+     * @param fn - The synchronous function to execute.
+     * @returns The result of the execution.
+     */
+    doSync(fn: () => T): OnceResult<T>;
     /**
      * Returns true if the operation has completed (success or non-retryable failure)
-     * and is not currently executing.
-     * Replaces the previous `done() && !running()` two-call pattern.
+     * and the internal promise has been cleared.
+     *
+     * This is the canonical "safe to read" check — prefer it over `done()`.
      */
     isReady(): boolean;
     /**
      * Returns true if the operation is currently executing.
+     *
+     * Uses isReady() as the canonical check: running is its logical complement
+     * when a promise is in flight. This correctly handles the brief window where
+     * _done=true but the promise hasn't been cleared yet in finally.
      */
     running(): boolean;
     /**
@@ -113,16 +187,27 @@ declare class Once<T = void> {
     get(): T | null;
     /**
      * Resets the instance, allowing the action to run again on the next call.
+     *
+     * @throws {Error} If called while an operation is currently executing,
+     * as this would leave the in-flight promise in an inconsistent state.
      */
     reset(): void;
     /**
-     * Returns the underlying promise if running or done, null otherwise.
+     * Returns the in-flight execution promise if one is currently running, null otherwise.
+     *
+     * Use this to join an in-progress operation without triggering a new one.
      */
-    resolved(): Promise<OnceResult<T>> | null;
+    currentExecution(): Promise<OnceResult<T>> | null;
     /**
      * Returns true if the operation has finished (success or final failure).
      */
     done(): boolean;
+    /**
+     * Awaits a promise with an optional timeout.
+     *
+     * We clear the timer on the winning branch, consistent with the
+     * Mutex/Semaphore/Latch timeout pattern throughout this module.
+     */
     private _awaitWithTimeout;
 }
 type SerializerResult<T> = {
@@ -137,8 +222,8 @@ interface SerializerOptions {
     capacity?: number;
     /**
      * Yield mode for the internal mutex. Defaults to "macrotask" for
-     * coarse-grained serializers (invalidationSerializer). Use "microtask"
-     * for fine-grained latency-sensitive serializers (streamSerializer).
+     * coarse-grained serializers. Use "microtask" for fine-grained
+     * latency-sensitive serializers.
      */
     yieldMode?: "macrotask" | "microtask";
 }
@@ -152,6 +237,7 @@ declare class Serializer<T = void> {
     private _done;
     private _lastValue;
     private _lastError;
+    private _hasRun;
     constructor(options?: SerializerOptions);
     /**
      * Enqueue a function to be executed after all previous tasks complete.
@@ -161,8 +247,18 @@ declare class Serializer<T = void> {
      * @returns Object containing the value or error.
      */
     do(fn: () => Promise<T> | T, timeout?: number): Promise<SerializerResult<T | null>>;
-    /** Returns the result of the last successful execution. */
+    /**
+     * 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.
@@ -173,5 +269,261 @@ declare class Serializer<T = void> {
     /** 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.
+     */
+    yieldMode?: "macrotask" | "microtask";
+}
+/**
+ * A read-write mutex with writer preference.
+ *
+ * - Multiple readers can hold the lock concurrently.
+ * - Writers get exclusive access — no readers or other writers.
+ * - Writer preference: once a writer is waiting, new readers queue behind it.
+ *   This prevents writer starvation under read-heavy loads.
+ *
+ * Readers should call `rlock()` / `runlock()`.
+ * Writers should call `lock()` / `unlock()`.
+ * Prefer the `read()` and `write()` convenience wrappers to avoid lock leaks.
+ */
+declare class RWMutex {
+    private _readers;
+    private _writeLocked;
+    private _pendingWriters;
+    private _yieldMode;
+    private readerWaiters;
+    private writerWaiters;
+    constructor(options?: RWMutexOptions);
+    /**
+     * Acquires a read lock. Blocks if a writer holds or is waiting for the lock.
+     *
+     * @param timeout - Optional maximum wait time in milliseconds.
+     * @throws {TimeoutError} If the read lock cannot be acquired within the timeout.
+     */
+    rlock(timeout?: number): Promise<void>;
+    /**
+     * Releases a read lock.
+     * @throws {Error} If no read lock is currently held.
+     */
+    runlock(): void;
+    /**
+     * Acquires the write lock. Blocks until all current readers and any prior
+     * writers have finished.
+     *
+     * @param timeout - Optional maximum wait time in milliseconds.
+     * @throws {TimeoutError} If the write lock cannot be acquired within the timeout.
+     */
+    lock(timeout?: number): Promise<void>;
+    /**
+     * Releases the write lock.
+     * Wakes the next pending writer if one exists; otherwise wakes all pending readers.
+     *
+     * @throws {Error} If no write lock is currently held.
+     */
+    unlock(): void;
+    /**
+     * Runs a function under a read lock, releasing it when done.
+     * Prefer this over manual rlock/runlock to avoid lock leaks.
+     */
+    read<T>(fn: () => Promise<T> | T, timeout?: number): Promise<T>;
+    /**
+     * Runs a function under the write lock, releasing it when done.
+     * Prefer this over manual lock/unlock to avoid lock leaks.
+     */
+    write<T>(fn: () => Promise<T> | T, timeout?: number): Promise<T>;
+    /** Returns true if the write lock is currently held. */
+    writeLocked(): boolean;
+    /** Returns the number of active read lock holders. */
+    readers(): number;
+    /** Returns the number of writers currently waiting for the lock. */
+    pendingWriters(): number;
+    /** Returns the number of readers currently waiting for the lock. */
+    pendingReaders(): number;
+    /**
+     * Wakes the next writer if the lock is free and a writer is waiting.
+     * Returns true if a writer was woken, false otherwise.
+     */
+    private _tryWakeWriter;
+    /**
+     * Wakes all pending readers (called when a writer releases and no writers are queued).
+     */
+    private _wakeAllReaders;
+    /**
+     * Schedules a waiter callback according to the configured yieldMode.
+     */
+    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;
+    /**
+     * 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;
+}
 
-export { Mutex, type MutexOptions, Once, type OnceResult, Serializer, type SerializerOptions, type SerializerResult };
+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 };

package/index.js

@@ -1 +1 @@
-"use strict";var t=class t extends Error{constructor(e,r){super(e,{cause:r}),this.name="SyncError",Object.setPrototypeOf(this,t.prototype)}},e=class extends t{constructor(t){super(`[ArtifactContainer] Operation timed out: ${t}`)}},r=class extends t{constructor(t){super("[Serializer] The serializer has been marked as done!",t)}},i=class{_locked=!1;_capacity;_yieldMode;waiters=[];constructor(t){this._capacity=t?.capacity??1/0,this._yieldMode=t?.yieldMode??"macrotask"}async lock(t){if(!this._locked)return void(this._locked=!0);if(this.waiters.length>=this._capacity)throw new Error(`Mutex queue is full (capacity: ${this._capacity})`);let r;const i=new Promise((t=>r=t));this.waiters.push(r),null!=t?await Promise.race([i,new Promise(((i,s)=>setTimeout((()=>{const t=this.waiters.indexOf(r);-1!==t&&this.waiters.splice(t,1),s(new e("Mutex lock timed out"))}),t)))]):await i}tryLock(){return!this._locked&&(this._locked=!0,!0)}unlock(){if(!this._locked)throw new Error("Mutex is not locked");const t=this.waiters.shift();t?"microtask"===this._yieldMode?queueMicrotask(t):setTimeout(t,0):this._locked=!1}locked(){return this._locked}pending(){return this.waiters.length}};exports.Mutex=i,exports.Once=class{mutex=new i({yieldMode:"microtask"});promise=null;_value=null;_error;_done=!1;retry;throws;constructor({retry:t,throws:e}={}){this.retry=Boolean(t),this.throws=Boolean(e)}async do(t,e){return this._done?this.peek():this.promise?this._awaitWithTimeout(this.promise,e,"Once do() timed out"):(await this.mutex.lock(),this.promise?(this.mutex.unlock(),this._awaitWithTimeout(this.promise,e,"Once do() timed out")):(this.promise=(async()=>{try{const e=await t();this._value=e,this._done=!0}catch(t){if(this._error=t,this.retry||(this._done=!0),this.throws)throw t}finally{this.promise=null}return this.peek()})(),this.mutex.unlock(),this._awaitWithTimeout(this.promise,e,"Once do() timed out")))}isReady(){return this._done&&null===this.promise}running(){return null!==this.promise&&!this._done}peek(){return{value:this._value,error:this._error}}get(){if(!this._done)throw new Error("Once operation is not yet complete");if(this._error)throw this._error;return this._value}reset(){this._done=!1,this.promise=null,this._value=null,this._error=void 0}resolved(){return this.promise}done(){return this._done}_awaitWithTimeout(t,r,i="Operation timed out"){return null==r?t:Promise.race([t,new Promise(((t,s)=>setTimeout((()=>s(new e(i))),r)))])}},exports.Serializer=class{mutex;_done=!1;_lastValue=null;_lastError=void 0;constructor(t){this.mutex=new i({capacity:t?.capacity??1e3,yieldMode:t?.yieldMode??"macrotask"})}async do(t,e){if(this._done)return{value:null,error:new r};try{await this.mutex.lock(e)}catch(t){return{value:null,error:t}}let i,s=null;try{if(this._done)throw new r;s=await t(),this._lastValue=s,this._lastError=void 0}catch(t){i=t,this._lastError=t}finally{this.mutex.unlock()}return{value:s,error:i}}peek(){return{value:this._lastValue,error:this._lastError}}close(){this._done=!0}pending(){return this.mutex.pending()}running(){return this.mutex.locked()}};
+"use strict";var e=class e extends Error{constructor(t,i){super(t,{cause:i}),this.name="SyncError",Object.setPrototypeOf(this,e.prototype)}},t=class extends e{constructor(e){super(`[ArtifactContainer] Operation timed out: ${e}`)}},i=class extends e{constructor(e){super("[Serializer] The serializer has been marked as done!",e)}},r=class{_locked=!1;_capacity;_yieldMode;waiters=[];constructor(e){this._capacity=e?.capacity??1/0,this._yieldMode=e?.yieldMode??"macrotask"}async lock(e){if(!this._locked)return void(this._locked=!0);if(this.waiters.length>=this._capacity)throw new Error(`Mutex queue is full (capacity: ${this._capacity})`);let i;const r=new Promise((e=>i=e));if(this.waiters.push(i),null==e)return void await r;let s;await Promise.race([r.then((()=>clearTimeout(s))),new Promise(((r,o)=>{s=setTimeout((()=>{const e=this.waiters.indexOf(i);-1!==e&&this.waiters.splice(e,1),o(new t("Mutex lock timed out"))}),e)}))])}tryLock(){return!this._locked&&(this._locked=!0,!0)}unlock(){if(!this._locked)throw new Error("Mutex is not locked");const e=this.waiters.shift();e?"microtask"===this._yieldMode?queueMicrotask(e):setTimeout(e,0):this._locked=!1}locked(){return this._locked}pending(){return this.waiters.length}};exports.Debouncer=class{_delay;_leading;_timer;_pendingFn;_pendingResolvers=[];_leadingFired=!1;constructor(e){this._delay=e?.delay??300,this._leading=e?.leading??!1}do(e){return new Promise((t=>{this._enqueue(e,t)}))}fire(e){this._enqueue(e,void 0)}_enqueue(e,t){if(this._pendingFn=e,t&&this._pendingResolvers.push(t),this._leading&&!this._leadingFired)return this._leadingFired=!0,this._fire(),clearTimeout(this._timer),void(this._timer=setTimeout((()=>{this._leadingFired=!1,void 0!==this._pendingFn&&this._fire()}),this._delay));clearTimeout(this._timer),this._timer=setTimeout((()=>{this._leadingFired=!1,this._fire()}),this._delay)}cancel(){clearTimeout(this._timer),this._timer=void 0,this._pendingFn=void 0,this._leadingFired=!1;const e=this._pendingResolvers.splice(0);for(const t of e)t({status:"cancelled"})}async flush(){return this._pendingFn?(clearTimeout(this._timer),this._timer=void 0,this._leadingFired=!1,this._fire()):null}pending(){return void 0!==this._pendingFn}async _fire(){const e=this._pendingFn,t=this._pendingResolvers.splice(0);let i;this._pendingFn=void 0;try{i={status:"ok",value:await e()}}catch(e){i={status:"error",error:e}}for(const e of t)e(i);return i}},exports.Latch=class{_open=!1;_resolve;_promise;constructor(){this._promise=new Promise((e=>{this._resolve=e}))}open(){this._open||(this._open=!0,this._resolve())}async wait(e){if(this._open)return;if(null==e)return this._promise;let i;await Promise.race([this._promise.then((()=>clearTimeout(i))),new Promise(((r,s)=>{i=setTimeout((()=>s(new t("Latch timed out"))),e)}))])}isOpen(){return this._open}},exports.Mutex=r,exports.Once=class{mutex=new r({yieldMode:"microtask"});promise=null;_value=null;_error;_done=!1;retry;throws;constructor({retry:e,throws:t}={}){this.retry=Boolean(e),this.throws=Boolean(t)}async do(e,t){return this._done?this.peek():this.promise?this._awaitWithTimeout(this.promise,t,"Once do() timed out"):(await this.mutex.lock(),this.promise?(this.mutex.unlock(),this._awaitWithTimeout(this.promise,t,"Once do() timed out")):(this.promise=(async()=>{try{const t=await e();this._value=t,this._done=!0}catch(e){if(this._error=e,this.retry||(this._done=!0),this.throws)throw e}finally{this.promise=null}return this.peek()})(),this.mutex.unlock(),this._awaitWithTimeout(this.promise,t,"Once do() timed out")))}doSync(e){if(this._done){if(this.throws&&this._error)throw this._error;return this.peek()}if(this.promise){const e=new Error("Cannot execute doSync while an async operation is pending.");if(this.throws)throw e;return{value:null,error:e}}if(!this.mutex.tryLock()){const e=new Error("Cannot execute doSync: lock is currently held.");if(this.throws)throw e;return{value:null,error:e}}if(this.promise||this._done){if(this.mutex.unlock(),this._done){if(this.throws&&this._error)throw this._error;return this.peek()}const e=new Error("Cannot execute doSync while an async operation is pending.");if(this.throws)throw e;return{value:null,error:e}}try{const t=e();this._value=t,this._done=!0}catch(e){if(this._error=e,this.retry||(this._done=!0),this.throws)throw e}finally{this.mutex.unlock()}return this.peek()}isReady(){return this._done&&null===this.promise}running(){return null!==this.promise&&!this.isReady()}peek(){return{value:this._value,error:this._error}}get(){if(!this._done)throw new Error("Once operation is not yet complete");if(this._error)throw this._error;return this._value}reset(){if(this.running())throw new Error("Cannot reset Once while an operation is in progress.");this._done=!1,this.promise=null,this._value=null,this._error=void 0}currentExecution(){return this.promise}done(){return this._done}_awaitWithTimeout(e,i,r="Operation timed out"){if(null==i)return e;let s;return Promise.race([e.then((e=>(clearTimeout(s),e))),new Promise(((e,o)=>{s=setTimeout((()=>o(new t(r))),i)}))])}},exports.RWMutex=class{_readers=0;_writeLocked=!1;_pendingWriters=0;_yieldMode;readerWaiters=[];writerWaiters=[];constructor(e){this._yieldMode=e?.yieldMode??"microtask"}async rlock(e){if(!this._writeLocked&&0===this._pendingWriters)return void this._readers++;let i;const r=new Promise((e=>i=e));if(this.readerWaiters.push(i),null==e)return void await r;let s;await Promise.race([r.then((()=>clearTimeout(s))),new Promise(((r,o)=>{s=setTimeout((()=>{const e=this.readerWaiters.indexOf(i);-1!==e&&this.readerWaiters.splice(e,1),o(new t("RWMutex rlock timed out"))}),e)}))])}runlock(){if(this._readers<=0)throw new Error("RWMutex: runlock called without a matching rlock");this._readers--,this._tryWakeWriter()}async lock(e){if(!this._writeLocked&&0===this._readers)return void(this._writeLocked=!0);let i;this._pendingWriters++;const r=new Promise((e=>i=e));if(this.writerWaiters.push(i),null==e)return void await r;let s;await Promise.race([r.then((()=>clearTimeout(s))),new Promise(((r,o)=>{s=setTimeout((()=>{const e=this.writerWaiters.indexOf(i);-1!==e&&(this.writerWaiters.splice(e,1),this._pendingWriters--),o(new t("RWMutex lock timed out"))}),e)}))])}unlock(){if(!this._writeLocked)throw new Error("RWMutex: unlock called without a matching lock");this._writeLocked=!1,this._tryWakeWriter()||this._wakeAllReaders()}async read(e,t){await this.rlock(t);try{return await e()}finally{this.runlock()}}async write(e,t){await this.lock(t);try{return await e()}finally{this.unlock()}}writeLocked(){return this._writeLocked}readers(){return this._readers}pendingWriters(){return this._pendingWriters}pendingReaders(){return this.readerWaiters.length}_tryWakeWriter(){if(this._writeLocked||this._readers>0)return!1;const e=this.writerWaiters.shift();return!!e&&(this._writeLocked=!0,this._pendingWriters--,this._schedule(e),!0)}_wakeAllReaders(){const e=this.readerWaiters.splice(0);if(0!==e.length){this._readers+=e.length;for(const t of e)this._schedule(t)}}_schedule(e){"microtask"===this._yieldMode?queueMicrotask(e):setTimeout(e,0)}},exports.Semaphore=class{_slots;_available;_capacity;_yieldMode;waiters=[];constructor(e){if(this._slots=e?.slots??1,this._available=this._slots,this._capacity=e?.capacity??1/0,this._yieldMode=e?.yieldMode??"macrotask",this._slots<1)throw new Error("Semaphore slots must be >= 1")}async acquire(e){if(this._available>0)return void this._available--;if(this.waiters.length>=this._capacity)throw new Error(`Semaphore queue is full (capacity: ${this._capacity})`);let i;const r=new Promise((e=>i=e));if(this.waiters.push(i),null==e)return void await r;let s;await Promise.race([r.then((()=>clearTimeout(s))),new Promise(((r,o)=>{s=setTimeout((()=>{const e=this.waiters.indexOf(i);-1!==e&&this.waiters.splice(e,1),o(new t("Semaphore acquire timed out"))}),e)}))])}tryAcquire(){return this._available>0&&(this._available--,!0)}release(){if(this._available>=this._slots)throw new Error("Semaphore released more times than acquired");const e=this.waiters.shift();e?"microtask"===this._yieldMode?queueMicrotask(e):setTimeout(e,0):this._available++}async run(e,t){await this.acquire(t);try{return await e()}finally{this.release()}}available(){return this._available}pending(){return this.waiters.length}slots(){return this._slots}},exports.Serializer=class{mutex;_done=!1;_lastValue=null;_lastError=void 0;_hasRun=!1;constructor(e){this.mutex=new r({capacity:e?.capacity??1e3,yieldMode:e?.yieldMode??"macrotask"})}async do(e,t){if(this._done)return{value:null,error:new i};try{await this.mutex.lock(t)}catch(e){return{value:null,error:e}}let r,s=null;try{if(this._done)throw new i;s=await e(),this._lastValue=s,this._lastError=void 0,this._hasRun=!0}catch(e){r=e,this._lastError=e,this._hasRun=!0}finally{this.mutex.unlock()}return{value:s,error:r}}peek(){return{value:this._lastValue,error:this._lastError}}hasRun(){return this._hasRun}close(){this._done=!0}pending(){return this.mutex.pending()}running(){return this.mutex.locked()}};

package/index.mjs

@@ -1 +1 @@
-var t=class t extends Error{constructor(e,r){super(e,{cause:r}),this.name="SyncError",Object.setPrototypeOf(this,t.prototype)}},e=class extends t{constructor(t){super(`[ArtifactContainer] Operation timed out: ${t}`)}},r=class extends t{constructor(t){super("[Serializer] The serializer has been marked as done!",t)}},i=class{_locked=!1;_capacity;_yieldMode;waiters=[];constructor(t){this._capacity=t?.capacity??1/0,this._yieldMode=t?.yieldMode??"macrotask"}async lock(t){if(!this._locked)return void(this._locked=!0);if(this.waiters.length>=this._capacity)throw new Error(`Mutex queue is full (capacity: ${this._capacity})`);let r;const i=new Promise((t=>r=t));this.waiters.push(r),null!=t?await Promise.race([i,new Promise(((i,s)=>setTimeout((()=>{const t=this.waiters.indexOf(r);-1!==t&&this.waiters.splice(t,1),s(new e("Mutex lock timed out"))}),t)))]):await i}tryLock(){return!this._locked&&(this._locked=!0,!0)}unlock(){if(!this._locked)throw new Error("Mutex is not locked");const t=this.waiters.shift();t?"microtask"===this._yieldMode?queueMicrotask(t):setTimeout(t,0):this._locked=!1}locked(){return this._locked}pending(){return this.waiters.length}},s=class{mutex=new i({yieldMode:"microtask"});promise=null;_value=null;_error;_done=!1;retry;throws;constructor({retry:t,throws:e}={}){this.retry=Boolean(t),this.throws=Boolean(e)}async do(t,e){return this._done?this.peek():this.promise?this._awaitWithTimeout(this.promise,e,"Once do() timed out"):(await this.mutex.lock(),this.promise?(this.mutex.unlock(),this._awaitWithTimeout(this.promise,e,"Once do() timed out")):(this.promise=(async()=>{try{const e=await t();this._value=e,this._done=!0}catch(t){if(this._error=t,this.retry||(this._done=!0),this.throws)throw t}finally{this.promise=null}return this.peek()})(),this.mutex.unlock(),this._awaitWithTimeout(this.promise,e,"Once do() timed out")))}isReady(){return this._done&&null===this.promise}running(){return null!==this.promise&&!this._done}peek(){return{value:this._value,error:this._error}}get(){if(!this._done)throw new Error("Once operation is not yet complete");if(this._error)throw this._error;return this._value}reset(){this._done=!1,this.promise=null,this._value=null,this._error=void 0}resolved(){return this.promise}done(){return this._done}_awaitWithTimeout(t,r,i="Operation timed out"){return null==r?t:Promise.race([t,new Promise(((t,s)=>setTimeout((()=>s(new e(i))),r)))])}},o=class{mutex;_done=!1;_lastValue=null;_lastError=void 0;constructor(t){this.mutex=new i({capacity:t?.capacity??1e3,yieldMode:t?.yieldMode??"macrotask"})}async do(t,e){if(this._done)return{value:null,error:new r};try{await this.mutex.lock(e)}catch(t){return{value:null,error:t}}let i,s=null;try{if(this._done)throw new r;s=await t(),this._lastValue=s,this._lastError=void 0}catch(t){i=t,this._lastError=t}finally{this.mutex.unlock()}return{value:s,error:i}}peek(){return{value:this._lastValue,error:this._lastError}}close(){this._done=!0}pending(){return this.mutex.pending()}running(){return this.mutex.locked()}};export{i as Mutex,s as Once,o as Serializer};
+var e=class e extends Error{constructor(t,i){super(t,{cause:i}),this.name="SyncError",Object.setPrototypeOf(this,e.prototype)}},t=class extends e{constructor(e){super(`[ArtifactContainer] Operation timed out: ${e}`)}},i=class extends e{constructor(e){super("[Serializer] The serializer has been marked as done!",e)}},r=class{_locked=!1;_capacity;_yieldMode;waiters=[];constructor(e){this._capacity=e?.capacity??1/0,this._yieldMode=e?.yieldMode??"macrotask"}async lock(e){if(!this._locked)return void(this._locked=!0);if(this.waiters.length>=this._capacity)throw new Error(`Mutex queue is full (capacity: ${this._capacity})`);let i;const r=new Promise((e=>i=e));if(this.waiters.push(i),null==e)return void await r;let s;await Promise.race([r.then((()=>clearTimeout(s))),new Promise(((r,o)=>{s=setTimeout((()=>{const e=this.waiters.indexOf(i);-1!==e&&this.waiters.splice(e,1),o(new t("Mutex lock timed out"))}),e)}))])}tryLock(){return!this._locked&&(this._locked=!0,!0)}unlock(){if(!this._locked)throw new Error("Mutex is not locked");const e=this.waiters.shift();e?"microtask"===this._yieldMode?queueMicrotask(e):setTimeout(e,0):this._locked=!1}locked(){return this._locked}pending(){return this.waiters.length}},s=class{_slots;_available;_capacity;_yieldMode;waiters=[];constructor(e){if(this._slots=e?.slots??1,this._available=this._slots,this._capacity=e?.capacity??1/0,this._yieldMode=e?.yieldMode??"macrotask",this._slots<1)throw new Error("Semaphore slots must be >= 1")}async acquire(e){if(this._available>0)return void this._available--;if(this.waiters.length>=this._capacity)throw new Error(`Semaphore queue is full (capacity: ${this._capacity})`);let i;const r=new Promise((e=>i=e));if(this.waiters.push(i),null==e)return void await r;let s;await Promise.race([r.then((()=>clearTimeout(s))),new Promise(((r,o)=>{s=setTimeout((()=>{const e=this.waiters.indexOf(i);-1!==e&&this.waiters.splice(e,1),o(new t("Semaphore acquire timed out"))}),e)}))])}tryAcquire(){return this._available>0&&(this._available--,!0)}release(){if(this._available>=this._slots)throw new Error("Semaphore released more times than acquired");const e=this.waiters.shift();e?"microtask"===this._yieldMode?queueMicrotask(e):setTimeout(e,0):this._available++}async run(e,t){await this.acquire(t);try{return await e()}finally{this.release()}}available(){return this._available}pending(){return this.waiters.length}slots(){return this._slots}},o=class{mutex=new r({yieldMode:"microtask"});promise=null;_value=null;_error;_done=!1;retry;throws;constructor({retry:e,throws:t}={}){this.retry=Boolean(e),this.throws=Boolean(t)}async do(e,t){return this._done?this.peek():this.promise?this._awaitWithTimeout(this.promise,t,"Once do() timed out"):(await this.mutex.lock(),this.promise?(this.mutex.unlock(),this._awaitWithTimeout(this.promise,t,"Once do() timed out")):(this.promise=(async()=>{try{const t=await e();this._value=t,this._done=!0}catch(e){if(this._error=e,this.retry||(this._done=!0),this.throws)throw e}finally{this.promise=null}return this.peek()})(),this.mutex.unlock(),this._awaitWithTimeout(this.promise,t,"Once do() timed out")))}doSync(e){if(this._done){if(this.throws&&this._error)throw this._error;return this.peek()}if(this.promise){const e=new Error("Cannot execute doSync while an async operation is pending.");if(this.throws)throw e;return{value:null,error:e}}if(!this.mutex.tryLock()){const e=new Error("Cannot execute doSync: lock is currently held.");if(this.throws)throw e;return{value:null,error:e}}if(this.promise||this._done){if(this.mutex.unlock(),this._done){if(this.throws&&this._error)throw this._error;return this.peek()}const e=new Error("Cannot execute doSync while an async operation is pending.");if(this.throws)throw e;return{value:null,error:e}}try{const t=e();this._value=t,this._done=!0}catch(e){if(this._error=e,this.retry||(this._done=!0),this.throws)throw e}finally{this.mutex.unlock()}return this.peek()}isReady(){return this._done&&null===this.promise}running(){return null!==this.promise&&!this.isReady()}peek(){return{value:this._value,error:this._error}}get(){if(!this._done)throw new Error("Once operation is not yet complete");if(this._error)throw this._error;return this._value}reset(){if(this.running())throw new Error("Cannot reset Once while an operation is in progress.");this._done=!1,this.promise=null,this._value=null,this._error=void 0}currentExecution(){return this.promise}done(){return this._done}_awaitWithTimeout(e,i,r="Operation timed out"){if(null==i)return e;let s;return Promise.race([e.then((e=>(clearTimeout(s),e))),new Promise(((e,o)=>{s=setTimeout((()=>o(new t(r))),i)}))])}},n=class{mutex;_done=!1;_lastValue=null;_lastError=void 0;_hasRun=!1;constructor(e){this.mutex=new r({capacity:e?.capacity??1e3,yieldMode:e?.yieldMode??"macrotask"})}async do(e,t){if(this._done)return{value:null,error:new i};try{await this.mutex.lock(t)}catch(e){return{value:null,error:e}}let r,s=null;try{if(this._done)throw new i;s=await e(),this._lastValue=s,this._lastError=void 0,this._hasRun=!0}catch(e){r=e,this._lastError=e,this._hasRun=!0}finally{this.mutex.unlock()}return{value:s,error:r}}peek(){return{value:this._lastValue,error:this._lastError}}hasRun(){return this._hasRun}close(){this._done=!0}pending(){return this.mutex.pending()}running(){return this.mutex.locked()}},a=class{_open=!1;_resolve;_promise;constructor(){this._promise=new Promise((e=>{this._resolve=e}))}open(){this._open||(this._open=!0,this._resolve())}async wait(e){if(this._open)return;if(null==e)return this._promise;let i;await Promise.race([this._promise.then((()=>clearTimeout(i))),new Promise(((r,s)=>{i=setTimeout((()=>s(new t("Latch timed out"))),e)}))])}isOpen(){return this._open}},h=class{_readers=0;_writeLocked=!1;_pendingWriters=0;_yieldMode;readerWaiters=[];writerWaiters=[];constructor(e){this._yieldMode=e?.yieldMode??"microtask"}async rlock(e){if(!this._writeLocked&&0===this._pendingWriters)return void this._readers++;let i;const r=new Promise((e=>i=e));if(this.readerWaiters.push(i),null==e)return void await r;let s;await Promise.race([r.then((()=>clearTimeout(s))),new Promise(((r,o)=>{s=setTimeout((()=>{const e=this.readerWaiters.indexOf(i);-1!==e&&this.readerWaiters.splice(e,1),o(new t("RWMutex rlock timed out"))}),e)}))])}runlock(){if(this._readers<=0)throw new Error("RWMutex: runlock called without a matching rlock");this._readers--,this._tryWakeWriter()}async lock(e){if(!this._writeLocked&&0===this._readers)return void(this._writeLocked=!0);let i;this._pendingWriters++;const r=new Promise((e=>i=e));if(this.writerWaiters.push(i),null==e)return void await r;let s;await Promise.race([r.then((()=>clearTimeout(s))),new Promise(((r,o)=>{s=setTimeout((()=>{const e=this.writerWaiters.indexOf(i);-1!==e&&(this.writerWaiters.splice(e,1),this._pendingWriters--),o(new t("RWMutex lock timed out"))}),e)}))])}unlock(){if(!this._writeLocked)throw new Error("RWMutex: unlock called without a matching lock");this._writeLocked=!1,this._tryWakeWriter()||this._wakeAllReaders()}async read(e,t){await this.rlock(t);try{return await e()}finally{this.runlock()}}async write(e,t){await this.lock(t);try{return await e()}finally{this.unlock()}}writeLocked(){return this._writeLocked}readers(){return this._readers}pendingWriters(){return this._pendingWriters}pendingReaders(){return this.readerWaiters.length}_tryWakeWriter(){if(this._writeLocked||this._readers>0)return!1;const e=this.writerWaiters.shift();return!!e&&(this._writeLocked=!0,this._pendingWriters--,this._schedule(e),!0)}_wakeAllReaders(){const e=this.readerWaiters.splice(0);if(0!==e.length){this._readers+=e.length;for(const t of e)this._schedule(t)}}_schedule(e){"microtask"===this._yieldMode?queueMicrotask(e):setTimeout(e,0)}},l=class{_delay;_leading;_timer;_pendingFn;_pendingResolvers=[];_leadingFired=!1;constructor(e){this._delay=e?.delay??300,this._leading=e?.leading??!1}do(e){return new Promise((t=>{this._enqueue(e,t)}))}fire(e){this._enqueue(e,void 0)}_enqueue(e,t){if(this._pendingFn=e,t&&this._pendingResolvers.push(t),this._leading&&!this._leadingFired)return this._leadingFired=!0,this._fire(),clearTimeout(this._timer),void(this._timer=setTimeout((()=>{this._leadingFired=!1,void 0!==this._pendingFn&&this._fire()}),this._delay));clearTimeout(this._timer),this._timer=setTimeout((()=>{this._leadingFired=!1,this._fire()}),this._delay)}cancel(){clearTimeout(this._timer),this._timer=void 0,this._pendingFn=void 0,this._leadingFired=!1;const e=this._pendingResolvers.splice(0);for(const t of e)t({status:"cancelled"})}async flush(){return this._pendingFn?(clearTimeout(this._timer),this._timer=void 0,this._leadingFired=!1,this._fire()):null}pending(){return void 0!==this._pendingFn}async _fire(){const e=this._pendingFn,t=this._pendingResolvers.splice(0);let i;this._pendingFn=void 0;try{i={status:"ok",value:await e()}}catch(e){i={status:"error",error:e}}for(const e of t)e(i);return i}};export{l as Debouncer,a as Latch,r as Mutex,o as Once,h as RWMutex,s as Semaphore,n as Serializer};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asaidimu/utils-sync",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "A collection of sync utilities.",
   "main": "index.js",
   "module": "index.mjs",