@crewhaus/idempotency-keys 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crewhaus/idempotency-keys",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Idempotency-key dedup store for the BATCH consumer (Section 23 BATCH)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/idempotency-keys"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/idempotency-keys#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/index.test.ts

@@ -0,0 +1,102 @@
+import { describe, expect, test } from "bun:test";
+import { createInMemoryIdempotencyStore, idempotencyKey, withIdempotency } from "./index.js";
+
+describe("idempotencyKey", () => {
+  test("same (jobId, attempt) → same key (T9 invariant)", () => {
+    const a = idempotencyKey("job_001", 1);
+    const b = idempotencyKey("job_001", 1);
+    expect(a).toBe(b);
+    expect(a).toMatch(/^[0-9a-f]{24}$/);
+  });
+
+  test("different attempts produce different keys", () => {
+    expect(idempotencyKey("job_001", 1)).not.toBe(idempotencyKey("job_001", 2));
+  });
+
+  test("different jobIds produce different keys", () => {
+    expect(idempotencyKey("a", 1)).not.toBe(idempotencyKey("b", 1));
+  });
+});
+
+describe("createInMemoryIdempotencyStore", () => {
+  test("get returns undefined for unknown keys", async () => {
+    const store = createInMemoryIdempotencyStore();
+    expect(await store.get("nope")).toBeUndefined();
+  });
+
+  test("set then get within TTL returns the value", async () => {
+    const store = createInMemoryIdempotencyStore<string>();
+    await store.set("k", "v", 1000);
+    expect(await store.get("k")).toBe("v");
+  });
+
+  test("entries past TTL are evicted on next access", async () => {
+    let t = 1_000;
+    const store = createInMemoryIdempotencyStore<string>({ now: () => t });
+    await store.set("k", "v", 100);
+    expect(await store.get("k")).toBe("v");
+    t = 1_200;
+    expect(await store.get("k")).toBeUndefined();
+    expect(store.size()).toBe(0);
+  });
+});
+
+describe("withIdempotency", () => {
+  test("first call invokes the handler; second call with same key hits cache", async () => {
+    const store = createInMemoryIdempotencyStore<string>();
+    let invocations = 0;
+    const wrapped = withIdempotency<{ x: number }, string>(
+      async (input) => {
+        invocations += 1;
+        return `result-${input.x}-${invocations}`;
+      },
+      { store, ttlMs: 60_000 },
+    );
+    const k = idempotencyKey("job_a", 1);
+    const first = await wrapped({ x: 7 }, k);
+    const second = await wrapped({ x: 7 }, k);
+    expect(invocations).toBe(1);
+    expect(first.fromCache).toBe(false);
+    expect(second.fromCache).toBe(true);
+    expect(second.value).toBe(first.value);
+  });
+
+  test("handler errors do NOT poison the cache (next attempt re-runs)", async () => {
+    const store = createInMemoryIdempotencyStore<string>();
+    let invocations = 0;
+    const wrapped = withIdempotency<unknown, string>(
+      async () => {
+        invocations += 1;
+        if (invocations === 1) throw new Error("transient");
+        return "ok";
+      },
+      { store, ttlMs: 60_000 },
+    );
+    const k = idempotencyKey("job_x", 1);
+    await expect(wrapped(null, k)).rejects.toThrow("transient");
+    const retry = await wrapped(null, k);
+    expect(retry.value).toBe("ok");
+    expect(retry.fromCache).toBe(false);
+    expect(invocations).toBe(2);
+  });
+
+  test("T9 property: 5 retries with the same key call the handler once and return identical results", async () => {
+    const store = createInMemoryIdempotencyStore<string>();
+    let invocations = 0;
+    const wrapped = withIdempotency<unknown, string>(
+      async () => {
+        invocations += 1;
+        return `unique-${Math.random()}`; // would differ on each call
+      },
+      { store, ttlMs: 60_000 },
+    );
+    const key = idempotencyKey("job_p", 1);
+    const results: string[] = [];
+    for (let i = 0; i < 5; i++) {
+      const r = await wrapped(null, key);
+      results.push(r.value);
+    }
+    expect(invocations).toBe(1);
+    expect(new Set(results).size).toBe(1); // all identical
+  });
+});

package/src/index.ts

@@ -0,0 +1,98 @@
+/**
+ * Catalog R7 `idempotency-keys` — Section 23 BATCH.
+ *
+ * Per-key cached-result store the BATCH consumer wraps the user's
+ * handler with so a job that's already been processed (e.g. after a
+ * crash → retry, or after a transient nack that produced a partial
+ * result) returns the cached value without re-invoking the model.
+ *
+ * Key shape: `idempotencyKey(jobId, attempt)` — the consumer derives
+ * the key from the job's id + attempt counter on the queue. Same job
+ * + same attempt → same key, so two consumers grabbing the same job
+ * (the "double-pull" race when visibility leases collide) get the
+ * same cached result.
+ *
+ * The default `createInMemoryIdempotencyStore` is a Map with a per-key
+ * TTL. Eviction happens lazily on next get/set; tests can override the
+ * clock via the `now` injection seam.
+ */
+import { createHash } from "node:crypto";
+
+export type IdempotencyKey = string;
+
+export interface IdempotencyStore<TValue = unknown> {
+  get(key: IdempotencyKey): Promise<TValue | undefined>;
+  /** TTL in ms; entries past TTL are evicted on next access. */
+  set(key: IdempotencyKey, value: TValue, ttlMs: number): Promise<void>;
+  /** Test seam — current entry count after lazy eviction. */
+  size(): number;
+}
+
+/**
+ * Compose a stable key from a job id + attempt number. We hash so the
+ * key fits the typical kv-store key-length limits regardless of job-id
+ * shape.
+ */
+export function idempotencyKey(jobId: string, attempt: number): IdempotencyKey {
+  return createHash("sha256").update(`${jobId}:${attempt}`).digest("hex").slice(0, 24);
+}
+
+export type InMemoryStoreOptions = {
+  readonly now?: () => number;
+};
+
+export function createInMemoryIdempotencyStore<TValue = unknown>(
+  opts: InMemoryStoreOptions = {},
+): IdempotencyStore<TValue> {
+  const now = opts.now ?? Date.now;
+  type Entry = { value: TValue; expiresAt: number };
+  const map = new Map<IdempotencyKey, Entry>();
+
+  function evictExpired(): void {
+    const t = now();
+    for (const [k, v] of map.entries()) {
+      if (v.expiresAt <= t) map.delete(k);
+    }
+  }
+
+  return {
+    async get(key) {
+      evictExpired();
+      const entry = map.get(key);
+      if (entry === undefined) return undefined;
+      return entry.value;
+    },
+    async set(key, value, ttlMs) {
+      evictExpired();
+      map.set(key, { value, expiresAt: now() + ttlMs });
+    },
+    size() {
+      evictExpired();
+      return map.size;
+    },
+  };
+}
+
+/**
+ * `withIdempotency` wraps a handler so a re-invocation with the same
+ * (jobId, attempt) tuple is served from cache. The first call's
+ * SUCCESSFUL result is cached; failures (the handler throws) bypass the
+ * cache so the next attempt re-runs the handler. This matches the
+ * SQS-style "ack on success, nack on failure" contract: the cache is
+ * for ack'd work, not for failed attempts.
+ */
+export function withIdempotency<TInput, TResult>(
+  handler: (input: TInput, key: IdempotencyKey) => Promise<TResult>,
+  opts: {
+    readonly store: IdempotencyStore<TResult>;
+    readonly ttlMs: number;
+  },
+): (input: TInput, key: IdempotencyKey) => Promise<{ value: TResult; fromCache: boolean }> {
+  return async (input, key) => {
+    const cached = await opts.store.get(key);
+    if (cached !== undefined) return { value: cached, fromCache: true };
+    const value = await handler(input, key);
+    await opts.store.set(key, value, opts.ttlMs);
+    return { value, fromCache: false };
+  };
+}