@asaidimu/utils-sync 2.2.3 → 2.3.1

package/index.d.mts

@@ -1,718 +0,0 @@
-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;
-}
-
-/**
- * Severity levels for structured issues and errors.
- */
-type Severity = "error" | "warning" | "info";
-/**
- * Represents a detailed validation or operational problem.
- * Designed to be machine-readable while remaining human-friendly.
- */
-interface Issue {
-    /** Machine-readable identifier (e.g., "REQUIRED_FIELD_MISSING"). */
-    readonly code: string;
-    /** Human-readable description of the problem. */
-    readonly message: string;
-    /** Field path in a document or state (e.g., "users.0.email"). */
-    readonly path?: string;
-    /** Optional array index when the issue relates to a specific element. */
-    readonly index?: number;
-    /** Seriousness of the issue. Defaults to "error". */
-    readonly severity?: Severity;
-    /** Optional detailed explanation, can be multi-line. */
-    readonly description?: string;
-    /** Nested issues that caused this one. */
-    readonly cause?: readonly Issue[];
-}
-/**
- * Standardized error code format: CATEGORY-XXX[-SUFFIX]
- * Examples:
- * - VAL-001 (Validation: required field missing)
- * - DB-002-NF (Database: not found)
- * - AUTH-003-DENIED (Auth: permission denied)
- */
-interface ErrorCodeMetadata {
-    /** The formal error code (e.g., "VAL-001") */
-    readonly code: string;
-    /** Human-readable name for the error type */
-    readonly name: string;
-    /** Detailed description of when this error occurs */
-    readonly description: string;
-    /** Suggested action for handling or resolving the error */
-    readonly action?: string;
-    /** HTTP status code mapping (if applicable) */
-    readonly httpStatus?: number;
-    /** Category of the error */
-    readonly category: ErrorCategory;
-    /** Whether this error should be logged as warning vs error */
-    readonly logLevel?: "debug" | "info" | "warn" | "error";
-}
-type ErrorCategory = "validation" | "database" | "auth" | "business" | "system" | "network" | "concurrency" | "custom";
-/**
- * SystemError is the primary error type for all operational and validation errors.
- * Supports both predefined and custom error codes with full metadata.
- */
-declare class SystemError extends Error {
-    readonly code: string;
-    readonly codeMetadata: ErrorCodeMetadata;
-    readonly severity: Severity;
-    readonly path?: string;
-    readonly operation?: string;
-    readonly issues: readonly Issue[];
-    readonly cause?: unknown;
-    constructor(params: {
-        code: string;
-        message?: string;
-        severity?: Severity;
-        path?: string;
-        operation?: string;
-        issues?: readonly Issue[];
-        cause?: unknown;
-        metadata?: Partial<Omit<ErrorCodeMetadata, "code">>;
-    });
-    /**
-     * Returns a new SystemError with the specified path.
-     */
-    withPath(path: string): SystemError;
-    /**
-     * Returns a new SystemError with the specified operation name.
-     */
-    withOperation(operation: string): SystemError;
-    /**
-     * Returns a new SystemError with the specified issue appended.
-     */
-    withIssue(issue: Issue): SystemError;
-    /**
-     * Returns a new SystemError with multiple issues appended.
-     */
-    withIssues(issues: readonly Issue[]): SystemError;
-    /**
-     * Returns a new SystemError wrapping the specified cause.
-     */
-    withCause(cause: unknown): SystemError;
-    /**
-     * Returns the HTTP status code for this error (if applicable).
-     */
-    getHttpStatus(): number | undefined;
-    /**
-     * Formats the error for logging with structured metadata.
-     */
-    toLogEntry(): Record<string, unknown>;
-    /**
-     * Produces a human-readable representation suitable for logging.
-     */
-    toString(): string;
-}
-
-/** Represents all errors within the sync system */
-declare class SyncError extends SystemError {
-    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.
-     * If exceeded, tryLock/lock will fail.
-     * @default Infinity
-     */
-    capacity?: number;
-    /**
-     * Controls how lock handoff is scheduled when a waiter is unblocked.
-     *
-     * - `"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 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. Once, Semaphore where builds are infrequent
-     *   and latency matters more than fairness).
-     */
-    yieldMode?: "macrotask" | "microtask";
-}
-/**
- * A mutual exclusion lock.
- * Allows only one execution context to access a resource at a time.
- *
- * Yield mode is configurable per instance:
- * - "macrotask" (default): yields between handoffs, preventing microtask starvation.
- * - "microtask": zero-delay handoff for latency-sensitive paths.
- */
-declare class Mutex {
-    private _locked;
-    private _capacity;
-    private _yieldMode;
-    private waiters;
-    constructor(options?: MutexOptions);
-    /**
-     * Acquires the lock. If already held, waits until released or timeout reached.
-     *
-     * @param timeout - Optional maximum wait time in milliseconds.
-     * @throws {TimeoutError} If the lock cannot be acquired within the timeout.
-     * @throws {Error} If the wait queue is full (backpressure).
-     */
-    lock(timeout?: number): Promise<void>;
-    /**
-     * Attempts to acquire the lock without waiting.
-     * @returns `true` if the lock was acquired, `false` otherwise.
-     */
-    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;
-    /** Returns true if the mutex is currently locked. */
-    locked(): boolean;
-    /** Returns the number of operations waiting for the lock. */
-    pending(): number;
-}
-
-type OnceResult<T> = {
-    value: T | null;
-    error?: unknown;
-};
-/**
- * Ensures a specific task is executed exactly once, regardless of concurrent callers.
- * Handles race conditions, caching, and optional retries on failure.
- *
- * Uses microtask yield mode for its internal mutex — builds are latency-sensitive
- * and starvation is not a concern (only one build runs at a time by design).
- *
- * @template T - The type of value returned by the execution.
- */
-declare class Once<T = void> {
-    private mutex;
-    private promise;
-    private _value;
-    private _error;
-    private _done;
-    private retry;
-    private throws;
-    constructor({ retry, throws }?: {
-        retry?: boolean;
-        throws?: boolean;
-    });
-    /**
-     * Manually sets a value, marking the operation as done.
-     * Throws if the operation is already done or currently running.
-     *
-     * @param value - The value to resolve to.
-     */
-    resolve(value: T): void;
-    /**
-     * Execute the function if it hasn't been executed yet.
-     * Subsequent calls return the result of the first execution.
-     *
-     * @param fn - The function to execute.
-     * @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 is currently executing.
-     *
-     * Uses ready() 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;
-    /**
-     * Returns the current state without waiting.
-     */
-    peek(): OnceResult<T>;
-    /**
-     * Returns the stored value if successful, otherwise throws the stored error.
-     * Throws if the operation is not yet complete.
-     */
-    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 true if the operation has finished (success or final failure).
-     */
-    done(): boolean;
-    /**
-     * 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.
-     */
-    current(): Promise<OnceResult<T>> | null;
-    /**
-     * 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;
-}
-
-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 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 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.
-     */
-    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;
-}
-
-interface SharedResourceOptions {
-    /**
-     * How long to wait after the last subscriber leaves before cleaning up.
-     * - "microtask": (Default) Waits until the end of the current synchronous execution tick.
-     * Perfect for React StrictMode or concurrent rendering.
-     * - number: Waits for the specified milliseconds. Useful for debouncing rapid reconnects.
-     * - "sync": Cleans up immediately (bypasses the grace period entirely).
-     */
-    gracePeriod?: "microtask" | "sync" | number;
-}
-/**
- * Manages the lifecycle of a reference-counted shared resource.
- * Ensures the resource is created exactly once on the first acquisition,
- * and cleaned up only when the last subscriber releases it (after an optional grace period).
- */
-declare class SharedResource<T> {
-    private readonly factory;
-    private readonly onCleanup;
-    private readonly options;
-    private _count;
-    private readonly init;
-    private pendingMicrotask;
-    private cleanupTimer?;
-    constructor(factory: () => Promise<T> | T, onCleanup: (value: T | null) => void | Promise<void>, options?: SharedResourceOptions);
-    /**
-     * The current number of active subscribers.
-     */
-    get subscribers(): number;
-    /**
-     * Increments the reference count and ensures the resource is initialized.
-     * If a cleanup was scheduled but hasn't executed yet, it is cancelled.
-     *
-     * @returns The initialized resource.
-     */
-    acquire(): Promise<T>;
-    /**
-     * Decrements the reference count.
-     * If the count reaches zero, the cleanup process is scheduled according to the grace period.
-     */
-    release(): void;
-    /**
-     * Returns the current value synchronously if it has been successfully initialized.
-     * Returns null if initialization is pending, failed, or hasn't started.
-     */
-    peek(): T | null;
-    /**
-     * Forcibly tears down the resource, ignoring the reference count and grace period.
-     * Useful for emergency teardowns (e.g., container disposal).
-     */
-    forceCleanup(): void;
-    /**
-     * Cancels any scheduled cleanup tasks.
-     * This is the core mechanism that prevents React StrictMode from destroying the resource.
-     */
-    private cancelPendingCleanup;
-    /**
-     * Determines how to schedule the cleanup based on the configured options.
-     */
-    private scheduleCleanup;
-    /**
-     * Performs the actual teardown of the resource and resets the initialization state.
-     */
-    private executeCleanup;
-}
-
-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, SharedResource, type SharedResourceOptions, SyncError, TimeoutError };