@periodic/vanadium 1.0.0

package/dist/cjs/cleanup/engine.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CleanupEngine = void 0;
+exports.createCleanupEngine = createCleanupEngine;
+const DEFAULT_INTERVAL_MS = 60000; // 1 minute
+const DEFAULT_STALE_THRESHOLD_MS = 10 * 60000; // 10 minutes
+// ─── Cleanup Engine ───────────────────────────────────────────────────────────
+/**
+ * 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());
+ * ```
+ */
+class CleanupEngine {
+    constructor(options) {
+        this.intervalHandle = null;
+        this.running = false;
+        this.adapter = options.adapter;
+        this.intervalMs = options.intervalMs ?? DEFAULT_INTERVAL_MS;
+        this.staleThresholdMs = options.staleThresholdMs ?? DEFAULT_STALE_THRESHOLD_MS;
+        this.deleteOnClean = options.deleteOnClean ?? true;
+        this.clock = options.clock ?? Date.now;
+    }
+    /**
+     * Start the cleanup timer.
+     */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.intervalHandle = setInterval(() => {
+            void this._runCleanup();
+        }, this.intervalMs);
+        // Allow process to exit without waiting for cleanup timer
+        if (this.intervalHandle.unref) {
+            this.intervalHandle.unref();
+        }
+    }
+    /**
+     * Stop the cleanup timer gracefully.
+     */
+    stop() {
+        if (this.intervalHandle !== null) {
+            clearInterval(this.intervalHandle);
+            this.intervalHandle = null;
+        }
+        this.running = false;
+    }
+    /**
+     * Run a single cleanup pass manually (useful for testing).
+     */
+    async runOnce(keysToCheck) {
+        return this._cleanKeys(keysToCheck);
+    }
+    // ── Private ───────────────────────────────────────────────────────────────
+    async _runCleanup() {
+        // NOTE: The cleanup engine operates on keys that callers explicitly provide.
+        // A full scan requires adapter-level support (e.g., SCAN in Redis, SELECT in Postgres).
+        // This base implementation is a no-op periodic tick — adapters may extend it.
+        // Use runOnce(keys) to clean specific known stale keys.
+    }
+    async _cleanKeys(keys) {
+        const now = this.clock();
+        let cleaned = 0;
+        for (const key of keys) {
+            try {
+                const record = await this.adapter.get(key);
+                if (!record)
+                    continue;
+                if (record.status !== 'IN_PROGRESS')
+                    continue;
+                const staleAt = record.updatedAt + this.staleThresholdMs;
+                if (now < staleAt)
+                    continue;
+                if (this.deleteOnClean) {
+                    await this.adapter.delete(key);
+                }
+                cleaned++;
+            }
+            catch {
+                // Best effort — never let cleanup crash the app
+            }
+        }
+        return cleaned;
+    }
+}
+exports.CleanupEngine = CleanupEngine;
+// ─── Factory ──────────────────────────────────────────────────────────────────
+function createCleanupEngine(options) {
+    return new CleanupEngine(options);
+}
+//# sourceMappingURL=engine.js.map

package/dist/cjs/cleanup/engine.js.map

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

package/dist/cjs/core/concurrencyGuard.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConcurrencyGuard = void 0;
+/**
+ * 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.
+ */
+class ConcurrencyGuard {
+    constructor() {
+        this.inFlight = new Map();
+    }
+    /**
+     * If a promise for this key is already in-flight, return it.
+     * Otherwise, register the new promise and clean up when it settles.
+     */
+    wrap(key, fn) {
+        const existing = this.inFlight.get(key);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const promise = fn().finally(() => {
+            this.inFlight.delete(key);
+        });
+        this.inFlight.set(key, promise);
+        return promise;
+    }
+    /**
+     * Check if a key is currently in-flight locally.
+     */
+    isInFlight(key) {
+        return this.inFlight.has(key);
+    }
+    /**
+     * Return the number of keys currently tracked.
+     */
+    size() {
+        return this.inFlight.size;
+    }
+    /**
+     * Clear all tracked keys (for testing / cleanup).
+     */
+    clear() {
+        this.inFlight.clear();
+    }
+}
+exports.ConcurrencyGuard = ConcurrencyGuard;
+//# sourceMappingURL=concurrencyGuard.js.map

package/dist/cjs/core/concurrencyGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"concurrencyGuard.js","sourceRoot":"","sources":["../../../src/core/concurrencyGuard.ts"],"names":[],"mappings":";;;AAAA;;;;;;GAMG;AACH,MAAa,gBAAgB;IAA7B;QACmB,aAAQ,GAAG,IAAI,GAAG,EAA4B,CAAC;IAwClE,CAAC;IAtCC;;;OAGG;IACH,IAAI,CAAI,GAAW,EAAE,EAAoB;QACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACxC,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,OAAO,QAAsB,CAAC;QAChC,CAAC;QAED,MAAM,OAAO,GAAG,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,EAAE;YAChC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAChC,OAAO,OAAO,CAAC;IACjB,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,GAAW;QACpB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IAED;;OAEG;IACH,IAAI;QACF,OAAO,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,KAAK;QACH,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE,CAAC;IACxB,CAAC;CACF;AAzCD,4CAyCC"}

package/dist/cjs/core/metrics.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MetricsStore = void 0;
+// ─── Metrics Store ────────────────────────────────────────────────────────────
+/**
+ * Mutable metrics container. One instance per engine.
+ * Never uses global state.
+ */
+class MetricsStore {
+    constructor() {
+        this.data = {
+            totalExecutions: 0,
+            totalDuplicates: 0,
+            totalLocksAcquired: 0,
+            totalLockFailures: 0,
+            totalPayloadMismatches: 0,
+            inProgressCount: 0,
+            totalTakeovers: 0,
+            totalStorageErrors: 0,
+            totalFailuresCached: 0,
+        };
+    }
+    increment(key, amount = 1) {
+        this.data[key] += amount;
+    }
+    decrement(key, amount = 1) {
+        this.data[key] = Math.max(0, this.data[key] - amount);
+    }
+    get() {
+        return { ...this.data };
+    }
+    reset() {
+        for (const key of Object.keys(this.data)) {
+            this.data[key] = 0;
+        }
+    }
+}
+exports.MetricsStore = MetricsStore;
+//# sourceMappingURL=metrics.js.map

package/dist/cjs/core/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../../../src/core/metrics.ts"],"names":[],"mappings":";;;AAEA,iFAAiF;AAEjF;;;GAGG;AACH,MAAa,YAAY;IAAzB;QACU,SAAI,GAAoB;YAC9B,eAAe,EAAE,CAAC;YAClB,eAAe,EAAE,CAAC;YAClB,kBAAkB,EAAE,CAAC;YACrB,iBAAiB,EAAE,CAAC;YACpB,sBAAsB,EAAE,CAAC;YACzB,eAAe,EAAE,CAAC;YAClB,cAAc,EAAE,CAAC;YACjB,kBAAkB,EAAE,CAAC;YACrB,mBAAmB,EAAE,CAAC;SACvB,CAAC;IAmBJ,CAAC;IAjBC,SAAS,CAAC,GAA0B,EAAE,MAAM,GAAG,CAAC;QAC9C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC;IAC3B,CAAC;IAED,SAAS,CAAC,GAA0B,EAAE,MAAM,GAAG,CAAC;QAC9C,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC;IACxD,CAAC;IAED,GAAG;QACD,OAAO,EAAE,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;IAC1B,CAAC;IAED,KAAK;QACH,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAA8B,EAAE,CAAC;YACtE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACrB,CAAC;IACH,CAAC;CACF;AA9BD,oCA8BC"}

package/dist/cjs/core/stateMachine.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertValidTransition = assertValidTransition;
+exports.isValidTransition = isValidTransition;
+exports.isExpired = isExpired;
+exports.canTakeover = canTakeover;
+const index_js_1 = require("../errors/index.js");
+// ─── Valid Transitions ────────────────────────────────────────────────────────
+const VALID_TRANSITIONS = new Set([
+    'IN_PROGRESS -> COMPLETED',
+    'IN_PROGRESS -> FAILED',
+    'IN_PROGRESS -> IN_PROGRESS', // expired takeover only
+]);
+// ─── State Machine ────────────────────────────────────────────────────────────
+/**
+ * Assert that a transition from one execution status to another is valid.
+ * Throws a VanadiumError(STATE_TRANSITION_ERROR) on illegal transitions.
+ */
+function assertValidTransition(from, to, key, adapterName, clock = Date.now) {
+    const transition = `${from} -> ${to}`;
+    if (!VALID_TRANSITIONS.has(transition)) {
+        throw (0, index_js_1.createStateTransitionError)(key, adapterName, from, to, clock);
+    }
+}
+/**
+ * Check if a transition is valid without throwing.
+ */
+function isValidTransition(from, to) {
+    return VALID_TRANSITIONS.has(`${from} -> ${to}`);
+}
+/**
+ * Determine whether a stored record has expired based on current time.
+ */
+function isExpired(expiresAt, clock = Date.now) {
+    if (expiresAt === undefined)
+        return false;
+    return clock() >= expiresAt;
+}
+/**
+ * Determine whether an IN_PROGRESS record can be taken over.
+ * Requires: status is IN_PROGRESS AND expiresAt has passed.
+ */
+function canTakeover(status, expiresAt, clock = Date.now) {
+    return status === 'IN_PROGRESS' && isExpired(expiresAt, clock);
+}
+//# sourceMappingURL=stateMachine.js.map

package/dist/cjs/core/stateMachine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stateMachine.js","sourceRoot":"","sources":["../../../src/core/stateMachine.ts"],"names":[],"mappings":";;AAiBA,sDAWC;AAKD,8CAEC;AAKD,8BAGC;AAMD,kCAMC;AAtDD,iDAAgE;AAEhE,iFAAiF;AAEjF,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAS;IACxC,0BAA0B;IAC1B,uBAAuB;IACvB,4BAA4B,EAAE,wBAAwB;CACvD,CAAC,CAAC;AAEH,iFAAiF;AAEjF;;;GAGG;AACH,SAAgB,qBAAqB,CACnC,IAAqB,EACrB,EAAmB,EACnB,GAAW,EACX,WAAmB,EACnB,QAAsB,IAAI,CAAC,GAAG;IAE9B,MAAM,UAAU,GAAG,GAAG,IAAI,OAAO,EAAE,EAAE,CAAC;IACtC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;QACvC,MAAM,IAAA,qCAA0B,EAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,CAAC,CAAC;IACtE,CAAC;AACH,CAAC;AAED;;GAEG;AACH,SAAgB,iBAAiB,CAAC,IAAqB,EAAE,EAAmB;IAC1E,OAAO,iBAAiB,CAAC,GAAG,CAAC,GAAG,IAAI,OAAO,EAAE,EAAE,CAAC,CAAC;AACnD,CAAC;AAED;;GAEG;AACH,SAAgB,SAAS,CAAC,SAA6B,EAAE,QAAsB,IAAI,CAAC,GAAG;IACrF,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,KAAK,EAAE,IAAI,SAAS,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,SAAgB,WAAW,CACzB,MAAuB,EACvB,SAA6B,EAC7B,QAAsB,IAAI,CAAC,GAAG;IAE9B,OAAO,MAAM,KAAK,aAAa,IAAI,SAAS,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;AACjE,CAAC"}

package/dist/cjs/errors/index.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VanadiumError = void 0;
+exports.createDuplicateExecutionError = createDuplicateExecutionError;
+exports.createInProgressError = createInProgressError;
+exports.createLockAcquisitionFailedError = createLockAcquisitionFailedError;
+exports.createLockTimeoutError = createLockTimeoutError;
+exports.createPayloadMismatchError = createPayloadMismatchError;
+exports.createConfigurationError = createConfigurationError;
+exports.createStorageError = createStorageError;
+exports.createStateTransitionError = createStateTransitionError;
+exports.isVanadiumError = isVanadiumError;
+class VanadiumError extends Error {
+    constructor(details) {
+        super(details.message);
+        this.name = 'VanadiumError';
+        this.type = details.type;
+        this.key = details.key;
+        this.adapterName = details.adapterName;
+        this.timestamp = details.timestamp;
+        this.originalError = details.originalError;
+        this.attempts = details.attempts;
+        this.payloadHash = details.payloadHash;
+        // Maintain proper prototype chain
+        Object.setPrototypeOf(this, VanadiumError.prototype);
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, VanadiumError);
+        }
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            type: this.type,
+            message: this.message,
+            key: this.key,
+            adapterName: this.adapterName,
+            timestamp: this.timestamp,
+            attempts: this.attempts,
+            payloadHash: this.payloadHash,
+        };
+    }
+}
+exports.VanadiumError = VanadiumError;
+// ─── Error Factories ──────────────────────────────────────────────────────────
+function createDuplicateExecutionError(key, adapterName, clock = Date.now) {
+    return new VanadiumError({
+        type: 'DUPLICATE_EXECUTION',
+        key,
+        adapterName,
+        timestamp: clock(),
+        message: `Duplicate execution detected for key "${key}". Returning cached result.`,
+    });
+}
+function createInProgressError(key, adapterName, attempts, clock = Date.now) {
+    return new VanadiumError({
+        type: 'IN_PROGRESS',
+        key,
+        adapterName,
+        timestamp: clock(),
+        attempts,
+        message: `Execution for key "${key}" is currently in progress (attempt ${attempts}). Another node owns execution.`,
+    });
+}
+function createLockAcquisitionFailedError(key, adapterName, clock = Date.now) {
+    return new VanadiumError({
+        type: 'LOCK_ACQUISITION_FAILED',
+        key,
+        adapterName,
+        timestamp: clock(),
+        message: `Failed to acquire lock for key "${key}".`,
+    });
+}
+function createLockTimeoutError(key, adapterName, maxWaitMs, clock = Date.now) {
+    return new VanadiumError({
+        type: 'LOCK_TIMEOUT',
+        key,
+        adapterName,
+        timestamp: clock(),
+        message: `Timed out waiting to acquire lock for key "${key}" after ${maxWaitMs}ms.`,
+    });
+}
+function createPayloadMismatchError(key, adapterName, storedHash, incomingHash, clock = Date.now) {
+    return new VanadiumError({
+        type: 'PAYLOAD_MISMATCH',
+        key,
+        adapterName,
+        timestamp: clock(),
+        payloadHash: incomingHash,
+        message: `Payload mismatch for key "${key}". ` +
+            `Stored hash: "${storedHash ?? 'none'}", Incoming hash: "${incomingHash}". ` +
+            `The same idempotency key cannot be used with different payloads.`,
+    });
+}
+function createConfigurationError(key, adapterName, message, clock = Date.now) {
+    return new VanadiumError({
+        type: 'CONFIGURATION_ERROR',
+        key,
+        adapterName,
+        timestamp: clock(),
+        message,
+    });
+}
+function createStorageError(key, adapterName, originalError, clock = Date.now) {
+    const msg = originalError instanceof Error ? originalError.message : String(originalError);
+    return new VanadiumError({
+        type: 'STORAGE_ERROR',
+        key,
+        adapterName,
+        timestamp: clock(),
+        originalError,
+        message: `Storage error for key "${key}" in adapter "${adapterName}": ${msg}`,
+    });
+}
+function createStateTransitionError(key, adapterName, from, to, clock = Date.now) {
+    return new VanadiumError({
+        type: 'STATE_TRANSITION_ERROR',
+        key,
+        adapterName,
+        timestamp: clock(),
+        message: `Invalid state transition for key "${key}": ${from} -> ${to}`,
+    });
+}
+// ─── Type Guard ───────────────────────────────────────────────────────────────
+function isVanadiumError(err) {
+    return err instanceof VanadiumError;
+}
+//# sourceMappingURL=index.js.map

package/dist/cjs/errors/index.js.map

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

package/dist/cjs/http/express.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * 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);
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vanadiumMiddleware = vanadiumMiddleware;
+const index_js_1 = require("../errors/index.js");
+// ─── Middleware Factory ───────────────────────────────────────────────────────
+/**
+ * Create Express middleware that enforces idempotency on HTTP handlers.
+ */
+function vanadiumMiddleware(idempotency, options = {}) {
+    const headerName = options.headerName ?? 'idempotency-key';
+    const methods = (options.methods ?? ['POST', 'PUT', 'PATCH']).map((m) => m.toUpperCase());
+    return function vanadiumHandler(req, res, next) {
+        if (!methods.includes(req.method.toUpperCase())) {
+            next();
+            return;
+        }
+        const rawHeader = req.headers[headerName.toLowerCase()];
+        const idempotencyKey = Array.isArray(rawHeader) ? rawHeader[0] : rawHeader;
+        if (!idempotencyKey) {
+            next();
+            return;
+        }
+        const fullKey = `http:${req.method}:${req.path}:${idempotencyKey}`;
+        void idempotency
+            .execute(fullKey, () => {
+            return new Promise((resolve, _reject) => {
+                // Intercept res.json to capture the response
+                const originalJson = res.json.bind(res);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                res.json = function (body) {
+                    const statusCode = res.statusCode ?? 200;
+                    originalJson(body);
+                    resolve({ statusCode, body });
+                };
+                next();
+            });
+        })
+            .then((cached) => {
+            // If we got here without executing the handler (duplicate), replay cached response
+            if (cached) {
+                res.status(cached.statusCode).json(cached.body);
+            }
+        })
+            .catch((err) => {
+            if ((0, index_js_1.isVanadiumError)(err)) {
+                if (err.type === 'DUPLICATE_EXECUTION') {
+                    // Already handled — no-op
+                    return;
+                }
+                if (err.type === 'IN_PROGRESS') {
+                    res.status(409).json({
+                        error: 'Request is currently being processed',
+                        type: 'IN_PROGRESS',
+                        key: err.key,
+                    });
+                    return;
+                }
+            }
+            next(err);
+        });
+    };
+}
+//# sourceMappingURL=express.js.map

package/dist/cjs/http/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../../../src/http/express.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;;AAiDH,gDA+DC;AA7GD,iDAAqD;AAyCrD,iFAAiF;AAEjF;;GAEG;AACH,SAAgB,kBAAkB,CAChC,WAA8B,EAC9B,UAAqC,EAAE;IAEvC,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,SAAS,eAAe,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB;QAC7E,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,EAAE,CAAC,EAAE,CAAC;YAChD,IAAI,EAAE,CAAC;YACP,OAAO;QACT,CAAC;QAED,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;QACxD,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAE3E,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,IAAI,EAAE,CAAC;YACP,OAAO;QACT,CAAC;QAED,MAAM,OAAO,GAAG,QAAQ,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,IAAI,IAAI,cAAc,EAAE,CAAC;QAEnE,KAAK,WAAW;aACb,OAAO,CAAiB,OAAO,EAAE,GAAG,EAAE;YACrC,OAAO,IAAI,OAAO,CAAiB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE;gBACtD,6CAA6C;gBAC7C,MAAM,YAAY,GAAG,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBAExC,8DAA8D;gBAC9D,GAAG,CAAC,IAAI,GAAG,UAAU,IAAS;oBAC5B,MAAM,UAAU,GAAG,GAAG,CAAC,UAAU,IAAI,GAAG,CAAC;oBACzC,YAAY,CAAC,IAAI,CAAC,CAAC;oBACnB,OAAO,CAAC,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAC;gBAChC,CAAC,CAAC;gBAEF,IAAI,EAAE,CAAC;YACT,CAAC,CAAC,CAAC;QACL,CAAC,CAAC;aACD,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;YACf,mFAAmF;YACnF,IAAI,MAAM,EAAE,CAAC;gBACX,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAClD,CAAC;QACH,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;YACb,IAAI,IAAA,0BAAe,EAAC,GAAG,CAAC,EAAE,CAAC;gBACzB,IAAI,GAAG,CAAC,IAAI,KAAK,qBAAqB,EAAE,CAAC;oBACvC,0BAA0B;oBAC1B,OAAO;gBACT,CAAC;gBACD,IAAI,GAAG,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;oBAC/B,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC;wBACnB,KAAK,EAAE,sCAAsC;wBAC7C,IAAI,EAAE,aAAa;wBACnB,GAAG,EAAE,GAAG,CAAC,GAAG;qBACb,CAAC,CAAC;oBACH,OAAO;gBACT,CAAC;YACH,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,CAAC;QACZ,CAAC,CAAC,CAAC;IACP,CAAC,CAAC;AACJ,CAAC"}

package/dist/cjs/http/fastify.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * 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;
+ * });
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.vanadiumFastifyPlugin = vanadiumFastifyPlugin;
+const index_js_1 = require("../errors/index.js");
+// ─── Plugin ───────────────────────────────────────────────────────────────────
+/**
+ * Register Vanadium idempotency as a Fastify plugin.
+ */
+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 ((0, index_js_1.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 ((0, index_js_1.isVanadiumError)(err) && err.type === 'DUPLICATE_EXECUTION') {
+                return; // Already sent cached response
+            }
+        }
+    });
+}
+//# sourceMappingURL=fastify.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"fastify.js","sourceRoot":"","sources":["../../../src/http/fastify.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;AA0CH,sDA6CC;AApFD,iDAAqD;AAkCrD,iFAAiF;AAEjF;;GAEG;AACI,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,IAAA,0BAAe,EAAC,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,IAAA,0BAAe,EAAC,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"}