@demlik/tea 0.1.0 → 0.1.1

package/dist/{chunk-CMG2KMWX.js → chunk-2WZHS4P2.js}

@@ -1,126 +1,10 @@
+import { detectUpdateForm, formOf, foldUpdates, __DEV__, deepFreeze, assertPureResult } from './chunk-BNJYE4AU.js';
 import { Result } from 'better-result';
 
-// src/index.ts
-var __DEV__ = (() => {
-  try {
-    const meta = import.meta;
-    if (meta.env?.DEV !== void 0) {
-      return meta.env.DEV;
-    }
-  } catch {
-  }
-  try {
-    return typeof process !== "undefined" && process.env?.NODE_ENV !== "production";
-  } catch {
-    return false;
-  }
-})();
-function deepFreeze(obj, seen) {
-  if (obj === null || typeof obj !== "object") return obj;
-  const proto = Object.getPrototypeOf(obj);
-  if (proto !== Object.prototype && proto !== Array.prototype && proto !== null) return obj;
-  const visited = seen ?? /* @__PURE__ */ new WeakSet();
-  if (visited.has(obj)) return obj;
-  visited.add(obj);
-  Object.freeze(obj);
-  for (const v of Object.values(obj)) deepFreeze(v, visited);
-  return obj;
-}
-function hasFunctionValues(obj) {
-  if (obj === null || typeof obj !== "object") return null;
-  for (const [key, value] of Object.entries(obj)) {
-    if (typeof value === "function") return key;
-  }
-  return null;
-}
-function assertPureResult(result, msgType) {
-  if (result && typeof result.then === "function") {
-    throw new Error(
-      `@demlik/tea: update cell "${msgType}" returned a Promise. update must be synchronous. Move async work to interpret.`
-    );
-  }
-  if (!Array.isArray(result) || result.length < 2 || !Array.isArray(result[1])) {
-    throw new Error(
-      `@demlik/tea: update cell "${msgType}" returned a non-tuple. Expected [State, Cmd[]], got ${typeof result}.`
-    );
-  }
-  const cmds = result[1];
-  for (const cmd of cmds) {
-    const fnField = hasFunctionValues(cmd);
-    if (fnField !== null) {
-      throw new Error(
-        `@demlik/tea: Cmd "${cmd.type}" has function field "${fnField}". Cmds must be plain data, not closures.`
-      );
-    }
-  }
-}
 function absurd(x) {
   throw new Error(`unreachable: ${JSON.stringify(x)}`);
 }
-var noop = (state, _msg) => [
-  state,
-  []
-];
-var Cmd = {
-  /**
-   * The empty Cmd array. Typed `readonly never[]` so it's assignable to any
-   * `readonly C[]` for any `C extends Cmd`. Use in `init` returns and
-   * Transitions cells that emit zero effects:
-   *
-   *   init: (loaded) => [loaded ?? initial, Cmd.none],
-   *   tick: (state) => [state, Cmd.none],
-   *
-   * Elm's `Cmd.none` analogue. Cultural signal alongside the runtime help:
-   * `[state, Cmd.none]` reads as intent ("this transition emits nothing"),
-   * `[state, []]` reads as "empty array of what".
-   *
-   * Frozen at runtime so a downstream consumer can't `.push()` into the
-   * shared reference.
-   */
-  none: Object.freeze([]),
-  /**
-   * Flat concat of cmd arrays. Use when a cell composes effects from
-   * multiple conditional sources:
-   *
-   *   return [next, Cmd.batch(
-   *     Cmd.whenDefined(state.queueItemId, (id) => ({ type: "complete", id })),
-   *     Cmd.when(state.windowId !== undefined, { type: "close_window", windowId }),
-   *     [{ type: "detach_debugger", tabId: state.tabId }],
-   *   )];
-   *
-   * `<const C>` keeps inline cmd literals' discriminants narrow (same
-   * rationale as `when` / `whenDefined` above).
-   */
-  batch: (...arrs) => {
-    const out = [];
-    for (const arr of arrs) out.push(...arr);
-    return out;
-  },
-  /**
-   * Emit `cmd` wrapped in a single-element array iff `cond` is true.
-   * Otherwise return the empty array. Spreads cleanly into the cmds array
-   * returned by a Transitions cell.
-   *
-   * `const C` (TypeScript 5.0+) keeps the inferred `type:` discriminator
-   * literal narrow when called with an object literal — so `Cmd.when(b,
-   * { type: "x", ... })` infers as `{ type: "x", ... }`, not `{ type:
-   * string, ... }`, and stays assignable to a discriminated-union arm
-   * without `as const` at the call site.
-   */
-  when: (cond, cmd) => cond ? [cmd] : [],
-  /**
-   * If `value` is defined, call `build(value)` and emit the resulting cmd
-   * wrapped in a single-element array. If `value` is `undefined`, return
-   * the empty array. `value` is narrowed to `T` inside `build`.
-   *
-   * `const C` on the return type keeps the callback's object-literal
-   * `type:` field narrow (see `when` above for the full rationale).
-   */
-  whenDefined: (value, build) => value !== void 0 ? [build(value)] : []
-};
-function subId(s) {
-  return s;
-}
+var noop = (state, _msg) => [state, []];
 var definedPortNames = /* @__PURE__ */ new Set();
 var PortNameCollisionError = class extends Error {
   name = "PortNameCollisionError";
@@ -133,6 +17,25 @@ var PortNameCollisionError = class extends Error {
 function __resetPortRegistry() {
   definedPortNames.clear();
 }
+function defaultOnError(error, _context) {
+  setTimeout(() => {
+    throw error;
+  }, 0);
+}
+function normalizeSupervision(supervision) {
+  if (supervision === void 0) return { strategy: "stop" };
+  if (typeof supervision === "string") return { strategy: supervision };
+  return supervision;
+}
+var QuiescenceTimeoutError = class extends Error {
+  constructor(iterations) {
+    super(
+      `@demlik/tea: idle() did not reach quiescence after ${iterations} iterations \u2014 the dispatch tail kept advancing. The machine is likely livelocking (an interpret handler enqueues a follow-up Msg that enqueues another, without end). Bound the follow-up chain in the reducer, or stop the runtime.`
+    );
+    this.iterations = iterations;
+  }
+  name = "QuiescenceTimeoutError";
+};
 function definePort(name) {
   let isHmr = false;
   try {
@@ -148,16 +51,44 @@ function definePort(name) {
   return { __brand: "port", name };
 }
 function defineMachine(m) {
+  if (m.__form === void 0) {
+    Object.defineProperty(m, "__form", {
+      value: detectUpdateForm(m.update),
+      enumerable: false,
+      writable: false,
+      configurable: true
+    });
+  }
   return m;
 }
+function asReducer(reducer) {
+  return reducer;
+}
 function run(machine, opts) {
-  const { ctx, store } = opts;
+  const { store } = opts;
+  const ctx = opts.ctx ?? {};
+  const idleCap = opts.__idleCap ?? 1e5;
+  const projectEvents = opts.events ?? (() => []);
+  const isTerminal = opts.terminal ?? (() => false);
+  const onError = opts.onError ?? defaultOnError;
+  const reportError = (error, context) => {
+    try {
+      onError(error, context);
+    } catch (sinkError) {
+      defaultOnError(sinkError);
+    }
+  };
+  const supervision = normalizeSupervision(opts.supervision);
   let state;
   let bootError = null;
   let stopped = false;
   const subRegistry = /* @__PURE__ */ new Map();
   const listeners = /* @__PURE__ */ new Set();
   const observers = /* @__PURE__ */ new Set();
+  const bootHandlers = /* @__PURE__ */ new Set();
+  let booted = false;
+  const eventHandlers = /* @__PURE__ */ new Map();
+  const doneWaiters = /* @__PURE__ */ new Set();
   const portRegistry = /* @__PURE__ */ new Map();
   function portEmit(port, value) {
     const subscribers = portRegistry.get(port);
@@ -172,14 +103,7 @@ function run(machine, opts) {
   }
   const augmentedCtx = { ...ctx, emit: portEmit };
   const updateForm = machine.update;
-  const updateMode = (() => {
-    const firstKey = Object.keys(updateForm)[0];
-    if (firstKey === void 0) {
-      return "reducer";
-    }
-    const firstValue = updateForm[firstKey];
-    return typeof firstValue === "function" ? "reducer" : "transitions";
-  })();
+  const updateMode = formOf(machine);
   function applyUpdate(state2, msg) {
     if (__DEV__) deepFreeze(state2);
     let result;
@@ -230,7 +154,11 @@ function run(machine, opts) {
         continue;
       }
       try {
-        const cleanup = handler(sub, ctx, enqueueDispatch);
+        const cleanup = handler(
+          sub,
+          ctx,
+          enqueueDispatch
+        );
         subRegistry.set(sub.id, cleanup);
       } catch (err) {
         if (firstStartError === null) firstStartError = err;
@@ -243,9 +171,13 @@ function run(machine, opts) {
     for (const cmd of cmds) {
       const handler = interpretMap[cmd.type];
       if (!handler) continue;
-      const follow = await handler(cmd, augmentedCtx);
+      const follow = await handler(
+        cmd,
+        augmentedCtx
+      );
       if (follow !== void 0 && follow !== null) {
-        enqueueDispatch(follow).catch(() => {
+        enqueueDispatch(follow).catch((error) => {
+          reportError(error, { phase: "follow-up" });
         });
       }
     }
@@ -270,17 +202,83 @@ function run(machine, opts) {
       }
     }
   }
+  function fireEvents(msg) {
+    if (eventHandlers.size === 0 || state === void 0) return;
+    let events;
+    try {
+      events = projectEvents(msg, state);
+    } catch (err) {
+      console.error(err);
+      return;
+    }
+    for (const event of events) {
+      const bucket = eventHandlers.get(event.type);
+      if (bucket === void 0) continue;
+      for (const handler of bucket) {
+        try {
+          handler(event);
+        } catch (err) {
+          console.error(err);
+        }
+      }
+    }
+  }
+  function fireBoot() {
+    booted = true;
+    if (bootHandlers.size === 0 || state === void 0) return;
+    const snapshot = state;
+    for (const handler of bootHandlers) {
+      try {
+        handler(snapshot);
+      } catch (err) {
+        console.error(err);
+      }
+    }
+  }
+  function settleDoneWaiters() {
+    if (doneWaiters.size === 0 || state === void 0) return;
+    if (!isTerminal(state)) return;
+    const snapshot = state;
+    const parked = [...doneWaiters];
+    doneWaiters.clear();
+    for (const resolve of parked) resolve(snapshot);
+  }
   async function stepDispatch(msg) {
     if (state === void 0) {
       throw new Error("@demlik/tea: runtime not booted");
     }
-    const [next, cmds] = applyUpdate(state, msg);
+    let next;
+    let cmds;
+    try {
+      [next, cmds] = applyUpdate(state, msg);
+    } catch (reduceError) {
+      reportError(reduceError, { phase: "reduce" });
+      switch (supervision.strategy) {
+        case "restart": {
+          state = supervision.rehydrate(state, msg, reduceError);
+          if (store) await store.save(state);
+          reconcileSubs();
+          fireListeners();
+          fireObservers(msg);
+          fireEvents(msg);
+          settleDoneWaiters();
+          return;
+        }
+        case "escalate":
+          throw reduceError;
+        default:
+          stopped = true;
+          throw reduceError;
+      }
+    }
     state = next;
     if (store) await store.save(state);
     reconcileSubs();
     await runInterpret(cmds);
     fireListeners();
     fireObservers(msg);
+    fireEvents(msg);
+    settleDoneWaiters();
   }
   let pendingInitCmds = [];
   if (!store) {
@@ -300,10 +298,12 @@ function run(machine, opts) {
     reconcileSubs();
     await runInterpret(pendingInitCmds);
     fireListeners();
-    fireObservers(null);
+    fireBoot();
+    settleDoneWaiters();
   }
   function enqueueDispatch(msg) {
-    if (stopped) return Promise.reject(new Error("@demlik/tea: runtime stopped"));
+    if (stopped)
+      return Promise.reject(new Error("@demlik/tea: runtime stopped"));
     const next = tail.then(() => {
       if (bootError !== null) throw bootError;
       return stepDispatch(msg);
@@ -312,17 +312,30 @@ function run(machine, opts) {
     });
     return next;
   }
+  async function drainToQuiescence() {
+    for (let i = 0; i < idleCap; i++) {
+      const observed = tail;
+      await observed;
+      if (tail === observed) return;
+    }
+    throw new QuiescenceTimeoutError(idleCap);
+  }
+  async function dispatchToQuiescence(msg, opts2) {
+    await enqueueDispatch(msg);
+    if (opts2?.settle === "once") return;
+    await drainToQuiescence();
+  }
   const bootPromise = stepBootEffects();
   tail = bootPromise.catch((err) => {
     bootError = err;
   });
+  const readyPromise = bootPromise.then(
+    () => runtime
+  );
   const runtime = {
-    dispatch: enqueueDispatch,
+    dispatch: dispatchToQuiescence,
+    dispatchOnce: enqueueDispatch,
     getState() {
-      if (bootError !== null) throw bootError;
-      if (state === void 0) {
-        throw new Error("@demlik/tea: getState() called before runtime booted");
-      }
       return state;
     },
     subscribe(listener) {
@@ -337,6 +350,36 @@ function run(machine, opts) {
         observers.delete(observer);
       };
     },
+    onBoot(handler) {
+      if (booted && state !== void 0) {
+        try {
+          handler(state);
+        } catch (err) {
+          console.error(err);
+        }
+        return () => {
+        };
+      }
+      bootHandlers.add(handler);
+      return () => {
+        bootHandlers.delete(handler);
+      };
+    },
+    on(type, handler) {
+      let bucket = eventHandlers.get(type);
+      if (bucket === void 0) {
+        bucket = /* @__PURE__ */ new Set();
+        eventHandlers.set(type, bucket);
+      }
+      const erased = handler;
+      bucket.add(erased);
+      return () => {
+        const set = eventHandlers.get(type);
+        if (set === void 0) return;
+        set.delete(erased);
+        if (set.size === 0) eventHandlers.delete(type);
+      };
+    },
     subscribePort(port, listener) {
       const key = port;
       let bucket = portRegistry.get(key);
@@ -356,11 +399,24 @@ function run(machine, opts) {
     emitPort(port, value) {
       portEmit(port, value);
     },
-    // `ready` is the original (un-swallowed) boot promise. Idempotency
-    // comes for free — promises settle exactly once; every read returns the
-    // same settled value. See the boot-promise note above for why this is
-    // distinct from `tail`.
-    ready: bootPromise,
+    // `ready` is assigned just below (it must resolve to `runtime` itself,
+    // which can't be referenced inside its own object literal). See the
+    // assignment + rationale after this block.
+    ready: readyPromise,
+    idle() {
+      return drainToQuiescence();
+    },
+    result() {
+      const current = state;
+      return isTerminal(current) ? current : void 0;
+    },
+    done() {
+      const current = state;
+      if (isTerminal(current)) return Promise.resolve(current);
+      return new Promise((resolve) => {
+        doneWaiters.add(resolve);
+      });
+    },
     async stop() {
       stopped = true;
       await tail;
@@ -375,8 +431,8 @@ function run(machine, opts) {
       if (store && state !== void 0 && bootError === null) {
         try {
           await store.save(state);
-        } catch (err) {
-          console.error(err);
+        } catch (error) {
+          reportError(error, { phase: "stop-save" });
         }
       }
     }
@@ -386,10 +442,17 @@ function run(machine, opts) {
 function historyTracker(runtime, size) {
   const buffer = [];
   let stopped = false;
+  const push = (entry) => {
+    buffer.push(entry);
+    if (buffer.length > size) buffer.shift();
+  };
   const unobserve = size <= 0 ? () => {
   } : runtime.observe((msg, state) => {
-    buffer.push({ msg, state });
-    if (buffer.length > size) buffer.shift();
+    push({ msg, state });
+  });
+  const unboot = size <= 0 ? () => {
+  } : runtime.onBoot((state) => {
+    push({ msg: null, state });
   });
   return {
     snapshot() {
@@ -399,6 +462,7 @@ function historyTracker(runtime, size) {
       if (stopped) return;
       stopped = true;
       unobserve();
+      unboot();
     }
   };
 }
@@ -410,33 +474,12 @@ function replay(machine, opts) {
       "TEA contract violation: machine.init must return [state, []] (no Cmds) when `loaded` is non-null. Init's rehydrate branch is a pure state passthrough \u2014 the migration/parse boundary, not the boot-effect hook.\n\nRoutes for boot effects:\n  - Stateless infrastructure (e.g. chrome.alarms ensure) \u2192 host module top level, outside TEA.\n  - State-conditional resume (e.g. re-attach a session) \u2192 a `boot` Msg dispatched once from the host after `run(...)` returns, handled in update.\n\nSee .patterns/tea/tea-invariants.md (Invariant 2)."
     );
   }
-  let state = initialState;
-  const cmds = [...initCmds];
-  const updateForm = machine.update;
-  const updateMode = (() => {
-    const firstKey = Object.keys(updateForm)[0];
-    if (firstKey === void 0) return "reducer";
-    const firstValue = updateForm[firstKey];
-    return typeof firstValue === "function" ? "reducer" : "transitions";
-  })();
-  for (const msg of opts.msgs) {
-    if (__DEV__) deepFreeze(state);
-    let result;
-    if (updateMode === "reducer") {
-      result = updateForm[msg.type](
-        state,
-        msg
-      );
-    } else {
-      const table = updateForm;
-      const stateKey = state.type;
-      result = table[stateKey][msg.type](state, msg);
-    }
-    if (__DEV__) assertPureResult(result, msg.type);
-    const [next, emitted] = result;
-    state = next;
-    cmds.push(...emitted);
-  }
+  const { state, cmds: foldedCmds } = foldUpdates(
+    machine,
+    initialState,
+    opts.msgs
+  );
+  const cmds = [...initCmds, ...foldedCmds];
   const subs = machine.subscriptions ? [...machine.subscriptions(state)] : [];
   return { state, cmds, subs };
 }
@@ -453,6 +496,6 @@ function tryInterpret(work, onOk, onErr) {
   };
 }
 
-export { Cmd, PortNameCollisionError, __resetPortRegistry, absurd, defineMachine, definePort, historyTracker, noop, replay, run, subId, tryInterpret };
-//# sourceMappingURL=chunk-CMG2KMWX.js.map
-//# sourceMappingURL=chunk-CMG2KMWX.js.map
+export { PortNameCollisionError, QuiescenceTimeoutError, __resetPortRegistry, absurd, asReducer, defineMachine, definePort, historyTracker, noop, replay, run, tryInterpret };
+//# sourceMappingURL=chunk-2WZHS4P2.js.map
+//# sourceMappingURL=chunk-2WZHS4P2.js.map