@barnum/barnum 0.0.0-main-ef57b8fd → 0.0.0-main-39525152

package/dist/ast.d.ts

@@ -68,16 +68,20 @@ export type BuiltinKind = {
 } | {
     kind: "Flatten";
 } | {
-    kind: "ExtractField";
+    kind: "GetField";
     value: string;
 } | {
-    kind: "ExtractIndex";
+    kind: "GetIndex";
     value: number;
 } | {
     kind: "Pick";
     value: string[];
 } | {
     kind: "CollectSome";
+} | {
+    kind: "SplitFirst";
+} | {
+    kind: "SplitLast";
 } | {
     kind: "WrapInField";
     value: string;
@@ -130,14 +134,20 @@ export type TypedAction<In = unknown, Out = unknown, Refs extends string = never
     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>;
+    /** Extract a field from the output object. `a.getField("name")` ≡ `pipe(a, getField("name"))`. */
+    getField<TField extends keyof Out & string>(field: TField): TypedAction<In, Out[TField], Refs>;
+    /** Extract an element from the output tuple by index. `a.getIndex(0)` ≡ `pipe(a, getIndex(0))`. */
+    getIndex<TIn, TTuple extends unknown[], TIndex extends number, TRefs extends string>(this: TypedAction<TIn, TTuple, TRefs>, index: TIndex): TypedAction<TIn, TTuple[TIndex], TRefs>;
     /** 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.
@@ -331,7 +341,7 @@ export declare const IDENTITY: Action;
  * 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)`
+ * Compiled form: `RestartHandle(id, GetIndex(0), body)`
  */
 export declare function recur<TIn = never, TOut = any>(bodyFn: (restart: TypedAction<TIn, never>) => Pipeable<TIn, TOut>): TypedAction<PipeIn<TIn>, TOut>;
 /**
@@ -349,7 +359,7 @@ export declare function recur<TIn = never, TOut = any>(bodyFn: (restart: TypedAc
 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 })))`
+ * `Chain(Tag("Continue"), RestartHandle(id, GetIndex(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`.

package/dist/ast.js

@@ -49,7 +49,7 @@ function tagMethod(kind) {
         },
     });
 }
-function getMethod(field) {
+function getFieldMethod(field) {
     return typedAction({
         kind: "Chain",
         first: this,
@@ -57,7 +57,20 @@ function getMethod(field) {
             kind: "Invoke",
             handler: {
                 kind: "Builtin",
-                builtin: { kind: "ExtractField", value: field },
+                builtin: { kind: "GetField", value: field },
+            },
+        },
+    });
+}
+function getIndexMethod(index) {
+    return typedAction({
+        kind: "Chain",
+        first: this,
+        rest: {
+            kind: "Invoke",
+            handler: {
+                kind: "Builtin",
+                builtin: { kind: "GetIndex", value: index },
             },
         },
     });
@@ -95,6 +108,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:
@@ -182,10 +215,13 @@ export function typedAction(action) {
             flatten: { value: flattenMethod, configurable: true },
             drop: { value: dropMethod, configurable: true },
             tag: { value: tagMethod, configurable: true },
-            get: { value: getMethod, configurable: true },
+            getField: { value: getFieldMethod, configurable: true },
+            getIndex: { value: getIndexMethod, 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 },
@@ -209,7 +245,7 @@ export function forEach(action) {
     return typedAction({ kind: "ForEach", action: action });
 }
 /**
- * Insert ExtractField("value") before each case handler in a branch.
+ * Insert GetField("value") before each case handler in a branch.
  * This implements auto-unwrapping: the engine dispatches on `kind`, then
  * extracts `value` before passing to the handler. Case handlers receive
  * the payload directly, not the full `{ kind, value }` variant.
@@ -223,7 +259,7 @@ function unwrapBranchCases(cases) {
                 kind: "Invoke",
                 handler: {
                     kind: "Builtin",
-                    builtin: { kind: "ExtractField", value: "value" },
+                    builtin: { kind: "GetField", value: "value" },
                 },
             },
             rest: cases[key],
@@ -240,7 +276,7 @@ export function branch(cases) {
 // ---------------------------------------------------------------------------
 const EXTRACT_PAYLOAD = {
     kind: "Invoke",
-    handler: { kind: "Builtin", builtin: { kind: "ExtractIndex", value: 0 } },
+    handler: { kind: "Builtin", builtin: { kind: "GetIndex", value: 0 } },
 };
 const TAG_CONTINUE = {
     kind: "Invoke",
@@ -264,7 +300,7 @@ export const IDENTITY = {
  * 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)`
+ * Compiled form: `RestartHandle(id, GetIndex(0), body)`
  */
 export function recur(bodyFn) {
     const restartHandlerId = allocateRestartHandlerId();
@@ -310,7 +346,7 @@ export function earlyReturn(bodyFn) {
 // ---------------------------------------------------------------------------
 /**
  * Build the restart+branch compiled form:
- * `Chain(Tag("Continue"), RestartHandle(id, ExtractIndex(0), Branch({ Continue: continueArm, Break: breakArm })))`
+ * `Chain(Tag("Continue"), RestartHandle(id, GetIndex(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`.

package/dist/bind.d.ts

@@ -3,7 +3,7 @@ import { type Action, type ExtractInput, type ExtractOutput, type TypedAction }
  * 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 `extractField` — pipe overloads can't infer
+ * 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<never, TValue>;
@@ -33,7 +33,7 @@ export type InferVarRefs<TBindings extends Action[]> = {
  *     All(...bindings, Identity),
  *     ResumeHandle(r0, readVar(0),
  *       ResumeHandle(r1, readVar(1),
- *         Chain(ExtractIndex(N), body)
+ *         Chain(GetIndex(N), body)
  *       )
  *     )
  *   )

package/dist/bind.js

@@ -18,7 +18,7 @@ function createVarRef(resumeHandlerId) {
  * `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(ExtractIndex(1), ExtractIndex(n)), ExtractIndex(1))
+ * Expanded AST: All(Chain(GetIndex(1), GetIndex(n)), GetIndex(1))
  */
 function readVar(n) {
     return {
@@ -30,14 +30,14 @@ function readVar(n) {
                     kind: "Invoke",
                     handler: {
                         kind: "Builtin",
-                        builtin: { kind: "ExtractIndex", value: 1 },
+                        builtin: { kind: "GetIndex", value: 1 },
                     },
                 },
                 rest: {
                     kind: "Invoke",
                     handler: {
                         kind: "Builtin",
-                        builtin: { kind: "ExtractIndex", value: n },
+                        builtin: { kind: "GetIndex", value: n },
                     },
                 },
             },
@@ -45,7 +45,7 @@ function readVar(n) {
                 kind: "Invoke",
                 handler: {
                     kind: "Builtin",
-                    builtin: { kind: "ExtractIndex", value: 1 },
+                    builtin: { kind: "GetIndex", value: 1 },
                 },
             },
         ],
@@ -67,7 +67,7 @@ export function bind(bindings, body) {
             kind: "Invoke",
             handler: {
                 kind: "Builtin",
-                builtin: { kind: "ExtractIndex", value: pipelineInputIndex },
+                builtin: { kind: "GetIndex", value: pipelineInputIndex },
             },
         },
         rest: bodyAction,

package/dist/builtins.d.ts

@@ -18,8 +18,8 @@ export declare const drop: TypedAction<any, never>;
 export declare function tag<TDef extends Record<string, unknown>, TKind extends keyof TDef & string>(kind: TKind): TypedAction<TDef[TKind], TaggedUnion<TDef>>;
 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]>;
+export declare function getField<TObj extends Record<string, unknown>, TField extends keyof TObj & string>(field: TField): TypedAction<TObj, TObj[TField]>;
+export declare function getIndex<TTuple extends unknown[], TIndex extends number>(index: TIndex): TypedAction<TTuple, TTuple[TIndex]>;
 export declare function pick<TObj extends Record<string, unknown>, TKeys extends (keyof TObj & string)[]>(...keys: TKeys): TypedAction<TObj, Pick<TObj, TKeys[number]>>;
 export declare function dropResult<TInput, TOutput>(action: Pipeable<TInput, TOutput>): TypedAction<TInput, never>;
 /**
@@ -57,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

package/dist/builtins.js

@@ -64,26 +64,26 @@ export function flatten() {
     });
 }
 // ---------------------------------------------------------------------------
-// ExtractField — extract a single field from an object
+// GetField — extract a single field from an object
 // ---------------------------------------------------------------------------
-export function extractField(field) {
+export function getField(field) {
     return typedAction({
         kind: "Invoke",
         handler: {
             kind: "Builtin",
-            builtin: { kind: "ExtractField", value: field },
+            builtin: { kind: "GetField", value: field },
         },
     });
 }
 // ---------------------------------------------------------------------------
-// ExtractIndex — extract a single element from an array by index
+// GetIndex — extract a single element from an array by index
 // ---------------------------------------------------------------------------
-export function extractIndex(index) {
+export function getIndex(index) {
     return typedAction({
         kind: "Invoke",
         handler: {
             kind: "Builtin",
-            builtin: { kind: "ExtractIndex", value: index },
+            builtin: { kind: "GetIndex", value: index },
         },
     });
 }
@@ -146,16 +146,16 @@ export function withResource({ create, action, dispose, }) {
         kind: "All",
         actions: [action, identity],
     });
-    // Step 3: all(extractIndex(0), chain(extractIndex(1), dispose)) → [TOut, unknown]
+    // Step 3: all(getIndex(0), chain(getIndex(1), dispose)) → [TOut, unknown]
     const disposeAndKeepResult = typedAction({
         kind: "All",
         actions: [
-            extractIndex(0),
-            chain(extractIndex(1), dispose),
+            getIndex(0),
+            chain(getIndex(1), dispose),
         ],
     });
-    // Step 4: extractIndex(0) → TOut
-    return chain(chain(chain(acquireAndMerge, actionAndKeepMerged), disposeAndKeepResult), extractIndex(0));
+    // Step 4: getIndex(0) → TOut
+    return chain(chain(chain(acquireAndMerge, actionAndKeepMerged), disposeAndKeepResult), getIndex(0));
 }
 // ---------------------------------------------------------------------------
 // Tap — run an action for side effects, preserve original input
@@ -227,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
@@ -242,7 +281,7 @@ const EXTRACT_VALUE = {
     kind: "Invoke",
     handler: {
         kind: "Builtin",
-        builtin: { kind: "ExtractField", value: "value" },
+        builtin: { kind: "GetField", value: "value" },
     },
 };
 const DROP = {
@@ -253,7 +292,7 @@ const IDENTITY = {
     kind: "Invoke",
     handler: { kind: "Builtin", builtin: { kind: "Identity" } },
 };
-/** Wrap branch cases with ExtractField("value") auto-unwrapping. */
+/** Wrap branch cases with GetField("value") auto-unwrapping. */
 function optionBranch(someCaseBody, noneCaseBody) {
     return {
         kind: "Branch",
@@ -416,7 +455,7 @@ const TAG_ERR = {
     kind: "Invoke",
     handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Err" } },
 };
-/** Wrap branch cases with ExtractField("value") auto-unwrapping. */
+/** Wrap branch cases with GetField("value") auto-unwrapping. */
 function resultBranch(okCaseBody, errCaseBody) {
     return {
         kind: "Branch",

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, getField, getIndex, 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, getField, getIndex, 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/dist/race.d.ts

@@ -8,7 +8,7 @@ import { type Pipeable, type Result, type TypedAction } from "./ast.js";
  *
  * Compiled form (restart+Branch, same substrate as loop/earlyReturn):
  *   `Chain(Tag("Continue"),`
- *     `RestartHandle(id, ExtractIndex(0),`
+ *     `RestartHandle(id, GetIndex(0),`
  *       `Branch({`
  *         `Continue: All(Chain(a, breakPerform), Chain(b, breakPerform), ...),`
  *         `Break: identity,`

package/dist/race.js

@@ -35,7 +35,7 @@ function breakPerform(restartHandlerId) {
  *
  * Compiled form (restart+Branch, same substrate as loop/earlyReturn):
  *   `Chain(Tag("Continue"),`
- *     `RestartHandle(id, ExtractIndex(0),`
+ *     `RestartHandle(id, GetIndex(0),`
  *       `Branch({`
  *         `Continue: All(Chain(a, breakPerform), Chain(b, breakPerform), ...),`
  *         `Break: identity,`

package/dist/recursive.js

@@ -1,7 +1,7 @@
 import { typedAction, branch, } from "./ast.js";
 import { all } from "./all.js";
 import { chain } from "./chain.js";
-import { constant, identity, extractField, extractIndex, tag, } from "./builtins.js";
+import { constant, identity, getField, getIndex, tag } from "./builtins.js";
 import { allocateResumeHandlerId } from "./effect-id.js";
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 const UNUSED_STATE = undefined;
@@ -35,10 +35,10 @@ export function defineRecursiveFunctions(bodiesFn) {
     const callTokens = Array.from({ length: fnCount }, (_, i) => typedAction(chain(tag(`Call${i}`), resumePerform)));
     // Get function body ASTs
     const bodyActions = bodiesFn(...callTokens);
-    // Branch cases: CallN → ExtractField("value") → bodyN
+    // Branch cases: CallN → GetField("value") → bodyN
     const cases = {};
     for (let i = 0; i < bodyActions.length; i++) {
-        cases[`Call${i}`] = chain(extractField("value"), bodyActions[i]);
+        cases[`Call${i}`] = chain(getField("value"), bodyActions[i]);
     }
     // Return curried entry-point combinator
     return (entryFn) => {
@@ -46,8 +46,8 @@ export function defineRecursiveFunctions(bodiesFn) {
         return typedAction(chain(all(identity, constant(UNUSED_STATE)), {
             kind: "ResumeHandle",
             resume_handler_id: resumeHandlerId,
-            body: chain(extractIndex(0), userBody),
-            handler: all(chain(extractIndex(0), branch(cases)), constant(UNUSED_STATE)),
+            body: chain(getIndex(0), userBody),
+            handler: all(chain(getIndex(0), branch(cases)), constant(UNUSED_STATE)),
         }));
     };
 }

package/dist/try-catch.d.ts

@@ -12,7 +12,7 @@ import { type Pipeable, type TypedAction } from "./ast.js";
  *
  * Compiled form (restart+Branch, same substrate as loop/earlyReturn):
  *   `Chain(Tag("Continue"),`
- *     `RestartHandle(id, ExtractIndex(0),`
+ *     `RestartHandle(id, GetIndex(0),`
  *       `Branch({ Continue: body, Break: recovery })))`
  *
  * throwError = `Chain(Tag("Break"), RestartPerform(id))`

package/dist/try-catch.js

@@ -16,7 +16,7 @@ import { allocateRestartHandlerId } from "./effect-id.js";
  *
  * Compiled form (restart+Branch, same substrate as loop/earlyReturn):
  *   `Chain(Tag("Continue"),`
- *     `RestartHandle(id, ExtractIndex(0),`
+ *     `RestartHandle(id, GetIndex(0),`
  *       `Branch({ Continue: body, Break: recovery })))`
  *
  * throwError = `Chain(Tag("Break"), RestartPerform(id))`

package/package.json

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

package/src/ast.ts

@@ -91,10 +91,12 @@ export type BuiltinKind =
   | { kind: "Tag"; value: string }
   | { kind: "Merge" }
   | { kind: "Flatten" }
-  | { kind: "ExtractField"; value: string }
-  | { kind: "ExtractIndex"; value: number }
+  | { kind: "GetField"; value: string }
+  | { kind: "GetIndex"; value: number }
   | { kind: "Pick"; value: string[] }
   | { kind: "CollectSome" }
+  | { kind: "SplitFirst" }
+  | { kind: "SplitLast" }
   | { kind: "WrapInField"; value: string }
   | { kind: "Sleep"; value: number };
 
@@ -181,10 +183,20 @@ export type TypedAction<
   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>(
+  /** Extract a field from the output object. `a.getField("name")` ≡ `pipe(a, getField("name"))`. */
+  getField<TField extends keyof Out & string>(
     field: TField,
   ): TypedAction<In, Out[TField], Refs>;
+  /** Extract an element from the output tuple by index. `a.getIndex(0)` ≡ `pipe(a, getIndex(0))`. */
+  getIndex<
+    TIn,
+    TTuple extends unknown[],
+    TIndex extends number,
+    TRefs extends string,
+  >(
+    this: TypedAction<TIn, TTuple, TRefs>,
+    index: TIndex,
+  ): TypedAction<TIn, TTuple[TIndex], TRefs>;
   /** Wrap output in an object under a field name. `a.wrapInField("foo")` ≡ `pipe(a, wrapInField("foo"))`. */
   wrapInField<TField extends string>(
     field: TField,
@@ -195,6 +207,14 @@ export type TypedAction<
   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.
@@ -418,7 +438,7 @@ function tagMethod(this: TypedAction, kind: string): TypedAction {
   });
 }
 
-function getMethod(this: TypedAction, field: string): TypedAction {
+function getFieldMethod(this: TypedAction, field: string): TypedAction {
   return typedAction({
     kind: "Chain",
     first: this,
@@ -426,7 +446,21 @@ function getMethod(this: TypedAction, field: string): TypedAction {
       kind: "Invoke",
       handler: {
         kind: "Builtin",
-        builtin: { kind: "ExtractField", value: field },
+        builtin: { kind: "GetField", value: field },
+      },
+    },
+  });
+}
+
+function getIndexMethod(this: TypedAction, index: number): TypedAction {
+  return typedAction({
+    kind: "Chain",
+    first: this,
+    rest: {
+      kind: "Invoke",
+      handler: {
+        kind: "Builtin",
+        builtin: { kind: "GetIndex", value: index },
       },
     },
   });
@@ -468,6 +502,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:
@@ -562,10 +618,13 @@ export function typedAction<
       flatten: { value: flattenMethod, configurable: true },
       drop: { value: dropMethod, configurable: true },
       tag: { value: tagMethod, configurable: true },
-      get: { value: getMethod, configurable: true },
+      getField: { value: getFieldMethod, configurable: true },
+      getIndex: { value: getIndexMethod, 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 },
@@ -625,7 +684,7 @@ export function forEach<In, Out>(
 }
 
 /**
- * Insert ExtractField("value") before each case handler in a branch.
+ * Insert GetField("value") before each case handler in a branch.
  * This implements auto-unwrapping: the engine dispatches on `kind`, then
  * extracts `value` before passing to the handler. Case handlers receive
  * the payload directly, not the full `{ kind, value }` variant.
@@ -641,7 +700,7 @@ function unwrapBranchCases(
         kind: "Invoke",
         handler: {
           kind: "Builtin",
-          builtin: { kind: "ExtractField", value: "value" },
+          builtin: { kind: "GetField", value: "value" },
         },
       },
       rest: cases[key],
@@ -691,7 +750,7 @@ export type LoopResult<TContinue, TBreak> = TaggedUnion<
 
 const EXTRACT_PAYLOAD: Action = {
   kind: "Invoke",
-  handler: { kind: "Builtin", builtin: { kind: "ExtractIndex", value: 0 } },
+  handler: { kind: "Builtin", builtin: { kind: "GetIndex", value: 0 } },
 };
 
 const TAG_CONTINUE: Action = {
@@ -720,7 +779,7 @@ export const IDENTITY: Action = {
  * 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)`
+ * Compiled form: `RestartHandle(id, GetIndex(0), body)`
  */
 export function recur<TIn = never, TOut = any>(
   bodyFn: (restart: TypedAction<TIn, never>) => Pipeable<TIn, TOut>,
@@ -784,7 +843,7 @@ export function earlyReturn<TEarlyReturn = never, TIn = any, TOut = any>(
 
 /**
  * Build the restart+branch compiled form:
- * `Chain(Tag("Continue"), RestartHandle(id, ExtractIndex(0), Branch({ Continue: continueArm, Break: breakArm })))`
+ * `Chain(Tag("Continue"), RestartHandle(id, GetIndex(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`.

package/src/bind.ts

@@ -17,7 +17,7 @@ import { pipe } from "./pipe.js";
  * 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 `extractField` — pipe overloads can't infer
+ * 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<never, TValue>;
@@ -61,7 +61,7 @@ export type InferVarRefs<TBindings extends Action[]> = {
  * `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(ExtractIndex(1), ExtractIndex(n)), ExtractIndex(1))
+ * Expanded AST: All(Chain(GetIndex(1), GetIndex(n)), GetIndex(1))
  */
 function readVar(n: number): Action {
   return {
@@ -73,14 +73,14 @@ function readVar(n: number): Action {
           kind: "Invoke",
           handler: {
             kind: "Builtin",
-            builtin: { kind: "ExtractIndex", value: 1 },
+            builtin: { kind: "GetIndex", value: 1 },
           },
         },
         rest: {
           kind: "Invoke",
           handler: {
             kind: "Builtin",
-            builtin: { kind: "ExtractIndex", value: n },
+            builtin: { kind: "GetIndex", value: n },
           },
         },
       },
@@ -88,7 +88,7 @@ function readVar(n: number): Action {
         kind: "Invoke",
         handler: {
           kind: "Builtin",
-          builtin: { kind: "ExtractIndex", value: 1 },
+          builtin: { kind: "GetIndex", value: 1 },
         },
       },
     ],
@@ -111,7 +111,7 @@ function readVar(n: number): Action {
  *     All(...bindings, Identity),
  *     ResumeHandle(r0, readVar(0),
  *       ResumeHandle(r1, readVar(1),
- *         Chain(ExtractIndex(N), body)
+ *         Chain(GetIndex(N), body)
  *       )
  *     )
  *   )
@@ -148,7 +148,7 @@ export function bind<TBindings extends Action[], TOut>(
       kind: "Invoke",
       handler: {
         kind: "Builtin",
-        builtin: { kind: "ExtractIndex", value: pipelineInputIndex },
+        builtin: { kind: "GetIndex", value: pipelineInputIndex },
       },
     },
     rest: bodyAction,

package/src/builtins.ts

@@ -93,10 +93,10 @@ export function flatten<TElement>(): TypedAction<TElement[][], TElement[]> {
 }
 
 // ---------------------------------------------------------------------------
-// ExtractField — extract a single field from an object
+// GetField — extract a single field from an object
 // ---------------------------------------------------------------------------
 
-export function extractField<
+export function getField<
   TObj extends Record<string, unknown>,
   TField extends keyof TObj & string,
 >(field: TField): TypedAction<TObj, TObj[TField]> {
@@ -104,23 +104,23 @@ export function extractField<
     kind: "Invoke",
     handler: {
       kind: "Builtin",
-      builtin: { kind: "ExtractField", value: field },
+      builtin: { kind: "GetField", value: field },
     },
   });
 }
 
 // ---------------------------------------------------------------------------
-// ExtractIndex — extract a single element from an array by index
+// GetIndex — extract a single element from an array by index
 // ---------------------------------------------------------------------------
 
-export function extractIndex<TTuple extends unknown[], TIndex extends number>(
+export function getIndex<TTuple extends unknown[], TIndex extends number>(
   index: TIndex,
 ): TypedAction<TTuple, TTuple[TIndex]> {
   return typedAction({
     kind: "Invoke",
     handler: {
       kind: "Builtin",
-      builtin: { kind: "ExtractIndex", value: index },
+      builtin: { kind: "GetIndex", value: index },
     },
   });
 }
@@ -216,25 +216,25 @@ export function withResource<
     actions: [action as Action, identity as Action],
   });
 
-  // Step 3: all(extractIndex(0), chain(extractIndex(1), dispose)) → [TOut, unknown]
+  // Step 3: all(getIndex(0), chain(getIndex(1), dispose)) → [TOut, unknown]
   const disposeAndKeepResult = typedAction<
     [TOut, TResource & TIn],
     [TOut, unknown]
   >({
     kind: "All",
     actions: [
-      extractIndex<[TOut, TResource & TIn], 0>(0) as Action,
+      getIndex<[TOut, TResource & TIn], 0>(0) as Action,
       chain(
-        extractIndex<[TOut, TResource & TIn], 1>(1),
+        getIndex<[TOut, TResource & TIn], 1>(1),
         dispose as Pipeable<TResource & TIn, unknown>,
       ) as Action,
     ],
   });
 
-  // Step 4: extractIndex(0) → TOut
+  // Step 4: getIndex(0) → TOut
   return chain(
     chain(chain(acquireAndMerge, actionAndKeepMerged), disposeAndKeepResult),
-    extractIndex<[TOut, unknown], 0>(0),
+    getIndex<[TOut, unknown], 0>(0),
   ) as TypedAction<TIn, TOut>;
 }
 
@@ -317,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
 // ---------------------------------------------------------------------------
@@ -334,7 +383,7 @@ const EXTRACT_VALUE: Action = {
   kind: "Invoke",
   handler: {
     kind: "Builtin",
-    builtin: { kind: "ExtractField", value: "value" },
+    builtin: { kind: "GetField", value: "value" },
   },
 };
 const DROP: Action = {
@@ -346,7 +395,7 @@ const IDENTITY: Action = {
   handler: { kind: "Builtin", builtin: { kind: "Identity" } },
 };
 
-/** Wrap branch cases with ExtractField("value") auto-unwrapping. */
+/** Wrap branch cases with GetField("value") auto-unwrapping. */
 function optionBranch(someCaseBody: Action, noneCaseBody: Action): Action {
   return {
     kind: "Branch",
@@ -541,7 +590,7 @@ const TAG_ERR: Action = {
   handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Err" } },
 };
 
-/** Wrap branch cases with ExtractField("value") auto-unwrapping. */
+/** Wrap branch cases with GetField("value") auto-unwrapping. */
 function resultBranch(okCaseBody: Action, errCaseBody: Action): Action {
   return {
     kind: "Branch",

package/src/index.ts

@@ -8,13 +8,15 @@ export {
   tag,
   merge,
   flatten,
-  extractField,
-  extractIndex,
+  getField,
+  getIndex,
   pick,
   dropResult,
   withResource,
   tap,
   range,
+  splitFirst,
+  splitLast,
   wrapInField,
   Option,
   Result,

package/src/race.ts

@@ -53,7 +53,7 @@ function breakPerform(restartHandlerId: RestartHandlerId): Action {
  *
  * Compiled form (restart+Branch, same substrate as loop/earlyReturn):
  *   `Chain(Tag("Continue"),`
- *     `RestartHandle(id, ExtractIndex(0),`
+ *     `RestartHandle(id, GetIndex(0),`
  *       `Branch({`
  *         `Continue: All(Chain(a, breakPerform), Chain(b, breakPerform), ...),`
  *         `Break: identity,`

package/src/recursive.ts

@@ -7,13 +7,7 @@ import {
 } from "./ast.js";
 import { all } from "./all.js";
 import { chain } from "./chain.js";
-import {
-  constant,
-  identity,
-  extractField,
-  extractIndex,
-  tag,
-} from "./builtins.js";
+import { constant, identity, getField, getIndex, tag } from "./builtins.js";
 import { allocateResumeHandlerId } from "./effect-id.js";
 
 // ---------------------------------------------------------------------------
@@ -84,11 +78,11 @@ export function defineRecursiveFunctions<TDefs extends FunctionDef[]>(
     ...(callTokens as FunctionRefs<TDefs>),
   ) as Action[];
 
-  // Branch cases: CallN → ExtractField("value") → bodyN
+  // Branch cases: CallN → GetField("value") → bodyN
   const cases: Record<string, Action> = {};
   for (let i = 0; i < bodyActions.length; i++) {
     cases[`Call${i}`] = chain(
-      extractField("value"),
+      getField("value"),
       bodyActions[i] as any,
     ) as Action;
   }
@@ -101,9 +95,9 @@ export function defineRecursiveFunctions<TDefs extends FunctionDef[]>(
       chain(all(identity, constant(UNUSED_STATE)), {
         kind: "ResumeHandle",
         resume_handler_id: resumeHandlerId,
-        body: chain(extractIndex(0), userBody as any) as Action,
+        body: chain(getIndex(0), userBody as any) as Action,
         handler: all(
-          chain(extractIndex(0), branch(cases) as any),
+          chain(getIndex(0), branch(cases) as any),
           constant(UNUSED_STATE),
         ) as Action,
       } as Action) as Action,

package/src/try-catch.ts

@@ -25,7 +25,7 @@ import { allocateRestartHandlerId } from "./effect-id.js";
  *
  * Compiled form (restart+Branch, same substrate as loop/earlyReturn):
  *   `Chain(Tag("Continue"),`
- *     `RestartHandle(id, ExtractIndex(0),`
+ *     `RestartHandle(id, GetIndex(0),`
  *       `Branch({ Continue: body, Break: recovery })))`
  *
  * throwError = `Chain(Tag("Break"), RestartPerform(id))`