syncguard/common/backend.d.ts

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

/**
 * Core types and interfaces for the distributed lock library
 */
/**
 * Configuration for acquiring a distributed lock
 */
export interface LockConfig {
    /** Unique key for the lock */
    key: string;
    /** Time to live in milliseconds (default: 30000) */
    ttlMs?: number;
    /** Delay between retries in milliseconds (default: 100) */
    retryDelayMs?: number;
    /** Maximum number of retries (default: 10) */
    maxRetries?: number;
    /** Timeout for acquiring the lock in milliseconds (default: 5000) */
    timeoutMs?: number;
}
/**
 * Result of a lock acquisition attempt
 */
export type LockResult = {
    success: true;
    lockId: string;
    expiresAt: Date;
} | {
    success: false;
    error: string;
};
/**
 * Backend interface for implementing distributed locks
 */
export interface LockBackend {
    /** Acquire a distributed lock */
    acquire: (config: LockConfig) => Promise<LockResult>;
    /** Release a distributed lock by its ID */
    release: (lockId: string) => Promise<boolean>;
    /** Extend the TTL of an existing lock */
    extend: (lockId: string, ttl: number) => Promise<boolean>;
    /** Check if a key is currently locked */
    isLocked: (key: string) => Promise<boolean>;
}
/**
 * Error thrown when lock operations fail
 */
export declare class LockError extends Error {
    readonly code?: string | undefined;
    constructor(message: string, code?: string | undefined);
}
/**
 * Standard error codes for lock operations
 */
export declare const LockErrorCodes: {
    readonly ACQUISITION_FAILED: "ACQUISITION_FAILED";
    readonly TIMEOUT: "TIMEOUT";
    readonly ALREADY_LOCKED: "ALREADY_LOCKED";
    readonly NOT_FOUND: "NOT_FOUND";
};
export type LockErrorCode = (typeof LockErrorCodes)[keyof typeof LockErrorCodes];
/**
 * Function type for automatic lock management
 */
export interface LockFunction {
    <T>(fn: () => Promise<T>, config: LockConfig): Promise<T>;
    acquire: (config: LockConfig) => Promise<LockResult>;
    release: (lockId: string) => Promise<boolean>;
    extend: (lockId: string, ttl: number) => Promise<boolean>;
    isLocked: (key: string) => Promise<boolean>;
}
/**
 * Creates a distributed lock function with automatic lock management
 * @param backend The lock backend implementation
 * @returns A function that provides both automatic and manual lock operations
 */
export declare function createLock(backend: LockBackend): LockFunction;
/**
 * Utility function to generate a unique lock ID using crypto.randomUUID for better uniqueness
 */
export declare function generateLockId(): string;
/**
 * Utility function to create a delay
 */
export declare function delay(ms: number): Promise<void>;
/**
 * Default configuration values
 */
export declare const DEFAULT_CONFIG: {
    readonly ttlMs: 30000;
    readonly retryDelayMs: 100;
    readonly maxRetries: 10;
    readonly timeoutMs: 5000;
};
/**
 * Helper type for merging configurations
 */
export type MergedLockConfig = Required<LockConfig>;
/**
 * Utility function to merge lock configuration with defaults
 */
export declare function mergeLockConfig(config: LockConfig): MergedLockConfig;