@lacspace/idempotency 1.0.0

package/LICENSE

@@ -0,0 +1,51 @@
+Lacspace Free Licence
+Version 1.0, August 2026
+
+Copyright (c) 2026 Lacspace
+
+PREAMBLE
+
+This software is published by Lacspace under the Lacspace Free Licence — a free,
+permissive licence that lets you use this software for any purpose, including in
+commercial products and services, at no cost. It grants the same freedoms as
+common permissive open-source licences; the only condition is that this notice
+travels with the software. The canonical, always-current text of this licence is
+maintained at https://lacspace.com/licenses/lacspace-free-1.0
+
+GRANT OF RIGHTS
+
+Permission is hereby granted, free of charge, to any person or organisation
+obtaining a copy of this software and its associated documentation and data files
+(the "Software"), to deal in the Software without restriction, including without
+limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the conditions below. These rights are
+granted for any purpose, personal or commercial, and are perpetual, worldwide,
+non-exclusive, and royalty-free.
+
+CONDITIONS
+
+The above copyright notice, this permission notice, and the name of this licence
+("Lacspace Free Licence") shall be included in all copies or substantial portions
+of the Software.
+
+TRADEMARKS
+
+This licence does not grant permission to use the trade names, trademarks, service
+marks, logos, or product names of Lacspace, except as required to reproduce the
+notice above or to describe the origin of the Software in a truthful manner.
+
+DISCLAIMER OF WARRANTY AND LIMITATION OF LIABILITY
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN
+AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+The Lacspace Free Licence is a source-available, permissive licence and is not (as
+of this version) an OSI-approved licence. In substance it grants the same freedoms
+as the MIT Licence. Learn more at https://lacspace.com/licenses

package/README.md

@@ -0,0 +1,114 @@
+<div align="center">
+
+# @lacspace/idempotency
+
+**Make any operation exactly-once with an idempotency key — replay results on retries, safe under concurrency.**
+
+[![npm version](https://img.shields.io/npm/v/@lacspace/idempotency?color=%2316a34a&label=npm)](https://www.npmjs.com/package/@lacspace/idempotency)
+[![install size](https://packagephobia.com/badge?p=@lacspace/idempotency)](https://packagephobia.com/result?p=@lacspace/idempotency)
+[![minzipped](https://img.shields.io/bundlephobia/minzip/@lacspace/idempotency?label=minzip)](https://bundlephobia.com/package/@lacspace/idempotency)
+[![types](https://img.shields.io/badge/types-included-blue)](https://www.npmjs.com/package/@lacspace/idempotency)
+[![license](https://img.shields.io/npm/l/@lacspace/idempotency?color=green)](https://github.com/lacspace/npm-packages/blob/main/LICENSE)
+
+</div>
+
+> The "don't double-charge the card, don't send the email twice" pattern. A client retries; a webhook fires again; a user double-clicks — and your operation runs **once**, replaying the stored result. Every existing library is welded to a framework (Hono, AWS Lambda); this is the framework-agnostic primitive.
+
+- ♻️ **Exactly-once** — a repeat key replays the cached result instead of re-running
+- 🔒 **Concurrency-safe** — in-flight de-dupe in-process, atomic create-if-absent for shared stores, plus a conflict/wait policy
+- 🔎 Optional **request fingerprint** — catch a key reused with a different payload (Stripe-style)
+- 🧩 Pluggable store (in-memory built in; bring your own Redis / KV / SQL) · zero deps · isomorphic
+
+## Install
+
+```bash
+npm install @lacspace/idempotency      # or pnpm add / yarn add / bun add
+```
+
+## Exactly-once in one call
+
+```ts
+import { idempotent } from "@lacspace/idempotency";
+
+// in a POST handler — the client sends an Idempotency-Key header
+const key = request.headers.get("idempotency-key")!;
+
+const { value, replayed } = await idempotent(key, () => chargeCard(order));
+// first request: runs chargeCard, stores the result   → replayed: false
+// any retry with the same key: returns the SAME result → replayed: true (no second charge)
+
+return Response.json(value);
+```
+
+## Bring your own store
+
+```ts
+import { Idempotency, MemoryIdempotencyStore } from "@lacspace/idempotency";
+
+const idem = new Idempotency({ store: new MemoryIdempotencyStore(60 * 60 * 1000) });
+// implement { get, create, set, delete } over Redis/KV/SQL for multi-instance apps
+```
+
+## Detect key reuse (different payload, same key)
+
+```ts
+import { fingerprint } from "@lacspace/idempotency";
+
+await idem.run(key, () => createOrder(body), { fingerprint: fingerprint(body) });
+// reusing the key with a different body throws IdempotencyKeyReuseError
+```
+
+## Concurrency
+
+```ts
+// Two requests, same key, at the same time:
+const [a, b] = await Promise.all([
+  idem.run(key, work),
+  idem.run(key, work),
+]);
+// work() runs ONCE; both get the same value. a.replayed=false, b.replayed=true
+```
+
+Across processes/instances (shared store), a second call finds an in-progress record and either throws `IdempotencyConflictError` (default) or waits for the result with `{ onConflict: "wait" }`.
+
+## Behaviour
+
+| Situation | Result |
+| --- | --- |
+| New key | runs `fn`, stores result, `replayed: false` |
+| Repeat key (completed) | replays stored value, `replayed: true` |
+| `fn` throws | key is cleared → next call retries (unless `cacheErrors: true`) |
+| `cacheErrors: true` + prior failure | replays a `ReplayedError` |
+| Same key in progress (same process) | de-duped — awaits the one execution |
+| Same key in progress (other instance) | `IdempotencyConflictError`, or waits with `onConflict: "wait"` |
+| Same key, different `fingerprint` | `IdempotencyKeyReuseError` |
+
+## API
+
+| Export | Description |
+| --- | --- |
+| `idempotent(key, fn, opts?)` | run at-most-once via a shared in-memory store |
+| `new Idempotency({ store?, cacheErrors? })` | engine bound to a store |
+| `.run(key, fn, opts?)` → `{ value, replayed }` | the core method |
+| `.forget(key)` | clear a key so it can run fresh |
+| `MemoryIdempotencyStore(ttlMs?)` · `IdempotencyStore` | store + interface |
+| `fingerprint(payload)` | stable, order-independent request signature |
+| `IdempotencyConflictError` · `IdempotencyKeyReuseError` · `ReplayedError` | typed errors |
+
+## Licensing
+
+This package is **free** under the **[Lacspace Free Licence](https://lacspace.com/licenses/lacspace-free-1.0)** — MIT-equivalent freedoms. Use it in personal and commercial projects at no cost; just keep the notice.
+
+Not every Lacspace package is free. We also offer **Commercial** (paid), **Client-specific**, and **Private** (proprietary) packages under separate terms. See the full **[Lacspace Licence Centre](https://lacspace.com/licenses)**.
+
+---
+
+<div align="center">
+
+**Part of the Lacspace ecosystem — zero-dependency, isomorphic TypeScript packages.**
+
+[All packages ↗](https://lacspace.com/packages) · [npm org ↗](https://www.npmjs.com/org/lacspace) · [Licence Centre ↗](https://lacspace.com/licenses) · [GitHub ↗](https://github.com/lacspace/npm-packages)
+
+</div>
+
+<div align="center"><sub>Built with care by <a href="https://lacspace.com">Lacspace</a> · Lacspace Free Licence · <a href="https://github.com/lacspace/npm-packages">source</a></sub></div>

package/dist/index.cjs

@@ -0,0 +1,156 @@
+'use strict';
+
+// src/index.ts
+var IdempotencyConflictError = class extends Error {
+  constructor(key) {
+    super(`An operation for idempotency key "${key}" is already in progress.`);
+    this.key = key;
+    this.code = "conflict";
+    this.name = "IdempotencyConflictError";
+  }
+};
+var IdempotencyKeyReuseError = class extends Error {
+  constructor(key) {
+    super(`Idempotency key "${key}" was reused with a different request payload.`);
+    this.key = key;
+    this.code = "key-reuse";
+    this.name = "IdempotencyKeyReuseError";
+  }
+};
+var ReplayedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.code = "replayed-error";
+    this.name = "ReplayedError";
+  }
+};
+var MemoryIdempotencyStore = class {
+  constructor(ttlMs = 24 * 60 * 60 * 1e3) {
+    this.ttlMs = ttlMs;
+    this.map = /* @__PURE__ */ new Map();
+  }
+  get(key) {
+    const e = this.map.get(key);
+    if (!e) return void 0;
+    if (Date.now() > e.exp) {
+      this.map.delete(key);
+      return void 0;
+    }
+    return e.rec;
+  }
+  create(key, record) {
+    if (this.get(key)) return false;
+    this.map.set(key, { rec: record, exp: Date.now() + this.ttlMs });
+    return true;
+  }
+  set(key, record) {
+    this.map.set(key, { rec: record, exp: Date.now() + this.ttlMs });
+  }
+  delete(key) {
+    this.map.delete(key);
+  }
+};
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;
+}
+function fingerprint(value) {
+  const s = stableStringify(value);
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24)) >>> 0;
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var Idempotency = class {
+  constructor(opts = {}) {
+    this.inflight = /* @__PURE__ */ new Map();
+    this.store = opts.store ?? new MemoryIdempotencyStore();
+    this.cacheErrors = opts.cacheErrors ?? false;
+  }
+  /**
+   * Run `fn` at most once for `key`. A repeat call replays the stored result.
+   *
+   * @example
+   * const { value, replayed } = await idem.run(idempotencyKey, () => charge(order));
+   */
+  async run(key, fn, opts = {}) {
+    const flying = this.inflight.get(key);
+    if (flying) return { value: (await flying).value, replayed: true };
+    const store = opts.store ?? this.store;
+    const cacheErrors = opts.cacheErrors ?? this.cacheErrors;
+    const now = opts.now ?? Date.now();
+    const record = { status: "in-progress", fingerprint: opts.fingerprint, createdAt: now };
+    const exec = (async () => {
+      const existing = await store.get(key);
+      if (existing) {
+        if (opts.fingerprint && existing.fingerprint && existing.fingerprint !== opts.fingerprint) {
+          throw new IdempotencyKeyReuseError(key);
+        }
+        if (existing.status === "completed") return { value: existing.value, fresh: false };
+        if (existing.status === "failed") {
+          if (cacheErrors) throw new ReplayedError(existing.error ?? "Operation previously failed.");
+          await store.delete(key);
+        } else {
+          if ((opts.onConflict ?? "throw") === "wait") return { value: await this.waitFor(store, key, opts), fresh: false };
+          throw new IdempotencyConflictError(key);
+        }
+      }
+      const created = await store.create(key, record);
+      if (!created) {
+        if ((opts.onConflict ?? "throw") === "wait") return { value: await this.waitFor(store, key, opts), fresh: false };
+        throw new IdempotencyConflictError(key);
+      }
+      try {
+        const value = await fn();
+        await store.set(key, { status: "completed", value, fingerprint: opts.fingerprint, createdAt: record.createdAt, completedAt: Date.now() });
+        return { value, fresh: true };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (cacheErrors) await store.set(key, { status: "failed", error: message, fingerprint: opts.fingerprint, createdAt: record.createdAt, completedAt: Date.now() });
+        else await store.delete(key);
+        throw err;
+      }
+    })().finally(() => this.inflight.delete(key));
+    this.inflight.set(key, exec);
+    const out = await exec;
+    return { value: out.value, replayed: !out.fresh };
+  }
+  async waitFor(store, key, opts) {
+    const interval = opts.pollIntervalMs ?? 50;
+    const timeout = opts.waitTimeoutMs ?? 1e4;
+    const start = Date.now();
+    for (; ; ) {
+      const rec = await store.get(key);
+      if (!rec || rec.status === "completed") {
+        if (rec?.status === "completed") return rec.value;
+        throw new IdempotencyConflictError(key);
+      }
+      if (rec.status === "failed") throw new ReplayedError(rec.error ?? "Operation failed.");
+      if (Date.now() - start > timeout) throw new IdempotencyConflictError(key);
+      await sleep(interval);
+    }
+  }
+  /** Forget a key so its operation can run fresh again. */
+  async forget(key, store) {
+    await (store ?? this.store).delete(key);
+  }
+};
+var shared = new Idempotency();
+function idempotent(key, fn, opts) {
+  return shared.run(key, fn, opts);
+}
+
+exports.Idempotency = Idempotency;
+exports.IdempotencyConflictError = IdempotencyConflictError;
+exports.IdempotencyKeyReuseError = IdempotencyKeyReuseError;
+exports.MemoryIdempotencyStore = MemoryIdempotencyStore;
+exports.ReplayedError = ReplayedError;
+exports.fingerprint = fingerprint;
+exports.idempotent = idempotent;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @lacspace/idempotency\n *\n * Make any operation exactly-once with an idempotency key — the \"run this at\n * most once, and replay the stored result on retries\" pattern that payment APIs\n * and webhook handlers need. Framework-agnostic (every existing lib is locked to\n * Hono / AWS Lambda), zero-dependency, isomorphic.\n *\n * - Replay the cached result for a repeated key (never double-charge / double-send)\n * - Safe under concurrency: in-flight de-dupe in-process, atomic \"create-if-absent\"\n *   for shared stores, and a conflict/wait policy for the rest\n * - Optional request fingerprint → detect a key reused with a different payload\n * - Pluggable store (in-memory built in; bring your own Redis/KV/SQL)\n */\n\nexport type RecordStatus = \"in-progress\" | \"completed\" | \"failed\";\n\nexport interface IdempotencyRecord<T = unknown> {\n  status: RecordStatus;\n  value?: T;\n  error?: string;\n  /** Optional request signature to detect key reuse with different params. */\n  fingerprint?: string;\n  createdAt: number;\n  completedAt?: number;\n}\n\nexport interface IdempotencyStore {\n  get(key: string): IdempotencyRecord | undefined | Promise<IdempotencyRecord | undefined>;\n  /** Atomically create an in-progress record only if the key is absent. Returns true when created. */\n  create(key: string, record: IdempotencyRecord): boolean | Promise<boolean>;\n  set(key: string, record: IdempotencyRecord): void | Promise<void>;\n  delete(key: string): void | Promise<void>;\n}\n\n/* ------------------------------ errors ------------------------------ */\n\nexport class IdempotencyConflictError extends Error {\n  readonly code = \"conflict\";\n  constructor(public readonly key: string) {\n    super(`An operation for idempotency key \"${key}\" is already in progress.`);\n    this.name = \"IdempotencyConflictError\";\n  }\n}\n\nexport class IdempotencyKeyReuseError extends Error {\n  readonly code = \"key-reuse\";\n  constructor(public readonly key: string) {\n    super(`Idempotency key \"${key}\" was reused with a different request payload.`);\n    this.name = \"IdempotencyKeyReuseError\";\n  }\n}\n\nexport class ReplayedError extends Error {\n  readonly code = \"replayed-error\";\n  constructor(message: string) {\n    super(message);\n    this.name = \"ReplayedError\";\n  }\n}\n\n/* ------------------------------ in-memory store ------------------------------ */\n\nexport class MemoryIdempotencyStore implements IdempotencyStore {\n  private readonly map = new Map<string, { rec: IdempotencyRecord; exp: number }>();\n  constructor(private readonly ttlMs = 24 * 60 * 60 * 1000) {}\n\n  get(key: string): IdempotencyRecord | undefined {\n    const e = this.map.get(key);\n    if (!e) return undefined;\n    if (Date.now() > e.exp) { this.map.delete(key); return undefined; }\n    return e.rec;\n  }\n  create(key: string, record: IdempotencyRecord): boolean {\n    if (this.get(key)) return false;\n    this.map.set(key, { rec: record, exp: Date.now() + this.ttlMs });\n    return true;\n  }\n  set(key: string, record: IdempotencyRecord): void {\n    this.map.set(key, { rec: record, exp: Date.now() + this.ttlMs });\n  }\n  delete(key: string): void {\n    this.map.delete(key);\n  }\n}\n\n/* ------------------------------ fingerprint ------------------------------ */\n\nfunction stableStringify(value: unknown): string {\n  if (value === null || typeof value !== \"object\") return JSON.stringify(value);\n  if (Array.isArray(value)) return `[${value.map(stableStringify).join(\",\")}]`;\n  const keys = Object.keys(value as Record<string, unknown>).sort();\n  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify((value as Record<string, unknown>)[k])}`).join(\",\")}}`;\n}\n\n/** Stable fingerprint of a request payload (order-independent). Pass it as `fingerprint`. */\nexport function fingerprint(value: unknown): string {\n  const s = stableStringify(value);\n  let h = 0x811c9dc5;\n  for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0; }\n  return (h >>> 0).toString(16).padStart(8, \"0\");\n}\n\n/* ------------------------------ options & result ------------------------------ */\n\nexport interface RunOptions {\n  store?: IdempotencyStore;\n  /** Request signature; a mismatch on the same key throws {@link IdempotencyKeyReuseError}. */\n  fingerprint?: string;\n  /** What to do when another call for the key is in progress. Default \"throw\". */\n  onConflict?: \"throw\" | \"wait\";\n  /** Cache failures too (replay the error). Default false → failures are retryable. */\n  cacheErrors?: boolean;\n  /** Poll interval when waiting (ms). Default 50. */\n  pollIntervalMs?: number;\n  /** Max time to wait for an in-progress op (ms). Default 10_000. */\n  waitTimeoutMs?: number;\n  /** Override \"now\" (ms) — for tests. */\n  now?: number;\n}\n\nexport interface RunResult<T> {\n  value: T;\n  /** True when the result came from a previous run (a replay), not a fresh execution. */\n  replayed: boolean;\n}\n\nconst sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));\n\n/* ------------------------------ the engine ------------------------------ */\n\nexport class Idempotency {\n  private readonly store: IdempotencyStore;\n  private readonly cacheErrors: boolean;\n  private readonly inflight = new Map<string, Promise<unknown>>();\n\n  constructor(opts: { store?: IdempotencyStore; cacheErrors?: boolean } = {}) {\n    this.store = opts.store ?? new MemoryIdempotencyStore();\n    this.cacheErrors = opts.cacheErrors ?? false;\n  }\n\n  /**\n   * Run `fn` at most once for `key`. A repeat call replays the stored result.\n   *\n   * @example\n   * const { value, replayed } = await idem.run(idempotencyKey, () => charge(order));\n   */\n  async run<T>(key: string, fn: () => Promise<T> | T, opts: RunOptions = {}): Promise<RunResult<T>> {\n    // Same-process single-flight: concurrent duplicates await the same execution.\n    const flying = this.inflight.get(key) as Promise<{ value: T; fresh: boolean }> | undefined;\n    if (flying) return { value: (await flying).value, replayed: true };\n\n    const store = opts.store ?? this.store;\n    const cacheErrors = opts.cacheErrors ?? this.cacheErrors;\n    const now = opts.now ?? Date.now();\n    const record: IdempotencyRecord = { status: \"in-progress\", fingerprint: opts.fingerprint, createdAt: now };\n\n    // Register the in-flight promise SYNCHRONOUSLY, before any await, so\n    // truly-concurrent callers see it and don't race on create().\n    const exec = (async (): Promise<{ value: T; fresh: boolean }> => {\n      const existing = await store.get(key);\n      if (existing) {\n        if (opts.fingerprint && existing.fingerprint && existing.fingerprint !== opts.fingerprint) {\n          throw new IdempotencyKeyReuseError(key);\n        }\n        if (existing.status === \"completed\") return { value: existing.value as T, fresh: false };\n        if (existing.status === \"failed\") {\n          if (cacheErrors) throw new ReplayedError(existing.error ?? \"Operation previously failed.\");\n          await store.delete(key); // retryable → clear and re-run below\n        } else {\n          if ((opts.onConflict ?? \"throw\") === \"wait\") return { value: await this.waitFor<T>(store, key, opts), fresh: false };\n          throw new IdempotencyConflictError(key);\n        }\n      }\n      const created = await store.create(key, record);\n      if (!created) {\n        if ((opts.onConflict ?? \"throw\") === \"wait\") return { value: await this.waitFor<T>(store, key, opts), fresh: false };\n        throw new IdempotencyConflictError(key);\n      }\n      try {\n        const value = await fn();\n        await store.set(key, { status: \"completed\", value, fingerprint: opts.fingerprint, createdAt: record.createdAt, completedAt: Date.now() });\n        return { value, fresh: true };\n      } catch (err) {\n        const message = err instanceof Error ? err.message : String(err);\n        if (cacheErrors) await store.set(key, { status: \"failed\", error: message, fingerprint: opts.fingerprint, createdAt: record.createdAt, completedAt: Date.now() });\n        else await store.delete(key);\n        throw err;\n      }\n    })().finally(() => this.inflight.delete(key));\n\n    this.inflight.set(key, exec);\n    const out = await exec;\n    return { value: out.value, replayed: !out.fresh };\n  }\n\n  private async waitFor<T>(store: IdempotencyStore, key: string, opts: RunOptions): Promise<T> {\n    const interval = opts.pollIntervalMs ?? 50;\n    const timeout = opts.waitTimeoutMs ?? 10_000;\n    const start = Date.now();\n    for (;;) {\n      const rec = await store.get(key);\n      if (!rec || rec.status === \"completed\") {\n        if (rec?.status === \"completed\") return rec.value as T;\n        throw new IdempotencyConflictError(key); // vanished mid-wait\n      }\n      if (rec.status === \"failed\") throw new ReplayedError(rec.error ?? \"Operation failed.\");\n      if (Date.now() - start > timeout) throw new IdempotencyConflictError(key);\n      await sleep(interval);\n    }\n  }\n\n  /** Forget a key so its operation can run fresh again. */\n  async forget(key: string, store?: IdempotencyStore): Promise<void> {\n    await (store ?? this.store).delete(key);\n  }\n}\n\n/* ------------------------------ functional default ------------------------------ */\n\nconst shared = new Idempotency();\n\n/**\n * Run `fn` at most once for `key`, using a shared in-memory store (pass\n * `opts.store` for your own). Returns `{ value, replayed }`.\n *\n * @example\n * const { value } = await idempotent(req.headers[\"idempotency-key\"], () => createOrder(body));\n */\nexport function idempotent<T>(key: string, fn: () => Promise<T> | T, opts?: RunOptions): Promise<RunResult<T>> {\n  return shared.run(key, fn, opts);\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,105 @@
+/**
+ * @lacspace/idempotency
+ *
+ * Make any operation exactly-once with an idempotency key — the "run this at
+ * most once, and replay the stored result on retries" pattern that payment APIs
+ * and webhook handlers need. Framework-agnostic (every existing lib is locked to
+ * Hono / AWS Lambda), zero-dependency, isomorphic.
+ *
+ * - Replay the cached result for a repeated key (never double-charge / double-send)
+ * - Safe under concurrency: in-flight de-dupe in-process, atomic "create-if-absent"
+ *   for shared stores, and a conflict/wait policy for the rest
+ * - Optional request fingerprint → detect a key reused with a different payload
+ * - Pluggable store (in-memory built in; bring your own Redis/KV/SQL)
+ */
+type RecordStatus = "in-progress" | "completed" | "failed";
+interface IdempotencyRecord<T = unknown> {
+    status: RecordStatus;
+    value?: T;
+    error?: string;
+    /** Optional request signature to detect key reuse with different params. */
+    fingerprint?: string;
+    createdAt: number;
+    completedAt?: number;
+}
+interface IdempotencyStore {
+    get(key: string): IdempotencyRecord | undefined | Promise<IdempotencyRecord | undefined>;
+    /** Atomically create an in-progress record only if the key is absent. Returns true when created. */
+    create(key: string, record: IdempotencyRecord): boolean | Promise<boolean>;
+    set(key: string, record: IdempotencyRecord): void | Promise<void>;
+    delete(key: string): void | Promise<void>;
+}
+declare class IdempotencyConflictError extends Error {
+    readonly key: string;
+    readonly code = "conflict";
+    constructor(key: string);
+}
+declare class IdempotencyKeyReuseError extends Error {
+    readonly key: string;
+    readonly code = "key-reuse";
+    constructor(key: string);
+}
+declare class ReplayedError extends Error {
+    readonly code = "replayed-error";
+    constructor(message: string);
+}
+declare class MemoryIdempotencyStore implements IdempotencyStore {
+    private readonly ttlMs;
+    private readonly map;
+    constructor(ttlMs?: number);
+    get(key: string): IdempotencyRecord | undefined;
+    create(key: string, record: IdempotencyRecord): boolean;
+    set(key: string, record: IdempotencyRecord): void;
+    delete(key: string): void;
+}
+/** Stable fingerprint of a request payload (order-independent). Pass it as `fingerprint`. */
+declare function fingerprint(value: unknown): string;
+interface RunOptions {
+    store?: IdempotencyStore;
+    /** Request signature; a mismatch on the same key throws {@link IdempotencyKeyReuseError}. */
+    fingerprint?: string;
+    /** What to do when another call for the key is in progress. Default "throw". */
+    onConflict?: "throw" | "wait";
+    /** Cache failures too (replay the error). Default false → failures are retryable. */
+    cacheErrors?: boolean;
+    /** Poll interval when waiting (ms). Default 50. */
+    pollIntervalMs?: number;
+    /** Max time to wait for an in-progress op (ms). Default 10_000. */
+    waitTimeoutMs?: number;
+    /** Override "now" (ms) — for tests. */
+    now?: number;
+}
+interface RunResult<T> {
+    value: T;
+    /** True when the result came from a previous run (a replay), not a fresh execution. */
+    replayed: boolean;
+}
+declare class Idempotency {
+    private readonly store;
+    private readonly cacheErrors;
+    private readonly inflight;
+    constructor(opts?: {
+        store?: IdempotencyStore;
+        cacheErrors?: boolean;
+    });
+    /**
+     * Run `fn` at most once for `key`. A repeat call replays the stored result.
+     *
+     * @example
+     * const { value, replayed } = await idem.run(idempotencyKey, () => charge(order));
+     */
+    run<T>(key: string, fn: () => Promise<T> | T, opts?: RunOptions): Promise<RunResult<T>>;
+    private waitFor;
+    /** Forget a key so its operation can run fresh again. */
+    forget(key: string, store?: IdempotencyStore): Promise<void>;
+}
+/**
+ * Run `fn` at most once for `key`, using a shared in-memory store (pass
+ * `opts.store` for your own). Returns `{ value, replayed }`.
+ *
+ * @example
+ * const { value } = await idempotent(req.headers["idempotency-key"], () => createOrder(body));
+ */
+declare function idempotent<T>(key: string, fn: () => Promise<T> | T, opts?: RunOptions): Promise<RunResult<T>>;
+
+export { Idempotency, IdempotencyConflictError, IdempotencyKeyReuseError, type IdempotencyRecord, type IdempotencyStore, MemoryIdempotencyStore, type RecordStatus, ReplayedError, type RunOptions, type RunResult, fingerprint, idempotent };

package/dist/index.d.ts

@@ -0,0 +1,105 @@
+/**
+ * @lacspace/idempotency
+ *
+ * Make any operation exactly-once with an idempotency key — the "run this at
+ * most once, and replay the stored result on retries" pattern that payment APIs
+ * and webhook handlers need. Framework-agnostic (every existing lib is locked to
+ * Hono / AWS Lambda), zero-dependency, isomorphic.
+ *
+ * - Replay the cached result for a repeated key (never double-charge / double-send)
+ * - Safe under concurrency: in-flight de-dupe in-process, atomic "create-if-absent"
+ *   for shared stores, and a conflict/wait policy for the rest
+ * - Optional request fingerprint → detect a key reused with a different payload
+ * - Pluggable store (in-memory built in; bring your own Redis/KV/SQL)
+ */
+type RecordStatus = "in-progress" | "completed" | "failed";
+interface IdempotencyRecord<T = unknown> {
+    status: RecordStatus;
+    value?: T;
+    error?: string;
+    /** Optional request signature to detect key reuse with different params. */
+    fingerprint?: string;
+    createdAt: number;
+    completedAt?: number;
+}
+interface IdempotencyStore {
+    get(key: string): IdempotencyRecord | undefined | Promise<IdempotencyRecord | undefined>;
+    /** Atomically create an in-progress record only if the key is absent. Returns true when created. */
+    create(key: string, record: IdempotencyRecord): boolean | Promise<boolean>;
+    set(key: string, record: IdempotencyRecord): void | Promise<void>;
+    delete(key: string): void | Promise<void>;
+}
+declare class IdempotencyConflictError extends Error {
+    readonly key: string;
+    readonly code = "conflict";
+    constructor(key: string);
+}
+declare class IdempotencyKeyReuseError extends Error {
+    readonly key: string;
+    readonly code = "key-reuse";
+    constructor(key: string);
+}
+declare class ReplayedError extends Error {
+    readonly code = "replayed-error";
+    constructor(message: string);
+}
+declare class MemoryIdempotencyStore implements IdempotencyStore {
+    private readonly ttlMs;
+    private readonly map;
+    constructor(ttlMs?: number);
+    get(key: string): IdempotencyRecord | undefined;
+    create(key: string, record: IdempotencyRecord): boolean;
+    set(key: string, record: IdempotencyRecord): void;
+    delete(key: string): void;
+}
+/** Stable fingerprint of a request payload (order-independent). Pass it as `fingerprint`. */
+declare function fingerprint(value: unknown): string;
+interface RunOptions {
+    store?: IdempotencyStore;
+    /** Request signature; a mismatch on the same key throws {@link IdempotencyKeyReuseError}. */
+    fingerprint?: string;
+    /** What to do when another call for the key is in progress. Default "throw". */
+    onConflict?: "throw" | "wait";
+    /** Cache failures too (replay the error). Default false → failures are retryable. */
+    cacheErrors?: boolean;
+    /** Poll interval when waiting (ms). Default 50. */
+    pollIntervalMs?: number;
+    /** Max time to wait for an in-progress op (ms). Default 10_000. */
+    waitTimeoutMs?: number;
+    /** Override "now" (ms) — for tests. */
+    now?: number;
+}
+interface RunResult<T> {
+    value: T;
+    /** True when the result came from a previous run (a replay), not a fresh execution. */
+    replayed: boolean;
+}
+declare class Idempotency {
+    private readonly store;
+    private readonly cacheErrors;
+    private readonly inflight;
+    constructor(opts?: {
+        store?: IdempotencyStore;
+        cacheErrors?: boolean;
+    });
+    /**
+     * Run `fn` at most once for `key`. A repeat call replays the stored result.
+     *
+     * @example
+     * const { value, replayed } = await idem.run(idempotencyKey, () => charge(order));
+     */
+    run<T>(key: string, fn: () => Promise<T> | T, opts?: RunOptions): Promise<RunResult<T>>;
+    private waitFor;
+    /** Forget a key so its operation can run fresh again. */
+    forget(key: string, store?: IdempotencyStore): Promise<void>;
+}
+/**
+ * Run `fn` at most once for `key`, using a shared in-memory store (pass
+ * `opts.store` for your own). Returns `{ value, replayed }`.
+ *
+ * @example
+ * const { value } = await idempotent(req.headers["idempotency-key"], () => createOrder(body));
+ */
+declare function idempotent<T>(key: string, fn: () => Promise<T> | T, opts?: RunOptions): Promise<RunResult<T>>;
+
+export { Idempotency, IdempotencyConflictError, IdempotencyKeyReuseError, type IdempotencyRecord, type IdempotencyStore, MemoryIdempotencyStore, type RecordStatus, ReplayedError, type RunOptions, type RunResult, fingerprint, idempotent };

package/dist/index.js

@@ -0,0 +1,148 @@
+// src/index.ts
+var IdempotencyConflictError = class extends Error {
+  constructor(key) {
+    super(`An operation for idempotency key "${key}" is already in progress.`);
+    this.key = key;
+    this.code = "conflict";
+    this.name = "IdempotencyConflictError";
+  }
+};
+var IdempotencyKeyReuseError = class extends Error {
+  constructor(key) {
+    super(`Idempotency key "${key}" was reused with a different request payload.`);
+    this.key = key;
+    this.code = "key-reuse";
+    this.name = "IdempotencyKeyReuseError";
+  }
+};
+var ReplayedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.code = "replayed-error";
+    this.name = "ReplayedError";
+  }
+};
+var MemoryIdempotencyStore = class {
+  constructor(ttlMs = 24 * 60 * 60 * 1e3) {
+    this.ttlMs = ttlMs;
+    this.map = /* @__PURE__ */ new Map();
+  }
+  get(key) {
+    const e = this.map.get(key);
+    if (!e) return void 0;
+    if (Date.now() > e.exp) {
+      this.map.delete(key);
+      return void 0;
+    }
+    return e.rec;
+  }
+  create(key, record) {
+    if (this.get(key)) return false;
+    this.map.set(key, { rec: record, exp: Date.now() + this.ttlMs });
+    return true;
+  }
+  set(key, record) {
+    this.map.set(key, { rec: record, exp: Date.now() + this.ttlMs });
+  }
+  delete(key) {
+    this.map.delete(key);
+  }
+};
+function stableStringify(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  const keys = Object.keys(value).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`).join(",")}}`;
+}
+function fingerprint(value) {
+  const s = stableStringify(value);
+  let h = 2166136261;
+  for (let i = 0; i < s.length; i++) {
+    h ^= s.charCodeAt(i);
+    h = h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24)) >>> 0;
+  }
+  return (h >>> 0).toString(16).padStart(8, "0");
+}
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var Idempotency = class {
+  constructor(opts = {}) {
+    this.inflight = /* @__PURE__ */ new Map();
+    this.store = opts.store ?? new MemoryIdempotencyStore();
+    this.cacheErrors = opts.cacheErrors ?? false;
+  }
+  /**
+   * Run `fn` at most once for `key`. A repeat call replays the stored result.
+   *
+   * @example
+   * const { value, replayed } = await idem.run(idempotencyKey, () => charge(order));
+   */
+  async run(key, fn, opts = {}) {
+    const flying = this.inflight.get(key);
+    if (flying) return { value: (await flying).value, replayed: true };
+    const store = opts.store ?? this.store;
+    const cacheErrors = opts.cacheErrors ?? this.cacheErrors;
+    const now = opts.now ?? Date.now();
+    const record = { status: "in-progress", fingerprint: opts.fingerprint, createdAt: now };
+    const exec = (async () => {
+      const existing = await store.get(key);
+      if (existing) {
+        if (opts.fingerprint && existing.fingerprint && existing.fingerprint !== opts.fingerprint) {
+          throw new IdempotencyKeyReuseError(key);
+        }
+        if (existing.status === "completed") return { value: existing.value, fresh: false };
+        if (existing.status === "failed") {
+          if (cacheErrors) throw new ReplayedError(existing.error ?? "Operation previously failed.");
+          await store.delete(key);
+        } else {
+          if ((opts.onConflict ?? "throw") === "wait") return { value: await this.waitFor(store, key, opts), fresh: false };
+          throw new IdempotencyConflictError(key);
+        }
+      }
+      const created = await store.create(key, record);
+      if (!created) {
+        if ((opts.onConflict ?? "throw") === "wait") return { value: await this.waitFor(store, key, opts), fresh: false };
+        throw new IdempotencyConflictError(key);
+      }
+      try {
+        const value = await fn();
+        await store.set(key, { status: "completed", value, fingerprint: opts.fingerprint, createdAt: record.createdAt, completedAt: Date.now() });
+        return { value, fresh: true };
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        if (cacheErrors) await store.set(key, { status: "failed", error: message, fingerprint: opts.fingerprint, createdAt: record.createdAt, completedAt: Date.now() });
+        else await store.delete(key);
+        throw err;
+      }
+    })().finally(() => this.inflight.delete(key));
+    this.inflight.set(key, exec);
+    const out = await exec;
+    return { value: out.value, replayed: !out.fresh };
+  }
+  async waitFor(store, key, opts) {
+    const interval = opts.pollIntervalMs ?? 50;
+    const timeout = opts.waitTimeoutMs ?? 1e4;
+    const start = Date.now();
+    for (; ; ) {
+      const rec = await store.get(key);
+      if (!rec || rec.status === "completed") {
+        if (rec?.status === "completed") return rec.value;
+        throw new IdempotencyConflictError(key);
+      }
+      if (rec.status === "failed") throw new ReplayedError(rec.error ?? "Operation failed.");
+      if (Date.now() - start > timeout) throw new IdempotencyConflictError(key);
+      await sleep(interval);
+    }
+  }
+  /** Forget a key so its operation can run fresh again. */
+  async forget(key, store) {
+    await (store ?? this.store).delete(key);
+  }
+};
+var shared = new Idempotency();
+function idempotent(key, fn, opts) {
+  return shared.run(key, fn, opts);
+}
+
+export { Idempotency, IdempotencyConflictError, IdempotencyKeyReuseError, MemoryIdempotencyStore, ReplayedError, fingerprint, idempotent };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @lacspace/idempotency\n *\n * Make any operation exactly-once with an idempotency key — the \"run this at\n * most once, and replay the stored result on retries\" pattern that payment APIs\n * and webhook handlers need. Framework-agnostic (every existing lib is locked to\n * Hono / AWS Lambda), zero-dependency, isomorphic.\n *\n * - Replay the cached result for a repeated key (never double-charge / double-send)\n * - Safe under concurrency: in-flight de-dupe in-process, atomic \"create-if-absent\"\n *   for shared stores, and a conflict/wait policy for the rest\n * - Optional request fingerprint → detect a key reused with a different payload\n * - Pluggable store (in-memory built in; bring your own Redis/KV/SQL)\n */\n\nexport type RecordStatus = \"in-progress\" | \"completed\" | \"failed\";\n\nexport interface IdempotencyRecord<T = unknown> {\n  status: RecordStatus;\n  value?: T;\n  error?: string;\n  /** Optional request signature to detect key reuse with different params. */\n  fingerprint?: string;\n  createdAt: number;\n  completedAt?: number;\n}\n\nexport interface IdempotencyStore {\n  get(key: string): IdempotencyRecord | undefined | Promise<IdempotencyRecord | undefined>;\n  /** Atomically create an in-progress record only if the key is absent. Returns true when created. */\n  create(key: string, record: IdempotencyRecord): boolean | Promise<boolean>;\n  set(key: string, record: IdempotencyRecord): void | Promise<void>;\n  delete(key: string): void | Promise<void>;\n}\n\n/* ------------------------------ errors ------------------------------ */\n\nexport class IdempotencyConflictError extends Error {\n  readonly code = \"conflict\";\n  constructor(public readonly key: string) {\n    super(`An operation for idempotency key \"${key}\" is already in progress.`);\n    this.name = \"IdempotencyConflictError\";\n  }\n}\n\nexport class IdempotencyKeyReuseError extends Error {\n  readonly code = \"key-reuse\";\n  constructor(public readonly key: string) {\n    super(`Idempotency key \"${key}\" was reused with a different request payload.`);\n    this.name = \"IdempotencyKeyReuseError\";\n  }\n}\n\nexport class ReplayedError extends Error {\n  readonly code = \"replayed-error\";\n  constructor(message: string) {\n    super(message);\n    this.name = \"ReplayedError\";\n  }\n}\n\n/* ------------------------------ in-memory store ------------------------------ */\n\nexport class MemoryIdempotencyStore implements IdempotencyStore {\n  private readonly map = new Map<string, { rec: IdempotencyRecord; exp: number }>();\n  constructor(private readonly ttlMs = 24 * 60 * 60 * 1000) {}\n\n  get(key: string): IdempotencyRecord | undefined {\n    const e = this.map.get(key);\n    if (!e) return undefined;\n    if (Date.now() > e.exp) { this.map.delete(key); return undefined; }\n    return e.rec;\n  }\n  create(key: string, record: IdempotencyRecord): boolean {\n    if (this.get(key)) return false;\n    this.map.set(key, { rec: record, exp: Date.now() + this.ttlMs });\n    return true;\n  }\n  set(key: string, record: IdempotencyRecord): void {\n    this.map.set(key, { rec: record, exp: Date.now() + this.ttlMs });\n  }\n  delete(key: string): void {\n    this.map.delete(key);\n  }\n}\n\n/* ------------------------------ fingerprint ------------------------------ */\n\nfunction stableStringify(value: unknown): string {\n  if (value === null || typeof value !== \"object\") return JSON.stringify(value);\n  if (Array.isArray(value)) return `[${value.map(stableStringify).join(\",\")}]`;\n  const keys = Object.keys(value as Record<string, unknown>).sort();\n  return `{${keys.map((k) => `${JSON.stringify(k)}:${stableStringify((value as Record<string, unknown>)[k])}`).join(\",\")}}`;\n}\n\n/** Stable fingerprint of a request payload (order-independent). Pass it as `fingerprint`. */\nexport function fingerprint(value: unknown): string {\n  const s = stableStringify(value);\n  let h = 0x811c9dc5;\n  for (let i = 0; i < s.length; i++) { h ^= s.charCodeAt(i); h = (h + ((h << 1) + (h << 4) + (h << 7) + (h << 8) + (h << 24))) >>> 0; }\n  return (h >>> 0).toString(16).padStart(8, \"0\");\n}\n\n/* ------------------------------ options & result ------------------------------ */\n\nexport interface RunOptions {\n  store?: IdempotencyStore;\n  /** Request signature; a mismatch on the same key throws {@link IdempotencyKeyReuseError}. */\n  fingerprint?: string;\n  /** What to do when another call for the key is in progress. Default \"throw\". */\n  onConflict?: \"throw\" | \"wait\";\n  /** Cache failures too (replay the error). Default false → failures are retryable. */\n  cacheErrors?: boolean;\n  /** Poll interval when waiting (ms). Default 50. */\n  pollIntervalMs?: number;\n  /** Max time to wait for an in-progress op (ms). Default 10_000. */\n  waitTimeoutMs?: number;\n  /** Override \"now\" (ms) — for tests. */\n  now?: number;\n}\n\nexport interface RunResult<T> {\n  value: T;\n  /** True when the result came from a previous run (a replay), not a fresh execution. */\n  replayed: boolean;\n}\n\nconst sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));\n\n/* ------------------------------ the engine ------------------------------ */\n\nexport class Idempotency {\n  private readonly store: IdempotencyStore;\n  private readonly cacheErrors: boolean;\n  private readonly inflight = new Map<string, Promise<unknown>>();\n\n  constructor(opts: { store?: IdempotencyStore; cacheErrors?: boolean } = {}) {\n    this.store = opts.store ?? new MemoryIdempotencyStore();\n    this.cacheErrors = opts.cacheErrors ?? false;\n  }\n\n  /**\n   * Run `fn` at most once for `key`. A repeat call replays the stored result.\n   *\n   * @example\n   * const { value, replayed } = await idem.run(idempotencyKey, () => charge(order));\n   */\n  async run<T>(key: string, fn: () => Promise<T> | T, opts: RunOptions = {}): Promise<RunResult<T>> {\n    // Same-process single-flight: concurrent duplicates await the same execution.\n    const flying = this.inflight.get(key) as Promise<{ value: T; fresh: boolean }> | undefined;\n    if (flying) return { value: (await flying).value, replayed: true };\n\n    const store = opts.store ?? this.store;\n    const cacheErrors = opts.cacheErrors ?? this.cacheErrors;\n    const now = opts.now ?? Date.now();\n    const record: IdempotencyRecord = { status: \"in-progress\", fingerprint: opts.fingerprint, createdAt: now };\n\n    // Register the in-flight promise SYNCHRONOUSLY, before any await, so\n    // truly-concurrent callers see it and don't race on create().\n    const exec = (async (): Promise<{ value: T; fresh: boolean }> => {\n      const existing = await store.get(key);\n      if (existing) {\n        if (opts.fingerprint && existing.fingerprint && existing.fingerprint !== opts.fingerprint) {\n          throw new IdempotencyKeyReuseError(key);\n        }\n        if (existing.status === \"completed\") return { value: existing.value as T, fresh: false };\n        if (existing.status === \"failed\") {\n          if (cacheErrors) throw new ReplayedError(existing.error ?? \"Operation previously failed.\");\n          await store.delete(key); // retryable → clear and re-run below\n        } else {\n          if ((opts.onConflict ?? \"throw\") === \"wait\") return { value: await this.waitFor<T>(store, key, opts), fresh: false };\n          throw new IdempotencyConflictError(key);\n        }\n      }\n      const created = await store.create(key, record);\n      if (!created) {\n        if ((opts.onConflict ?? \"throw\") === \"wait\") return { value: await this.waitFor<T>(store, key, opts), fresh: false };\n        throw new IdempotencyConflictError(key);\n      }\n      try {\n        const value = await fn();\n        await store.set(key, { status: \"completed\", value, fingerprint: opts.fingerprint, createdAt: record.createdAt, completedAt: Date.now() });\n        return { value, fresh: true };\n      } catch (err) {\n        const message = err instanceof Error ? err.message : String(err);\n        if (cacheErrors) await store.set(key, { status: \"failed\", error: message, fingerprint: opts.fingerprint, createdAt: record.createdAt, completedAt: Date.now() });\n        else await store.delete(key);\n        throw err;\n      }\n    })().finally(() => this.inflight.delete(key));\n\n    this.inflight.set(key, exec);\n    const out = await exec;\n    return { value: out.value, replayed: !out.fresh };\n  }\n\n  private async waitFor<T>(store: IdempotencyStore, key: string, opts: RunOptions): Promise<T> {\n    const interval = opts.pollIntervalMs ?? 50;\n    const timeout = opts.waitTimeoutMs ?? 10_000;\n    const start = Date.now();\n    for (;;) {\n      const rec = await store.get(key);\n      if (!rec || rec.status === \"completed\") {\n        if (rec?.status === \"completed\") return rec.value as T;\n        throw new IdempotencyConflictError(key); // vanished mid-wait\n      }\n      if (rec.status === \"failed\") throw new ReplayedError(rec.error ?? \"Operation failed.\");\n      if (Date.now() - start > timeout) throw new IdempotencyConflictError(key);\n      await sleep(interval);\n    }\n  }\n\n  /** Forget a key so its operation can run fresh again. */\n  async forget(key: string, store?: IdempotencyStore): Promise<void> {\n    await (store ?? this.store).delete(key);\n  }\n}\n\n/* ------------------------------ functional default ------------------------------ */\n\nconst shared = new Idempotency();\n\n/**\n * Run `fn` at most once for `key`, using a shared in-memory store (pass\n * `opts.store` for your own). Returns `{ value, replayed }`.\n *\n * @example\n * const { value } = await idempotent(req.headers[\"idempotency-key\"], () => createOrder(body));\n */\nexport function idempotent<T>(key: string, fn: () => Promise<T> | T, opts?: RunOptions): Promise<RunResult<T>> {\n  return shared.run(key, fn, opts);\n}\n"]}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@lacspace/idempotency",
+  "version": "1.0.0",
+  "description": "Make any operation exactly-once with an idempotency key — replay stored results on retries, safe under concurrency, with optional request fingerprinting. Framework-agnostic, pluggable store, zero-dependency, isomorphic.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "idempotency",
+    "idempotency-key",
+    "idempotent",
+    "exactly-once",
+    "deduplication",
+    "dedupe",
+    "retry-safe",
+    "payment-safety",
+    "webhook-idempotency",
+    "stripe-idempotency",
+    "concurrency",
+    "isomorphic",
+    "typescript"
+  ],
+  "author": "Lacspace <contact@lacspace.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://lacspace.com/packages",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lacspace/npm-packages.git",
+    "directory": "idempotency"
+  },
+  "bugs": {
+    "url": "https://github.com/lacspace/npm-packages/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}