@barnum/barnum 0.2.3 → 0.4.0

package/dist/ast.js

@@ -0,0 +1,419 @@
+import { chain } from "./chain.js";
+import { constant, drop, extractPrefix, flatten as flattenBuiltin, getField, getIndex, identity, panic, pick, splitFirst, splitLast, tag, wrapInField, asOption as asOptionStandalone, } from "./builtins/index.js";
+import { Option } from "./option.js";
+import { Result } from "./result.js";
+// Lazy import — iterator.ts imports from ast.ts, but these are only called inside
+// methods (after all modules load), so the circular reference is safe at runtime.
+import { Iterator as IteratorNs } from "./iterator.js";
+// Lazy import — bind.ts imports from ast.ts, but these are only called inside
+// methods (after all modules load), so the circular reference is safe at runtime.
+import { bind as bindStandalone, bindInput as bindInputStandalone, } from "./bind.js";
+/**
+ * Strip phantom types from a Pipeable, returning a plain Action.
+ *
+ * Replaces `x as Action` casts throughout the codebase. The constraint
+ * ensures the argument is structurally a Pipeable — unlike a bare cast,
+ * `toAction(123)` is a type error.
+ */
+export function toAction(pipeable) {
+    return pipeable;
+}
+// ---------------------------------------------------------------------------
+// typedAction — attach .then() and .forEach() as non-enumerable methods
+// ---------------------------------------------------------------------------
+// Shared implementations (one closure, not per-instance)
+function thenMethod(next) {
+    return chain(this, next);
+}
+function branchMethod(cases) {
+    return chain(toAction(this), toAction(branch(cases)));
+}
+function flattenMethod() {
+    return chain(toAction(this), toAction(flattenBuiltin()));
+}
+function dropMethod() {
+    return chain(toAction(this), toAction(drop));
+}
+function tagMethod(kind, enumName) {
+    return chain(toAction(this), toAction(tag(kind, enumName)));
+}
+function someMethod() {
+    return chain(toAction(this), toAction(Option.some()));
+}
+function okMethod() {
+    return chain(toAction(this), toAction(Result.ok()));
+}
+function errMethod() {
+    return chain(toAction(this), toAction(Result.err()));
+}
+function getFieldMethod(field) {
+    return chain(toAction(this), toAction(getField(field)));
+}
+function getIndexMethod(index) {
+    return chain(toAction(this), toAction(getIndex(index)));
+}
+function wrapInFieldMethod(field) {
+    return chain(toAction(this), toAction(wrapInField(field)));
+}
+function pickMethod(...keys) {
+    return chain(toAction(this), toAction(pick(...keys)));
+}
+function splitFirstMethod() {
+    return chain(toAction(this), toAction(branchFamily({
+        Iterator: IteratorNs.splitFirst(),
+        Array: splitFirst(),
+    })));
+}
+function splitLastMethod() {
+    return chain(toAction(this), toAction(branchFamily({
+        Iterator: IteratorNs.splitLast(),
+        Array: splitLast(),
+    })));
+}
+// --- Shared postfix methods (Option + Result) — dispatch via branchFamily ---
+function mapMethod(action) {
+    return chain(toAction(this), toAction(branchFamily({
+        Result: branch({
+            Ok: chain(toAction(action), toAction(Result.ok())),
+            Err: Result.err(),
+        }),
+        Option: branch({
+            Some: chain(toAction(action), toAction(Option.some())),
+            None: Option.none(),
+        }),
+        Iterator: IteratorNs.map(action),
+    })));
+}
+function unwrapMethod() {
+    return chain(toAction(this), toAction(branchFamily({
+        Result: branch({ Ok: identity(), Err: panic("called unwrap on Err") }),
+        Option: branch({
+            Some: identity(),
+            None: panic("called unwrap on None"),
+        }),
+    })));
+}
+function unwrapOrMethod(defaultAction) {
+    return chain(toAction(this), toAction(branchFamily({
+        Result: branch({ Ok: identity(), Err: defaultAction }),
+        Option: branch({ Some: identity(), None: defaultAction }),
+    })));
+}
+function andThenMethod(action) {
+    return chain(toAction(this), toAction(branchFamily({
+        Result: branch({ Ok: action, Err: Result.err() }),
+        Option: branch({ Some: action, None: Option.none() }),
+    })));
+}
+function transposeMethod() {
+    return chain(toAction(this), toAction(branchFamily({
+        Option: branch({
+            Some: branch({
+                Ok: chain(toAction(Option.some()), toAction(Result.ok())),
+                Err: Result.err(),
+            }),
+            None: chain(toAction(chain(toAction(drop), toAction(Option.none()))), toAction(Result.ok())),
+        }),
+        Result: branch({
+            Ok: branch({
+                Some: chain(toAction(Result.ok()), toAction(Option.some())),
+                None: chain(toAction(drop), toAction(Option.none())),
+            }),
+            Err: chain(toAction(Result.err()), toAction(Option.some())),
+        }),
+    })));
+}
+// --- Result-only postfix methods ---
+function mapErrMethod(action) {
+    return chain(toAction(this), toAction(branch({
+        Ok: Result.ok(),
+        Err: chain(toAction(action), toAction(Result.err())),
+    })));
+}
+function orMethod(fallback) {
+    return chain(toAction(this), toAction(branch({
+        Ok: Result.ok(),
+        Err: fallback,
+    })));
+}
+function asOkOptionMethod() {
+    return chain(toAction(this), toAction(branch({
+        Ok: Option.some(),
+        Err: chain(toAction(drop), toAction(Option.none())),
+    })));
+}
+function asErrOptionMethod() {
+    return chain(toAction(this), toAction(branch({
+        Ok: chain(toAction(drop), toAction(Option.none())),
+        Err: Option.some(),
+    })));
+}
+function isOkMethod() {
+    return chain(toAction(this), toAction(branch({
+        Ok: constant(true),
+        Err: constant(false),
+    })));
+}
+function isErrMethod() {
+    return chain(toAction(this), toAction(branch({
+        Ok: constant(false),
+        Err: constant(true),
+    })));
+}
+// --- Option-only postfix methods ---
+function filterMethod(predicate) {
+    return chain(toAction(this), toAction(branchFamily({
+        Option: branch({
+            Some: predicate,
+            None: Option.none(),
+        }),
+        Iterator: IteratorNs.filter(predicate),
+    })));
+}
+function isSomeMethod() {
+    return chain(toAction(this), toAction(branch({
+        Some: constant(true),
+        None: constant(false),
+    })));
+}
+function isNoneMethod() {
+    return chain(toAction(this), toAction(branch({
+        Some: constant(false),
+        None: constant(true),
+    })));
+}
+function asOptionMethod() {
+    return chain(toAction(this), toAction(asOptionStandalone()));
+}
+// --- Iterator postfix methods ---
+function iterateMethod() {
+    return chain(toAction(this), toAction(branchFamily({
+        Option: IteratorNs.fromOption(),
+        Result: IteratorNs.fromResult(),
+        Array: IteratorNs.fromArray(),
+    })));
+}
+function flatMapMethod(action) {
+    return chain(toAction(this), toAction(IteratorNs.flatMap(action)));
+}
+function collectMethod() {
+    return chain(toAction(this), toAction(branchFamily({
+        Array: Option.collect(),
+        Iterator: IteratorNs.collect(),
+    })));
+}
+function foldMethod(init, body) {
+    return chain(toAction(this), toAction(IteratorNs.fold(init, body)));
+}
+function isEmptyMethod() {
+    return chain(toAction(this), toAction(IteratorNs.isEmpty()));
+}
+function sliceMethod(start, end) {
+    return chain(toAction(this), toAction(IteratorNs.slice(start, end)));
+}
+function takeMethod(n) {
+    return chain(toAction(this), toAction(IteratorNs.take(n)));
+}
+function skipMethod(n) {
+    return chain(toAction(this), toAction(IteratorNs.skip(n)));
+}
+function bindMethod(bindings, body) {
+    return chain(toAction(this), toAction(bindStandalone(bindings, body)));
+}
+function bindInputMethod(body) {
+    return chain(toAction(this), toAction(bindInputStandalone(body)));
+}
+/**
+ * Attach `.then()` and `.forEach()` methods to a plain Action object.
+ * Methods are non-enumerable: invisible to JSON.stringify and toEqual.
+ */
+export function typedAction(action) {
+    if (!("then" in action)) {
+        Object.defineProperties(action, {
+            then: { value: thenMethod, configurable: true },
+            branch: { value: branchMethod, configurable: true },
+            flatten: { value: flattenMethod, configurable: true },
+            drop: { value: dropMethod, configurable: true },
+            tag: { value: tagMethod, configurable: true },
+            some: { value: someMethod, configurable: true },
+            ok: { value: okMethod, configurable: true },
+            err: { value: errMethod, configurable: true },
+            getField: { value: getFieldMethod, configurable: true },
+            getIndex: { value: getIndexMethod, configurable: true },
+            wrapInField: { value: wrapInFieldMethod, configurable: true },
+            pick: { value: pickMethod, configurable: true },
+            splitFirst: { value: splitFirstMethod, configurable: true },
+            splitLast: { value: splitLastMethod, configurable: true },
+            map: { value: mapMethod, configurable: true },
+            mapErr: { value: mapErrMethod, configurable: true },
+            unwrap: { value: unwrapMethod, configurable: true },
+            unwrapOr: { value: unwrapOrMethod, configurable: true },
+            andThen: { value: andThenMethod, configurable: true },
+            filter: { value: filterMethod, configurable: true },
+            isSome: { value: isSomeMethod, configurable: true },
+            isNone: { value: isNoneMethod, configurable: true },
+            asOption: { value: asOptionMethod, configurable: true },
+            collect: { value: collectMethod, configurable: true },
+            fold: { value: foldMethod, configurable: true },
+            isEmpty: { value: isEmptyMethod, configurable: true },
+            slice: { value: sliceMethod, configurable: true },
+            take: { value: takeMethod, configurable: true },
+            skip: { value: skipMethod, configurable: true },
+            or: { value: orMethod, configurable: true },
+            iterate: { value: iterateMethod, configurable: true },
+            flatMap: { value: flatMapMethod, configurable: true },
+            asOkOption: { value: asOkOptionMethod, configurable: true },
+            asErrOption: { value: asErrOptionMethod, configurable: true },
+            isOk: { value: isOkMethod, configurable: true },
+            isErr: { value: isErrMethod, configurable: true },
+            transpose: { value: transposeMethod, configurable: true },
+            bind: { value: bindMethod, configurable: true },
+            bindInput: { value: bindInputMethod, configurable: true },
+        });
+    }
+    return action;
+}
+// ---------------------------------------------------------------------------
+// Combinators
+// ---------------------------------------------------------------------------
+export { pipe } from "./pipe.js";
+export { chain } from "./chain.js";
+export { all } from "./all.js";
+export { bind, bindInput } from "./bind.js";
+export { defineRecursiveFunctions } from "./recursive.js";
+export { resetEffectIdCounter } from "./effect-id.js";
+import { allocateRestartHandlerId, } from "./effect-id.js";
+export { tryCatch } from "./try-catch.js";
+export { race, sleep, withTimeout } from "./race.js";
+export function forEach(action) {
+    return typedAction({ kind: "ForEach", action: toAction(action) });
+}
+/**
+ * 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.
+ */
+function unwrapBranchCases(cases) {
+    const unwrapped = {};
+    for (const key of Object.keys(cases)) {
+        unwrapped[key] = toAction(chain(toAction(getField("value")), toAction(cases[key])));
+    }
+    return unwrapped;
+}
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function branch(cases) {
+    return typedAction({ kind: "Branch", cases: unwrapBranchCases(cases) });
+}
+/**
+ * Two-level dispatch: extract the enum prefix from a tagged value's `kind`,
+ * then branch on that prefix. Used by postfix methods (`.map()`, `.unwrapOr()`,
+ * etc.) to dispatch across union families (Option, Result) without runtime
+ * metadata.
+ *
+ * `branchFamily({ Result: ..., Option: ... })` ≡ `chain(extractPrefix(), branch(cases))`
+ */
+export function branchFamily(cases) {
+    return typedAction({
+        kind: "Chain",
+        first: toAction(extractPrefix()),
+        rest: toAction(branch(cases)),
+    });
+}
+// ---------------------------------------------------------------------------
+// recur — restart body primitive
+// ---------------------------------------------------------------------------
+/**
+ * Restartable scope. The body callback receives `restart`, a TypedAction that
+ * re-executes the body from the beginning with a new input value.
+ *
+ * If the body completes normally → output is TOut.
+ * If restart fires → body re-executes with the restarted value.
+ *
+ * Compiled form: `RestartHandle(id, GetIndex(0), body)`
+ */
+export function recur(bodyFn) {
+    const restartHandlerId = allocateRestartHandlerId();
+    const restartAction = typedAction({
+        kind: "RestartPerform",
+        restart_handler_id: restartHandlerId,
+    });
+    const body = toAction(bodyFn(restartAction));
+    return typedAction({
+        kind: "RestartHandle",
+        restart_handler_id: restartHandlerId,
+        body,
+        handler: toAction(getIndex(0).unwrap()),
+    });
+}
+// ---------------------------------------------------------------------------
+// earlyReturn — exit scope primitive (built on restart + Branch)
+// ---------------------------------------------------------------------------
+/**
+ * Early return scope. The body callback receives `earlyReturn`, a TypedAction
+ * that exits the scope immediately with the returned value.
+ *
+ * If the body completes normally → output is TOut.
+ * If earlyReturn fires → output is TEarlyReturn.
+ * Combined output: TEarlyReturn | TOut.
+ *
+ * Built on the restart mechanism: input is tagged Continue, body runs inside
+ * a Branch. earlyReturn tags with Break and performs — the handler restarts
+ * the body, Branch takes the Break path, and the value exits.
+ */
+export function earlyReturn(bodyFn) {
+    const restartHandlerId = allocateRestartHandlerId();
+    const earlyReturnAction = typedAction(toAction(chain(toAction(tag("Break", "LoopResult")), {
+        kind: "RestartPerform",
+        restart_handler_id: restartHandlerId,
+    })));
+    const body = toAction(bodyFn(earlyReturnAction));
+    return typedAction(buildRestartBranchAction(restartHandlerId, body, toAction(identity())));
+}
+// ---------------------------------------------------------------------------
+// loop — iterative restart with break
+// ---------------------------------------------------------------------------
+/**
+ * Build the restart+branch compiled form:
+ * `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`.
+ *
+ * Used by earlyReturn, loop, tryCatch, and race.
+ */
+export function buildRestartBranchAction(restartHandlerId, continueArm, breakArm) {
+    return toAction(chain(toAction(tag("Continue", "LoopResult")), {
+        kind: "RestartHandle",
+        restart_handler_id: restartHandlerId,
+        body: toAction(branch({ Continue: continueArm, Break: breakArm })),
+        handler: toAction(getIndex(0).unwrap()),
+    }));
+}
+/**
+ * Iterative loop. The body callback receives `recur` and `done`:
+ * - `recur`: restart the loop with a new input
+ * - `done`: exit the loop with the break value
+ *
+ * Both are TypedAction values (not functions), consistent with throwError in tryCatch.
+ *
+ * Compiles to `RestartHandle`/`RestartPerform`/Branch — same effect substrate as tryCatch and earlyReturn.
+ */
+export function loop(bodyFn) {
+    const restartHandlerId = allocateRestartHandlerId();
+    const perform = {
+        kind: "RestartPerform",
+        restart_handler_id: restartHandlerId,
+    };
+    const recurAction = typedAction(toAction(chain(toAction(tag("Continue", "LoopResult")), toAction(perform))));
+    const doneAction = typedAction(toAction(chain(toAction(tag("Break", "LoopResult")), toAction(perform))));
+    const body = toAction(bodyFn(recurAction, doneAction));
+    return typedAction(buildRestartBranchAction(restartHandlerId, body, toAction(identity())));
+}
+// ---------------------------------------------------------------------------
+// Config builders
+// ---------------------------------------------------------------------------
+/** Simple config factory. */
+export function config(workflow) {
+    return { workflow };
+}

package/dist/bind.d.ts

@@ -0,0 +1,59 @@
+import { type Action, type ExtractInput, type ExtractOutput, type TypedAction } from "./ast.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 `getField` — pipe overloads can't infer
+ * the generic's type parameter from the VarRef's output.
+ */
+export type VarRef<TValue> = TypedAction<any, TValue>;
+/**
+ * Maps each binding's output type to a VarRef. TypeScript resolves
+ * ExtractOutput from each binding expression.
+ *
+ * Constraint is `Action[]` (not `Pipeable<any, any>[]`) so that
+ * `ExtractOutput` extracts the correct output type from the phantom
+ * fields on the concrete types without fighting invariant `__in` checks.
+ */
+export type InferVarRefs<TBindings extends Action[]> = {
+    [K in keyof TBindings]: VarRef<ExtractOutput<TBindings[K]>>;
+};
+/**
+ * Bind concurrent values as VarRefs available throughout the body.
+ *
+ * All bindings are actions (Pipeable) evaluated concurrently with the
+ * pipeline input. The body callback receives an array of VarRefs,
+ * one per binding.
+ *
+ * Compiles to:
+ *   Chain(
+ *     All(...bindings, Identity),
+ *     ResumeHandle(r0, readVar(0),
+ *       ResumeHandle(r1, readVar(1),
+ *         Chain(GetIndex(N), body)
+ *       )
+ *     )
+ *   )
+ */
+/**
+ * Constraint for the body callback return type. Only requires the output
+ * phantom field — omits `__in` and `__in_co` so that body actions with
+ * any input type (e.g. pipelines starting from a VarRef) are assignable.
+ */
+type BodyResult<TOut> = Action & {
+    __out?: () => TOut;
+};
+export declare function bind<TBindings extends Action[], TOut>(bindings: [...TBindings], body: (vars: InferVarRefs<TBindings>) => BodyResult<TOut>): TypedAction<ExtractInput<TBindings[number]>, TOut>;
+/**
+ * Convenience wrapper for the common pattern of capturing the pipeline
+ * input as a VarRef. The body's pipeline input is `never` — the input
+ * is dropped, so the body must access it through the VarRef.
+ *
+ * Sugar for: `bind([identity()], ([input]) => pipe(drop, body(input)))`
+ *
+ * TOut defaults to `any` so callers can specify just TIn:
+ *   bindInput<FileEntry>((entry) => ...)
+ */
+export declare function bindInput<TIn, TOut = any>(body: (input: VarRef<TIn>) => BodyResult<TOut>): TypedAction<TIn, TOut>;
+export {};
+//# sourceMappingURL=bind.d.ts.map

package/dist/bind.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bind.d.ts","sourceRoot":"","sources":["../src/bind.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,EACX,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,WAAW,EAGjB,MAAM,UAAU,CAAC;AAWlB;;;;;;GAMG;AACH,MAAM,MAAM,MAAM,CAAC,MAAM,IAAI,WAAW,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AAetD;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,CAAC,SAAS,SAAS,MAAM,EAAE,IAAI;KACpD,CAAC,IAAI,MAAM,SAAS,GAAG,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;CAC5D,CAAC;AA4BF;;;;;;;;;;;;;;;;GAgBG;AACH;;;;GAIG;AACH,KAAK,UAAU,CAAC,IAAI,IAAI,MAAM,GAAG;IAC/B,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;CACpB,CAAC;AAEF,wBAAgB,IAAI,CAAC,SAAS,SAAS,MAAM,EAAE,EAAE,IAAI,EACnD,QAAQ,EAAE,CAAC,GAAG,SAAS,CAAC,EACxB,IAAI,EAAE,CAAC,IAAI,EAAE,YAAY,CAAC,SAAS,CAAC,KAAK,UAAU,CAAC,IAAI,CAAC,GACxD,WAAW,CAAC,YAAY,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,CAkCpD;AAMD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,GAAG,EAAE,IAAI,GAAG,GAAG,EACvC,IAAI,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,UAAU,CAAC,IAAI,CAAC,GAC7C,WAAW,CAAC,GAAG,EAAE,IAAI,CAAC,CAExB"}

package/dist/bind.js

@@ -0,0 +1,69 @@
+import { toAction, typedAction, } from "./ast.js";
+import { chain } from "./chain.js";
+import { all } from "./all.js";
+import { identity, drop, getIndex } from "./builtins/index.js";
+import { allocateResumeHandlerId } from "./effect-id.js";
+import { pipe } from "./pipe.js";
+function createVarRef(resumeHandlerId) {
+    return typedAction({
+        kind: "ResumePerform",
+        resume_handler_id: resumeHandlerId,
+    });
+}
+// ---------------------------------------------------------------------------
+// readVar — handler DAG for the nth binding
+// ---------------------------------------------------------------------------
+/**
+ * Returns an action that extracts the nth value from the ResumeHandle's
+ * state tuple and passes state through unchanged. When a ResumePerform
+ * fires, the engine calls the handler with `[payload, state]`. For bind,
+ * `state` (index 1) is the full All output tuple. The handler produces
+ * `[state[n], state]` — value is state[n], new_state is state (unchanged).
+ *
+ * Expanded AST: All(Chain(GetIndex(1).unwrap(), GetIndex(n).unwrap()), GetIndex(1).unwrap())
+ */
+function readVar(n) {
+    return toAction(all(chain(toAction(getIndex(1).unwrap()), toAction(getIndex(n).unwrap())), toAction(getIndex(1).unwrap())));
+}
+export function bind(bindings, body) {
+    // 1. Gensym one resumeHandlerId per binding.
+    const resumeHandlerIds = bindings.map(() => allocateResumeHandlerId());
+    // 2. Create VarRefs (ResumePerform nodes) for each binding.
+    const varRefs = resumeHandlerIds.map((id) => createVarRef(id));
+    // 3. Invoke the body callback with the VarRefs.
+    const bodyAction = toAction(body(varRefs));
+    // 4. Build nested Handles from inside out.
+    //    Innermost: extract pipeline_input (last All element) → user body
+    const pipelineInputIndex = bindings.length;
+    let inner = toAction(chain(toAction(getIndex(pipelineInputIndex).unwrap()), toAction(bodyAction)));
+    for (let i = resumeHandlerIds.length - 1; i >= 0; i--) {
+        inner = {
+            kind: "ResumeHandle",
+            resume_handler_id: resumeHandlerIds[i],
+            handler: readVar(i),
+            body: inner,
+        };
+    }
+    // 5. All(...bindings, identity()) → nested Handles
+    const allAction = {
+        kind: "All",
+        actions: [...bindings.map((b) => toAction(b)), toAction(identity())],
+    };
+    return typedAction(toAction(chain(toAction(allAction), toAction(inner))));
+}
+// ---------------------------------------------------------------------------
+// bindInput — bind the pipeline input
+// ---------------------------------------------------------------------------
+/**
+ * Convenience wrapper for the common pattern of capturing the pipeline
+ * input as a VarRef. The body's pipeline input is `never` — the input
+ * is dropped, so the body must access it through the VarRef.
+ *
+ * Sugar for: `bind([identity()], ([input]) => pipe(drop, body(input)))`
+ *
+ * TOut defaults to `any` so callers can specify just TIn:
+ *   bindInput<FileEntry>((entry) => ...)
+ */
+export function bindInput(body) {
+    return bind([identity()], ([input]) => pipe(drop, body(input)));
+}

package/dist/builtins/array.d.ts

@@ -0,0 +1,36 @@
+import { type Option as OptionT, type TypedAction } from "../ast.js";
+export declare function getIndex<TTuple extends unknown[], TIndex extends number>(index: TIndex): TypedAction<TTuple, OptionT<TTuple[TIndex]>>;
+export declare function flatten<TElement>(): TypedAction<TElement[][], TElement[]>;
+/**
+ * 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]>>;
+/**
+ * Slice an array from `start` (inclusive) to `end` (exclusive).
+ * `T[] → T[]`
+ *
+ * Both indices are clamped to array length. If `end` is omitted, slices
+ * to the end of the array. Returns empty array if `start >= end`.
+ */
+export declare function slice<TElement>(start: number, end?: number): TypedAction<TElement[], TElement[]>;
+export declare function range(start: number, end: number): TypedAction<any, number[]>;
+//# sourceMappingURL=array.d.ts.map

package/dist/builtins/array.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../src/builtins/array.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,MAAM,IAAI,OAAO,EACtB,KAAK,WAAW,EAEjB,MAAM,WAAW,CAAC;AAMnB,wBAAgB,QAAQ,CAAC,MAAM,SAAS,OAAO,EAAE,EAAE,MAAM,SAAS,MAAM,EACtE,KAAK,EAAE,MAAM,GACZ,WAAW,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAQ9C;AAMD,wBAAgB,OAAO,CAAC,QAAQ,KAAK,WAAW,CAAC,QAAQ,EAAE,EAAE,EAAE,QAAQ,EAAE,CAAC,CAKzE;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,UAAU,CAAC,QAAQ,KAAK,WAAW,CACjD,QAAQ,EAAE,EACV,OAAO,CAAC,CAAC,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC,CAChC,CAKA;AAMD;;;;;;;;;GASG;AACH,wBAAgB,SAAS,CAAC,QAAQ,KAAK,WAAW,CAChD,QAAQ,EAAE,EACV,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,QAAQ,CAAC,CAAC,CAChC,CAKA;AAMD;;;;;;GAMG;AACH,wBAAgB,KAAK,CAAC,QAAQ,EAC5B,KAAK,EAAE,MAAM,EACb,GAAG,CAAC,EAAE,MAAM,GACX,WAAW,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,CAAC,CASrC;AAMD,wBAAgB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,CAAC,CAS5E"}

package/dist/builtins/array.js

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