lifecycle-utils/dist/withLock.d.ts

A set of general utilities for the lifecycle of a JS/TS project/library

/**
 * Run a callback while holding an exclusive lock for the given `scope`.
 *
 * An exclusive lock prevents any other exclusive or shared locks from being held at the same time.
 * Lock requests are acquired in the order they are made; consecutive shared lock requests are acquired together.
 */
export declare function withLock<ReturnType, const Scope extends readonly any[]>(scope: ValidLockScope<Scope>, callback: () => Promise<ReturnType> | ReturnType): Promise<ReturnType>;
export declare function withLock<ReturnType, const Scope extends readonly any[]>(scope: ValidLockScope<Scope>, acquireLockSignal: AbortSignal | undefined, callback: () => Promise<ReturnType> | ReturnType): Promise<ReturnType>;
/**
 * Run a callback while holding a shared lock for the given `scope`.
 *
 * Multiple shared locks can run in parallel, while a regular lock requires exclusive access.
 * Lock requests are acquired in the order they are made; consecutive shared lock requests acquired together.
 * A new shared lock joins an active shared lock immediately when no regular lock requests are waiting.
 */
export declare function withSharedLock<ReturnType, const Scope extends readonly any[]>(scope: ValidLockScope<Scope>, callback: () => Promise<ReturnType> | ReturnType): Promise<ReturnType>;
export declare function withSharedLock<ReturnType, const Scope extends readonly any[]>(scope: ValidLockScope<Scope>, acquireLockSignal: AbortSignal | undefined, callback: () => Promise<ReturnType> | ReturnType): Promise<ReturnType>;
/**
 * Check whether a lock is currently active for a given `scope` values.
 */
export declare function isLockActive<const Scope extends readonly any[]>(scope: ValidLockScope<Scope>): boolean;
/**
 * Acquire an exclusive lock for the given `scope`.
 *
 * An exclusive lock prevents any other exclusive or shared locks from being held at the same time.
 * Lock requests are acquired in the order they are made; consecutive shared lock requests are acquired together.
 */
export declare function acquireLock<const Scope extends readonly any[]>(scope: ValidLockScope<Scope>, acquireLockSignal?: AbortSignal): Promise<Lock<Scope>>;
/**
 * Acquire a shared lock for the given `scope`.
 *
 * Multiple shared locks can be held in parallel, while a regular lock requires exclusive access.
 * Lock requests are acquired in the order they are made; consecutive shared lock requests acquired together.
 * A new shared lock joins an active shared lock immediately when no regular lock requests are waiting.
 */
export declare function acquireSharedLock<const Scope extends readonly any[]>(scope: ValidLockScope<Scope>, acquireLockSignal?: AbortSignal): Promise<Lock<Scope>>;
/**
 * Wait for a lock to be released for a given `scope` values.
 */
export declare function waitForLockRelease<const Scope extends readonly any[]>(scope: ValidLockScope<Scope>, signal?: AbortSignal): Promise<void>;
export declare class LockHandle<const Scope extends readonly any[]> implements Lock<Scope> {
    readonly scope: Scope;
    private constructor();
    dispose(): void;
    [Symbol.dispose](): void;
}
export type Lock<Scope extends readonly any[] = readonly any[]> = {
    scope: Scope;
    dispose(): void;
    [Symbol.dispose](): void;
};
/**
 * Ensure that the scope array contains at least one object, otherwise it will be `never`.
 */
export type ValidLockScope<T extends readonly unknown[] = readonly unknown[]> = IncludesObject<T> extends true ? Readonly<T & [...T]> : InvalidScopeError<"Scope array must include at least one object reference">;
type IncludesObject<T extends readonly unknown[]> = true extends ({
    [K in keyof T]: readonly [T[K]] extends readonly [object] ? true : false;
}[keyof T]) ? true : false;
type InvalidScopeError<Message extends string> = readonly unknown[] & {
    error: Message;
    __error: never;
};
export {};
//# sourceMappingURL=withLock.d.ts.map