@onrails/result 0.1.4 → 0.3.0

package/dist/railway.d.ts

@@ -1,5 +1,5 @@
-import { R as ResultAsync } from './async-DKISqIBc.js';
-import { R as Result } from './types-C2Dp1d5J.js';
+import { R as ResultAsync } from './async-SZ7BEl0g.js';
+import { R as Result } from './types-BQ9vv0nD.js';
 
 /**
  * Tracks whether a {@link Railway} workflow has crossed an async boundary.
@@ -11,20 +11,10 @@ type RailwayMode = "sync" | "async";
  * `Result<T, E>`, async mode → `ResultAsync<T, E>`.
  */
 type RailwayOutput<T, E, M extends RailwayMode> = M extends "async" ? ResultAsync<T, E> : Result<T, E>;
-/**
- * Initial context shape for a `railway` functional pipeline.
- * Wraps the raw input under the `input` key so subsequent named steps
- * can reference it via `ctx.input`.
- */
-type RailwayInput<I> = {
-    readonly input: I;
-};
 type BranchFn<C extends object> = (ctx: C) => ResultAsync<unknown, unknown>;
 type BranchRecord = Record<string, (ctx: never) => ResultAsync<unknown, unknown>>;
 type BranchOk<R> = R extends (ctx: never) => ResultAsync<infer T, infer _E> ? T : never;
 type BranchErr<R> = R extends (ctx: never) => ResultAsync<infer _T, infer E> ? E : never;
-type BranchInput<R> = R extends (ctx: infer C) => ResultAsync<unknown, unknown> ? C : never;
-type ParallelInput<R extends BranchRecord> = BranchInput<R[keyof R]> & object;
 type ParallelOutput<R extends BranchRecord> = {
     [K in keyof R]: BranchOk<R[K]>;
 };
@@ -33,27 +23,6 @@ type ParallelError<R extends BranchRecord> = BranchErr<R[keyof R]>;
  * Named-context workflow builder. Each step appends a typed field to the
  * accumulating context object; the workflow tracks sync/async mode so the
  * final output type ({@link RailwayOutput}) is correct.
- *
- * Use `Railway` when a service workflow has 4+ named steps, mixed sync and
- * async boundaries, or independent async branches that should run in
- * parallel. For 1–2 step flows, prefer `flatMap` / `asyncAfter` directly.
- *
- * @example
- * ```ts
- * const summary = Railway
- *   .fromSync("id", () => IdSchema.parse(raw), toError)
- *   .fromPromise("row", ({ id }) => db.profiles.findFirst({ where: eq(profiles.id, id) }), toError)
- *   .require("profile", "row", ({ id }) => ({ kind: "not_found" as const, id }))
- *   .derive("normalized", ({ profile }) => normalizeProfile(profile))
- *   .parallel({
- *     artifacts: ({ normalized }) => loadArtifacts(normalized.id),
- *     metrics:   ({ normalized }) => loadMetrics(normalized.id),
- *   })
- *   .select(({ normalized, artifacts, metrics }) =>
- *     toProfileSummary({ profile: normalized, artifacts, metrics }),
- *   );
- * // ResultAsync<ProfileSummary, ParseError | DbError | NotFound>
- * ```
  */
 declare class Railway<C extends object, E, M extends RailwayMode> {
     private readonly state;
@@ -62,10 +31,7 @@ declare class Railway<C extends object, E, M extends RailwayMode> {
     static empty(): Railway<Record<never, never>, never, "sync">;
     /** Start a sync workflow with the given context as the initial state. */
     static context<C extends object>(context: C): Railway<C, never, "sync">;
-    /**
-     * Start a sync workflow with a throwing function — `onThrow` maps any
-     * exception to a typed error.
-     */
+    /** Start a sync workflow with a throwing function. */
     static fromSync<K extends string, T, E>(key: K, fn: () => T, onThrow: (error: unknown) => E): Railway<Record<K, T>, E, "sync">;
     /** Start a sync workflow with a `Result`-returning function. */
     static fromResult<K extends string, T, E>(key: K, fn: () => Result<T, E>): Railway<Record<K, T>, E, "sync">;
@@ -74,159 +40,39 @@ declare class Railway<C extends object, E, M extends RailwayMode> {
     /** Start an async workflow with a `ResultAsync`-returning function. */
     static fromAsync<K extends string, T, E>(key: K, fn: () => ResultAsync<T, E>): Railway<Record<K, T>, E, "async">;
     /**
-     * Pure sync derivation — `fn` must not throw. Use {@link fromSync} for
-     * throwing transforms.
+     * Rebuild the workflow in its current mode after transforming the carried
+     * result. Single re-link point for the state/phantom invariant: the mode
+     * tag is preserved verbatim, so `M` still describes the new state — TS
+     * cannot narrow the phantom `M` from the runtime tag, hence the cast.
      */
-    derive<K extends string, T>(key: K, fn: (ctx: C) => T): Railway<C & Record<K, T>, E, M>;
+    private step;
     /**
-     * Throwing sync transform. Adds `{ [key]: T }` to context; converts any
-     * exception to `Err<F>` via `onThrow`.
+     * Project the carried result into the mode-aware output type. Counterpart
+     * of {@link Railway.step} for terminal steps: the runtime branch matches
+     * the branch `RailwayOutput` picks for `M` (state/phantom invariant), but
+     * TS cannot resolve the conditional on an unresolved `M`, hence the cast.
      */
+    private out;
+    /** Lift the carried result into `ResultAsync` for async-upgrading steps. */
+    private toAsync;
+    /** Pure sync derivation. */
+    derive<K extends string, T>(key: K, fn: (ctx: C) => T): Railway<C & Record<K, T>, E, M>;
+    /** Throwing sync transform. */
     fromSync<K extends string, T, F>(key: K, fn: (ctx: C) => T, onThrow: (error: unknown) => F): Railway<C & Record<K, T>, E | F, M>;
-    /**
-     * Sync `Result`-returning step. Adds `{ [key]: T }` to context on `Ok`;
-     * short-circuits the workflow on `Err`. Error union widens to `E | F`.
-     */
+    /** Sync `Result`-returning step. */
     fromResult<K extends string, T, F>(key: K, fn: (ctx: C) => Result<T, F>): Railway<C & Record<K, T>, E | F, M>;
-    /**
-     * Promise-returning step — upgrades the workflow to async mode. Reject
-     * reasons go through `onReject` to become typed `Err<F>`.
-     */
+    /** Promise-returning step — upgrades the workflow to async mode. */
     fromPromise<K extends string, T, F>(key: K, fn: (ctx: C) => PromiseLike<T>, onReject: (error: unknown) => F): Railway<C & Record<K, T>, E | F, "async">;
-    /**
-     * `ResultAsync`-returning step — upgrades the workflow to async mode.
-     * Already-typed error: no mapper needed.
-     */
+    /** `ResultAsync`-returning step — upgrades the workflow to async mode. */
     fromAsync<K extends string, T, F>(key: K, fn: (ctx: C) => ResultAsync<T, F>): Railway<C & Record<K, T>, E | F, "async">;
-    /**
-     * Narrow a nullable context field into a required non-null field. If the
-     * source field is `null` / `undefined`, the workflow short-circuits with
-     * `onMissing(ctx)`.
-     *
-     * @example
-     * ```ts
-     * .fromPromise("row", ({ id }) => db.users.findFirst({ where: eq(users.id, id) }))
-     * .require("user", "row", ({ id }) => ({ kind: "not_found" as const, id }))
-     * // user is now User (non-null), not User | null
-     * ```
-     */
+    /** Narrow a nullable context field into a required non-null field. */
     require<K extends string, S extends keyof C, F>(key: K, source: S, onMissing: (ctx: C) => F): Railway<C & Record<K, NonNullable<C[S]>>, E | F, M>;
-    /**
-     * Run independent `ResultAsync` branches concurrently and merge their
-     * named outputs back into context. Upgrades the workflow to async mode.
-     * On multiple failures, the first `Err` in record-iteration order wins.
-     *
-     * @example
-     * ```ts
-     * .parallel({
-     *   recent:  ({ userId }) => loadRecent(userId),
-     *   metrics: ({ userId }) => loadMetrics(userId),
-     * })
-     * // ctx now has { ..., recent, metrics }
-     * ```
-     */
+    /** Run independent `ResultAsync` branches concurrently and merge outputs. */
     parallel<R extends Record<string, BranchFn<C>>>(branches: R): Railway<C & ParallelOutput<R>, E | ParallelError<R>, "async">;
-    /**
-     * Project the final context into the workflow's output type. Hides the
-     * internal context shape from callers.
-     */
+    /** Project the final context into the workflow's output type. */
     select<T>(fn: (ctx: C) => T): RailwayOutput<T, E, M>;
-    /**
-     * Return the accumulated context as-is. Use when downstream code needs
-     * every named field; prefer {@link select} when you can project to a DTO.
-     */
+    /** Return the accumulated context as-is. */
     done(): RailwayOutput<C, E, M>;
 }
 
-type ParserLike<I, T> = {
-    readonly parse: (input: I) => T;
-} | ((input: I) => T);
-type UnaryStep<I, O> = (input: I) => O;
-/**
- * Functional companion to {@link Railway} — point-free composition of
- * reusable workflow steps. Starts from `Railway.context({ input })` and
- * applies each step in order. Step factories live below: {@link parseWith},
- * {@link fromSyncNamed}, {@link fromResultNamed}, {@link fromPromiseNamed},
- * {@link fromAsyncNamed}, {@link deriveNamed}, {@link requireNamed},
- * {@link parallelNamed}, {@link select}.
- *
- * @example
- * ```ts
- * const summary = railway(
- *   rawId,
- *   parseWith(IdSchema, toError).as("id"),
- *   fromPromiseNamed("row", ({ id }) => db.profiles.findFirst({ where: eq(profiles.id, id) }), toError),
- *   requireNamed("profile", "row", ({ id }) => ({ kind: "not_found" as const, id })),
- *   deriveNamed("normalized", ({ profile }) => normalizeProfile(profile)),
- *   select(({ normalized }) => toProfileSummary(normalized)),
- * );
- * ```
- */
-declare function railway<I, A>(input: I, step1: UnaryStep<Railway<RailwayInput<I>, never, "sync">, A>): A;
-declare function railway<I, A, B>(input: I, step1: UnaryStep<Railway<RailwayInput<I>, never, "sync">, A>, step2: UnaryStep<A, B>): B;
-declare function railway<I, A, B, C>(input: I, step1: UnaryStep<Railway<RailwayInput<I>, never, "sync">, A>, step2: UnaryStep<A, B>, step3: UnaryStep<B, C>): C;
-declare function railway<I, A, B, C, D>(input: I, step1: UnaryStep<Railway<RailwayInput<I>, never, "sync">, A>, step2: UnaryStep<A, B>, step3: UnaryStep<B, C>, step4: UnaryStep<C, D>): D;
-declare function railway<I, A, B, C, D, E>(input: I, step1: UnaryStep<Railway<RailwayInput<I>, never, "sync">, A>, step2: UnaryStep<A, B>, step3: UnaryStep<B, C>, step4: UnaryStep<C, D>, step5: UnaryStep<D, E>): E;
-declare function railway<I, A, B, C, D, E, F>(input: I, step1: UnaryStep<Railway<RailwayInput<I>, never, "sync">, A>, step2: UnaryStep<A, B>, step3: UnaryStep<B, C>, step4: UnaryStep<C, D>, step5: UnaryStep<D, E>, step6: UnaryStep<E, F>): F;
-declare function railway<I, A, B, C, D, E, F, G>(input: I, step1: UnaryStep<Railway<RailwayInput<I>, never, "sync">, A>, step2: UnaryStep<A, B>, step3: UnaryStep<B, C>, step4: UnaryStep<C, D>, step5: UnaryStep<D, E>, step6: UnaryStep<E, F>, step7: UnaryStep<F, G>): G;
-declare function railway<I, A, B, C, D, E, F, G, H>(input: I, step1: UnaryStep<Railway<RailwayInput<I>, never, "sync">, A>, step2: UnaryStep<A, B>, step3: UnaryStep<B, C>, step4: UnaryStep<C, D>, step5: UnaryStep<D, E>, step6: UnaryStep<E, F>, step7: UnaryStep<F, G>, step8: UnaryStep<G, H>): H;
-/**
- * Step factory: parse the workflow input with a Zod-like schema (or a
- * unary parse function). Call `.as(key)` to name the output field.
- *
- * @example
- * ```ts
- * parseWith(IdSchema, toError).as("id");
- * // Used as the first step in `railway(rawId, parseId, ...)`
- * ```
- */
-declare const parseWith: <I, T, E>(parser: ParserLike<I, T>, onThrow: (error: unknown) => E) => {
-    as: <K extends string>(key: K) => <F, M extends RailwayMode>(workflow: Railway<RailwayInput<I>, F, M>) => Railway<RailwayInput<I> & Record<K, T>, F | E, M>;
-};
-/**
- * Name-first companion to {@link parseWith}: parse the workflow input with a
- * Zod-like schema (or unary parse fn), naming the output field in the same
- * `(key, ...)` shape as {@link fromSyncNamed}, {@link deriveNamed}, et al.
- * Prefer this in `railway(...)` pipelines so every step's name aligns at the
- * left edge.
- *
- * @example
- * ```ts
- * railway(
- *   rawId,
- *   parseNamed("id", IdSchema, toError),
- *   fromPromiseNamed("profile", ({ id }) => fetchProfile(id), toError),
- * );
- * ```
- */
-declare const parseNamed: <K extends string, I, T, E>(key: K, parser: ParserLike<I, T>, onThrow: (error: unknown) => E) => <F, M extends RailwayMode>(workflow: Railway<RailwayInput<I>, F, M>) => Railway<RailwayInput<I> & Record<K, T>, F | E, M>;
-/**
- * Reusable wrapper around {@link Railway.fromSync}. Captures key + fn +
- * onThrow once; applies to any compatible workflow.
- */
-declare const fromSyncNamed: <K extends string, C extends object, T, E>(key: K, fn: (ctx: C) => T, onThrow: (error: unknown) => E) => <I extends C, F, M extends RailwayMode>(workflow: Railway<I, F, M>) => Railway<I & Record<K, T>, F | E, M>;
-/** Reusable wrapper around {@link Railway.fromResult}. */
-declare const fromResultNamed: <K extends string, C extends object, T, E>(key: K, fn: (ctx: C) => Result<T, E>) => <I extends C, F, M extends RailwayMode>(workflow: Railway<I, F, M>) => Railway<I & Record<K, T>, F | E, M>;
-/**
- * Reusable wrapper around {@link Railway.fromPromise}. Upgrades the
- * workflow to async mode when applied.
- */
-declare const fromPromiseNamed: <K extends string, C extends object, T, E>(key: K, fn: (ctx: C) => PromiseLike<T>, onReject: (error: unknown) => E) => <I extends C, F, M extends RailwayMode>(workflow: Railway<I, F, M>) => Railway<I & Record<K, T>, F | E, "async">;
-/** Reusable wrapper around {@link Railway.fromAsync}. */
-declare const fromAsyncNamed: <K extends string, C extends object, T, E>(key: K, fn: (ctx: C) => ResultAsync<T, E>) => <I extends C, F, M extends RailwayMode>(workflow: Railway<I, F, M>) => Railway<I & Record<K, T>, F | E, "async">;
-/** Reusable wrapper around {@link Railway.derive} — pure sync derivation. */
-declare const deriveNamed: <K extends string, C extends object, T>(key: K, fn: (ctx: C) => T) => <I extends C, E, M extends RailwayMode>(workflow: Railway<I, E, M>) => Railway<I & Record<K, T>, E, M>;
-/** Reusable wrapper around {@link Railway.require} — narrows a nullable field. */
-declare const requireNamed: <K extends string, S extends string, C extends object, E>(key: K, source: S, onMissing: (ctx: C & Record<S, unknown>) => E) => <I extends C & Record<S, unknown>, F, M extends RailwayMode>(workflow: Railway<I, F, M>) => Railway<I & Record<K, NonNullable<I[S]>>, F | E, M>;
-/**
- * Reusable wrapper around {@link Railway.parallel}. Branches run
- * concurrently and merge their named outputs back into context.
- */
-declare const parallelNamed: <R extends BranchRecord>(branches: R) => <I extends ParallelInput<R>, E, M extends RailwayMode>(workflow: Railway<I, E, M>) => Railway<I & ParallelOutput<R>, E | ParallelError<R>, "async">;
-/**
- * Reusable wrapper around {@link Railway.select} — projects the final
- * context into the workflow's output type.
- */
-declare const select: <C extends object, T>(fn: (ctx: C) => T) => <E, M extends RailwayMode>(workflow: Railway<C, E, M>) => RailwayOutput<T, E, M>;
-
-export { Railway, type RailwayInput, type RailwayMode, type RailwayOutput, deriveNamed, fromAsyncNamed, fromPromiseNamed, fromResultNamed, fromSyncNamed, parallelNamed, parseNamed, parseWith, railway, requireNamed, select };
+export { type BranchFn, type BranchRecord, type ParallelError, type ParallelOutput, Railway, type RailwayMode, type RailwayOutput };