Class Railway<C, E, M>

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

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>

Type Parameters

C extends object
E
M extends RailwayMode

Index

Methods

derive done fromAsync fromPromise fromResult fromSync parallel require select context empty fromAsync fromPromise fromResult fromSync

Methods

derive

derive<K extends string, T>(
key: K,
fn: (ctx: C) => T,
): Railway<C & Record<K, T>, E, M>
Pure sync derivation — fn must not throw. Use fromSync for throwing transforms.
Type Parameters
- K extends string
- T
Parameters
- key: K
- fn: (ctx: C) => T
Returns Railway<C & Record<K, T>, E, M>
- Defined in packages/result/src/railway.ts:135

done

done(): RailwayOutput<C, E, M>
Return the accumulated context as-is. Use when downstream code needs every named field; prefer select when you can project to a DTO.

Returns RailwayOutput<C, E, M>
- Defined in packages/result/src/railway.ts:289

fromAsync

fromAsync<K extends string, T, F>(
key: K,
fn: (ctx: C) => ResultAsync<T, F>,
): Railway<C & Record<K, T>, E | F, "async">
ResultAsync-returning step — upgrades the workflow to async mode. Already-typed error: no mapper needed.
Type Parameters
- K extends string
- T
- F
Parameters
- key: K
- fn: (ctx: C) => ResultAsync<T, F>
Returns Railway<C & Record<K, T>, E | F, "async">
- Defined in packages/result/src/railway.ts:198

fromPromise

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">
Promise-returning step — upgrades the workflow to async mode. Reject reasons go through onReject to become typed Err<F>.
Type Parameters
- K extends string
- T
- F
Parameters
- key: K
- fn: (ctx: C) => PromiseLike<T>
- onReject: (error: unknown) => F
Returns Railway<C & Record<K, T>, E | F, "async">
- Defined in packages/result/src/railway.ts:186

fromResult

fromResult<K extends string, T, F>(
key: K,
fn: (ctx: C) => Result<T, 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.
Type Parameters
- K extends string
- T
- F
Parameters
- key: K
- fn: (ctx: C) => Result<T, F>
Returns Railway<C & Record<K, T>, E | F, M>
- Defined in packages/result/src/railway.ts:155

fromSync

fromSync<K extends string, T, F>(
    key: K,
    fn: (ctx: C) => T,
    onThrow: (error: unknown) => F,
): Railway<C & Record<K, T>, E | F, M>
Throwing sync transform. Adds { [key]: T } to context; converts any exception to Err<F> via onThrow.
Type Parameters
- K extends string
- T
- F
Parameters
- key: K
- fn: (ctx: C) => T
- onThrow: (error: unknown) => F
Returns Railway<C & Record<K, T>, E | F, M>
- Defined in packages/result/src/railway.ts:143

parallel

parallel<R extends Record<string, BranchFn<C>>>(
branches: R,
): Railway<C & ParallelOutput<R>, E | BranchErr<R[keyof R]>, "async">
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.
Type Parameters
- R extends Record<string, BranchFn<C>>
Parameters
- branches: R
Returns Railway<C & ParallelOutput<R>, E | BranchErr<R[keyof R]>, "async">
Example
```
.parallel({
  recent:  ({ userId }) => loadRecent(userId),
  metrics: ({ userId }) => loadMetrics(userId),
})
// ctx now has { ..., recent, metrics }
```
- Defined in packages/result/src/railway.ts:247

require

require<K extends string, S extends string | number | symbol, F>(
    key: K,
    source: S,
    onMissing: (ctx: C) => F,
): Railway<C & Record<K, NonNullable<C[S]>>, E | F, M>
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).
Type Parameters
- K extends string
- S extends string | number | symbol
- F
Parameters
- key: K
- source: S
- onMissing: (ctx: C) => F
Returns Railway<C & Record<K, NonNullable<C[S]>>, E | F, M>
Example
```
.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
```
- Defined in packages/result/src/railway.ts:222

select

select<T>(fn: (ctx: C) => T): RailwayOutput<T, E, M>
Project the final context into the workflow's output type. Hides the internal context shape from callers.
Type Parameters
- T
Parameters
- fn: (ctx: C) => T
Returns RailwayOutput<T, E, M>
- Defined in packages/result/src/railway.ts:272

`Static`context

context<C extends object>(context: C): Railway<C, never, "sync">
Start a sync workflow with the given context as the initial state.
Type Parameters
- C extends object
Parameters
- context: C
Returns Railway<C, never, "sync">
- Defined in packages/result/src/railway.ts:90

`Static`empty

empty(): Railway<Record<never, never>, never, "sync">
Start an empty sync workflow with no fields in context.

Returns Railway<Record<never, never>, never, "sync">
- Defined in packages/result/src/railway.ts:85

`Static`fromAsync

fromAsync<K extends string, T, E>(
key: K,
fn: () => ResultAsync<T, E>,
): Railway<Record<K, T>, E, "async">
Start an async workflow with a ResultAsync-returning function.
Type Parameters
- K extends string
- T
- E
Parameters
- key: K
- fn: () => ResultAsync<T, E>
Returns Railway<Record<K, T>, E, "async">
- Defined in packages/result/src/railway.ts:124

`Static`fromPromise

fromPromise<K extends string, T, E>(
    key: K,
    fn: () => PromiseLike<T>,
    onReject: (error: unknown) => E,
): Railway<Record<K, T>, E, "async">
Start an async workflow with a PromiseLike-returning function.
Type Parameters
- K extends string
- T
- E
Parameters
- key: K
- fn: () => PromiseLike<T>
- onReject: (error: unknown) => E
Returns Railway<Record<K, T>, E, "async">
- Defined in packages/result/src/railway.ts:115

`Static`fromResult

fromResult<K extends string, T, E>(
key: K,
fn: () => Result<T, E>,
): Railway<Record<K, T>, E, "sync">
Start a sync workflow with a Result-returning function.
Type Parameters
- K extends string
- T
- E
Parameters
- key: K
- fn: () => Result<T, E>
Returns Railway<Record<K, T>, E, "sync">
- Defined in packages/result/src/railway.ts:107

`Static`fromSync

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 throwing function — onThrow maps any exception to a typed error.
Type Parameters
- K extends string
- T
- E
Parameters
- key: K
- fn: () => T
- onThrow: (error: unknown) => E
Returns Railway<Record<K, T>, E, "sync">
- Defined in packages/result/src/railway.ts:98

Class Railway<C, E, M>

Example

Type Parameters

Index

Methods

Methods

derive

Type Parameters

Parameters

Returns Railway<C & Record<K, T>, E, M>

done

Returns RailwayOutput<C, E, M>

fromAsync

Type Parameters

Parameters

Returns Railway<C & Record<K, T>, E | F, "async">

fromPromise

Type Parameters

Parameters

Returns Railway<C & Record<K, T>, E | F, "async">

fromResult

Type Parameters

Parameters

Returns Railway<C & Record<K, T>, E | F, M>

fromSync

Type Parameters

Parameters

Returns Railway<C & Record<K, T>, E | F, M>

parallel

Type Parameters

Parameters

Returns Railway<C & ParallelOutput<R>, E | BranchErr<R[keyof R]>, "async">

Example

require

Type Parameters

Parameters

Returns Railway<C & Record<K, NonNullable<C[S]>>, E | F, M>

Example

select

Type Parameters

Parameters

Returns RailwayOutput<T, E, M>

Staticcontext

Type Parameters

Parameters

Returns Railway<C, never, "sync">

Staticempty

Returns Railway<Record<never, never>, never, "sync">

StaticfromAsync

Type Parameters

Parameters

Returns Railway<Record<K, T>, E, "async">

StaticfromPromise

Type Parameters

Parameters

Returns Railway<Record<K, T>, E, "async">

StaticfromResult

Type Parameters

Parameters

Returns Railway<Record<K, T>, E, "sync">

StaticfromSync

Type Parameters

Parameters

Returns Railway<Record<K, T>, E, "sync">

Settings

On This Page

`Static`context

`Static`empty

`Static`fromAsync

`Static`fromPromise

`Static`fromResult

`Static`fromSync