@demlik/tea 0.13.0 → 0.14.0

package/dist/{deadline/index.d.ts → index-q0hXFeZ0.d.ts}

@@ -1,9 +1,155 @@
-import { S as Sub, b as SubId } from '../core-Co0LWkIA.js';
-import { S as SubscribeHandler } from '../types-XS_miRnB.js';
-import 'zod';
+import { S as Sub, c as SubId } from './core-CTzMJ82M.js';
+import { S as SubscribeHandler } from './types-DP3f5NIl.js';
 
 /**
- * @demlik/tea/deadline — a one-shot Sub that fires when an ABSOLUTE wall-clock
+ * internal/resilience/cache — a TTL cache as pure state, PLUS a periodic eviction Sub.
+ *
+ * Same pure-state-ops shape as `../../idempotency/` and
+ * `../../work-queue/ops.ts`: 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 `fromInterval`, from `src/subs/`) 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.
+ *
+ * Internal to the package (`src/internal/resilience/`), not a published
+ * subpath (#46); same one-shape-per-module 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>;
+
+/**
+ * internal/resilience/deadline — a one-shot Sub that fires when an ABSOLUTE wall-clock
  * deadline is reached.
  *
  * Generalizes the recurring "auto-fail a machine at T+N" / "15-minute stale
@@ -24,7 +170,7 @@ import 'zod';
  *
  * Composition over reinvention: the timer lifecycle is `fromTimeout`'s, not
  * redrawn here. `deadlineSub` produces the Sub literal carrying `atMs`; the
- * `subscribe` cell (`subscribeDeadline`) translates `atMs` → a relative delay
+ * `subscribe` handler (`subscribeDeadline`) translates `atMs` → a relative delay
  * and delegates the `setTimeout` / `clearTimeout` to `fromTimeout`. The clock
  * read (`Date.now()`) lives only in the subscribe handler — never in a reducer
  * (invariant 2) — and is exercised in tests via vitest fake timers, matching
@@ -35,7 +181,7 @@ import 'zod';
  * live `setTimeout` to wake it, so its deadline must be backed by a `do_alarm`
  * registered on the alarm registry; a test host wants a fake-timer schedule.
  * That backing is the `ArmTimer` seam — `subscribeWith(armTimer)` builds the
- * `subscribe.deadline` cell from a host-plugged timer, and `subscribeDeadline`
+ * `subscribe.deadline` handler from a host-plugged timer, and `subscribeDeadline`
  * IS `subscribeWith(setTimeoutArmTimer())`. One deadline surface, three hosts;
  * there is no second Sub type and no second `atMs` anchor to keep in sync.
  *
@@ -173,7 +319,7 @@ declare function subscribeWith(armTimer: ArmTimer<DeadlineExceeded>): SubscribeH
  */
 declare function setTimeoutArmTimer(): ArmTimer<DeadlineExceeded>;
 /**
- * The `subscribe["deadline"]` cell for the DEFAULT `setTimeout` backing. Arms a
+ * The `subscribe["deadline"]` handler for the DEFAULT `setTimeout` backing. Arms a
  * one-shot timer for the remaining delay `max(0, atMs - Date.now())` and
  * dispatches `deadlineExceeded(...)` when it fires; returns a cleanup that
  * clears the pending timer.
@@ -182,7 +328,7 @@ declare function setTimeoutArmTimer(): ArmTimer<DeadlineExceeded>;
  * a separate implementation, so the host-plugged path and the default path can
  * never disagree about the anchor.
  *
- * Assign directly to a `Subscribe` cell:
+ * Assign directly to a `Subscribe` handler:
  *
  *   subscribe: {
  *     deadline: subscribeDeadline,
@@ -196,4 +342,4 @@ declare const subscribeDeadline: SubscribeHandler<DeadlineSub, DeadlineExceeded,
  */
 declare function deadlineExceeded(id: string, atMs: number): DeadlineExceeded;
 
-export { type ArmTimer, type DeadlineExceeded, type DeadlineOpts, type DeadlineSub, deadlineExceeded, deadlineSub, setTimeoutArmTimer, subscribeDeadline, subscribeWith };
+export { type ArmTimer as A, type CacheEvictionSub as C, type DeadlineExceeded as D, type TtlCache as T, type DeadlineSub as a, deadlineSub as b, type CacheEvictMsg as c, deadlineExceeded as d, type CacheEntry as e, type DeadlineOpts as f, cacheEvictMsg as g, cacheEvictionSub as h, cacheEvictionSubscribe as i, evictExpired as j, get as k, has as l, initCache as m, set as n, setTimeoutArmTimer as o, subscribeWith as p, remove as r, subscribeDeadline as s };