@demlik/tea 0.13.0 → 0.15.0

package/dist/flow/index.js

@@ -0,0 +1,732 @@
+export { addItem, batchWindowExpired, createBatchWindow, initBatchWindow, onWindow, subsFor, subscribeBatchWindow } from '../chunk-QPEVCJ5Q.js';
+export { debounce } from '../chunk-LFZUK6J2.js';
+import { createPaginatedWalk, PAGE_KEY } from '../chunk-Q5CQTBFA.js';
+import { pendingEffectsLedger, foldLedger, survivingEffects } from '../chunk-6IQPODUF.js';
+export { emptyLedger } from '../chunk-6IQPODUF.js';
+export { createMonitoredRun, liftRun } from '../chunk-3B5X7SBB.js';
+export { createFanOut, initFanOut, isComplete } from '../chunk-MYXFNWAJ.js';
+import { idempotencyMemory } from '../chunk-PR6TB3BL.js';
+import { queueAdapter } from '../chunk-TXN2KFHF.js';
+import '../chunk-L3TND7LA.js';
+import '../chunk-AYS5N6WY.js';
+import { asRng, defaultRetryPolicy, initRetry, recordFailure, shouldRetry, nextDelayMs } from '../chunk-VBDU4JL6.js';
+import { deadlineSub, initCache, get, set } from '../chunk-22POWGFA.js';
+export { deadlineSub, subscribeDeadline } from '../chunk-22POWGFA.js';
+import { run, Cmd } from '../chunk-66PY5WYF.js';
+import { z } from 'zod';
+
+// src/internal/flow/await-terminal/index.ts
+var TerminalTimeoutError = class extends Error {
+  constructor(timeoutMs) {
+    super(
+      `@demlik/tea: awaitTerminal did not reach a terminal state within ${timeoutMs}ms \u2014 no transition satisfied isTerminal before the deadline.`
+    );
+    this.timeoutMs = timeoutMs;
+  }
+  timeoutMs;
+  name = "TerminalTimeoutError";
+  _tag = "TerminalTimeoutError";
+};
+function awaitTerminal(runtime, isTerminal, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const current = runtime.getState();
+    if (isTerminal(current)) {
+      resolve(current);
+      return;
+    }
+    let settled = false;
+    let timer;
+    let detach;
+    const cleanup = () => {
+      if (timer !== void 0) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      if (detach !== void 0) {
+        detach();
+        detach = void 0;
+      }
+    };
+    detach = runtime.observe((_msg, state) => {
+      if (settled) return;
+      if (isTerminal(state)) {
+        settled = true;
+        cleanup();
+        resolve(state);
+      }
+    });
+    const timeoutMs = opts.timeoutMs;
+    if (timeoutMs !== void 0) {
+      timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(new TerminalTimeoutError(timeoutMs));
+      }, timeoutMs);
+    }
+  });
+}
+async function runToTerminal(machine, seed, isTerminal, opts = {}) {
+  const { msgs, ...ctxArg } = seed;
+  const runtime = await run(
+    machine,
+    ctxArg
+  ).ready;
+  try {
+    const terminal = awaitTerminal(runtime, isTerminal, opts);
+    const seeding = Promise.all(msgs.map((msg) => runtime.dispatch(msg)));
+    const state = await Promise.race([terminal, seeding.then(() => terminal)]);
+    await runtime.stop();
+    return state;
+  } catch (err) {
+    await runtime.stop().catch(() => {
+    });
+    throw err;
+  }
+}
+
+// src/internal/flow/poller/index.ts
+function pollerSubId(atMs) {
+  return `poller:tick:${atMs}`;
+}
+function createPoller(config, rng = Math.random) {
+  const rngBranded = asRng(rng);
+  const policy = config.retry ?? defaultRetryPolicy;
+  const memory = idempotencyMemory();
+  function init() {
+    return {
+      phase: "polling",
+      tick: 0,
+      retry: initRetry(),
+      nextAtMs: null,
+      // The dedupe store is created regardless; it is only WRITTEN when
+      // `dedupeKey` is set, so an unconfigured poller carries an inert empty
+      // store (no per-op cost, JSON-serializable, durable like the rest of
+      // the slice).
+      dedupe: memory.init({ ttlMs: config.dedupeTtlMs })
+    };
+  }
+  function start(state, at) {
+    return [
+      {
+        phase: "polling",
+        tick: state.tick,
+        lastResult: state.lastResult,
+        retry: state.retry,
+        nextAtMs: at + config.everyMs,
+        dedupe: state.dedupe
+      },
+      []
+    ];
+  }
+  function tick(state) {
+    if (state.phase !== "polling") return [state, []];
+    return [state, [config.onTick()]];
+  }
+  function tickResult(state, result, at, untilHeld) {
+    const tick2 = state.tick + 1;
+    if (untilHeld) {
+      return [
+        {
+          phase: "done",
+          tick: tick2,
+          lastResult: result,
+          retry: initRetry(),
+          dedupe: state.dedupe
+        },
+        []
+      ];
+    }
+    const next = {
+      phase: "polling",
+      tick: tick2,
+      lastResult: result,
+      retry: initRetry(),
+      nextAtMs: at + config.everyMs,
+      dedupe: state.dedupe
+    };
+    if (!config.dedupeKey) return [next, []];
+    const key = config.dedupeKey(result);
+    const suppress = memory.isSeen(next.dedupe, key, at);
+    const deduped = {
+      ...next,
+      dedupe: memory.remember(next.dedupe, key, true, at)
+    };
+    return [deduped, suppress ? [] : [config.onTick()]];
+  }
+  function tickErr(state, error, at) {
+    const retry = recordFailure(state.retry, error, at);
+    const tick2 = state.tick + 1;
+    if (!shouldRetry(retry, policy, at)) {
+      return [
+        {
+          phase: "gave_up",
+          tick: tick2,
+          lastResult: state.lastResult,
+          retry,
+          dedupe: state.dedupe
+        },
+        []
+      ];
+    }
+    const delayMs = nextDelayMs(retry, policy, rngBranded);
+    return [
+      {
+        phase: "polling",
+        tick: tick2,
+        lastResult: state.lastResult,
+        retry,
+        nextAtMs: at + delayMs,
+        dedupe: state.dedupe
+      },
+      []
+    ];
+  }
+  function subs(state) {
+    if (state.phase !== "polling" || state.nextAtMs === null) return [];
+    return [deadlineSub(pollerSubId(state.nextAtMs), state.nextAtMs)];
+  }
+  return { init, start, tick, tickResult, tickErr, subs };
+}
+
+// src/internal/flow/reconciler/index.ts
+function createReconciler(config, rng = Math.random) {
+  const walk = createPaginatedWalk(
+    {
+      firstPage: config.firstPage,
+      nextCursor: config.nextCursor,
+      // The walk's per-page hook emits no Cmds — the reconciler accumulates the
+      // page's items itself in `pageOk` (where it holds its own slice), so the
+      // walk's onPage stays empty.
+      onPage: () => [],
+      retry: config.retry,
+      circuit: config.circuit,
+      rateLimit: config.rateLimit,
+      deadline: config.deadline
+    },
+    rng
+  );
+  function changeId(change) {
+    return config.idOf ? config.idOf(change) : JSON.stringify(change);
+  }
+  function withWalk(s, w) {
+    return { ...s, walk: w };
+  }
+  function init() {
+    return {
+      phase: "idle",
+      walk: walk.init(),
+      actual: [],
+      plan: [],
+      appliedCursor: 0,
+      applied: initCache()
+    };
+  }
+  function scan(s, at) {
+    if (s.phase !== "idle") return [s, []];
+    const [w, cmds] = walk.start(s.walk, at);
+    const next = { ...s, phase: "scanning", walk: w };
+    return [next, cmds];
+  }
+  function pageOk(s, page, at) {
+    if (s.phase !== "scanning") {
+      const [w2] = walk.pageOk(s.walk, page, at);
+      return [withWalk(s, w2), []];
+    }
+    const [w, walkCmds] = walk.pageOk(s.walk, page, at);
+    const actual = [...s.actual, ...config.itemsOf(page)];
+    const scanned = { ...s, walk: w, actual };
+    const cmds = walkCmds;
+    if (walk.isComplete(scanned.walk)) {
+      const [plannedState, applyCmds] = planned(scanned, at);
+      return [plannedState, [...cmds, ...applyCmds]];
+    }
+    return [scanned, cmds];
+  }
+  function pageErr(s, error, at) {
+    const [w, cmds] = walk.pageErr(s.walk, error, at);
+    let next = withWalk(s, w);
+    if (s.phase === "scanning" && w.resilience.calls[PAGE_KEY]?.phase === "failed") {
+      next = { ...next, phase: "failed" };
+    }
+    return [next, cmds];
+  }
+  function planned(s, at, changes) {
+    const plan = changes ?? config.diff(config.desired, s.actual);
+    const planning = {
+      ...s,
+      phase: "applying",
+      plan,
+      appliedCursor: 0
+    };
+    return applyNext(planning, at);
+  }
+  function applyNext(s, at) {
+    if (s.phase !== "applying") return [s, []];
+    let cursor = s.appliedCursor;
+    while (cursor < s.plan.length) {
+      const change = s.plan[cursor];
+      if (change === void 0) {
+        cursor++;
+        continue;
+      }
+      const id = changeId(change);
+      if (get(s.applied, id, at) === void 0) {
+        const advanced = { ...s, appliedCursor: cursor };
+        return [advanced, [config.apply(change)]];
+      }
+      cursor++;
+    }
+    const done = { ...s, phase: "done", appliedCursor: cursor };
+    return [done, []];
+  }
+  function applied(s, change, at) {
+    if (s.phase !== "applying") return [s, []];
+    const id = changeId(change);
+    const applied2 = set(
+      s.applied,
+      id,
+      change,
+      at,
+      Number.MAX_SAFE_INTEGER
+    );
+    const advanced = {
+      ...s,
+      applied: applied2,
+      appliedCursor: s.appliedCursor + 1
+    };
+    return applyNext(advanced, at);
+  }
+  function onTimer(s, msg) {
+    const [w, cmds] = walk.onTimer(s.walk, msg);
+    if (w === s.walk) {
+      return [s, []];
+    }
+    let next = withWalk(s, w);
+    if (s.phase === "scanning" && w.resilience.calls[PAGE_KEY]?.phase === "failed") {
+      next = { ...next, phase: "failed" };
+    }
+    return [next, cmds];
+  }
+  function isComplete2(s) {
+    return s.phase === "done";
+  }
+  function subs(s) {
+    return walk.subs(s.walk);
+  }
+  function handlers(ports) {
+    return walk.handlers(ports);
+  }
+  return {
+    init,
+    scan,
+    pageOk,
+    pageErr,
+    planned,
+    applyNext,
+    applied,
+    onTimer,
+    isComplete: isComplete2,
+    subs,
+    handlers
+  };
+}
+function liftReconciler(state, [slice, cmds]) {
+  return [{ ...state, rec: slice }, cmds];
+}
+
+// src/internal/flow/saga/index.ts
+function isCommitted(state) {
+  return state.phase === "committed";
+}
+function isAborted(state) {
+  return state.phase === "aborted";
+}
+function isCompensationFailed(state) {
+  return state.phase === "compensation_failed";
+}
+function isSettled(state) {
+  return state.phase === "committed" || state.phase === "aborted" || state.phase === "compensation_failed";
+}
+function initSaga() {
+  return {
+    position: 0,
+    done: [],
+    compensating: false,
+    phase: "idle",
+    items: []
+  };
+}
+function createSaga(config) {
+  const wq = queueAdapter();
+  function freshLedger() {
+    let items = [];
+    config.steps.forEach((_step, index) => {
+      items = wq.enqueue(items, index, 0, String(index)).next;
+    });
+    return items;
+  }
+  function setStatus(items, index, status) {
+    return wq.patch(items, String(index), (item) => ({
+      ...item,
+      status
+    })).next;
+  }
+  function stepAt(index) {
+    return config.steps[index];
+  }
+  function lastDone(done) {
+    return done[done.length - 1];
+  }
+  function start(state) {
+    if (state.phase !== "idle") return [state, []];
+    const items = freshLedger();
+    const first = stepAt(0);
+    if (first === void 0) {
+      return [{ ...state, phase: "committed", items }, []];
+    }
+    const next = {
+      ...state,
+      position: 0,
+      phase: "running",
+      items: setStatus(items, 0, "running")
+    };
+    return [next, [first.do]];
+  }
+  function stepOk(state) {
+    if (state.phase !== "running") return [state, []];
+    const completed = state.position;
+    const itemsDone = setStatus(state.items, completed, "done");
+    const done = [...state.done, completed];
+    const nextPosition = completed + 1;
+    const nextStep = stepAt(nextPosition);
+    if (nextStep === void 0) {
+      return [{ ...state, done, items: itemsDone, phase: "committed" }, []];
+    }
+    const next = {
+      ...state,
+      position: nextPosition,
+      done,
+      items: setStatus(itemsDone, nextPosition, "running")
+    };
+    return [next, [nextStep.do]];
+  }
+  function stepErr(state, error) {
+    if (state.phase !== "running") return [state, []];
+    const failed = state.position;
+    const items = setStatus(state.items, failed, "failed");
+    const undoIndex = lastDone(state.done);
+    const undoStep = undoIndex === void 0 ? void 0 : stepAt(undoIndex);
+    if (undoIndex === void 0 || undoStep === void 0) {
+      return [
+        { ...state, items, error, compensating: true, phase: "aborted" },
+        []
+      ];
+    }
+    const next = {
+      ...state,
+      items,
+      error,
+      compensating: true,
+      phase: "compensating",
+      position: undoIndex
+    };
+    return [next, [undoStep.undo]];
+  }
+  function undoOk(state) {
+    if (state.phase !== "compensating") return [state, []];
+    const undone = lastDone(state.done);
+    if (undone === void 0) return [state, []];
+    const remaining = state.done.slice(0, -1);
+    const items = setStatus(state.items, undone, "cancelled");
+    const nextUndo = lastDone(remaining);
+    const nextStep = nextUndo === void 0 ? void 0 : stepAt(nextUndo);
+    if (nextUndo === void 0 || nextStep === void 0) {
+      return [{ ...state, done: remaining, items, phase: "aborted" }, []];
+    }
+    const next = {
+      ...state,
+      done: remaining,
+      items,
+      position: nextUndo
+    };
+    return [next, [nextStep.undo]];
+  }
+  function undoErr(state, error) {
+    if (state.phase !== "compensating") return [state, []];
+    const items = setStatus(state.items, state.position, "failed");
+    return [
+      {
+        ...state,
+        items,
+        compensationError: error,
+        phase: "compensation_failed"
+      },
+      []
+    ];
+  }
+  return {
+    init: initSaga,
+    start,
+    stepOk,
+    stepErr,
+    undoOk,
+    undoErr,
+    isCommitted,
+    isAborted,
+    isCompensationFailed,
+    isSettled
+  };
+}
+
+// src/internal/flow/workflow/route.ts
+function routeWorkflowMsg(wf, state, msg) {
+  switch (msg.type) {
+    case "activity_ok":
+      return wf.onActivityOk(state, msg);
+    case "activity_err":
+      return wf.onActivityErr(state, msg);
+    case "compensation_ok":
+      return wf.onCompensationOk(state, msg);
+    case "compensation_err":
+      return wf.onCompensationErr(state, msg);
+  }
+}
+
+// src/internal/flow/workflow/index.ts
+var WORKFLOW_STATUSES = new Set(
+  Object.keys({
+    running: true,
+    completed: true,
+    failed: true,
+    compensating: true,
+    failed_compensated: true,
+    compensation_failed: true
+  })
+);
+function workflowActivityDef() {
+  return Cmd.define("workflow_activity", {
+    input: z.custom(),
+    ok: z.void(),
+    err: []
+  });
+}
+function workflowCompensationDef() {
+  return Cmd.define("workflow_compensation", {
+    input: z.custom(),
+    ok: z.void(),
+    err: []
+  });
+}
+var WORKFLOW_MSG_TYPES = new Set(
+  Object.keys({
+    activity_ok: true,
+    activity_err: true,
+    compensation_ok: true,
+    compensation_err: true
+  })
+);
+function createWorkflow(restore) {
+  const recorder = pendingEffectsLedger(restore);
+  const activityCmd = workflowActivityDef();
+  const compensationCmd = workflowCompensationDef();
+  function stepAt(steps, index) {
+    const step = steps[index];
+    if (step === void 0) {
+      throw new Error(
+        `createWorkflow: step index ${index} out of range (length ${steps.length}) \u2014 a reducer bounds proof was violated.`
+      );
+    }
+    return step;
+  }
+  function oweOnLedger(build) {
+    const id = recorder.lastId() + 1;
+    const cmd = build(id);
+    const { id: issued, event } = recorder.owe(cmd);
+    if (issued !== id) {
+      throw new Error(
+        `createWorkflow: delivery-id prediction (${id}) diverged from the recorder's issued id (${issued}). The #67 recorder's monotonic counter is not gap-free as assumed \u2014 this is a substrate invariant violation, not a recoverable condition.`
+      );
+    }
+    return { id, owed: event, cmd };
+  }
+  function oweActivity(step, index) {
+    const { id, owed, cmd } = oweOnLedger(
+      (id2) => activityCmd({ index, id: id2, activity: step.activity })
+    );
+    const current = { index, step, id };
+    return { current, owed, cmd };
+  }
+  function oweCompensation(step, compensation, index) {
+    const { id, owed, cmd } = oweOnLedger(
+      (id2) => compensationCmd({ index, id: id2, compensation })
+    );
+    const current = { index, step, id };
+    return { current, owed, cmd };
+  }
+  function oweNextCompensation(completed, belowIndex) {
+    for (let i = belowIndex - 1; i >= 0; i--) {
+      const entry = completed[i];
+      if (entry !== void 0 && entry.step.compensation !== void 0) {
+        return oweCompensation(entry.step, entry.step.compensation, i);
+      }
+    }
+    return null;
+  }
+  function continueCompensating(base, next, confirmed) {
+    const compensating = {
+      ...base,
+      current: next.current
+    };
+    return {
+      state: compensating,
+      ledger: [confirmed, next.owed],
+      cmds: [next.cmd]
+    };
+  }
+  return {
+    init(steps) {
+      const { current, owed, cmd } = oweActivity(stepAt(steps, 0), 0);
+      const state = {
+        status: "running",
+        steps,
+        completed: [],
+        current
+      };
+      return { state, ledger: [owed], cmds: [cmd] };
+    },
+    onActivityOk(state, msg) {
+      if (state.status !== "running" || msg.id !== state.current.id) {
+        return { state, ledger: [], cmds: [] };
+      }
+      const confirmed = confirm(state.current.id);
+      const completedStep = {
+        step: state.current.step,
+        result: msg.result
+      };
+      const completed = [...state.completed, completedStep];
+      const nextIndex = state.current.index + 1;
+      if (nextIndex >= state.steps.length) {
+        const done = {
+          status: "completed",
+          steps: state.steps,
+          completed,
+          output: msg.result
+        };
+        return { state: done, ledger: [confirmed], cmds: [] };
+      }
+      const { current, owed, cmd } = oweActivity(
+        stepAt(state.steps, nextIndex),
+        nextIndex
+      );
+      const running = {
+        status: "running",
+        steps: state.steps,
+        completed,
+        current
+      };
+      return { state: running, ledger: [confirmed, owed], cmds: [cmd] };
+    },
+    onActivityErr(state, msg) {
+      if (state.status !== "running" || msg.id !== state.current.id) {
+        return { state, ledger: [], cmds: [] };
+      }
+      const confirmed = confirm(state.current.id);
+      const next = oweNextCompensation(state.completed, state.completed.length);
+      if (next === null) {
+        const failed = {
+          status: "failed",
+          steps: state.steps,
+          completed: state.completed,
+          failedStep: state.current.step,
+          failure: msg.failure
+        };
+        return { state: failed, ledger: [confirmed], cmds: [] };
+      }
+      return continueCompensating(
+        {
+          status: "compensating",
+          steps: state.steps,
+          completed: state.completed,
+          failedStep: state.current.step,
+          failure: msg.failure,
+          compensated: []
+        },
+        next,
+        confirmed
+      );
+    },
+    onCompensationOk(state, msg) {
+      if (state.status !== "compensating" || msg.id !== state.current.id) {
+        return { state, ledger: [], cmds: [] };
+      }
+      const confirmed = confirm(state.current.id);
+      const undoneStep = state.completed[state.current.index];
+      if (undoneStep === void 0) {
+        throw new Error(
+          `createWorkflow.onCompensationOk: compensation index ${state.current.index} has no completed step \u2014 a reverse-walk bounds proof was violated.`
+        );
+      }
+      const compensated = [...state.compensated, undoneStep];
+      const next = oweNextCompensation(state.completed, state.current.index);
+      if (next === null) {
+        const settled = {
+          status: "failed_compensated",
+          steps: state.steps,
+          completed: state.completed,
+          failedStep: state.failedStep,
+          failure: state.failure
+        };
+        return { state: settled, ledger: [confirmed], cmds: [] };
+      }
+      return continueCompensating(
+        {
+          status: "compensating",
+          steps: state.steps,
+          completed: state.completed,
+          failedStep: state.failedStep,
+          failure: state.failure,
+          compensated
+        },
+        next,
+        confirmed
+      );
+    },
+    onCompensationErr(state, msg) {
+      if (state.status !== "compensating" || msg.id !== state.current.id) {
+        return { state, ledger: [], cmds: [] };
+      }
+      const confirmed = confirm(state.current.id);
+      const halted = {
+        status: "compensation_failed",
+        steps: state.steps,
+        completed: state.completed,
+        failedStep: state.failedStep,
+        failure: state.failure,
+        compensated: state.compensated,
+        failedCompensationStep: state.current.step,
+        compensationFailure: msg.failure
+      };
+      return { state: halted, ledger: [confirmed], cmds: [] };
+    },
+    survivingActivities(ledgerEvents) {
+      const ledger = foldLedger(ledgerEvents);
+      return survivingEffects(ledger).map((owed) => owed.effect);
+    }
+  };
+  function confirm(id) {
+    return recorder.confirm(id).event;
+  }
+}
+function foldWorkflow(steps, msgs) {
+  const wf = createWorkflow();
+  let { state } = wf.init(steps);
+  for (const msg of msgs) {
+    state = routeWorkflowMsg(wf, state, msg).state;
+  }
+  return state;
+}
+
+export { TerminalTimeoutError, WORKFLOW_MSG_TYPES, WORKFLOW_STATUSES, awaitTerminal, createPoller, createReconciler, createSaga, createWorkflow, foldWorkflow, initSaga, isAborted, isCommitted, isCompensationFailed, isSettled, liftReconciler, routeWorkflowMsg, runToTerminal, workflowActivityDef, workflowCompensationDef };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map