Forem: Sarkis M

I Ported a Peer-Reviewed Astrodynamics Paper to TypeScript. Here's Why.

Sarkis M — Wed, 04 Mar 2026 19:04:19 +0000

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 aa, bb, dd_lambda because MATLAB doesn't have types. Visualization is a non-interactive figure window. Collaboration is a shared drive. Every new team reimplements the same papers from scratch, introduces the same bugs, builds the same bad UIs.

The web has solved this problem for virtually every other domain. Finance has interactive dashboards. Data science has Observable notebooks. Mapping has Mapbox. Astrodynamics has MATLAB figure windows and STK if you can afford the license.

I decided to change that for one particular domain. I took Koenig, Guffanti, and D'Amico's 2017 paper on State Transition Matrices for perturbed relative motion — from the Journal of Guidance, Control, and Dynamics — and implemented it as a TypeScript library with a 3D interactive mission planner that runs entirely in the browser. 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.

Try the live demo →

No MATLAB license. No install. No backend. Click to place waypoints in 3D space, toggle perturbation models, watch a deputy spacecraft fly the computed trajectory. This is the same math that flies real missions.

What I Actually Built

The project has two layers:

1. An orbital mechanics library (src/orbital/) — pure TypeScript, zero framework dependencies. Implements three fidelity levels of State Transition Matrices from the Koenig et al. paper:

Model	Matrix Size	What It Captures
Keplerian	6×6	Two-body motion only
J2-Perturbed	6×6	Earth's equatorial bulge (nodal regression, apsidal precession)
J2 + Drag	7×7 / 9×9	Atmospheric drag with density-model-free formulation

Plus a targeting solver (Newton-Raphson iterative root-finding for rendezvous), a mission planner that chains multi-waypoint transfers, Gauss Variational Equations (how impulsive burns map to orbit changes), and ROE ↔ RIC coordinate transforms.

2. A 3D mission planner — React 19, React Three Fiber, Zustand, Tailwind. Interactive waypoint placement, real-time trajectory recomputation, simulation playback with telemetry HUD, and data export to JSON/CSV.

The library is framework-agnostic. You could use it in a Node script, a Bun project, a WASM module — the React app is just one consumer.

Why This Paper

Not all astrodynamics papers are created equal for the purpose of porting to a web environment.

Koenig et al.'s approach uses analytical State Transition Matrices instead of numerical integration. This is the key architectural decision that makes browser-native implementation viable.

Numerical integration (Runge-Kutta, etc.) requires hundreds or thousands of timesteps, each with expensive trigonometric evaluations. It's inherently iterative and hard to make fast in JavaScript. Analytical STMs reduce propagation to a single matrix-vector multiply — for a 6×6 matrix, that's 36 multiplies and 30 adds. Done. The state at any future time falls out directly.

This means the targeting solver — which calls propagation on every Newton-Raphson iteration, and again 6 times per Jacobian evaluation — runs in microseconds instead of milliseconds. Which means the mission planner can recompute trajectories on every frame while the user drags a waypoint in 3D space. Which means the tool feels interactive rather than "click compute and wait."

Drag a waypoint 200 meters radially outward. The planner recomputes departure burns, coast arcs, and arrival burns in under a millisecond. That's analytical propagation at work — not clever optimization, not caching, just math that's inherently fast enough.

The paper also uses a Relative Orbital Elements (ROE) formulation instead of Cartesian state vectors. ROE describes how two orbits differ — relative semi-major axis, relative eccentricity vector, relative inclination vector — rather than tracking two absolute positions. Perturbations separate cleanly in this space. J2 effects show up as known secular drift rates. Drag adds coupling terms with known structure. Each perturbation layer extends the STM while preserving the analytical form.

Porting PhD-Level Math to TypeScript: What That Actually Involves

This is the part that's hard to convey in a README.

The paper is 20+ pages of derivations. The STMs reference orbital factors (κ, η, P, Q, and others) that are themselves functions of eccentricity, inclination, and Earth's J2 coefficient. The drag model introduces a "density-model-free" formulation where you don't need an atmospheric density profile — instead, you parameterize the drag effect as rates of change of ROE components. The 9×9 arbitrary-eccentricity drag matrix has elements that are polynomials in these factors.

Translating this means:

Reading the paper deeply enough to implement it, not just cite it. You need to understand what each matrix element represents physically, because when your output is wrong, the debugger doesn't tell you "sign error in row 3, column 5 of the J2 STM." It tells you the trajectory curves the wrong way. Knowing that row 3 corresponds to δex (eccentricity x-component) and that a sign flip there would reverse the apsidal precession is how you find the bug.

Handling the notation translation. Academic papers use compact notation that maps poorly to code. Subscripts, superscripts, overlines, primes — all of these become variable names. The paper's Ω̇ becomes something like raanDrift and you need to make sure every consumer of that value knows it's a rate in rad/s, not rad/orbit.

Here's the moment it stops being abstract and becomes software — the J2 STM in TypeScript. The paper defines a 6×6 matrix where each row captures how one ROE component evolves under J2 perturbations. Orbital factors like kappa, E, F, G, P, Q, S, T encode how Earth's oblateness affects the orbit — and they compose into matrix elements that track apsidal precession (eccentricity vector rotation) and nodal regression (orbit plane drift):

// 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],
];

This is a direct translation of the paper's Equation A6. Each element is a product of orbital factors and time — no numerical integration, no timestep loops, just algebra. That's what makes it fast enough to call hundreds of times per second in the targeting solver.

Getting the constants and units right. The J2 coefficient, Earth's gravitational parameter, equatorial radius — these are well-known values, but the paper may normalize differently than your implementation. A factor-of-two error in how you apply J2 produces trajectories that look plausible but are quantitatively wrong. There's no compiler warning for "your orbital factor η should use 1 - e², not 1 - e."

Making the API not terrible. The paper's formulation is beautiful math. The TypeScript API needs to be something a developer can use without reading the paper. That means clear type definitions, sensible defaults, and function signatures that guide you toward correct usage:

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;
};

Every field is readonly. The types are self-documenting. You can't accidentally mutate a maneuver leg and corrupt downstream computations. This is the kind of thing MATLAB doesn't even have a concept for.

Validating correctness is the scariest part. 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. 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.

The validation approach: implement the same dynamics as an RK4 numerical integrator, propagate using both the STM and the brute-force integrator, and verify they 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 closes the loop — the person who derived the math checking the port.

Making It Interactive: The 3D Planner

The math is the foundation, but the tool is the point.

The planner uses React Three Fiber for 3D rendering. The chief spacecraft sits at the origin, the deputy moves along computed trajectories, and the user places waypoints by clicking in 3D space. Dragging a waypoint triggers incremental replanning — only the legs affected by the change are recomputed, keeping the interaction fluid even with complex missions.

Three Zustand stores with cross-store subscriptions. Mission state (orbit parameters, waypoints, computed plan), simulation state (playback time, speed), and UI state (sidebar, HUD) are separate stores, with a sync layer that bridges them. The mission store uses subscribeWithSelector so the 3D scene only re-renders when trajectory data changes, not when the user toggles the sidebar.

Synchronous solver on the main thread. The solver doesn't use Web Workers. For 6×6 matrix multiplies, the structured clone serialization overhead of posting data to a worker would likely exceed the computation cost itself. The entire multi-waypoint planning loop — including TOF optimization via golden section search — completes fast enough that it runs between frames.

The solver needs to handle every waypoint a user can click, not just textbook cases. A pure Newton-Raphson solver diverges on many real inputs. Here's what that looks like in practice:

// From src/orbital/targeting/rendezvous.ts — adaptive damping
let dv1Correction: Vector3;
try {
  const jacobianInv = invert3x3(jacobian);
  dv1Correction = matMul3x3_3x1(jacobianInv, positionError);
} catch {
  // Jacobian singular — use gradient descent fallback
  dv1Correction = positionError;
}

let damping: number;
if (iter < 3) {
  damping = 0.5;
} else if (iter < 10) {
  damping = 0.8;
} else {
  damping = 1;
}
dv1 = add3(dv1, [
  damping * dv1Correction[0],
  damping * dv1Correction[1],
  damping * dv1Correction[2],
]);

Aggressive damping early, relax toward full Newton steps as the solver converges, fall back to gradient descent when the Jacobian goes singular. None of this was derived from theory — it came from watching the solver blow up on edge cases and tuning until it converged reliably across all scenario presets.

This Is What Browser-Native Mission Design Looks Like

A mission analyst opens a URL, loads an ISS-altitude scenario, places three waypoints in 3D space, toggles J2 perturbations, and watches the delta-v budget update in real time. No MATLAB license, no installation, no waiting.

The math in these papers is public. The STMs, the Gauss Variational Equations, the targeting algorithms — all published and peer-reviewed. We don't need to wait for legacy vendors to modernize.

TypeScript gives you types that prevent the class of bugs MATLAB can't even detect. Browser deployment eliminates the install. Analytical STMs give you the performance budget for real-time interactivity. Five years ago, this would have required a desktop application and a license. Now it runs in a browser tab with zero infrastructure.

The orbital mechanics library is framework-agnostic and designed to be consumed independently. If you're building anything involving relative spacecraft motion, it might save you from reimplementing Koenig et al. from a MATLAB script on a shared drive.

GitHub: sakobu/koenig-guffanti-damico-roe-stm

What domain-specific math are you sitting on that deserves a serious frontend? If you've hit the MATLAB-to-browser gap in your own field, I'd love to hear what paper you'd port first.

The Smallest Schema Library on the Market (and the Form Hook Built on Top of It)

Sarkis M — Thu, 26 Feb 2026 15:00:00 +0000

I'm going to make a claim and back it up: @railway-ts/pipelines ships the smallest schema validation bundle of any library available today. Smaller than Valibot. Smaller than Zod, Yup, TypeBox, io-ts — all of them.

Don't take my word for it. This is benchmarked by schemabenchmarks.dev, a comparison site created by Open Circle — the organization behind Valibot.

That alone might be interesting. But a small schema library isn't useful if it can't handle real forms. So I built @railway-ts/use-form — a 3.6 kB React hook where the schema is the validator. No resolver. No adapter. No translation layer between your validation logic and your form state.

Here's what that actually means in practice, and why I think the current form ecosystem has a glue-code problem worth solving.

The Glue-Code Tax

The standard React form stack looks like this: pick a schema library, pick a form library, install a resolver package to connect them, then manually thread errors.fieldName?.message through your JSX. It works. It's also three packages and a bunch of wiring that has nothing to do with your actual validation logic.

The tax isn't the login form. A login form is two fields — anything works. The tax shows up when things get real: cross-field validation, async uniqueness checks, server errors that need to map back to specific fields, dynamic array fields with per-item validation. That's where the adapter pattern starts to creak.

@railway-ts/use-form sidesteps all of it. You define a schema, pass it to useForm, and you're done. The schema handles validation, type inference, and error messages. The hook handles state, touched tracking, and field binding. There's nothing in between.

Where It Actually Gets Interesting

I'm not going to walk through basic field binding — there's a live demo on StackBlitz for that. Instead, here are three things that are genuinely hard to do cleanly with other libraries.

Cross-field validation + server errors in one form

This is a signup form with password confirmation, async username checking, and server-side email validation — three different error sources that all need to surface on the right field:

const baseSchema = S.object({
  username: S.required(S.chain(S.string(), S.nonEmpty("Required"), S.minLength(3, "Min 3 chars"))),
  email: S.required(S.chain(S.string(), S.nonEmpty("Required"), S.email("Invalid email"))),
  password: S.required(S.chain(S.string(), S.nonEmpty("Required"), S.minLength(8, "Min 8 chars"))),
  confirmPassword: S.required(S.chain(S.string(), S.nonEmpty("Confirm your password"))),
});

type SignupValues = S.InferSchemaType<typeof baseSchema>;

const signupSchema = S.chain(
  baseSchema,
  // Cross-field: receives the whole object, targets a specific field
  S.refineAt<SignupValues>("confirmPassword", (data) => data.password === data.confirmPassword, "Passwords must match"),
);

const form = useForm(signupSchema, {
  initialValues: { username: "", email: "", password: "", confirmPassword: "" },
  // Async per-field: debounced automatically, surfaces on the field
  fieldValidators: {
    username: async (value) => {
      const taken = await checkUsername(value);
      return taken ? "Already taken" : undefined;
    },
  },
  onSubmit: async (values) => {
    const result = await createAccount(values);
    if (result.type === "EMAIL_TAKEN") {
      // Server errors: same error system, keyed by field name
      form.setServerErrors({ email: "Already registered" });
    }
  },
});

Three error layers — schema validation, async field validators, server errors — all flowing through the same getFieldError() call. No special handling per source.

One thing worth calling out: every field path is fully typed. getFieldProps("emai") is a compile error — TypeScript infers the valid field names from your schema, so you get autocomplete on every field binding and can't fat-finger a field name into a runtime bug.

Conditional validation that composes

Virtual events need a platform and meeting URL. In-person events don't. S.when lets you express this as a composable validation rule instead of imperative if blocks:

const eventSchema = S.chain(
  baseEventSchema,
  S.when<EventValues>(
    (data) => !!data.isVirtual,
    S.chain(
      S.refineAt("platform", (data) => !!data.platform, "Required for virtual events"),
      S.refineAt("meetingUrl", (data) => !!data.meetingUrl, "Required for virtual events"),
    ),
  ),
);

The conditional validation lives in the schema, not scattered across useEffect hooks or imperative validation functions. It composes with S.chain like everything else.

Submit returns a Result, not a prayer

This is the one that functional programming people will appreciate. You don't need an onSubmit callback. handleSubmit() returns a Result<T, ValidationError[]> that you can pattern-match on:

import * as R from "@railway-ts/pipelines/result";

const result = await form.handleSubmit(e);

R.match(result, {
  ok: (values) => showSuccess(values),
  err: (errors) => showValidationSummary(errors),
});

No try/catch. No silent failures. The types enforce that you've handled both paths. And because everything in the pipeline is Result-based, form submission composes cleanly with async workflows:

import { flowAsync } from "@railway-ts/pipelines/composition";

const submit = flowAsync(
  validateWithSchema,
  R.flatMapWith(saveToDatabase),
  R.tapWith(sendConfirmationEmail),
);

flatMapWith chains async operations that return Result, tapWith runs async side effects and passes the value through. Every step either succeeds and passes data forward, or fails and short-circuits with a typed error. It's the same pattern the whole @railway-ts/pipelines library is built on.

The Full Picture

There's more that didn't fit the narrative above — dynamic array fields with arrayHelpers (push, remove, swap, per-item validation), four validation modes (live, blur, submit, mount), checkbox/select/slider bindings, onFieldChange callbacks for dependent field clearing. The StackBlitz demo covers all of it across five tabs, progressively. No install required — edit the forms live in your browser.

Why I Built This

I got tired of the adapter pattern. Schema validation and form state are the same concern — "is this data valid, and if not, where and why?" — split across multiple packages with a translation layer in between. Making the schema the single source of truth for validation, types, and error messages eliminates an entire category of wiring code.

The bundle size wasn't a goal — it was a side effect of keeping the API surface small and not pulling in dependencies. But I'll take it.

If you're interested:

The Pipeline That Doesn't Know It's Being Watched

Sarkis M — Mon, 23 Feb 2026 02:41:01 +0000

The pipeline that processes your records and the pipeline that traces them are the same pipeline. That sentence should feel wrong — tracing means logging, timing, capturing intermediate state. That's side-effect territory. You'd expect the traced version to be a different thing, wired with callbacks and context objects, behaving subtly differently under pressure.

It isn't. And the way it works changed how I think about composing software around a core that shouldn't be touched.

The Problem With Observability That Modifies What It Observes

You have a pipeline — four stages, composed together, each taking a Result and returning a Result. It works. Now product wants a visualization: show which stage each record passed through, how long each took, where failures forked off the happy path.

The natural instinct is to reach inside. Add a logger to each stage function. Pass a context object through. Wrap each stage in a decorator that captures timing. Every approach has the same shape: you modify the thing you're trying to observe.

And now you have two problems. The production pipeline and the traced pipeline are different code paths. They can diverge. The tracing might swallow an exception. The timing wrapper might change async scheduling. You're not observing the pipeline anymore — you're observing a different pipeline that you hope behaves the same way.

What if the observation points were composed between stages, in the same way the stages themselves are composed? What if the pipeline couldn't tell the difference?

Interleaving Observation

Here's the production pipeline. Four stages, one recovery step, no instrumentation:

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

And here's the traced version:

const createTracedPipeline = () => {
  const tracer = createTracer();

  const pipeline = flowAsync(
    validateRaw,
    tapWith((tx: Transaction) => tracer.recordOk("validate", tx)),
    flatMapWith(normalize),
    tapWith((tx: NormalizedTransaction) => tracer.recordOk("normalize", tx)),
    flatMapWith(applyBusinessRules),
    tapWith((tx: NormalizedTransaction) =>
      tracer.recordOk("businessRules", tx),
    ),
    flatMapWith(enrichWithCustomerData),
    tapWith((tx: EnrichedTransaction) => tracer.recordOk("enrich", tx)),
    tapErrWith((error: string) => tracer.recordErr(error)),
    orElseWith(recovery),
  );

  return { pipeline, tracer };
};

Look at what didn't change. Every stage function is identical. The composition order is identical. validateRaw, normalize, applyBusinessRules, enrichWithCustomerData, recovery — all untouched. The only additions are tapWith and tapErrWith calls slotted between stages.

tapWith runs its callback when a value passes through on the ok track, then forwards that value unchanged. tapErrWith does the same on the err track. They're observation points that participate in the composition but not in the logic. The pipeline genuinely cannot tell they're there.

This only works because the composition model treats observation the same way it treats transformation — as a function in the chain. There's no special "middleware" concept, no decorator protocol. A tap is just another step that happens to return its input untouched.

Reconstructing What Happened

The clever part isn't the taps. It's what happens after.

The pipeline returns a single Result — either ok(processedTransaction) or err("some message"). That's the whole output. But the tracer has been quietly accumulating entries as each tap fired. After the pipeline completes, tracer.buildStages() reconstructs the full four-stage trace from those breadcrumbs.

Take a concrete example. Record #2 — bob@example.com, $50 USD, December 2024. It passes validation, passes normalization, then fails business rules because the date is before the 2025 cutoff. The pipeline returns err("Transaction too old").

The tracer's entries array after execution:

[ { stage: "validate",  value: {...}, timestamp: 1.2 },
  { stage: "normalize", value: {...}, timestamp: 1.5 } ]

Two entries. The tapErrWith also captured "Transaction too old" with its own timestamp.

Now buildStages() walks the four-stage order and applies three rules:

Stage has a recorded entry → ok, duration derived from timestamps.
First missing stage whose predecessor was ok → err, with the captured error message.
Everything after that → skipped.

Output: [ok, ok, err, skipped]. Validate ✓ → Normalize ✓ → Business Rules ✗ → Enrich skipped.

From a single error string and two breadcrumbs, the tracer reconstructed exactly where and when the pipeline diverged. That's what the demo renders in the center panel — not a log dump, but a visual trace showing each record's path through the pipeline, with timing, fork points, and recovery status.

Record #5 shows the recovery case. It passes all stages, then enrichWithCustomerData fails because the customer isn't in the mock database. But the orElseWith recovery catches customer-lookup failures and converts them to partial results. The tracer sees three ok entries, plus the error capture, and the final result is ok({ partial: true }). Four stages visible, enrichment marked with ◐ instead of ✗. Partial success, not failure.

One Schema in Two Contexts

There's a second pattern in the demo that's less surprising but saves real maintenance pain.

In most form + pipeline setups, you define validation constraints twice. Even when tools let you share, there's glue. With Zod and react-hook-form, for example, you share the schema but still need a resolver adapter to bridge the two worlds:

// Same schema, but you still need this adapter
const form = useForm({
  resolver: zodResolver(transactionSchema),
  defaultValues: record.data,
});

In the demo, transactionSchema is declared once and imported directly into both contexts with no adapter at all:

// Pipeline side — validates raw input on entry
export const validateRaw = (raw: unknown): Result<Transaction, string> => {
  const result = validate(raw, transactionSchema);
  // ...
};

// Form side — same schema, no resolver, no translation layer
const form = useForm(transactionSchema, {
  initialValues: record.data,
  onSubmit: (values) => updateRecord(index, values),
});

The email() validator that rejects "not-an-email" in the pipeline is the same validator that shows an inline error when you type it into the form. Change a constraint in one place, both contexts pick it up. The schema also infers the TypeScript type, so there's no separate type definition drifting out of sync.

It's not a breakthrough — it's just what happens when the schema layer is designed to work as both a runtime validator and a form driver from the start, rather than bolting the form integration on after.

Batch Semantics, Three Ways

One more thing the demo makes visible. After the pipeline runs, the right panel applies three aggregation strategies to the same batch of results:

partition splits successes from failures and keeps both. The ETL default — process what you can, quarantine what you can't.
combine is all-or-nothing, stops at the first error. For atomic operations where partial success is meaningless.
combineAll is all-or-nothing but collects every error. For import validation where you want to surface all problems before rejecting.

With try/catch, each of these is a custom accumulation loop with its own subtle bugs. With Result, they're one-liners on results the pipeline already produced. When record #2 fails, combine and combineAll both reject the entire batch. partition shows 4 successes alongside that failure. Same data, different semantics, visible side by side.

What This Pattern Enables

Both the tracing and the schema sharing come from the same design choice: compose around the pipeline rather than modifying it.

The schema is shared by importing one declaration into both contexts — not by building an adapter between two different systems. The tracing is added by interleaving taps into the composition — not by modifying stage functions. The batch semantics are computed by running combinators over existing results — not by changing how those results are produced.

But the interesting question is what else you could slot into those gaps. The same tapWith mechanism that drives a visualization could drive an audit log, a performance budget that rejects slow stages, a diff tracker that compares outputs across pipeline versions, a circuit breaker that trips after N consecutive failures. Each would be composed between stages the same way. Each would leave the pipeline unaware.

The constraint — observation can't modify what it observes — turns out to be generative. When you can't reach inside, you find better places to stand.

ETL Pipeline Dashboard on StackBlitz — if StackBlitz appears stuck on "cloning from repo", hit refresh (known StackBlitz bug).

GitHub: @railway-ts/pipelines · @railway-ts/use-form

Building a Type-Safe Data Processing Pipeline in TypeScript

Sarkis M — Fri, 20 Feb 2026 01:55:00 +0000

This is a companion post to the Railway-Oriented TypeScript series — a bonus deep-dive showing the pipeline library in an ETL context, with no React or UI. If you haven't read the main series, start here. The pipeline operators are covered in Part 2; this part covers what's new for batch processing: combine, combineAll, partition, reusable sub-pipelines, and structured error reporting.

You have messy data from an external source. Some records are malformed, some fail business rules, some need enrichment from an async service. You need clean results, structured error reports, and graceful recovery — and you need all of this to work across thousands of records without accumulating a hand-rolled error tracking loop in every pipeline.

Here's how the Result model handles it.

Open in StackBlitz — run the full pipeline in your browser, no setup required.

Schema for a Single Record

Records arrive as JSON with string values — common when pulling from CSVs or external APIs. The schema handles type coercion:

import {
  validate,
  object,
  required,
  chain,
  string,
  nonEmpty,
  email,
  parseNumber,
  min,
  parseDate,
  refine,
  formatErrors,
  type InferSchemaType,
  type ValidationError,
} from "@railway-ts/pipelines/schema";

const transactionSchema = object({
  id: required(chain(string(), nonEmpty())),
  customerEmail: required(chain(string(), nonEmpty(), email())),
  amount: required(chain(parseNumber(), min(0.01, "Amount must be positive"))),
  currency: required(
    chain(
      string(),
      refine((s) => ["USD", "EUR", "GBP"].includes(s), "Unsupported currency"),
    ),
  ),
  date: required(parseDate()),
});

type Transaction = InferSchemaType<typeof transactionSchema>;

parseNumber() converts "42.50" → 42.50. parseDate() converts "2025-03-15" → Date. refine() applies a custom predicate. All errors accumulate — you get every problem in a record at once, not just the first.

validate returns Result<Transaction, ValidationError[]> directly — no SafeParseReturnType, no conversion.

Processing Pipeline

The operators here are covered in Part 2. What's worth noting is how they compose in a data processing context — particularly how mapWith(normalize) and flatMapWith(enrichWithCustomerData) build a typed chain where each step's output becomes the next step's input:

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

const USD_RATES: Record<string, number> = { USD: 1, EUR: 1.08, GBP: 1.27 };

const normalize = (tx: Transaction) => ({
  ...tx,
  amountUSD: +(tx.amount * (USD_RATES[tx.currency] ?? 1)).toFixed(2),
  dateFormatted: tx.date.toISOString().split("T")[0],
});

type NormalizedTransaction = ReturnType<typeof normalize>;

const enrichWithCustomerData = async (tx: NormalizedTransaction) => {
  const res = await fetch(
    `/api/customers?email=${encodeURIComponent(tx.customerEmail)}`,
  );
  if (!res.ok) return err(`Customer lookup failed for ${tx.customerEmail}`);
  const customer = await res.json();
  return ok({ ...tx, customerName: customer.name, tier: customer.tier });
};

type EnrichedTransaction = NormalizedTransaction & {
  customerName: string;
  tier: string;
};

const MINIMUM_AMOUNT_USD = 10;

const processTransaction = flowAsync(
  (raw: unknown) => validate(raw, transactionSchema),
  mapErrWith((errors: ValidationError[]) =>
    Object.entries(formatErrors(errors))
      .map(([field, msg]) => `${field}: ${msg}`)
      .join("; "),
  ),
  mapWith(normalize),
  flatMapWith(enrichWithCustomerData),
  filterWith(
    (tx: EnrichedTransaction) => tx.amountUSD >= MINIMUM_AMOUNT_USD,
    `Transaction below minimum ($${MINIMUM_AMOUNT_USD})`,
  ),
  tapWith((tx: EnrichedTransaction) =>
    console.log(`Processed: ${tx.id} — $${tx.amountUSD} (${tx.customerName})`),
  ),
  tapErrWith((error: string) => console.error(`[pipeline error] ${error}`)),
  orElseWith((error: string) => {
    if (error.startsWith("Customer lookup failed")) {
      return ok({
        partial: true,
        message: "Processed without customer data",
        error,
      });
    }
    return err(error);
  }),
);

If any step returns Err, all subsequent steps are skipped. Recovery in orElseWith is localized — changing it doesn't touch anything else in the pipeline.

await processTransaction({
  id: "tx-001",
  customerEmail: "alice@example.com",
  amount: "150.00",
  currency: "EUR",
  date: "2025-03-15",
});
// → Ok({ id: "tx-001", amountUSD: 162.00, customerName: "Alice Smith", ... })

await processTransaction({
  id: "",
  customerEmail: "not-an-email",
  amount: "-5",
  currency: "BTC",
  date: "not-a-date",
});
// → Err("id: String must not be empty; customerEmail: Invalid email format; ...")

await processTransaction({
  id: "tx-002",
  customerEmail: "bob@example.com",
  amount: "5.00",
  currency: "USD",
  date: "2025-03-15",
});
// → Err("Transaction below minimum ($10)")

Batch Processing

This is what the Result model earns its keep over try/catch in a batch context. Process all records first, then decide what to do with the results:

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

const results = await Promise.all(rawRecords.map(processTransaction));

Three batch semantics, one call each:

combine — all-or-nothing, fail fast. If any record fails, the whole batch is an Err with the first failure. Use this when the batch must entirely succeed or the whole job is invalid.

const batchResult = combine(results);
match(batchResult, {
  ok: (transactions) => console.log(`All ${transactions.length} processed`),
  err: (error) => console.error(`Batch failed: ${error}`),
});

combineAll — all-or-nothing, all errors. If any record fails, you get every failure at once. Useful for import validation where you want to show users all problems before they fix anything.

const batchResult = combineAll(results);
match(batchResult, {
  ok: (transactions) => console.log(`All ${transactions.length} processed`),
  err: (errors) =>
    errors.forEach((e, i) => console.error(`  Error ${i + 1}: ${e}`)),
});

partition — keep both sides. Every record gets processed; successes and failures are separated at the end. This is what ETL workloads typically need.

const { successes, failures } = partition(results);
console.log(`Processed: ${successes.length}, Failed: ${failures.length}`);

With try/catch, each of these semantics is a custom accumulation loop you write from scratch. With Result, they're one-liners on top of results you already have.

Reusable Sub-Pipelines

flow composes steps into a named, reusable function — meaning sub-pipelines compose into larger pipelines without any special wiring:

import { flow } from "@railway-ts/pipelines/composition";

const validateAndNormalize = flow(
  (raw: unknown) => validate(raw, transactionSchema),
  mapErrWith((errors: ValidationError[]) =>
    Object.entries(formatErrors(errors))
      .map(([field, msg]) => `${field}: ${msg}`)
      .join("; "),
  ),
  mapWith(normalize),
);

const applyBusinessRules = flow(
  filterWith(
    (tx: NormalizedTransaction) => tx.amountUSD >= MINIMUM_AMOUNT_USD,
    `Below minimum ($${MINIMUM_AMOUNT_USD})`,
  ),
  filterWith(
    (tx: NormalizedTransaction) => tx.date >= new Date("2025-01-01"),
    "Transaction too old",
  ),
);

// Compose into the full pipeline
const processTransaction = flowAsync(
  validateAndNormalize,
  applyBusinessRules,
  flatMapWith(enrichWithCustomerData),
  tapWith((tx: EnrichedTransaction) => console.log(`Done: ${tx.id}`)),
);

// Or compose for a dry-run that skips side effects
const validateOnly = flow(validateAndNormalize, applyBusinessRules);
const dryRunResult = validateOnly(rawRecord);

Two pipelines that differ only in their enrichment step share validateAndNormalize and applyBusinessRules without any coordination overhead — they're plain functions. validateOnly is useful for preview validation: check whether records will pass before committing to the async enrichment step.

Structured Error Reporting

ETL jobs need row-level context in their error reports:

const processAndReport = async (
  records: Array<{ row: number; data: unknown }>,
) => {
  const results = await Promise.all(
    records.map(async ({ row, data }) => ({
      row,
      result: await processTransaction(data),
    })),
  );

  const report = {
    total: results.length,
    succeeded: 0,
    failed: 0,
    errors: [] as Array<{ row: number; error: string }>,
  };

  for (const { row, result } of results) {
    match(result, {
      ok: () => {
        report.succeeded++;
      },
      err: (error) => {
        report.failed++;
        report.errors.push({ row, error });
      },
    });
  }

  return report;
};

const report = await processAndReport([
  {
    row: 1,
    data: {
      id: "tx-001",
      customerEmail: "alice@example.com",
      amount: "150",
      currency: "EUR",
      date: "2025-03-15",
    },
  },
  {
    row: 2,
    data: {
      id: "",
      customerEmail: "bad",
      amount: "-5",
      currency: "BTC",
      date: "nope",
    },
  },
  {
    row: 3,
    data: {
      id: "tx-003",
      customerEmail: "carol@example.com",
      amount: "75",
      currency: "USD",
      date: "2025-03-16",
    },
  },
]);

// { total: 3, succeeded: 2, failed: 1, errors: [{ row: 2, error: "id: String must not be empty; ..." }] }

Compared to try/catch

For reference, the same pipeline logic written imperatively:

const processTransactionImperative = async (raw: unknown) => {
  let transaction: Transaction;
  try {
    transaction = validateTransaction(raw); // throws on failure
  } catch (e) {
    console.error(`[pipeline error] Validation failed: ${e}`);
    return { success: false, error: `Validation failed: ${e}` };
  }

  const normalized = {
    ...transaction,
    amountUSD: +(
      transaction.amount * (USD_RATES[transaction.currency] ?? 1)
    ).toFixed(2),
    dateFormatted: transaction.date.toISOString().split("T")[0],
  };

  if (normalized.amountUSD < MINIMUM_AMOUNT_USD) {
    const error = `Transaction below minimum ($${MINIMUM_AMOUNT_USD})`;
    console.error(`[pipeline error] ${error}`);
    return { success: false, error };
  }

  let enriched;
  try {
    const res = await fetch(
      `/api/customers?email=${encodeURIComponent(normalized.customerEmail)}`,
    );
    if (!res.ok) throw new Error("Customer lookup failed");
    const customer = await res.json();
    enriched = {
      ...normalized,
      customerName: customer.name,
      tier: customer.tier,
    };
  } catch (e) {
    if (String(e).includes("Customer lookup failed")) {
      return {
        success: true,
        data: { partial: true, message: "Processed without customer data" },
      };
    }
    return { success: false, error: String(e) };
  }

  console.log(
    `Processed: ${enriched.id} — $${enriched.amountUSD} (${enriched.customerName})`,
  );
  return { success: true, data: enriched };
};

The pipeline version is shorter, but line count isn't the interesting difference. What matters structurally: error handling is interleaved with business logic at every step; recovery is buried inside a catch block rather than isolated in orElseWith; adding a step means adding another try/catch; and batch semantics (combine, combineAll, partition) don't exist — you write a custom accumulation loop for each pipeline.

The pipeline version is also easier to test: normalize and enrichWithCustomerData are standalone functions with clear Result contracts. Testing normalize means calling it with a Transaction. In the imperative version, testing the normalization step requires the validation step to succeed first.

Links:

@railway-ts/pipelines — Result, Option, pipe/flow, schema validation (0.2–3 kB per module, tree-shakable)

Full series: Railway-Oriented TypeScript — Overview · Part 1: The Glue Code Tax · Part 2: Composable Async Pipelines · Part 3: Schema-First React Forms · Setup & AI Tooling

Working With AI Tools on a New Library

Sarkis M — Fri, 20 Feb 2026 01:50:00 +0000

This is the setup guide for Railway-Oriented TypeScript. If you haven't read the overview yet, start there.

@railway-ts/pipelines and @railway-ts/use-form are new. That creates a practical problem: AI coding assistants — Claude Code, Cursor, GitHub Copilot — have been trained on millions of examples of Zod, react-hook-form, and neverthrow. They have almost no training data for @railway-ts.

The result is predictable. Ask Claude Code to build a form with @railway-ts/use-form installed and it will write zodResolver, useForm from react-hook-form, and setError/clearErrors — confidently, without being asked, because that's the pattern it's seen thousands of times. It's not hallucinating random code. It's pattern-matching against the highest-probability answer in its training distribution. The problem is that answer is wrong for your project.

This isn't a criticism of AI tools. It's a structural reality about how they work that's worth understanding and routing around.

Why Docs Shipped With the Package Matter

Both libraries now ship their documentation inside the npm package:

node_modules/@railway-ts/pipelines/docs/
node_modules/@railway-ts/use-form/docs/

This matters because modern AI coding tools — Claude Code in particular — can read your node_modules and reason from types and documentation in context. When you point the tool at the right docs, it stops pattern-matching against training data and starts reasoning from the actual library API. The generated code goes from "confidently wrong" to "reads the types and generates correct usage."

The difference in output quality is substantial. The bundled docs are the mechanism that makes AI-assisted development on a new library viable.

Setting Up a CLAUDE.md

The most reliable way to redirect an AI tool is a CLAUDE.md (or equivalent context file) in your project root. Claude Code reads this automatically. Create it before you start generating form or pipeline code:

# AI Coding Instructions

This project uses @railway-ts/pipelines and @railway-ts/use-form.

Before generating any form or pipeline code, read the docs shipped with the packages:

- node_modules/@railway-ts/pipelines/docs/
- node_modules/@railway-ts/use-form/docs/

Rules:

- Do NOT use Zod or @hookform/resolvers patterns
- Do NOT use react-hook-form's useForm, setError, or clearErrors
- Schema validation uses @railway-ts/pipelines/schema, not z.object()
- Form state uses useForm from @railway-ts/use-form, not react-hook-form
- Async pipelines use flowAsync/pipeAsync from @railway-ts/pipelines/composition

This does two things: tells the tool what not to do (which matters as much as what to do), and points it to the docs that contain the correct patterns.

For other AI tools:

Cursor — add the same content to .cursorrules or use the @Docs feature to index the bundled docs directly.

GitHub Copilot — less controllable without explicit doc indexing, but keeping a reference file open in your editor with correct usage examples significantly improves suggestion quality.

Verifying the Setup Works

After creating CLAUDE.md, ask your AI tool to build a simple form before touching any real code:

Build a React login form with email and password fields using @railway-ts/use-form. Handle server validation errors.

The output should use useForm from @railway-ts/use-form, a schema built with object/required/chain from @railway-ts/pipelines/schema, and form.setServerErrors() for server errors. If you see zodResolver, @hookform/resolvers, or setError/clearErrors, the tool is still pattern-matching against training data — check that CLAUDE.md is in the project root and that the docs are present in node_modules.

What the AI Gets Right Once Pointed at the Docs

Once the tool is reading from the bundled docs, the things it handles well:

Schema composition with chain, object, required, optional
fieldValidators for async field-level checks
form.setServerErrors() for server-side error injection
flowAsync/pipeAsync for composing multi-step async pipelines
mapWith, flatMapWith, filterWith, tapWith — the full curried operator set
combine, combineAll, partition for batch processing
Cross-field validation with refineAt

The things worth double-checking manually:

Type inference with InferSchemaType — verify the generated type matches your intent
initialValues completeness — the TypeScript error is immediate if a field is missing, but worth confirming
Error path strings in setServerErrors — confirm they match your schema field names

Quick Start

mkdir my-project && cd my-project
npm init -y
npm install react react-dom @types/react typescript
npm install @railway-ts/pipelines @railway-ts/use-form

Create CLAUDE.md as shown above, then verify the docs are present:

ls node_modules/@railway-ts/pipelines/docs/
ls node_modules/@railway-ts/use-form/docs/

If you're migrating an existing project that uses Zod:

npm install @railway-ts/use-form @railway-ts/pipelines
# keep zod — the form hook accepts Zod schemas via Standard Schema v1

You can adopt the form hook without touching your Zod schemas. See Part 3 for the migration path.

The Series

Part 1 — The Glue Code Tax
The Zod + react-hook-form seam counted line by line: the resolver, the async validation wiring, the server error conversion, the type assertions. Then the same form rewritten without any of them.

Part 2 — Composable Async Pipelines
The @railway-ts/pipelines API: Result, curried operators, and flowAsync for multi-step async pipelines where errors short-circuit automatically. The same Result type the form hook uses.

Part 3 — Schema-First React Forms
The 3-layer error priority system in detail, array fields, and the full-stack loop where one schema drives backend pipeline validation and frontend form state without any format conversion between them.

Bonus — Data Processing Pipelines
The pipeline library in an ETL context: batch processing with combine, combineAll, and partition, reusable sub-pipelines, structured error reporting. No React, no UI.

GitHub:

@railway-ts/pipelines — Result, Option, schema validation, composable pipelines
@railway-ts/use-form — React form hook with native schema integration

Schema-First React Forms: One Schema, Three Error Layers, Zero Glue

Sarkis M — Fri, 20 Feb 2026 01:45:00 +0000

This is Part 3 of Railway-Oriented TypeScript. Part 1 showed fieldValidators and setServerErrors eliminating the glue code. This part goes deeper into what the form hook actually does with those three error sources — and how one schema drives both the backend pipeline and the frontend form.

Every form has three sources of errors: the schema says "invalid email," an async check says "username taken," the server says "email already registered." In Part 1 you saw how fieldValidators and setServerErrors declare these without glue code. What wasn't shown is how the hook resolves them when multiple apply simultaneously.

The 3-Layer Error Priority System

In react-hook-form, all three error sources use setError() with different type strings. Priority is your responsibility — whichever you called last wins, or whichever you forgot to clearErrors. That's a deliberate design choice that gives you control. The tradeoff is that you have to exercise it correctly every time.

@railway-ts/use-form makes this deterministic:

Priority	Source	How it's set	When it clears
1 (lowest)	Schema validation	Automatic on change/blur/submit	On every validation run
2	Async field validators	`fieldValidators` option	When the field validator re-runs
3 (highest)	Server errors	`form.setServerErrors(...)`	When the user edits the affected field

Higher priority wins. A server error stays visible even when schema validation passes — the server is the authority. An async "username taken" overrides a schema-level "too short" — the live check is more specific. Editing a field clears the server error and lets schema validation take over again.

You never manage this in component code. You read form.errors.email and display it.

<input type="email" {...form.getFieldProps("email")} />;
{
  form.touched.email && form.errors.email && <span>{form.errors.email}</span>;
}
{
  /* Could be schema error, async field error, or server error.
    Always shows the highest-priority one. */
}

Installation

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

The Schema Is the Form

The schema drives both the frontend form and the backend pipeline — covered in the full-stack section below. Define it once, export it from a shared file:

// schema.ts
import {
  object,
  required,
  optional,
  chain,
  string,
  nonEmpty,
  email,
  minLength,
  parseNumber,
  min,
  max,
  array,
  stringEnum,
  refineAt,
  type InferSchemaType,
} from "@railway-ts/pipelines/schema";

export const registrationSchema = chain(
  object({
    username: required(
      chain(string(), nonEmpty("Username is required"), minLength(3)),
    ),
    email: required(chain(string(), nonEmpty("Email is required"), email())),
    password: required(
      chain(string(), nonEmpty("Password is required"), minLength(8)),
    ),
    confirmPassword: required(
      chain(string(), nonEmpty("Please confirm your password")),
    ),
    age: required(
      chain(parseNumber(), min(18, "Must be at least 18"), max(120)),
    ),
    contacts: optional(array(stringEnum(["email", "phone", "sms"]))),
  }),
  refineAt(
    "confirmPassword",
    (d) => d.password === d.confirmPassword,
    "Passwords must match",
  ),
);

export type Registration = InferSchemaType<typeof registrationSchema>;

The schema goes directly into useForm — no resolver, no adapter:

import { useForm } from "@railway-ts/use-form";
import { registrationSchema, type Registration } from "./schema";

const form = useForm<Registration>(registrationSchema, {
  initialValues: {
    username: "",
    email: "",
    password: "",
    confirmPassword: "",
    age: 0,
    contacts: [],
  },
  fieldValidators: {
    username: async (value) => {
      const { available } = await fetch(
        `/api/check-username?u=${encodeURIComponent(value)}`,
      ).then((r) => r.json());
      return available ? undefined : "Username is already taken";
    },
  },
  onSubmit: async (values) => {
    const res = await fetch("/api/register", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(values),
    });
    if (!res.ok) form.setServerErrors(await res.json());
    else navigate("/welcome");
  },
});

Types propagate from the schema into initialValues, errors, touched, and getFieldProps — form.getFieldProps("usernam") is a TypeScript error. The fieldValidators key is typed to only accept valid field names from Registration.

Form-Level Errors

setServerErrors handles field-level errors. For errors not tied to a specific field — network failures, rate limiting — use ROOT_ERROR_KEY:

import { ROOT_ERROR_KEY } from "@railway-ts/pipelines/schema";

form.setServerErrors({
  [ROOT_ERROR_KEY]: "Network error. Please try again.",
});

{
  form.errors[ROOT_ERROR_KEY] && (
    <div className="form-error">{form.errors[ROOT_ERROR_KEY]}</div>
  );
}

ROOT_ERROR_KEY is the string "_root" — a reserved key for form-level errors, exported as a constant so you're not scattering string literals through component code.

Array Fields

Two patterns depending on the use case.

Checkbox groups — a static set of options mapped to an array field:

{
  ["email", "phone", "sms"].map((option) => (
    <label key={option}>
      <input
        type="checkbox"
        {...form.getCheckboxGroupOptionProps("contacts", option)}
      />
      {option}
    </label>
  ));
}

Dynamic lists — add/remove items at runtime:

const { push, remove, insert, swap, replace } = form.arrayHelpers("todos");

All operations are type-safe. Error paths are automatic — if todos[2].text fails validation, form.errors['todos.2.text'] has the message. You don't construct error path strings manually.

Backend: Same Schema, Full Loop

This is the payoff. The same registrationSchema that drives the frontend form validates the backend request — and the error format that comes out of the pipeline is the exact format setServerErrors expects in.

// server.ts
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 "./schema"; // same file

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) }),
  });
};

app.post("/api/register", async (req, res) => {
  const { status, body } = await handleRegistration(req.body);
  res.status(status).json(body);
});

Follow the data: validate(body, registrationSchema) 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>:

// ValidationError[] from validate() or checkEmailUnique
[{ path: ["email"], message: "Email already registered" }];

// formatErrors() →
{
  email: "Email already registered";
}

That's the exact shape form.setServerErrors() expects. The frontend calls form.setServerErrors(await res.json()) and the error appears on the email field. No conversion, no field name mapping, no adapter. Same format out of the backend, same format into the form hook — because they share the schema.

Already Using Zod?

The form hook accepts Zod and Valibot schemas directly via Standard Schema v1 auto-detection — no resolver, no adapter package:

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

const zodSchema = z.object({
  username: z.string().min(3, "Username must be at least 3 characters"),
  email: z.email("Invalid email address"),
  password: z.string().min(8, "Password must be at least 8 characters"),
  age: z.coerce.number().min(18, "Must be at least 18"),
});

type ZodUser = z.infer<typeof zodSchema>;

const form = useForm<ZodUser>(zodSchema, {
  initialValues: { username: "", email: "", password: "", age: 0 },
  onSubmit: (values) => console.log(values),
});

No zodResolver. No @hookform/resolvers. You keep the full hook API — getFieldProps, touched, setServerErrors, fieldValidators, arrayHelpers, and the 3-layer error system. The Standard Schema path means you can adopt the form hook now with your existing Zod schemas, and migrate to @railway-ts/pipelines/schema later when the shared backend/frontend schema is what you want.

Trade-offs

Re-renders

@railway-ts/use-form uses controlled inputs — every keystroke updates React state and triggers a re-render of the component. react-hook-form uses uncontrolled inputs backed by refs, updating the DOM directly without React involvement.

For most forms — login, signup, settings, CRUD with under ~30 fields — the performance difference is unmeasurable. Both feel instant.

For forms with 50+ fields, live-preview editors where every character re-renders a complex output, or performance-sensitive mobile contexts, react-hook-form's uncontrolled approach is measurably faster. If you're building a form where keystroke latency matters at scale, that's a real advantage worth keeping.

We chose controlled inputs because they're simpler to reason about — state is always in React, there's no ref/state divergence to debug, and the entire form state is inspectable at any point. For the 95% of forms where performance isn't a constraint, that tradeoff favors correctness and debuggability.

Ecosystem

react-hook-form has a DevTools extension, a plugin ecosystem, and years of edge cases documented in GitHub issues. @railway-ts/use-form doesn't have that history yet. For teams that encounter unusual component integrations regularly, community depth is a genuine advantage.

Feature comparison

	RHF + Zod	@railway-ts
Bundle size	~35.5 kB gzip†	~10 kB gzip††
npm packages	3	2
Adapter packages	1 (`@hookform/resolvers`)	0
Error priority	Manual `setError` ordering	Automatic 3-layer system
Async field validation	Manual	Built-in `fieldValidators`
Cross-field validation	`.refine()`	`refineAt()`
Standard Schema	Via resolver	Native
`handleSubmit` returns	`void`	`Promise<Result<T, E[]>>`
Re-render strategy	Uncontrolled	Controlled
DevTools	Yes	No
Community size	Large	Small

† Sizes from bundlephobia (gzip). †† @railway-ts sizes from size-limit; ~7.8 kB brotli. If your project already ships Zod, the marginal cost of RHF + resolvers is ~22.5 kB. The @railway-ts total includes both the form hook and the full pipeline/validation library — if you're using that on the backend anyway, the form hook adds ~4.8 kB gzip.

Putting It Together

The complete registration form — schema validation, cross-field rules, async username check, server errors, checkbox groups, loading states — is in the StackBlitz demo. Try the form hook directly — schema validation, async checks, and error priority in one runnable example.

GitHub:

@railway-ts/pipelines — Schema, Result types, pipelines
@railway-ts/use-form — React form hook

Next: Bonus — Data Processing Pipelines — the same pipeline library in an ETL context. Batch processing with combine, combineAll, and partition; reusable sub-pipelines; structured error reporting. No React, no UI.

Composable Async Pipelines in TypeScript: One Result Type, Zero Adapters

Sarkis M — Fri, 20 Feb 2026 01:40:00 +0000

This is Part 2 of Railway-Oriented TypeScript. Part 1 counted the glue code tax in forms. The same pattern appears on the backend — and this is where @railway-ts/pipelines lives.

If you've ever used Zod on the backend, you know this code. It's in every route that validates input — the bridge between Zod's SafeParseReturnType and whatever Result type your pipeline expects:

// Zod returns SafeParseReturnType. Your pipeline expects Result.
const parsed = orderSchema.safeParse(body);
if (!parsed.success) {
  return err({
    type: "validation" as const,
    issues: parsed.error.issues.map((i) => ({
      path: i.path.map(String),
      message: i.message,
    })),
  });
}
// Now you can use parsed.data

Every pipeline that starts with Zod validation has this bridge. You write it once, extract it into a utility, and move on — but the seam is structural. Your validation layer and your error-handling layer speak different languages.

What if validation just returned Result natively?

import {
  validate,
  object,
  required,
  chain,
  string,
  email,
  minLength,
} from "@railway-ts/pipelines/schema";
import { match } from "@railway-ts/pipelines/result";

const userSchema = object({
  email: required(chain(string(), email())),
  password: required(chain(string(), minLength(8))),
});

const result = validate(input, userSchema);
// Result<{ email: string; password: string }, ValidationError[]>
// No conversion. Same Result your pipeline steps consume.

That's the premise of @railway-ts/pipelines. This part covers how it works.

Curried Helpers: The Design That Enables Composition

Method chaining (neverthrow's .andThen().map()) works, but it ties operations to Result instances and can't produce reusable, deferred pipelines. This library uses curried operators instead — functions that return functions:

// Without curried helpers — lambda noise at every step
const result = pipe(
  ok(5),
  (r) => map(r, (x) => x * 2),
  (r) => flatMap(r, (x) => divide(x, 3)),
);

// With curried helpers — point-free
const result = pipe(
  ok(5),
  mapWith((x) => x * 2),
  flatMapWith((x) => divide(x, 3)),
);

Every Result operator has a curried counterpart: mapWith, flatMapWith, filterWith, tapWith, orElseWith, mapErrWith, tapErrWith. These are what make pipe and flow composition clean.

pipe executes immediately. flow returns a reusable function. pipeAsync and flowAsync do the same for async operations, awaiting each step and mixing sync and async freely.

A Minimal Pipeline

Before the full operator set, here's the basic shape — validate, transform, branch:

import { flowAsync } from "@railway-ts/pipelines/composition";
import { mapWith, match } from "@railway-ts/pipelines/result";
import {
  validate,
  object,
  required,
  chain,
  string,
  email,
  parseNumber,
  min,
} from "@railway-ts/pipelines/schema";

const contactSchema = object({
  email: required(chain(string(), email())),
  age: required(chain(parseNumber(), min(18))),
});

const processContact = flowAsync(
  (input: unknown) => validate(input, contactSchema),
  mapWith(({ email, age }) => ({
    email,
    ageGroup: age < 30 ? "young" : age < 60 ? "middle" : "senior",
    isEligibleForDiscount: age >= 65,
  })),
  (result) =>
    match(result, {
      ok: (data) => ({ success: true as const, data }),
      err: (errors) => ({ success: false as const, errors }),
    }),
);

await processContact({ email: "alice@example.com", age: "25" });
// → { success: true, data: { email: "alice@example.com", ageGroup: "young", isEligibleForDiscount: false } }

await processContact({ email: "not-an-email", age: "-5" });
// → { success: false, errors: [...] }

Three steps. If validation fails, mapWith never runs. The match branches once, at the boundary. Adding a step means inserting one line.

Note parseNumber() above — it converts the string "25" to the number 25. Useful when data arrives from forms or CSVs where everything is a string. chain() composes validators left to right, and all errors accumulate — you see every problem at once.

The Full Operator Set

The minimal pipeline above covered the core shape: validate, transform, branch. Now let's add what a real pipeline needs — business rules with filterWith, async steps with flatMapWith, side effects with tapWith/tapErrWith, and error recovery with orElseWith.

Here's a complete order processing pipeline using every operator:

import { flowAsync } from "@railway-ts/pipelines/composition";
import {
  err,
  ok,
  filterWith,
  flatMapWith,
  mapErrWith,
  mapWith,
  match,
  orElseWith,
  tapErrWith,
  tapWith,
} from "@railway-ts/pipelines/result";
import {
  validate,
  object,
  required,
  chain,
  string,
  nonEmpty,
  email,
  parseNumber,
  min,
  max,
  formatErrors,
  type InferSchemaType,
  type ValidationError,
} from "@railway-ts/pipelines/schema";

const orderSchema = object({
  customerEmail: required(chain(string(), nonEmpty(), email())),
  item: required(chain(string(), nonEmpty())),
  quantity: required(chain(parseNumber(), min(1), max(100))),
  unitPrice: required(chain(parseNumber(), min(0.01))),
});

type Order = InferSchemaType<typeof orderSchema>;

const TAX_RATE = 0.08;
const MINIMUM_ORDER_TOTAL = 10;

const processOrder = flowAsync(
  (input: unknown) => validate(input, orderSchema),

  // Convert ValidationError[] to a human-readable string
  mapErrWith((errors: ValidationError[]) =>
    Object.entries(formatErrors(errors))
      .map(([field, msg]) => `${field}: ${msg}`)
      .join("; "),
  ),

  // Side effect on success — doesn't alter the Result
  tapWith((order: Order) =>
    console.log(`Validated: ${order.quantity}x ${order.item}`),
  ),

  // Business rule: if predicate fails, Ok becomes Err with given message
  filterWith(
    (order: Order) => order.quantity * order.unitPrice >= MINIMUM_ORDER_TOTAL,
    `Order total must be at least $${MINIMUM_ORDER_TOTAL}`,
  ),

  // Async step that can independently fail
  flatMapWith((order: Order) => checkInventory(order)),

  // Transform Ok without the ability to fail
  mapWith((order: Order) => {
    const total = order.quantity * order.unitPrice;
    return {
      ...order,
      total,
      totalWithTax: +(total * (1 + TAX_RATE)).toFixed(2),
    };
  }),

  // Side effect on error — doesn't alter the Result
  tapErrWith((error: string) => console.error("[order error]", error)),

  // Error recovery: return a new Ok, or re-raise
  orElseWith((error: string) => {
    if (error === "Item is out of stock") {
      return ok({
        backordered: true,
        message: "Item on back-order. You will be notified.",
      });
    }
    return err(error);
  }),

  // Branch once at the boundary
  (result) =>
    match(result, {
      ok: (data) => ({ success: true as const, data }),
      err: (error) => ({ success: false as const, error }),
    }),
);

await processOrder({
  customerEmail: "alice@example.com",
  item: "widget",
  quantity: "3",
  unitPrice: "12.50",
});
// → { success: true, data: { ..., total: 37.5, totalWithTax: 40.5 } }

await processOrder({
  customerEmail: "not-an-email",
  item: "",
  quantity: "-5",
  unitPrice: "10",
});
// → { success: false, error: "customerEmail: Invalid email format; item: String must not be empty; quantity: Must be at least 1" }

await processOrder({
  customerEmail: "carol@example.com",
  item: "out-of-stock-widget",
  quantity: "5",
  unitPrice: "20",
});
// → { success: true, data: { backordered: true, message: "Item on back-order..." } }

The pipeline reads top-to-bottom. The happy path and error path never intersect until match. Each step is a plain function you can test in isolation.

Typed Errors: When E Is a Discriminated Union

The examples above use string errors for readability. The real power of Result<T, E> shows when E is a discriminated union:

type OrderError =
  | { type: "validation"; fields: Record<string, string> }
  | { type: "inventory"; item: string }
  | { type: "payment"; code: string; retryable: boolean }
  | { type: "shipment"; reason: string };

const checkInventory = (order: Order): Result<Order, OrderError> =>
  order.item === "out-of-stock-widget"
    ? err({ type: "inventory", item: order.item })
    : ok(order);

const chargePayment = (order: Order): Result<Order, OrderError> =>
  order.quantity * order.unitPrice > 10_000
    ? err({ type: "payment", code: "LIMIT_EXCEEDED", retryable: false })
    : ok(order);

Your error handling at the boundary pattern-matches on .type:

match(result, {
  ok: (data) => respond(200, data),
  err: (error) => {
    switch (error.type) {
      case "validation":
        return respond(400, error.fields);
      case "inventory":
        return respond(409, `${error.item} unavailable`);
      case "payment":
        return respond(402, { code: error.code, retryable: error.retryable });
      case "shipment":
        return respond(500, error.reason);
    }
  },
});

TypeScript narrows the error type at each branch. No instanceof, no hand-written type guards — just data.

Honest Comparison With Alternatives

Use neverthrow if you only need Result wrapping and you're already using Zod for validation. neverthrow gives you .andThen().map() method chaining on a Result type — a different shape from the curried flatMapWith/mapWith functions here, but equally expressive for linear chains. The real gap: neverthrow doesn't include validation, so you still pair it with Zod. That means Zod returns a plain object or throws, and neverthrow returns Result<T, E> — two error models your glue code bridges. Manageable for most apps, and neverthrow has a mature community.

Use fp-ts if your team thinks in Haskell abstractions and wants the full toolkit. Concretely: TaskEither for typed-error async, Reader for dependency injection, IO for effect tracking — tools railway-ts doesn't offer. The cost: fp-ts adds ~15–50 kB depending on imports, and the API uses category-theory naming (Alt, Bifunctor, Monad) that steepens onboarding. If your team is comfortable with that vocabulary, nothing in the TypeScript ecosystem is more comprehensive.

Use Effect if you're ready to adopt Effect as your application framework. Effect isn't a utility library — it ships its own runtime, a dependency-injection system (Layer/Context), structured concurrency, and a typed error channel. Exceptional when you're fully in it; significant overhead if you just want Result<T, E> and composable pipelines without re-architecting your app.

Use @railway-ts/pipelines if you want one library where validation and error handling share a type, and async pipelines compose naturally. It targets a narrower niche than fp-ts or Effect — Result + pipelines + validation — without requiring a new runtime or category-theory vocabulary. Particularly strong paired with @railway-ts/use-form — the same Result the pipeline produces is what the form hook consumes natively. That's Part 3.

Trade-offs: smaller ecosystem means less community coverage at 2am. Newer means less production history. The unified model couples validation and error handling — if you want to swap your validation library independently, separate packages give you that flexibility.

Links:

@railway-ts/pipelines — Result, Option, pipe/flow, schema validation (0.2–3 kB per module, tree-shakable)
@railway-ts/use-form — React form hook with native schema integration

Next: Part 3 — Schema-First React Forms — the 3-layer error priority system that makes server errors, async field checks, and schema errors deterministic; array fields; and the full-stack payoff where one schema drives backend pipeline and frontend form state without any format conversion.

The Glue Code Tax: A Line-by-Line Audit of Zod + react-hook-form

Sarkis M — Fri, 20 Feb 2026 01:35:00 +0000

This is Part 1 of Railway-Oriented TypeScript. The overview established the problem: library seams produce glue code that costs you every time you touch it. Here we count it.

Zod and react-hook-form are both good at what they do. The problem isn't in either library — it's in the space between them.

Here's a registration form. Nothing exotic — username, email, password with confirmation, async username check, server-side errors. The kind of form every SaaS app has. Let's count the glue.

Want to see the difference? Try the full-stack demo in StackBlitz — the same registration form with a shared Express backend.

The Resolver — Bridging Zod to react-hook-form

import { zodResolver } from "@hookform/resolvers/zod";

const registrationSchema = z
  .object({
    username: z.string().min(3),
    email: z.email(),
    password: z.string().min(8),
    confirmPassword: z.string(),
  })
  .refine((data) => data.password === data.confirmPassword, {
    message: "Passwords must match",
    path: ["confirmPassword"],
  });

type RegistrationForm = z.infer<typeof registrationSchema>;

const {
  register,
  handleSubmit,
  setError,
  clearErrors,
  formState: { errors, isSubmitting },
} = useForm<RegistrationForm>({
  resolver: zodResolver(registrationSchema),
  defaultValues: { username: "", email: "", password: "", confirmPassword: "" },
});

That zodResolver call is one line — but it pulls in @hookform/resolvers (~8.5 kB), a package whose only job is converting Zod's SafeParseReturnType into react-hook-form's FieldErrors format. It works. It's also a bridge layer you ship, and when either library changes its error shape, this is the thing that breaks first.

Async Validation — The Real Pain

Now you need to check if a username is available. Zod's .refine() can be async, but react-hook-form's resolver doesn't handle async Zod validation reliably. Most teams move the check out of the schema:

const validateUsername = async (username: string) => {
  if (username.length < 3) return;

  try {
    const res = await fetch(
      `/api/check-username?u=${encodeURIComponent(username)}`,
    );
    const { available } = await res.json();
    if (!available) {
      setError("username", {
        type: "validate",
        message: "Username is already taken",
      });
    } else {
      clearErrors("username");
    }
  } catch {
    setError("username", {
      type: "validate",
      message: "Unable to check availability",
    });
  }
};

The fetch and try/catch are real work — you'd write those regardless. The glue is the setError / clearErrors dance: the { type: "validate", message } shape, the imperative calls at exactly the right moments. This exists purely to inject your async check into react-hook-form's error model.

Notice what's missing: no loading state, no race condition handling. If the user types faster than the API responds, the last response to arrive wins regardless of which was sent last. That's a bug you'll introduce and debug yourself. Glue lines: ~8

Server Errors — Another Format Conversion

The server returns { email: "Email already exists" }. react-hook-form expects setError("email", { type: "server", message: "Email already exists" }):

const onSubmit = async (values: RegistrationForm) => {
  try {
    const res = await fetch("/api/register", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(values),
    });

    if (!res.ok) {
      const serverErrors = await res.json();
      Object.entries(serverErrors).forEach(([field, message]) => {
        setError(field as keyof RegistrationForm, {
          type: "server",
          message: message as string,
        });
      });
      return;
    }

    navigate("/welcome");
  } catch {
    setError("root", {
      type: "server",
      message: "Network error. Please try again.",
    });
  }
};

That Object.entries(...).forEach(...) loop is pure glue. The as keyof RegistrationForm cast is a type hole — the compiler cannot verify that the server's field names match the form's. The type: "server" string is a convention you have to know and remember. Glue lines: ~6

The Real Costs

These aren't just extra lines.

They're untested. Nobody writes tests for format conversion code. It's too short, too obviously correct. Until it isn't — and then you're debugging a runtime error in code with no test coverage.

They're cast-heavy. Every as keyof RegistrationForm and message as string is a place where a library upgrade can introduce a runtime error TypeScript won't catch. Casts are promises to the compiler you're making on behalf of runtime behavior you can't verify statically.

They break on upgrades. When either library bumps a major version, the glue between them needs re-auditing. The libraries have upgrade guides. The glue doesn't.

They fragment validation logic. Part of your validation lives in the Zod schema. Part lives in the async validator. Part lives in the server error handler. There is no single place to look to understand what makes this form valid. That question now has three answers.

The Same Form, No Glue

Same features — schema validation, cross-field validation, async username check, server errors. One Result type flowing from validation through form state.

Schema + hook

import { useForm } from "@railway-ts/use-form";
import {
  chain,
  object,
  required,
  string,
  nonEmpty,
  email,
  minLength,
  refineAt,
  ROOT_ERROR_KEY,
  type InferSchemaType,
} from "@railway-ts/pipelines/schema";

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

type Registration = InferSchemaType<typeof schema>;

const form = useForm<Registration>(schema, {
  initialValues: { username: "", email: "", password: "", confirmPassword: "" },
  fieldValidators: {
    username: async (value) => {
      const { available } = await fetch(
        `/api/check-username?u=${encodeURIComponent(value)}`,
      ).then((r) => r.json());
      return available ? undefined : "Username is already taken";
    },
  },
  onSubmit: async (values) => {
    const res = await fetch("/api/register", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(values),
    });
    if (!res.ok) form.setServerErrors(await res.json());
    else navigate("/welcome");
  },
});

refineAt places the cross-field error on the confirmPassword field path as part of the schema — no separate .refine() callback with a { path: [...] } object. fieldValidators declares async checks declaratively — the hook manages loading state (form.validatingFields.username), discards stale responses, and gates the validator behind schema validation for that field. setServerErrors takes the server's { fieldName: "message" } format directly.

JSX

<form onSubmit={(e) => void form.handleSubmit(e)}>
  <input {...form.getFieldProps("username")} />
  {form.validatingFields.username && <span>Checking...</span>}
  {form.touched.username && form.errors.username && (
    <span>{form.errors.username}</span>
  )}

  <input type="email" {...form.getFieldProps("email")} />
  {form.touched.email && form.errors.email && <span>{form.errors.email}</span>}

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

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

  {form.errors[ROOT_ERROR_KEY] && <div>{form.errors[ROOT_ERROR_KEY]}</div>}

  <button type="submit" disabled={form.isSubmitting || form.isValidating}>
    {form.isSubmitting ? "Registering..." : "Create Account"}
  </button>
</form>

No format conversions. No type assertions. No setError / clearErrors. Types flow from the schema through the hook into JSX without a single as cast — form.getFieldProps("usernam") is a TypeScript error.

The numbers

	Zod + RHF + resolvers	@railway-ts
npm packages	3	2
Format conversion lines	~25	0
Type assertions (`as`)	4+	0
Files with validation logic	3–4	1
Places errors are shaped	3 (resolver, async validator, server error handler)	1 (schema)

Bundle Size

Library	Size (gzip)	What you get
@railway-ts/pipelines	~5.5 kB	Result, Option, pipe/flow, schema validation
@railway-ts/use-form	~4.8 kB	React form hook
@railway-ts total	~10.3 kB	Full stack
Zod	~13 kB	Schema validation only
react-hook-form	~14 kB	Form state only
@hookform/resolvers	~8.5 kB	Adapter layer only
Zod + RHF total	~35.5 kB	Validation + form + adapter

@railway-ts sizes measured with size-limit (both gzip and brotli). Zod/RHF sizes from bundlephobia (gzip only). The gzip-to-gzip comparison: ~10.3 kB vs ~35.5 kB. Brotli is typically ~20% smaller than gzip; the brotli column is provided for projects that serve brotli-compressed assets.

The honest comparison depends on your starting point. If your codebase already uses Zod for API validation, the marginal cost of adding react-hook-form is ~22.5 kB (RHF + resolvers), not ~35.5 kB. The @railway-ts total includes both the form hook and the full pipeline/validation library. The size argument is sharpest for greenfield projects.

Tradeoffs

Coupling. Adopting this ties your validation and form state to one library ecosystem. Less than you might think — the form hook supports Standard Schema v1, so you can pass a Zod or Valibot schema directly to useForm without any resolver. The coupling is in schema definitions, not in component code.

Ecosystem size. Zod has years of community validators, blog posts, and Stack Overflow answers. react-hook-form has a DevTools extension and a rich plugin ecosystem. If you hit a weird edge case with a third-party date picker at 11pm, RHF probably has a GitHub issue about it. @railway-ts probably doesn't yet.

Migration cost. If your team has 20+ existing react-hook-form forms, this is a rewrite, not a drop-in replacement. The API surface is different — controlled vs. uncontrolled inputs, declarative field validators vs. imperative setError, a different hook return shape. Standard Schema support means you can adopt the form hook on new forms while keeping existing RHF forms untouched — a gradual migration where you never rewrite a working form unless you choose to. But don't underestimate the cost of maintaining two form systems in parallel during the transition.

Battle-testing. Zod and react-hook-form are used in thousands of production apps. @railway-ts is newer with a smaller production footprint. For risk-averse teams, proven stability matters more than API elegance.

The glue code tax isn't an argument against modular design. It's an argument that this particular seam — between Zod's error model and react-hook-form's — extracts more overhead than it returns in flexibility, for most forms, most of the time.

Links:

@railway-ts/pipelines — Result types, schema validation, composable pipelines
@railway-ts/use-form — React form hook with native schema integration

Next: Part 2 — Composable Async Pipelines — the same seam appears on the backend whenever Zod meets a Result type. Part 2 covers the @railway-ts/pipelines API: how Result, curried operators, and flowAsync eliminate it.

I Stopped Context-Switching Between Validation, Forms, and Pipelines

Sarkis M — Fri, 20 Feb 2026 01:30:00 +0000

There's a moment every TypeScript developer knows. You're staring at a form bug — a server error that should be showing on the email field isn't appearing. You open the component. Then the submit handler. Then the server. Then the resolver. You're tracing through three separate error-shaping layers and you can't quite hold the whole thing in your head at once.

It's not that the code is wrong. It's that understanding it requires knowing four things simultaneously: how Zod formats errors, how the resolver converts them, how setError structures them, and how the server formats its response. Four mental models for one question: what makes this form invalid?

I've been in that moment a lot. It made me wonder whether the complexity was intrinsic to the problem, or just an artifact of the tools.

Want to skip the pitch? Try it live in StackBlitz — a runnable app with schema validation, async checks, server errors, and a shared Express backend.

What We've Accepted as Normal

Here's the standard stack: Zod for validation, react-hook-form for form state, @hookform/resolvers to bridge them, plus your own async validator wiring and your own server error converter. Three npm packages, a resolver adapter, and custom glue code for anything outside the happy path.

It works. That's not the point. The point is what you're carrying in your head whenever you touch it.

Every field has errors potentially living in three different places: the Zod result, the setError calls from async validation, the setError calls from server errors. The rule for which one displays is: whatever you called last. Which means you have to track call order in your head, or you'll show a stale server error after the user has already fixed their input.

Adding a new field means touching the schema, the useForm defaults, the JSX, and potentially the async validator and server error handler depending on what the field does. These aren't in one place. They're coordinated across the file.

None of this is a knock on Zod or react-hook-form. Both are excellent at what they do. But "excellent at what they do" is exactly the problem — they do different things, and you write the code that connects them.

The Same Seam on the Backend

Zod's safeParse returns SafeParseReturnType. Your pipeline expects Result. Every route that validates input starts with a conversion:

const parsed = schema.safeParse(body);
if (!parsed.success) {
  return err({
    type: "validation",
    issues: parsed.error.issues.map((i) => ({
      path: i.path.map(String),
      message: i.message,
    })),
  });
}
// now you can use parsed.data

You write this once, extract it into a utility, and forget about it. Until the next person writes it again because they didn't know the utility existed. Or until Zod changes its error shape. Or until someone else's async step returns a different error format and now you have two error models in the same pipeline.

The seam on the backend is structurally identical to the one on the frontend: validation output doesn't naturally match error-handling input, so you write code to bridge them.

What a Unified Stack Actually Feels Like

Here's the concrete experience of adding a field. Say you have a registration form and you need to add age: must be a number, must be at least 18.

In the Zod + RHF stack, you touch:

The Zod schema — add the field
The useForm defaultValues — add the field
The JSX — add the input and error display
If age needs async or server validation — add setError/clearErrors wiring

Three of those four are pure coordination. The Zod schema is the work. The rest is keeping other layers informed.

With @railway-ts/use-form and @railway-ts/pipelines:

// schema.ts — shared between frontend and backend
const registrationSchema = object({
  username: required(chain(string(), nonEmpty(), minLength(3))),
  email: required(chain(string(), nonEmpty(), email())),
  password: required(chain(string(), nonEmpty(), minLength(8))),
  confirmPassword: required(chain(string(), nonEmpty())),
  age: required(chain(parseNumber(), min(18, "Must be at least 18"), max(120))),
});

If the schema syntax is unfamiliar — chain, required, object — Part 1 walks through each piece. The short version: chain() composes validators left-to-right, required() marks a field as non-optional, and object() collects fields into a typed shape.

Add age to the schema. InferSchemaType propagates it to the TypeScript type. initialValues gives you a TypeScript error immediately — age is missing. form.getFieldProps("age") works without any other changes. form.errors.age works. If the server returns { age: "Age cannot be verified" }, form.setServerErrors(res.json()) handles it — no field name mapping, no as keyof FormType cast.

The JSX is still the JSX — you write the input. But nothing else changes. The schema change propagated everywhere else automatically.

That's the difference. Not fewer files. Not less JSX. Less coordination. Less working memory spent keeping layers in sync.

This assumes you want identical validation on frontend and backend — which is true for most forms. When you intentionally need them to differ (admin bypasses, progressive disclosure, different error messages for API consumers vs. UI), you'd define separate schemas. The library doesn't force sharing; it makes sharing free when you want it.

The Error Priority Problem, Solved

The context-switching that happens when a field has multiple simultaneous error sources — schema says invalid, async check says taken, server says already registered — is one of the subtlest bugs to track in a React form.

@railway-ts/use-form makes this deterministic with a fixed priority system:

Priority	Source	Clears when
1 (lowest)	Schema validation	Every validation run
2	Async field validators	Field validator re-runs
3 (highest)	Server errors	User edits the field

You never manage this. You read form.errors.email and display it. A server error stays visible even after schema validation passes — the server is more authoritative than client-side rules. Editing the field clears the server error and hands control back to schema validation.

<input type="email" {...form.getFieldProps("email")} />;
{
  form.touched.email && form.errors.email && <span>{form.errors.email}</span>;
}
{
  /* Could be schema, async, or server error. Always the highest-priority one. */
}

Async validation is declared, not wired:

const form = useForm<Registration>(registrationSchema, {
  fieldValidators: {
    username: async (value) => {
      const { available } = await fetch(
        `/api/check-username?u=${encodeURIComponent(value)}`,
      ).then((r) => r.json());
      return available ? undefined : "Username is already taken";
    },
  },
  onSubmit: async (values) => {
    const res = await fetch("/api/register", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(values),
    });
    if (!res.ok) form.setServerErrors(await res.json());
    else navigate("/welcome");
  },
});

The hook handles loading state (form.validatingFields.username), discards stale responses — the last issued request wins, not the last received — and gates the async check behind schema validation so you're not hitting the API with values that are already invalid. None of that is wiring you write.

You Also Get a Pipeline Library

This is where it goes past "better forms." The same Result type the form hook uses natively is what @railway-ts/pipelines produces on the backend — in API handlers, in ETL jobs, in any async operation that can fail.

import { flowAsync } from "@railway-ts/pipelines/composition";
import { flatMapWith, match } from "@railway-ts/pipelines/result";
import { validate, formatErrors } from "@railway-ts/pipelines/schema";
import { registrationSchema } from "./schema"; // same file the form uses

const handleRegistration = flowAsync(
  (body: unknown) => validate(body, registrationSchema),
  flatMapWith(checkEmailUnique),
  flatMapWith(createUser),
);

app.post("/api/register", async (req, res) => {
  const result = await handleRegistration(req.body);
  match(result, {
    ok: (user) => res.status(201).json({ id: user.id }),
    err: (errors) => res.status(422).json(formatErrors(errors)),
  });
});

formatErrors converts ValidationError[] to Record<string, string>. That's the exact format form.setServerErrors() consumes. The full loop — frontend schema validation, async field checks, backend pipeline validation, server errors surfacing on the right fields — shares one schema and one error format with zero conversion between layers.

For batch processing, you get combine, combineAll, and partition — semantics that would each be a custom accumulation loop with try/catch:

const results = await Promise.all(rawRecords.map(processTransaction));

// All-or-nothing, first failure
const batchResult = combine(results);

// All-or-nothing, all failures at once
const batchResult = combineAll(results);

// Keep both sides — the ETL default
const { successes, failures } = partition(results);

One call each, on results you already have.

What You're Not Giving Up

If you already have Zod schemas, @railway-ts/use-form accepts them directly via Standard Schema v1 — no resolver, no adapter:

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

const zodSchema = z.object({
  username: z.string().min(3),
  email: z.email(),
  password: z.string().min(8),
  age: z.coerce.number().min(18),
});

const form = useForm<z.infer<typeof zodSchema>>(zodSchema, {
  initialValues: { username: "", email: "", password: "", age: 0 },
  onSubmit: (values) => console.log(values),
});

Full hook API. No zodResolver. No @hookform/resolvers. The migration path is: adopt the form hook now with existing Zod schemas, migrate to @railway-ts/pipelines/schema later when you want the shared full-stack loop.

The Actual Pitch

I'm not selling you on monads or railway-oriented design as a philosophy. Those are interesting, but they're not the point.

The point is: right now, your validation layer, your form state layer, and your async pipeline layer are three separate mental models you context-switch between every time you open a related file. The error shapes don't naturally align. The libraries weren't designed to share a type vocabulary. That's not a flaw in any of them — it's what happens when you compose independently excellent tools.

There's a version of this where it's one model. Schema drives types drives form state drives server communication drives pipeline validation — the same Result, the same error format, no adapters between layers.

The bundle is ~7.8 kB brotli (~10 kB gzip) for both libraries combined. For comparison, Zod + react-hook-form + resolvers is ~35.5 kB gzip. Different compression methods — but even on the same scale, the unified stack is meaningfully smaller.

What you're getting: Zod's job, react-hook-form's job, a resolver's job, and a backend pipeline library's job — in one coherent stack that shares a type vocabulary end to end.

Want the deep dives?

Part 1 — The Glue Code Tax — the Zod + RHF seam counted line by line, then eliminated
Part 2 — Composable Async Pipelines — the full Result + flowAsync operator set
Part 3 — Schema-First React Forms — the 3-layer error system, array fields, and the full-stack loop
Setup & AI tooling — how to get Claude Code and other AI tools to reason from the library docs instead of hallucinating Zod patterns
Bonus — Data Processing Pipelines — batch processing with combine, combineAll, partition

GitHub:

@railway-ts/pipelines — Result, Option, schema validation, composable pipelines
@railway-ts/use-form — React form hook with native schema integration