@barnum/barnum 0.2.2 → 0.3.0

package/dist/builtins.d.ts

@@ -0,0 +1,257 @@
+import { type Action, type Option as OptionT, type Pipeable, type Result as ResultT, type TaggedUnion, type TypedAction } from "./ast.js";
+/**
+ * Typed combinators for structural data transformations.
+ *
+ * All builtins emit `{ kind: "Builtin", builtin: { kind: ... } }` handler
+ * kinds. The Rust scheduler executes them inline (no subprocess).
+ */
+export declare function constant<TValue>(value: TValue): TypedAction<any, TValue>;
+export declare const identity: TypedAction<any, any>;
+export declare const drop: TypedAction<any, never>;
+/**
+ * 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 declare function tag<TDef extends Record<string, unknown>, TKind extends keyof TDef & string>(kind: TKind): TypedAction<TDef[TKind], TaggedUnion<TDef>>;
+type UnionToIntersection<U> = (U extends any ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+export declare function merge<TObjects extends Record<string, unknown>[]>(): TypedAction<TObjects, UnionToIntersection<TObjects[number]>>;
+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 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>;
+/**
+ * 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 declare function withResource<TIn extends Record<string, unknown>, TResource extends Record<string, unknown>, TOut, TDisposeOut = unknown>({ create, action, dispose, }: {
+    create: Pipeable<TIn, TResource>;
+    action: Pipeable<TResource & TIn, TOut>;
+    dispose: Pipeable<TResource, TDisposeOut>;
+}): TypedAction<TIn, TOut>;
+/**
+ * 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 declare function augment<TInput extends Record<string, unknown>, TOutput extends Record<string, unknown>>(action: Pipeable<TInput, TOutput>): TypedAction<TInput, TInput & TOutput>;
+/**
+ * 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 declare function tap<TInput extends Record<string, unknown>>(action: Pipeable<TInput, any>): TypedAction<TInput, TInput>;
+export declare function range(start: number, end: number): TypedAction<any, number[]>;
+/**
+ * Option namespace. All combinators produce TypedAction AST nodes that
+ * desugar to branch + existing builtins, except collect which uses the
+ * CollectSome builtin.
+ */
+export declare const Option: {
+    /**
+     * Wrap a value as Some. `T → Option<T>`
+     *
+     * Equivalent to `tag<OptionDef<T>, "Some">("Some")`.
+     */
+    readonly some: <T>() => TypedAction<T, OptionT<T>>;
+    /**
+     * Produce a None. `never → Option<T>`
+     *
+     * Chain after `.drop()` to discard the current value first.
+     * Equivalent to `tag<OptionDef<T>, "None">("None")`.
+     */
+    readonly none: <T>() => TypedAction<never, OptionT<T>>;
+    /**
+     * Transform the Some value. `Option<T> → Option<U>`
+     *
+     * Desugars to: `branch({ Some: pipe(action, tag("Some")), None: tag("None") })`
+     */
+    readonly map: <T, U>(action: Pipeable<T, U>) => TypedAction<OptionT<T>, OptionT<U>>;
+    /**
+     * 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") })`
+     */
+    readonly andThen: <T, U>(action: Pipeable<T, OptionT<U>>) => TypedAction<OptionT<T>, OptionT<U>>;
+    /**
+     * 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) })`
+     */
+    readonly unwrapOr: <T>(defaultAction: Pipeable<never, T>) => TypedAction<OptionT<T>, T>;
+    /**
+     * Unwrap a nested Option. `Option<Option<T>> → Option<T>`
+     *
+     * Desugars to: `branch({ Some: identity(), None: tag("None") })`
+     */
+    readonly flatten: <T>() => TypedAction<OptionT<OptionT<T>>, OptionT<T>>;
+    /**
+     * 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") })`
+     */
+    readonly filter: <T>(predicate: Pipeable<T, OptionT<T>>) => TypedAction<OptionT<T>, OptionT<T>>;
+    /**
+     * 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.
+     */
+    readonly collect: <T = any>() => TypedAction<OptionT<T>[], T[]>;
+    /**
+     * 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)) })`
+     */
+    readonly isSome: <T>() => TypedAction<OptionT<T>, boolean>;
+    /**
+     * 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)) })`
+     */
+    readonly isNone: <T>() => TypedAction<OptionT<T>, boolean>;
+};
+/**
+ * Result namespace. All combinators produce TypedAction AST nodes that
+ * desugar to branch + existing builtins.
+ */
+export declare const Result: {
+    /**
+     * Wrap a value as Ok. `TValue → Result<TValue, TError>`
+     */
+    readonly ok: <TValue, TError>() => TypedAction<TValue, ResultT<TValue, TError>>;
+    /**
+     * Wrap a value as Err. `TError → Result<TValue, TError>`
+     */
+    readonly err: <TValue, TError>() => TypedAction<TError, ResultT<TValue, TError>>;
+    /**
+     * Transform the Ok value. `Result<TValue, TError> → Result<TOut, TError>`
+     *
+     * Desugars to: `branch({ Ok: pipe(action, tag("Ok")), Err: tag("Err") })`
+     */
+    readonly map: <TValue, TOut, TError>(action: Pipeable<TValue, TOut>) => TypedAction<ResultT<TValue, TError>, ResultT<TOut, TError>>;
+    /**
+     * Transform the Err value. `Result<TValue, TError> → Result<TValue, TErrorOut>`
+     *
+     * Desugars to: `branch({ Ok: tag("Ok"), Err: pipe(action, tag("Err")) })`
+     */
+    readonly mapErr: <TValue, TError, TErrorOut>(action: Pipeable<TError, TErrorOut>) => TypedAction<ResultT<TValue, TError>, ResultT<TValue, TErrorOut>>;
+    /**
+     * 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") })`
+     */
+    readonly andThen: <TValue, TOut, TError>(action: Pipeable<TValue, ResultT<TOut, TError>>) => TypedAction<ResultT<TValue, TError>, ResultT<TOut, TError>>;
+    /**
+     * 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 })`
+     */
+    readonly or: <TValue, TError, TErrorOut>(fallback: Pipeable<TError, ResultT<TValue, TErrorOut>>) => TypedAction<ResultT<TValue, TError>, ResultT<TValue, TErrorOut>>;
+    /**
+     * 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") })`
+     */
+    readonly and: <TValue, TOut, TError>(other: Pipeable<never, ResultT<TOut, TError>>) => TypedAction<ResultT<TValue, TError>, ResultT<TOut, TError>>;
+    /**
+     * 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 })`
+     */
+    readonly unwrapOr: <TValue, TError>(defaultAction: Action & {
+        __in?: (input: TError) => void;
+        __out?: () => TValue;
+    }) => TypedAction<ResultT<TValue, TError>, TValue>;
+    /**
+     * Unwrap nested Result. `Result<Result<TValue, TError>, TError> → Result<TValue, TError>`
+     *
+     * Desugars to: `branch({ Ok: identity(), Err: tag("Err") })`
+     */
+    readonly flatten: <TValue, TError>() => TypedAction<ResultT<ResultT<TValue, TError>, TError>, ResultT<TValue, TError>>;
+    /**
+     * Convert Ok to Some, Err to None. `Result<TValue, TError> → Option<TValue>`
+     *
+     * Desugars to: `branch({ Ok: tag("Some"), Err: pipe(drop(), tag("None")) })`
+     */
+    readonly toOption: <TValue, TError>() => TypedAction<ResultT<TValue, TError>, OptionT<TValue>>;
+    /**
+     * Convert Err to Some, Ok to None. `Result<TValue, TError> → Option<TError>`
+     *
+     * Desugars to: `branch({ Ok: pipe(drop(), tag("None")), Err: tag("Some") })`
+     */
+    readonly toOptionErr: <TValue, TError>() => TypedAction<ResultT<TValue, TError>, OptionT<TError>>;
+    /**
+     * Swap Result/Option nesting.
+     * `Result<Option<TValue>, TError> → Option<Result<TValue, TError>>`
+     */
+    readonly transpose: <TValue, TError>() => TypedAction<ResultT<OptionT<TValue>, TError>, OptionT<ResultT<TValue, TError>>>;
+    /**
+     * Test if the value is Ok. `Result<TValue, TError> → boolean`
+     */
+    readonly isOk: <TValue, TError>() => TypedAction<ResultT<TValue, TError>, boolean>;
+    /**
+     * Test if the value is Err. `Result<TValue, TError> → boolean`
+     */
+    readonly isErr: <TValue, TError>() => TypedAction<ResultT<TValue, TError>, boolean>;
+};
+export {};