@barnum/barnum 0.2.3 → 0.4.0

package/src/bind.ts

@@ -0,0 +1,162 @@
+import {
+  type Action,
+  type ExtractInput,
+  type ExtractOutput,
+  type TypedAction,
+  toAction,
+  typedAction,
+} from "./ast.js";
+import { chain } from "./chain.js";
+import { all } from "./all.js";
+import { identity, drop, getIndex } from "./builtins/index.js";
+import { allocateResumeHandlerId, type ResumeHandlerId } from "./effect-id.js";
+import { pipe } from "./pipe.js";
+
+// ---------------------------------------------------------------------------
+// VarRef — typed reference to a bound value
+// ---------------------------------------------------------------------------
+
+/**
+ * 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 `getField` — pipe overloads can't infer
+ * the generic's type parameter from the VarRef's output.
+ */
+export type VarRef<TValue> = TypedAction<any, TValue>;
+
+function createVarRef<TValue>(
+  resumeHandlerId: ResumeHandlerId,
+): VarRef<TValue> {
+  return typedAction({
+    kind: "ResumePerform",
+    resume_handler_id: resumeHandlerId,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// InferVarRefs — map bindings to VarRef types
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps each binding's output type to a VarRef. TypeScript resolves
+ * ExtractOutput from each binding expression.
+ *
+ * Constraint is `Action[]` (not `Pipeable<any, any>[]`) so that
+ * `ExtractOutput` extracts the correct output type from the phantom
+ * fields on the concrete types without fighting invariant `__in` checks.
+ */
+export type InferVarRefs<TBindings extends Action[]> = {
+  [K in keyof TBindings]: VarRef<ExtractOutput<TBindings[K]>>;
+};
+
+// ---------------------------------------------------------------------------
+// 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(GetIndex(1).unwrap(), GetIndex(n).unwrap()), GetIndex(1).unwrap())
+ */
+function readVar(n: number): Action {
+  return toAction(
+    all(
+      chain(toAction(getIndex(1).unwrap()), toAction(getIndex(n).unwrap())),
+      toAction(getIndex(1).unwrap()),
+    ),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// bind — the user-facing function
+// ---------------------------------------------------------------------------
+
+/**
+ * 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(GetIndex(N), body)
+ *       )
+ *     )
+ *   )
+ */
+/**
+ * Constraint for the body callback return type. Only requires the output
+ * phantom field — omits `__in` and `__in_co` so that body actions with
+ * any input type (e.g. pipelines starting from a VarRef) are assignable.
+ */
+type BodyResult<TOut> = Action & {
+  __out?: () => TOut;
+};
+
+export function bind<TBindings extends Action[], TOut>(
+  bindings: [...TBindings],
+  body: (vars: InferVarRefs<TBindings>) => BodyResult<TOut>,
+): TypedAction<ExtractInput<TBindings[number]>, TOut> {
+  // 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 = toAction(body(varRefs as InferVarRefs<TBindings>));
+
+  // 4. Build nested Handles from inside out.
+  //    Innermost: extract pipeline_input (last All element) → user body
+  const pipelineInputIndex = bindings.length;
+  let inner: Action = toAction(
+    chain(
+      toAction(getIndex(pipelineInputIndex).unwrap()),
+      toAction(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 allAction: Action = {
+    kind: "All",
+    actions: [...bindings.map((b) => toAction(b)), toAction(identity())],
+  };
+  return typedAction(toAction(chain(toAction(allAction), toAction(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<TIn, TOut = any>(
+  body: (input: VarRef<TIn>) => BodyResult<TOut>,
+): TypedAction<TIn, TOut> {
+  return bind([identity()], ([input]) => pipe(drop, body(input)));
+}

package/src/builtins/array.ts

@@ -0,0 +1,121 @@
+import {
+  type Option as OptionT,
+  type TypedAction,
+  typedAction,
+} from "../ast.js";
+
+// ---------------------------------------------------------------------------
+// GetIndex — extract a single element from an array by index
+// ---------------------------------------------------------------------------
+
+export function getIndex<TTuple extends unknown[], TIndex extends number>(
+  index: TIndex,
+): TypedAction<TTuple, OptionT<TTuple[TIndex]>> {
+  return typedAction({
+    kind: "Invoke",
+    handler: {
+      kind: "Builtin",
+      builtin: { kind: "GetIndex", index },
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Flatten — flatten a nested array one level
+// ---------------------------------------------------------------------------
+
+export function flatten<TElement>(): TypedAction<TElement[][], TElement[]> {
+  return typedAction({
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "Flatten" } },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// SplitFirst — head/tail decomposition of an array
+// ---------------------------------------------------------------------------
+
+/**
+ * Deconstruct an array into its first element and the remaining elements.
+ * `TElement[] → Option<[TElement, TElement[]]>`
+ *
+ * Returns `Some([first, rest])` for non-empty arrays, `None` for empty arrays.
+ * This is the array equivalent of cons/uncons — enables recursive iteration
+ * patterns via `loop` + `splitFirst` + `branch`.
+ *
+ * This is a builtin (SplitFirst) because it requires array-length branching
+ * that can't be composed from existing AST nodes.
+ */
+export function splitFirst<TElement>(): TypedAction<
+  TElement[],
+  OptionT<[TElement, TElement[]]>
+> {
+  return typedAction({
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "SplitFirst" } },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// SplitLast — init/last decomposition of an array
+// ---------------------------------------------------------------------------
+
+/**
+ * Deconstruct an array into the leading elements and the last element.
+ * `TElement[] → Option<[TElement[], TElement]>`
+ *
+ * Returns `Some([init, last])` for non-empty arrays, `None` for empty arrays.
+ * Mirror of `splitFirst` — enables processing from the tail end.
+ *
+ * This is a builtin (SplitLast) because it requires array-length branching
+ * that can't be composed from existing AST nodes.
+ */
+export function splitLast<TElement>(): TypedAction<
+  TElement[],
+  OptionT<[TElement[], TElement]>
+> {
+  return typedAction({
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "SplitLast" } },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Slice — extract a sub-array from start to end
+// ---------------------------------------------------------------------------
+
+/**
+ * Slice an array from `start` (inclusive) to `end` (exclusive).
+ * `T[] → T[]`
+ *
+ * Both indices are clamped to array length. If `end` is omitted, slices
+ * to the end of the array. Returns empty array if `start >= end`.
+ */
+export function slice<TElement>(
+  start: number,
+  end?: number,
+): TypedAction<TElement[], TElement[]> {
+  const builtin: { kind: "Slice"; start: number; end?: number } =
+    end === undefined
+      ? { kind: "Slice", start }
+      : { kind: "Slice", start, end };
+  return typedAction({
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Range — produce an integer array [start, start+1, ..., end-1]
+// ---------------------------------------------------------------------------
+
+export function range(start: number, end: number): TypedAction<any, number[]> {
+  const result: number[] = [];
+  for (let i = start; i < end; i++) {
+    result.push(i);
+  }
+  return typedAction({
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "Constant", value: result } },
+  });
+}

package/src/builtins/index.ts

@@ -0,0 +1,17 @@
+export { constant, identity, drop, panic } from "./scalar.js";
+export { getField, wrapInField, merge, pick, allObject } from "./struct.js";
+export {
+  getIndex,
+  flatten,
+  splitFirst,
+  splitLast,
+  slice,
+  range,
+} from "./array.js";
+export {
+  tag,
+  extractPrefix,
+  asOption,
+  taggedUnionSchema,
+} from "./tagged-union.js";
+export { withResource } from "./with-resource.js";

package/src/builtins/scalar.ts

@@ -0,0 +1,49 @@
+import { type TypedAction, typedAction } from "../ast.js";
+
+// ---------------------------------------------------------------------------
+// Constant — produce a fixed value (takes no pipeline input)
+// ---------------------------------------------------------------------------
+
+export function constant<TValue>(value: TValue): TypedAction<any, TValue> {
+  return typedAction({
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "Constant", value } },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Identity — pass input through unchanged
+// ---------------------------------------------------------------------------
+
+export function identity<TValue = any>(): TypedAction<TValue, TValue> {
+  return typedAction({
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "Identity" } },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Drop — discard pipeline value
+// ---------------------------------------------------------------------------
+
+export const drop: TypedAction<any, void> = typedAction({
+  kind: "Invoke",
+  handler: { kind: "Builtin", builtin: { kind: "Drop" } },
+});
+
+// ---------------------------------------------------------------------------
+// Panic — halt execution with an error message
+// ---------------------------------------------------------------------------
+
+/**
+ * Halt execution with a fatal error. Not caught by tryCatch.
+ * Analogous to Rust's `panic!`.
+ *
+ * Output type is `never` — a panic never produces a value.
+ */
+export function panic(message: string): TypedAction<any, never> {
+  return typedAction({
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "Panic", message } },
+  });
+}

package/src/builtins/struct.ts

@@ -0,0 +1,111 @@
+import {
+  type Action,
+  type ExtractOutput,
+  type MergeTuple,
+  type Pipeable,
+  type TypedAction,
+  toAction,
+  typedAction,
+} from "../ast.js";
+import { chain } from "../chain.js";
+
+// ---------------------------------------------------------------------------
+// GetField — extract a single field from an object
+// ---------------------------------------------------------------------------
+
+export function getField<
+  TObj extends Record<string, unknown>,
+  TField extends keyof TObj & string,
+>(field: TField): TypedAction<TObj, TObj[TField]> {
+  return typedAction({
+    kind: "Invoke",
+    handler: {
+      kind: "Builtin",
+      builtin: { kind: "GetField", field },
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// WrapInField — wrap input as { <field>: <input> }
+// ---------------------------------------------------------------------------
+
+export function wrapInField<TField extends string, TValue>(
+  field: TField,
+): TypedAction<TValue, Record<TField, TValue>> {
+  return typedAction({
+    kind: "Invoke",
+    handler: {
+      kind: "Builtin",
+      builtin: { kind: "WrapInField", field },
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Merge — merge a tuple of objects into a single object
+// ---------------------------------------------------------------------------
+
+export function merge<TTuple extends Record<string, unknown>[]>(): TypedAction<
+  TTuple,
+  MergeTuple<TTuple>
+> {
+  return typedAction({
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "Merge" } },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Pick — select named fields from an object
+// ---------------------------------------------------------------------------
+
+export function pick<
+  TObj extends Record<string, unknown>,
+  TKeys extends (keyof TObj & string)[],
+>(...keys: TKeys): TypedAction<TObj, Pick<TObj, TKeys[number]>> {
+  const actions = keys.map((key) =>
+    toAction(chain(toAction(getField(key)), toAction(wrapInField(key)))),
+  );
+  const allAction: Action = { kind: "All", actions };
+  return chain(toAction(allAction), toAction(merge())) as TypedAction<
+    TObj,
+    Pick<TObj, TKeys[number]>
+  >;
+}
+
+// ---------------------------------------------------------------------------
+// AllObject — run named actions concurrently, collect into an object
+// ---------------------------------------------------------------------------
+
+/**
+ * Run named actions concurrently on the same input, collecting results
+ * into an object with matching keys.
+ *
+ * ```ts
+ * allObject({
+ *   files: listFiles,
+ *   config: loadConfig,
+ * })
+ * // TIn → { files: string[], config: Config }
+ * ```
+ *
+ * Each action receives the pipeline input. Results are wrapped in
+ * `{ key: value }` via `wrapInField`, run concurrently via `All`,
+ * then merged into a single object.
+ */
+export function allObject<TActions extends Record<string, Pipeable<any, any>>>(
+  actions: TActions,
+): TypedAction<
+  any,
+  { [K in keyof TActions & string]: ExtractOutput<TActions[K]> }
+> {
+  const wrapped = Object.entries(actions).map(([key, action]) =>
+    toAction(chain(action, wrapInField(key))),
+  );
+  const allAction: Action = { kind: "All", actions: wrapped };
+  return chain(toAction(allAction), toAction(merge())) as TypedAction<
+    any,
+    { [K in keyof TActions & string]: ExtractOutput<TActions[K]> }
+  >;
+}

package/src/builtins/tagged-union.ts

@@ -0,0 +1,142 @@
+import {
+  type Option,
+  type TaggedUnion,
+  type TypedAction,
+  toAction,
+  typedAction,
+} from "../ast.js";
+import { chain } from "../chain.js";
+import { all } from "../all.js";
+import { constant } from "./scalar.js";
+import { wrapInField, merge } from "./struct.js";
+import { z } from "zod";
+
+// ---------------------------------------------------------------------------
+// Tag — wrap input as a tagged union variant
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap input as a tagged union member. Requires the full variant map TDef
+ * so the output type carries __def for branch decomposition.
+ *
+ * Usage: tag<{ Ok: string; Err: number }, "Ok">("Ok")
+ *        input: string → output: TaggedUnion<{ Ok: string; Err: number }>
+ */
+export function tag<
+  TEnumName extends string,
+  TDef extends Record<string, unknown>,
+  TKind extends keyof TDef & string,
+>(
+  kind: TKind,
+  enumName: TEnumName,
+): TypedAction<TDef[TKind], TaggedUnion<TEnumName, TDef>> {
+  const namespacedKind = `${enumName}.${kind}`;
+  return chain(
+    toAction(
+      all(
+        chain(
+          toAction(constant(namespacedKind)),
+          toAction(wrapInField("kind")),
+        ),
+        wrapInField("value"),
+      ),
+    ),
+    toAction(merge()),
+  ) as TypedAction<TDef[TKind], TaggedUnion<TEnumName, TDef>>;
+}
+
+// ---------------------------------------------------------------------------
+// ExtractPrefix — extract enum prefix from tagged value kind
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract the enum prefix from a tagged value's `kind` field.
+ *
+ * Input:  `{ kind: "Result.Ok", value: 42 }`
+ * Output: `{ kind: "Result", value: { kind: "Result.Ok", value: 42 } }`
+ *
+ * If `kind` contains no `'.'`, the entire kind string becomes the prefix.
+ * Used internally by `branchFamily` for two-level dispatch.
+ */
+export function extractPrefix(): TypedAction {
+  return typedAction({
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "ExtractPrefix" } },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// AsOption — convert boolean to Option<void>
+// ---------------------------------------------------------------------------
+
+/**
+ * Convert a boolean to `Option<void>`.
+ *
+ * `true`  → `{ kind: "Option.Some", value: null }`
+ * `false` → `{ kind: "Option.None", value: null }`
+ */
+export function asOption(): TypedAction<boolean, Option<void>> {
+  return typedAction({
+    kind: "Invoke",
+    handler: { kind: "Builtin", builtin: { kind: "AsOption" } },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// TaggedUnion Zod schema constructor
+// ---------------------------------------------------------------------------
+
+/**
+ * Reverse of VoidToNull: maps `null` back to `void` in the def so that
+ * `taggedUnionSchema({ Clean: z.null() })` produces the same phantom __def
+ * as `TaggedUnion<{ Clean: void }>`.
+ */
+type NullToVoid<TDef> = {
+  [K in keyof TDef]: TDef[K] extends null ? void : TDef[K];
+};
+
+/**
+ * Build a Zod schema for a `TaggedUnion<TEnumName, TDef>` — a discriminated
+ * union of `{ kind: "EnumName.Variant"; value: V }` objects.
+ *
+ * Each key in `cases` becomes a variant with a namespaced kind string.
+ * Use `z.null()` for void variants.
+ *
+ * ```ts
+ * const schema = taggedUnionSchema("ClassifyResult", {
+ *   HasErrors: z.array(TypeErrorValidator),
+ *   Clean: z.null(),
+ * });
+ * ```
+ */
+export function taggedUnionSchema<
+  TEnumName extends string,
+  TDef extends Record<string, z.ZodTypeAny>,
+>(
+  enumName: TEnumName,
+  cases: TDef,
+): z.ZodType<
+  TaggedUnion<
+    TEnumName,
+    NullToVoid<{ [K in keyof TDef & string]: z.infer<TDef[K]> }>
+  >
+> {
+  type Out = TaggedUnion<
+    TEnumName,
+    NullToVoid<{ [K in keyof TDef & string]: z.infer<TDef[K]> }>
+  >;
+  const variants = Object.entries(cases).map(([kind, valueSchema]) =>
+    z.object({ kind: z.literal(`${enumName}.${kind}`), value: valueSchema }),
+  );
+  if (variants.length === 0) {
+    return z.never() as z.ZodType<Out>;
+  }
+  if (variants.length === 1) {
+    return variants[0] as z.ZodType<Out>;
+  }
+  return z.discriminatedUnion("kind", [
+    variants[0],
+    variants[1],
+    ...variants.slice(2),
+  ]) as z.ZodType<Out>;
+}

package/src/builtins/with-resource.ts

@@ -0,0 +1,69 @@
+import { type Pipeable, type TypedAction, toAction } from "../ast.js";
+import { chain } from "../chain.js";
+import { all } from "../all.js";
+import { identity } from "./scalar.js";
+import { merge } from "./struct.js";
+import { getIndex } from "./array.js";
+
+// ---------------------------------------------------------------------------
+// WithResource — RAII-style create/action/dispose
+// ---------------------------------------------------------------------------
+
+/**
+ * RAII-style resource management combinator.
+ *
+ * Runs `create` to acquire a resource, then merges the resource with the
+ * original input into a flat object (`TResource & TIn`) for the action.
+ * After the action completes, `dispose` receives the resource for cleanup.
+ * The overall combinator returns the action's output.
+ *
+ * ```
+ * TIn → create → TResource
+ *     → merge(TResource, TIn) → TResource & TIn
+ *     → action(TResource & TIn) → TOut
+ *     → dispose(TResource) → (discarded)
+ *     → TOut
+ * ```
+ */
+export function withResource<
+  TIn extends Record<string, unknown>,
+  TResource extends Record<string, unknown>,
+  TOut,
+  TDisposeOut = unknown,
+>({
+  create,
+  action,
+  dispose,
+}: {
+  create: Pipeable<TIn, TResource>;
+  action: Pipeable<TResource & TIn, TOut>;
+  dispose: Pipeable<TResource, TDisposeOut>;
+}): TypedAction<TIn, TOut> {
+  // Step 1: all(create, identity) → [TResource, TIn] → merge → TResource & TIn
+  const acquireAndMerge = chain(
+    toAction(all(create, identity())),
+    toAction(merge()),
+  );
+
+  // Step 2: all(action, identity) → [TOut, TResource & TIn]
+  const actionAndKeepMerged = all(toAction(action), toAction(identity()));
+
+  // Step 3: all(getIndex(0).unwrap(), chain(getIndex(1).unwrap(), dispose)) → [TOut, unknown]
+  const disposeAndKeepResult = all(
+    toAction(getIndex(0).unwrap()),
+    chain(toAction(getIndex(1).unwrap()), toAction(dispose)),
+  );
+
+  // Step 4: getIndex(0).unwrap() → TOut
+  return chain(
+    toAction(
+      chain(
+        toAction(
+          chain(toAction(acquireAndMerge), toAction(actionAndKeepMerged)),
+        ),
+        toAction(disposeAndKeepResult),
+      ),
+    ),
+    toAction(getIndex(0).unwrap()),
+  ) as TypedAction<TIn, TOut>;
+}

package/src/chain.ts

@@ -0,0 +1,17 @@
+import {
+  type Pipeable,
+  type TypedAction,
+  toAction,
+  typedAction,
+} from "./ast.js";
+
+export function chain<T1, T2, T3>(
+  first: Pipeable<T1, T2>,
+  rest: Pipeable<T2, T3>,
+): TypedAction<T1, T3> {
+  return typedAction<T1, T3>({
+    kind: "Chain",
+    first: toAction(first),
+    rest: toAction(rest),
+  });
+}