@beignet/core/dist/locks/index.d.ts

Core framework primitives for Beignet

/**
 * @beignet/core/locks
 *
 * Provider-neutral distributed lock and lease primitives for Beignet apps.
 */
type MaybePromise<T> = T | Promise<T>;
/**
 * Metadata attached to lock acquisition instrumentation and diagnostics.
 */
export type LeaseMetadata = Record<string, string | number | boolean | null | undefined>;
/**
 * Options for acquiring a lease.
 */
export type LeaseAcquireOptions = {
    /**
     * Lease time-to-live in milliseconds. The provider must treat ownership as
     * expired after this duration unless the lease is renewed.
     */
    ttlMs: number;
    /**
     * How long to wait for the lease before returning a non-acquired result.
     *
     * @default 0
     */
    waitMs?: number;
    /**
     * Delay between acquisition attempts while waiting.
     *
     * @default 50
     */
    retryDelayMs?: number;
    /**
     * Optional owner token supplied by the caller. Providers generate one when
     * omitted. Release and renew operations must only succeed for the current
     * owner token.
     */
    ownerToken?: string;
    /**
     * Optional diagnostics metadata. Providers should not use this for lock
     * correctness.
     */
    metadata?: LeaseMetadata;
};
/**
 * Options for renewing a lease.
 */
export type LeaseRenewOptions = {
    /**
     * New lease time-to-live in milliseconds. Defaults to the original ttlMs
     * used to acquire the lease.
     */
    ttlMs?: number;
};
/**
 * State required to restore a lease handle in another runtime invocation.
 */
export type LeaseRestoreOptions = {
    /**
     * TTL to use when `renew()` is called without an explicit override.
     */
    ttlMs: number;
    /**
     * Persisted expiry when the caller has it. Omitted values stay unknown.
     */
    expiresAt?: Date;
    /**
     * Persisted fencing token when the caller has it. Omitted values stay
     * unknown rather than being fabricated.
     */
    fencingToken?: string | number;
};
/**
 * Active lease handle returned by a lock provider.
 */
export type LeaseHandle = {
    key: string;
    ownerToken: string;
    expiresAt?: Date;
    /**
     * Optional monotonically increasing token. Apps can store this with writes to
     * reject stale lease owners when the underlying resource supports fencing.
     */
    fencingToken?: string | number;
    renew(options?: LeaseRenewOptions): Promise<boolean>;
    release(): Promise<boolean>;
};
/**
 * Lease acquisition result.
 */
export type LeaseAcquireResult = {
    acquired: true;
    lease: LeaseHandle;
} | {
    acquired: false;
    reason: "unavailable" | "timeout";
};
/**
 * App-facing lock port.
 */
export type LocksPort = {
    acquire(key: string, options: LeaseAcquireOptions): Promise<LeaseAcquireResult>;
    withLease<T>(key: string, options: LeaseAcquireOptions, fn: (ctx: {
        lease: LeaseHandle;
    }) => MaybePromise<T>): Promise<T | undefined>;
    restore(key: string, ownerToken: string, options: LeaseRestoreOptions): LeaseHandle;
    forceRelease(key: string): Promise<boolean>;
};
/**
 * Captured memory lease state exposed for tests.
 */
export type MemoryLeaseRecord = {
    key: string;
    ownerToken: string;
    expiresAt: Date;
    ttlMs: number;
    fencingToken: number;
    metadata?: LeaseMetadata;
};
/**
 * In-memory locks port exposed for assertions in tests.
 */
export type MemoryLocksPort = LocksPort & {
    leases: Map<string, MemoryLeaseRecord>;
    reset(): void;
};
/**
 * Options for the in-memory locks adapter.
 */
export type CreateMemoryLocksOptions = {
    now?: () => Date;
    createOwnerToken?: () => string;
    sleep?: (ms: number) => Promise<void>;
};
/**
 * Options for the in-memory locks provider.
 */
export type MemoryLocksProviderOptions = CreateMemoryLocksOptions & {
    name?: string;
};
/**
 * Ports contributed by the memory locks provider.
 */
export interface MemoryLocksProviderPorts {
    locks: LocksPort;
}
/**
 * Error thrown when a lease option is invalid.
 */
export declare class LeaseOptionsError extends Error {
    constructor(message: string);
}
/**
 * Create an in-memory locks port for tests and single-process development.
 */
export declare function createMemoryLocks(options?: CreateMemoryLocksOptions): MemoryLocksPort;
/**
 * Create a provider that contributes an in-memory locks port.
 */
export declare function createMemoryLocksProvider(options?: MemoryLocksProviderOptions): import("../providers/provider.js").ServiceProvider<unknown, import("@standard-schema/spec").StandardSchemaV1<void, void>, {
    locks: LocksPort;
}, unknown, void>;
/**
 * Convenience helper for any lock port.
 */
export declare function acquireLease(locks: LocksPort, key: string, options: LeaseAcquireOptions): Promise<LeaseAcquireResult>;
/**
 * Convenience helper for any lock port.
 */
export declare function withLease<T>(locks: LocksPort, key: string, options: LeaseAcquireOptions, fn: (ctx: {
    lease: LeaseHandle;
}) => MaybePromise<T>): Promise<T | undefined>;
export {};
//# sourceMappingURL=index.d.ts.map