@junoflow/testkit 0.11.0 → 0.13.0

package/src/handles.js

@@ -0,0 +1,472 @@
+import { fail } from './assert.js';
+
+// The handle half of the flow harness: ctx.after, ctx.at, ctx.all and
+// ctx.wait, plus the state handles (state.<b>.when|becomes|changes), the
+// event handle (targets.<i>.untilEvent), the run handle
+// (targets.<f>.start|startAll), the press handle (controls.<b>.untilPressed)
+// and the question handle (ctx.ask), built as sdk/src/handles.ts and the
+// engine's kinds behave, minus the clock and the bus. The harness cannot
+// suspend, so a handle fires only where the engine would fire it inside Open:
+// an `at` whose instant is at or before h.now(), and a `when` without `for`
+// whose binding's value already matches — and a run handle or a question,
+// which fires at open with the test's answer. An `after`, a `becomes`, a
+// `changes`, a `for` hold, an event, a press and an unanswered question never
+// fire. An `all` fires at open when every member did, and is cancelled with
+// any member. A wait with a fired handle listed returns it; any other wait is
+// refused.
+
+/** The engine's cap on open handles per run (decision 6 of the wait plan). */
+export const MAX_OPEN_HANDLES = 100;
+
+const CAP_MESSAGE = `run has ${MAX_OPEN_HANDLES} open handles; cancel the ones it no longer needs (a handle created in a loop wants "using")`;
+
+// Go's time.ParseDuration, as juno/valid-duration spells it.
+const GO_DURATION =
+  /^[+-]?(\d+(\.\d*)?|\.\d+)(ns|us|µs|μs|ms|s|m|h)((\d+(\.\d*)?|\.\d+)(ns|us|µs|μs|ms|s|m|h))*$/;
+
+// time.RFC3339 as Go parses it: seconds required, an offset required.
+const RFC3339 =
+  /^\d{4}-\d{2}-\d{2}[Tt]\d{2}:\d{2}:\d{2}(\.\d+)?([Zz]|[+-]\d{2}:\d{2})$/;
+
+// `using` lowers to Symbol.dispose where the runtime has it, and to this
+// registered symbol where it does not — the fallback esbuild and tsc emit.
+const DISPOSE = Symbol.dispose ?? Symbol.for('Symbol.dispose');
+
+/**
+ * An instant as the engine writes fired_at: RFC 3339 in UTC with trailing
+ * fractional zeros trimmed (Go's RFC3339Nano).
+ */
+export function rfc3339(ms) {
+  return new Date(ms)
+    .toISOString()
+    .replace(/\.(\d*?)0+Z$/, (_, d) => (d ? `.${d}Z` : 'Z'));
+}
+
+/**
+ * One run's handle table. `refuse` is the run's recording fail(); `instant`
+ * reads the harness clock (epoch ms, or undefined with none set); `render`
+ * spells a call's arguments for a refusal.
+ */
+export function createHandleTable({ refuse, instant, render, harnessName }) {
+  const handles = [];
+  let handleIdx = 0;
+  let waitIdx = 0;
+  // The SDK reports a refused open at the next wait or when the handler
+  // returns, never at the constructor, which is synchronous. Kept here and
+  // thrown at the same two points.
+  let refusal = null;
+
+  const record = (message) => {
+    try {
+      refuse(message);
+    } catch (err) {
+      refusal ??= err;
+    }
+  };
+
+  const byObject = new WeakMap();
+
+  // name is the constructor as a refusal spells it; kind is what the host
+  // records (both `after` and `at` are timers there). spec carries the host's
+  // refusal (`error`), or when it fires at open, `firesAt` (epoch ms) and
+  // `value`; and `label` when it is not the second argument, as a timer's is.
+  function open(name, args, spec, kind = 'timer') {
+    const id = `__h_${handleIdx++}__`;
+    const label = 'label' in spec ? spec.label : args[1];
+    const h = {
+      id,
+      kind,
+      label,
+      status: 'open',
+      call: spec.call ?? `${name}(${render(args)})`,
+      members: spec.members,
+      returned: false,
+      value: undefined,
+      firedAt: undefined,
+    };
+
+    const openCount = handles.filter((x) => x.status === 'open').length;
+    let error = spec.error;
+    if (!error && openCount >= MAX_OPEN_HANDLES) error = CAP_MESSAGE;
+    if (error) {
+      // A refused open leaves nothing behind on the host.
+      h.status = 'refused';
+      record(error);
+    } else {
+      handles.push(h);
+      if (spec.firesAt !== undefined) {
+        h.status = 'fired';
+        h.value = spec.value ?? null;
+        h.firedAt = rfc3339(spec.firesAt);
+      }
+    }
+    return handleObject(h);
+  }
+
+  function handleObject(h) {
+    const notReturned = () => {
+      throw new Error(`handle ${h.id} has not been returned by a wait`);
+    };
+    const obj = {
+      id: h.id,
+      label: h.label,
+      get fired() {
+        return h.returned;
+      },
+      get value() {
+        if (!h.returned) notReturned();
+        return h.value;
+      },
+      get firedAt() {
+        if (!h.returned) notReturned();
+        return h.firedAt;
+      },
+      cancel() {
+        if (h.cancelled) return;
+        h.cancelled = true;
+        if (h.status === 'open') cancelOpen(h);
+      },
+      [DISPOSE]() {
+        obj.cancel();
+      },
+    };
+    byObject.set(obj, h);
+    return obj;
+  }
+
+  // The engine's cancelHandle: close the handle, then every open all that
+  // lists it, recursively — an all whose member cannot fire cannot either.
+  // A cascaded all is refused by a later wait, as the host refuses it.
+  function cancelOpen(h) {
+    h.status = 'cancelled';
+    for (const a of handles) {
+      if (a.kind === 'all' && a.status === 'open' && a.members.includes(h)) {
+        a.cancelled = true;
+        cancelOpen(a);
+      }
+    }
+  }
+
+  return {
+    after(duration, label) {
+      const args = [duration, label];
+      const ok =
+        typeof duration === 'string' &&
+        (duration === '0' || GO_DURATION.test(duration));
+      if (!ok) {
+        return open('after', args, {
+          error: `after: ${JSON.stringify(duration)} is not a duration (e.g. "30s", "5m")`,
+        });
+      }
+      return open('after', args, {});
+    },
+
+    at(when, label) {
+      const args = [when, label];
+      const ms =
+        typeof when === 'string' && RFC3339.test(when) ? Date.parse(when) : NaN;
+      if (Number.isNaN(ms)) {
+        return open('at', args, {
+          error: `at: ${JSON.stringify(when)} is not an RFC 3339 instant`,
+        });
+      }
+      const now = instant();
+      if (now === undefined) {
+        refuse(
+          `at(${render(args)}) was called but the test set no clock — h.now('2026-10-04T18:42:00') ` +
+            `(wall time in h.timezone(), default UTC), or ${harnessName}({ now })`
+        );
+      }
+      return open('at', args, { firesAt: ms <= now ? ms : undefined });
+    },
+
+    /**
+     * state.<binding>.when|becomes|changes. `call` is how a refusal spells
+     * the constructor (`state.door.when`); `current` answers the binding's
+     * value, read only when a `when` without `for` needs it to decide whether
+     * the handle fires at open; `error` is a host refusal the caller already
+     * knows of (a binding that grants no value access).
+     */
+    stateHandle(mode, call, args, { current, error }) {
+      const [match, opts] = mode === 'changes' ? [undefined, args[0]] : args;
+      const label = opts?.label;
+      const conds =
+        mode === 'changes' ? undefined : compileMatch(mode, match, refuse);
+      const hold = mode === 'changes' ? undefined : opts?.for;
+      if (!error && hold !== undefined && !isPositiveDuration(hold)) {
+        error = `${mode}: for ${JSON.stringify(hold)} is not a duration (e.g. "30s", "5m")`;
+      }
+      if (error) return open(call, args, { error, label }, 'state');
+      const spec = { label };
+      if (mode === 'when' && hold === undefined) {
+        const value = current();
+        if (matches(value, conds)) {
+          spec.firesAt = instant() ?? Date.now();
+          spec.value = value;
+        }
+      }
+      return open(call, args, spec, 'state');
+    },
+
+    /**
+     * targets.<binding>.untilEvent. The harness has no bus, so it never
+     * fires; a `where` value that is not a scalar is the host's refusal.
+     */
+    eventHandle(call, args) {
+      const [, where, opts] = args;
+      let error;
+      for (const field of Object.keys(where ?? {}).sort()) {
+        if (!isScalar(where[field])) {
+          error = `untilEvent: where.${field} must be a string, number, boolean or null`;
+          break;
+        }
+      }
+      return open(call, args, { error, label: opts?.label }, 'event');
+    },
+
+    /** controls.<b>.untilPressed: never fires, since nothing presses in a test. */
+    pressHandle(call, args) {
+      const [opts] = args;
+      return open(call, args, { label: opts?.label }, 'press');
+    },
+
+    /**
+     * targets.<flow>.start|startAll. The harness runs no child, so a run
+     * handle fires at open with the value the test's answer makes, or is the
+     * host's refusal when `error` is set.
+     */
+    runHandle(call, args, { label, value, error }) {
+      if (error !== undefined) return open(call, args, { error, label }, 'run');
+      return open(
+        call,
+        args,
+        { label, firesAt: instant() ?? Date.now(), value },
+        'run'
+      );
+    },
+
+    /**
+     * ctx.ask. The harness has no channels, so a question fires at open with
+     * the value the test's answer makes, stays open with none, or is the
+     * host's refusal when `error` is set.
+     */
+    questionHandle(call, args, { label, value, error }) {
+      if (error !== undefined) {
+        return open(call, args, { error, label }, 'question');
+      }
+      const spec = { label };
+      if (value !== undefined) {
+        spec.firesAt = instant() ?? Date.now();
+        spec.value = value;
+      }
+      return open(call, args, spec, 'question');
+    },
+
+    /**
+     * ctx.all: fires at open when every member fired at open, with their
+     * values in list order at the latest member's firedAt; else never.
+     */
+    all(list, label) {
+      if (!Array.isArray(list)) {
+        refuse(`all takes an array of handles, got ${render([list])}`);
+      }
+      const rows = list.filter(Boolean).map((obj) => {
+        const h = byObject.get(obj);
+        if (!h) refuse(`all lists ${render([obj])}, which is not a handle`);
+        return h;
+      });
+      const call = `all([${rows.map((h) => h.call).join(', ')}]${label === undefined ? '' : `, ${render([label])}`})`;
+      const spec = { call, label, members: rows };
+      if (rows.length === 0) {
+        spec.error = 'all needs at least one handle';
+      } else {
+        const bad =
+          rows.find((h) => h.status === 'refused') ??
+          rows.find((h) => h.status === 'cancelled');
+        if (bad) {
+          spec.error =
+            bad.status === 'refused'
+              ? `all lists ${bad.id}, which this run never opened`
+              : `all lists ${bad.id}, which was cancelled`;
+        } else if (rows.every((h) => h.status === 'fired')) {
+          spec.firesAt = Math.max(...rows.map((h) => Date.parse(h.firedAt)));
+          spec.value = rows.map((h) => h.value);
+        }
+      }
+      return open('all', [list, label], spec, 'all');
+    },
+
+    async wait(list, label) {
+      waitIdx++;
+      if (!Array.isArray(list)) {
+        refuse(`wait takes an array of handles, got ${render([list])}`);
+      }
+      const listed = list.filter(Boolean);
+      if (listed.length === 0) refuse('wait needs at least one handle');
+      const rows = listed.map((obj) => {
+        const h = byObject.get(obj);
+        if (!h) refuse(`wait lists ${render([obj])}, which is not a handle`);
+        return h;
+      });
+      for (const h of rows) {
+        if (h.cancelled) refuse(`wait lists ${h.id}, which was cancelled`);
+      }
+      settle();
+
+      // The earliest fired_at wins; ties go to the earlier list position.
+      let best = null;
+      for (const h of rows) {
+        if (h.status !== 'fired') continue;
+        if (best === null || Date.parse(h.firedAt) < Date.parse(best.firedAt)) {
+          best = h;
+        }
+      }
+      if (best) {
+        best.returned = true;
+        return listed[rows.indexOf(best)];
+      }
+      const calls = rows.map((h) => h.call).join(', ');
+      refuse(
+        `a handler cannot suspend in a test: wait([${calls}]${label === undefined ? '' : `, ${render([label])}`})`
+      );
+    },
+
+    /** Throws the first refused open, as the SDK's settle() does. */
+    settle,
+
+    /** A run that ended cancels every handle still open, as the engine does. */
+    close() {
+      for (const h of handles) if (h.status === 'open') h.status = 'cancelled';
+    },
+
+    list() {
+      return handles.map(({ id, kind, label, status }) => ({
+        id,
+        kind,
+        label,
+        status,
+      }));
+    },
+  };
+
+  function settle() {
+    if (refusal) throw refusal;
+  }
+}
+
+/** A Go duration greater than zero, as the state kind accepts for `for`. */
+export function isPositiveDuration(d) {
+  if (typeof d !== 'string' || !GO_DURATION.test(d) || d.startsWith('-')) {
+    return false;
+  }
+  return [...d.matchAll(/(\d+(?:\.\d*)?|\.\d+)[a-zµμ]+/g)].some(
+    (m) => Number(m[1]) > 0
+  );
+}
+
+// ─── match semantics (internal/handlekind) ─────────────────────────────────
+//
+// One definition of what `where` and a state match mean, held to the Go side
+// by internal/handlekind/testdata/handle-match.json (test/handles.test.js).
+
+/** A state match's object keys, and the op each compiles to (sdk/src/context.ts). */
+const MATCH_KEYS = new Map([
+  ['in', 'in'],
+  ['not', 'ne'],
+  ['notIn', 'not_in'],
+  ['above', 'gt'],
+  ['below', 'lt'],
+  ['atLeast', 'ge'],
+  ['atMost', 'le'],
+]);
+
+/**
+ * compileMatch in sdk/src/context.ts: a plain value is one `eq`; an object is
+ * one condition per key present. An unknown key is refused, as the SDK throws.
+ */
+export function compileMatch(ctor, match, refuse = fail) {
+  if (match === null || typeof match !== 'object' || Array.isArray(match)) {
+    return [{ op: 'eq', value: match ?? null }];
+  }
+  const conds = [];
+  for (const [key, value] of Object.entries(match)) {
+    const op = MATCH_KEYS.get(key);
+    if (op === undefined) {
+      refuse(
+        `${ctor}: match has no condition "${key}" (have: ${[...MATCH_KEYS.keys()].join(', ')})`
+      );
+    }
+    if (value !== undefined) conds.push({ op, value });
+  }
+  return conds;
+}
+
+/** handlekind.Matches: every condition holds. */
+export function matches(value, conds) {
+  return conds.every((c) => matchCond(value, c));
+}
+
+function matchCond(v, { op, value }) {
+  switch (op) {
+    case 'eq':
+      return jsonEqual(v, value);
+    case 'ne':
+      return !jsonEqual(v, value);
+    case 'in':
+    case 'not_in': {
+      if (!Array.isArray(value)) return false;
+      return value.some((x) => jsonEqual(v, x)) === (op === 'in');
+    }
+    case 'gt':
+    case 'lt':
+    case 'ge':
+    case 'le': {
+      if (typeof v !== 'number' || typeof value !== 'number') return false;
+      if (op === 'gt') return v > value;
+      if (op === 'lt') return v < value;
+      if (op === 'ge') return v >= value;
+      return v <= value;
+    }
+    default:
+      return false;
+  }
+}
+
+/**
+ * handlekind.MatchWhere: every where field present on the payload and equal
+ * as a JSON value; a where value that is not a scalar never matches.
+ */
+export function matchWhere(payload, where) {
+  const fields = Object.keys(where ?? {});
+  if (fields.length === 0) return true;
+  if (
+    payload === null ||
+    typeof payload !== 'object' ||
+    Array.isArray(payload)
+  ) {
+    return false;
+  }
+  return fields.every(
+    (f) =>
+      isScalar(where[f]) &&
+      Object.hasOwn(payload, f) &&
+      jsonEqual(payload[f], where[f])
+  );
+}
+
+function isScalar(v) {
+  return v === null || ['string', 'number', 'boolean'].includes(typeof v);
+}
+
+/** Equal as JSON values: object keys in any order, 1 and "1" different. */
+function jsonEqual(a, b) {
+  return canonical(a) === canonical(b);
+}
+
+function canonical(v) {
+  if (v === undefined) return 'null';
+  if (v === null || typeof v !== 'object') return JSON.stringify(v);
+  if (Array.isArray(v)) return `[${v.map(canonical).join(',')}]`;
+  const keys = Object.keys(v).sort();
+  return `{${keys.map((k) => `${JSON.stringify(k)}:${canonical(v[k])}`).join(',')}}`;
+}