@demlik/tea 0.13.0 → 0.15.0

package/dist/idempotency/index.d.ts

@@ -1,131 +1,105 @@
+import { I as IdempotencyStore } from '../index-Bc40JWVl.js';
+export { a as IdempotencyEntry, e as evictExpired, i as initStore, r as recall, b as remember, s as seen } from '../index-Bc40JWVl.js';
+import { a as CmdOf, b as CmdDef } from '../core-DnzqWy6u.js';
+import { Q as QueueItem } from '../index-CSyMYDAB.js';
+import 'zod';
+import '../runtime-types-CMF13BBh.js';
+import 'better-result';
+
 /**
- * @demlik/tea/idempotency — dedupe-by-key + last-result cache as pure state + ops.
- *
- * Same shape as `@demlik/tea/work-queue`'s `ops.ts` and `@demlik/tea/rate-limit`:
- * a state type plus pure transition functions. Host-agnostic by construction —
- * no `Date.now()`, no timers, no I/O. The caller injects the clock (`nowMs`)
- * and wires the result into its own reducer / interpret. This keeps the store
- * inside TEA's invariant 2 (transitions are pure: same inputs → same outputs,
- * no `Date.now`) so a consumer can fold it through `update` and exercise it
- * with `replay` / the pbt fold without a fake clock.
- *
- * Every op returns a NEW store value and never mutates its input (invariant 1 —
- * state is a value, not a place). `seen` / `recall` are read-shaped predicates;
- * `remember` / `evictExpired` return a new store.
- *
- * The use case: a webhook receiver, a retried queue message, or a repeated user
- * action arrives carrying an idempotency key. `seen(store, key, now)` answers
- * "did I already process this?"; `recall(store, key, now)` returns the cached
- * result so the duplicate request gets the SAME response the original produced
- * rather than re-running the side effect. `remember(store, key, value, now)`
- * records the key + its result after the first run.
- *
- * Two eviction policies keep the store bounded, both injected at `initStore`:
+ * 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`.
  *
- *   - **`ttlMs`** — an entry expires `ttlMs` after the `atMs` it was remembered
- *     at. `seen` / `recall` treat an expired entry as absent; `evictExpired`
- *     (and every `remember`) physically drops it. Without a TTL, entries live
- *     until evicted by capacity. The cutoff is half-open: an entry exactly
- *     `ttlMs` old is expired (`age >= ttlMs` drops it), matching `rate-limit`'s
- *     window edge — a key remembered at `t` no longer counts at `t + ttlMs`.
- *   - **`capacity`** — at most `capacity` entries are retained. When a
- *     `remember` would push the count past `capacity` (after expiry eviction),
- *     the OLDEST entries by insertion `order` are dropped until the count fits.
- *     Without a capacity, the store grows unbounded (TTL alone bounds it).
- *
- * `order` is the insertion-order index that capacity eviction reads — the keys
- * oldest-first. It is the store's own LRU-by-insertion ledger, kept in lockstep
- * with `entries` so `entries` never needs to be sorted to find the oldest.
- *
- * **Overwrite semantics** (decided + pinned by tests): re-`remember`ing an
- * existing key is an UPDATE, not a no-op. It (1) overwrites `value`, (2)
- * refreshes `atMs` to the new `nowMs` — so the TTL clock restarts and a
- * frequently-seen key never expires — and (3) moves the key to the NEWEST
- * position in `order` — so capacity eviction treats a re-remembered key as
- * fresh, not as a stale candidate for eviction. This makes `remember` behave
- * like "touch": a key actively being re-seen is kept alive on both the TTL and
- * capacity axes.
- *
- * NOT exported from the package root — reached via the `@demlik/tea/idempotency`
- * subpath, same one-shape-per-package rule as `work-queue`, `rate-limit`, and
- * `do`.
+ * 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;
+};
 /**
- * A cached entry: the result `value` the original request produced and the
- * clock reading `atMs` it was remembered at. `atMs` is the TTL anchor — expiry
- * is measured from here, and a re-`remember` refreshes it. Both fields are
- * plain data so the whole store is trivially JSON-serializable into a
- * consumer's `Store<S>`.
- */
-interface IdempotencyEntry<V> {
-    readonly value: V;
-    readonly atMs: number;
-}
-/**
- * The dedupe store: a map of `key → entry`, an insertion-`order` ledger
- * (oldest-first) that capacity eviction reads, and the two optional bounds.
+ * 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).
  *
- * `entries` and `order` are kept in lockstep — every key in `order` has an
- * entry and vice versa. `capacity` / `ttlMs` are carried on the store (not
- * passed per-op) so a single value fully describes the policy; a consumer
- * persists the store and rehydrates the same bounds without re-deriving them.
+ * 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 IdempotencyStore<V> {
-    readonly entries: Readonly<Record<string, IdempotencyEntry<V>>>;
-    readonly order: readonly string[];
-    readonly capacity?: number;
+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;
 }
 /**
- * Create an empty store. `capacity` and `ttlMs` are both optional — omit both
- * for an unbounded cache, supply either or both to bound by count, age, or
- * both. Stored on the returned value so every later op reads the policy off
- * the store rather than from a re-passed argument.
- */
-declare function initStore<V>(opts?: {
-    capacity?: number;
-    ttlMs?: number;
-}): IdempotencyStore<V>;
-/**
- * True iff `key` is present AND not expired at `nowMs`. This is the dedupe
- * predicate: a webhook / retried message / repeated action whose key returns
- * `true` has already been processed and should be short-circuited (paired with
- * `recall` to return the original result). PURE — reads only, never mutates.
+ * 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.
  */
-declare function seen<V>(store: IdempotencyStore<V>, key: string, nowMs: number): boolean;
-/**
- * The cached `value` for `key` if present and unexpired at `nowMs`, else
- * `undefined`. Use after `seen` returns `true` to replay the original result to
- * a duplicate request. An expired entry reads as absent (returns `undefined`)
- * even though it is physically still in `entries` until the next `remember` /
- * `evictExpired` drops it. PURE — reads only, never mutates.
- */
-declare function recall<V>(store: IdempotencyStore<V>, key: string, nowMs: number): V | undefined;
+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. */
+declare function intakeProcessDef<P>(): CmdDef<"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;
+}, void, never, unknown>;
+type IntakeProcessCmd<P> = CmdOf<ReturnType<typeof intakeProcessDef<P>>>;
 /**
- * Drop every entry expired at `nowMs` (older than `ttlMs`). Returns a NEW store
- * with the survivors; `order` is rebuilt to drop the same keys, preserving the
- * relative insertion order of the survivors. A no-TTL store returns an
- * equivalent store (nothing ages out). PURE — the input store is never mutated.
+ * A duplicate of an already-completed key arrived — replay the cached result
+ * to the caller instead of re-running the side effect.
  */
-declare function evictExpired<V>(store: IdempotencyStore<V>, nowMs: number): IdempotencyStore<V>;
+declare function intakeReplayDef<R>(): CmdDef<"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;
+}, void, never, unknown>;
+type IntakeReplayCmd<R> = CmdOf<ReturnType<typeof intakeReplayDef<R>>>;
+/** The Cmd union the intake verbs emit. */
+type IntakeCmd<P, R> = IntakeProcessCmd<P> | IntakeReplayCmd<R>;
 /**
- * Record `key → value` at `nowMs`, then enforce both bounds. PURE — returns a
- * new store; the input is untouched.
- *
- * Order of operations (each step matters):
- *   1. **Expiry eviction** — drop everything older than `ttlMs` first, so an
- *      expired key never occupies a capacity slot the new entry could take, and
- *      a stale entry under the same `key` is cleared before the overwrite.
- *   2. **Insert / overwrite** — write the new entry. If `key` already exists,
- *      this is an UPDATE: `value` is overwritten, `atMs` is refreshed to
- *      `nowMs` (restarting the TTL clock), and the key is moved to the NEWEST
- *      position in `order` (removed from wherever it sat, appended at the end).
- *      See the module-level "Overwrite semantics" note.
- *   3. **Capacity eviction** — if the entry count now exceeds `capacity`, drop
- *      the OLDEST keys by `order` until the count fits. Because step 2 moves a
- *      re-remembered key to the newest position, an actively re-seen key is
- *      never the eviction victim.
+ * 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 remember<V>(store: IdempotencyStore<V>, key: string, value: V, nowMs: number): IdempotencyStore<V>;
+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 IdempotencyEntry, type IdempotencyStore, evictExpired, initStore, recall, remember, seen };
+export { IdempotencyStore, type IntakeCmd, type IntakeConfig, type IntakeEntry, type IntakeProcessCmd, type IntakeReplayCmd, type IntakeState, createIntake, intakeProcessDef, intakeReplayDef };

package/dist/idempotency/index.js

@@ -1,3 +1,6 @@
-export { evictExpired, initStore, recall, remember, seen } from '../chunk-K575PT4S.js';
+export { createIntake, intakeProcessDef, intakeReplayDef } from '../chunk-VTQI2NHP.js';
+export { evictExpired, initStore, recall, remember, seen } from '../chunk-PR6TB3BL.js';
+import '../chunk-TXN2KFHF.js';
+import '../chunk-66PY5WYF.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/index-Bc40JWVl.d.ts

@@ -0,0 +1,131 @@
+/**
+ * internal/idempotency/idempotency — dedupe-by-key + last-result cache as pure state + ops.
+ *
+ * Same shape as `../../work-queue`'s `ops.ts` and `../../resilience/rate-limit`:
+ * a state type plus pure transition functions. Host-agnostic by construction —
+ * no `Date.now()`, no timers, no I/O. The caller injects the clock (`nowMs`)
+ * and wires the result into its own reducer / interpret. This keeps the store
+ * inside TEA's invariant 2 (transitions are pure: same inputs → same outputs,
+ * no `Date.now`) so a consumer can fold it through `update` and exercise it
+ * with `replay` / the pbt fold without a fake clock.
+ *
+ * Every op returns a NEW store value and never mutates its input (invariant 1 —
+ * state is a value, not a place). `seen` / `recall` are read-shaped predicates;
+ * `remember` / `evictExpired` return a new store.
+ *
+ * The use case: a webhook receiver, a retried queue message, or a repeated user
+ * action arrives carrying an idempotency key. `seen(store, key, now)` answers
+ * "did I already process this?"; `recall(store, key, now)` returns the cached
+ * result so the duplicate request gets the SAME response the original produced
+ * rather than re-running the side effect. `remember(store, key, value, now)`
+ * records the key + its result after the first run.
+ *
+ * Two eviction policies keep the store bounded, both injected at `initStore`:
+ *
+ *   - **`ttlMs`** — an entry expires `ttlMs` after the `atMs` it was remembered
+ *     at. `seen` / `recall` treat an expired entry as absent; `evictExpired`
+ *     (and every `remember`) physically drops it. Without a TTL, entries live
+ *     until evicted by capacity. The cutoff is half-open: an entry exactly
+ *     `ttlMs` old is expired (`age >= ttlMs` drops it), matching `rate-limit`'s
+ *     window edge — a key remembered at `t` no longer counts at `t + ttlMs`.
+ *   - **`capacity`** — at most `capacity` entries are retained. When a
+ *     `remember` would push the count past `capacity` (after expiry eviction),
+ *     the OLDEST entries by insertion `order` are dropped until the count fits.
+ *     Without a capacity, the store grows unbounded (TTL alone bounds it).
+ *
+ * `order` is the insertion-order index that capacity eviction reads — the keys
+ * oldest-first. It is the store's own LRU-by-insertion ledger, kept in lockstep
+ * with `entries` so `entries` never needs to be sorted to find the oldest.
+ *
+ * **Overwrite semantics** (decided + pinned by tests): re-`remember`ing an
+ * existing key is an UPDATE, not a no-op. It (1) overwrites `value`, (2)
+ * refreshes `atMs` to the new `nowMs` — so the TTL clock restarts and a
+ * frequently-seen key never expires — and (3) moves the key to the NEWEST
+ * position in `order` — so capacity eviction treats a re-remembered key as
+ * fresh, not as a stale candidate for eviction. This makes `remember` behave
+ * like "touch": a key actively being re-seen is kept alive on both the TTL and
+ * capacity axes.
+ *
+ * Internal since #47 — not published on any subpath; reached from inside the
+ * package as `internal/idempotency/idempotency`. Same one-shape-per-package rule
+ * as `work-queue`, `rate-limit`, and `do`.
+ */
+/**
+ * A cached entry: the result `value` the original request produced and the
+ * clock reading `atMs` it was remembered at. `atMs` is the TTL anchor — expiry
+ * is measured from here, and a re-`remember` refreshes it. Both fields are
+ * plain data so the whole store is trivially JSON-serializable into a
+ * consumer's `Store<S>`.
+ */
+interface IdempotencyEntry<V> {
+    readonly value: V;
+    readonly atMs: number;
+}
+/**
+ * The dedupe store: a map of `key → entry`, an insertion-`order` ledger
+ * (oldest-first) that capacity eviction reads, and the two optional bounds.
+ *
+ * `entries` and `order` are kept in lockstep — every key in `order` has an
+ * entry and vice versa. `capacity` / `ttlMs` are carried on the store (not
+ * passed per-op) so a single value fully describes the policy; a consumer
+ * persists the store and rehydrates the same bounds without re-deriving them.
+ */
+interface IdempotencyStore<V> {
+    readonly entries: Readonly<Record<string, IdempotencyEntry<V>>>;
+    readonly order: readonly string[];
+    readonly capacity?: number;
+    readonly ttlMs?: number;
+}
+/**
+ * Create an empty store. `capacity` and `ttlMs` are both optional — omit both
+ * for an unbounded cache, supply either or both to bound by count, age, or
+ * both. Stored on the returned value so every later op reads the policy off
+ * the store rather than from a re-passed argument.
+ */
+declare function initStore<V>(opts?: {
+    capacity?: number;
+    ttlMs?: number;
+}): IdempotencyStore<V>;
+/**
+ * True iff `key` is present AND not expired at `nowMs`. This is the dedupe
+ * predicate: a webhook / retried message / repeated action whose key returns
+ * `true` has already been processed and should be short-circuited (paired with
+ * `recall` to return the original result). PURE — reads only, never mutates.
+ */
+declare function seen<V>(store: IdempotencyStore<V>, key: string, nowMs: number): boolean;
+/**
+ * The cached `value` for `key` if present and unexpired at `nowMs`, else
+ * `undefined`. Use after `seen` returns `true` to replay the original result to
+ * a duplicate request. An expired entry reads as absent (returns `undefined`)
+ * even though it is physically still in `entries` until the next `remember` /
+ * `evictExpired` drops it. PURE — reads only, never mutates.
+ */
+declare function recall<V>(store: IdempotencyStore<V>, key: string, nowMs: number): V | undefined;
+/**
+ * Drop every entry expired at `nowMs` (older than `ttlMs`). Returns a NEW store
+ * with the survivors; `order` is rebuilt to drop the same keys, preserving the
+ * relative insertion order of the survivors. A no-TTL store returns an
+ * equivalent store (nothing ages out). PURE — the input store is never mutated.
+ */
+declare function evictExpired<V>(store: IdempotencyStore<V>, nowMs: number): IdempotencyStore<V>;
+/**
+ * Record `key → value` at `nowMs`, then enforce both bounds. PURE — returns a
+ * new store; the input is untouched.
+ *
+ * Order of operations (each step matters):
+ *   1. **Expiry eviction** — drop everything older than `ttlMs` first, so an
+ *      expired key never occupies a capacity slot the new entry could take, and
+ *      a stale entry under the same `key` is cleared before the overwrite.
+ *   2. **Insert / overwrite** — write the new entry. If `key` already exists,
+ *      this is an UPDATE: `value` is overwritten, `atMs` is refreshed to
+ *      `nowMs` (restarting the TTL clock), and the key is moved to the NEWEST
+ *      position in `order` (removed from wherever it sat, appended at the end).
+ *      See the module-level "Overwrite semantics" note.
+ *   3. **Capacity eviction** — if the entry count now exceeds `capacity`, drop
+ *      the OLDEST keys by `order` until the count fits. Because step 2 moves a
+ *      re-remembered key to the newest position, an actively re-seen key is
+ *      never the eviction victim.
+ */
+declare function remember<V>(store: IdempotencyStore<V>, key: string, value: V, nowMs: number): IdempotencyStore<V>;
+
+export { type IdempotencyStore as I, type IdempotencyEntry as a, remember as b, evictExpired as e, initStore as i, recall as r, seen as s };

package/dist/{batch-window/index.d.ts → index-C2DwkjlP.d.ts}

@@ -1,14 +1,9 @@
-import { C as Cmd } from '../core-Co0LWkIA.js';
-export { Debounced, debounce } from '../debounce/index.js';
-import { DeadlineExceeded, DeadlineSub } from '../deadline/index.js';
-import { S as SubscribeHandler } from '../types-XS_miRnB.js';
-export { EnqueueInput } from '../work-queue/index.js';
-import 'zod';
-import '../runtime-types-CNLmhWif.js';
-import 'better-result';
+import { C as Cmd } from './core-DnzqWy6u.js';
+import { S as SubscribeHandler } from './types-BseNPIhr.js';
+import { D as DeadlineExceeded, a as DeadlineSub } from './index-HSYgG2Yt.js';
 
 /**
- * @demlik/tea/batch-window — coalesce a stream of items into size- or
+ * internal/flow/batch-window — coalesce a stream of items into size- or
  * time-bounded BATCHES, then flush each batch as a single Cmd.
  *
  * What this module actually DELEGATES to, vs. what it merely RE-EXPORTS:
@@ -63,8 +58,8 @@ import 'better-result';
  * is the consumer's — it is where the batch meets I/O (an `enqueue`, a network
  * POST, an R2 write).
  *
- * NOT exported from the package root — reached via the `@demlik/tea/batch-window`
- * subpath, same one-shape-per-package rule as `deadline`, `cache`, and
+ * Internal since #48 — not published on any subpath; reached from inside the
+ * package as `internal/flow/batch-window`. Same one-shape-per-package rule as `deadline`, `cache`, and
  * `work-queue`.
  */
 
@@ -258,4 +253,4 @@ declare const subscribeBatchWindow: SubscribeHandler<BatchWindowSub, BatchWindow
  */
 declare function createBatchWindow<I, C extends Cmd>(config: BatchWindowConfig<I, C>): BatchWindowKnob<I, C>;
 
-export { type BatchWindow, type BatchWindowConfig, type BatchWindowExpired, type BatchWindowKnob, type BatchWindowSub, addItem, batchWindowExpired, createBatchWindow, initBatchWindow, onWindow, subsFor, subscribeBatchWindow };
+export { type BatchWindow as B, type BatchWindowSub as a, type BatchWindowExpired as b, type BatchWindowConfig as c, type BatchWindowKnob as d, addItem as e, batchWindowExpired as f, createBatchWindow as g, subscribeBatchWindow as h, initBatchWindow as i, onWindow as o, subsFor as s };