@asaidimu/utils-sync 2.3.0 → 2.3.2

package/index.d.mts

@@ -1,809 +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]`
- *
- * @example
- * ```typescript
- * // VAL-001 (Validation: required field missing)
- * // DB-001-NF (Database: not found)
- * // AUTH-001-DENIED (Auth: permission denied)
- * ```
- */
-interface ErrorCodeMetadata {
-    /** The formal unique error code identifier (e.g., `"VAL-001"`). */
-    readonly code: string;
-    /** Human-readable uppercase name for the error type (e.g., `"VALIDATION_FAILED"`). */
-    readonly name: string;
-    /** Detailed description of when and why this error occurs. */
-    readonly description: string;
-    /** Suggested immediate action for engineers or systems to handle or resolve the error. */
-    readonly action?: string;
-    /** HTTP status code mapping for upstream REST APIs (e.g., `404`, `500`). */
-    readonly httpStatus?: number;
-    /** Operational category this error belongs to. */
-    readonly category: ErrorCategory;
-    /** Recommended logging level threshold (`"debug" | "info" | "warn" | "error"`). */
-    readonly logLevel?: "debug" | "info" | "warn" | "error";
-}
-/**
- * Categories classifying the origin and nature of an error.
- */
-type ErrorCategory = "validation" | "database" | "auth" | "business" | "system" | "network" | "concurrency" | "custom";
-/**
- * Configuration options container used when constructing a new `SystemError`.
- */
-interface SystemErrorParams {
-    /** The unique registered error code identifier (e.g., `ErrorCodes.INTERNAL_ERROR.code`). */
-    code: string;
-    /** Explicit error message overrides. If omitted, defaults to the error code's description. */
-    message?: string;
-    /** Operational severity tier. Defaults to `"error"`. */
-    severity?: Severity;
-    /** State path or key where the operational failure occurred (e.g., `"users.0.email"`). */
-    path?: string;
-    /** The function block, track component, or routing process executing during failure. */
-    operation?: string;
-    /** Flat array of precise granular input issues or schema violations. */
-    issues?: readonly Issue[];
-    /** The underlying trigger cause. Accepts native `Error` instances, custom errors, or concurrent `Error[]` arrays. */
-    cause?: unknown | unknown[];
-    /** Ad-hoc modifications overriding base properties mapped from the code registry. */
-    metadata?: Partial<Omit<ErrorCodeMetadata, "code" | "category">>;
-}
-/**
- * Primary domain operational error wrapper.
- * Unfolds historical deep error hierarchies into flat, parallel-aware trace timelines.
- */
-declare class SystemError extends Error {
-    /** The associated error identifier code (e.g., `"SYS-001"`). */
-    readonly code: string;
-    /** Static documentation mapping and registration rules bound to this code type. */
-    readonly codeMetadata: ErrorCodeMetadata;
-    /** Severity tier grading the operational consequence of this failure. */
-    readonly severity: Severity;
-    /** Target state or document path where processing failed. */
-    readonly path?: string;
-    /** Active system segment, workflow node, or function context executing during failure. */
-    readonly operation?: string;
-    /** Detailed sub-layer list representing structural data validation failures. */
-    readonly issues: readonly Issue[];
-    /** Raw backing trigger, array of concurrent branches, or source error instance. */
-    readonly cause?: unknown | unknown[];
-    /** Exact moment this error was instantiated (ISO string). */
-    readonly timestamp: string;
-    /**
-     * Instantiate a structurally traceable `SystemError`.
-     * @param params - Configuration parameters outlining the error's state context.
-     */
-    constructor(params: SystemErrorParams);
-    /**
-     * Generates a separate immutable clone assigning a target file, state, or field path.
-     */
-    withPath(path: string): SystemError;
-    /**
-     * Generates a separate immutable clone assigning a specific execution block or track tracking context.
-     */
-    withOperation(operation: string): SystemError;
-    /**
-     * Appends an operational validation structural issue to a fresh clone of this error.
-     */
-    withIssue(issue: Issue): SystemError;
-    /**
-     * Appends multiple validation issues onto a fresh clone of this error instance.
-     */
-    withIssues(issues: readonly Issue[]): SystemError;
-    /**
-     * Maps a backing raw trigger or concurrent array tracking set to a fresh clone of this error instance.
-     */
-    withCause(cause: unknown | unknown[]): SystemError;
-    /**
-     * Retrieves the recommended HTTP Status code mapped to this error's code metadata registry.
-     */
-    getHttpStatus(): number | undefined;
-    /**
-     * Unrolls execution hierarchies chronologically, isolating parallel pipelines into clear trace frames.
-     * Always returns an array of trace nodes.
-     */
-    private extractChronologicalTrace;
-    /**
-     * Transforms the error payload into a flattened transmission format.
-     * Strips recursive depth in favor of an array-mapped chronological failure `trace`.
-     */
-    toJSON(): Record<string, unknown>;
-    /**
-     * Generates a flat payload matching `toJSON` format requirements for centralized platform ingestion engines.
-     */
-    toLogEntry(): Record<string, unknown>;
-    /**
-     * Terminal terminal dump representation formatting details cleanly into plain strings.
-     */
-    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;
-}
-
-interface ResourceRegistryOptions<T, K, O> {
-    /**
-     * Async factory: receives the key and per-call options.
-     * Only invoked when a resource does not already exist.
-     */
-    onCreate?: (key: K, options: O) => Promise<T>;
-    /**
-     * Sync factory: receives the key and per-call options.
-     * Only invoked when a resource does not already exist.
-     */
-    onCreateSync?: (key: K, options: O) => T;
-    /**
-     * Optional disposer for explicit cleanup (release/clear).
-     */
-    onDispose?: (resource: T) => void | Promise<void>;
-    /**
-     * Optional callback fired when the resource is GC'd.
-     */
-    onEvict?: (key: K) => void;
-}
-declare class ResourceRegistry<R extends object, K extends string | number = string, O = void> {
-    private readonly entries;
-    private readonly resourceToOnce;
-    private readonly finalizer;
-    private readonly onCreate?;
-    private readonly onCreateSync?;
-    private readonly onDispose?;
-    private readonly onEvict?;
-    constructor(options: ResourceRegistryOptions<R, K, O>);
-    /**
-     * Get or create a resource.
-     *
-     * IMPORTANT: The `options` are ONLY used if the resource does NOT exist yet.
-     * If the resource already exists (or is being created by another concurrent call),
-     * the `options` are ignored and the existing instance is returned.
-     *
-     * This matches the original `registry.ts` behavior.
-     */
-    get(key: K, options: O, timeout?: number): Promise<R>;
-    /**
-     * Synchronous version of `get`.
-     * Options are only used on the first creation.
-     */
-    getSync(key: K, options: O): R;
-    release(key: K): Promise<boolean>;
-    clear(): Promise<void>;
-    has(key: K): boolean;
-    get size(): number;
-}
-
-export { Debouncer, type DebouncerCancelled, type DebouncerError, type DebouncerOk, type DebouncerOptions, type DebouncerResult, Latch, Mutex, type MutexOptions, Once, OnceExecutionConflict, type OnceResult, RWMutex, type RWMutexOptions, ResourceRegistry, type ResourceRegistryOptions, Semaphore, type SemaphoreOptions, Serializer, SerializerExecutionDone, type SerializerOptions, type SerializerResult, SharedResource, type SharedResourceOptions, SyncError, TimeoutError };