If you do mission design, you've solved Lambert's problem more times than you can count. You also know the tooling reality: GMAT, STK, MATLAB scripts your advisor wrote in 2007, PyKEP, poliastro, the occasional Fortran routine that nobody wants to touch. All fine on a workstation. None of it useful when you want to put a porkchop plot in a web dashboard, run a quick TOF sweep in an Observable notebook, or build an interactive teaching tool that doesn't require a 4GB Python environment to load.

I built lambert-izzo for that gap. It's a Rust implementation of Izzo's revisited algorithm (CMDA, 2014), compiled to WebAssembly, shipped on npm, with TypeScript types generated straight out of the Rust types. The Rust crate (lambert_izzo) is the same code if you want it from a Rust binary or no_std embedded target.

This post is about why I made the choices I did and how to actually use it for trajectory work.

What's in the box

npm install lambert-izzo

import init, { solveLambert } from "lambert-izzo";

await init();

const result = solveLambert({
  r1: [7000, 0, 0],         // km, any consistent inertial frame
  r2: [0, 7000, 0],
  tof: 1457,                // s — quarter-period of a 7000 km circular orbit
  mu: 398_600.4418,         // km³/s²
  way: "short",
  maxRevs: null,            // null = single-rev only; 1..=32 for multi-rev
});

if (result.kind === "ok") {
  const { v1, v2 } = result.response.single;
  const iters = result.response.diagnostics.single.iters;
  // ...
} else {
  // result.error.kind: "DegeneratePositionVector" | "CollinearGeometry" | ...
}

That's the whole API surface. One function (plus a batch variant for sweeps), one input type, one tagged-union output. The published 2.0.0 package is ~97 KB of wasm (42 KB gzipped) plus a small wasm-bindgen JS glue layer, and does no I/O — it's a pure computational kernel.

Why "in your browser" is a real thing

The argument I most expect to hear is: why not just use PyKEP or poliastro? You should, if your environment can host them. They're excellent. The point isn't to replace them — it's that "your environment can host them" is doing a lot of work in that sentence.

A few cases where it isn't true:

• Interactive web tools. You want users to drop in (r1, r2, tof) and see a transfer ellipse. A WebAssembly module loads in milliseconds. A Python kernel doesn't load at all.

• Notebook frontends. Observable, Marimo's web mode, anything JS-native. A typed npm package is just an import.

• Teaching demos. Students click a button. They don't pip install their first orbital-mechanics homework.

• Visual mission-design sketches. You're prototyping a porkchop UI before committing to a backend. The iteration loop should be npm run dev, not deploying a Python service.

If your trajectory pipeline already lives in Python, keep it there. This is for the cases where the JS side of the wall is where the work is actually happening.

The algorithm, briefly

For readers who haven't met Izzo's formulation: the solver works in a single dimensionless parameter x ∈ (-∞, ∞) (the Lancaster–Blanchard variable), where x = 0 is a balanced ellipse, x = ±1 is parabolic escape, and |x| > 1 is hyperbolic. Time of flight T(x) is smooth-ish, with a single root for any feasible TOF. Multi-rev branches add Mπ periods, splitting T(x) into pieces with their own minima — that's where the long-period and short-period branches per M come from.

The core loop is Householder's third-order method on T(x) - tof = 0, with analytic first/second/third derivatives (Izzo Eq. 22). For the multi-rev T_min(M) feasibility check, it's Halley's method on dT/dx = 0.

The numerical interesting bit is that T(x) is unstable near x = 1. The solver dispatches across three regimes depending on |x − 1|:

• Battin's hypergeometric series (Izzo Eq. 20) for |x − 1| ≤ 0.01. Well-conditioned in the near-parabolic regime where Lagrange and Lancaster–Blanchard lose precision.

• Lancaster–Blanchard form (Izzo Eq. 18) for 0.01 < |x − 1| ≤ 0.2. Clean middle band.

• Lagrange form (Izzo Eq. 9) for |x − 1| > 0.2. Stable far from parabolic.

You don't pick the regime. The dispatcher does. The thresholds are tuned and constant-folded out at compile time.

If you want the full picture, the paper PDF is in the repo at docs/izzo.pdf and there's a concepts.md next to it that walks through the Lancaster x, the three regimes, and what the multi-rev branch structure actually looks like.

Multi-rev, properly

Pass maxRevs: 5 and you get every feasible (long_period, short_period) pair up to M = 5, in ascending M order:

const result = solveLambert({
  r1: [8000, 0, 0],
  r2: [5600, 5600, 0],
  tof: 5 * 7158,            // ~5 orbital periods at r ≈ 8000 km
  mu: 398_600.4418,
  way: "short",
  maxRevs: 5,
});

if (result.kind === "ok") {
  const branches = result.response.multi.flatMap((pair) => [
    { kind: "long" as const,  m: pair.nRevs, ...pair.longPeriod },
    { kind: "short" as const, m: pair.nRevs, ...pair.shortPeriod },
  ]);
  // 0–10 trajectories, depending on which branches were feasible
}

If T_min(M) > tof for some M, that branch is silently dropped from the returned set — there's no solution to return, and faking one would be worse than honest absence. response.multi.length tells you how many came back; the highest feasible M is response.multi.at(-1)?.nRevs.

Out-of-range maxRevs (zero, or > 32) is rejected as RevsOutOfRange before any solver work runs. The cap of 32 is a real architectural decision — the Rust core uses a stack-allocated ArrayVec so the entire solver does zero heap allocation on the hot path. You don't pay for an allocator on a porkchop sweep.

Validation

The Rust crate has a stress example that runs 100,000 random Earth-scale geometries each for single-rev and multi-rev (up to M = 5), checking vis-viva energy and angular-momentum conservation between the returned (v1, v2) pairs:

Iteration counts match the paper's figures. Conservation residuals sit at f64 round-off, which is the right answer — there's no algorithmic error left to find at that precision.

There's also a Kepler round-trip test: take the returned v1, propagate forward by tof using a universal-variable Kepler propagator, check that you arrive at r2. Across 500 random multi-rev geometries, max relative position error is < 1e-5 per branch.

Performance

Numbers from the native Rust crate on an Apple Silicon laptop, release profile, except where noted. The wasm package is sequential — wasm threads are a deployment ordeal (cross-origin isolation headers, SharedArrayBuffer support) that I didn't want to bake into a default install.

The wasm path is single-threaded and runs through the v8/SpiderMonkey wasm engine, so expect a constant-factor slowdown vs native — typically 1.5–3× depending on browser. Several hundred thousand calls per second on a single thread is enough for a 200×200 porkchop in a couple of seconds.

For batch work from JS:

import { solveLambertBatch } from "lambert-izzo";

const requests = tofValues.map((tof) => ({ r1, r2, tof, mu, way: "short" as const, maxRevs: null }));
const results = solveLambertBatch(requests);

const dvProfile = results
  .map((r, i) => ({ tof: tofValues[i], result: r }))
  .filter(({ result }) => result.kind === "ok")
  .map(({ tof, result }) => ({
    tof,
    dv: norm(sub(result.response.single.v1, vCircular)),
  }));

solveLambertBatch takes an array, returns an array of the same length, preserves order, errors are per-element. No bulk-fail behavior.

The error model is a tagged union, not exceptions

The output is { kind: "ok"; response: ... } | { kind: "err"; error: ... }. solveLambert and solveLambertBatch never throw on solver failure. The errors are themselves a discriminated union — switch on error.kind:

const result = solveLambert(input);

if (result.kind === "err") {
  const { error } = result;
  switch (error.kind) {
    case "NonFiniteInput":
      // error.parameter: "R1X" | "R1Y" | "R1Z" | "R2X" | "R2Y" | "R2Z" | "Tof" | "Mu"
      // error.value:     the NaN / ±Infinity that came in
      break;
    case "NonPositiveTimeOfFlight":
      // error.tof: the rejected value (≤ 0)
      break;
    case "NonPositiveMu":
      // error.mu: the rejected value (≤ 0)
      break;
    case "DegeneratePositionVector":
      // error.position: "R1" | "R2"
      // error.norm:     magnitude of the offending vector (below 1e-15)
      break;
    case "CollinearGeometry":
      // error.sin_angle: |r1 × r2| / (|r1|·|r2|), below 1e-15.
      // Transfer plane is undefined — perturb one endpoint off-plane.
      break;
    case "NoConvergence":
      // error.iterations: Householder iters before giving up
      // error.last_step:  magnitude of the final |Δx|
      // error.n_revs:     0 = single-rev, ≥ 1 = multi-rev branch index
      break;
    case "SingularDenominator":
      // error.n_revs: branch index where the denominator went singular
      break;
    case "RevsOutOfRange":
      // error.requested, error.max — maxRevs outside [1, 32]
      break;
    case "Unknown":
      // error.message: upstream Display text. Surface verbatim.
      break;
  }
}

There's no string parsing anywhere. Every variant has structured fields. The Unknown { message } variant only fires if the upstream Rust crate adds a new error case the wasm adapter hasn't mirrored yet — exhaustive switch blocks should include it as a safety net.

The reason I'm bringing this up is that "throw on bad input" is the JS default, and it's the wrong default for a numerical kernel. A degenerate Lambert input isn't a runtime crash — it's a perfectly valid signal from the solver that says this geometry has no transfer plane, fix your inputs. Treating it as an exception conflates "the code is broken" with "the math doesn't apply here," and the caller pays for that conflation in try/catch noise.

Frame invariance and units

The solver doesn't know what frame you're in. Pass r1 and r2 in any consistent inertial frame (ECI, HCRS, MCI, or any other inertial frame) and the returned v1 / v2 come back in the same frame. There are no field names like vEciX or assumptions about J2000.

Same for units. The solver is dimensionally homogeneous. The docs and examples use km / s / km/s / km³/s² because that's what aerospace SI looks like, but if you want canonical units (r in DU, tof in TU, mu = 1), it works without modification. The solver does no unit conversion — that's your problem, and it's the right boundary.

What this doesn't do

This is the boundary-value step. It is not a mission-design framework. Specifically:

• No patched conics. If you want SOI handoffs, you build that on top.

• No perturbations. Two-body only — no J2, no third-body, no SRP. Lambert is two-body by definition.

• No low-thrust. Δv is impulsive at the endpoints.

• No outer-loop optimization. Porkchop minima, primer-vector, multi-shooter convergence — those are things you call Lambert from, not things Lambert does for you.

• No ephemerides. You bring your own SPICE / Skyfield / Horizons output. The solver eats [x, y, z] triples; how you got them is your business.

That scope is deliberate. The crate is the boundary-value step, period. Anything that creeps beyond that turns into a framework, and there are already good frameworks.

A real example: Δv profile across TOF

Here's the pattern I actually use it for — sweeping TOF for a fixed boundary condition and looking at where the Δv minimum sits:

import init, { solveLambertBatch } from "lambert-izzo";

await init();

const sub = (a: number[], b: number[]) => a.map((x, i) => x - b[i]);
const norm = (v: number[]) => Math.hypot(...v);

const r1 = [7000, 0, 0] as const;
const r2 = [-12_000, 1, 0] as const;     // 1 km off-axis to clear collinearity
const mu = 398_600.4418;

const vCirc1 = Math.sqrt(mu / norm(r1));
const vInitial = [0, vCirc1, 0];          // prograde from r1

const tofValues = Array.from({ length: 200 }, (_, i) => 1000 + i * 50);

const requests = tofValues.map((tof) => ({
  r1: [...r1], r2: [...r2], tof, mu, way: "short" as const, maxRevs: null,
}));

const profile = solveLambertBatch(requests).flatMap((result, i) => {
  if (result.kind !== "ok") return [];
  const { v1 } = result.response.single;
  return [{ tof: tofValues[i], dv1: norm(sub(v1, vInitial)) }];
});

const optimal = profile.reduce((a, b) => (a.dv1 < b.dv1 ? a : b));
console.log(`Min Δv₁ = \({optimal.dv1.toFixed(3)} km/s at tof = \){optimal.tof} s`);

That's a 200-point sweep. On a recent laptop, the solveLambertBatch call is ~1 ms. You can put that behind a slider in a web UI and update on every drag event without thinking about it.

For a full porkchop, replace the 1D tofValues array with a 2D grid over departure date and arrival date, plug in ephemerides for r1(t1) and r2(t2) from your favorite source, and reduce over the grid. The math is identical.

Links

• npm: lambert-izzo

• crates.io: lambert_izzo

• GitHub: sakobu/izzos-lambert — paper PDF, concepts doc, architecture doc, all examples

Spacecraft proximity operations math is world-class. Papers in JGCD present elegant, validated formulations — analytical State Transition Matrices, density-model-free drag representations, quasi-nonsingular element sets that avoid coordinate singularities. Decades of theoretical refinement.

The tooling is plot3() in a MATLAB figure window. Scripts with magic numbers. Variable names like dd_lambda. No types, no tests, no version control — collaboration by shared drive. Researchers publish validated math, then every downstream team reimplements the same papers, introduces the same bugs, builds the same terrible UIs.

I decided to bridge this for one specific domain. I took Koenig, Guffanti, and D'Amico's 2017 paper on State Transition Matrices for perturbed relative motion and implemented it as an idiomatic TypeScript library — pure functions, immutable types, framework-agnostic — with a React Three Fiber mission planner on top. Adam Koenig, the paper's lead author and a current colleague, has validated the implementation. This is a production-quality port of peer-reviewed math, not a weekend approximation.

Live demo · Source

Why Analytical STMs Enable Browser-Native Astrodynamics

This paper was specifically chosen because its mathematical structure maps to a performance envelope that works in the browser.

The alternative — numerical integration of the equations of motion — requires hundreds of RK4/RK8 steps per propagation, each involving trigonometric evaluations. Wrap that in a Newton-Raphson targeting loop (which calls propagation per iteration, plus 6 calls per Jacobian evaluation via central differences), and wrap that in a golden section TOF optimizer (~20 evaluations), and you're looking at tens of thousands of trig calls per user interaction. Possible in JavaScript, but not at interactive framerates with real-time 3D rendering competing for the same thread.

Koenig et al.'s STMs reduce propagation to a matrix-vector multiply. The 6×6 J2 matrix costs 36 multiplies and 30 adds. The targeting solver converges in 5–15 iterations. The entire multi-waypoint planning pipeline — TOF optimization, targeting, trajectory generation — completes within a frame budget. This is what makes dragging a waypoint in 3D space and seeing the trajectory update in real time architecturally feasible, not just a demo trick.

Concretely: drag a waypoint 200 meters radially outward and the planner recomputes departure burns, coast arcs, and arrival burns in under a millisecond. That's not clever caching — that's analytical propagation being inherently fast enough for real-time interaction.

The paper's choice of Relative Orbital Elements over Cartesian state vectors further enables this. In ROE space, perturbations separate analytically — J2 appears as known secular drift rates, drag adds coupling terms with known structure — so each perturbation layer extends the STM without breaking the analytical form. Three fidelity levels (Keplerian 6×6, J2 6×6, J2+Drag 7×7/9×9), each embedding the previous as a subblock.

The Translation Problem

Porting a paper like this to TypeScript is a fundamentally different engineering challenge than implementing a well-documented algorithm from a textbook.

Reading Depth

You can implement quicksort from a description of the algorithm. You cannot implement a 9×9 drag State Transition Matrix from a description. You need to understand what each matrix element represents physically, because when your output is wrong — and it will be wrong, many times — the failure mode is a trajectory that curves subtly in the wrong direction, not a crash.

Debugging means knowing that row 3 of the STM corresponds to δex (the x-component of the relative eccentricity vector), that a sign error there reverses apsidal precession, and that this would manifest as the trajectory spiraling the wrong way over multiple orbits. The debugger tells you a number is wrong. The paper tells you why it's wrong.

Notation Mismatch

Academic papers optimize for typographic density. A single equation might contain subscripts, superscripts, overlines, dots (time derivatives), and Greek letters that each carry specific meaning within the paper's convention system. Mapping this to code requires decisions at every level:

• The paper's Ω̇ (RAAN rate due to J2) becomes raanDrift — but is it rad/s or rad/orbit?

• The orbital factor η appears as sqrt(1 - e²) in some papers and (1 - e²) in others. Which convention does this paper use, and did you get it right in all 36 elements of the J2 matrix?

• The drag model's "density-model-free" parameterization means da/dt isn't atmospheric-density-times-ballistic-coefficient — it's a direct rate input. Every consumer of that value needs to understand this distinction.

Here's what that notation mismatch looks like resolved — the J2 STM translated into TypeScript:

// From src/orbital/stm/j2.ts — the J2 STM, Equation A6
// Orbital factors (kappa, E, F, G, P, Q, S, T) are precomputed
// from eccentricity, inclination, and J2

return [
  // Row 1: delta-a is constant (no J2 secular effect on semi-major axis)
  [1, 0, 0, 0, 0, 0],

  // Row 2: delta-lambda evolution (Keplerian drift + J2 corrections)
  [
    -(1.5 * n + 3.5 * kappa * E * P) * tau,
    1,
    kappa * ex_i * F * G * P * tau,
    kappa * ey_i * F * G * P * tau,
    -kappa * F * S * tau,
    0,
  ],

  // Row 3: delta-ex evolution (apsidal precession rotates eccentricity vector)
  [
    3.5 * kappa * ey_f * Q * tau,
    0,
    cos_wt - 4 * kappa * ex_i * ey_f * G * Q * tau,
    -sin_wt - 4 * kappa * ey_i * ey_f * G * Q * tau,
    5 * kappa * ey_f * S * tau,
    0,
  ],

  // Row 4: delta-ey evolution (apsidal precession, conjugate to row 3)
  [
    -3.5 * kappa * ex_f * Q * tau,
    0,
    sin_wt + 4 * kappa * ex_i * ex_f * G * Q * tau,
    cos_wt + 4 * kappa * ey_i * ex_f * G * Q * tau,
    -5 * kappa * ex_f * S * tau,
    0,
  ],

  // Row 5: delta-ix is constant
  [0, 0, 0, 0, 1, 0],

  // Row 6: delta-iy evolution (nodal regression)
  [3.5 * kappa * S * tau, 0, -4 * kappa * ex_i * G * S * tau,
   -4 * kappa * ey_i * G * S * tau, 2 * kappa * T * tau, 1],
];

Each element is a product of orbital factors and time — no numerical integration, no timestep loops, just algebra.

The Validation Problem

This is the most dangerous part of porting a paper, and the part that gets the least attention.

Getting a matrix "mostly right" is worse than getting it obviously wrong. A 6×6 STM with one wrong element out of 36 will often produce trajectories that converge — the Newton-Raphson solver is robust enough to compensate — but the trajectories will be physically wrong. The solver finds a minimum. It's just not the minimum. You get a smooth, plausible-looking trajectory to the wrong destination. No error, no divergence, no warning.

This is fundamentally different from most software bugs. A wrong index throws. A null pointer crashes. A wrong sign in element (3,4) of a State Transition Matrix gives you a spacecraft that calmly spirals in the wrong direction over six orbits. You have to know enough physics to look at the output and feel that something is off.

The validation approach: implement the same dynamics as an RK4 numerical integrator. Propagate a state using both the analytical STM and the brute-force integrator. They should agree within numerical tolerance. This was done in the original Bun implementation with full test coverage. Adam Koenig's direct review of the matrix implementations provides a second, independent verification path — the author checking the port against his own math.

Library Architecture

The orbital library (src/orbital/) is ~4,800 lines of framework-agnostic TypeScript. Some deliberate architectural choices:

Pure Functions, Immutable Types

Every public function is a pure transform. No internal state, no side effects. The core types use readonly on every field:

export type ManeuverLeg = {
  readonly from: Vector3;
  readonly to: Vector3;
  readonly targetVelocity: Vector3;
  readonly tof: number;
  readonly burn1: Maneuver;
  readonly burn2: Maneuver;
  readonly totalDeltaV: number;
  readonly converged: boolean;
  readonly iterations: number;
  readonly positionError: number;
};

This isn't just style. When trajectory data flows from the solver → the store → the 3D renderer → the HUD → the export module, immutability means you can reason about correctness locally. A component receiving a ManeuverLeg knows it won't change out from under it. In MATLAB, this guarantee doesn't exist — any function can mutate any workspace variable, and the resulting bugs are insidious.

Hand-Rolled Linear Algebra

The library implements its own 3×3 and 6×6 matrix operations (~350 lines). Deliberate tradeoff — pulling in a full LA library for structured small-matrix operations adds dependency weight without meaningful benefit when the matrix dimensions are compile-time constants. The 9×9 drag STMs push the boundary of where this flips, but the operations are still structured enough (block matrix embedding) that generic LA isn't needed yet.

Solver Robustness

The targeting solver (Newton-Raphson with numerical Jacobian) uses a Clohessy-Wiltshire initial guess from the linearized Hill equations, adaptive damping in early iterations to stay in the convergence basin, and a singular Jacobian fallback for degenerate geometries where specific burn directions become ineffective. None of this is sophisticated — it emerged empirically from testing across the full scenario range. Convergence to 0.1 meter accuracy in 5–15 iterations is typical for formations from 100m to 10km.

Frontend Integration

The React layer consumes the orbital library through a service module that maps Zustand store actions to library calls.

Three stores with cross-store subscriptions. Mission state, simulation state, and UI state live in separate Zustand stores, with a sync layer (sync.ts) that bridges them — resetting the simulation when trajectory data changes. The mission store uses subscribeWithSelector so the 3D scene re-renders on trajectory changes, not sidebar toggles. This separation matters because mission recomputation is the expensive path, and you don't want it coupled to UI state transitions.

Incremental replanning. When a waypoint is dragged, only downstream legs are recomputed. The planner preserves converged legs before the modification point and resolves forward from the boundary state. This keeps multi-waypoint interactions fluid.

Synchronous main-thread solver. No Web Workers. For matrix multiplies at this scale, the serialization overhead of structured clone likely exceeds the computation cost. If this ever needs to move off the main thread, WASM is the more promising path — it avoids the serialization penalty entirely.

The Math Is Public. The UX Doesn't Have to Be 2005.

TypeScript is a credible platform for this class of problem. Types catch the bugs MATLAB can't detect. Browser deployment eliminates installation friction. Analytical formulations like Koenig et al.'s STMs provide the performance budget for real-time interactivity. The modern frontend ecosystem makes building rich 3D tools surprisingly tractable.

The barrier is no longer computational. It's architectural. The math is published. The papers are public. What's been missing is the software engineering to make it accessible.

The orbital library is designed to be consumed independently of the React app. If you're building relative motion analysis tools, formation flying simulators, or mission planning interfaces — this might save you from the MATLAB-script-on-a-shared-drive approach.

github.com/sakobu/koenig-guffanti-damico-roe-stm

What papers are you sitting on that could use a real implementation? If you've ported peer-reviewed math to production code, I'd like to hear what worked — and what the paper didn't prepare you for.

Pick a schema library. Pick a form library. Install a resolver to connect them. Thread errors.fieldName?.message through JSX. Call setError and clearErrors for server responses. Coordinate async field checks with schema validation. Realize your backend's error format doesn't match your form library. Write an adapter. Maintain the adapter.

Somewhere along the way, you start mass-producing translation layers instead of building product.

@railway-ts/use-form exists because I got tired of translating error formats across the stack.

The core idea is simple:

One error format, from schema to server to field — with nothing in between.

The same schema validates the frontend form and the backend request. The error shape produced by the server is the exact shape the form hook consumes. No resolver. No adapter. No format conversion. One data contract across the entire stack.

And because the hook implements Standard Schema v1, you don't need to adopt @railway-ts/pipelines to use it. Zod, Valibot, ArkType — anything that speaks the spec works immediately.

The Pitch in 30 Seconds

import * as S from "@railway-ts/pipelines/schema";
import { useForm } from "@railway-ts/use-form";

const schema = S.object({
  email: S.required(S.chain(S.string(), S.nonEmpty("Required"), S.email())),
  password: S.required(S.chain(S.string(), S.minLength(8, "Min 8 chars"))),
});

type Login = S.InferSchemaType<typeof schema>;

function LoginForm() {
  const form = useForm<Login>(schema, {
    initialValues: { email: "", password: "" },
    onSubmit: async (values) => { /* send to API */ },
  });

  return (
    <form onSubmit={(e) => void form.handleSubmit(e)}>
      <input {...form.getFieldProps("email")} />
      {form.getFieldError("email") && <span>{form.getFieldError("email")}</span>}

      <input type="password" {...form.getFieldProps("password")} />
      {form.getFieldError("password") && <span>{form.getFieldError("password")}</span>}

      <button type="submit" disabled={form.isSubmitting}>Log In</button>
    </form>
  );
}

That's a complete, type-safe, validated form. getFieldProps("emal") is a TypeScript error. form.errors is fully typed. The schema is the single source of truth.

Standard Schema: Use Whatever You Want

Standard Schema is a small TypeScript interface created by the authors of Zod, Valibot, and ArkType. It's not a validator — it's a contract. If a schema exposes a ~standard property with a validate method, useForm can consume it.

Your schema library is a local decision, not a stack-wide commitment.

With Zod

import { z } from "zod";
import { useForm } from "@railway-ts/use-form";

const schema = z.object({
  username: z.string().min(3, "Too short"),
  email: z.email("Invalid email"),
  password: z.string().min(8),
});

type User = z.infer<typeof schema>;

const form = useForm<User>(schema, {
  initialValues: { username: "", email: "", password: "" },
  onSubmit: (values) => console.log(values),
});

No zodResolver. No adapter layer. Full useForm API: getFieldProps, arrayHelpers, fieldValidators, setServerErrors, error prioritization — all available.

With @railway-ts/pipelines

The native schema unlocks additional capabilities: targeted cross-field validation, conditional validation, and Railway-oriented Result types — and it enables the full-stack symmetry covered later.

import * as S from "@railway-ts/pipelines/schema";

const schema = S.chain(
  S.object({
    password: S.required(S.chain(S.string(), S.minLength(8))),
    confirmPassword: S.required(S.chain(S.string(), S.nonEmpty("Required"))),
  }),
  S.refineAt(
    "confirmPassword",
    (d) => d.password === d.confirmPassword,
    "Passwords must match",
  ),
);

S.refineAt runs a cross-field check but attaches the error to a specific field. With most schema libraries, object-level refinements typically require manually mapping errors back to individual fields. Here, placement is explicit.

Three Error Layers, Deterministic Priority

Every form has three error sources: schema validation ("invalid email"), async field checks ("username taken"), and server responses ("email already registered"). Most form libraries merge them into a single bucket and let call order decide what the user sees.

useForm makes this deterministic:

Higher priority wins. Server errors override schema errors. Async checks override sync validation. Editing a field clears its server error and hands control back to validation.

Component code doesn't manage this. It just reads form.getFieldError("email") and displays whatever won.

Here's all three layers wired up in a single form:

const form = useForm<Registration>(schema, {
  initialValues: { username: "", email: "", password: "", confirmPassword: "" },

  // Layer 2: async per-field validators
  fieldValidators: {
    username: async (value) => {
      if (value.length < 3) return; // skip if sync already fails
      const res = await fetch(`/api/check-username?u=${encodeURIComponent(value)}`);
      const { available } = await res.json();
      return available ? undefined : `"${value}" is already taken`;
    },
  },

  // Layer 3: server errors on submit
  onSubmit: async (values) => {
    const res = await fetch("/api/register", {
      method: "POST",
      body: JSON.stringify(values),
    });
    if (!res.ok) {
      form.setServerErrors(await res.json());
      // { email: "Email already registered" }
      // Shows up on the email field. Clears when the user edits it.
    }
  },
});

The fieldValidators key is typed — it only accepts field names from your schema type.

Form-Level Errors

Not every error belongs to a field. Network failures and global server rejections are handled via ROOT_ERROR_KEY:

form.setServerErrors({
  email: "Already registered",
  [ROOT_ERROR_KEY]: "Registration failed. Please fix the errors below.",
});

One error contract, including form-level state.

The Full-Stack Payoff

This is where the thesis pays off.

The same schema drives the frontend form and the backend validation pipeline. The error format produced by formatErrorson the server is the exact Record<string, string> that setServerErrors expects on the client. No conversion layer. No field name mapping.

Shared schema:

// shared/schema.ts
import * as S from "@railway-ts/pipelines/schema";

export const registrationSchema = S.chain(
  S.object({
    username: S.required(S.chain(S.string(), S.nonEmpty(),     S.minLength(3))),
    email: S.required(S.chain(S.string(), S.nonEmpty(), S.email())),
    password: S.required(S.chain(S.string(), S.nonEmpty(), S.minLength(8))),
    confirmPassword: S.required(S.chain(S.string(), S.nonEmpty())),
  }),
  S.refineAt("confirmPassword", (d) => d.password === d.confirmPassword, "Passwords must match"),
);

export type Registration = S.InferSchemaType<typeof registrationSchema>;

Server:

import { validate, formatErrors } from "@railway-ts/pipelines/schema";
import { pipeAsync } from "@railway-ts/pipelines/composition";
import { ok, err, flatMapWith, match } from "@railway-ts/pipelines/result";
import { registrationSchema, type Registration } from "../shared/schema";

const checkEmailUnique = async (data: Registration) => {
  const exists = await db.user.findUnique({ where: { email: data.email } });
  return exists
    ? err([{ path: ["email"], message: "Email already registered" }])
    : ok(data);
};

const createUser = async (data: Registration) => {
  const user = await db.user.create({
    data: {
      username: data.username,
      email: data.email,
      password: await hash(data.password),
      age: data.age,
    },
  });
  return ok(user);
};

const handleRegistration = async (body: unknown) => {
  const result = await pipeAsync(
    validate(body, registrationSchema),
    flatMapWith(checkEmailUnique),
    flatMapWith(createUser),
  );

  return match(result, {
    ok: (user) => ({ status: 201, body: { id: user.id } }),
    err: (errors) => ({ status: 422, body: formatErrors(errors) }),
  });
};

Client:

onSubmit: async (values) => {
  const res = await fetch("/api/register", {
    method: "POST",
    body: JSON.stringify(values),
  });
  if (!res.ok) {
    form.setServerErrors(await res.json());
    // Server returned { email: "Email already registered" }
    // It shows up on the email field. Done.
  }
}

Follow the data: validate() returns Result<Registration, ValidationError[]>. If it passes, checkEmailUnique runs. If that passes, createUser runs. match branches once at the end. formatErrors converts ValidationError[] to Record<string, string>. The frontend calls setServerErrors and the error appears on the correct field.

Same schema. Same types. Same error format. No translation layer anywhere.

Conditional Validation

Fields that only matter under certain conditions:

const eventSchema = S.chain(
  S.object({
    title: S.required(S.chain(S.string(), S.nonEmpty())),
    isVirtual: S.optional(S.boolean()),
    platform: S.optional(S.string()),
    meetingUrl: S.emptyAsOptional(S.chain(S.string(), S.url())),
  }),
  S.when(
    (data) => !!data.isVirtual,
    S.chain(
      S.refineAt("platform", (d) => !!d.platform, "Platform required for virtual events"),
      S.refineAt("meetingUrl", (d) => !!d.meetingUrl, "URL required for virtual events"),
    ),
  ),
);

S.when applies validation conditionally. When isVirtual is false, platform and meetingUrl are ignored. When it's true, both become required — with errors on the right fields.

Combined with onFieldChange, dependent fields clear automatically:

const form = useForm(eventSchema, {
  initialValues: { title: "", isVirtual: false, platform: "", meetingUrl: "" },
  onFieldChange: (field, value) => {
    if (field === "isVirtual" && !value) {
      form.setFieldValue("platform", "", false);
      form.setFieldValue("meetingUrl", "", false);
    }
  },
});

Arrays, Modes, and Results

Dynamic lists and checkbox groups are type-safe through arrayHelpers:

const helpers = form.arrayHelpers("attendees");

helpers.push({ name: "", email: "", role: "" });
helpers.remove(2);
helpers.swap(0, 1);

// Per-item field binding and errors
<input {...helpers.getFieldProps(index, "name")} />
{helpers.getFieldError(index, "name") && <span>{helpers.getFieldError(index, "name")}</span>}

Validation timing is configurable via validationMode — live, blur, mount, or submit.

If you omit onSubmit, handleSubmit() returns a Railway-style Result, so submission can be pattern-matched instead of guarded with flags:

const result = await form.handleSubmit();

R.match(result, {
  ok: (values) => console.log("Valid:", values),
  err: (errors) => console.log("Errors:", errors),
});

The API stays consistent because the underlying contract stays consistent.

On Performance

useForm uses controlled inputs. Every keystroke updates React state. That's intentional: form state lives in React, not in a parallel ref system.

Uncontrolled approaches (like react-hook-form) avoid re-renders and can be faster for very large forms or live-preview editors. This library optimizes for architectural clarity and stack symmetry over micro-optimizing keystrokes.

For typical product forms — login, registration, CRUD under a few dozen fields — both approaches feel instant.

On Size

@railway-ts/use-form is ~3.6 kB gzip. @railway-ts/pipelines is ~4.8 kB gzip. A typical Zod + react-hook-form + resolver setup is significantly larger depending on configuration. If you're already using pipelines on the backend, the form hook is the only marginal cost.

Get Started

Already using Zod or Valibot? Install the hook and pass your existing schema directly to useForm. No resolver. No adapter. Full API immediately.

npm install @railway-ts/use-form @railway-ts/pipelines

Want full-stack validation symmetry? Use @railway-ts/pipelines as your schema library and share it across frontend and backend.

• Live Demo (StackBlitz) — five tabs, progressively complex

• npm

• GitHub

• Getting Started Guide

• API Reference

If you're tired of writing adapters between your schema, your server, and your form layer — this is built for you.

Forms aren't a UI problem. They're a data contract problem.

This library treats them that way.

This function can fail in these specific ways.

That's deliberate. Anders Hejlsberg has explained why checked exceptions create coupling and refactoring pain. TypeScript chose not to encode failure into the type system.

That tradeoff works until you start building pipelines.

Validation. Normalization. Business rules. External lookups. Enrichment.

At every stage, the type system tracks what flows forward on success.

On failure, it goes dark.

The error channel becomes invisible.

This article walks through the different ways to make that channel visible in TypeScript, what each approach costs, and where the library I built fits on that spectrum.

The Status Quo: Throw and Catch

Here's a typical pipeline:

async function processTransaction(raw: unknown):Promise<ProcessedTransaction> {
  const validated = validateTransaction(raw);
  const normalized = normalizeTransaction(validated);
  assertBusinessRules(normalized);

  try {
    return await enrichWithCustomerData(normalized);
  } catch {
    return makePartialResult(normalized);
  }
}

This works.

It's readable. It's idiomatic. Most production TypeScript looks like this.

The friction shows up later.

1) The call site can't see failure modes

The signature says:

Promise<ProcessedTransaction>

It does not say:

• This might throw ValidationError

• Or BusinessRuleError

• Or an enrichment failure

The only way to distinguish them is runtime narrowing on unknown. The type system can't help. If another team owns the caller, they must read your implementation to understand what can go wrong.

The type signature doesn't describe the failure surface.

2) Batch processing collapses error structure

Wrap this in a loop and every failure becomes "something threw." You lose the distinction between validation failures and business rule violations unless you manually re-encode it.

Switching from "keep the valid ones" to "fail the whole batch" means rewriting control flow, not flipping a strategy.

3) Recovery logic is invisible

This line:

return makePartialResult(normalized);

is a business decision inside a catch. The caller sees only ProcessedTransaction. Whether it's partial or complete isn't reflected in the type.

None of this is broken.

But in multi-stage pipelines, especially batch systems, the cost becomes visible.

Level 1: Discriminated Unions (Zero Dependencies)

The simplest typed-error approach is one you already know:

type ProcessResult =
  | { type: "success"; data: EnrichedTransaction }
  | { type: "validation_error"; errors: string[] }
  | { type: "business_rule"; reason: string }
  | { type: "partial"; data: PartialTransaction };

async function processTransaction(raw: unknown): Promise<ProcessResult> {
  const validation = validateTransaction(raw);
  if (validation.type === "validation_error") return validation;

  const normalized = normalizeTransaction(validation.data);

  const ruleCheck = checkBusinessRules(normalized);
  if (ruleCheck.type === "business_rule") return ruleCheck;

  const enrichment = await enrichWithCustomerData(normalized);
  if (enrichment.type === "success") return enrichment;

  return { type: "partial", data: makePartialResult(normalized) };
}

This is a real improvement.

The error channel is visible in the type. The compiler forces narrowing. There's no dependency and every TypeScript developer understands it.

The tradeoffs:

• The union is per-pipeline, not per-stage.

• Composition is manual (if (...) return ... everywhere).

• Batch semantics are DIY per union type.

For one or two pipelines, this is probably the right solution.

When you have five pipelines and each grows to six stages, the repetition starts to show.

Level 2: A Standardized Result Type (neverthrow)

neverthrow standardizes the discriminated union into Result<T, E> with helpers like map, andThen, and match:

import { ok, err } from "neverthrow";

const result = validateRaw(input)
  .andThen(normalize)
  .andThen(applyBusinessRules);

This removes the short-circuit boilerplate. Errors propagate automatically.

neverthrow gives you:

• A consistent Result abstraction

• Clean chaining

• A small conceptual footprint

What it intentionally does not give you:

• A pipeline composition model

• Batch semantics across arrays of results

• A schema layer

• Cross-cutting tracing hooks

neverthrow is a Result type.

It standardizes how one function communicates success or failure.

It does not define how functions compose into reusable pipeline values.

That distinction matters once pipelines become architectural patterns instead of one-offs.

Level 3: Result + Option + Composition + Schema (@railway-ts/pipelines)

This is the missing middle I kept running into.

@railway-ts/pipelines keeps the same Result<T, E> idea but adds:

• Point-free composition (flow, flowAsync)

• Batch semantics (partition, combine, combineAll)

• An Option type

• A schema module integrated directly into the error track

The same pipeline becomes:

import { flowAsync } from "@railway-ts/pipelines/composition";
import { ok, err, flatMapWith, orElseWith } from "@railway-ts/pipelines/result";

const processTransaction = flowAsync(
  validateRaw,
  flatMapWith(normalize),
  flatMapWith(applyBusinessRules),
  flatMapWith(enrichWithCustomerData),
  orElseWith(recoverPartial),
);

Instead of chaining off a starting value, flowAsync produces a pipeline as a first-class function.

That means you can:

• Pass it around

• Wrap it with tracing

• Test it independently

• Swap recovery strategies

The pipeline itself becomes a value.

Batch Semantics as a Strategy

Given:

const results = await Promise.all(records.map((r) => processTransaction(r)));

You can choose interpretation:

import { partition, combine, combineAll } from "@railway-ts/pipelines/result";

const { successes, failures } = partition(results);
const allOrNothing = combine(results);
const allErrors = combineAll(results);

Switching behavior is a one-line change. No control-flow rewrite.

Why Schema Belongs Here

If the goal is to make the error channel visible, validation is the first place it appears.

Most pipelines start by turning unknown into typed data. That transformation produces:

• A parsed value

• Structured validation errors

If validation lives outside your error abstraction, the model breaks immediately.

That's why the schema module is included—not to compete with standalone validators, but to ensure validation failures share the same typed error track as business rule and enrichment failures.

The module is benchmarked on schemabenchmarks.dev and fully tree-shakable.

Schema isn't an add-on. It's the front door to the pipeline.

Tracing Without Modifying Stages

Once a pipeline is a composed value, observability becomes compositional too.

tapWith and tapErrWith observe values on either track without changing results. A traced pipeline and an untraced pipeline produce identical output for identical input.

Instrumentation becomes insertion, not intrusion. The ETL demo visualizes this — each record's stage trace shows exactly where it succeeded, where it failed, and how long each stage took, all captured by taps woven into the pipeline.

What It Costs

• A dependency

• New primitives (flowAsync, flatMapWith)

• A more declarative style

The imperative version is immediately readable.

The composed version requires learning a protocol.

Whether that's worth it depends on:

• How many pipelines you have

• How complex your batch logic is

• Whether your team values explicit error types enough to learn new abstractions

Level 4: Effect-TS

Effect-TS goes further than any of the above.

An Effect<A, E, R> models:

• Success

• Typed errors

• Required dependencies

• Concurrency

• Resource safety

• Scheduling

Effect is not just a container for success or failure. It's a full runtime and programming model.

Adopting it means adopting:

• A fiber-based concurrency system

• A layer-based dependency model

• An execution boundary (runPromise, etc.)

That's a framework-level commitment.

If your team wants typed errors as part of a broader architectural system, Effect is powerful.

If your problem is simply:

I have multi-stage data pipelines and I want failures to compose as data.

A lightweight Result + composition layer may be sufficient.

The difference isn't capability.

It's scope and commitment.

When to Use What

Throw and catch

When failure handling happens at boundaries and you don't need programmatic distinction.

Discriminated unions

When you have a small number of pipelines and want zero dependencies.

neverthrow

When you want a standardized Result with clean chaining.

@railway-ts/pipelines

When pipelines are recurring architecture, batch semantics matter, and validation should integrate with composition.

Effect-TS

When typed errors are part of a larger concurrency and dependency story.

The Missing Middle

There's a spectrum in TypeScript:

• Exceptions at the boundary

• Hand-rolled unions

• A standalone Result

• A full effect system

What I kept hitting in production was a gap in the middle.

A way to:

• Treat failures as data

• Compose multi-stage pipelines without boilerplate

• Switch batch strategies without rewriting loops

• Drive validation and forms from one definition

• Add tracing without modifying business logic

Without committing to an entire programming model.

That's the niche @railway-ts/pipelines is designed for.

If you've written the same validation → normalization → rule-check pipeline five times in one codebase, you already know the problem this is solving.

There's an interactive ETL demo you can run in the browser. Edit records, switch between partition, combine, and combineAll, and watch how the same data produces different batch outcomes.

If it feels wrong, awkward, or incomplete, I'd genuinely like to hear why. The sharpest feedback comes from engineers who've lived through these tradeoffs.

• GitHub — @railway-ts/pipelines

• GitHub — @railway-ts/use-form

• npm — @railway-ts/pipelines

• npm — @railway-ts/use-form