@barnum/barnum 0.2.3 → 0.3.0

package/dist/ast.js

@@ -0,0 +1,381 @@
+// ---------------------------------------------------------------------------
+// typedAction — attach .then() and .forEach() as non-enumerable methods
+// ---------------------------------------------------------------------------
+// Shared implementations (one closure, not per-instance)
+function thenMethod(next) {
+    return typedAction({ kind: "Chain", first: this, rest: next });
+}
+function forEachMethod(action) {
+    return typedAction({
+        kind: "Chain",
+        first: this,
+        rest: { kind: "ForEach", action },
+    });
+}
+function branchMethod(cases) {
+    return typedAction({
+        kind: "Chain",
+        first: this,
+        rest: { kind: "Branch", cases: unwrapBranchCases(cases) },
+    });
+}
+function flattenMethod() {
+    return typedAction({
+        kind: "Chain",
+        first: this,
+        rest: {
+            kind: "Invoke",
+            handler: { kind: "Builtin", builtin: { kind: "Flatten" } },
+        },
+    });
+}
+function dropMethod() {
+    return typedAction({
+        kind: "Chain",
+        first: this,
+        rest: {
+            kind: "Invoke",
+            handler: { kind: "Builtin", builtin: { kind: "Drop" } },
+        },
+    });
+}
+function tagMethod(kind) {
+    return typedAction({
+        kind: "Chain",
+        first: this,
+        rest: {
+            kind: "Invoke",
+            handler: { kind: "Builtin", builtin: { kind: "Tag", value: kind } },
+        },
+    });
+}
+function getMethod(field) {
+    return typedAction({
+        kind: "Chain",
+        first: this,
+        rest: {
+            kind: "Invoke",
+            handler: {
+                kind: "Builtin",
+                builtin: { kind: "ExtractField", value: field },
+            },
+        },
+    });
+}
+function augmentMethod() {
+    // Construct: All(this, identity) → Merge
+    // "this" is the sub-pipeline. augment() wraps it so the original input
+    // flows through identity alongside the sub-pipeline, then merges the results.
+    return typedAction({
+        kind: "Chain",
+        first: {
+            kind: "All",
+            actions: [
+                this,
+                {
+                    kind: "Invoke",
+                    handler: { kind: "Builtin", builtin: { kind: "Identity" } },
+                },
+            ],
+        },
+        rest: {
+            kind: "Invoke",
+            handler: { kind: "Builtin", builtin: { kind: "Merge" } },
+        },
+    });
+}
+function mergeMethod() {
+    return typedAction({
+        kind: "Chain",
+        first: this,
+        rest: {
+            kind: "Invoke",
+            handler: { kind: "Builtin", builtin: { kind: "Merge" } },
+        },
+    });
+}
+function pickMethod(...keys) {
+    return typedAction({
+        kind: "Chain",
+        first: this,
+        rest: {
+            kind: "Invoke",
+            handler: { kind: "Builtin", builtin: { kind: "Pick", value: keys } },
+        },
+    });
+}
+function mapOptionMethod(action) {
+    // Desugars to: self.then(branch({ Some: pipe(action, tag("Some")), None: tag("None") }))
+    // But branch auto-unwraps value, so:
+    //   Some case: receives T, runs action, wraps as Some
+    //   None case: receives void, wraps as None
+    return typedAction({
+        kind: "Chain",
+        first: this,
+        rest: {
+            kind: "Branch",
+            cases: unwrapBranchCases({
+                Some: {
+                    kind: "Chain",
+                    first: action,
+                    rest: {
+                        kind: "Invoke",
+                        handler: {
+                            kind: "Builtin",
+                            builtin: { kind: "Tag", value: "Some" },
+                        },
+                    },
+                },
+                None: {
+                    kind: "Invoke",
+                    handler: { kind: "Builtin", builtin: { kind: "Tag", value: "None" } },
+                },
+            }),
+        },
+    });
+}
+function mapErrMethod(action) {
+    // Desugars to: self.then(branch({ Ok: tag("Ok"), Err: pipe(action, tag("Err")) }))
+    return typedAction({
+        kind: "Chain",
+        first: this,
+        rest: {
+            kind: "Branch",
+            cases: unwrapBranchCases({
+                Ok: {
+                    kind: "Invoke",
+                    handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Ok" } },
+                },
+                Err: {
+                    kind: "Chain",
+                    first: action,
+                    rest: {
+                        kind: "Invoke",
+                        handler: {
+                            kind: "Builtin",
+                            builtin: { kind: "Tag", value: "Err" },
+                        },
+                    },
+                },
+            }),
+        },
+    });
+}
+function unwrapOrMethod(defaultAction) {
+    // Desugars to: self.then(branch({ Ok: identity(), Err: defaultAction }))
+    return typedAction({
+        kind: "Chain",
+        first: this,
+        rest: {
+            kind: "Branch",
+            cases: unwrapBranchCases({
+                Ok: {
+                    kind: "Invoke",
+                    handler: { kind: "Builtin", builtin: { kind: "Identity" } },
+                },
+                Err: defaultAction,
+            }),
+        },
+    });
+}
+/**
+ * Attach `.then()` and `.forEach()` methods to a plain Action object.
+ * Methods are non-enumerable: invisible to JSON.stringify and toEqual.
+ */
+export function typedAction(action) {
+    if (!("then" in action)) {
+        Object.defineProperties(action, {
+            then: { value: thenMethod, configurable: true },
+            forEach: { value: forEachMethod, configurable: true },
+            branch: { value: branchMethod, configurable: true },
+            flatten: { value: flattenMethod, configurable: true },
+            drop: { value: dropMethod, configurable: true },
+            tag: { value: tagMethod, configurable: true },
+            get: { value: getMethod, configurable: true },
+            augment: { value: augmentMethod, configurable: true },
+            merge: { value: mergeMethod, configurable: true },
+            pick: { value: pickMethod, configurable: true },
+            mapOption: { value: mapOptionMethod, configurable: true },
+            mapErr: { value: mapErrMethod, configurable: true },
+            unwrapOr: { value: unwrapOrMethod, configurable: true },
+        });
+    }
+    return action;
+}
+// ---------------------------------------------------------------------------
+// Combinators
+// ---------------------------------------------------------------------------
+export { pipe } from "./pipe.js";
+export { chain } from "./chain.js";
+export { all } from "./all.js";
+export { bind, bindInput } from "./bind.js";
+export { defineRecursiveFunctions } from "./recursive.js";
+export { resetEffectIdCounter } from "./effect-id.js";
+import { allocateRestartHandlerId, } from "./effect-id.js";
+export { tryCatch } from "./try-catch.js";
+export { race, sleep, withTimeout } from "./race.js";
+export function forEach(action) {
+    return typedAction({ kind: "ForEach", action: action });
+}
+/**
+ * Insert ExtractField("value") before each case handler in a branch.
+ * This implements auto-unwrapping: the engine dispatches on `kind`, then
+ * extracts `value` before passing to the handler. Case handlers receive
+ * the payload directly, not the full `{ kind, value }` variant.
+ */
+function unwrapBranchCases(cases) {
+    const unwrapped = {};
+    for (const key of Object.keys(cases)) {
+        unwrapped[key] = {
+            kind: "Chain",
+            first: {
+                kind: "Invoke",
+                handler: {
+                    kind: "Builtin",
+                    builtin: { kind: "ExtractField", value: "value" },
+                },
+            },
+            rest: cases[key],
+        };
+    }
+    return unwrapped;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function branch(cases) {
+    return typedAction({ kind: "Branch", cases: unwrapBranchCases(cases) });
+}
+// ---------------------------------------------------------------------------
+// Shared AST constants for control flow compilation
+// ---------------------------------------------------------------------------
+const EXTRACT_PAYLOAD = {
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "ExtractIndex", value: 0 } },
+};
+const TAG_CONTINUE = {
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Continue" } },
+};
+export const TAG_BREAK = {
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Break" } },
+};
+export const IDENTITY = {
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "Identity" } },
+};
+// ---------------------------------------------------------------------------
+// recur — restart body primitive
+// ---------------------------------------------------------------------------
+/**
+ * Restartable scope. The body callback receives `restart`, a TypedAction that
+ * re-executes the body from the beginning with a new input value.
+ *
+ * If the body completes normally → output is TOut.
+ * If restart fires → body re-executes with the restarted value.
+ *
+ * Compiled form: `RestartHandle(id, ExtractIndex(0), body)`
+ */
+export function recur(bodyFn) {
+    const restartHandlerId = allocateRestartHandlerId();
+    const restartAction = typedAction({
+        kind: "RestartPerform",
+        restart_handler_id: restartHandlerId,
+    });
+    const body = bodyFn(restartAction);
+    return typedAction({
+        kind: "RestartHandle",
+        restart_handler_id: restartHandlerId,
+        body,
+        handler: EXTRACT_PAYLOAD,
+    });
+}
+// ---------------------------------------------------------------------------
+// earlyReturn — exit scope primitive (built on restart + Branch)
+// ---------------------------------------------------------------------------
+/**
+ * Early return scope. The body callback receives `earlyReturn`, a TypedAction
+ * that exits the scope immediately with the returned value.
+ *
+ * If the body completes normally → output is TOut.
+ * If earlyReturn fires → output is TEarlyReturn.
+ * Combined output: TEarlyReturn | TOut.
+ *
+ * Built on the restart mechanism: input is tagged Continue, body runs inside
+ * a Branch. earlyReturn tags with Break and performs — the handler restarts
+ * the body, Branch takes the Break path, and the value exits.
+ */
+export function earlyReturn(bodyFn) {
+    const restartHandlerId = allocateRestartHandlerId();
+    const earlyReturnAction = typedAction({
+        kind: "Chain",
+        first: TAG_BREAK,
+        rest: { kind: "RestartPerform", restart_handler_id: restartHandlerId },
+    });
+    const body = bodyFn(earlyReturnAction);
+    return typedAction(buildRestartBranchAction(restartHandlerId, body, IDENTITY));
+}
+// ---------------------------------------------------------------------------
+// loop — iterative restart with break
+// ---------------------------------------------------------------------------
+/**
+ * Build the restart+branch compiled form:
+ * `Chain(Tag("Continue"), RestartHandle(id, ExtractIndex(0), Branch({ Continue: continueArm, Break: breakArm })))`
+ *
+ * Input is tagged Continue so the Branch enters the continueArm on first execution.
+ * Continue tag → restart → re-enters continueArm. Break tag → restart → runs breakArm, exits `RestartHandle`.
+ *
+ * Used by earlyReturn, loop, tryCatch, and race.
+ */
+export function buildRestartBranchAction(restartHandlerId, continueArm, breakArm) {
+    return {
+        kind: "Chain",
+        first: TAG_CONTINUE,
+        rest: {
+            kind: "RestartHandle",
+            restart_handler_id: restartHandlerId,
+            body: {
+                kind: "Branch",
+                cases: unwrapBranchCases({
+                    Continue: continueArm,
+                    Break: breakArm,
+                }),
+            },
+            handler: EXTRACT_PAYLOAD,
+        },
+    };
+}
+/**
+ * Iterative loop. The body callback receives `recur` and `done`:
+ * - `recur`: restart the loop with a new input
+ * - `done`: exit the loop with the break value
+ *
+ * Both are TypedAction values (not functions), consistent with throwError in tryCatch.
+ *
+ * Compiles to `RestartHandle`/`RestartPerform`/Branch — same effect substrate as tryCatch and earlyReturn.
+ */
+export function loop(bodyFn) {
+    const restartHandlerId = allocateRestartHandlerId();
+    const perform = {
+        kind: "RestartPerform",
+        restart_handler_id: restartHandlerId,
+    };
+    const recurAction = typedAction({
+        kind: "Chain",
+        first: TAG_CONTINUE,
+        rest: perform,
+    });
+    const doneAction = typedAction({
+        kind: "Chain",
+        first: TAG_BREAK,
+        rest: perform,
+    });
+    const body = bodyFn(recurAction, doneAction);
+    return typedAction(buildRestartBranchAction(restartHandlerId, body, IDENTITY));
+}
+// ---------------------------------------------------------------------------
+// Config builders
+// ---------------------------------------------------------------------------
+/** Simple config factory. */
+export function config(workflow) {
+    return { workflow };
+}

package/dist/bind.d.ts

@@ -0,0 +1,62 @@
+import { type Action, type ExtractInput, type ExtractOutput, type TypedAction } from "./ast.js";
+/**
+ * A typed reference to a bound value. Output is `TValue`.
+ *
+ * Use `.then()` (not `pipe()`) when chaining a VarRef into a generic
+ * action like `pick` or `extractField` — pipe overloads can't infer
+ * the generic's type parameter from the VarRef's output.
+ */
+export type VarRef<TValue> = TypedAction<never, TValue>;
+/**
+ * Maps each binding's output type to a VarRef. TypeScript resolves
+ * ExtractOutput from each binding expression.
+ *
+ * Constraint is `Action[]` (not `Pipeable<any, any>[]`) because
+ * `TypedAction<never, X>` (e.g. from `constant()`) fails the invariant
+ * `__in` check against `Pipeable<any, any>` on the 9-variant
+ * Action union. Using raw `Action[]` avoids the phantom field
+ * assignability issue while `ExtractOutput` still extracts the correct
+ * output type from the phantom fields on the concrete types.
+ */
+export type InferVarRefs<TBindings extends Action[]> = {
+    [K in keyof TBindings]: VarRef<ExtractOutput<TBindings[K]>>;
+};
+/**
+ * Bind concurrent values as VarRefs available throughout the body.
+ *
+ * All bindings are actions (Pipeable) evaluated concurrently with the
+ * pipeline input. The body callback receives an array of VarRefs,
+ * one per binding.
+ *
+ * Compiles to:
+ *   Chain(
+ *     All(...bindings, Identity),
+ *     ResumeHandle(r0, readVar(0),
+ *       ResumeHandle(r1, readVar(1),
+ *         Chain(ExtractIndex(N), body)
+ *       )
+ *     )
+ *   )
+ */
+/**
+ * Constraint for the body callback return type. Only requires the output
+ * phantom fields — omits `__in` and `__in_co` so that body actions with
+ * `In = never` (e.g. pipelines starting from a VarRef) are assignable.
+ */
+type BodyResult<TOut> = Action & {
+    __out?: () => TOut;
+    __out_contra?: (output: TOut) => void;
+};
+export declare function bind<TBindings extends Action[], TOut>(bindings: [...TBindings], body: (vars: InferVarRefs<TBindings>) => BodyResult<TOut>): TypedAction<ExtractInput<TBindings[number]>, TOut>;
+/**
+ * Convenience wrapper for the common pattern of capturing the pipeline
+ * input as a VarRef. The body's pipeline input is `never` — the input
+ * is dropped, so the body must access it through the VarRef.
+ *
+ * Sugar for: `bind([identity()], ([input]) => pipe(drop, body(input)))`
+ *
+ * TOut defaults to `any` so callers can specify just TIn:
+ *   bindInput<FileEntry>((entry) => ...)
+ */
+export declare function bindInput<TIn, TOut = any>(body: (input: VarRef<TIn>) => BodyResult<TOut>): TypedAction<TIn, TOut>;
+export {};

package/dist/bind.js

@@ -0,0 +1,106 @@
+import { typedAction, } from "./ast.js";
+import { identity, drop } from "./builtins.js";
+import { allocateResumeHandlerId } from "./effect-id.js";
+import { pipe } from "./pipe.js";
+function createVarRef(resumeHandlerId) {
+    return typedAction({
+        kind: "ResumePerform",
+        resume_handler_id: resumeHandlerId,
+    });
+}
+// ---------------------------------------------------------------------------
+// readVar — handler DAG for the nth binding
+// ---------------------------------------------------------------------------
+/**
+ * Returns an action that extracts the nth value from the ResumeHandle's
+ * state tuple and passes state through unchanged. When a ResumePerform
+ * fires, the engine calls the handler with `[payload, state]`. For bind,
+ * `state` (index 1) is the full All output tuple. The handler produces
+ * `[state[n], state]` — value is state[n], new_state is state (unchanged).
+ *
+ * Expanded AST: All(Chain(ExtractIndex(1), ExtractIndex(n)), ExtractIndex(1))
+ */
+function readVar(n) {
+    return {
+        kind: "All",
+        actions: [
+            {
+                kind: "Chain",
+                first: {
+                    kind: "Invoke",
+                    handler: {
+                        kind: "Builtin",
+                        builtin: { kind: "ExtractIndex", value: 1 },
+                    },
+                },
+                rest: {
+                    kind: "Invoke",
+                    handler: {
+                        kind: "Builtin",
+                        builtin: { kind: "ExtractIndex", value: n },
+                    },
+                },
+            },
+            {
+                kind: "Invoke",
+                handler: {
+                    kind: "Builtin",
+                    builtin: { kind: "ExtractIndex", value: 1 },
+                },
+            },
+        ],
+    };
+}
+export function bind(bindings, body) {
+    // 1. Gensym one resumeHandlerId per binding.
+    const resumeHandlerIds = bindings.map(() => allocateResumeHandlerId());
+    // 2. Create VarRefs (ResumePerform nodes) for each binding.
+    const varRefs = resumeHandlerIds.map((id) => createVarRef(id));
+    // 3. Invoke the body callback with the VarRefs.
+    const bodyAction = body(varRefs);
+    // 4. Build nested Handles from inside out.
+    //    Innermost: extract pipeline_input (last All element) → user body
+    const pipelineInputIndex = bindings.length;
+    let inner = {
+        kind: "Chain",
+        first: {
+            kind: "Invoke",
+            handler: {
+                kind: "Builtin",
+                builtin: { kind: "ExtractIndex", value: pipelineInputIndex },
+            },
+        },
+        rest: bodyAction,
+    };
+    for (let i = resumeHandlerIds.length - 1; i >= 0; i--) {
+        inner = {
+            kind: "ResumeHandle",
+            resume_handler_id: resumeHandlerIds[i],
+            handler: readVar(i),
+            body: inner,
+        };
+    }
+    // 5. All(...bindings, identity()) → nested Handles
+    const allActions = [...bindings.map((b) => b), identity];
+    return typedAction({
+        kind: "Chain",
+        first: { kind: "All", actions: allActions },
+        rest: inner,
+    });
+}
+// ---------------------------------------------------------------------------
+// bindInput — bind the pipeline input
+// ---------------------------------------------------------------------------
+/**
+ * Convenience wrapper for the common pattern of capturing the pipeline
+ * input as a VarRef. The body's pipeline input is `never` — the input
+ * is dropped, so the body must access it through the VarRef.
+ *
+ * Sugar for: `bind([identity()], ([input]) => pipe(drop, body(input)))`
+ *
+ * TOut defaults to `any` so callers can specify just TIn:
+ *   bindInput<FileEntry>((entry) => ...)
+ */
+export function bindInput(body) {
+    return bind([identity], ([input]) => pipe(drop, body(input)));
+}