@barnum/barnum 0.3.0 → 0.4.0

package/src/chain.ts

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

package/src/handler.ts

@@ -1,7 +1,10 @@
 import { fileURLToPath } from "node:url";
 import type { JSONSchema7 } from "json-schema";
 import type { z } from "zod";
-import { type TypedAction, typedAction } from "./ast.js";
+import { type TypedAction, toAction, typedAction } from "./ast.js";
+import { chain } from "./chain.js";
+import { all } from "./all.js";
+import { constant, identity } from "./builtins/index.js";
 import { zodToCheckedJsonSchema } from "./schema.js";
 
 // ---------------------------------------------------------------------------
@@ -84,21 +87,21 @@ function getCallerFilePath(): string {
 }
 
 // ---------------------------------------------------------------------------
-// HandlerOutput — maps void → never so fire-and-forget handlers compose
+// HandlerOutput — maps void → void (null at runtime)
 // ---------------------------------------------------------------------------
 
 /**
- * Handlers that return `Promise<void>` produce `never` output. This means
- * they naturally compose in pipes without needing `.drop()` — a handler
- * that returns nothing produces a value no one can observe.
+ * Handlers that return `Promise<void>` produce `void` output (null at
+ * runtime). This is honest — the handler completes and returns nothing
+ * useful, but execution continues.
  */
-type HandlerOutput<TOutput> = [TOutput] extends [void] ? never : TOutput;
+type HandlerOutput<TOutput> = [TOutput] extends [void] ? void : TOutput;
 
 // ---------------------------------------------------------------------------
 // createHandler — single overload, validators optional
 // ---------------------------------------------------------------------------
 
-export function createHandler<TValue = never, TOutput = unknown>(
+export function createHandler<TValue = void, TOutput = unknown>(
   definition: {
     inputValidator?: z.ZodType<TValue>;
     outputValidator?: z.ZodType<NoInfer<TOutput>>;
@@ -158,7 +161,7 @@ export function createHandler(
 // ---------------------------------------------------------------------------
 
 export function createHandlerWithConfig<
-  TValue = never,
+  TValue = void,
   TOutput = unknown,
   TStepConfig = unknown,
 >(
@@ -245,26 +248,7 @@ export function createHandlerWithConfig(
   // __definition for the worker to find (the worker imports the module
   // and accesses the named export, which is this function).
   const factory = (config: unknown): TypedAction =>
-    typedAction({
-      kind: "Chain",
-      first: {
-        kind: "All",
-        actions: [
-          {
-            kind: "Invoke",
-            handler: { kind: "Builtin", builtin: { kind: "Identity" } },
-          },
-          {
-            kind: "Invoke",
-            handler: {
-              kind: "Builtin",
-              builtin: { kind: "Constant", value: config },
-            },
-          },
-        ],
-      },
-      rest: invokeAction,
-    });
+    chain(toAction(all(identity(), constant(config))), toAction(invokeAction));
 
   Object.defineProperty(factory, HANDLER_BRAND, {
     value: true,

package/src/index.ts

@@ -1,30 +1,37 @@
-import type { TaggedUnion, OptionDef, ResultDef } from "./ast.js";
+import type { TaggedUnion, OptionDef, ResultDef, IteratorDef } from "./ast.js";
 
 export * from "./ast.js";
 export {
+  allObject,
+  asOption,
   constant,
-  identity,
   drop,
-  tag,
-  merge,
   flatten,
-  extractField,
-  extractIndex,
+  getField,
+  getIndex,
+  identity,
+  panic,
   pick,
-  dropResult,
-  withResource,
-  augment,
-  tap,
   range,
-  Option,
-  Result,
-} from "./builtins.js";
-export * from "./handler.js";
-export { runPipeline } from "./run.js";
+  splitFirst,
+  splitLast,
+  tag,
+  taggedUnionSchema,
+  withResource,
+  wrapInField,
+} from "./builtins/index.js";
+export { Option, first, last } from "./option.js";
+export { Result } from "./result.js";
+export { Iterator } from "./iterator.js";
+export { runPipeline, type RunPipelineOptions, type LogLevel } from "./run.js";
 export { zodToCheckedJsonSchema } from "./schema.js";
 
 // Declaration merge: the explicit value exports of Option/Result from builtins
 // shadow the type-only exports from ast's `export *`. Re-declare the generic
 // type aliases here so consumers get both the type and value under one name.
-export type Option<T> = TaggedUnion<OptionDef<T>>;
-export type Result<TValue, TError> = TaggedUnion<ResultDef<TValue, TError>>;
+export type Option<T> = TaggedUnion<"Option", OptionDef<T>>;
+export type Result<TValue, TError> = TaggedUnion<
+  "Result",
+  ResultDef<TValue, TError>
+>;
+export type Iterator<TElement> = TaggedUnion<"Iterator", IteratorDef<TElement>>;

package/src/iterator.ts

@@ -0,0 +1,243 @@
+import {
+  type Iterator as IteratorT,
+  type IteratorDef,
+  type Option as OptionT,
+  type Pipeable,
+  type Result as ResultT,
+  type TypedAction,
+  toAction,
+  typedAction,
+  branch,
+  branchFamily,
+  forEach,
+  loop,
+} from "./ast.js";
+import { chain } from "./chain.js";
+import {
+  constant,
+  drop,
+  flatten,
+  getField,
+  getIndex,
+  identity,
+  slice,
+  splitFirst,
+  splitLast,
+  tag,
+} from "./builtins/index.js";
+import { all } from "./all.js";
+import { Option } from "./option.js";
+import { bindInput } from "./bind.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Wrap a single value in an array. `T → T[]`
+ * Implemented as `all(identity())`. May warrant a dedicated builtin later.
+ */
+function wrapInArray<TElement>(): TypedAction<TElement, TElement[]> {
+  return all(identity()) as TypedAction<TElement, TElement[]>;
+}
+
+/**
+ * Normalize any IntoIterator return type to a plain array.
+ * Used inside `.flatMap()` to handle Iterator, Option, Result, and Array returns.
+ */
+const intoIteratorNormalize = branchFamily({
+  Iterator: branch({ Iterator: identity() }),
+  Option: branch({ Some: wrapInArray(), None: constant([]) }),
+  Result: branch({ Ok: wrapInArray(), Err: constant([]) }),
+  Array: identity(),
+});
+
+// ---------------------------------------------------------------------------
+// Iterator namespace
+// ---------------------------------------------------------------------------
+
+export const Iterator = {
+  /** Wrap an array as Iterator. `T[] → Iterator<T>` */
+  fromArray<TElement>(): TypedAction<TElement[], IteratorT<TElement>> {
+    return tag<"Iterator", IteratorDef<TElement>, "Iterator">(
+      "Iterator",
+      "Iterator",
+    );
+  },
+
+  /** Wrap an Option as Iterator. `Option<T> → Iterator<T>` */
+  fromOption<TElement>(): TypedAction<OptionT<TElement>, IteratorT<TElement>> {
+    return branch({
+      Some: chain(wrapInArray<TElement>(), Iterator.fromArray<TElement>()),
+      None: chain(constant<TElement[]>([]), Iterator.fromArray<TElement>()),
+    }) as TypedAction<OptionT<TElement>, IteratorT<TElement>>;
+  },
+
+  /** Wrap a Result as Iterator (Ok kept, Err dropped). `Result<T, E> → Iterator<T>` */
+  fromResult<TElement, TError>(): TypedAction<
+    ResultT<TElement, TError>,
+    IteratorT<TElement>
+  > {
+    return branch({
+      Ok: chain(wrapInArray<TElement>(), Iterator.fromArray<TElement>()),
+      Err: chain(constant<TElement[]>([]), Iterator.fromArray<TElement>()),
+    }) as TypedAction<ResultT<TElement, TError>, IteratorT<TElement>>;
+  },
+
+  /** Unwrap Iterator to array. `Iterator<T> → T[]` */
+  collect<TElement>(): TypedAction<IteratorT<TElement>, TElement[]> {
+    return getField("value") as TypedAction<IteratorT<TElement>, TElement[]>;
+  },
+
+  /** Transform each element. `Iterator<T> → Iterator<U>` */
+  map<TIn, TOut>(
+    action: Pipeable<TIn, TOut>,
+  ): TypedAction<IteratorT<TIn>, IteratorT<TOut>> {
+    return chain(
+      toAction(getField("value")),
+      chain(toAction(forEach(action)), Iterator.fromArray<TOut>()),
+    ) as TypedAction<IteratorT<TIn>, IteratorT<TOut>>;
+  },
+
+  /** Flat-map each element. `f` returns any IntoIterator type. `Iterator<T> → Iterator<U>` */
+  flatMap<TIn, TOut>(
+    action: Pipeable<TIn, unknown>,
+  ): TypedAction<IteratorT<TIn>, IteratorT<TOut>> {
+    return chain(
+      toAction(getField("value")),
+      chain(
+        toAction(forEach(chain(action, intoIteratorNormalize))),
+        chain(toAction(flatten()), Iterator.fromArray<TOut>()),
+      ),
+    ) as TypedAction<IteratorT<TIn>, IteratorT<TOut>>;
+  },
+
+  /** Keep elements where predicate returns true. `Iterator<T> → Iterator<T>` */
+  filter<TElement>(
+    predicate: Pipeable<TElement, boolean>,
+  ): TypedAction<IteratorT<TElement>, IteratorT<TElement>> {
+    return Iterator.flatMap<TElement, TElement>(
+      bindInput<TElement>((element) =>
+        element
+          .then(predicate)
+          .asOption()
+          .branch({
+            Some: element.some(),
+            None: chain(drop, Option.none<TElement>()),
+          }),
+      ),
+    );
+  },
+
+  /** Head/tail decomposition. `Iterator<T> → Option<[T, Iterator<T>]>` */
+  splitFirst<TElement>(): TypedAction<
+    IteratorT<TElement>,
+    OptionT<[TElement, IteratorT<TElement>]>
+  > {
+    return Iterator.collect<TElement>()
+      .then(splitFirst<TElement>())
+      .then(
+        Option.map(
+          all(
+            getIndex<[TElement, TElement[]], 0>(0).unwrap(),
+            getIndex<[TElement, TElement[]], 1>(1).unwrap().iterate(),
+          ),
+        ),
+      );
+  },
+
+  /** Init/last decomposition. `Iterator<T> → Option<[Iterator<T>, T]>` */
+  splitLast<TElement>(): TypedAction<
+    IteratorT<TElement>,
+    OptionT<[IteratorT<TElement>, TElement]>
+  > {
+    return Iterator.collect<TElement>()
+      .then(splitLast<TElement>())
+      .then(
+        Option.map(
+          all(
+            getIndex<[TElement[], TElement], 0>(0).unwrap().iterate(),
+            getIndex<[TElement[], TElement], 1>(1).unwrap(),
+          ),
+        ),
+      );
+  },
+
+  /** Fold elements with accumulator. `Iterator<T> → TAcc` */
+  fold<TElement, TAcc>(
+    init: Pipeable<void, TAcc>,
+    body: Pipeable<[TAcc, TElement], TAcc>,
+  ): TypedAction<IteratorT<TElement>, TAcc> {
+    return Iterator.collect<TElement>().then(
+      bindInput<TElement[]>((elements) =>
+        all(init, elements).then(
+          loop<TAcc, [TAcc, TElement[]]>((recur, done) => {
+            // Re-wrap done to bridge VoidToNull<TAcc> → TAcc (TypeScript
+            // can't simplify the conditional type for generic TAcc).
+            const doneTAcc = typedAction<TAcc, never>(toAction(done));
+
+            // Wrap return with typedAction — branch output inference fails
+            // for generic types inside loop bodies.
+            return typedAction<[TAcc, TElement[]], never>(
+              toAction(
+                bindInput<[TAcc, TElement[]]>((state) => {
+                  const acc = state.getIndex(0).unwrap();
+                  const remaining = state.getIndex(1).unwrap();
+
+                  return remaining.splitFirst().branch({
+                    None: acc.then(doneTAcc),
+                    Some: bindInput<[TElement, TElement[]]>((headTail) => {
+                      const head = headTail.getIndex(0).unwrap();
+                      const tail = headTail.getIndex(1).unwrap();
+
+                      return all(acc, head)
+                        .then(body)
+                        .then(
+                          bindInput<TAcc>((newAcc) =>
+                            all(newAcc, tail).then(recur),
+                          ),
+                        );
+                    }),
+                  });
+                }),
+              ),
+            );
+          }),
+        ),
+      ),
+    );
+  },
+
+  /** Slice elements from start to end. `Iterator<T> → Iterator<T>` */
+  slice<TElement>(
+    start: number,
+    end?: number,
+  ): TypedAction<IteratorT<TElement>, IteratorT<TElement>> {
+    return chain(
+      Iterator.collect<TElement>(),
+      chain(
+        toAction(slice<TElement>(start, end)),
+        Iterator.fromArray<TElement>(),
+      ),
+    );
+  },
+
+  /** First n elements. `Iterator<T> → Iterator<T>` */
+  take<TElement>(
+    n: number,
+  ): TypedAction<IteratorT<TElement>, IteratorT<TElement>> {
+    return Iterator.slice(0, n);
+  },
+
+  /** Drop first n elements. `Iterator<T> → Iterator<T>` */
+  skip<TElement>(
+    n: number,
+  ): TypedAction<IteratorT<TElement>, IteratorT<TElement>> {
+    return Iterator.slice(n);
+  },
+
+  /** Check if iterator is empty. `Iterator<T> → boolean` */
+  isEmpty<TElement>(): TypedAction<IteratorT<TElement>, boolean> {
+    return Iterator.collect<TElement>().splitFirst().isNone();
+  },
+} as const;

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>>;
+}