@protoyard/flows 0.0.0-stage → 1.1.1

package/dist/model/walk.js

@@ -0,0 +1,68 @@
+/** The arms of a step, empty for anything but a branch. */
+export function childArms(step) {
+    if (step.type !== 'branch')
+        return [];
+    return [
+        { branch: 'then', steps: step.then },
+        { branch: 'otherwise', steps: step.otherwise },
+    ];
+}
+/** Visits every step in document (pre-)order, which is also run order. */
+export function walkSteps(steps, visit, parent = null) {
+    const base = parent ? [...parent.path, parent.branch] : ['steps'];
+    steps.forEach((step, index) => {
+        const location = {
+            step,
+            path: [...base, index],
+            parentId: parent?.id ?? null,
+            branch: parent?.branch ?? null,
+            index,
+            depth: parent ? parent.depth + 1 : 0,
+            arms: parent ? [...parent.arms, `${parent.id}:${parent.branch}`] : [],
+        };
+        visit(location);
+        for (const arm of childArms(step)) {
+            walkSteps(arm.steps, visit, {
+                id: step.id,
+                branch: arm.branch,
+                path: location.path,
+                depth: location.depth,
+                arms: location.arms,
+            });
+        }
+    });
+}
+export function listSteps(steps) {
+    const out = [];
+    walkSteps(steps, (location) => out.push(location));
+    return out;
+}
+export function findStep(steps, stepId) {
+    return listSteps(steps).find((location) => location.step.id === stepId) ?? null;
+}
+/**
+ * True when `earlier` has certainly run by the time `later` starts: it comes
+ * first in run order and is not inside a branch arm that `later` is outside of.
+ */
+export function runsBefore(earlier, later, order) {
+    const a = order.get(earlier.step.id);
+    const b = order.get(later.step.id);
+    if (a === undefined || b === undefined || a >= b)
+        return false;
+    return earlier.arms.every((arm, i) => later.arms[i] === arm);
+}
+/** The steps whose output a step may reference. */
+export function stepsBefore(steps, stepId) {
+    const all = listSteps(steps);
+    const order = new Map(all.map((location, i) => [location.step.id, i]));
+    const target = all.find((location) => location.step.id === stepId);
+    if (!target)
+        return [];
+    return all.filter((location) => runsBefore(location, target, order)).map((l) => l.step);
+}
+/** `['steps', 0, 'then', 1]` → `steps[0].then[1]`. */
+export function formatPath(path) {
+    return path
+        .map((segment, i) => typeof segment === 'number' ? `[${segment}]` : i === 0 ? segment : `.${segment}`)
+        .join('');
+}

package/dist/runtime/clock.d.ts

@@ -0,0 +1,12 @@
+/** Injected simulated clock for the mock flow runtime. */
+export interface MockClock {
+    nowMs(): number;
+    nowIso(): string;
+    /** Advance by whole minutes (waits and delays). */
+    advanceMinutes(minutes: number): void;
+    set(ms: number): void;
+}
+export declare function toEpochMs(value: string | number | Date | undefined, fallback: number): number;
+/** Fixed default so tests without `now` still match across machines. */
+export declare const DEFAULT_RUNTIME_NOW_MS: number;
+export declare function createMockClock(initial?: string | number | Date): MockClock;

package/dist/runtime/clock.js

@@ -0,0 +1,40 @@
+/** Injected simulated clock for the mock flow runtime. */
+export function toEpochMs(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value))
+            throw new RangeError(`Invalid clock value: ${String(value)}`);
+        return value;
+    }
+    if (value instanceof Date) {
+        const ms = value.getTime();
+        if (Number.isNaN(ms))
+            throw new RangeError('Invalid clock Date');
+        return ms;
+    }
+    const ms = Date.parse(value);
+    if (Number.isNaN(ms))
+        throw new RangeError(`Invalid clock ISO: ${value}`);
+    return ms;
+}
+/** Fixed default so tests without `now` still match across machines. */
+export const DEFAULT_RUNTIME_NOW_MS = Date.parse('2026-03-15T10:00:00.000Z');
+export function createMockClock(initial) {
+    let ms = toEpochMs(initial, DEFAULT_RUNTIME_NOW_MS);
+    return {
+        nowMs: () => ms,
+        nowIso: () => new Date(ms).toISOString(),
+        advanceMinutes(minutes) {
+            if (!Number.isFinite(minutes) || minutes < 0) {
+                throw new RangeError(`Invalid advance minutes: ${String(minutes)}`);
+            }
+            ms += Math.floor(minutes) * 60_000;
+        },
+        set(next) {
+            if (!Number.isFinite(next))
+                throw new RangeError(`Invalid clock set: ${String(next)}`);
+            ms = next;
+        },
+    };
+}

package/dist/runtime/engine.d.ts

@@ -0,0 +1,15 @@
+import { type Flow } from '../model/index.ts';
+import type { FlowRunResult, FlowRuntimeOptions } from './types.ts';
+/**
+ * Run a flow once against a mock context. Pure with respect to the inputs:
+ * the same flow, options and clock produce identical results. Does not mutate
+ * the input flow or the caller's keeps maps.
+ */
+export declare function runFlow(flow: Flow, options?: FlowRuntimeOptions): FlowRunResult;
+/**
+ * Convenience: create a reusable runner bound to default options (people,
+ * tools, seed). Each `run` call still takes a fresh flow and overrides.
+ */
+export declare function createFlowRuntime(defaults?: FlowRuntimeOptions): {
+    run(flow: Flow, overrides?: FlowRuntimeOptions): FlowRunResult;
+};