@demlik/tea 0.1.0 → 0.1.1

package/dist/batch-window/index.d.ts

@@ -0,0 +1,259 @@
+import { C as Cmd } from '../core-CymXZCeY.js';
+export { Debounced, debounce } from '../debounce/index.js';
+import { DeadlineSub, DeadlineExceeded } from '../deadline/index.js';
+import { S as SubscribeHandler } from '../types-N9LZbdnr.js';
+export { EnqueueInput } from '../work-queue/index.js';
+import '../index.js';
+
+/**
+ * @demlik/tea/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:
+ *
+ *   - `../deadline` — REAL delegation (the only one). The window timer IS a
+ *     `deadline` Sub: `subsFor` returns `deadlineSub` keyed on the window's
+ *     identity, the subscribe cell is `subscribeDeadline` verbatim, and the
+ *     expiry Msg is `deadlineExceeded`. Nothing about the timer is redrawn here.
+ *     "Fire at an absolute instant, even across a rehydrate" is exactly
+ *     `deadline`'s absolute-target lifecycle: a late subscribe (post-`Store`
+ *     rehydrate) recomputes the remaining delay from the current clock and still
+ *     fires at the correct moment.
+ *   - `../work-queue` — TYPE re-export only, NOT a sink this module calls. A
+ *     flush emits a Cmd; the CONSUMER's interpret handler is what enqueues onto a
+ *     `createQueue(store)`. This module never touches queue status — it has no
+ *     queue state and no status flip to delegate. It re-exports `EnqueueInput<I>`
+ *     purely so the consumer's flush Cmd and queue agree on the item shape; any
+ *     actual status flip belongs in the consumer and is delegated to
+ *     `../work-queue/ops` there, not here.
+ *   - `../debounce` — VALUE/TYPE re-export only, NOT wired into `update`. A
+ *     bursty source (keystrokes, scroll, websocket frames) can be `debounce`d at
+ *     the host BEFORE it ever becomes an `add` Msg, so the batch window only sees
+ *     settled items. `debounce` is a sink transformer OUTSIDE `update`;
+ *     batch-window is the durable, replayable half inside it. Re-exported for
+ *     one-import ergonomics — this module does not call it.
+ *
+ * Why this is a knob and not hand-wired logic: the managed state (the buffer +
+ * the window-open instant) lives in the Model, so it survives DO eviction /
+ * reload (durable) and every transition is still a Msg through `update`
+ * (replayable). A closure holding a `setTimeout` and a mutable array would break
+ * both — banned. `add` / `onWindow` are PURE: time arrives as an `at`
+ * parameter, never `Date.now()`; they return NEW slice values, never mutate.
+ *
+ * Typical wiring (combinator form):
+ *
+ *   const bw = createBatchWindow<LogLine, Msg>({
+ *     maxItems: 100,
+ *     maxMs: 5_000,
+ *     flush: (items) => ({ type: "FlushBatch", items }),
+ *   });
+ *
+ *   // Model:        { batch: BatchWindow<LogLine>, ... }
+ *   // init:         (loaded) => [loaded ?? { batch: bw.init(), ... }, []]
+ *   // update cells:
+ *   //   LogArrived:   (s, m) => mapBatch(s, bw.add(s.batch, m.line, m.at))
+ *   //   WindowFired:  (s, m) => mapBatch(s, bw.onWindow(s.batch, m.atMs))
+ *   // subscriptions: (s) => bw.subs(s.batch)
+ *   // subscribe:     { ...bw.handlers() }
+ *
+ * where `mapBatch(s, [batch, cmds]) => [{ ...s, batch }, cmds]` lifts the slice
+ * transition into the consumer's Model. The `FlushBatch` Cmd's interpret handler
+ * 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
+ * `work-queue`.
+ */
+
+/**
+ * Configuration for a batch window — the knob. Pure config, no mutable state
+ * (the `BatchWindow<I>` slice carries that). One config object is shared across
+ * every window of one logical stream (often a module-scope const).
+ *
+ * `flush` is a pure Cmd CONSTRUCTOR, not a closure-with-state: it maps the
+ * buffered items to the single Cmd the runtime performs when a window closes.
+ * Keeping it a `(items) => Cmd` (not a `(items) => void`) is what keeps the
+ * trigger replayable — the flush is a Cmd in the transition's output, never a
+ * side effect inside the verb.
+ */
+interface BatchWindowConfig<I, C extends Cmd> {
+    /**
+     * Size trigger. A batch flushes the instant its buffer reaches `maxItems`,
+     * WITHOUT waiting for the time window — the classic "send as soon as the
+     * page is full" cutoff. Must be `>= 1`; a config of `maxItems: 0` would flush
+     * an empty batch on every `add`, which is never useful, so callers treat `1`
+     * as the floor (the verb still behaves: with `maxItems <= 1` every item
+     * flushes on arrival, a degenerate but legal "no batching" window).
+     */
+    readonly maxItems: number;
+    /**
+     * Time trigger, in milliseconds. A batch flushes no later than `openedAt +
+     * maxMs` — `openedAt` being the `at` of the item that opened the window. This
+     * is the latency ceiling: an item never waits longer than `maxMs` to ship,
+     * even if the buffer never reaches `maxItems`.
+     */
+    readonly maxMs: number;
+    /**
+     * Map a flushed batch to the single Cmd the runtime performs. Called with the
+     * buffered items in arrival order; the returned Cmd is what `add` / `onWindow`
+     * emit when a window closes. PURE constructor — no I/O, no clock; the I/O
+     * happens later in the consumer's interpret handler for the returned Cmd.
+     */
+    readonly flush: (items: readonly I[]) => C;
+}
+/**
+ * The Model slice a batch window owns. `buffer` is the items accumulated for the
+ * current open window; `openedAt` is the `at` of the item that OPENED it (the
+ * anchor the time trigger measures against), or `null` when the window is
+ * closed (buffer empty). The pair is the single source of truth for "is a
+ * window open, and when must it flush by?" — both plain data so the whole slice
+ * is trivially JSON-serializable into a consumer's `Store<S>`.
+ *
+ * Invariant the verbs preserve: `buffer.length === 0` IFF `openedAt === null`.
+ * A non-empty buffer always has an `openedAt`; an empty buffer never does. The
+ * window timer Sub keys its arm/disarm off exactly this invariant.
+ */
+interface BatchWindow<I> {
+    readonly buffer: readonly I[];
+    readonly openedAt: number | null;
+}
+/** The starting slice: closed window, empty buffer. */
+declare function initBatchWindow<I>(): BatchWindow<I>;
+/**
+ * The Sub a batch window's open timer produces: it IS `../deadline`'s
+ * `DeadlineSub`, not a re-tagged copy. `atMs` is the absolute flush-by instant
+ * (`openedAt + maxMs`). Aliasing the deadline type (rather than redeclaring an
+ * identical shape) is what lets `subsFor` return `deadlineSub(...)` with no
+ * cast — the value's static type already satisfies this name. Consumers running
+ * several windows route each one by the Sub's `id`, not by a distinct type.
+ */
+type BatchWindowSub = DeadlineSub;
+/** The Msg a closed-by-time window dispatches. Alias of `deadline`'s Msg. */
+type BatchWindowExpired = DeadlineExceeded;
+/**
+ * Construct the window-expired Msg for the window identified by `id`, flushing
+ * by `atMs`. Re-exported alias of `deadlineExceeded` so the subscribe cell and
+ * the consumer's reducer share one constructor rather than two literals that
+ * can drift. The consumer handles it in a reducer cell by calling `onWindow`.
+ */
+declare function batchWindowExpired(id: string, atMs: number): BatchWindowExpired;
+/**
+ * The bound knob returned by `createBatchWindow`. `init` + the two pure verbs +
+ * `subs` + `handlers`, all closing over one `BatchWindowConfig`. The verbs
+ * return `readonly [BatchWindow<I>, readonly C[]]`: the next slice and the Cmds
+ * to emit (one `flush` Cmd when a window closes, none otherwise).
+ */
+interface BatchWindowKnob<I, C extends Cmd> {
+    /** The starting slice — `initBatchWindow()`. */
+    init(): BatchWindow<I>;
+    /**
+     * Buffer `item` (arrival-stamped `at`), flushing immediately if that brings
+     * the buffer to `maxItems`. See `addItem`.
+     */
+    add(state: BatchWindow<I>, item: I, at: number): readonly [BatchWindow<I>, readonly C[]];
+    /**
+     * Flush whatever is buffered because the time window closed. See `onWindow`.
+     */
+    onWindow(state: BatchWindow<I>, at: number): readonly [BatchWindow<I>, readonly C[]];
+    /**
+     * The window timer Sub, armed only while a window is open. See `subsFor`.
+     * `id` keys the deadline so several windows on one machine route distinctly.
+     */
+    subs(state: BatchWindow<I>, id?: string): readonly BatchWindowSub[];
+    /**
+     * The `subscribe` cells this knob splices into `machine.subscribe`. One cell,
+     * keyed `"deadline"`, delegating to `../deadline`'s subscribe handler. Spread
+     * into the consumer's subscribe map: `subscribe: { ...bw.handlers() }`.
+     */
+    handlers(): {
+        deadline: SubscribeHandler<BatchWindowSub, BatchWindowExpired, unknown>;
+    };
+}
+/**
+ * Buffer `item` and decide whether the size trigger fires. PURE.
+ *
+ * - Empty (closed) window → `item` OPENS it: `openedAt` becomes `at`, buffer
+ *   becomes `[item]`. This is the anchor the time window measures against.
+ * - Open window → `item` appends; `openedAt` is left untouched (the window's
+ *   latency clock keeps running from the FIRST item, not this one).
+ *
+ * After buffering, if the buffer has reached `maxItems` the window flushes
+ * immediately: emit `config.flush(buffer)` and RESET to the closed slice. The
+ * size trigger pre-empts the time trigger — a full page ships now, the window
+ * Sub for the (now closed) window disarms on the next reconcile because `subs`
+ * returns `[]` for an empty buffer.
+ *
+ * `maxItems <= 1` is the degenerate "no batching" case: every item flushes on
+ * arrival (buffer reaches 1 immediately). Legal and useful as a feature flag to
+ * disable batching without restructuring the wiring.
+ *
+ * @param config the knob (maxItems / flush constructor)
+ * @param state  the current slice
+ * @param item   the item to buffer
+ * @param at     the arrival instant (epoch ms) — the caller stamps it; the verb
+ *               never reads the clock
+ */
+declare function addItem<I, C extends Cmd>(config: BatchWindowConfig<I, C>, state: BatchWindow<I>, item: I, at: number): readonly [BatchWindow<I>, readonly C[]];
+/**
+ * Flush the open window because its time bound was reached. PURE.
+ *
+ * - Open window (buffer non-empty) → emit `config.flush(buffer)` and RESET to
+ *   the closed slice.
+ * - Closed window (buffer empty) → no-op: return the same slice and no Cmds.
+ *   This guards the race where the size trigger already flushed and reset the
+ *   window before the time Sub's Msg lands — a stale `onWindow` after a
+ *   size-flush must NOT emit an empty batch.
+ *
+ * `at` is accepted for symmetry with `add` and so the consumer's reducer cell
+ * has a uniform `(state, at)` shape; the verb doesn't need it for the flush
+ * decision (the buffer's emptiness is the whole signal), but taking it keeps a
+ * future "flush only if the window is genuinely past `openedAt + maxMs`"
+ * tightening a non-breaking change.
+ *
+ * @param config the knob (flush constructor)
+ * @param state  the current slice
+ * @param at     the firing instant (epoch ms) — the caller stamps it; the verb
+ *               never reads the clock
+ */
+declare function onWindow<I, C extends Cmd>(config: BatchWindowConfig<I, C>, state: BatchWindow<I>, _at: number): readonly [BatchWindow<I>, readonly C[]];
+/**
+ * The window timer Sub, derived from the slice. PURE.
+ *
+ * Returns the single `deadline` Sub targeting `openedAt + maxMs` while a window
+ * is open (buffer non-empty), or `[]` while it is closed. The substrate's
+ * reconcile pass arms the timer when the array gains the Sub and disarms it
+ * (clearing the pending `setTimeout`) when the array loses it — so a size-flush
+ * that empties the buffer auto-cancels the now-irrelevant time trigger on the
+ * next transition.
+ *
+ * `id` defaults to `"batch-window"`; pass a distinct id per window when a
+ * machine runs several so the dispatched `BatchWindowExpired` Msg (and its
+ * reconcile identity) routes to the right one.
+ *
+ * @param config the knob (maxMs)
+ * @param state  the current slice
+ * @param id     stable identity for this window's timer (default
+ *               `"batch-window"`)
+ */
+declare function subsFor<I, C extends Cmd>(config: BatchWindowConfig<I, C>, state: BatchWindow<I>, id?: string): readonly BatchWindowSub[];
+/**
+ * The `subscribe["deadline"]` cell for a batch window's timer — the exact
+ * `../deadline` handler. Arms a one-shot timer for `max(0, atMs - now)` and
+ * dispatches `batchWindowExpired(...)`; returns a cleanup that clears it. The
+ * consumer assigns it via the knob's `handlers()`.
+ */
+declare const subscribeBatchWindow: SubscribeHandler<BatchWindowSub, BatchWindowExpired, unknown>;
+/**
+ * Build a batch window knob from a config. Combinator form (the default L2
+ * ergonomic): hand it the config, splice the ~4 returned hooks into your
+ * machine. The pure verbs (`add` / `onWindow`) close over the config so the
+ * consumer's reducer cells stay a uniform `(state, ...args)` shape; `subs` /
+ * `handlers` pre-wire the window timer.
+ *
+ * @typeParam I the item type buffered into each batch
+ * @typeParam C the Cmd type `config.flush` returns
+ */
+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 };

package/dist/batch-window/index.js

@@ -0,0 +1,43 @@
+export { debounce } from '../chunk-EQRUAP2A.js';
+import { subscribeDeadline, deadlineExceeded, deadlineSub } from '../chunk-QGZW4W3E.js';
+import '../chunk-2YFLOCWX.js';
+import '../chunk-2WZHS4P2.js';
+import '../chunk-BNJYE4AU.js';
+
+// src/batch-window/index.ts
+function initBatchWindow() {
+  return { buffer: [], openedAt: null };
+}
+function batchWindowExpired(id, atMs) {
+  return deadlineExceeded(id, atMs);
+}
+function addItem(config, state, item, at) {
+  const buffer = [...state.buffer, item];
+  const openedAt = state.openedAt ?? at;
+  if (buffer.length >= Math.max(1, config.maxItems)) {
+    return [initBatchWindow(), [config.flush(buffer)]];
+  }
+  return [{ buffer, openedAt }, []];
+}
+function onWindow(config, state, _at) {
+  if (state.buffer.length === 0) return [state, []];
+  return [initBatchWindow(), [config.flush(state.buffer)]];
+}
+function subsFor(config, state, id = "batch-window") {
+  if (state.openedAt === null) return [];
+  return [deadlineSub(id, state.openedAt + config.maxMs)];
+}
+var subscribeBatchWindow = subscribeDeadline;
+function createBatchWindow(config) {
+  return {
+    init: () => initBatchWindow(),
+    add: (state, item, at) => addItem(config, state, item, at),
+    onWindow: (state, at) => onWindow(config, state),
+    subs: (state, id) => subsFor(config, state, id),
+    handlers: () => ({ deadline: subscribeBatchWindow })
+  };
+}
+
+export { addItem, batchWindowExpired, createBatchWindow, initBatchWindow, onWindow, subsFor, subscribeBatchWindow };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/batch-window/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/batch-window/index.ts"],"names":[],"mappings":";;;;;;;AA2IO,SAAS,eAAA,GAAqC;AACnD,EAAA,OAAO,EAAE,MAAA,EAAQ,EAAC,EAAG,UAAU,IAAA,EAAK;AACtC;AAqBO,SAAS,kBAAA,CACd,IACA,IAAA,EACoB;AACpB,EAAA,OAAO,gBAAA,CAAiB,IAAI,IAAI,CAAA;AAClC;AAkEO,SAAS,OAAA,CACd,MAAA,EACA,KAAA,EACA,IAAA,EACA,EAAA,EACyC;AACzC,EAAA,MAAM,MAAA,GAAS,CAAC,GAAG,KAAA,CAAM,QAAQ,IAAI,CAAA;AAGrC,EAAA,MAAM,QAAA,GAAW,MAAM,QAAA,IAAY,EAAA;AAInC,EAAA,IAAI,OAAO,MAAA,IAAU,IAAA,CAAK,IAAI,CAAA,EAAG,MAAA,CAAO,QAAQ,CAAA,EAAG;AACjD,IAAA,OAAO,CAAC,iBAAmB,EAAG,CAAC,OAAO,KAAA,CAAM,MAAM,CAAC,CAAC,CAAA;AAAA,EACtD;AAEA,EAAA,OAAO,CAAC,EAAE,MAAA,EAAQ,QAAA,EAAS,EAAG,EAAE,CAAA;AAClC;AAuBO,SAAS,QAAA,CACd,MAAA,EACA,KAAA,EACA,GAAA,EACyC;AAGzC,EAAA,IAAI,KAAA,CAAM,OAAO,MAAA,KAAW,CAAA,SAAU,CAAC,KAAA,EAAO,EAAE,CAAA;AAChD,EAAA,OAAO,CAAC,iBAAmB,EAAG,CAAC,OAAO,KAAA,CAAM,KAAA,CAAM,MAAM,CAAC,CAAC,CAAA;AAC5D;AAqBO,SAAS,OAAA,CACd,MAAA,EACA,KAAA,EACA,EAAA,GAAK,cAAA,EACsB;AAK3B,EAAA,IAAI,KAAA,CAAM,QAAA,KAAa,IAAA,EAAM,OAAO,EAAC;AACrC,EAAA,OAAO,CAAC,WAAA,CAAY,EAAA,EAAI,MAAM,QAAA,GAAW,MAAA,CAAO,KAAK,CAAC,CAAA;AACxD;AAQO,IAAM,oBAAA,GAIT;AAYG,SAAS,kBACd,MAAA,EACuB;AACvB,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,MAAM,eAAA,EAAmB;AAAA,IAC/B,GAAA,EAAK,CAAC,KAAA,EAAO,IAAA,EAAM,OAAO,OAAA,CAAQ,MAAA,EAAQ,KAAA,EAAO,IAAA,EAAM,EAAE,CAAA;AAAA,IACzD,UAAU,CAAC,KAAA,EAAO,OAAO,QAAA,CAAS,MAAA,EAAQ,KAAS,CAAA;AAAA,IACnD,MAAM,CAAC,KAAA,EAAO,OAAO,OAAA,CAAQ,MAAA,EAAQ,OAAO,EAAE,CAAA;AAAA,IAC9C,QAAA,EAAU,OAAO,EAAE,QAAA,EAAU,oBAAA,EAAqB;AAAA,GACpD;AACF","file":"index.js","sourcesContent":["/**\n * @demlik/tea/batch-window — coalesce a stream of items into size- or\n * time-bounded BATCHES, then flush each batch as a single Cmd.\n *\n * What this module actually DELEGATES to, vs. what it merely RE-EXPORTS:\n *\n *   - `../deadline` — REAL delegation (the only one). The window timer IS a\n *     `deadline` Sub: `subsFor` returns `deadlineSub` keyed on the window's\n *     identity, the subscribe cell is `subscribeDeadline` verbatim, and the\n *     expiry Msg is `deadlineExceeded`. Nothing about the timer is redrawn here.\n *     \"Fire at an absolute instant, even across a rehydrate\" is exactly\n *     `deadline`'s absolute-target lifecycle: a late subscribe (post-`Store`\n *     rehydrate) recomputes the remaining delay from the current clock and still\n *     fires at the correct moment.\n *   - `../work-queue` — TYPE re-export only, NOT a sink this module calls. A\n *     flush emits a Cmd; the CONSUMER's interpret handler is what enqueues onto a\n *     `createQueue(store)`. This module never touches queue status — it has no\n *     queue state and no status flip to delegate. It re-exports `EnqueueInput<I>`\n *     purely so the consumer's flush Cmd and queue agree on the item shape; any\n *     actual status flip belongs in the consumer and is delegated to\n *     `../work-queue/ops` there, not here.\n *   - `../debounce` — VALUE/TYPE re-export only, NOT wired into `update`. A\n *     bursty source (keystrokes, scroll, websocket frames) can be `debounce`d at\n *     the host BEFORE it ever becomes an `add` Msg, so the batch window only sees\n *     settled items. `debounce` is a sink transformer OUTSIDE `update`;\n *     batch-window is the durable, replayable half inside it. Re-exported for\n *     one-import ergonomics — this module does not call it.\n *\n * Why this is a knob and not hand-wired logic: the managed state (the buffer +\n * the window-open instant) lives in the Model, so it survives DO eviction /\n * reload (durable) and every transition is still a Msg through `update`\n * (replayable). A closure holding a `setTimeout` and a mutable array would break\n * both — banned. `add` / `onWindow` are PURE: time arrives as an `at`\n * parameter, never `Date.now()`; they return NEW slice values, never mutate.\n *\n * Typical wiring (combinator form):\n *\n *   const bw = createBatchWindow<LogLine, Msg>({\n *     maxItems: 100,\n *     maxMs: 5_000,\n *     flush: (items) => ({ type: \"FlushBatch\", items }),\n *   });\n *\n *   // Model:        { batch: BatchWindow<LogLine>, ... }\n *   // init:         (loaded) => [loaded ?? { batch: bw.init(), ... }, []]\n *   // update cells:\n *   //   LogArrived:   (s, m) => mapBatch(s, bw.add(s.batch, m.line, m.at))\n *   //   WindowFired:  (s, m) => mapBatch(s, bw.onWindow(s.batch, m.atMs))\n *   // subscriptions: (s) => bw.subs(s.batch)\n *   // subscribe:     { ...bw.handlers() }\n *\n * where `mapBatch(s, [batch, cmds]) => [{ ...s, batch }, cmds]` lifts the slice\n * transition into the consumer's Model. The `FlushBatch` Cmd's interpret handler\n * is the consumer's — it is where the batch meets I/O (an `enqueue`, a network\n * POST, an R2 write).\n *\n * NOT exported from the package root — reached via the `@demlik/tea/batch-window`\n * subpath, same one-shape-per-package rule as `deadline`, `cache`, and\n * `work-queue`.\n */\n\nimport type { Cmd } from \"../index\";\n\n// `../debounce` re-export (value + type) for one-import ergonomics — see file\n// header. This module does NOT call debounce; a consumer that wants to debounce\n// a bursty source BEFORE it becomes an `add` Msg reaches it from the same import\n// as the batch window.\nexport { type Debounced, debounce } from \"../debounce\";\n\nimport {\n  type DeadlineExceeded,\n  type DeadlineSub,\n  deadlineExceeded,\n  deadlineSub,\n  subscribeDeadline,\n} from \"../deadline\";\nimport type { SubscribeHandler } from \"../subs/types\";\n\n// `../work-queue` TYPE re-export only (see file header). This module emits a\n// flush Cmd; the CONSUMER's interpret handler enqueues onto a\n// `createQueue(store)`. Re-export the caller-facing enqueue payload type so the\n// consumer's flush Cmd and queue agree on the item shape.\nexport type { EnqueueInput } from \"../work-queue\";\n\n/**\n * Configuration for a batch window — the knob. Pure config, no mutable state\n * (the `BatchWindow<I>` slice carries that). One config object is shared across\n * every window of one logical stream (often a module-scope const).\n *\n * `flush` is a pure Cmd CONSTRUCTOR, not a closure-with-state: it maps the\n * buffered items to the single Cmd the runtime performs when a window closes.\n * Keeping it a `(items) => Cmd` (not a `(items) => void`) is what keeps the\n * trigger replayable — the flush is a Cmd in the transition's output, never a\n * side effect inside the verb.\n */\nexport interface BatchWindowConfig<I, C extends Cmd> {\n  /**\n   * Size trigger. A batch flushes the instant its buffer reaches `maxItems`,\n   * WITHOUT waiting for the time window — the classic \"send as soon as the\n   * page is full\" cutoff. Must be `>= 1`; a config of `maxItems: 0` would flush\n   * an empty batch on every `add`, which is never useful, so callers treat `1`\n   * as the floor (the verb still behaves: with `maxItems <= 1` every item\n   * flushes on arrival, a degenerate but legal \"no batching\" window).\n   */\n  readonly maxItems: number;\n  /**\n   * Time trigger, in milliseconds. A batch flushes no later than `openedAt +\n   * maxMs` — `openedAt` being the `at` of the item that opened the window. This\n   * is the latency ceiling: an item never waits longer than `maxMs` to ship,\n   * even if the buffer never reaches `maxItems`.\n   */\n  readonly maxMs: number;\n  /**\n   * Map a flushed batch to the single Cmd the runtime performs. Called with the\n   * buffered items in arrival order; the returned Cmd is what `add` / `onWindow`\n   * emit when a window closes. PURE constructor — no I/O, no clock; the I/O\n   * happens later in the consumer's interpret handler for the returned Cmd.\n   */\n  readonly flush: (items: readonly I[]) => C;\n}\n\n/**\n * The Model slice a batch window owns. `buffer` is the items accumulated for the\n * current open window; `openedAt` is the `at` of the item that OPENED it (the\n * anchor the time trigger measures against), or `null` when the window is\n * closed (buffer empty). The pair is the single source of truth for \"is a\n * window open, and when must it flush by?\" — both plain data so the whole slice\n * is trivially JSON-serializable into a consumer's `Store<S>`.\n *\n * Invariant the verbs preserve: `buffer.length === 0` IFF `openedAt === null`.\n * A non-empty buffer always has an `openedAt`; an empty buffer never does. The\n * window timer Sub keys its arm/disarm off exactly this invariant.\n */\nexport interface BatchWindow<I> {\n  readonly buffer: readonly I[];\n  readonly openedAt: number | null;\n}\n\n/** The starting slice: closed window, empty buffer. */\nexport function initBatchWindow<I>(): BatchWindow<I> {\n  return { buffer: [], openedAt: null };\n}\n\n/**\n * The Sub a batch window's open timer produces: it IS `../deadline`'s\n * `DeadlineSub`, not a re-tagged copy. `atMs` is the absolute flush-by instant\n * (`openedAt + maxMs`). Aliasing the deadline type (rather than redeclaring an\n * identical shape) is what lets `subsFor` return `deadlineSub(...)` with no\n * cast — the value's static type already satisfies this name. Consumers running\n * several windows route each one by the Sub's `id`, not by a distinct type.\n */\nexport type BatchWindowSub = DeadlineSub;\n\n/** The Msg a closed-by-time window dispatches. Alias of `deadline`'s Msg. */\nexport type BatchWindowExpired = DeadlineExceeded;\n\n/**\n * Construct the window-expired Msg for the window identified by `id`, flushing\n * by `atMs`. Re-exported alias of `deadlineExceeded` so the subscribe cell and\n * the consumer's reducer share one constructor rather than two literals that\n * can drift. The consumer handles it in a reducer cell by calling `onWindow`.\n */\nexport function batchWindowExpired(\n  id: string,\n  atMs: number,\n): BatchWindowExpired {\n  return deadlineExceeded(id, atMs);\n}\n\n/**\n * The bound knob returned by `createBatchWindow`. `init` + the two pure verbs +\n * `subs` + `handlers`, all closing over one `BatchWindowConfig`. The verbs\n * return `readonly [BatchWindow<I>, readonly C[]]`: the next slice and the Cmds\n * to emit (one `flush` Cmd when a window closes, none otherwise).\n */\nexport interface BatchWindowKnob<I, C extends Cmd> {\n  /** The starting slice — `initBatchWindow()`. */\n  init(): BatchWindow<I>;\n  /**\n   * Buffer `item` (arrival-stamped `at`), flushing immediately if that brings\n   * the buffer to `maxItems`. See `addItem`.\n   */\n  add(\n    state: BatchWindow<I>,\n    item: I,\n    at: number,\n  ): readonly [BatchWindow<I>, readonly C[]];\n  /**\n   * Flush whatever is buffered because the time window closed. See `onWindow`.\n   */\n  onWindow(\n    state: BatchWindow<I>,\n    at: number,\n  ): readonly [BatchWindow<I>, readonly C[]];\n  /**\n   * The window timer Sub, armed only while a window is open. See `subsFor`.\n   * `id` keys the deadline so several windows on one machine route distinctly.\n   */\n  subs(state: BatchWindow<I>, id?: string): readonly BatchWindowSub[];\n  /**\n   * The `subscribe` cells this knob splices into `machine.subscribe`. One cell,\n   * keyed `\"deadline\"`, delegating to `../deadline`'s subscribe handler. Spread\n   * into the consumer's subscribe map: `subscribe: { ...bw.handlers() }`.\n   */\n  handlers(): {\n    deadline: SubscribeHandler<BatchWindowSub, BatchWindowExpired, unknown>;\n  };\n}\n\n/**\n * Buffer `item` and decide whether the size trigger fires. PURE.\n *\n * - Empty (closed) window → `item` OPENS it: `openedAt` becomes `at`, buffer\n *   becomes `[item]`. This is the anchor the time window measures against.\n * - Open window → `item` appends; `openedAt` is left untouched (the window's\n *   latency clock keeps running from the FIRST item, not this one).\n *\n * After buffering, if the buffer has reached `maxItems` the window flushes\n * immediately: emit `config.flush(buffer)` and RESET to the closed slice. The\n * size trigger pre-empts the time trigger — a full page ships now, the window\n * Sub for the (now closed) window disarms on the next reconcile because `subs`\n * returns `[]` for an empty buffer.\n *\n * `maxItems <= 1` is the degenerate \"no batching\" case: every item flushes on\n * arrival (buffer reaches 1 immediately). Legal and useful as a feature flag to\n * disable batching without restructuring the wiring.\n *\n * @param config the knob (maxItems / flush constructor)\n * @param state  the current slice\n * @param item   the item to buffer\n * @param at     the arrival instant (epoch ms) — the caller stamps it; the verb\n *               never reads the clock\n */\nexport function addItem<I, C extends Cmd>(\n  config: BatchWindowConfig<I, C>,\n  state: BatchWindow<I>,\n  item: I,\n  at: number,\n): readonly [BatchWindow<I>, readonly C[]] {\n  const buffer = [...state.buffer, item];\n  // A closed window opens at THIS item's `at`; an already-open window keeps its\n  // original `openedAt` (the latency clock runs from the first item).\n  const openedAt = state.openedAt ?? at;\n\n  // Size trigger: a full page ships now, regardless of the time window. The\n  // floor of 1 means `maxItems <= 1` flushes every item on arrival.\n  if (buffer.length >= Math.max(1, config.maxItems)) {\n    return [initBatchWindow<I>(), [config.flush(buffer)]];\n  }\n\n  return [{ buffer, openedAt }, []];\n}\n\n/**\n * Flush the open window because its time bound was reached. PURE.\n *\n * - Open window (buffer non-empty) → emit `config.flush(buffer)` and RESET to\n *   the closed slice.\n * - Closed window (buffer empty) → no-op: return the same slice and no Cmds.\n *   This guards the race where the size trigger already flushed and reset the\n *   window before the time Sub's Msg lands — a stale `onWindow` after a\n *   size-flush must NOT emit an empty batch.\n *\n * `at` is accepted for symmetry with `add` and so the consumer's reducer cell\n * has a uniform `(state, at)` shape; the verb doesn't need it for the flush\n * decision (the buffer's emptiness is the whole signal), but taking it keeps a\n * future \"flush only if the window is genuinely past `openedAt + maxMs`\"\n * tightening a non-breaking change.\n *\n * @param config the knob (flush constructor)\n * @param state  the current slice\n * @param at     the firing instant (epoch ms) — the caller stamps it; the verb\n *               never reads the clock\n */\nexport function onWindow<I, C extends Cmd>(\n  config: BatchWindowConfig<I, C>,\n  state: BatchWindow<I>,\n  _at: number,\n): readonly [BatchWindow<I>, readonly C[]] {\n  // Empty buffer = the size trigger already flushed (or nothing arrived). A\n  // stale timer Msg must not ship an empty batch — return the slice untouched.\n  if (state.buffer.length === 0) return [state, []];\n  return [initBatchWindow<I>(), [config.flush(state.buffer)]];\n}\n\n/**\n * The window timer Sub, derived from the slice. PURE.\n *\n * Returns the single `deadline` Sub targeting `openedAt + maxMs` while a window\n * is open (buffer non-empty), or `[]` while it is closed. The substrate's\n * reconcile pass arms the timer when the array gains the Sub and disarms it\n * (clearing the pending `setTimeout`) when the array loses it — so a size-flush\n * that empties the buffer auto-cancels the now-irrelevant time trigger on the\n * next transition.\n *\n * `id` defaults to `\"batch-window\"`; pass a distinct id per window when a\n * machine runs several so the dispatched `BatchWindowExpired` Msg (and its\n * reconcile identity) routes to the right one.\n *\n * @param config the knob (maxMs)\n * @param state  the current slice\n * @param id     stable identity for this window's timer (default\n *               `\"batch-window\"`)\n */\nexport function subsFor<I, C extends Cmd>(\n  config: BatchWindowConfig<I, C>,\n  state: BatchWindow<I>,\n  id = \"batch-window\",\n): readonly BatchWindowSub[] {\n  // Closed window → no timer. The invariant (empty buffer IFF openedAt null)\n  // means either check suffices; we read `openedAt` so the `atMs` arithmetic\n  // below is non-null without a `!`. `deadlineSub` already returns a\n  // `DeadlineSub`, which IS `BatchWindowSub` — no cast.\n  if (state.openedAt === null) return [];\n  return [deadlineSub(id, state.openedAt + config.maxMs)];\n}\n\n/**\n * The `subscribe[\"deadline\"]` cell for a batch window's timer — the exact\n * `../deadline` handler. Arms a one-shot timer for `max(0, atMs - now)` and\n * dispatches `batchWindowExpired(...)`; returns a cleanup that clears it. The\n * consumer assigns it via the knob's `handlers()`.\n */\nexport const subscribeBatchWindow: SubscribeHandler<\n  BatchWindowSub,\n  BatchWindowExpired,\n  unknown\n> = subscribeDeadline;\n\n/**\n * Build a batch window knob from a config. Combinator form (the default L2\n * ergonomic): hand it the config, splice the ~4 returned hooks into your\n * machine. The pure verbs (`add` / `onWindow`) close over the config so the\n * consumer's reducer cells stay a uniform `(state, ...args)` shape; `subs` /\n * `handlers` pre-wire the window timer.\n *\n * @typeParam I the item type buffered into each batch\n * @typeParam C the Cmd type `config.flush` returns\n */\nexport function createBatchWindow<I, C extends Cmd>(\n  config: BatchWindowConfig<I, C>,\n): BatchWindowKnob<I, C> {\n  return {\n    init: () => initBatchWindow<I>(),\n    add: (state, item, at) => addItem(config, state, item, at),\n    onWindow: (state, at) => onWindow(config, state, at),\n    subs: (state, id) => subsFor(config, state, id),\n    handlers: () => ({ deadline: subscribeBatchWindow }),\n  };\n}\n"]}

package/dist/cache/index.d.ts

@@ -1,5 +1,5 @@
-import { Sub } from '../index.js';
-import { S as SubscribeHandler } from '../types-CwBC5wMn.js';
+import { S as Sub } from '../core-CymXZCeY.js';
+import { S as SubscribeHandler } from '../types-N9LZbdnr.js';
 
 /**
  * @demlik/tea/cache — a TTL cache as pure state, PLUS a periodic eviction Sub.

package/dist/cache/index.js

@@ -1,53 +1,5 @@
-import { fromInterval } from '../chunk-Y5JM3UUH.js';
+export { cacheEvictMsg, cacheEvictionSub, cacheEvictionSubscribe, evictExpired, get, has, initCache, remove, set } from '../chunk-IN33Q4VJ.js';
+import '../chunk-NSDFA6M6.js';
 import '../chunk-2YFLOCWX.js';
-
-// src/cache/index.ts
-function initCache() {
-  return { entries: {} };
-}
-function isExpired(entry, nowMs) {
-  return nowMs >= entry.expiresAtMs;
-}
-function get(cache, key, nowMs) {
-  const entry = cache.entries[key];
-  if (entry === void 0 || isExpired(entry, nowMs)) return void 0;
-  return entry.value;
-}
-function has(cache, key, nowMs) {
-  const entry = cache.entries[key];
-  if (entry === void 0) return false;
-  return !isExpired(entry, nowMs);
-}
-function set(cache, key, value, nowMs, ttlMs) {
-  const nextEntries = { ...cache.entries };
-  nextEntries[key] = { value, expiresAtMs: nowMs + ttlMs };
-  return { ...cache, entries: nextEntries };
-}
-function remove(cache, key) {
-  const nextEntries = { ...cache.entries };
-  delete nextEntries[key];
-  return { ...cache, entries: nextEntries };
-}
-function evictExpired(cache, nowMs) {
-  const nextEntries = {};
-  for (const [key, entry] of Object.entries(cache.entries)) {
-    if (isExpired(entry, nowMs)) continue;
-    nextEntries[key] = entry;
-  }
-  return { ...cache, entries: nextEntries };
-}
-function cacheEvictMsg(id) {
-  return { type: "cache_evict", id };
-}
-function cacheEvictionSub(id, everyMs) {
-  return {
-    id,
-    type: "cache",
-    intervalMs: everyMs
-  };
-}
-var cacheEvictionSubscribe = fromInterval((sub) => cacheEvictMsg(sub.id));
-
-export { cacheEvictMsg, cacheEvictionSub, cacheEvictionSubscribe, evictExpired, get, has, initCache, remove, set };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/cache/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/cache/index.ts"],"names":[],"mappings":";;;;AAuEO,SAAS,SAAA,GAA4B;AAC1C,EAAA,OAAO,EAAE,OAAA,EAAS,EAAC,EAAE;AACvB;AAQA,SAAS,SAAA,CAAa,OAAsB,KAAA,EAAwB;AAClE,EAAA,OAAO,SAAS,KAAA,CAAM,WAAA;AACxB;AAQO,SAAS,GAAA,CACd,KAAA,EACA,GAAA,EACA,KAAA,EACe;AACf,EAAA,MAAM,KAAA,GAAQ,KAAA,CAAM,OAAA,CAAQ,GAAG,CAAA;AAC/B,EAAA,IAAI,UAAU,MAAA,IAAa,SAAA,CAAU,KAAA,EAAO,KAAK,GAAG,OAAO,MAAA;AAC3D,EAAA,OAAO,KAAA,CAAM,KAAA;AACf;AAMO,SAAS,GAAA,CACd,KAAA,EACA,GAAA,EACA,KAAA,EACS;AACT,EAAA,MAAM,KAAA,GAAQ,KAAA,CAAM,OAAA,CAAQ,GAAG,CAAA;AAC/B,EAAA,IAAI,KAAA,KAAU,QAAW,OAAO,KAAA;AAChC,EAAA,OAAO,CAAC,SAAA,CAAU,KAAA,EAAO,KAAK,CAAA;AAChC;AAQO,SAAS,GAAA,CACd,KAAA,EACA,GAAA,EACA,KAAA,EACA,OACA,KAAA,EACa;AACb,EAAA,MAAM,WAAA,GAA6C,EAAE,GAAG,KAAA,CAAM,OAAA,EAAQ;AACtE,EAAA,WAAA,CAAY,GAAG,CAAA,GAAI,EAAE,KAAA,EAAO,WAAA,EAAa,QAAQ,KAAA,EAAM;AACvD,EAAA,OAAO,EAAE,GAAG,KAAA,EAAO,OAAA,EAAS,WAAA,EAAY;AAC1C;AAOO,SAAS,MAAA,CAAU,OAAoB,GAAA,EAA0B;AACtE,EAAA,MAAM,WAAA,GAA6C,EAAE,GAAG,KAAA,CAAM,OAAA,EAAQ;AACtE,EAAA,OAAO,YAAY,GAAG,CAAA;AACtB,EAAA,OAAO,EAAE,GAAG,KAAA,EAAO,OAAA,EAAS,WAAA,EAAY;AAC1C;AASO,SAAS,YAAA,CACd,OACA,KAAA,EACa;AACb,EAAA,MAAM,cAA6C,EAAC;AACpD,EAAA,KAAA,MAAW,CAAC,KAAK,KAAK,CAAA,IAAK,OAAO,OAAA,CAAQ,KAAA,CAAM,OAAO,CAAA,EAAG;AACxD,IAAA,IAAI,SAAA,CAAU,KAAA,EAAO,KAAK,CAAA,EAAG;AAC7B,IAAA,WAAA,CAAY,GAAG,CAAA,GAAI,KAAA;AAAA,EACrB;AACA,EAAA,OAAO,EAAE,GAAG,KAAA,EAAO,OAAA,EAAS,WAAA,EAAY;AAC1C;AAmCO,SAAS,cAAc,EAAA,EAA2B;AACvD,EAAA,OAAO,EAAE,IAAA,EAAM,aAAA,EAAe,EAAA,EAAG;AACnC;AAqBO,SAAS,gBAAA,CACd,IACA,OAAA,EACkB;AAClB,EAAA,OAAO;AAAA,IACL,EAAA;AAAA,IACA,IAAA,EAAM,OAAA;AAAA,IACN,UAAA,EAAY;AAAA,GACd;AACF;AAcO,IAAM,yBAIT,YAAA,CAAa,CAAC,QAAQ,aAAA,CAAc,GAAA,CAAI,EAAE,CAAC","file":"index.js","sourcesContent":["/**\n * @demlik/tea/cache — a TTL cache as pure state, PLUS a periodic eviction Sub.\n *\n * Same pure-state-ops shape as `@demlik/tea/idempotency` and\n * `@demlik/tea/work-queue`: a state type plus pure transition functions. Host-\n * agnostic by construction — no `Date.now()`, no timers, no I/O inside the ops.\n * The caller injects the clock (`nowMs`) and folds the result through its own\n * reducer, keeping the store inside TEA's invariant 2 (transitions are pure:\n * same inputs → same outputs) so a consumer can exercise it with `replay`\n * without a fake clock.\n *\n * Every op returns a NEW cache value and never mutates its input (invariant 1 —\n * state is a value, not a place). `get` / `has` are read-shaped; `set` /\n * `remove` / `evictExpired` return a new cache.\n *\n * **Distinct from `/idempotency`.** Both are TTL-bounded key maps, but they\n * answer different questions and so carry different shapes:\n *\n *   - `/idempotency` is DEDUPE-focused — \"have I already processed this key?\"\n *     TTL is a single store-level policy (`ttlMs`), each entry stores the\n *     `atMs` it was remembered at, and expiry is derived (`now - atMs >=\n *     ttlMs`). It carries an `order` ledger + `capacity` because the use case\n *     (webhook receivers, retried messages) needs bounded LRU eviction.\n *   - `/cache` is RETRIEVAL-focused — \"what is the value for this key right\n *     now?\" TTL is set PER ENTRY at write time: `set(key, value, nowMs,\n *     ttlMs)` bakes the absolute `expiresAtMs = nowMs + ttlMs` into the entry.\n *     Different keys can carry different lifetimes (a hot key cached for 1s, a\n *     cold one for 1h) — the dimension idempotency's single store-level\n *     `ttlMs` cannot express. No `order`, no `capacity`: a cache bounds itself\n *     by TTL + periodic eviction, not by LRU count.\n *\n * The eviction Sub is the \"eviction is a Msg\" half: a `setInterval`-shaped Sub\n * (composed directly on `@demlik/tea/subs`' `fromInterval`) that periodically\n * dispatches a `cache_evict` Msg the consumer's reducer handles by calling\n * `evictExpired`. Time still never enters the reducer — the Sub fires the Msg,\n * the reducer reads `nowMs` off the Msg (the consumer stamps it at the Sub\n * boundary), and `evictExpired` does the pure drop.\n *\n * NOT exported from the package root — reached via the `@demlik/tea/cache`\n * subpath, same one-shape-per-package rule as `work-queue`, `idempotency`, and\n * `rate-limit`.\n */\n\nimport type { Sub } from \"../index\";\nimport { fromInterval } from \"../subs\";\nimport type { SubscribeHandler } from \"../subs/types\";\n\n/**\n * A cached entry: the `value` and the absolute clock reading `expiresAtMs` it\n * expires at. Unlike `/idempotency`'s entry (which stores `atMs` and derives\n * expiry from a store-level `ttlMs`), the expiry instant is baked in at write\n * time — so per-entry TTLs are a first-class capability. Both fields are plain\n * data so the whole cache is trivially JSON-serializable into a consumer's\n * `Store<S>`.\n */\nexport interface CacheEntry<V> {\n  readonly value: V;\n  readonly expiresAtMs: number;\n}\n\n/**\n * The cache: a map of `key → entry`. No `order` ledger and no `capacity` (cf.\n * `/idempotency`) — a TTL cache bounds itself by expiry + periodic eviction,\n * not by LRU count. Each entry carries its own `expiresAtMs`, so the cache\n * needs no store-level TTL policy field.\n */\nexport interface TtlCache<V> {\n  readonly entries: Readonly<Record<string, CacheEntry<V>>>;\n}\n\n/** Create an empty cache. */\nexport function initCache<V>(): TtlCache<V> {\n  return { entries: {} };\n}\n\n/**\n * Whether `entry` is expired at `nowMs`. Half-open: an entry whose\n * `expiresAtMs` exactly equals `nowMs` is expired (`nowMs >= expiresAtMs`),\n * matching `/idempotency` and `/rate-limit`'s window-edge cutoff — a value\n * cached at `t` with a `ttlMs` lifetime is gone at exactly `t + ttlMs`.\n */\nfunction isExpired<V>(entry: CacheEntry<V>, nowMs: number): boolean {\n  return nowMs >= entry.expiresAtMs;\n}\n\n/**\n * The cached `value` for `key` iff present AND unexpired at `nowMs`, else\n * `undefined`. An expired entry reads as absent even though it is physically\n * still in `entries` until the next `evictExpired` (or an overwriting `set`)\n * drops it. PURE — reads only, never mutates.\n */\nexport function get<V>(\n  cache: TtlCache<V>,\n  key: string,\n  nowMs: number,\n): V | undefined {\n  const entry = cache.entries[key];\n  if (entry === undefined || isExpired(entry, nowMs)) return undefined;\n  return entry.value;\n}\n\n/**\n * True iff `key` is present AND unexpired at `nowMs`. The boolean sibling of\n * `get` for callers that only need presence, not the value. PURE.\n */\nexport function has<V>(\n  cache: TtlCache<V>,\n  key: string,\n  nowMs: number,\n): boolean {\n  const entry = cache.entries[key];\n  if (entry === undefined) return false;\n  return !isExpired(entry, nowMs);\n}\n\n/**\n * Write `key → value` with an absolute expiry of `nowMs + ttlMs`. Re-`set`ting\n * an existing key overwrites both the value and the expiry — the TTL clock\n * restarts from the new `nowMs`. PURE — returns a new cache; the input is\n * untouched (a fresh shallow copy of `entries`).\n */\nexport function set<V>(\n  cache: TtlCache<V>,\n  key: string,\n  value: V,\n  nowMs: number,\n  ttlMs: number,\n): TtlCache<V> {\n  const nextEntries: Record<string, CacheEntry<V>> = { ...cache.entries };\n  nextEntries[key] = { value, expiresAtMs: nowMs + ttlMs };\n  return { ...cache, entries: nextEntries };\n}\n\n/**\n * Drop `key` regardless of expiry. PURE — returns a new cache; the input is\n * untouched. Removing an absent key returns an equivalent cache (the shallow\n * copy still happens, but no entry is dropped).\n */\nexport function remove<V>(cache: TtlCache<V>, key: string): TtlCache<V> {\n  const nextEntries: Record<string, CacheEntry<V>> = { ...cache.entries };\n  delete nextEntries[key];\n  return { ...cache, entries: nextEntries };\n}\n\n/**\n * Physically drop every entry expired at `nowMs` (`nowMs >= expiresAtMs`).\n * Returns a NEW cache with the survivors. This is the pure work the eviction\n * Sub's `cache_evict` Msg triggers — `get` / `has` already treat expired\n * entries as absent, so eviction is purely a memory-reclaim pass, not a\n * correctness one. PURE — the input cache is never mutated.\n */\nexport function evictExpired<V>(\n  cache: TtlCache<V>,\n  nowMs: number,\n): TtlCache<V> {\n  const nextEntries: Record<string, CacheEntry<V>> = {};\n  for (const [key, entry] of Object.entries(cache.entries)) {\n    if (isExpired(entry, nowMs)) continue;\n    nextEntries[key] = entry;\n  }\n  return { ...cache, entries: nextEntries };\n}\n\n// ---------------------------------------------------------------------------\n// Eviction Sub — \"eviction is a Msg\".\n//\n// A periodic timer Sub that dispatches `cache_evict` so the consumer's reducer\n// can call `evictExpired`. It is `fromInterval` specialized to a fixed Msg\n// shape — the factory carries the interval ON the Sub (per the substrate's\n// reconcile-by-id contract) and dispatches a `cache_evict` Msg tagged with the\n// Sub's own `id`, so a consumer running several caches can route each tick to\n// the right cache by `msg.id`.\n//\n// Mirrors `fromInterval` exactly (factory + SubscribeHandler cell + exported\n// Msg constructor); it does NOT reimplement the timer lifecycle — it composes\n// directly on `fromInterval`, which owns `setInterval` / `clearInterval`. That\n// keeps the timer-handle bookkeeping (and its cleanup) in one place and this\n// module purely declarative.\n//\n// Strengthens invariant 4 (external time is a Sub, reconciled by id) and\n// invariant 9 (named, small Sub surface composed on the shared factory).\n// ---------------------------------------------------------------------------\n\n/**\n * The Msg the eviction Sub dispatches each tick. `id` is the Sub's own id so a\n * consumer with multiple caches can route the tick to the matching cache. The\n * reducer reads `Date.now()`-free time by stamping `nowMs` itself at the Sub\n * boundary if needed; the canonical reducer cell is\n * `cache_evict: (s) => [{ ...s, cache: evictExpired(s.cache, nowMs) }, []]`.\n */\nexport interface CacheEvictMsg {\n  readonly type: \"cache_evict\";\n  readonly id: string;\n}\n\n/** Construct a `cache_evict` Msg for the cache identified by `id`. */\nexport function cacheEvictMsg(id: string): CacheEvictMsg {\n  return { type: \"cache_evict\", id };\n}\n\n/**\n * The Sub shape the eviction factory installs: a `setInterval`-shaped Sub\n * carrying its tick period (`intervalMs`) per the substrate's\n * reconcile-by-id-with-data-on-the-Sub contract. `type: \"cache\"` is the\n * lowercase source-noun Sub convention (canon §2.5 / naming-style).\n */\nexport type CacheEvictionSub = Sub<\"cache\"> & { readonly intervalMs: number };\n\n/**\n * Declare an eviction Sub for the cache identified by `id`, ticking every\n * `everyMs`. Drop the result into `subscriptions(state)`:\n *\n *   subscriptions: (s) => [cacheEvictionSub(\"session-cache\", 30_000)]\n *\n * Same id ⇒ same running interval across transitions (no reconcile churn);\n * changing `everyMs` alone will NOT re-arm the timer (the substrate leaves a\n * same-id Sub running) — change the `id` too if the period must change. This\n * mirrors `fromInterval`'s data-on-the-Sub tradeoff exactly.\n */\nexport function cacheEvictionSub(\n  id: string,\n  everyMs: number,\n): CacheEvictionSub {\n  return {\n    id: id as CacheEvictionSub[\"id\"],\n    type: \"cache\",\n    intervalMs: everyMs,\n  };\n}\n\n/**\n * The `subscribe` cell for the eviction Sub. Assign it to\n * `machine.subscribe.cache`:\n *\n *   subscribe: { cache: cacheEvictionSubscribe }\n *\n * Composed directly on `fromInterval` — it owns the `setInterval` /\n * `clearInterval` lifecycle; this cell only pins the Msg the tick dispatches\n * (`cacheEvictMsg(sub.id)`). The cleanup `fromInterval` returns stops the\n * interval when the Sub is reconciled out (the cache's state exits the phase\n * that declared it).\n */\nexport const cacheEvictionSubscribe: SubscribeHandler<\n  CacheEvictionSub,\n  CacheEvictMsg,\n  unknown\n> = fromInterval((sub) => cacheEvictMsg(sub.id));\n"]}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}