@barnum/barnum 0.0.0-main-ef57b8fd → 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;
@@ -138,6 +142,10 @@ export type TypedAction<In = unknown, Out = unknown, Refs extends string = never
     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

@@ -95,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:
@@ -186,6 +206,8 @@ export function typedAction(action) {
             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

@@ -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

@@ -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

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-ef57b8fd",
+  "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 };
 
@@ -195,6 +197,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.
@@ -468,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:
@@ -566,6 +598,8 @@ export function typedAction<
       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

@@ -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
 // ---------------------------------------------------------------------------

package/src/index.ts

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