@barnum/barnum 0.0.0-main-8d724777 → 0.0.0-main-50effdfd

package/dist/ast.d.ts

@@ -78,6 +78,10 @@ export type BuiltinKind = {
     value: string[];
 } | {
     kind: "CollectSome";
+} | {
+    kind: "SplitFirst";
+} | {
+    kind: "SplitLast";
 } | {
     kind: "WrapInField";
     value: string;
@@ -132,10 +136,16 @@ export type TypedAction<In = unknown, Out = unknown, Refs extends string = never
     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>;
+    /** Wrap output in an object under a field name. `a.wrapInField("foo")` ≡ `pipe(a, wrapInField("foo"))`. */
+    wrapInField<TField extends string>(field: TField): TypedAction<In, Record<TField, 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>;
+    /** Head/tail decomposition. Only callable when Out is TElement[]. */
+    splitFirst<TIn, TElement, TRefs extends string>(this: TypedAction<TIn, TElement[], TRefs>): TypedAction<TIn, Option<[TElement, TElement[]]>, TRefs>;
+    /** Init/last decomposition. Only callable when Out is TElement[]. */
+    splitLast<TIn, TElement, TRefs extends string>(this: TypedAction<TIn, TElement[], TRefs>): TypedAction<TIn, Option<[TElement[], TElement]>, TRefs>;
     /**
      * Transform the Some value inside an Option output. Only callable when
      * Out is Option<T>. Uses `this` parameter constraint to gate availability.

package/dist/ast.js

@@ -62,6 +62,19 @@ function getMethod(field) {
         },
     });
 }
+function wrapInFieldMethod(field) {
+    return typedAction({
+        kind: "Chain",
+        first: this,
+        rest: {
+            kind: "Invoke",
+            handler: {
+                kind: "Builtin",
+                builtin: { kind: "WrapInField", value: field },
+            },
+        },
+    });
+}
 function mergeMethod() {
     return typedAction({
         kind: "Chain",
@@ -82,6 +95,26 @@ function pickMethod(...keys) {
         },
     });
 }
+function splitFirstMethod() {
+    return typedAction({
+        kind: "Chain",
+        first: this,
+        rest: {
+            kind: "Invoke",
+            handler: { kind: "Builtin", builtin: { kind: "SplitFirst" } },
+        },
+    });
+}
+function splitLastMethod() {
+    return typedAction({
+        kind: "Chain",
+        first: this,
+        rest: {
+            kind: "Invoke",
+            handler: { kind: "Builtin", builtin: { kind: "SplitLast" } },
+        },
+    });
+}
 function mapOptionMethod(action) {
     // Desugars to: self.then(branch({ Some: pipe(action, tag("Some")), None: tag("None") }))
     // But branch auto-unwraps value, so:
@@ -170,8 +203,11 @@ export function typedAction(action) {
             drop: { value: dropMethod, configurable: true },
             tag: { value: tagMethod, configurable: true },
             get: { value: getMethod, configurable: true },
+            wrapInField: { value: wrapInFieldMethod, configurable: true },
             merge: { value: mergeMethod, configurable: true },
             pick: { value: pickMethod, configurable: true },
+            splitFirst: { value: splitFirstMethod, configurable: true },
+            splitLast: { value: splitLastMethod, configurable: true },
             mapOption: { value: mapOptionMethod, configurable: true },
             mapErr: { value: mapErrMethod, configurable: true },
             unwrapOr: { value: unwrapOrMethod, configurable: true },

package/dist/builtins.d.ts

@@ -1,4 +1,4 @@
-import { type Action, type Option as OptionT, type Pipeable, type Result as ResultT, type TaggedUnion, type TypedAction } from "./ast.js";
+import { type Action, type MergeTuple, type Option as OptionT, type Pipeable, type Result as ResultT, type TaggedUnion, type TypedAction } from "./ast.js";
 /**
  * Typed combinators for structural data transformations.
  *
@@ -16,40 +16,7 @@ export declare const drop: TypedAction<any, never>;
  *        input: string → output: TaggedUnion<{ Ok: string; Err: number }>
  */
 export declare function tag<TDef extends Record<string, unknown>, TKind extends keyof TDef & string>(kind: TKind): TypedAction<TDef[TKind], TaggedUnion<TDef>>;
-type Obj = Record<string, unknown>;
-export declare function merge<A extends Obj, B extends Obj>(): TypedAction<[
-    A,
-    B
-], A & B>;
-export declare function merge<A extends Obj, B extends Obj, C extends Obj>(): TypedAction<[A, B, C], A & B & C>;
-export declare function merge<A extends Obj, B extends Obj, C extends Obj, D extends Obj>(): TypedAction<[A, B, C, D], A & B & C & D>;
-export declare function merge<A extends Obj, B extends Obj, C extends Obj, D extends Obj, E extends Obj>(): TypedAction<[A, B, C, D, E], A & B & C & D & E>;
-export declare function merge<A extends Obj, B extends Obj, C extends Obj, D extends Obj, E extends Obj, F extends Obj>(): TypedAction<[A, B, C, D, E, F], A & B & C & D & E & F>;
-export declare function merge<A extends Obj, B extends Obj, C extends Obj, D extends Obj, E extends Obj, F extends Obj, G extends Obj>(): TypedAction<[A, B, C, D, E, F, G], A & B & C & D & E & F & G>;
-export declare function merge<A extends Obj, B extends Obj, C extends Obj, D extends Obj, E extends Obj, F extends Obj, G extends Obj, H extends Obj>(): TypedAction<[A, B, C, D, E, F, G, H], A & B & C & D & E & F & G & H>;
-export declare function merge<A extends Obj, B extends Obj, C extends Obj, D extends Obj, E extends Obj, F extends Obj, G extends Obj, H extends Obj, I extends Obj>(): TypedAction<[
-    A,
-    B,
-    C,
-    D,
-    E,
-    F,
-    G,
-    H,
-    I
-], A & B & C & D & E & F & G & H & I>;
-export declare function merge<A extends Obj, B extends Obj, C extends Obj, D extends Obj, E extends Obj, F extends Obj, G extends Obj, H extends Obj, I extends Obj, J extends Obj>(): TypedAction<[
-    A,
-    B,
-    C,
-    D,
-    E,
-    F,
-    G,
-    H,
-    I,
-    J
-], A & B & C & D & E & F & G & H & I & J>;
+export declare function merge<TTuple extends Record<string, unknown>[]>(): TypedAction<TTuple, MergeTuple<TTuple>>;
 export declare function flatten<TElement>(): TypedAction<TElement[][], TElement[]>;
 export declare function extractField<TObj extends Record<string, unknown>, TField extends keyof TObj & string>(field: TField): TypedAction<TObj, TObj[TField]>;
 export declare function extractIndex<TTuple extends unknown[], TIndex extends number>(index: TIndex): TypedAction<TTuple, TTuple[TIndex]>;
@@ -90,6 +57,29 @@ export declare function withResource<TIn extends Record<string, unknown>, TResou
 export declare function tap<TInput extends Record<string, unknown>>(action: Pipeable<TInput, any>): TypedAction<TInput, TInput>;
 export declare function wrapInField<TField extends string, TValue>(field: TField): TypedAction<TValue, Record<TField, TValue>>;
 export declare function range(start: number, end: number): TypedAction<any, number[]>;
+/**
+ * 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 declare function splitFirst<TElement>(): TypedAction<TElement[], OptionT<[TElement, TElement[]]>>;
+/**
+ * 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 declare function splitLast<TElement>(): TypedAction<TElement[], OptionT<[TElement[], TElement]>>;
 /**
  * Option namespace. All combinators produce TypedAction AST nodes that
  * desugar to branch + existing builtins, except collect which uses the
@@ -276,4 +266,3 @@ export declare const Result: {
      */
     readonly isErr: <TValue, TError>() => TypedAction<ResultT<TValue, TError>, boolean>;
 };
-export {};

package/dist/builtins.js

@@ -45,6 +45,9 @@ export function tag(kind) {
         handler: { kind: "Builtin", builtin: { kind: "Tag", value: kind } },
     });
 }
+// ---------------------------------------------------------------------------
+// Merge — merge a tuple of objects into a single object
+// ---------------------------------------------------------------------------
 export function merge() {
     return typedAction({
         kind: "Invoke",
@@ -224,6 +227,45 @@ export function range(start, end) {
     });
 }
 // ---------------------------------------------------------------------------
+// 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() {
+    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() {
+    return typedAction({
+        kind: "Invoke",
+        handler: { kind: "Builtin", builtin: { kind: "SplitLast" } },
+    });
+}
+// ---------------------------------------------------------------------------
 // Option namespace — combinators for Option<T> tagged unions
 // ---------------------------------------------------------------------------
 // Shared AST fragments for Option desugaring

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import type { TaggedUnion, OptionDef, ResultDef } from "./ast.js";
 export * from "./ast.js";
-export { constant, identity, drop, tag, merge, flatten, extractField, extractIndex, pick, dropResult, withResource, tap, range, wrapInField, Option, Result, } from "./builtins.js";
+export { constant, identity, drop, tag, merge, flatten, extractField, extractIndex, pick, dropResult, withResource, tap, range, splitFirst, splitLast, wrapInField, Option, Result, } from "./builtins.js";
 export * from "./handler.js";
 export { runPipeline, type RunPipelineOptions, type LogLevel } from "./run.js";
 export { zodToCheckedJsonSchema } from "./schema.js";

package/dist/index.js

@@ -1,5 +1,5 @@
 export * from "./ast.js";
-export { constant, identity, drop, tag, merge, flatten, extractField, extractIndex, pick, dropResult, withResource, tap, range, wrapInField, Option, Result, } from "./builtins.js";
+export { constant, identity, drop, tag, merge, flatten, extractField, extractIndex, pick, dropResult, withResource, tap, range, splitFirst, splitLast, wrapInField, Option, Result, } from "./builtins.js";
 export * from "./handler.js";
 export { runPipeline } from "./run.js";
 export { zodToCheckedJsonSchema } from "./schema.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@barnum/barnum",
-  "version": "0.0.0-main-8d724777",
+  "version": "0.0.0-main-50effdfd",
   "description": "Barnum workflow engine",
   "type": "module",
   "main": "dist/index.js",

package/src/ast.ts

@@ -95,6 +95,8 @@ export type BuiltinKind =
   | { kind: "ExtractIndex"; value: number }
   | { kind: "Pick"; value: string[] }
   | { kind: "CollectSome" }
+  | { kind: "SplitFirst" }
+  | { kind: "SplitLast" }
   | { kind: "WrapInField"; value: string }
   | { kind: "Sleep"; value: number };
 
@@ -185,12 +187,24 @@ export type TypedAction<
   get<TField extends keyof Out & string>(
     field: TField,
   ): TypedAction<In, Out[TField], Refs>;
+  /** Wrap output in an object under a field name. `a.wrapInField("foo")` ≡ `pipe(a, wrapInField("foo"))`. */
+  wrapInField<TField extends string>(
+    field: TField,
+  ): TypedAction<In, Record<TField, 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>;
+  /** Head/tail decomposition. Only callable when Out is TElement[]. */
+  splitFirst<TIn, TElement, TRefs extends string>(
+    this: TypedAction<TIn, TElement[], TRefs>,
+  ): TypedAction<TIn, Option<[TElement, TElement[]]>, TRefs>;
+  /** Init/last decomposition. Only callable when Out is TElement[]. */
+  splitLast<TIn, TElement, TRefs extends string>(
+    this: TypedAction<TIn, TElement[], TRefs>,
+  ): TypedAction<TIn, Option<[TElement[], TElement]>, TRefs>;
   /**
    * Transform the Some value inside an Option output. Only callable when
    * Out is Option<T>. Uses `this` parameter constraint to gate availability.
@@ -428,6 +442,20 @@ function getMethod(this: TypedAction, field: string): TypedAction {
   });
 }
 
+function wrapInFieldMethod(this: TypedAction, field: string): TypedAction {
+  return typedAction({
+    kind: "Chain",
+    first: this,
+    rest: {
+      kind: "Invoke",
+      handler: {
+        kind: "Builtin",
+        builtin: { kind: "WrapInField", value: field },
+      },
+    },
+  });
+}
+
 function mergeMethod(this: TypedAction): TypedAction {
   return typedAction({
     kind: "Chain",
@@ -450,6 +478,28 @@ function pickMethod(this: TypedAction, ...keys: string[]): TypedAction {
   });
 }
 
+function splitFirstMethod(this: TypedAction): TypedAction {
+  return typedAction({
+    kind: "Chain",
+    first: this,
+    rest: {
+      kind: "Invoke",
+      handler: { kind: "Builtin", builtin: { kind: "SplitFirst" } },
+    },
+  });
+}
+
+function splitLastMethod(this: TypedAction): TypedAction {
+  return typedAction({
+    kind: "Chain",
+    first: this,
+    rest: {
+      kind: "Invoke",
+      handler: { kind: "Builtin", builtin: { kind: "SplitLast" } },
+    },
+  });
+}
+
 function mapOptionMethod(this: TypedAction, action: Action): TypedAction {
   // Desugars to: self.then(branch({ Some: pipe(action, tag("Some")), None: tag("None") }))
   // But branch auto-unwraps value, so:
@@ -545,8 +595,11 @@ export function typedAction<
       drop: { value: dropMethod, configurable: true },
       tag: { value: tagMethod, configurable: true },
       get: { value: getMethod, configurable: true },
+      wrapInField: { value: wrapInFieldMethod, configurable: true },
       merge: { value: mergeMethod, configurable: true },
       pick: { value: pickMethod, configurable: true },
+      splitFirst: { value: splitFirstMethod, configurable: true },
+      splitLast: { value: splitLastMethod, configurable: true },
       mapOption: { value: mapOptionMethod, configurable: true },
       mapErr: { value: mapErrMethod, configurable: true },
       unwrapOr: { value: unwrapOrMethod, configurable: true },

package/src/builtins.ts

@@ -1,5 +1,6 @@
 import {
   type Action,
+  type MergeTuple,
   type Option as OptionT,
   type Pipeable,
   type Result as ResultT,
@@ -70,87 +71,10 @@ export function tag<
 // Merge — merge a tuple of objects into a single object
 // ---------------------------------------------------------------------------
 
-type Obj = Record<string, unknown>;
-
-export function merge<A extends Obj, B extends Obj>(): TypedAction<
-  [A, B],
-  A & B
->;
-export function merge<
-  A extends Obj,
-  B extends Obj,
-  C extends Obj,
->(): TypedAction<[A, B, C], A & B & C>;
-export function merge<
-  A extends Obj,
-  B extends Obj,
-  C extends Obj,
-  D extends Obj,
->(): TypedAction<[A, B, C, D], A & B & C & D>;
-export function merge<
-  A extends Obj,
-  B extends Obj,
-  C extends Obj,
-  D extends Obj,
-  E extends Obj,
->(): TypedAction<[A, B, C, D, E], A & B & C & D & E>;
-export function merge<
-  A extends Obj,
-  B extends Obj,
-  C extends Obj,
-  D extends Obj,
-  E extends Obj,
-  F extends Obj,
->(): TypedAction<[A, B, C, D, E, F], A & B & C & D & E & F>;
-export function merge<
-  A extends Obj,
-  B extends Obj,
-  C extends Obj,
-  D extends Obj,
-  E extends Obj,
-  F extends Obj,
-  G extends Obj,
->(): TypedAction<[A, B, C, D, E, F, G], A & B & C & D & E & F & G>;
-export function merge<
-  A extends Obj,
-  B extends Obj,
-  C extends Obj,
-  D extends Obj,
-  E extends Obj,
-  F extends Obj,
-  G extends Obj,
-  H extends Obj,
->(): TypedAction<[A, B, C, D, E, F, G, H], A & B & C & D & E & F & G & H>;
-export function merge<
-  A extends Obj,
-  B extends Obj,
-  C extends Obj,
-  D extends Obj,
-  E extends Obj,
-  F extends Obj,
-  G extends Obj,
-  H extends Obj,
-  I extends Obj,
->(): TypedAction<
-  [A, B, C, D, E, F, G, H, I],
-  A & B & C & D & E & F & G & H & I
->;
-export function merge<
-  A extends Obj,
-  B extends Obj,
-  C extends Obj,
-  D extends Obj,
-  E extends Obj,
-  F extends Obj,
-  G extends Obj,
-  H extends Obj,
-  I extends Obj,
-  J extends Obj,
->(): TypedAction<
-  [A, B, C, D, E, F, G, H, I, J],
-  A & B & C & D & E & F & G & H & I & J
->;
-export function merge(): Action {
+export function merge<TTuple extends Record<string, unknown>[]>(): TypedAction<
+  TTuple,
+  MergeTuple<TTuple>
+> {
   return typedAction({
     kind: "Invoke",
     handler: { kind: "Builtin", builtin: { kind: "Merge" } },
@@ -393,6 +317,55 @@ export function range(start: number, end: number): TypedAction<any, number[]> {
   });
 }
 
+// ---------------------------------------------------------------------------
+// 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" } },
+  });
+}
+
 // ---------------------------------------------------------------------------
 // Option namespace — combinators for Option<T> tagged unions
 // ---------------------------------------------------------------------------

package/src/index.ts

@@ -15,6 +15,8 @@ export {
   withResource,
   tap,
   range,
+  splitFirst,
+  splitLast,
   wrapInField,
   Option,
   Result,