@periodic/vanadium 1.0.0

package/dist/esm/http/fastify.js

@@ -0,0 +1,67 @@
+/**
+ * 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 { isVanadiumError } from '../errors/index.js';
+// ─── Plugin ───────────────────────────────────────────────────────────────────
+/**
+ * Register Vanadium idempotency as a Fastify plugin.
+ */
+export async function vanadiumFastifyPlugin(fastify, options) {
+    const { idempotency } = options;
+    const headerName = options.headerName ?? 'idempotency-key';
+    const methods = (options.methods ?? ['POST', 'PUT', 'PATCH']).map((m) => m.toUpperCase());
+    fastify.addHook('preHandler', async (request, reply) => {
+        if (!methods.includes(request.method.toUpperCase()))
+            return;
+        const rawHeader = request.headers[headerName.toLowerCase()];
+        const idempotencyKey = Array.isArray(rawHeader) ? rawHeader[0] : rawHeader;
+        if (!idempotencyKey)
+            return;
+        const fullKey = `http:${request.method}:${request.url}:${idempotencyKey}`;
+        try {
+            // For Fastify, we check if a COMPLETED result exists and replay it
+            // The actual execution is handled downstream
+            const existing = await idempotency
+                .execute(fullKey, async () => {
+                // placeholder — real response will be captured in onSend
+                return null;
+            })
+                .catch((err) => {
+                if (isVanadiumError(err) && err.type === 'IN_PROGRESS') {
+                    reply.code(409).send({
+                        error: 'Request is currently being processed',
+                        type: 'IN_PROGRESS',
+                        key: err.key,
+                    });
+                }
+                throw err;
+            });
+            if (existing !== null && reply.sent === false) {
+                reply.code(200).send(existing);
+            }
+        }
+        catch (err) {
+            if (isVanadiumError(err) && err.type === 'DUPLICATE_EXECUTION') {
+                return; // Already sent cached response
+            }
+        }
+    });
+}
+//# sourceMappingURL=fastify.js.map

package/dist/esm/http/fastify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fastify.js","sourceRoot":"","sources":["../../../src/http/fastify.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAkCrD,iFAAiF;AAEjF;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,OAAwB,EACxB,OAA+B;IAE/B,MAAM,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC;IAChC,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,iBAAiB,CAAC;IAC3D,MAAM,OAAO,GAAG,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC,CAAC;IAE1F,OAAO,CAAC,OAAO,CAAC,YAAY,EAAE,KAAK,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE;QACrD,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC;YAAE,OAAO;QAE5D,MAAM,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;QAC5D,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC3E,IAAI,CAAC,cAAc;YAAE,OAAO;QAE5B,MAAM,OAAO,GAAG,QAAQ,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,IAAI,cAAc,EAAE,CAAC;QAE1E,IAAI,CAAC;YACH,mEAAmE;YACnE,6CAA6C;YAC7C,MAAM,QAAQ,GAAG,MAAM,WAAW;iBAC/B,OAAO,CAAC,OAAO,EAAE,KAAK,IAAI,EAAE;gBAC3B,yDAAyD;gBACzD,OAAO,IAAI,CAAC;YACd,CAAC,CAAC;iBACD,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;gBACb,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;oBACvD,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;wBACnB,KAAK,EAAE,sCAAsC;wBAC7C,IAAI,EAAE,aAAa;wBACnB,GAAG,EAAE,GAAG,CAAC,GAAG;qBACb,CAAC,CAAC;gBACL,CAAC;gBACD,MAAM,GAAG,CAAC;YACZ,CAAC,CAAC,CAAC;YAEL,IAAI,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;gBAC9C,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACjC,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,eAAe,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,IAAI,KAAK,qBAAqB,EAAE,CAAC;gBAC/D,OAAO,CAAC,+BAA+B;YACzC,CAAC;QACH,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/esm/idempotency/engine.js

@@ -0,0 +1,261 @@
+import { createDuplicateExecutionError, createInProgressError, createPayloadMismatchError, createStorageError, } from '../errors/index.js';
+import { MetricsStore } from '../core/metrics.js';
+import { ConcurrencyGuard } from '../core/concurrencyGuard.js';
+import { canTakeover, assertValidTransition } from '../core/stateMachine.js';
+import { hashPayload, generateOwnerToken } from '../utils/crypto.js';
+import { validateKey } from '../utils/keys.js';
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const DEFAULT_IN_PROGRESS_EXPIRY_MS = 5 * 60 * 1000; // 5 minutes
+// ─── Idempotency Engine ───────────────────────────────────────────────────────
+export class IdempotencyEngineImpl {
+    constructor(options) {
+        this.metrics = new MetricsStore();
+        this.guard = new ConcurrencyGuard();
+        this.opts = {
+            adapter: options.adapter,
+            ttlMs: options.ttlMs ?? DEFAULT_TTL_MS,
+            inProgressExpiryMs: options.inProgressExpiryMs ?? DEFAULT_IN_PROGRESS_EXPIRY_MS,
+            hashPayload: options.hashPayload ?? false,
+            cacheFailures: options.cacheFailures ?? false,
+            clock: options.clock ?? Date.now,
+            onDuplicate: options.onDuplicate,
+            hooks: options.hooks,
+        };
+    }
+    // ── Public API ────────────────────────────────────────────────────────────
+    async execute(key, fn, payload) {
+        validateKey(key, this.opts.adapter.name);
+        return this.guard.wrap(key, () => this._executeInternal(key, fn, payload));
+    }
+    getMetrics() {
+        return this.metrics.get();
+    }
+    resetMetrics() {
+        this.metrics.reset();
+    }
+    // ── Core Execution Flow ───────────────────────────────────────────────────
+    async _executeInternal(key, fn, payload) {
+        const { adapter, clock, 
+        // ttlMs,
+        inProgressExpiryMs, hashPayload: shouldHash, cacheFailures, } = this.opts;
+        const now = clock();
+        const ownerToken = generateOwnerToken();
+        const incomingHash = shouldHash && payload !== undefined ? hashPayload(payload) : undefined;
+        // ── Step 1: Check existing record ────────────────────────────────────────
+        let existing = null;
+        try {
+            existing = await adapter.get(key);
+        }
+        catch (err) {
+            this.metrics.increment('totalStorageErrors');
+            await this._runHook('onStorageError', err, key);
+            throw createStorageError(key, adapter.name, err, clock);
+        }
+        // ── Step 2: Handle existing record ────────────────────────────────────────
+        if (existing !== null) {
+            // Payload mismatch detection
+            if (incomingHash !== undefined && existing.payloadHash !== undefined) {
+                if (existing.payloadHash !== incomingHash) {
+                    this.metrics.increment('totalPayloadMismatches');
+                    throw createPayloadMismatchError(key, adapter.name, existing.payloadHash, incomingHash, clock);
+                }
+            }
+            // Completed record — return cached result
+            if (existing.status === 'COMPLETED') {
+                this.metrics.increment('totalDuplicates');
+                this.opts.onDuplicate?.({
+                    key,
+                    status: existing.status,
+                    attempts: existing.attempts,
+                    adapterName: adapter.name,
+                });
+                await this._runHook('onDuplicateHit', {
+                    key,
+                    status: existing.status,
+                    attempts: existing.attempts,
+                    adapterName: adapter.name,
+                });
+                return existing.result;
+            }
+            // Failed record with cacheFailures enabled — rethrow cached error
+            if (existing.status === 'FAILED' && cacheFailures) {
+                this.metrics.increment('totalDuplicates');
+                throw createDuplicateExecutionError(key, adapter.name, clock);
+            }
+            // IN_PROGRESS: check for expired takeover
+            if (existing.status === 'IN_PROGRESS') {
+                if (canTakeover(existing.status, existing.expiresAt, clock)) {
+                    // Takeover: increment attempts, assign new owner
+                    const takeoverRecord = {
+                        ...existing,
+                        ownerToken,
+                        attempts: existing.attempts + 1,
+                        updatedAt: now,
+                        expiresAt: now + inProgressExpiryMs,
+                    };
+                    assertValidTransition('IN_PROGRESS', 'IN_PROGRESS', key, adapter.name, clock);
+                    try {
+                        if (adapter.compareAndSet) {
+                            const success = await adapter.compareAndSet(key, existing.ownerToken ?? '', takeoverRecord, inProgressExpiryMs);
+                            if (!success) {
+                                // Another node beat us to the takeover
+                                throw createInProgressError(key, adapter.name, existing.attempts, clock);
+                            }
+                        }
+                        else {
+                            await adapter.set(key, takeoverRecord, inProgressExpiryMs);
+                        }
+                    }
+                    catch (err) {
+                        if (err.type === 'IN_PROGRESS')
+                            throw err;
+                        this.metrics.increment('totalStorageErrors');
+                        throw createStorageError(key, adapter.name, err, clock);
+                    }
+                    this.metrics.increment('totalTakeovers');
+                    await this._runHook('onTakeover', {
+                        key,
+                        previousOwnerToken: existing.ownerToken,
+                        newOwnerToken: ownerToken,
+                        attempts: takeoverRecord.attempts,
+                        adapterName: adapter.name,
+                    });
+                    return this._runFunction(key, fn, ownerToken, takeoverRecord.attempts, incomingHash);
+                }
+                // Truly in-progress — reject
+                this.metrics.increment('totalDuplicates');
+                throw createInProgressError(key, adapter.name, existing.attempts, clock);
+            }
+        }
+        // ── Step 3: Claim ownership — write IN_PROGRESS ───────────────────────────
+        const progressRecord = {
+            key,
+            status: 'IN_PROGRESS',
+            ownerToken,
+            attempts: 1,
+            payloadHash: incomingHash,
+            createdAt: now,
+            updatedAt: now,
+            expiresAt: now + inProgressExpiryMs,
+        };
+        try {
+            await adapter.set(key, progressRecord, inProgressExpiryMs);
+        }
+        catch (err) {
+            this.metrics.increment('totalStorageErrors');
+            await this._runHook('onStorageError', err, key);
+            throw createStorageError(key, adapter.name, err, clock);
+        }
+        this.metrics.increment('inProgressCount');
+        this.metrics.increment('totalExecutions');
+        return this._runFunction(key, fn, ownerToken, 1, incomingHash);
+    }
+    // ── Function Execution ────────────────────────────────────────────────────
+    async _runFunction(key, fn, ownerToken, attempt, incomingHash) {
+        const { adapter, clock, ttlMs, cacheFailures } = this.opts;
+        const startedAt = clock();
+        await this._runHook('onBeforeExecute', {
+            key,
+            attempt,
+            adapterName: adapter.name,
+            startedAt,
+        });
+        try {
+            const result = await fn();
+            const completedAt = clock();
+            // Write COMPLETED record
+            assertValidTransition('IN_PROGRESS', 'COMPLETED', key, adapter.name, clock);
+            const completedRecord = {
+                key,
+                status: 'COMPLETED',
+                result,
+                ownerToken,
+                attempts: attempt,
+                payloadHash: incomingHash,
+                createdAt: startedAt,
+                updatedAt: completedAt,
+                expiresAt: completedAt + ttlMs,
+            };
+            try {
+                await adapter.set(key, completedRecord, ttlMs);
+            }
+            catch (err) {
+                this.metrics.increment('totalStorageErrors');
+                await this._runHook('onStorageError', err, key);
+                throw createStorageError(key, adapter.name, err, clock);
+            }
+            this.metrics.decrement('inProgressCount');
+            await this._runHook('onAfterExecute', {
+                key,
+                attempt,
+                adapterName: adapter.name,
+                startedAt,
+                durationMs: completedAt - startedAt,
+            });
+            return result;
+        }
+        catch (err) {
+            // If it's already a VanadiumError from storage, re-throw
+            if (err.type !== undefined)
+                throw err;
+            const failedAt = clock();
+            assertValidTransition('IN_PROGRESS', 'FAILED', key, adapter.name, clock);
+            if (cacheFailures) {
+                const failedRecord = {
+                    key,
+                    status: 'FAILED',
+                    result: undefined,
+                    ownerToken,
+                    attempts: attempt,
+                    createdAt: startedAt,
+                    updatedAt: failedAt,
+                };
+                try {
+                    await adapter.set(key, failedRecord);
+                }
+                catch {
+                    // Best effort — don't mask original error
+                }
+                this.metrics.increment('totalFailuresCached');
+            }
+            else {
+                try {
+                    await adapter.delete(key);
+                }
+                catch {
+                    // Best effort
+                }
+            }
+            this.metrics.decrement('inProgressCount');
+            throw err;
+        }
+    }
+    // ── Hook Runner ───────────────────────────────────────────────────────────
+    async _runHook(hookName, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ...args) {
+        const hook = this.opts.hooks?.[hookName];
+        if (hook) {
+            try {
+                await hook(...args);
+            }
+            catch {
+                // Hooks must never break execution flow
+            }
+        }
+    }
+}
+// ─── Factory ──────────────────────────────────────────────────────────────────
+/**
+ * Create a new idempotency engine instance.
+ *
+ * @example
+ * ```ts
+ * const idempotency = createIdempotency({ adapter, ttlMs: 60_000 });
+ * const result = await idempotency.execute('payment:123', () => chargeCard());
+ * ```
+ */
+export function createIdempotency(options) {
+    return new IdempotencyEngineImpl(options);
+}
+//# sourceMappingURL=engine.js.map

package/dist/esm/idempotency/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../../src/idempotency/engine.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -0,0 +1,9 @@
+// ─── Core ─────────────────────────────────────────────────────────────────────
+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';
+// ─── Errors ───────────────────────────────────────────────────────────────────
+export { VanadiumError, isVanadiumError } from './errors/index.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,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;AAEnE,iFAAiF;AACjF,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/esm/lock/engine.js

@@ -0,0 +1,182 @@
+import { createLockAcquisitionFailedError, createLockTimeoutError, createStorageError, } from '../errors/index.js';
+import { MetricsStore } from '../core/metrics.js';
+import { generateOwnerToken } from '../utils/crypto.js';
+import { validateKey } from '../utils/keys.js';
+import { sleep } from '../utils/sleep.js';
+const DEFAULT_RETRY_INTERVAL_MS = 50;
+const DEFAULT_MAX_WAIT_MS = 0; // 0 = no wait, fail immediately
+// ─── Lock Engine ──────────────────────────────────────────────────────────────
+export class LockEngineImpl {
+    constructor(options) {
+        this.metrics = new MetricsStore();
+        this.opts = {
+            adapter: options.adapter,
+            ttlMs: options.ttlMs,
+            retryIntervalMs: options.retryIntervalMs ?? DEFAULT_RETRY_INTERVAL_MS,
+            maxWaitMs: options.maxWaitMs ?? DEFAULT_MAX_WAIT_MS,
+            clock: options.clock ?? Date.now,
+            hooks: options.hooks,
+        };
+    }
+    // ── Public API ────────────────────────────────────────────────────────────
+    /**
+     * 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
+     */
+    async acquire(key, fn) {
+        validateKey(key, this.opts.adapter.name);
+        const ownerToken = generateOwnerToken();
+        const { adapter, ttlMs, retryIntervalMs, maxWaitMs, clock } = this.opts;
+        const startedAt = clock();
+        const deadline = maxWaitMs > 0 ? startedAt + maxWaitMs : null;
+        // ── Acquire Phase ─────────────────────────────────────────────────────────
+        while (true) {
+            const acquired = await this._tryAcquire(key, ownerToken, ttlMs);
+            if (acquired) {
+                break;
+            }
+            const now = clock();
+            if (deadline !== null && now >= deadline) {
+                this.metrics.increment('totalLockFailures');
+                await this._runHook('onLockFailed', key, 'timeout');
+                throw createLockTimeoutError(key, adapter.name, maxWaitMs, clock);
+            }
+            if (deadline === null) {
+                // No wait — fail immediately
+                this.metrics.increment('totalLockFailures');
+                await this._runHook('onLockFailed', key, 'immediate_fail');
+                throw createLockAcquisitionFailedError(key, adapter.name, clock);
+            }
+            await sleep(retryIntervalMs);
+        }
+        const acquiredAt = clock();
+        this.metrics.increment('totalLocksAcquired');
+        await this._runHook('onLockAcquired', {
+            key,
+            ownerToken,
+            adapterName: adapter.name,
+            acquiredAt,
+            ttlMs,
+        });
+        // ── Execution Phase ───────────────────────────────────────────────────────
+        try {
+            return await fn();
+        }
+        finally {
+            // ── Release Phase (always) ────────────────────────────────────────────
+            await this._safeRelease(key, ownerToken);
+            const releasedAt = clock();
+            await this._runHook('onLockReleased', {
+                key,
+                ownerToken,
+                adapterName: adapter.name,
+                acquiredAt,
+                durationMs: releasedAt - acquiredAt,
+                ttlMs,
+            });
+        }
+    }
+    getMetrics() {
+        const m = this.metrics.get();
+        return {
+            totalLocksAcquired: m.totalLocksAcquired,
+            totalLockFailures: m.totalLockFailures,
+        };
+    }
+    // ── Private ───────────────────────────────────────────────────────────────
+    async _tryAcquire(key, ownerToken, ttlMs) {
+        const { adapter, clock } = this.opts;
+        const now = clock();
+        try {
+            const existing = await adapter.get(key);
+            if (existing !== null) {
+                // Lock is held — check if TTL has expired (deadlock protection)
+                if (existing.expiresAt !== undefined && now >= existing.expiresAt) {
+                    // Expired lock — attempt CAS takeover
+                    if (adapter.compareAndSet) {
+                        const lockRecord = {
+                            key,
+                            status: 'IN_PROGRESS',
+                            ownerToken,
+                            attempts: (existing.attempts ?? 0) + 1,
+                            createdAt: existing.createdAt,
+                            updatedAt: now,
+                            expiresAt: now + ttlMs,
+                        };
+                        const taken = await adapter.compareAndSet(key, existing.ownerToken ?? '', lockRecord, ttlMs);
+                        return taken;
+                    }
+                    // No CAS support — overwrite (less safe, but acceptable for memory adapter)
+                }
+                else {
+                    return false;
+                }
+            }
+            const lockRecord = {
+                key,
+                status: 'IN_PROGRESS',
+                ownerToken,
+                attempts: 1,
+                createdAt: now,
+                updatedAt: now,
+                expiresAt: now + ttlMs,
+            };
+            // Use setIfAbsent if available for atomic initial acquisition
+            if (adapter.setIfAbsent) {
+                return await adapter.setIfAbsent(key, lockRecord, ttlMs);
+            }
+            await adapter.set(key, lockRecord, ttlMs);
+            return true;
+            return true;
+        }
+        catch (err) {
+            if (err.type !== undefined)
+                throw err;
+            throw createStorageError(key, adapter.name, err, clock);
+        }
+    }
+    async _safeRelease(key, ownerToken) {
+        const { adapter, clock } = this.opts;
+        try {
+            const existing = await adapter.get(key);
+            // Only release if we still own the lock
+            if (existing?.ownerToken === ownerToken) {
+                await adapter.delete(key);
+            }
+        }
+        catch {
+            // Best-effort release — TTL will handle cleanup
+            void clock; // reference to avoid unused var
+        }
+    }
+    // ── Hook Runner ───────────────────────────────────────────────────────────
+    async _runHook(hookName, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ...args) {
+        const hook = this.opts.hooks?.[hookName];
+        if (hook) {
+            try {
+                await hook(...args);
+            }
+            catch {
+                // Hooks must never break execution
+            }
+        }
+    }
+}
+// ─── Factory ──────────────────────────────────────────────────────────────────
+/**
+ * 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 function createLock(options) {
+    return new LockEngineImpl(options);
+}
+//# sourceMappingURL=engine.js.map

package/dist/esm/lock/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../../src/lock/engine.ts"],"names":[],"mappings":"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"}

package/dist/esm/observability/metrics.js

@@ -0,0 +1,89 @@
+/**
+ * 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);
+ * ```
+ */
+/* eslint-enable @typescript-eslint/no-explicit-any */
+// ─── No-op instruments ────────────────────────────────────────────────────────
+const noopCounter = { add: () => undefined };
+const noopHistogram = { record: () => undefined };
+const noopUpDownCounter = { add: () => undefined };
+/**
+ * Create metrics instruments. Pass an OTel Meter if you have one,
+ * otherwise all instruments are graceful no-ops.
+ */
+export function createVanadiumMetrics(meter, scopeName = 'periodic.vanadium') {
+    const executionTotal = meter?.createCounter(`${scopeName}.execution_total`, {
+        description: 'Total idempotent executions',
+    }) ?? noopCounter;
+    const duplicateTotal = meter?.createCounter(`${scopeName}.duplicate_hit_total`, {
+        description: 'Total duplicate execution attempts deflected',
+    }) ?? noopCounter;
+    const takeoverTotal = meter?.createCounter(`${scopeName}.takeover_total`, {
+        description: 'Total expired in-progress record takeovers',
+    }) ?? noopCounter;
+    const storageErrorTotal = meter?.createCounter(`${scopeName}.storage_error_total`, {
+        description: 'Total storage adapter errors',
+    }) ?? noopCounter;
+    const payloadMismatchTotal = meter?.createCounter(`${scopeName}.payload_mismatch_total`, {
+        description: 'Total payload hash mismatch rejections',
+    }) ?? noopCounter;
+    const lockAcquiredTotal = meter?.createCounter(`${scopeName}.lock_acquired_total`, {
+        description: 'Total distributed locks acquired',
+    }) ?? noopCounter;
+    const lockFailedTotal = meter?.createCounter(`${scopeName}.lock_failed_total`, {
+        description: 'Total lock acquisition failures',
+    }) ?? noopCounter;
+    const executionDuration = meter?.createHistogram(`${scopeName}.execution_duration_ms`, {
+        description: 'Duration of idempotent function executions in milliseconds',
+        unit: 'ms',
+    }) ?? noopHistogram;
+    const lockDuration = meter?.createHistogram(`${scopeName}.lock_duration_ms`, {
+        description: 'Duration locks were held in milliseconds',
+        unit: 'ms',
+    }) ?? noopHistogram;
+    const inProgressGauge = meter?.createUpDownCounter(`${scopeName}.in_progress_count`, {
+        description: 'Current number of in-progress executions',
+    }) ?? noopUpDownCounter;
+    return {
+        recordExecution(key, adapterName, durationMs) {
+            executionTotal.add(1, { 'idempotency.key': key, 'adapter.name': adapterName });
+            executionDuration.record(durationMs, { 'adapter.name': adapterName });
+        },
+        recordDuplicate(key, adapterName) {
+            duplicateTotal.add(1, { 'idempotency.key': key, 'adapter.name': adapterName });
+        },
+        recordTakeover(key, adapterName) {
+            takeoverTotal.add(1, { 'idempotency.key': key, 'adapter.name': adapterName });
+        },
+        recordStorageError(key, adapterName) {
+            storageErrorTotal.add(1, { 'idempotency.key': key, 'adapter.name': adapterName });
+        },
+        recordPayloadMismatch(key, adapterName) {
+            payloadMismatchTotal.add(1, { 'idempotency.key': key, 'adapter.name': adapterName });
+        },
+        recordLockAcquired(key, adapterName, durationMs) {
+            lockAcquiredTotal.add(1, { 'lock.key': key, 'adapter.name': adapterName });
+            lockDuration.record(durationMs, { 'adapter.name': adapterName });
+        },
+        recordLockFailed(key, adapterName, reason) {
+            lockFailedTotal.add(1, { 'lock.key': key, 'adapter.name': adapterName, reason });
+        },
+        setInProgressCount(count, adapterName) {
+            inProgressGauge.add(count, { 'adapter.name': adapterName });
+        },
+    };
+}
+//# sourceMappingURL=metrics.js.map

package/dist/esm/observability/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../../src/observability/metrics.ts"],"names":[],"mappings":"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"}