@demlik/tea 0.1.0

package/dist/cache/index.d.ts

@@ -0,0 +1,151 @@
+import { Sub } from '../index.js';
+import { S as SubscribeHandler } from '../types-CwBC5wMn.js';
+
+/**
+ * @demlik/tea/cache — a TTL cache as pure state, PLUS a periodic eviction Sub.
+ *
+ * Same pure-state-ops shape as `@demlik/tea/idempotency` and
+ * `@demlik/tea/work-queue`: a state type plus pure transition functions. Host-
+ * agnostic by construction — no `Date.now()`, no timers, no I/O inside the ops.
+ * The caller injects the clock (`nowMs`) and folds the result through its own
+ * reducer, keeping the store inside TEA's invariant 2 (transitions are pure:
+ * same inputs → same outputs) so a consumer can exercise it with `replay`
+ * without a fake clock.
+ *
+ * Every op returns a NEW cache value and never mutates its input (invariant 1 —
+ * state is a value, not a place). `get` / `has` are read-shaped; `set` /
+ * `remove` / `evictExpired` return a new cache.
+ *
+ * **Distinct from `/idempotency`.** Both are TTL-bounded key maps, but they
+ * answer different questions and so carry different shapes:
+ *
+ *   - `/idempotency` is DEDUPE-focused — "have I already processed this key?"
+ *     TTL is a single store-level policy (`ttlMs`), each entry stores the
+ *     `atMs` it was remembered at, and expiry is derived (`now - atMs >=
+ *     ttlMs`). It carries an `order` ledger + `capacity` because the use case
+ *     (webhook receivers, retried messages) needs bounded LRU eviction.
+ *   - `/cache` is RETRIEVAL-focused — "what is the value for this key right
+ *     now?" TTL is set PER ENTRY at write time: `set(key, value, nowMs,
+ *     ttlMs)` bakes the absolute `expiresAtMs = nowMs + ttlMs` into the entry.
+ *     Different keys can carry different lifetimes (a hot key cached for 1s, a
+ *     cold one for 1h) — the dimension idempotency's single store-level
+ *     `ttlMs` cannot express. No `order`, no `capacity`: a cache bounds itself
+ *     by TTL + periodic eviction, not by LRU count.
+ *
+ * The eviction Sub is the "eviction is a Msg" half: a `setInterval`-shaped Sub
+ * (composed directly on `@demlik/tea/subs`' `fromInterval`) that periodically
+ * dispatches a `cache_evict` Msg the consumer's reducer handles by calling
+ * `evictExpired`. Time still never enters the reducer — the Sub fires the Msg,
+ * the reducer reads `nowMs` off the Msg (the consumer stamps it at the Sub
+ * boundary), and `evictExpired` does the pure drop.
+ *
+ * NOT exported from the package root — reached via the `@demlik/tea/cache`
+ * subpath, same one-shape-per-package rule as `work-queue`, `idempotency`, and
+ * `rate-limit`.
+ */
+
+/**
+ * A cached entry: the `value` and the absolute clock reading `expiresAtMs` it
+ * expires at. Unlike `/idempotency`'s entry (which stores `atMs` and derives
+ * expiry from a store-level `ttlMs`), the expiry instant is baked in at write
+ * time — so per-entry TTLs are a first-class capability. Both fields are plain
+ * data so the whole cache is trivially JSON-serializable into a consumer's
+ * `Store<S>`.
+ */
+interface CacheEntry<V> {
+    readonly value: V;
+    readonly expiresAtMs: number;
+}
+/**
+ * The cache: a map of `key → entry`. No `order` ledger and no `capacity` (cf.
+ * `/idempotency`) — a TTL cache bounds itself by expiry + periodic eviction,
+ * not by LRU count. Each entry carries its own `expiresAtMs`, so the cache
+ * needs no store-level TTL policy field.
+ */
+interface TtlCache<V> {
+    readonly entries: Readonly<Record<string, CacheEntry<V>>>;
+}
+/** Create an empty cache. */
+declare function initCache<V>(): TtlCache<V>;
+/**
+ * The cached `value` for `key` iff present AND unexpired at `nowMs`, else
+ * `undefined`. An expired entry reads as absent even though it is physically
+ * still in `entries` until the next `evictExpired` (or an overwriting `set`)
+ * drops it. PURE — reads only, never mutates.
+ */
+declare function get<V>(cache: TtlCache<V>, key: string, nowMs: number): V | undefined;
+/**
+ * True iff `key` is present AND unexpired at `nowMs`. The boolean sibling of
+ * `get` for callers that only need presence, not the value. PURE.
+ */
+declare function has<V>(cache: TtlCache<V>, key: string, nowMs: number): boolean;
+/**
+ * Write `key → value` with an absolute expiry of `nowMs + ttlMs`. Re-`set`ting
+ * an existing key overwrites both the value and the expiry — the TTL clock
+ * restarts from the new `nowMs`. PURE — returns a new cache; the input is
+ * untouched (a fresh shallow copy of `entries`).
+ */
+declare function set<V>(cache: TtlCache<V>, key: string, value: V, nowMs: number, ttlMs: number): TtlCache<V>;
+/**
+ * Drop `key` regardless of expiry. PURE — returns a new cache; the input is
+ * untouched. Removing an absent key returns an equivalent cache (the shallow
+ * copy still happens, but no entry is dropped).
+ */
+declare function remove<V>(cache: TtlCache<V>, key: string): TtlCache<V>;
+/**
+ * Physically drop every entry expired at `nowMs` (`nowMs >= expiresAtMs`).
+ * Returns a NEW cache with the survivors. This is the pure work the eviction
+ * Sub's `cache_evict` Msg triggers — `get` / `has` already treat expired
+ * entries as absent, so eviction is purely a memory-reclaim pass, not a
+ * correctness one. PURE — the input cache is never mutated.
+ */
+declare function evictExpired<V>(cache: TtlCache<V>, nowMs: number): TtlCache<V>;
+/**
+ * The Msg the eviction Sub dispatches each tick. `id` is the Sub's own id so a
+ * consumer with multiple caches can route the tick to the matching cache. The
+ * reducer reads `Date.now()`-free time by stamping `nowMs` itself at the Sub
+ * boundary if needed; the canonical reducer cell is
+ * `cache_evict: (s) => [{ ...s, cache: evictExpired(s.cache, nowMs) }, []]`.
+ */
+interface CacheEvictMsg {
+    readonly type: "cache_evict";
+    readonly id: string;
+}
+/** Construct a `cache_evict` Msg for the cache identified by `id`. */
+declare function cacheEvictMsg(id: string): CacheEvictMsg;
+/**
+ * The Sub shape the eviction factory installs: a `setInterval`-shaped Sub
+ * carrying its tick period (`intervalMs`) per the substrate's
+ * reconcile-by-id-with-data-on-the-Sub contract. `type: "cache"` is the
+ * lowercase source-noun Sub convention (canon §2.5 / naming-style).
+ */
+type CacheEvictionSub = Sub<"cache"> & {
+    readonly intervalMs: number;
+};
+/**
+ * Declare an eviction Sub for the cache identified by `id`, ticking every
+ * `everyMs`. Drop the result into `subscriptions(state)`:
+ *
+ *   subscriptions: (s) => [cacheEvictionSub("session-cache", 30_000)]
+ *
+ * Same id ⇒ same running interval across transitions (no reconcile churn);
+ * changing `everyMs` alone will NOT re-arm the timer (the substrate leaves a
+ * same-id Sub running) — change the `id` too if the period must change. This
+ * mirrors `fromInterval`'s data-on-the-Sub tradeoff exactly.
+ */
+declare function cacheEvictionSub(id: string, everyMs: number): CacheEvictionSub;
+/**
+ * The `subscribe` cell for the eviction Sub. Assign it to
+ * `machine.subscribe.cache`:
+ *
+ *   subscribe: { cache: cacheEvictionSubscribe }
+ *
+ * Composed directly on `fromInterval` — it owns the `setInterval` /
+ * `clearInterval` lifecycle; this cell only pins the Msg the tick dispatches
+ * (`cacheEvictMsg(sub.id)`). The cleanup `fromInterval` returns stops the
+ * interval when the Sub is reconciled out (the cache's state exits the phase
+ * that declared it).
+ */
+declare const cacheEvictionSubscribe: SubscribeHandler<CacheEvictionSub, CacheEvictMsg, unknown>;
+
+export { type CacheEntry, type CacheEvictMsg, type CacheEvictionSub, type TtlCache, cacheEvictMsg, cacheEvictionSub, cacheEvictionSubscribe, evictExpired, get, has, initCache, remove, set };

package/dist/cache/index.js

@@ -0,0 +1,53 @@
+import { fromInterval } from '../chunk-Y5JM3UUH.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

@@ -0,0 +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"]}

package/dist/chunk-2YFLOCWX.js

@@ -0,0 +1,15 @@
+// src/subs/from-timeout.ts
+function fromTimeout(msgFn) {
+  return (sub, _ctx, dispatch) => {
+    const handle = setTimeout(() => {
+      dispatch(msgFn(sub));
+    }, sub.delayMs);
+    return () => {
+      clearTimeout(handle);
+    };
+  };
+}
+
+export { fromTimeout };
+//# sourceMappingURL=chunk-2YFLOCWX.js.map
+//# sourceMappingURL=chunk-2YFLOCWX.js.map

package/dist/chunk-2YFLOCWX.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/subs/from-timeout.ts"],"names":[],"mappings":";AAgCO,SAAS,YACd,KAAA,EACiC;AACjC,EAAA,OAAO,CAAC,GAAA,EAAK,IAAA,EAAM,QAAA,KAAa;AAC9B,IAAA,MAAM,MAAA,GAAS,WAAW,MAAM;AAC9B,MAAA,QAAA,CAAS,KAAA,CAAM,GAAG,CAAC,CAAA;AAAA,IACrB,CAAA,EAAG,IAAI,OAAO,CAAA;AACd,IAAA,OAAO,MAAM;AACX,MAAA,YAAA,CAAa,MAAM,CAAA;AAAA,IACrB,CAAA;AAAA,EACF,CAAA;AACF","file":"chunk-2YFLOCWX.js","sourcesContent":["// ---------------------------------------------------------------------------\n// fromTimeout — universal `setTimeout`-shaped Sub factory.\n//\n// Same lifecycle shape as `fromInterval` minus the recurrence: the\n// scheduled callback fires once, the cleanup is `clearTimeout`. Two\n// observable consequences worth pinning explicitly:\n//\n//   1. The Sub stays in the desired set until the caller removes it from\n//      `subscriptions(state)`. The substrate's reconcile pass does NOT\n//      auto-remove a Sub on cleanup — the timer fires, the callback\n//      dispatches its Msg, and if the Sub is still present on the next\n//      transition's desired set, the factory will... NOT re-fire. The\n//      timer handle is captured per-subscribe call; after it fires, the\n//      handle is exhausted. Adding the same Sub a second time (via a new\n//      id) is the only way to re-arm.\n//\n//   2. Cleanup before the timer fires cancels the pending dispatch. This\n//      is the \"cancel on state exit\" pattern: model the timeout as a Sub\n//      whose `subscriptions(state)` returns it only in the state where the\n//      timeout should be armed. When the state changes, the substrate's\n//      reconcile drops the Sub and the factory's cleanup fires before the\n//      timer does.\n//\n// Like `fromInterval`, the delay lives on the Sub (`delayMs`) — same id\n// means same scheduled timeout; changing the delay requires a new id.\n// ---------------------------------------------------------------------------\n\nimport type { Sub } from \"../index\";\nimport type { SubscribeHandler } from \"./types\";\n\ntype TimeoutSubData = { delayMs: number };\n\nexport function fromTimeout<S extends Sub & TimeoutSubData, M>(\n  msgFn: (sub: S) => M,\n): SubscribeHandler<S, M, unknown> {\n  return (sub, _ctx, dispatch) => {\n    const handle = setTimeout(() => {\n      dispatch(msgFn(sub));\n    }, sub.delayMs);\n    return () => {\n      clearTimeout(handle);\n    };\n  };\n}\n"]}