@demlik/tea 0.1.0 → 0.1.2

package/dist/idempotent-intake/index.d.ts

@@ -0,0 +1,186 @@
+import { IdempotencyStore } from '../idempotency/index.js';
+import { C as Cmd } from '../core-BoB6t7dB.js';
+import { QueueItem } from '../work-queue/index.js';
+import '../index.js';
+
+/**
+ * @demlik/tea/idempotent-intake — receive-once intake for webhooks / queue
+ * messages: dedupe by key, enqueue the new ones, replay the cached result to
+ * the duplicates. The "process this payload exactly once even though it
+ * arrives N times" knob.
+ *
+ * **The recipe.** This is a Level-2 composition — it owns no primitive
+ * queue/cache logic of its own, it *splices two L1 bricks into one Model slice*
+ * and DELEGATES every transition to their VERB SEAMS — `IdempotencyMemory`
+ * (`../idempotency/adapter`) and `QueueAdapter` (`../work-queue/adapter`) —
+ * so the store ops and the `QueueItem` / `IdempotencyStore` shapes stay
+ * insulated behind verbs the intake calls:
+ *
+ *   - `../idempotency/adapter` — the dedupe-by-key + last-result cache. The
+ *     `seen` half of the slice is its `IdempotencyStore`, keyed by
+ *     `keyOf(payload)`. A key is recorded once `receive` calls `memory.remember`;
+ *     `complete` calls `memory.remember` again to swap its cached value from
+ *     `pending` to the finished `result`. The cache write is the brick's, never
+ *     re-rolled here.
+ *   - `../work-queue/adapter` — the pending-work list. The `queue` half of the
+ *     slice is its `QueueItem<P>[]`. Every status flip routes through the
+ *     adapter verbs: `receive` enqueues via `queue.enqueue`, `claimNext` stamps
+ *     the `running` claim via `queue.patch`, `boot` re-arms a dead worker's
+ *     claim via `queue.patch`. Intake owns only the SELECTION (which item,
+ *     gated on the done-cache reconcile below) — the array transition is the
+ *     brick's. The consumer drains it (claim → process → `complete`) at its own
+ *     pace.
+ *
+ * Both bricks are pure-state + pure-ops, host- and clock-agnostic by
+ * construction, so the combined slice inherits TEA's two non-negotiables:
+ *
+ *   - **Durable** — the slice is a plain serializable value (a record-backed
+ *     idempotency store + an array of queue items, no `Map`, no closures), so
+ *     it survives a Durable-Object eviction / reload and rehydrates whole.
+ *   - **Replayable** — every verb is a pure `(state, …) => [state, Cmd[]]`
+ *     transition; no `Date.now()`, no `Math.random()`, no I/O inside a verb.
+ *     `at` (the clock) and `id` (the queue-item id) are *injected* at the call
+ *     site, so `trace-replay` reconstructs each transition exactly.
+ *
+ * **The decision lives in a Cmd, not in a return shape.** `receive` cannot
+ * "return" what it decided (the knob contract pins the shape to
+ * `[State, Cmd[]]`), so the decision is *reified as a Cmd* the runtime
+ * performs:
+ *
+ *   - first sighting of a key  → mark it `pending`, enqueue the payload, emit
+ *     `IntakeProcess` (go run the work).
+ *   - a key already `pending`  → drop silently (the original is in flight);
+ *     emit nothing.
+ *   - a key already `done`     → emit `IntakeReplay` carrying the cached
+ *     result so the duplicate caller gets the SAME response the first one
+ *     produced, with zero re-execution of the side effect.
+ *
+ * **Two crash-safety guarantees the verbs enforce (and the unit specs alone
+ * missed — see the wired-machine test):**
+ *
+ *   - *A slow worker is never double-enqueued.* The TTL clock starts at
+ *     `complete`, not at `receive`: a `pending` entry NEVER ages out, so a
+ *     duplicate of an in-flight key is always dropped no matter how long the
+ *     worker takes. Only a `done` entry expires (see `liveEntry`).
+ *   - *A complete-then-crash never re-runs.* `boot` and `claimNext` reconcile
+ *     the queue against the done cache: a queue item whose key already resolved
+ *     to `done` in `seen` is skipped (never reset to pending, never claimed),
+ *     so a worker that finished and cached its result before the DO evicted is
+ *     not re-executed on resume.
+ *
+ * Typical wiring (the combinator form — splice ~3 hooks into a host machine):
+ *
+ *   const intake = createIntake<StripeEvent, ChargeResult>({
+ *     keyOf: (e) => e.id,          // Stripe's idempotency key
+ *     ttlMs: 24 * 60 * 60 * 1000,  // a replayed webhook 24h after it COMPLETED is re-run
+ *   });
+ *
+ *   // in `init`:
+ *   intake: intake.init(),
+ *   // in `update`, on the inbound-webhook Msg:
+ *   const [next, cmds] = intake.receive(state.intake, payload, at, id);
+ *   // …route `IntakeProcess` to your worker, `IntakeReplay` to the responder.
+ *   // on the worker's done Msg:
+ *   const [next, _] = intake.complete(state.intake, key, result, at);
+ *   // once, after boot (DO reload), before resuming the drain:
+ *   const [next, _] = intake.boot(state.intake);
+ *
+ * Escape hatch: reach the raw L1 ops via `@demlik/tea/idempotency` and
+ * `@demlik/tea/work-queue` and thread them by hand.
+ */
+
+/**
+ * A cached intake entry: either a key whose work is still in flight
+ * (`pending`) or one whose work has finished and whose `result` is held for
+ * replay to later duplicates (`done`). Discriminated on `phase` — `pending`
+ * carries no payload, `done` carries the result `R`.
+ *
+ * Lives inside the `seen` half of the slice (`IdempotencyStore<IntakeEntry<R>>`).
+ * It is the dedupe ledger's *value*; the ledger's *key* is `keyOf(payload)`.
+ */
+type IntakeEntry<R> = {
+    readonly phase: "pending";
+} | {
+    readonly phase: "done";
+    readonly result: R;
+};
+/**
+ * The intake knob's config — `keyOf` derives the idempotency key from a
+ * payload, `ttlMs` (optional) ages a *completed* cached key out so a webhook
+ * replayed long after the work finished is treated as new and re-processed.
+ *
+ * **The TTL clock starts at `complete`, not at `receive`.** A `pending` entry
+ * (work still in flight) NEVER ages out, no matter how slow the worker is —
+ * ageing a pending key would let the duplicate re-enqueue the in-flight
+ * payload and double-process it. Only a `done` entry expires, measured from
+ * the `at` passed to `complete` (the moment the result was cached). Inside the
+ * window a duplicate replays the cached result; at/after the window it is
+ * re-accepted and re-processed.
+ *
+ * Omit `ttlMs` for a cache whose `done` entries never expire by age (keys live
+ * forever — fine for a bounded universe of ids, unbounded growth otherwise).
+ *
+ * The TTL is owned HERE, not delegated to the composed `IdempotencyStore`: the
+ * store's uniform per-entry TTL cannot tell `pending` from `done`, so intake
+ * keeps the store TTL-free and applies the phase-aware rule itself (see
+ * `liveEntry`).
+ */
+interface IntakeConfig<P> {
+    /** Derive the idempotency key from a payload. Must be pure + deterministic. */
+    readonly keyOf: (payload: P) => string;
+    /**
+     * Age a *completed* key out after this many ms, measured from the `at`
+     * passed to `complete`. Pending keys never age out.
+     */
+    readonly ttlMs?: number;
+}
+/**
+ * The Model slice this knob owns. `seen` is the dedupe + last-result cache
+ * (the `../idempotency` brick); `queue` is the pending-work list (the
+ * `../work-queue` brick). Both are plain serializable values — the whole slice
+ * round-trips through `JSON` so it survives eviction and replays exactly.
+ */
+interface IntakeState<P, R> {
+    readonly seen: IdempotencyStore<IntakeEntry<R>>;
+    readonly queue: readonly QueueItem<P>[];
+}
+/** A genuinely-new payload was accepted and enqueued — go run the work. */
+interface IntakeProcessCmd<P> extends Cmd<"intake:process"> {
+    /** The dedupe key the payload was filed under. */
+    readonly key: string;
+    /** The enqueued queue-item id (the same `id` passed to `receive`). */
+    readonly itemId: string;
+    /** The original payload, for the worker to process. */
+    readonly payload: P;
+}
+/**
+ * A duplicate of an already-completed key arrived — replay the cached result
+ * to the caller instead of re-running the side effect.
+ */
+interface IntakeReplayCmd<R> extends Cmd<"intake:replay"> {
+    /** The dedupe key whose cached result is being replayed. */
+    readonly key: string;
+    /** The result the ORIGINAL request produced, recalled from the cache. */
+    readonly result: R;
+}
+/** The Cmd union the intake verbs emit. */
+type IntakeCmd<P, R> = IntakeProcessCmd<P> | IntakeReplayCmd<R>;
+/**
+ * Build an idempotent-intake knob from `config`. Returns the uniform L2
+ * contract — `init()` + the verbs (`receive`, `complete`, `boot`, `claimNext`).
+ * No `subs` / `handlers`: intake owns no timers and does no I/O of its own (the
+ * composed bricks are pure-ops; the worker that runs `IntakeProcess` and the
+ * responder that runs `IntakeReplay` live in the host's interpret map).
+ */
+declare function createIntake<P, R>(config: IntakeConfig<P>): {
+    init: () => IntakeState<P, R>;
+    receive: (state: IntakeState<P, R>, payload: P, at: number, id: string) => readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]];
+    complete: (state: IntakeState<P, R>, key: string, result: R, at: number) => readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]];
+    boot: (state: IntakeState<P, R>) => readonly [IntakeState<P, R>, readonly IntakeCmd<P, R>[]];
+    claimNext: (state: IntakeState<P, R>, at: number) => {
+        readonly state: IntakeState<P, R>;
+        readonly claimed: QueueItem<P>;
+    } | null;
+};
+
+export { type IntakeCmd, type IntakeConfig, type IntakeEntry, type IntakeProcessCmd, type IntakeReplayCmd, type IntakeState, createIntake };

package/dist/idempotent-intake/index.js

@@ -0,0 +1,7 @@
+export { createIntake } from '../chunk-LEC4U6CX.js';
+import '../chunk-BYQUGDD3.js';
+import '../chunk-K575PT4S.js';
+import '../chunk-HJO6VNQI.js';
+import '../chunk-TGG26XMK.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/idempotent-intake/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}