@barnum/barnum 0.2.3 → 0.4.0

package/src/option.ts

@@ -0,0 +1,199 @@
+import {
+  type Option as OptionT,
+  type OptionDef,
+  type Pipeable,
+  type Result as ResultT,
+  type TypedAction,
+  toAction,
+  typedAction,
+  branch,
+} from "./ast.js";
+import { chain } from "./chain.js";
+import {
+  constant,
+  drop,
+  getIndex,
+  identity,
+  panic,
+  splitFirst,
+  splitLast,
+  tag,
+} from "./builtins/index.js";
+import { Result } from "./result.js";
+
+// ---------------------------------------------------------------------------
+// Option namespace — combinators for Option<T> tagged unions
+// ---------------------------------------------------------------------------
+
+/**
+ * Option namespace. All combinators produce TypedAction AST nodes that
+ * desugar to branch + existing builtins, except collect which uses the
+ * CollectSome builtin.
+ */
+export const Option = {
+  /** Tag combinator: wrap value as `Option.Some`. `T → Option<T>` */
+  some<T>(): TypedAction<T, OptionT<T>> {
+    return tag<"Option", OptionDef<T>, "Some">("Some", "Option");
+  },
+  /** Tag combinator: wrap value as `Option.None`. `void → Option<T>` */
+  none<T>(): TypedAction<void, OptionT<T>> {
+    return tag<"Option", OptionDef<T>, "None">("None", "Option");
+  },
+
+  /** Transform the Some value. `Option<T> → Option<U>` */
+  map<T, U>(action: Pipeable<T, U>): TypedAction<OptionT<T>, OptionT<U>> {
+    return branch({
+      Some: chain(action, Option.some<U>()),
+      None: Option.none<U>(),
+    }) as TypedAction<OptionT<T>, OptionT<U>>;
+  },
+
+  /**
+   * Monadic bind (flatMap). If Some, pass the value to action which
+   * returns Option<U>. If None, stay None. `Option<T> → Option<U>`
+   */
+  andThen<T, U>(
+    action: Pipeable<T, OptionT<U>>,
+  ): TypedAction<OptionT<T>, OptionT<U>> {
+    return branch({
+      Some: action,
+      None: Option.none<U>(),
+    }) as TypedAction<OptionT<T>, OptionT<U>>;
+  },
+
+  /**
+   * Extract the Some value or panic. `Option<T> → T`
+   *
+   * Panics (fatal, not caught by tryCatch) if the value is None.
+   */
+  unwrap<T>(): TypedAction<OptionT<T>, T> {
+    return branch({
+      Some: identity<T>(),
+      None: panic("called unwrap on None"),
+    }) as TypedAction<OptionT<T>, T>;
+  },
+
+  /**
+   * Extract the Some value or produce a default from an action.
+   * `Option<T> → T`
+   */
+  unwrapOr<T>(defaultAction: Pipeable<void, T>): TypedAction<OptionT<T>, T> {
+    return branch({
+      Some: identity<T>(),
+      None: defaultAction,
+    }) as TypedAction<OptionT<T>, T>;
+  },
+
+  /**
+   * Conditional keep. If Some, pass value to predicate which returns
+   * Option<T>. If None, stay None. `Option<T> → Option<T>`
+   */
+  filter<T>(
+    predicate: Pipeable<T, OptionT<T>>,
+  ): TypedAction<OptionT<T>, OptionT<T>> {
+    return branch({
+      Some: predicate,
+      None: Option.none<T>(),
+    }) as TypedAction<OptionT<T>, OptionT<T>>;
+  },
+
+  /**
+   * Collect Some values from an array, discarding Nones.
+   * `Option<T>[] → T[]`
+   */
+  collect<T = any>(): TypedAction<OptionT<T>[], T[]> {
+    return typedAction({
+      kind: "Invoke",
+      handler: { kind: "Builtin", builtin: { kind: "CollectSome" } },
+    });
+  },
+
+  /**
+   * Test if the value is Some. `Option<T> → boolean`
+   */
+  isSome<T>(): TypedAction<OptionT<T>, boolean> {
+    return branch({
+      Some: constant<boolean>(true),
+      None: constant<boolean>(false),
+    }) as TypedAction<OptionT<T>, boolean>;
+  },
+
+  /**
+   * Test if the value is None. `Option<T> → boolean`
+   */
+  isNone<T>(): TypedAction<OptionT<T>, boolean> {
+    return branch({
+      Some: constant<boolean>(false),
+      None: constant<boolean>(true),
+    }) as TypedAction<OptionT<T>, boolean>;
+  },
+
+  /**
+   * Swap Option/Result nesting.
+   * `Option<Result<TValue, TError>> → Result<Option<TValue>, TError>`
+   *
+   * - Some(Ok(t))  → Ok(Some(t))
+   * - Some(Err(e)) → Err(e)
+   * - None         → Ok(None)
+   */
+  transpose<TValue, TError>(): TypedAction<
+    OptionT<ResultT<TValue, TError>>,
+    ResultT<OptionT<TValue>, TError>
+  > {
+    return branch({
+      Some: branch({
+        Ok: chain(Option.some<TValue>(), Result.ok<OptionT<TValue>, TError>()),
+        Err: Result.err<OptionT<TValue>, TError>(),
+      }),
+      None: chain(
+        chain(drop, Option.none<TValue>()),
+        Result.ok<OptionT<TValue>, TError>(),
+      ),
+    }) as TypedAction<
+      OptionT<ResultT<TValue, TError>>,
+      ResultT<OptionT<TValue>, TError>
+    >;
+  },
+} as const;
+
+// ---------------------------------------------------------------------------
+// First — extract the first element of an array as Option<TElement>
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the first element of an array.
+ * `readonly TElement[] → Option<TElement>`
+ *
+ * Composes `splitFirst` (which returns `Option<[TElement, TElement[]]>`)
+ * with `Option.map(getIndex(0))` to extract just the element.
+ */
+export function first<TElement>(): TypedAction<
+  readonly TElement[],
+  OptionT<TElement>
+> {
+  return chain(
+    toAction(splitFirst()),
+    toAction(Option.map(toAction(getIndex(0).unwrap()))),
+  ) as TypedAction<readonly TElement[], OptionT<TElement>>;
+}
+
+// ---------------------------------------------------------------------------
+// Last — extract the last element of an array as Option<TElement>
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the last element of an array.
+ * `readonly TElement[] → Option<TElement>`
+ *
+ * Composes `splitLast` (which returns `Option<[TElement[], TElement]>`)
+ * with `Option.map(getIndex(1))` to extract just the element.
+ */
+export function last<TElement>(): TypedAction<
+  readonly TElement[],
+  OptionT<TElement>
+> {
+  return chain(
+    toAction(splitLast()),
+    toAction(Option.map(toAction(getIndex(1).unwrap()))),
+  ) as TypedAction<readonly TElement[], OptionT<TElement>>;
+}

package/src/pipe.ts

@@ -0,0 +1,138 @@
+import {
+  type Action,
+  type PipeIn,
+  type Pipeable,
+  type TypedAction,
+  toAction,
+} from "./ast.js";
+import { chain } from "./chain.js";
+import { identity } from "./builtins/index.js";
+
+export function pipe<TStep1, TStep2>(
+  a1: Pipeable<TStep1, TStep2>,
+): TypedAction<PipeIn<TStep1>, TStep2>;
+export function pipe<TStep1, TStep2, TStep3>(
+  a1: Pipeable<TStep1, TStep2>,
+  a2: Pipeable<TStep2, TStep3>,
+): TypedAction<PipeIn<TStep1>, TStep3>;
+export function pipe<TStep1, TStep2, TStep3, TStep4>(
+  a1: Pipeable<TStep1, TStep2>,
+  a2: Pipeable<TStep2, TStep3>,
+  a3: Pipeable<TStep3, TStep4>,
+): TypedAction<PipeIn<TStep1>, TStep4>;
+export function pipe<TStep1, TStep2, TStep3, TStep4, TStep5>(
+  a1: Pipeable<TStep1, TStep2>,
+  a2: Pipeable<TStep2, TStep3>,
+  a3: Pipeable<TStep3, TStep4>,
+  a4: Pipeable<TStep4, TStep5>,
+): TypedAction<PipeIn<TStep1>, TStep5>;
+export function pipe<TStep1, TStep2, TStep3, TStep4, TStep5, TStep6>(
+  a1: Pipeable<TStep1, TStep2>,
+  a2: Pipeable<TStep2, TStep3>,
+  a3: Pipeable<TStep3, TStep4>,
+  a4: Pipeable<TStep4, TStep5>,
+  a5: Pipeable<TStep5, TStep6>,
+): TypedAction<PipeIn<TStep1>, TStep6>;
+export function pipe<TStep1, TStep2, TStep3, TStep4, TStep5, TStep6, TStep7>(
+  a1: Pipeable<TStep1, TStep2>,
+  a2: Pipeable<TStep2, TStep3>,
+  a3: Pipeable<TStep3, TStep4>,
+  a4: Pipeable<TStep4, TStep5>,
+  a5: Pipeable<TStep5, TStep6>,
+  a6: Pipeable<TStep6, TStep7>,
+): TypedAction<PipeIn<TStep1>, TStep7>;
+export function pipe<
+  TStep1,
+  TStep2,
+  TStep3,
+  TStep4,
+  TStep5,
+  TStep6,
+  TStep7,
+  TStep8,
+>(
+  a1: Pipeable<TStep1, TStep2>,
+  a2: Pipeable<TStep2, TStep3>,
+  a3: Pipeable<TStep3, TStep4>,
+  a4: Pipeable<TStep4, TStep5>,
+  a5: Pipeable<TStep5, TStep6>,
+  a6: Pipeable<TStep6, TStep7>,
+  a7: Pipeable<TStep7, TStep8>,
+): TypedAction<PipeIn<TStep1>, TStep8>;
+export function pipe<
+  TStep1,
+  TStep2,
+  TStep3,
+  TStep4,
+  TStep5,
+  TStep6,
+  TStep7,
+  TStep8,
+  TStep9,
+>(
+  a1: Pipeable<TStep1, TStep2>,
+  a2: Pipeable<TStep2, TStep3>,
+  a3: Pipeable<TStep3, TStep4>,
+  a4: Pipeable<TStep4, TStep5>,
+  a5: Pipeable<TStep5, TStep6>,
+  a6: Pipeable<TStep6, TStep7>,
+  a7: Pipeable<TStep7, TStep8>,
+  a8: Pipeable<TStep8, TStep9>,
+): TypedAction<PipeIn<TStep1>, TStep9>;
+export function pipe<
+  TStep1,
+  TStep2,
+  TStep3,
+  TStep4,
+  TStep5,
+  TStep6,
+  TStep7,
+  TStep8,
+  TStep9,
+  TStep10,
+>(
+  a1: Pipeable<TStep1, TStep2>,
+  a2: Pipeable<TStep2, TStep3>,
+  a3: Pipeable<TStep3, TStep4>,
+  a4: Pipeable<TStep4, TStep5>,
+  a5: Pipeable<TStep5, TStep6>,
+  a6: Pipeable<TStep6, TStep7>,
+  a7: Pipeable<TStep7, TStep8>,
+  a8: Pipeable<TStep8, TStep9>,
+  a9: Pipeable<TStep9, TStep10>,
+): TypedAction<PipeIn<TStep1>, TStep10>;
+export function pipe<
+  TStep1,
+  TStep2,
+  TStep3,
+  TStep4,
+  TStep5,
+  TStep6,
+  TStep7,
+  TStep8,
+  TStep9,
+  TStep10,
+  TStep11,
+>(
+  a1: Pipeable<TStep1, TStep2>,
+  a2: Pipeable<TStep2, TStep3>,
+  a3: Pipeable<TStep3, TStep4>,
+  a4: Pipeable<TStep4, TStep5>,
+  a5: Pipeable<TStep5, TStep6>,
+  a6: Pipeable<TStep6, TStep7>,
+  a7: Pipeable<TStep7, TStep8>,
+  a8: Pipeable<TStep8, TStep9>,
+  a9: Pipeable<TStep9, TStep10>,
+  a10: Pipeable<TStep10, TStep11>,
+): TypedAction<PipeIn<TStep1>, TStep11>;
+export function pipe(...actions: Action[]): Action {
+  if (actions.length === 0) {
+    return identity();
+  }
+  if (actions.length === 1) {
+    return actions[0];
+  }
+  return actions.reduceRight((rest, first) =>
+    toAction(chain(toAction(first), toAction(rest))),
+  );
+}

package/src/race.ts

@@ -0,0 +1,173 @@
+import {
+  type Action,
+  type Pipeable,
+  type Result as ResultT,
+  type TypedAction,
+  toAction,
+  typedAction,
+  buildRestartBranchAction,
+} from "./ast.js";
+import { chain } from "./chain.js";
+import { identity, tag } from "./builtins/index.js";
+import { Result } from "./result.js";
+import {
+  allocateRestartHandlerId,
+  type RestartHandlerId,
+} from "./effect-id.js";
+
+/**
+ * `Chain(Tag("Break"), RestartPerform(id))` — shared by race branches.
+ * The winning branch tags its result as Break, then performs. The handler
+ * restarts the body; Branch takes the Break arm (identity), `RestartHandle` exits.
+ */
+function breakPerform(restartHandlerId: RestartHandlerId): Action {
+  return toAction(
+    chain(toAction(tag("Break", "LoopResult")), {
+      kind: "RestartPerform",
+      restart_handler_id: restartHandlerId,
+    }),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// race — first branch to complete wins, losers cancelled
+// ---------------------------------------------------------------------------
+
+/**
+ * Run multiple actions concurrently. The first to complete wins; losers
+ * are cancelled during `RestartHandle` frame teardown.
+ *
+ * All branches must have the same input and output type (since either
+ * could win).
+ *
+ * Compiled form (restart+Branch, same substrate as loop/earlyReturn):
+ *   `Chain(Tag("Continue"),`
+ *     `RestartHandle(id, GetIndex(0),`
+ *       `Branch({`
+ *         `Continue: All(Chain(a, breakPerform), Chain(b, breakPerform), ...),`
+ *         `Break: identity,`
+ *       `})))`
+ *
+ * First branch to complete tags Break → `RestartPerform` → handler restarts →
+ * Branch takes Break arm → identity → `RestartHandle` exits with winner's value.
+ */
+export function race<TIn, TOut>(
+  ...actions: Pipeable<TIn, TOut>[]
+): TypedAction<TIn, TOut> {
+  const restartHandlerId = allocateRestartHandlerId();
+  const perform = breakPerform(restartHandlerId);
+
+  const branches = actions.map((action) =>
+    toAction(chain(toAction(action), toAction(perform))),
+  );
+
+  const allAction: Action = { kind: "All", actions: branches };
+
+  return typedAction(
+    buildRestartBranchAction(restartHandlerId, allAction, toAction(identity())),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// sleep — Rust builtin that delays for a fixed duration (passthrough)
+// ---------------------------------------------------------------------------
+
+/**
+ * Sleep for a fixed duration, ignoring input and returning void.
+ *
+ * `ms` is baked into the AST at construction time. Executed by the Rust
+ * scheduler via `tokio::time::sleep` — no subprocess spawned.
+ *
+ * To preserve data across a sleep, use `bindInput`.
+ */
+export function sleep(ms: number): TypedAction<any, void> {
+  return typedAction<any, void>({
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "Sleep", ms } },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// dynamicSleep — TypeScript handler for withTimeout (takes ms as input)
+// ---------------------------------------------------------------------------
+
+/** The raw Invoke node for the dynamic sleep handler. */
+const DYNAMIC_SLEEP_INVOKE: Action = {
+  kind: "Invoke",
+  handler: {
+    kind: "TypeScript",
+    module: import.meta.url,
+    func: "dynamicSleep",
+  },
+};
+
+/**
+ * @internal TypeScript handler that takes ms as pipeline input and returns
+ * void after the timer fires. Used by `withTimeout` where the duration
+ * comes from a runtime pipeline, not a build-time constant.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-function
+export function dynamicSleep(): void {}
+Object.defineProperty(dynamicSleep, "__definition", {
+  value: {
+    handle: ({ value }: { value: number }) =>
+      new Promise<void>((resolve) => setTimeout(resolve, value)),
+  },
+  enumerable: false,
+});
+
+// ---------------------------------------------------------------------------
+// withTimeout — race body against sleep, return Result
+// ---------------------------------------------------------------------------
+
+/**
+ * Race the body against a sleep timer. Returns `Result<TOut, void>`:
+ * - Ok(value) if the body completed first
+ * - Err(void) if the timeout fired first
+ *
+ * The `ms` parameter is an AST node that evaluates to the timeout duration
+ * in milliseconds. Use `constant(5000)` for a fixed timeout, or any action
+ * that computes a duration from the pipeline input.
+ *
+ * Built as raw AST rather than through `race()` because each branch wraps
+ * its result differently (Ok vs Err) before the Break+Perform. `race()`
+ * requires homogeneous output types, but withTimeout needs heterogeneous
+ * tagging.
+ *
+ * Same restart+Branch substrate as race: each branch tags Break after
+ * wrapping its result as Ok or Err.
+ */
+export function withTimeout<TIn, TOut>(
+  ms: Pipeable<TIn, number>,
+  body: Pipeable<TIn, TOut>,
+): TypedAction<TIn, ResultT<TOut, void>> {
+  const restartHandlerId = allocateRestartHandlerId();
+  const perform = breakPerform(restartHandlerId);
+
+  // Branch 1: body → Tag("Ok") → Break → RestartPerform
+  const bodyBranch = toAction(
+    chain(
+      toAction(chain(toAction(body), toAction(Result.ok()))),
+      toAction(perform),
+    ),
+  );
+
+  // Branch 2: ms → sleep() → Tag("Err") → Break → RestartPerform
+  const sleepBranch = toAction(
+    chain(
+      toAction(
+        chain(
+          toAction(chain(toAction(ms), toAction(DYNAMIC_SLEEP_INVOKE))),
+          toAction(Result.err()),
+        ),
+      ),
+      toAction(perform),
+    ),
+  );
+
+  const allAction: Action = { kind: "All", actions: [bodyBranch, sleepBranch] };
+
+  return typedAction(
+    buildRestartBranchAction(restartHandlerId, allAction, toAction(identity())),
+  );
+}

package/src/recursive.ts

@@ -0,0 +1,129 @@
+import {
+  type Action,
+  type Pipeable,
+  type TypedAction,
+  toAction,
+  typedAction,
+  branch,
+} from "./ast.js";
+import { all } from "./all.js";
+import { chain } from "./chain.js";
+import {
+  constant,
+  identity,
+  getField,
+  getIndex,
+  tag,
+} from "./builtins/index.js";
+import { allocateResumeHandlerId } from "./effect-id.js";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+type FunctionDef = [input: unknown, output: unknown];
+
+type FunctionRefs<TDefs extends FunctionDef[]> = {
+  [K in keyof TDefs]: TypedAction<TDefs[K][0], TDefs[K][1]>;
+};
+
+/**
+ * Constraint for the entry-point callback return type. Only requires the
+ * output phantom field — omits __in and __in_co so that actions with
+ * any input type (e.g. pipelines starting from a call token) are assignable.
+ */
+type BodyResult<TOut> = Action & {
+  __out?: () => TOut;
+};
+
+const UNUSED_STATE = null;
+
+// ---------------------------------------------------------------------------
+// defineRecursiveFunctions
+// ---------------------------------------------------------------------------
+
+/**
+ * Define mutually recursive functions that can call each other.
+ *
+ * The type parameter is an array of [In, Out] tuples — one per function.
+ * TypeScript can't infer these from circular definitions, so they must be
+ * explicit.
+ *
+ * Returns a curried combinator: the first callback defines function bodies,
+ * the second receives the same call tokens and returns the workflow entry
+ * point.
+ *
+ * Desugars to a ResumeHandle with a Branch-based handler. Each call token
+ * is Chain(Tag("CallN"), ResumePerform(id)). The handler dispatches to the
+ * correct function body by tag. The caller's pipeline is preserved as a
+ * ResumePerformFrame across each call.
+ *
+ * **Known limitation:** concurrent calls to the same function do not work
+ * as expected. `all(f(x), f(x))` will NOT call `f` twice — both branches
+ * perform on the same ResumeHandle, and the second perform will not
+ * execute independently. Use sequential calls (chain/then) instead of
+ * concurrent calls (all) when calling recursive functions multiple times.
+ */
+export function defineRecursiveFunctions<TDefs extends FunctionDef[]>(
+  bodiesFn: (...fns: FunctionRefs<TDefs>) => {
+    [K in keyof TDefs]: Pipeable<TDefs[K][0], TDefs[K][1]>;
+  },
+): <TOut>(
+  entryFn: (...fns: FunctionRefs<TDefs>) => BodyResult<TOut>,
+) => TypedAction<any, TOut> {
+  const resumeHandlerId = allocateResumeHandlerId();
+
+  const resumePerform: Action = {
+    kind: "ResumePerform",
+    resume_handler_id: resumeHandlerId,
+  };
+
+  // Call tokens: Chain(Tag("CallN"), ResumePerform(resumeHandlerId))
+  const fnCount = bodiesFn.length;
+  const callTokens = Array.from({ length: fnCount }, (_, i) =>
+    typedAction(
+      toAction(
+        chain(
+          toAction(tag(`Call${i}`, "RecursiveDispatch")),
+          toAction(resumePerform),
+        ),
+      ),
+    ),
+  );
+
+  // Get function body ASTs
+  const bodyActions = (
+    bodiesFn(...(callTokens as FunctionRefs<TDefs>)) as Pipeable[]
+  ).map(toAction);
+
+  // Branch cases: CallN → GetField("value") → bodyN
+  const cases: Record<string, Action> = {};
+  for (let i = 0; i < bodyActions.length; i++) {
+    cases[`Call${i}`] = toAction(
+      chain(toAction(getField("value")), toAction(bodyActions[i])),
+    );
+  }
+
+  // Return curried entry-point combinator
+  return <TOut>(entryFn: (...fns: FunctionRefs<TDefs>) => BodyResult<TOut>) => {
+    const userBody = toAction(entryFn(...(callTokens as FunctionRefs<TDefs>)));
+
+    return typedAction<any, TOut>(
+      toAction(
+        chain(toAction(all(identity(), constant(UNUSED_STATE))), {
+          kind: "ResumeHandle",
+          resume_handler_id: resumeHandlerId,
+          body: toAction(
+            chain(toAction(getIndex(0).unwrap()), toAction(userBody)),
+          ),
+          handler: toAction(
+            all(
+              chain(toAction(getIndex(0).unwrap()), toAction(branch(cases))),
+              constant(UNUSED_STATE),
+            ),
+          ),
+        }),
+      ),
+    );
+  };
+}