@barnum/barnum 0.3.0 → 0.4.0

package/dist/builtins.js

@@ -1,600 +0,0 @@
-import { typedAction, } from "./ast.js";
-import { chain } from "./chain.js";
-/**
- * Typed combinators for structural data transformations.
- *
- * All builtins emit `{ kind: "Builtin", builtin: { kind: ... } }` handler
- * kinds. The Rust scheduler executes them inline (no subprocess).
- */
-// ---------------------------------------------------------------------------
-// Constant — produce a fixed value (takes no pipeline input)
-// ---------------------------------------------------------------------------
-export function constant(value) {
-    return typedAction({
-        kind: "Invoke",
-        handler: { kind: "Builtin", builtin: { kind: "Constant", value } },
-    });
-}
-// ---------------------------------------------------------------------------
-// Identity — pass input through unchanged
-// ---------------------------------------------------------------------------
-export const identity = typedAction({
-    kind: "Invoke",
-    handler: { kind: "Builtin", builtin: { kind: "Identity" } },
-});
-// ---------------------------------------------------------------------------
-// Drop — discard pipeline value
-// ---------------------------------------------------------------------------
-export const drop = typedAction({
-    kind: "Invoke",
-    handler: { kind: "Builtin", builtin: { kind: "Drop" } },
-});
-// ---------------------------------------------------------------------------
-// Tag — wrap input as a tagged union variant
-// ---------------------------------------------------------------------------
-/**
- * Wrap input as a tagged union member. Requires the full variant map TDef
- * so the output type carries __def for branch decomposition.
- *
- * Usage: tag<{ Ok: string; Err: number }, "Ok">("Ok")
- *        input: string → output: TaggedUnion<{ Ok: string; Err: number }>
- */
-export function tag(kind) {
-    return typedAction({
-        kind: "Invoke",
-        handler: { kind: "Builtin", builtin: { kind: "Tag", value: kind } },
-    });
-}
-export function merge() {
-    return typedAction({
-        kind: "Invoke",
-        handler: { kind: "Builtin", builtin: { kind: "Merge" } },
-    });
-}
-// ---------------------------------------------------------------------------
-// Flatten — flatten a nested array one level
-// ---------------------------------------------------------------------------
-export function flatten() {
-    return typedAction({
-        kind: "Invoke",
-        handler: { kind: "Builtin", builtin: { kind: "Flatten" } },
-    });
-}
-// ---------------------------------------------------------------------------
-// ExtractField — extract a single field from an object
-// ---------------------------------------------------------------------------
-export function extractField(field) {
-    return typedAction({
-        kind: "Invoke",
-        handler: {
-            kind: "Builtin",
-            builtin: { kind: "ExtractField", value: field },
-        },
-    });
-}
-// ---------------------------------------------------------------------------
-// ExtractIndex — extract a single element from an array by index
-// ---------------------------------------------------------------------------
-export function extractIndex(index) {
-    return typedAction({
-        kind: "Invoke",
-        handler: {
-            kind: "Builtin",
-            builtin: { kind: "ExtractIndex", value: index },
-        },
-    });
-}
-// ---------------------------------------------------------------------------
-// Pick — select named fields from an object
-// ---------------------------------------------------------------------------
-export function pick(...keys) {
-    return typedAction({
-        kind: "Invoke",
-        handler: { kind: "Builtin", builtin: { kind: "Pick", value: keys } },
-    });
-}
-// ---------------------------------------------------------------------------
-// DropResult — run an action for side effects, discard its output
-// ---------------------------------------------------------------------------
-export function dropResult(action) {
-    // Build AST directly — chain inference fails when drop's TValue
-    // isn't constrained by context (resolves to unknown ≠ TOutput).
-    return typedAction({
-        kind: "Chain",
-        first: action,
-        rest: {
-            kind: "Invoke",
-            handler: { kind: "Builtin", builtin: { kind: "Drop" } },
-        },
-    });
-}
-// ---------------------------------------------------------------------------
-// WithResource — RAII-style create/action/dispose
-// ---------------------------------------------------------------------------
-/**
- * RAII-style resource management combinator.
- *
- * Runs `create` to acquire a resource, then merges the resource with the
- * original input into a flat object (`TResource & TIn`) for the action.
- * After the action completes, `dispose` receives the resource for cleanup.
- * The overall combinator returns the action's output.
- *
- * ```
- * TIn → create → TResource
- *     → merge(TResource, TIn) → TResource & TIn
- *     → action(TResource & TIn) → TOut
- *     → dispose(TResource) → (discarded)
- *     → TOut
- * ```
- */
-export function withResource({ create, action, dispose, }) {
-    const mergeBuiltin = {
-        kind: "Invoke",
-        handler: { kind: "Builtin", builtin: { kind: "Merge" } },
-    };
-    // Step 1: all(create, identity) → [TResource, TIn] → merge → TResource & TIn
-    const acquireAndMerge = chain(typedAction({
-        kind: "All",
-        actions: [create, identity],
-    }), typedAction(mergeBuiltin));
-    // Step 2: all(action, identity) → [TOut, TResource & TIn]
-    // Keep merged object so dispose can access resource fields.
-    const actionAndKeepMerged = typedAction({
-        kind: "All",
-        actions: [action, identity],
-    });
-    // Step 3: all(extractIndex(0), chain(extractIndex(1), dispose)) → [TOut, unknown]
-    const disposeAndKeepResult = typedAction({
-        kind: "All",
-        actions: [
-            extractIndex(0),
-            chain(extractIndex(1), dispose),
-        ],
-    });
-    // Step 4: extractIndex(0) → TOut
-    return chain(chain(chain(acquireAndMerge, actionAndKeepMerged), disposeAndKeepResult), extractIndex(0));
-}
-// ---------------------------------------------------------------------------
-// Augment — run a transform, merge its output back into the original input
-// ---------------------------------------------------------------------------
-/**
- * Run `action` on the input, then merge the action's output fields back
- * into the original input object. The action must accept exactly `TInput`.
- * Use `pick` inside the action's pipe if the inner handler needs a subset.
- *
- * Example:
- *   augment(pipe(pick("file"), migrate))
- *   // { file, outputPath } → { file, outputPath, content, migrated }
- */
-export function augment(action) {
-    // Build AST directly — chain inference fails because [TOutput, TInput]
-    // doesn't match merge()'s Record<string, unknown>[] with invariance.
-    return typedAction({
-        kind: "Chain",
-        first: {
-            kind: "All",
-            actions: [action, identity],
-        },
-        rest: {
-            kind: "Invoke",
-            handler: { kind: "Builtin", builtin: { kind: "Merge" } },
-        },
-    });
-}
-// ---------------------------------------------------------------------------
-// Tap — run an action for side effects, preserve original input
-// ---------------------------------------------------------------------------
-/**
- * Run `action` on the input for its side effects, then discard the action's
- * output and return the original input unchanged. The action must accept
- * exactly `TInput`. Use `pick` inside the action's pipe if the inner
- * handler needs a subset.
- *
- * Constraint: input must be an object (uses augment internally, which
- * relies on all + merge).
- *
- * Example:
- *   pipe(tap(pipe(pick("worktreePath", "description"), implement)), createPR)
- */
-export function tap(action) {
-    // Build AST directly — internal plumbing (action → constant → augment)
-    // can't go through typed chain/augment with invariant phantom fields.
-    // tap: all(chain(action, constant({})), identity()) → merge
-    return typedAction({
-        kind: "Chain",
-        first: {
-            kind: "All",
-            actions: [
-                {
-                    kind: "Chain",
-                    first: action,
-                    rest: {
-                        kind: "Invoke",
-                        handler: {
-                            kind: "Builtin",
-                            builtin: { kind: "Constant", value: {} },
-                        },
-                    },
-                },
-                {
-                    kind: "Invoke",
-                    handler: { kind: "Builtin", builtin: { kind: "Identity" } },
-                },
-            ],
-        },
-        rest: {
-            kind: "Invoke",
-            handler: { kind: "Builtin", builtin: { kind: "Merge" } },
-        },
-    });
-}
-// ---------------------------------------------------------------------------
-// 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 } },
-    });
-}
-// ---------------------------------------------------------------------------
-// Option namespace — combinators for Option<T> tagged unions
-// ---------------------------------------------------------------------------
-// Shared AST fragments for Option desugaring
-const TAG_SOME = {
-    kind: "Invoke",
-    handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Some" } },
-};
-const TAG_NONE = {
-    kind: "Invoke",
-    handler: { kind: "Builtin", builtin: { kind: "Tag", value: "None" } },
-};
-const EXTRACT_VALUE = {
-    kind: "Invoke",
-    handler: {
-        kind: "Builtin",
-        builtin: { kind: "ExtractField", value: "value" },
-    },
-};
-const DROP = {
-    kind: "Invoke",
-    handler: { kind: "Builtin", builtin: { kind: "Drop" } },
-};
-const IDENTITY = {
-    kind: "Invoke",
-    handler: { kind: "Builtin", builtin: { kind: "Identity" } },
-};
-/** Wrap branch cases with ExtractField("value") auto-unwrapping. */
-function optionBranch(someCaseBody, noneCaseBody) {
-    return {
-        kind: "Branch",
-        cases: {
-            Some: { kind: "Chain", first: EXTRACT_VALUE, rest: someCaseBody },
-            None: { kind: "Chain", first: EXTRACT_VALUE, rest: noneCaseBody },
-        },
-    };
-}
-/**
- * Option namespace. All combinators produce TypedAction AST nodes that
- * desugar to branch + existing builtins, except collect which uses the
- * CollectSome builtin.
- */
-export const Option = {
-    /**
-     * Wrap a value as Some. `T → Option<T>`
-     *
-     * Equivalent to `tag<OptionDef<T>, "Some">("Some")`.
-     */
-    some() {
-        return typedAction(TAG_SOME);
-    },
-    /**
-     * Produce a None. `never → Option<T>`
-     *
-     * Chain after `.drop()` to discard the current value first.
-     * Equivalent to `tag<OptionDef<T>, "None">("None")`.
-     */
-    none() {
-        return typedAction(TAG_NONE);
-    },
-    /**
-     * Transform the Some value. `Option<T> → Option<U>`
-     *
-     * Desugars to: `branch({ Some: pipe(action, tag("Some")), None: tag("None") })`
-     */
-    map(action) {
-        return typedAction(optionBranch({ kind: "Chain", first: action, rest: TAG_SOME }, TAG_NONE));
-    },
-    /**
-     * Monadic bind (flatMap). If Some, pass the value to action which
-     * returns Option<U>. If None, stay None. `Option<T> → Option<U>`
-     *
-     * This is the most fundamental combinator — map, flatten, and filter
-     * are all derivable from andThen + constructors.
-     *
-     * Desugars to: `branch({ Some: action, None: tag("None") })`
-     */
-    andThen(action) {
-        return typedAction(optionBranch(action, TAG_NONE));
-    },
-    /**
-     * Extract the Some value or produce a default from an action.
-     * `Option<T> → T`
-     *
-     * The defaultAction takes no meaningful input (never) and must produce T.
-     * Use `Option.unwrapOr(constant("fallback"))`.
-     *
-     * The None branch drops its void payload before calling defaultAction,
-     * matching Rust's `unwrap_or_else(|| default)` where the closure takes
-     * no arguments.
-     *
-     * Desugars to: `branch({ Some: identity(), None: pipe(drop(), defaultAction) })`
-     */
-    unwrapOr(defaultAction) {
-        return typedAction({
-            kind: "Branch",
-            cases: {
-                Some: { kind: "Chain", first: EXTRACT_VALUE, rest: IDENTITY },
-                None: {
-                    kind: "Chain",
-                    first: EXTRACT_VALUE,
-                    rest: { kind: "Chain", first: DROP, rest: defaultAction },
-                },
-            },
-        });
-    },
-    /**
-     * Unwrap a nested Option. `Option<Option<T>> → Option<T>`
-     *
-     * Desugars to: `branch({ Some: identity(), None: tag("None") })`
-     */
-    flatten() {
-        return typedAction(optionBranch(IDENTITY, TAG_NONE));
-    },
-    /**
-     * Conditional keep. If Some, pass value to predicate which returns
-     * Option<T> (some() to keep, none() to discard). If None, stay None.
-     * `Option<T> → Option<T>`
-     *
-     * This has the same signature and desugaring as andThen with T=U.
-     * Named "filter" for readability when the intent is filtering.
-     *
-     * Desugars to: `branch({ Some: predicate, None: tag("None") })`
-     */
-    filter(predicate) {
-        return typedAction(optionBranch(predicate, TAG_NONE));
-    },
-    /**
-     * Collect Some values from an array, discarding Nones.
-     * `Option<T>[] → T[]`
-     *
-     * This is a builtin handler (CollectSome) — it can't be expressed
-     * as a composition of existing AST nodes because it requires
-     * array-level filtering logic.
-     */
-    collect() {
-        return typedAction({
-            kind: "Invoke",
-            handler: { kind: "Builtin", builtin: { kind: "CollectSome" } },
-        });
-    },
-    /**
-     * Test if the value is Some. `Option<T> → boolean`
-     *
-     * Rarely useful — branch on Some/None directly instead.
-     *
-     * Desugars to: `branch({ Some: pipe(drop(), constant(true)), None: pipe(drop(), constant(false)) })`
-     */
-    isSome() {
-        const constTrue = {
-            kind: "Invoke",
-            handler: { kind: "Builtin", builtin: { kind: "Constant", value: true } },
-        };
-        const constFalse = {
-            kind: "Invoke",
-            handler: { kind: "Builtin", builtin: { kind: "Constant", value: false } },
-        };
-        return typedAction(optionBranch({ kind: "Chain", first: DROP, rest: constTrue }, { kind: "Chain", first: DROP, rest: constFalse }));
-    },
-    /**
-     * Test if the value is None. `Option<T> → boolean`
-     *
-     * Rarely useful — branch on Some/None directly instead.
-     *
-     * Desugars to: `branch({ Some: pipe(drop(), constant(false)), None: pipe(drop(), constant(true)) })`
-     */
-    isNone() {
-        const constTrue = {
-            kind: "Invoke",
-            handler: { kind: "Builtin", builtin: { kind: "Constant", value: true } },
-        };
-        const constFalse = {
-            kind: "Invoke",
-            handler: { kind: "Builtin", builtin: { kind: "Constant", value: false } },
-        };
-        return typedAction(optionBranch({ kind: "Chain", first: DROP, rest: constFalse }, { kind: "Chain", first: DROP, rest: constTrue }));
-    },
-};
-// ---------------------------------------------------------------------------
-// Result namespace — combinators for Result<TValue, TError> tagged unions
-// ---------------------------------------------------------------------------
-// Shared AST fragments for Result desugaring
-const TAG_OK = {
-    kind: "Invoke",
-    handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Ok" } },
-};
-const TAG_ERR = {
-    kind: "Invoke",
-    handler: { kind: "Builtin", builtin: { kind: "Tag", value: "Err" } },
-};
-/** Wrap branch cases with ExtractField("value") auto-unwrapping. */
-function resultBranch(okCaseBody, errCaseBody) {
-    return {
-        kind: "Branch",
-        cases: {
-            Ok: { kind: "Chain", first: EXTRACT_VALUE, rest: okCaseBody },
-            Err: { kind: "Chain", first: EXTRACT_VALUE, rest: errCaseBody },
-        },
-    };
-}
-/**
- * Result namespace. All combinators produce TypedAction AST nodes that
- * desugar to branch + existing builtins.
- */
-export const Result = {
-    /**
-     * Wrap a value as Ok. `TValue → Result<TValue, TError>`
-     */
-    ok() {
-        return typedAction(TAG_OK);
-    },
-    /**
-     * Wrap a value as Err. `TError → Result<TValue, TError>`
-     */
-    err() {
-        return typedAction(TAG_ERR);
-    },
-    /**
-     * Transform the Ok value. `Result<TValue, TError> → Result<TOut, TError>`
-     *
-     * Desugars to: `branch({ Ok: pipe(action, tag("Ok")), Err: tag("Err") })`
-     */
-    map(action) {
-        return typedAction(resultBranch({ kind: "Chain", first: action, rest: TAG_OK }, TAG_ERR));
-    },
-    /**
-     * Transform the Err value. `Result<TValue, TError> → Result<TValue, TErrorOut>`
-     *
-     * Desugars to: `branch({ Ok: tag("Ok"), Err: pipe(action, tag("Err")) })`
-     */
-    mapErr(action) {
-        return typedAction(resultBranch(TAG_OK, {
-            kind: "Chain",
-            first: action,
-            rest: TAG_ERR,
-        }));
-    },
-    /**
-     * Monadic bind (flatMap) for Ok. If Ok, pass value to action which
-     * returns Result<TOut, TError>. If Err, propagate.
-     *
-     * Desugars to: `branch({ Ok: action, Err: tag("Err") })`
-     */
-    andThen(action) {
-        return typedAction(resultBranch(action, TAG_ERR));
-    },
-    /**
-     * Fallback on Err. If Ok, keep it. If Err, pass error to fallback
-     * which returns a new Result.
-     *
-     * Desugars to: `branch({ Ok: tag("Ok"), Err: fallback })`
-     */
-    or(fallback) {
-        return typedAction(resultBranch(TAG_OK, fallback));
-    },
-    /**
-     * Replace Ok value with another Result. If Ok, discard value and
-     * return other. If Err, propagate.
-     *
-     * Desugars to: `branch({ Ok: pipe(drop(), other), Err: tag("Err") })`
-     */
-    and(other) {
-        return typedAction(resultBranch({ kind: "Chain", first: DROP, rest: other }, TAG_ERR));
-    },
-    /**
-     * Extract Ok or compute default from Err. `Result<TValue, TError> → TValue`
-     *
-     * Takes an action that receives the Err payload and produces a fallback.
-     * Uses covariant output checking so throw tokens (Out=never) are assignable
-     * when TValue is provided explicitly: `Result.unwrapOr<string, string>(throwError)`.
-     *
-     * For inference-free usage with throw tokens, prefer the postfix method:
-     * `handler.unwrapOr(throwError)` — the `this` constraint provides TValue.
-     *
-     * Desugars to: `branch({ Ok: identity(), Err: defaultAction })`
-     */
-    unwrapOr(defaultAction) {
-        return typedAction(resultBranch(IDENTITY, defaultAction));
-    },
-    /**
-     * Unwrap nested Result. `Result<Result<TValue, TError>, TError> → Result<TValue, TError>`
-     *
-     * Desugars to: `branch({ Ok: identity(), Err: tag("Err") })`
-     */
-    flatten() {
-        return typedAction(resultBranch(IDENTITY, TAG_ERR));
-    },
-    /**
-     * Convert Ok to Some, Err to None. `Result<TValue, TError> → Option<TValue>`
-     *
-     * Desugars to: `branch({ Ok: tag("Some"), Err: pipe(drop(), tag("None")) })`
-     */
-    toOption() {
-        return typedAction(resultBranch(TAG_SOME, { kind: "Chain", first: DROP, rest: TAG_NONE }));
-    },
-    /**
-     * Convert Err to Some, Ok to None. `Result<TValue, TError> → Option<TError>`
-     *
-     * Desugars to: `branch({ Ok: pipe(drop(), tag("None")), Err: tag("Some") })`
-     */
-    toOptionErr() {
-        return typedAction(resultBranch({ kind: "Chain", first: DROP, rest: TAG_NONE }, TAG_SOME));
-    },
-    /**
-     * Swap Result/Option nesting.
-     * `Result<Option<TValue>, TError> → Option<Result<TValue, TError>>`
-     */
-    transpose() {
-        return typedAction(resultBranch(
-        // Ok case: receives Option<TValue>, branch on Some/None
-        {
-            kind: "Branch",
-            cases: {
-                Some: {
-                    kind: "Chain",
-                    first: EXTRACT_VALUE,
-                    rest: { kind: "Chain", first: TAG_OK, rest: TAG_SOME },
-                },
-                None: {
-                    kind: "Chain",
-                    first: EXTRACT_VALUE,
-                    rest: { kind: "Chain", first: DROP, rest: TAG_NONE },
-                },
-            },
-        }, 
-        // Err case: receives TError, wrap as Result.err then Option.some
-        { kind: "Chain", first: TAG_ERR, rest: TAG_SOME }));
-    },
-    /**
-     * Test if the value is Ok. `Result<TValue, TError> → boolean`
-     */
-    isOk() {
-        const constTrue = {
-            kind: "Invoke",
-            handler: { kind: "Builtin", builtin: { kind: "Constant", value: true } },
-        };
-        const constFalse = {
-            kind: "Invoke",
-            handler: { kind: "Builtin", builtin: { kind: "Constant", value: false } },
-        };
-        return typedAction(resultBranch({ kind: "Chain", first: DROP, rest: constTrue }, { kind: "Chain", first: DROP, rest: constFalse }));
-    },
-    /**
-     * Test if the value is Err. `Result<TValue, TError> → boolean`
-     */
-    isErr() {
-        const constTrue = {
-            kind: "Invoke",
-            handler: { kind: "Builtin", builtin: { kind: "Constant", value: true } },
-        };
-        const constFalse = {
-            kind: "Invoke",
-            handler: { kind: "Builtin", builtin: { kind: "Constant", value: false } },
-        };
-        return typedAction(resultBranch({ kind: "Chain", first: DROP, rest: constFalse }, { kind: "Chain", first: DROP, rest: constTrue }));
-    },
-};