@barnum/barnum 0.2.3 → 0.3.0

package/cli.cjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+"use strict";
+
+const { execFileSync } = require("child_process");
+const path = require("path");
+const os = require("os");
+const fs = require("fs");
+
+const platform = os.platform();
+const arch = os.arch();
+
+let binaryName = "barnum";
+let artifactDir;
+
+if (platform === "darwin" && arch === "arm64") artifactDir = "macos-arm64";
+else if (platform === "darwin") artifactDir = "macos-x64";
+else if (platform === "linux" && arch === "arm64") artifactDir = "linux-arm64";
+else if (platform === "linux") artifactDir = "linux-x64";
+else if (platform === "win32") { artifactDir = "win-x64"; binaryName = "barnum.exe"; }
+else { console.error(`Unsupported platform: ${platform}-${arch}`); process.exit(1); }
+
+const binaryPath = path.join(__dirname, "artifacts", artifactDir, binaryName);
+
+if (!fs.existsSync(binaryPath)) {
+  console.error(`Binary not found: ${binaryPath}`);
+  process.exit(1);
+}
+
+try {
+  execFileSync(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+} catch (e) {
+  process.exit(e.status || 1);
+}

package/dist/all.d.ts

@@ -0,0 +1,12 @@
+import { type Pipeable, type TypedAction } from "./ast.js";
+export declare function all(): TypedAction<any, []>;
+export declare function all<In, O1>(a1: Pipeable<In, O1>): TypedAction<In, [O1]>;
+export declare function all<In, O1, O2>(a1: Pipeable<In, O1>, a2: Pipeable<In, O2>): TypedAction<In, [O1, O2]>;
+export declare function all<In, O1, O2, O3>(a1: Pipeable<In, O1>, a2: Pipeable<In, O2>, a3: Pipeable<In, O3>): TypedAction<In, [O1, O2, O3]>;
+export declare function all<In, O1, O2, O3, O4>(a1: Pipeable<In, O1>, a2: Pipeable<In, O2>, a3: Pipeable<In, O3>, a4: Pipeable<In, O4>): TypedAction<In, [O1, O2, O3, O4]>;
+export declare function all<In, O1, O2, O3, O4, O5>(a1: Pipeable<In, O1>, a2: Pipeable<In, O2>, a3: Pipeable<In, O3>, a4: Pipeable<In, O4>, a5: Pipeable<In, O5>): TypedAction<In, [O1, O2, O3, O4, O5]>;
+export declare function all<In, O1, O2, O3, O4, O5, O6>(a1: Pipeable<In, O1>, a2: Pipeable<In, O2>, a3: Pipeable<In, O3>, a4: Pipeable<In, O4>, a5: Pipeable<In, O5>, a6: Pipeable<In, O6>): TypedAction<In, [O1, O2, O3, O4, O5, O6]>;
+export declare function all<In, O1, O2, O3, O4, O5, O6, O7>(a1: Pipeable<In, O1>, a2: Pipeable<In, O2>, a3: Pipeable<In, O3>, a4: Pipeable<In, O4>, a5: Pipeable<In, O5>, a6: Pipeable<In, O6>, a7: Pipeable<In, O7>): TypedAction<In, [O1, O2, O3, O4, O5, O6, O7]>;
+export declare function all<In, O1, O2, O3, O4, O5, O6, O7, O8>(a1: Pipeable<In, O1>, a2: Pipeable<In, O2>, a3: Pipeable<In, O3>, a4: Pipeable<In, O4>, a5: Pipeable<In, O5>, a6: Pipeable<In, O6>, a7: Pipeable<In, O7>, a8: Pipeable<In, O8>): TypedAction<In, [O1, O2, O3, O4, O5, O6, O7, O8]>;
+export declare function all<In, O1, O2, O3, O4, O5, O6, O7, O8, O9>(a1: Pipeable<In, O1>, a2: Pipeable<In, O2>, a3: Pipeable<In, O3>, a4: Pipeable<In, O4>, a5: Pipeable<In, O5>, a6: Pipeable<In, O6>, a7: Pipeable<In, O7>, a8: Pipeable<In, O8>, a9: Pipeable<In, O9>): TypedAction<In, [O1, O2, O3, O4, O5, O6, O7, O8, O9]>;
+export declare function all<In, O1, O2, O3, O4, O5, O6, O7, O8, O9, O10>(a1: Pipeable<In, O1>, a2: Pipeable<In, O2>, a3: Pipeable<In, O3>, a4: Pipeable<In, O4>, a5: Pipeable<In, O5>, a6: Pipeable<In, O6>, a7: Pipeable<In, O7>, a8: Pipeable<In, O8>, a9: Pipeable<In, O9>, a10: Pipeable<In, O10>): TypedAction<In, [O1, O2, O3, O4, O5, O6, O7, O8, O9, O10]>;

package/dist/all.js

@@ -0,0 +1,8 @@
+import { typedAction, } from "./ast.js";
+import { constant } from "./builtins.js";
+export function all(...actions) {
+    if (actions.length === 0) {
+        return constant([]);
+    }
+    return typedAction({ kind: "All", actions });
+}

package/dist/ast.d.ts

@@ -0,0 +1,375 @@
+import type { JSONSchema7 } from "json-schema";
+export type Action = InvokeAction | ChainAction | ForEachAction | AllAction | BranchAction | ResumeHandleAction | ResumePerformAction | RestartHandleAction | RestartPerformAction;
+export interface InvokeAction {
+    kind: "Invoke";
+    handler: HandlerKind;
+}
+export interface ChainAction {
+    kind: "Chain";
+    first: Action;
+    rest: Action;
+}
+export interface ForEachAction {
+    kind: "ForEach";
+    action: Action;
+}
+export interface AllAction {
+    kind: "All";
+    actions: Action[];
+}
+export interface BranchAction {
+    kind: "Branch";
+    cases: Record<string, Action>;
+}
+export interface ResumeHandleAction {
+    kind: "ResumeHandle";
+    resume_handler_id: ResumeHandlerId;
+    body: Action;
+    handler: Action;
+}
+export interface ResumePerformAction {
+    kind: "ResumePerform";
+    resume_handler_id: ResumeHandlerId;
+}
+export interface RestartHandleAction {
+    kind: "RestartHandle";
+    restart_handler_id: RestartHandlerId;
+    body: Action;
+    handler: Action;
+}
+export interface RestartPerformAction {
+    kind: "RestartPerform";
+    restart_handler_id: RestartHandlerId;
+}
+export type HandlerKind = TypeScriptHandler | BuiltinHandler;
+export interface TypeScriptHandler {
+    kind: "TypeScript";
+    module: string;
+    func: string;
+    input_schema?: JSONSchema7;
+    output_schema?: JSONSchema7;
+}
+export interface BuiltinHandler {
+    kind: "Builtin";
+    builtin: BuiltinKind;
+}
+export type BuiltinKind = {
+    kind: "Constant";
+    value: unknown;
+} | {
+    kind: "Identity";
+} | {
+    kind: "Drop";
+} | {
+    kind: "Tag";
+    value: string;
+} | {
+    kind: "Merge";
+} | {
+    kind: "Flatten";
+} | {
+    kind: "ExtractField";
+    value: string;
+} | {
+    kind: "ExtractIndex";
+    value: number;
+} | {
+    kind: "Pick";
+    value: string[];
+} | {
+    kind: "CollectSome";
+} | {
+    kind: "Sleep";
+    value: number;
+};
+/**
+ * When TIn is `never` (handler ignores input), produce `any` so the
+ * combinator/pipe can sit in any pipeline position.
+ */
+export type PipeIn<T> = [T] extends [never] ? any : T;
+export interface Config {
+    workflow: Action;
+}
+type UnionToIntersection<TUnion> = (TUnion extends any ? (x: TUnion) => void : never) extends (x: infer TIntersection) => void ? TIntersection : never;
+/** Merge a tuple of objects into a single intersection type. */
+export type MergeTuple<TTuple> = TTuple extends unknown[] ? UnionToIntersection<TTuple[number]> : never;
+/**
+ * An action with tracked input/output types. Phantom fields enforce invariance
+ * and are never set at runtime — they exist only for the TypeScript compiler.
+ *
+ * Each type variable gets a contravariant + covariant field pair:
+ *   In:  __in (contravariant) + __in_co (covariant) → invariant
+ *   Out: __out (covariant) + __out_contra (contravariant) → invariant
+ *
+ * This ensures exact type matching at every pipeline connection point.
+ * Data crosses serialization boundaries to handlers in arbitrary languages
+ * (Rust, Python, etc.), so extra/missing fields are runtime errors.
+ */
+export type TypedAction<In = unknown, Out = unknown, Refs extends string = never> = Action & {
+    __in?: (input: In) => void;
+    __in_co?: In;
+    __out?: () => Out;
+    __out_contra?: (output: Out) => void;
+    __refs?: {
+        _brand: Refs;
+    };
+    /** Chain this action with another. `a.then(b)` ≡ `chain(a, b)`. */
+    then<TNext>(next: Pipeable<Out, TNext>): TypedAction<In, TNext, Refs>;
+    /** Apply an action to each element of an array output. `a.forEach(b)` ≡ `a.then(forEach(b))`. */
+    forEach<TIn, TElement, TNext, TRefs extends string>(this: TypedAction<TIn, TElement[], TRefs>, action: Pipeable<TElement, TNext>): TypedAction<TIn, TNext[], TRefs>;
+    /** Dispatch on a tagged union output. Auto-unwraps `value` before each case handler. */
+    branch<TCases extends {
+        [K in BranchKeys<Out>]: CaseHandler<BranchPayload<Out, K>, unknown>;
+    }>(cases: [BranchKeys<Out>] extends [never] ? never : TCases): TypedAction<In, ExtractOutput<TCases[keyof TCases & string]>, Refs>;
+    /** Flatten a nested array output. `a.flatten()` ≡ `pipe(a, flatten())`. */
+    flatten(): TypedAction<In, Out extends (infer TElement)[][] ? TElement[] : Out, Refs>;
+    /** Discard output. `a.drop()` ≡ `pipe(a, drop)`. */
+    drop(): TypedAction<In, never, Refs>;
+    /** Wrap output as a tagged union member. Requires full variant map TDef so __def is carried. */
+    tag<TDef extends Record<string, unknown>, TKind extends keyof TDef & string>(kind: TKind): TypedAction<In, TaggedUnion<TDef>, Refs>;
+    /** Extract a field from the output object. `a.get("name")` ≡ `pipe(a, extractField("name"))`. */
+    get<TField extends keyof Out & string>(field: TField): TypedAction<In, Out[TField], Refs>;
+    /**
+     * Run this sub-pipeline, then merge its output back into the original input.
+     * `pipe(extractField("x"), transform).augment()` takes `In`, runs the
+     * sub-pipeline to get `Out`, and returns `In & Out`.
+     *
+     * Unlike the standalone `augment()` function, the postfix form has access
+     * to `In` so the intersection types correctly.
+     */
+    augment(): TypedAction<In, In & Out, Refs>;
+    /** Merge a tuple of objects into a single object. `a.merge()` ≡ `pipe(a, merge())`. */
+    merge(): TypedAction<In, MergeTuple<Out>, Refs>;
+    /** Select fields from the output. `a.pick("x", "y")` ≡ `pipe(a, pick("x", "y"))`. */
+    pick<TKeys extends (keyof Out & string)[]>(...keys: TKeys): TypedAction<In, Pick<Out, TKeys[number]>, Refs>;
+    /**
+     * Transform the Some value inside an Option output. Only callable when
+     * Out is Option<T>. Uses `this` parameter constraint to gate availability.
+     */
+    mapOption<TIn, T, U, TRefs extends string>(this: TypedAction<TIn, Option<T>, TRefs>, action: Pipeable<T, U>): TypedAction<TIn, Option<U>, TRefs>;
+    /**
+     * Transform the Err value of a Result output.
+     * `Result<TValue, TError> → Result<TValue, TErrorOut>`
+     *
+     * Only callable when Out is Result<TValue, TError>.
+     */
+    mapErr<TIn, TValue, TError, TErrorOut>(this: TypedAction<TIn, Result<TValue, TError>, any>, action: Pipeable<TError, TErrorOut>): TypedAction<TIn, Result<TValue, TErrorOut>, Refs>;
+    /**
+     * Unwrap a Result output. If Ok, pass through the value. If Err, apply
+     * the default action. Only callable when Out is Result<TValue, TError>.
+     *
+     * The `this` constraint provides TValue from context, so throw tokens
+     * (Out=never) work without explicit type parameters:
+     *   `handler.unwrapOr(throwError)`
+     *
+     * Uses CaseHandler for defaultAction (covariant output only) so that
+     * `TypedAction<TError, never>` is assignable to `CaseHandler<TError, TValue>`.
+     *
+     * Refs position uses `any` in the `this` constraint to avoid TS
+     * falling back to the constraint bound `string` when Refs = never.
+     * The return type uses the enclosing TypedAction's `Refs` directly.
+     */
+    unwrapOr<TIn, TValue, TError>(this: TypedAction<TIn, Result<TValue, TError>, any>, defaultAction: CaseHandler<TError, TValue>): TypedAction<TIn, TValue, Refs>;
+};
+/**
+ * Parameter type for pipe and combinators. Contains the same phantom fields
+ * as TypedAction but without methods.
+ *
+ * Invariance: Both In and Out are invariant, matching TypedAction:
+ *   In:  __in (contravariant) + __in_co (covariant) → invariant
+ *   Out: __out (covariant) + __out_contra (contravariant) → invariant
+ *
+ * Why no methods: TypedAction's methods (then, branch, etc.) participate in
+ * TS assignability checks in complex, recursive ways that interfere with
+ * generic inference in pipe overloads. Pipeable strips methods so that only
+ * phantom fields drive inference — predictable covariant/contravariant
+ * resolution, with invariance enforced when TS checks candidates from
+ * both sides of a connection.
+ *
+ * TypedAction (with methods) is assignable to Pipeable because Pipeable
+ * only requires a subset of properties.
+ */
+export type Pipeable<In = unknown, Out = unknown> = Action & {
+    __in?: (input: In) => void;
+    __in_co?: In;
+    __out?: () => Out;
+    __out_contra?: (output: Out) => void;
+};
+/**
+ * Contravariant-only input checking for branch case handler positions.
+ *
+ * Omits __in_co (covariant input) and __out_contra (contravariant output)
+ * compared to TypedAction/Pipeable. This gives:
+ *   In:  contravariant only (via __in)
+ *   Out: covariant only (via __out)
+ *
+ * Why contravariant input: a handler that accepts `unknown` (like drop)
+ * can handle any variant. (input: unknown) => void is assignable to
+ * (input: HasErrors) => void because HasErrors extends unknown.
+ *
+ * Why covariant output: the constraint doesn't restrict output types —
+ * they're inferred from the actual case handlers via ExtractOutput.
+ * TypedAction's invariant __out_contra with Out=unknown would
+ * reject any handler with a specific output type, so we omit it.
+ *
+ * TypedAction is assignable to CaseHandler because CaseHandler only
+ * requires a subset of TypedAction's phantom fields.
+ */
+type CaseHandler<TIn = unknown, TOut = unknown> = Action & {
+    __in?: (input: TIn) => void;
+    __out?: () => TOut;
+};
+/**
+ * Standard tagged union type. Each variant is `{ kind: K; value: TDef[K] }`
+ * with a phantom `__def` field carrying the full variant map. The __def
+ * field enables `.branch()` to decompose the union via simple indexing
+ * (`keyof ExtractDef<Out>` and `ExtractDef<Out>[K]`) instead of
+ * conditional types (`KindOf<Out>` and `Extract<Out, { kind: K }>`).
+ */
+type VoidToNull<T> = 0 extends 1 & T ? T : [T] extends [never] ? never : [T] extends [void] ? null : T;
+export type TaggedUnion<TDef extends Record<string, unknown>> = {
+    [K in keyof TDef & string]: {
+        kind: K;
+        value: VoidToNull<TDef[K]>;
+        __def?: TDef;
+    };
+}[keyof TDef & string];
+/** Extract the variant map definition from a tagged union's phantom __def. */
+export type ExtractDef<T> = T extends {
+    __def?: infer D;
+} ? D : never;
+export type OptionDef<T> = {
+    Some: T;
+    None: void;
+};
+export type Option<T> = TaggedUnion<OptionDef<T>>;
+export type ResultDef<TValue, TError> = {
+    Ok: TValue;
+    Err: TError;
+};
+export type Result<TValue, TError> = TaggedUnion<ResultDef<TValue, TError>>;
+/** Extract all `kind` string literals from a discriminated union. */
+type KindOf<T> = T extends {
+    kind: infer K extends string;
+} ? K : never;
+/** Extract the `value` field from a `{ kind, value }` variant. Falls back to T if no `value` field. */
+type UnwrapVariant<T> = T extends {
+    value: infer V;
+} ? V : T;
+/**
+ * Branch case keys: prefer ExtractDef (simple keyof indexing) when the
+ * output carries __def. Falls back to KindOf (conditional type) for
+ * outputs without __def.
+ */
+type BranchKeys<Out> = [ExtractDef<Out>] extends [never] ? KindOf<Out> : keyof ExtractDef<Out> & string;
+/**
+ * Branch case payload: prefer ExtractDef[K] (simple indexing) when available.
+ * Falls back to UnwrapVariant<Extract<Out, { kind: K }>> for outputs without __def.
+ */
+type BranchPayload<Out, K extends string> = [ExtractDef<Out>] extends [never] ? UnwrapVariant<Extract<Out, {
+    kind: K;
+}>> : K extends keyof ExtractDef<Out> ? VoidToNull<ExtractDef<Out>[K]> : never;
+/**
+ * Attach `.then()` and `.forEach()` methods to a plain Action object.
+ * Methods are non-enumerable: invisible to JSON.stringify and toEqual.
+ */
+export declare function typedAction<In = unknown, Out = unknown, Refs extends string = never>(action: Action): TypedAction<In, Out, Refs>;
+/**
+ * Extract the input type from a TypedAction.
+ *
+ * Uses direct phantom field extraction (not full TypedAction matching) to
+ * avoid the `TypedAction<any, any, any>` constraint which fails for In=never
+ * due to __in contravariance.
+ */
+export type ExtractInput<T> = T extends {
+    __in?: (input: infer In) => void;
+} ? In : never;
+/**
+ * Extract the output type from a TypedAction.
+ *
+ * Uses direct phantom field extraction to avoid constraint issues.
+ */
+export type ExtractOutput<T> = T extends {
+    __out?: () => infer Out;
+} ? Out : never;
+export { pipe } from "./pipe.js";
+export { chain } from "./chain.js";
+export { all } from "./all.js";
+export { bind, bindInput, type VarRef, type InferVarRefs } from "./bind.js";
+export { defineRecursiveFunctions } from "./recursive.js";
+export { resetEffectIdCounter } from "./effect-id.js";
+import { type RestartHandlerId, type ResumeHandlerId } from "./effect-id.js";
+export { tryCatch } from "./try-catch.js";
+export { race, sleep, withTimeout } from "./race.js";
+export declare function forEach<In, Out>(action: Pipeable<In, Out>): TypedAction<In[], Out[]>;
+/**
+ * Compute the branch input type from its cases. For each case key K,
+ * wraps the case handler's input type in `{ kind: K; value: T }`.
+ * This ensures the branch input is a proper tagged union matching the
+ * `{ kind, value }` convention.
+ *
+ * Example: `BranchInput<{ Yes: TypedAction<number, ...>, No: TypedAction<string, ...> }>`
+ *        = `{ kind: "Yes"; value: number } | { kind: "No"; value: string }`
+ *
+ * When a case handler uses `any` as input, the wrapping produces
+ * `{ kind: K; value: any }`, which is the correct escape hatch.
+ */
+export type BranchInput<TCases> = {
+    [K in keyof TCases & string]: {
+        kind: K;
+        value: ExtractInput<TCases[K]>;
+    };
+}[keyof TCases & string];
+export declare function branch<TCases extends Record<string, Action>>(cases: TCases): TypedAction<BranchInput<TCases>, ExtractOutput<TCases[keyof TCases & string]>>;
+type LoopResultDef<TContinue, TBreak> = {
+    Continue: TContinue;
+    Break: TBreak;
+};
+export type LoopResult<TContinue, TBreak> = TaggedUnion<LoopResultDef<TContinue, TBreak>>;
+export declare const TAG_BREAK: Action;
+export declare const IDENTITY: Action;
+/**
+ * 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 declare function recur<TIn = never, TOut = any>(bodyFn: (restart: TypedAction<TIn, never>) => Pipeable<TIn, TOut>): TypedAction<PipeIn<TIn>, TOut>;
+/**
+ * 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 declare function earlyReturn<TEarlyReturn = never, TIn = any, TOut = any>(bodyFn: (earlyReturn: TypedAction<TEarlyReturn, never>) => Pipeable<TIn, TOut>): TypedAction<TIn, TEarlyReturn | TOut>;
+/**
+ * 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 declare function buildRestartBranchAction(restartHandlerId: RestartHandlerId, continueArm: Action, breakArm: Action): Action;
+/**
+ * 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 declare function loop<TBreak = never, TIn = never>(bodyFn: (recur: TypedAction<TIn, never>, done: TypedAction<VoidToNull<TBreak>, never>) => Pipeable<TIn, never>): TypedAction<PipeIn<TIn>, VoidToNull<TBreak>>;
+/** Simple config factory. */
+export declare function config(workflow: Action): Config;