@periodic/vanadium 1.0.0

package/dist/types/adapters/prisma/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Prisma Storage Adapter for @periodic/vanadium
+ *
+ * Peer dependency: "@prisma/client" >= 5.0.0
+ * Import: import { createPrismaAdapter } from '@periodic/vanadium/adapters/prisma'
+ *
+ * Required Prisma schema model:
+ * ```prisma
+ * model VanadiumRecord {
+ *   key         String  @id
+ *   status      String
+ *   result      Json?
+ *   payloadHash String?
+ *   ownerToken  String?
+ *   attempts    Int     @default(0)
+ *   createdAt   BigInt
+ *   updatedAt   BigInt
+ *   expiresAt   BigInt?
+ *
+ *   @@map("vanadium_records")
+ * }
+ * ```
+ */
+import type { StorageAdapter, StoredRecord } from '../../types/index.js';
+interface PrismaClientLike {
+    $transaction<T>(fn: (tx: PrismaClientLike) => Promise<T>): Promise<T>;
+    [key: string]: any;
+}
+export interface PrismaAdapterOptions {
+    /** PrismaClient instance */
+    prisma: PrismaClientLike;
+    /** Model name as it appears on PrismaClient (default: "vanadiumRecord") */
+    modelName?: string;
+    /** Use interactive transactions (default: true) */
+    useInteractiveTransactions?: boolean;
+    /** Clock function for deterministic testing */
+    clock?: () => number;
+}
+export declare class PrismaAdapter implements StorageAdapter {
+    readonly name = "prisma";
+    private readonly prisma;
+    private readonly modelName;
+    private readonly useTransactions;
+    private readonly clock;
+    constructor(options: PrismaAdapterOptions);
+    private get model();
+    get<T = unknown>(key: string): Promise<StoredRecord<T> | null>;
+    set<T = unknown>(key: string, value: StoredRecord<T>, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    compareAndSet<T = unknown>(key: string, expectedOwnerToken: string, newValue: StoredRecord<T>, ttlMs?: number): Promise<boolean>;
+    capabilities(): {
+        transactions: boolean;
+        cas: boolean;
+        ttl: boolean;
+        advisoryLocks: boolean;
+    };
+    private _rowToRecord;
+}
+/**
+ * Create a Prisma storage adapter.
+ *
+ * @example
+ * ```ts
+ * import { PrismaClient } from '@prisma/client';
+ * import { createPrismaAdapter } from '@periodic/vanadium/adapters/prisma';
+ *
+ * const prisma = new PrismaClient();
+ * const adapter = createPrismaAdapter({ prisma });
+ * ```
+ */
+export declare function createPrismaAdapter(options: PrismaAdapterOptions): PrismaAdapter;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/types/adapters/prisma/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/adapters/prisma/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAczE,UAAU,gBAAgB;IACxB,YAAY,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,gBAAgB,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACtE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAiBD,MAAM,WAAW,oBAAoB;IACnC,4BAA4B;IAC5B,MAAM,EAAE,gBAAgB,CAAC;IACzB,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mDAAmD;IACnD,0BAA0B,CAAC,EAAE,OAAO,CAAC;IACrC,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAID,qBAAa,aAAc,YAAW,cAAc;IAClD,SAAgB,IAAI,YAAY;IAEhC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,OAAO,EAAE,oBAAoB;IAczC,OAAO,KAAK,KAAK,GAUhB;IAIK,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAU9D,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAwCpF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAWlC,aAAa,CAAC,CAAC,GAAG,OAAO,EAC7B,GAAG,EAAE,MAAM,EACX,kBAAkB,EAAE,MAAM,EAC1B,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,EACzB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC;IA8BnB,YAAY;;;;;;IAWZ,OAAO,CAAC,YAAY;CAarB;AAID;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAEhF"}

package/dist/types/adapters/redis/index.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Redis Storage Adapter for @periodic/vanadium
+ *
+ * Peer dependency: "redis" >= 4.0.0
+ * Import: import { createRedisAdapter } from '@periodic/vanadium/adapters/redis'
+ *
+ * The caller is responsible for creating and connecting the Redis client.
+ * This adapter NEVER creates its own connection.
+ */
+import type { StorageAdapter, StoredRecord } from '../../types/index.js';
+type RedisClientLike = {
+    set(key: string, value: string, options?: any): Promise<string | null>;
+    get(key: string): Promise<string | null>;
+    del(key: string | string[]): Promise<number>;
+    eval(script: string, options: {
+        keys: string[];
+        arguments: string[];
+    }): Promise<any>;
+    evalSha?(sha: string, options: {
+        keys: string[];
+        arguments: string[];
+    }): Promise<any>;
+    scriptLoad?(script: string): Promise<string>;
+};
+export interface RedisAdapterOptions {
+    /** Pre-connected Redis client (redis >= 4.0.0) */
+    client: RedisClientLike;
+    /** Key prefix (default: "vanadium:") */
+    keyPrefix?: string;
+    /** Optional namespace segment */
+    namespace?: string;
+    /** Use Lua scripts for atomic compare-and-set (default: true) */
+    useLua?: boolean;
+    /** Clock function for deterministic testing */
+    clock?: () => number;
+}
+export declare class RedisAdapter implements StorageAdapter {
+    readonly name = "redis";
+    private readonly client;
+    private readonly keyPrefix;
+    private readonly namespace;
+    private readonly useLua;
+    private readonly clock;
+    constructor(options: RedisAdapterOptions);
+    get<T = unknown>(key: string): Promise<StoredRecord<T> | null>;
+    set<T = unknown>(key: string, value: StoredRecord<T>, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    compareAndSet<T = unknown>(key: string, expectedOwnerToken: string, newValue: StoredRecord<T>, ttlMs?: number): Promise<boolean>;
+    /**
+     * Safe owner-only delete using Lua. Use in lock release.
+     */
+    safeDelete(key: string, ownerToken: string): Promise<boolean>;
+    capabilities(): {
+        transactions: boolean;
+        cas: boolean;
+        ttl: boolean;
+        advisoryLocks: boolean;
+    };
+    private _buildKey;
+}
+/**
+ * Create a Redis storage adapter.
+ *
+ * @example
+ * ```ts
+ * import { createClient } from 'redis';
+ * import { createRedisAdapter } from '@periodic/vanadium/adapters/redis';
+ *
+ * const client = createClient({ url: process.env.REDIS_URL });
+ * await client.connect();
+ *
+ * const adapter = createRedisAdapter({ client, namespace: 'payments' });
+ * ```
+ */
+export declare function createRedisAdapter(options: RedisAdapterOptions): RedisAdapter;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/types/adapters/redis/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/adapters/redis/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAQzE,KAAK,eAAe,GAAG;IACrB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACvE,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACrF,OAAO,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,EAAE,MAAM,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IACtF,UAAU,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC9C,CAAC;AAKF,MAAM,WAAW,mBAAmB;IAClC,kDAAkD;IAClD,MAAM,EAAE,eAAe,CAAC;IACxB,wCAAwC;IACxC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AA8BD,qBAAa,YAAa,YAAW,cAAc;IACjD,SAAgB,IAAI,WAAW;IAE/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAU;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,OAAO,EAAE,mBAAmB;IAalC,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAW9D,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBpF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IASlC,aAAa,CAAC,CAAC,GAAG,OAAO,EAC7B,GAAG,EAAE,MAAM,EACX,kBAAkB,EAAE,MAAM,EAC1B,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,EACzB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC;IA+BnB;;OAEG;IACG,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAenE,YAAY;;;;;;IAWZ,OAAO,CAAC,SAAS;CAGlB;AAID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAE7E"}

package/dist/types/cleanup/engine.d.ts

@@ -0,0 +1,41 @@
+import type { CleanupOptions } from '../types/index.js';
+/**
+ * Optional background cleanup engine.
+ *
+ * Scans for orphaned IN_PROGRESS records and removes or marks them FAILED.
+ * Does NOT break distributed semantics — TTL handles the authoritative expiry.
+ * This is purely a maintenance utility.
+ *
+ * @example
+ * ```ts
+ * const cleanup = createCleanupEngine({ adapter, intervalMs: 30_000 });
+ * cleanup.start();
+ * process.on('SIGTERM', () => cleanup.stop());
+ * ```
+ */
+export declare class CleanupEngine {
+    private intervalHandle;
+    private running;
+    private readonly adapter;
+    private readonly intervalMs;
+    private readonly staleThresholdMs;
+    private readonly deleteOnClean;
+    private readonly clock;
+    constructor(options: CleanupOptions);
+    /**
+     * Start the cleanup timer.
+     */
+    start(): void;
+    /**
+     * Stop the cleanup timer gracefully.
+     */
+    stop(): void;
+    /**
+     * Run a single cleanup pass manually (useful for testing).
+     */
+    runOnce(keysToCheck: string[]): Promise<number>;
+    private _runCleanup;
+    private _cleanKeys;
+}
+export declare function createCleanupEngine(options: CleanupOptions): CleanupEngine;
+//# sourceMappingURL=engine.d.ts.map

package/dist/types/cleanup/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/cleanup/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAkB,MAAM,mBAAmB,CAAC;AAOxE;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,OAAO,CAAS;IAExB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAU;IACxC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAEzB,OAAO,EAAE,cAAc;IAQnC;;OAEG;IACH,KAAK,IAAI,IAAI;IAab;;OAEG;IACH,IAAI,IAAI,IAAI;IAQZ;;OAEG;IACG,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;YAMvC,WAAW;YAOX,UAAU;CAwBzB;AAID,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,CAE1E"}

package/dist/types/core/concurrencyGuard.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Local concurrency guard — prevents redundant concurrent calls to the
+ * distributed adapter for the same key within a single process.
+ *
+ * This is a performance optimization ONLY. It does NOT replace the
+ * distributed guarantee provided by the storage adapter.
+ */
+export declare class ConcurrencyGuard {
+    private readonly inFlight;
+    /**
+     * If a promise for this key is already in-flight, return it.
+     * Otherwise, register the new promise and clean up when it settles.
+     */
+    wrap<T>(key: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Check if a key is currently in-flight locally.
+     */
+    isInFlight(key: string): boolean;
+    /**
+     * Return the number of keys currently tracked.
+     */
+    size(): number;
+    /**
+     * Clear all tracked keys (for testing / cleanup).
+     */
+    clear(): void;
+}
+//# sourceMappingURL=concurrencyGuard.d.ts.map

package/dist/types/core/concurrencyGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrencyGuard.d.ts","sourceRoot":"","sources":["../../../src/core/concurrencyGuard.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;IAEhE;;;OAGG;IACH,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IActD;;OAEG;IACH,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAIhC;;OAEG;IACH,IAAI,IAAI,MAAM;IAId;;OAEG;IACH,KAAK,IAAI,IAAI;CAGd"}

package/dist/types/core/metrics.d.ts

@@ -0,0 +1,13 @@
+import type { VanadiumMetrics } from '../types/index.js';
+/**
+ * Mutable metrics container. One instance per engine.
+ * Never uses global state.
+ */
+export declare class MetricsStore {
+    private data;
+    increment(key: keyof VanadiumMetrics, amount?: number): void;
+    decrement(key: keyof VanadiumMetrics, amount?: number): void;
+    get(): Readonly<VanadiumMetrics>;
+    reset(): void;
+}
+//# sourceMappingURL=metrics.d.ts.map

package/dist/types/core/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../src/core/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAIzD;;;GAGG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,IAAI,CAUV;IAEF,SAAS,CAAC,GAAG,EAAE,MAAM,eAAe,EAAE,MAAM,SAAI,GAAG,IAAI;IAIvD,SAAS,CAAC,GAAG,EAAE,MAAM,eAAe,EAAE,MAAM,SAAI,GAAG,IAAI;IAIvD,GAAG,IAAI,QAAQ,CAAC,eAAe,CAAC;IAIhC,KAAK,IAAI,IAAI;CAKd"}

package/dist/types/core/stateMachine.d.ts

@@ -0,0 +1,20 @@
+import type { ExecutionStatus } from '../types/index.js';
+/**
+ * Assert that a transition from one execution status to another is valid.
+ * Throws a VanadiumError(STATE_TRANSITION_ERROR) on illegal transitions.
+ */
+export declare function assertValidTransition(from: ExecutionStatus, to: ExecutionStatus, key: string, adapterName: string, clock?: () => number): void;
+/**
+ * Check if a transition is valid without throwing.
+ */
+export declare function isValidTransition(from: ExecutionStatus, to: ExecutionStatus): boolean;
+/**
+ * Determine whether a stored record has expired based on current time.
+ */
+export declare function isExpired(expiresAt: number | undefined, clock?: () => number): boolean;
+/**
+ * Determine whether an IN_PROGRESS record can be taken over.
+ * Requires: status is IN_PROGRESS AND expiresAt has passed.
+ */
+export declare function canTakeover(status: ExecutionStatus, expiresAt: number | undefined, clock?: () => number): boolean;
+//# sourceMappingURL=stateMachine.d.ts.map

package/dist/types/core/stateMachine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateMachine.d.ts","sourceRoot":"","sources":["../../../src/core/stateMachine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAazD;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,eAAe,EACrB,EAAE,EAAE,eAAe,EACnB,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,KAAK,GAAE,MAAM,MAAiB,GAC7B,IAAI,CAKN;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,eAAe,EAAE,EAAE,EAAE,eAAe,GAAG,OAAO,CAErF;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,GAAE,MAAM,MAAiB,GAAG,OAAO,CAGhG;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,eAAe,EACvB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,GAAE,MAAM,MAAiB,GAC7B,OAAO,CAET"}

package/dist/types/errors/index.d.ts

@@ -0,0 +1,32 @@
+import type { VanadiumErrorType } from '../types/index.js';
+export interface VanadiumErrorDetails {
+    type: VanadiumErrorType;
+    key: string;
+    adapterName: string;
+    timestamp: number;
+    message: string;
+    originalError?: unknown;
+    attempts?: number;
+    payloadHash?: string;
+}
+export declare class VanadiumError extends Error {
+    readonly type: VanadiumErrorType;
+    readonly key: string;
+    readonly adapterName: string;
+    readonly timestamp: number;
+    readonly originalError?: unknown;
+    readonly attempts?: number;
+    readonly payloadHash?: string;
+    constructor(details: VanadiumErrorDetails);
+    toJSON(): Record<string, unknown>;
+}
+export declare function createDuplicateExecutionError(key: string, adapterName: string, clock?: () => number): VanadiumError;
+export declare function createInProgressError(key: string, adapterName: string, attempts: number, clock?: () => number): VanadiumError;
+export declare function createLockAcquisitionFailedError(key: string, adapterName: string, clock?: () => number): VanadiumError;
+export declare function createLockTimeoutError(key: string, adapterName: string, maxWaitMs: number, clock?: () => number): VanadiumError;
+export declare function createPayloadMismatchError(key: string, adapterName: string, storedHash: string | undefined, incomingHash: string, clock?: () => number): VanadiumError;
+export declare function createConfigurationError(key: string, adapterName: string, message: string, clock?: () => number): VanadiumError;
+export declare function createStorageError(key: string, adapterName: string, originalError: unknown, clock?: () => number): VanadiumError;
+export declare function createStateTransitionError(key: string, adapterName: string, from: string, to: string, clock?: () => number): VanadiumError;
+export declare function isVanadiumError(err: unknown): err is VanadiumError;
+//# sourceMappingURL=index.d.ts.map

package/dist/types/errors/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI3D,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,iBAAiB,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBAAa,aAAc,SAAQ,KAAK;IACtC,SAAgB,IAAI,EAAE,iBAAiB,CAAC;IACxC,SAAgB,GAAG,EAAE,MAAM,CAAC;IAC5B,SAAgB,WAAW,EAAE,MAAM,CAAC;IACpC,SAAgB,SAAS,EAAE,MAAM,CAAC;IAClC,SAAgB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxC,SAAgB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClC,SAAgB,WAAW,CAAC,EAAE,MAAM,CAAC;gBAEzB,OAAO,EAAE,oBAAoB;IAmBzC,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAYlC;AAID,wBAAgB,6BAA6B,CAC3C,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,KAAK,GAAE,MAAM,MAAiB,GAC7B,aAAa,CAQf;AAED,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,KAAK,GAAE,MAAM,MAAiB,GAC7B,aAAa,CASf;AAED,wBAAgB,gCAAgC,CAC9C,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,KAAK,GAAE,MAAM,MAAiB,GAC7B,aAAa,CAQf;AAED,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,KAAK,GAAE,MAAM,MAAiB,GAC7B,aAAa,CAQf;AAED,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,UAAU,EAAE,MAAM,GAAG,SAAS,EAC9B,YAAY,EAAE,MAAM,EACpB,KAAK,GAAE,MAAM,MAAiB,GAC7B,aAAa,CAYf;AAED,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,MAAM,EACf,KAAK,GAAE,MAAM,MAAiB,GAC7B,aAAa,CAQf;AAED,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,OAAO,EACtB,KAAK,GAAE,MAAM,MAAiB,GAC7B,aAAa,CAUf;AAED,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,IAAI,EAAE,MAAM,EACZ,EAAE,EAAE,MAAM,EACV,KAAK,GAAE,MAAM,MAAiB,GAC7B,aAAa,CAQf;AAID,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,aAAa,CAElE"}

package/dist/types/http/express.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Express middleware for @periodic/vanadium
+ *
+ * Automatically wraps HTTP handlers with idempotency semantics.
+ * Reads the Idempotency-Key header and caches successful responses.
+ *
+ * @example
+ * ```ts
+ * import express from 'express';
+ * import { createIdempotency, createMemoryAdapter } from '@periodic/vanadium';
+ * import { vanadiumMiddleware } from '@periodic/vanadium/http/express';
+ *
+ * const app = express();
+ * const idempotency = createIdempotency({ adapter: createMemoryAdapter(), ttlMs: 86_400_000 });
+ *
+ * app.post('/payments', vanadiumMiddleware(idempotency), async (req, res) => {
+ *   const result = await chargeCard(req.body);
+ *   res.json(result);
+ * });
+ * ```
+ */
+import type { IdempotencyEngine } from '../types/index.js';
+interface Request {
+    headers: Record<string, string | string[] | undefined>;
+    method: string;
+    path: string;
+}
+interface Response {
+    status(code: number): Response;
+    json(body: any): void;
+    set(headers: Record<string, string>): Response;
+    statusCode: number;
+    end(): void;
+}
+type NextFunction = (err?: any) => void;
+type RequestHandler = (req: Request, res: Response, next: NextFunction) => void;
+export interface VanadiumMiddlewareOptions {
+    /** Header name to read idempotency key from (default: "idempotency-key") */
+    headerName?: string;
+    /** If true, return 409 when key is IN_PROGRESS (default: true) */
+    rejectInProgress?: boolean;
+    /** HTTP methods to apply middleware to (default: ['POST', 'PUT', 'PATCH']) */
+    methods?: string[];
+}
+/**
+ * Create Express middleware that enforces idempotency on HTTP handlers.
+ */
+export declare function vanadiumMiddleware(idempotency: IdempotencyEngine, options?: VanadiumMiddlewareOptions): RequestHandler;
+export {};
+//# sourceMappingURL=express.d.ts.map

package/dist/types/http/express.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../../src/http/express.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAM3D,UAAU,OAAO;IACf,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACvD,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAED,UAAU,QAAQ;IAChB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC;IAC/B,IAAI,CAAC,IAAI,EAAE,GAAG,GAAG,IAAI,CAAC;IACtB,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,QAAQ,CAAC;IAC/C,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,IAAI,IAAI,CAAC;CACb;AAED,KAAK,YAAY,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,KAAK,IAAI,CAAC;AACxC,KAAK,cAAc,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,IAAI,CAAC;AAKhF,MAAM,WAAW,yBAAyB;IACxC,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kEAAkE;IAClE,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,8EAA8E;IAC9E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAWD;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,WAAW,EAAE,iBAAiB,EAC9B,OAAO,GAAE,yBAA8B,GACtC,cAAc,CA4DhB"}

package/dist/types/http/fastify.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Fastify plugin for @periodic/vanadium
+ *
+ * @example
+ * ```ts
+ * import Fastify from 'fastify';
+ * import { createIdempotency, createMemoryAdapter } from '@periodic/vanadium';
+ * import { vanadiumFastifyPlugin } from '@periodic/vanadium/http/fastify';
+ *
+ * const app = Fastify();
+ * const idempotency = createIdempotency({ adapter: createMemoryAdapter(), ttlMs: 86_400_000 });
+ *
+ * await app.register(vanadiumFastifyPlugin, { idempotency });
+ *
+ * app.post('/payments', async (request, reply) => {
+ *   const result = await chargeCard(request.body);
+ *   return result;
+ * });
+ * ```
+ */
+import type { IdempotencyEngine } from '../types/index.js';
+interface FastifyRequest {
+    method: string;
+    url: string;
+    headers: Record<string, string | string[] | undefined>;
+}
+interface FastifyReply {
+    code(statusCode: number): FastifyReply;
+    send(payload?: any): void;
+    statusCode: number;
+    sent: boolean;
+}
+type FastifyHook = (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+interface FastifyInstance {
+    addHook(hookName: string, fn: FastifyHook): void;
+    setErrorHandler(fn: (err: any, req: FastifyRequest, reply: FastifyReply) => void): void;
+}
+export interface VanadiumFastifyOptions {
+    idempotency: IdempotencyEngine;
+    headerName?: string;
+    methods?: string[];
+}
+/**
+ * Register Vanadium idempotency as a Fastify plugin.
+ */
+export declare function vanadiumFastifyPlugin(fastify: FastifyInstance, options: VanadiumFastifyOptions): Promise<void>;
+export {};
+//# sourceMappingURL=fastify.d.ts.map

package/dist/types/http/fastify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastify.d.ts","sourceRoot":"","sources":["../../../src/http/fastify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAM3D,UAAU,cAAc;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;CACxD;AAED,UAAU,YAAY;IACpB,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,YAAY,CAAC;IACvC,IAAI,CAAC,OAAO,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,KAAK,WAAW,GAAG,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnF,UAAU,eAAe;IACvB,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,WAAW,GAAG,IAAI,CAAC;IACjD,eAAe,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,KAAK,IAAI,GAAG,IAAI,CAAC;CACzF;AAKD,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE,iBAAiB,CAAC;IAC/B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAID;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC,CA0Cf"}

package/dist/types/idempotency/engine.d.ts

@@ -0,0 +1,24 @@
+import type { IdempotencyOptions, VanadiumMetrics, IdempotencyEngine as IIdempotencyEngine } from '../types/index.js';
+export declare class IdempotencyEngineImpl implements IIdempotencyEngine {
+    private readonly opts;
+    private readonly metrics;
+    private readonly guard;
+    constructor(options: IdempotencyOptions);
+    execute<T>(key: string, fn: () => Promise<T>, payload?: unknown): Promise<T>;
+    getMetrics(): VanadiumMetrics;
+    resetMetrics(): void;
+    private _executeInternal;
+    private _runFunction;
+    private _runHook;
+}
+/**
+ * Create a new idempotency engine instance.
+ *
+ * @example
+ * ```ts
+ * const idempotency = createIdempotency({ adapter, ttlMs: 60_000 });
+ * const result = await idempotency.execute('payment:123', () => chargeCard());
+ * ```
+ */
+export declare function createIdempotency(options: IdempotencyOptions): IdempotencyEngineImpl;
+//# sourceMappingURL=engine.d.ts.map

package/dist/types/idempotency/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/idempotency/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAElB,eAAe,EACf,iBAAiB,IAAI,kBAAkB,EACxC,MAAM,mBAAmB,CAAC;AAkB3B,qBAAa,qBAAsB,YAAW,kBAAkB;IAC9D,OAAO,CAAC,QAAQ,CAAC,IAAI,CAC+B;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;gBAEpC,OAAO,EAAE,kBAAkB;IAejC,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,CAAC,CAAC;IAKlF,UAAU,IAAI,eAAe;IAI7B,YAAY,IAAI,IAAI;YAMN,gBAAgB;YAoJhB,YAAY;YA6FZ,QAAQ;CAgBvB;AAID;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,kBAAkB,GAAG,qBAAqB,CAEpF"}

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+export { createIdempotency } from './idempotency/engine.js';
+export { createLock } from './lock/engine.js';
+export { createMemoryAdapter } from './adapters/memory/index.js';
+export { createCircuitBreaker } from './resilience/circuitBreaker.js';
+export { createVanadiumMetrics } from './observability/metrics.js';
+export { VanadiumError, isVanadiumError } from './errors/index.js';
+export type { StorageAdapter, StoredRecord, IdempotencyOptions, LockOptions, VanadiumMetrics, VanadiumErrorType, IdempotencyHooks, LockHooks, CircuitBreakerState, ExecutionStatus, } from './types/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,gCAAgC,CAAC;AACtE,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGnE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAGnE,YAAY,EACV,cAAc,EACd,YAAY,EACZ,kBAAkB,EAClB,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,SAAS,EACT,mBAAmB,EACnB,eAAe,GAChB,MAAM,kBAAkB,CAAC"}

package/dist/types/lock/engine.d.ts

@@ -0,0 +1,28 @@
+import type { LockOptions, VanadiumMetrics } from '../types/index.js';
+export declare class LockEngineImpl {
+    private readonly opts;
+    private readonly metrics;
+    constructor(options: LockOptions);
+    /**
+     * Acquire an exclusive lock for `key`, execute `fn`, then release the lock.
+     * Guarantees only one concurrent execution per key across all nodes.
+     *
+     * @throws {VanadiumError} LOCK_ACQUISITION_FAILED | LOCK_TIMEOUT
+     */
+    acquire<T>(key: string, fn: () => Promise<T>): Promise<T>;
+    getMetrics(): Pick<VanadiumMetrics, 'totalLocksAcquired' | 'totalLockFailures'>;
+    private _tryAcquire;
+    private _safeRelease;
+    private _runHook;
+}
+/**
+ * Create a new distributed lock engine.
+ *
+ * @example
+ * ```ts
+ * const lock = createLock({ adapter, ttlMs: 10_000, maxWaitMs: 5_000 });
+ * const result = await lock.acquire('order:123', () => processOrder());
+ * ```
+ */
+export declare function createLock(options: LockOptions): LockEngineImpl;
+//# sourceMappingURL=engine.d.ts.map

package/dist/types/lock/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/lock/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAgB,MAAM,mBAAmB,CAAC;AAgBpF,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAoE;IACzF,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;gBAElC,OAAO,EAAE,WAAW;IAahC;;;;;OAKG;IACG,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IA+D/D,UAAU,IAAI,IAAI,CAAC,eAAe,EAAE,oBAAoB,GAAG,mBAAmB,CAAC;YAUjE,WAAW;YA0DX,YAAY;YAgBZ,QAAQ;CAgBvB;AAID;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,cAAc,CAE/D"}

package/dist/types/observability/metrics.d.ts

@@ -0,0 +1,45 @@
+/**
+ * OpenTelemetry-compatible metrics for @periodic/vanadium
+ *
+ * Peer dependency (optional): "@opentelemetry/api" >= 1.0.0
+ *
+ * If OpenTelemetry is not configured, all metrics gracefully no-op.
+ *
+ * @example
+ * ```ts
+ * import { VanadiumInstrumentation } from '@periodic/vanadium';
+ * // or in your setup:
+ * import { createVanadiumMetrics } from '@periodic/vanadium/observability';
+ *
+ * const metrics = createVanadiumMetrics('my-service');
+ * metrics.recordExecution('payment:123', 'payments', 42);
+ * ```
+ */
+interface OtelMeter {
+    createCounter(name: string, options?: any): {
+        add(value: number, attributes?: any): void;
+    };
+    createHistogram(name: string, options?: any): {
+        record(value: number, attributes?: any): void;
+    };
+    createUpDownCounter(name: string, options?: any): {
+        add(value: number, attributes?: any): void;
+    };
+}
+export interface VanadiumMetricsInstruments {
+    recordExecution(key: string, adapterName: string, durationMs: number): void;
+    recordDuplicate(key: string, adapterName: string): void;
+    recordTakeover(key: string, adapterName: string): void;
+    recordStorageError(key: string, adapterName: string): void;
+    recordPayloadMismatch(key: string, adapterName: string): void;
+    recordLockAcquired(key: string, adapterName: string, durationMs: number): void;
+    recordLockFailed(key: string, adapterName: string, reason: string): void;
+    setInProgressCount(count: number, adapterName: string): void;
+}
+/**
+ * Create metrics instruments. Pass an OTel Meter if you have one,
+ * otherwise all instruments are graceful no-ops.
+ */
+export declare function createVanadiumMetrics(meter?: OtelMeter, scopeName?: string): VanadiumMetricsInstruments;
+export {};
+//# sourceMappingURL=metrics.d.ts.map

package/dist/types/observability/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../src/observability/metrics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,UAAU,SAAS;IACjB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG;QAAE,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;KAAE,CAAC;IAC3F,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG;QAAE,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;KAAE,CAAC;IAChG,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,GAAG;QAAE,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;KAAE,CAAC;CAClG;AAWD,MAAM,WAAW,0BAA0B;IACzC,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5E,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACxD,cAAc,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACvD,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3D,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9D,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/E,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACzE,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9D;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,CAAC,EAAE,SAAS,EACjB,SAAS,SAAsB,GAC9B,0BAA0B,CAiF5B"}

package/dist/types/resilience/circuitBreaker.d.ts

@@ -0,0 +1,48 @@
+import type { CircuitBreakerState, CircuitBreakerOptions } from '../types/index.js';
+import type { StorageAdapter, StoredRecord } from '../types/index.js';
+/**
+ * Wraps a StorageAdapter with a circuit breaker pattern.
+ * Protects the application from repeated storage failures.
+ *
+ * States:
+ * - CLOSED: Normal operation. Failures counted.
+ * - OPEN: Storage blocked. All calls throw immediately.
+ * - HALF_OPEN: Probe mode. Limited calls allowed to test recovery.
+ */
+export declare class CircuitBreakerAdapter implements StorageAdapter {
+    readonly name: string;
+    private state;
+    private failureCount;
+    private successCount;
+    private lastFailureAt;
+    private halfOpenCalls;
+    private readonly adapter;
+    private readonly failureThreshold;
+    private readonly resetTimeoutMs;
+    private readonly halfOpenMaxCalls;
+    private readonly clock;
+    constructor(adapter: StorageAdapter, options?: CircuitBreakerOptions, clock?: () => number);
+    get<T = unknown>(key: string): Promise<StoredRecord<T> | null>;
+    set<T = unknown>(key: string, value: StoredRecord<T>, ttlMs?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+    compareAndSet<T = unknown>(key: string, expectedOwnerToken: string, newValue: StoredRecord<T>, ttlMs?: number): Promise<boolean>;
+    getState(): CircuitBreakerState;
+    reset(): void;
+    private _execute;
+    private _onSuccess;
+    private _onFailure;
+    private _checkReset;
+}
+/**
+ * Wrap any StorageAdapter with a circuit breaker.
+ *
+ * @example
+ * ```ts
+ * const protectedAdapter = createCircuitBreaker(redisAdapter, {
+ *   failureThreshold: 3,
+ *   resetTimeoutMs: 15_000,
+ * });
+ * ```
+ */
+export declare function createCircuitBreaker(adapter: StorageAdapter, options?: CircuitBreakerOptions, clock?: () => number): CircuitBreakerAdapter;
+//# sourceMappingURL=circuitBreaker.d.ts.map

package/dist/types/resilience/circuitBreaker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"circuitBreaker.d.ts","sourceRoot":"","sources":["../../../src/resilience/circuitBreaker.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAC;AACpF,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAUtE;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,YAAW,cAAc;IAC1D,SAAgB,IAAI,EAAE,MAAM,CAAC;IAE7B,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,aAAa,CAAK;IAE1B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAiB;IACzC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAGnC,OAAO,EAAE,cAAc,EACvB,OAAO,GAAE,qBAA0B,EACnC,KAAK,GAAE,MAAM,MAAiB;IAa1B,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC;IAI9D,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpF,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlC,aAAa,CAAC,CAAC,GAAG,OAAO,EAC7B,GAAG,EAAE,MAAM,EACX,kBAAkB,EAAE,MAAM,EAC1B,QAAQ,EAAE,YAAY,CAAC,CAAC,CAAC,EACzB,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,OAAO,CAAC;IAiBnB,QAAQ,IAAI,mBAAmB;IAK/B,KAAK,IAAI,IAAI;YASC,QAAQ;IAsCtB,OAAO,CAAC,UAAU;IASlB,OAAO,CAAC,UAAU;IAWlB,OAAO,CAAC,WAAW;CASpB;AAID;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,cAAc,EACvB,OAAO,CAAC,EAAE,qBAAqB,EAC/B,KAAK,CAAC,EAAE,MAAM,MAAM,GACnB,qBAAqB,CAEvB"}