never-rest

An opinionated architectural choice — never-rest puts Result-based railway-oriented programming at the API boundary. Whether either side uses railway style internally is up to that team and does not matter to the contract. The assumption is that at least one side wants it; otherwise there is no reason to reach for this.

On top of that choice: a ContractDef where handlers return Result instead of throwing. serve projects that contract onto HTTP. ./local runs the same contract in-process — module to module, or behind a host that already carries the operation as a string (NDJSON, MCP stdio, agent tool calls). Errors carry their cause chain across boundaries. Disclosure is graded by caller trust — not blanket obfuscation.

Package: @eddy-works/never-rest · Licence: Apache-2.0 · Peer: neverthrow · Runtime deps: none (validation via Standard Schema)

Install

npm i @eddy-works/never-rest neverthrow

pnpm add @eddy-works/never-rest neverthrow

neverthrow is a peer dependency — it's the Result / ResultAsync implementation never-rest builds on.

Exports

| Module | Key exports | | --- | --- | | @eddy-works/never-rest | RailError, railError, chain, flatten, formatChain, statusFor, toDeclaredResponse, HOST_STATUSES, disclose, respond | | @eddy-works/never-rest/contract | RouteDef, ContractDef, ClientArgsOf, HandlerArgsOf, OutputOf, ErrorOf, ClientErrorOf, ServerErrorOf, parseRouteSources, parseOutput, compileContract, isContractPath, compilePath, matchPath, normalizePath, assertHandlersComplete, ContractConfigurationError | | @eddy-works/never-rest/server | serve, Handler, Handlers, ServeHandler, compileRoutes, matchRoute, assertProtocolResponse | | @eddy-works/never-rest/client | createClient, Client, ClientOptions, buildRequest | | @eddy-works/never-rest/node | toNodeHandler, FetchHandler, NodeHttpHandler | | @eddy-works/never-rest/local | createLocalClient, createDispatcher | | @eddy-works/never-rest/testing | createTestClient, assertProtocolResponse, checkTransportStability, checkContractOutputs | | @eddy-works/never-rest/openapi | toOpenAPI, OpenApiExportError | | @eddy-works/never-rest/query | createQueryOptions, createMutationOptions, isRetryable |

The problem

Most REST libraries assume handlers throw. Middleware intercepts exceptions, typed errors get lost at the boundary, and clients branch on tuples or catch blocks instead of composing with andThen. Contract DSLs (initContract(), chained builders) inflate TypeScript instantiation cost — @ts-rest/core measures ~5,984 instantiations per route on a 20-route fixture. oRPC types errors on the wire but its server model is throw-based; its non-throwing safe() client does not compose with map / andThen / match. never-rest is contract-first with plain object literals, Result/ResultAsync end to end, and a published per-route type budget enforced in CI.

No middleware

When handlers return Result, auth, side effects, and after-effects are just functions in the chain — not a separate interceptor stack:

getInvoice: ({ params, request }) =>
  requireAuth(request) // gate
    .andThen((session) => requireRole(session, 'billing'))
    .andTee((session) => metrics.increment('invoice.auth_ok')) // side effect
    .andThen((session) => loadInvoiceFor(session, params.id))
    .andTee((invoice) => audit.read('invoice', invoice.id)), // after-effect (best-effort)

If auth fails, the domain call never runs. Tee effects observe without inventing new failure modes; use andThen when a follow-up must succeed. Full catalogue (router, recover, fan-out, lift, …) with neverthrow and ROP links: docs/railway-patterns.md. Thesis: docs/concepts.md — No middleware.

Quickstart

Handlers return a neverthrow Result — never throw. Compose with map / andThen on the server; the client is the same ResultAsync shape.

import { ok, err, type Result } from 'neverthrow';
import { z } from 'zod';
import { railError, type RailError } from '@eddy-works/never-rest';
import type { ContractDef } from '@eddy-works/never-rest/contract';
import { serve, type Handlers } from '@eddy-works/never-rest/server';
import { createClient } from '@eddy-works/never-rest/client';

const userSchema = z.object({ id: z.string(), name: z.string() });
type User = z.infer<typeof userSchema>;

// Plumbing — declare routes, schemas, and status map.
const contract = {
  getUser: {
    method: 'GET',
    path: '/users/:id',
    params: z.object({ id: z.string() }),
    output: userSchema,
    errors: { not_found: 404 },
  },
  createUser: {
    method: 'POST',
    path: '/users',
    body: z.object({ name: z.string().min(1) }),
    output: userSchema,
    success: 201,
    errors: { conflict: 409 },
  },
} as const satisfies ContractDef;

// Business logic — compose with `map` / `andThen` the same way as the client.
const users = new Map<string, User>([['ada', { id: 'ada', name: 'Ada' }]]);

function findUser(id: string): Result<User, RailError<'not_found'>> {
  const user = users.get(id);
  if (user === undefined) {
    return err(railError('not_found', `User ${id} not found`));
  }
  return ok(user);
}

function reserveId(name: string): Result<string, RailError<'conflict'>> {
  const id = name.toLowerCase();
  if (users.has(id)) {
    return err(railError('conflict', `User ${id} already exists`));
  }
  return ok(id);
}

const handlers: Handlers<typeof contract, undefined> = {
  getUser: ({ params }): Result<User, RailError<'not_found'>> =>
    findUser(params.id).map((user) => ({ ...user, name: user.name.trim() })),
  createUser: ({ body }): Result<User, RailError<'conflict'>> =>
    reserveId(body.name).map((id) => {
      const user = { id, name: body.name };
      users.set(id, user);
      return user;
    }),
};

// Plumbing — mount the contract; disclosure grades what callers see.
export default serve(contract, handlers, {
  origin: 'users-api',
  disclosure: (req) =>
    req.headers.get('x-internal') === '1' ? 'full' : 'public',
});

const client = createClient(contract, { baseUrl: 'https://api.example.com' });

await client
  .getUser({ params: { id: 'ada' } })
  .andThen((user) => client.createUser({ body: { name: `${user.name} Jr` } }))
  .match(
    (user) => console.log(user.id),
    (error) => console.error(error.code), // not_found | conflict | validation_error | internal | unavailable
  );

Bring any Standard Schema validator (Zod 4, Valibot, ArkType). Use as const satisfies ContractDef on every contract — without as const, errors widens and domain codes stop being literal. serve returns a callable fetch handler (always answers, including route_not_found) plus cooperative handle() on Workers, Deno, Bun, Node 18+, SvelteKit, Next. For classic Node/http or Express, use toNodeHandler from @eddy-works/never-rest/node.

The same contract also runs without HTTP. Handlers that omit request are LocalHandlers — assignable to serve as well:

import { createLocalClient, createDispatcher } from '@eddy-works/never-rest/local';

const localHandlers = {
  getUser: ({ params }) => findUser(params.id),
  createUser: ({ body }) =>
    reserveId(body.name).map((id) => {
      const user = { id, name: body.name };
      users.set(id, user);
      return user;
    }),
};

const localUsers = createLocalClient(contract, localHandlers, {
  origin: 'users-api',
});
await localUsers.getUser({ params: { id: 'ada' } });

await createDispatcher(contract, localHandlers, { origin: 'users-api' }).dispatch(
  'getUser',
  { params: { id: 'ada' } },
);

createLocalClient is one typed method per operation. createDispatcher is the same machinery addressed by operation name, for a socket, MCP stdio, or tool-call host that already has the string. Both validate declared input and output; neither constructs a Request or Response. Disclosure defaults to full. Route errors status maps are ignored. See docs/api.md — local.

Examples

Mini projects share one contract and mount it on different runtimes — see examples/README.md:

| Example | Runtime | | --- | --- | | express | Express via ./node | | hono | Hono | | next-app-router | Next.js App Router | | sveltekit | SvelteKit | | cloudflare-workers | Cloudflare Workers | | gateway | Cause chains + disclosure | | validators | Zod / Valibot / ArkType | | files-and-streams | Sibling multipart + SSE |

pnpm build
pnpm --filter @never-rest-examples/express start

Type budget

never-rest optimises for measured TypeScript instantiations per route, enforced in CI via @ark/attest. On synthetic 1–40 route fixtures against real src types (TypeScript 5.9.3), combined contract + client marginal slope is ~584 instantiations per route. Published budget: 1,800 per route. Research anchor for @ts-rest/core's c.router() DSL: ~5,984 per route — roughly 10× never-rest.

Methodology, reproduction, and slope breakdown: docs/performance.md.

When not to use this

| Alternative | Prefer it when | | --- | --- | | ts-rest | You want the initContract() builder, existing ecosystem adapters, or OpenAPI generation today. ts-rest is mature for contract-first REST with Zod; its DSL costs substantially more per route in instantiation benchmarks. Last stable release noted in project research: 2025-03-04. | | oRPC | You want RPC-style procedures, streaming, or framework integrations oRPC already ships. Server handlers use throw errors.NOT_FOUND(); typed errors do not compose as Result. The safe() client returns a tuple, not a composable ResultAsync. | | Throwing handlers + middleware | Your team already standardises on exception middleware, you do not need cross-service cause chains, and graded disclosure is unnecessary. |

Documentation

Browsable site: project-eddy.github.io/never-rest.

| Doc | Topic | | --- | --- | | docs/concepts.md | Railway at the boundary, HTTP and local transports, no middleware, errors as data, trust circles | | docs/railway-patterns.md | Full railway/neverthrow pattern catalogue + white-label tenant kitchen sink | | docs/advanced-usage.md | Policy without middleware — capabilities, composers, host wraps, agents | | docs/api.md | Every public export, signature, example — including ./local | | docs/examples.md | Express, Next, SvelteKit, Hono, Workers, gateway, files-and-streams | | docs/files-and-streams.md | JSON on the railway; multipart and SSE on the host | | docs/errors-as-intelligence.md | nextStep, origin, retryable, gateway chains | | docs/comparison.md | vs ts-rest, oRPC, tRPC, and Hono RPC | | docs/migrating.md | From ts-rest, oRPC, throwing handlers | | docs/performance.md | Type instantiation budget (~584/route, CI gate) |

Agent lookup index: skills/never-rest/SKILL.md.

Specs

Gherkin scenarios in specs/ — extract with pnpm specs:extract. Tests map one-to-one to scenario titles:

| Spec | Tests | | --- | --- | | specs/status-mapping.spec.md | src/status.test.ts, src/respond.test.ts, src/server/serve.test.ts | | specs/graded-disclosure.spec.md | src/disclose.test.ts, src/respond.test.ts, src/server/serve.test.ts | | specs/cause-chaining.spec.md | src/error.test.ts, src/server/serve.test.ts | | specs/client-results.spec.md | src/client/create.test.ts | | specs/server-output-validation.spec.md | src/server/serve.test.ts | | specs/contract-compilation.spec.md | src/contract/compile.test.ts, src/contract/path.test.ts, src/server/serve.test.ts | | specs/wire-serialization.spec.md | src/client/create.test.ts, src/client/request.ts paths | | specs/input-sources.spec.md | src/contract/compile.test.ts, src/contract/parse.test.ts | | specs/openapi-export.spec.md | src/openapi/to-openapi.test.ts | | specs/local-dispatch.spec.md | src/local/dispatch.test.ts | | specs/railway-boundary.spec.md | src/railway/ |

See specs/README.md for extraction and layout.