syncguard/common/helpers.d.ts

Functional TypeScript library for distributed locking across microservices. Prevents race conditions with Redis, PostgreSQL, Firestore, and custom backends. Features automatic lock management, timeout handling, and extensible architecture.

import type { AcquireOk, AcquireResult, BackendCapabilities, Fence, LockBackend, LockInfo, LockInfoDebug } from "./types.js";
/**
 * Type guard for fence token presence. Only needed for generic backend code.
 *
 * @param result - Acquire result to check
 * @returns true if successful with fence token
 */
export declare function hasFence<C extends BackendCapabilities>(result: AcquireResult<C>): result is AcquireOk<C> & {
    fence: Fence;
};
/**
 * Sanitizes raw lock data for safe observability (hashes sensitive fields).
 * @internal Used by backend implementations
 */
export declare function sanitizeLockInfo<C extends BackendCapabilities>(rawData: {
    key: string;
    lockId: string;
    expiresAtMs: number;
    acquiredAtMs: number;
    fence?: string;
}, capabilities: C): LockInfo<C>;
/**
 * Attaches raw data for debug access via getByKeyRaw()/getByIdRaw().
 * @internal Used by backend implementations
 */
export declare function attachRawData<C extends BackendCapabilities>(lockInfo: LockInfo<C>, rawData: {
    key: string;
    lockId: string;
}): LockInfo<C>;
/**
 * Looks up lock by key (direct access, O(1)).
 * @returns Sanitized LockInfo or null
 */
export declare function getByKey<C extends BackendCapabilities>(backend: LockBackend<C>, key: string, opts?: {
    signal?: AbortSignal;
}): Promise<LockInfo<C> | null>;
/**
 * Looks up lock by lockId (reverse lookup).
 * @returns Sanitized LockInfo or null
 */
export declare function getById<C extends BackendCapabilities>(backend: LockBackend<C>, lockId: string, opts?: {
    signal?: AbortSignal;
}): Promise<LockInfo<C> | null>;
/**
 * Looks up lock by key with raw key/lockId (for debugging).
 * @returns LockInfoDebug with sensitive fields or null
 */
export declare function getByKeyRaw<C extends BackendCapabilities>(backend: LockBackend<C>, key: string, opts?: {
    signal?: AbortSignal;
}): Promise<LockInfoDebug<C> | null>;
/**
 * Looks up lock by lockId with raw key/lockId (for debugging).
 * @returns LockInfoDebug with sensitive fields or null
 */
export declare function getByIdRaw<C extends BackendCapabilities>(backend: LockBackend<C>, lockId: string, opts?: {
    signal?: AbortSignal;
}): Promise<LockInfoDebug<C> | null>;
/**
 * Checks if lockId owns an active lock.
 *
 * ⚠️ WARNING: This is for DIAGNOSTIC/UI purposes only, NOT a correctness guard!
 * Never use `owns() → mutate` patterns. Correctness relies on atomic release/extend
 * with explicit ownership verification (ADR-003).
 *
 * @returns true if lockId has an active lock
 */
export declare function owns<C extends BackendCapabilities>(backend: LockBackend<C>, lockId: string): Promise<boolean>;
/**
 * Logs a warning when fence counter approaches overflow limit.
 * MANDATORY for all backends when fence > FENCE_THRESHOLDS.WARN (ADR-004).
 *
 * @param fence - Current fence value (string or number)
 * @param key - Lock key for context
 * @internal Used by backend implementations
 */
export declare function logFenceWarning(fence: Fence | number, key: string): void;
/**
 * Checks if an AbortSignal has been aborted and throws LockError if so.
 * Use this to provide cancellation points in long-running operations.
 *
 * @param signal - Optional AbortSignal to check
 * @throws LockError with code "Aborted" if signal is aborted
 * @internal Used by backend implementations
 */
export declare function checkAborted(signal?: AbortSignal): void;
/** Creates a delay promise for testing/retries. */
export declare function delay(ms: number): Promise<void>;