Code-first RPC for TypeScript
Plain TypeScript in.Bytes on the wire.
Write a router of async functions with ordinary types. tbr generate turns them into codecs, and the client reads lazy views straight from the response. Numeric columns arrive as Float32Array, ready for your charts.
response bytesfield v, 8 × f32, little-endian
on the client
const { t, v } = await api.series(query);
v // Float32Array(8)
[42.5, 47.25, 51, 49.75, 63.5, 71.25, 68, 55.5]
plot.setData([t, v]);- Reading 1000 objects
- 3.4–4.5× faster than
JSON.parsein browsers, verification included - Reading 2 of 7 fields
- 5.7–8.6× faster, because untouched fields cost nothing
- Numeric columns
- 19–118× faster on 100k points, verification included; typed arrays need no parsing
- Client runtime
- 5.3 KB min + gzip; 13.3 KB for the whole dashboard example
How it works
One contract, three files.
The router is the source of truth. Everything on the wire is derived from its types.
- 01
Write a router
Plain async functions and plain types. No IDL, no schema library. Branded numbers like u16 and f32 pick the wire width and are still just number in your code.
src/server/router.ts import type { u16, u32 } from 'ts-bin-rpc';/** A time series as two columns. */export interface Series {t: Float64Array; // ms since the epochv: Float32Array;}export const appRouter = {series: async (q: { host: u16; from: Date; to: Date; points: u32 }): Promise<Series> => {const t = timeline(q.from, q.to, q.points);return { t, v: sample(q.host, t) };},};export type AppRouter = typeof appRouter; - 02
Generate codecs
The CLI reads your types through the TypeScript 7.1 compiler API, writes typed codecs, and records stable field IDs in a lockfile you commit.
Terminal $ tbr generate --router src/server/router.tscreated tbr.lock.jsonwrote src/server/tbr.gen.ts$ tbr generate --router src/server/router.ts --watch # ~15 ms per save$ tbr check --router src/server/router.ts # in CI - 03
Call it from the client
Types come from typeof appRouter, as with tRPC. Only import type reaches server files, so the bundle holds the runtime and this direction’s codecs.
src/client/api.ts import { createClient } from 'ts-bin-rpc/client';import type { AppRouter } from '../server/router.ts';import { clientProcedures } from '../server/tbr.gen.ts';const api = createClient<AppRouter>({ url: '/rpc', procedures: clientProcedures });const { t, v } = await api.series({ host: 1, from, to, points: 10_000 });plot.setData([t, v]); // typed arrays over the response bytes, nothing copied
Why
tRPC’s ergonomics, without paying for JSON.
The developer experience stays code-first. What changes is what goes over the wire and how the client reads it.
Your types are the schema
Interfaces, unions, Date, generics, recursive types and typed arrays. No IDL to keep in sync and no validator DSL.
Branded numbers pick widths
u8, u16, u32, i32, f32, i64 and friends are number or bigint with an invisible tag. Assignments need no casts; the encoder checks ranges.
Lazy, zero-copy views
A response is verified once, then read on demand. Strings decode on first read and a field you never touch costs nothing.
Columns straight into charts
Float32Array and Float64Array fields come back as views over the response bytes. Hand them to uPlot or WebGL as they are.
Schema evolution in CI
tbr.lock.json gives every field a stable ID. tbr check labels each change safe or breaking, and stale generated code fails tsc.
Small, and runs anywhere
A Fetch API handler for Node, Bun, Deno and Workers. A 5.3 KB client runtime, no eval, so strict CSP works.
Streams and live state
Return a stream and rows arrive in batched frames. live() keeps rows by key and sends a snapshot, then only what changed, over HTTP or one WebSocket.
Validation in the types
u8 & Min<18>, string & Email: rules sit next to the types. The server checks every input, and inputSchema() checks forms on the client.
Fits the rest of your stack
TanStack Query options, a Vite plugin, middleware, request batching, cached GET queries and a DevTools panel for Chrome and Firefox.
Benchmarks
Measured against JSON.parse, in three browser engines.
Speed relative to JSON.parse(new TextDecoder().decode(bytes)), which is what response.json() does. Higher is better, and the dashed line marks JSON.
1000 users, every field of every object read once.
- with verification (development)
- without (production)
1000 users, two fields read. Views skip what you never touch.
- with verification (development)
- without (production)
1000 users, only the numeric columns read.
- with verification (development)
- without (production)
Four typed-array columns summed, against JSON number arrays. Nothing to parse.
- with verification (development)
- without (production)
1000 users encoded, against JSON.stringify. No verification on this path.
- ts-bin-rpc
A small response: 10 users, every field. The gain is a few microseconds.
- with verification (development)
- without (production)
500 products with 12–52 word descriptions, every field.
- with verification (development)
- without (production)
A single 150-byte object. Both take a microsecond or two; with verification JSON can be as fast or faster.
- with verification (development)
- without (production)
All numbers as a table
| Scenario | Chromium | Firefox | WebKit | Node |
|---|---|---|---|---|
| Read every field, verified | 4.5× | 3.4× | 3.8× | 8.2× |
| Read every field, not verified | 4.9× | 3.9× | 4.2× | 9.4× |
| Read 2 of 7 fields, verified | 8.6× | 5.8× | 5.7× | 16× |
| Read 2 of 7 fields, not verified | 10× | 7.7× | 6.7× | 20× |
| Numeric fields only, verified | 13× | 11× | 7.1× | 22× |
| Numeric fields only, not verified | 29× | 28× | 35× | 42× |
| 100k points, verified | 21× | 118× | 19× | 138× |
| 100k points, not verified | 21× | 118× | 19× | 138× |
| Encode | 3.0× | 1.7× | 2.1× | 2.9× |
| 10 users, verified | 1.4× | 1.1× | 1.1× | 2.8× |
| 10 users, not verified | 1.7× | 1.4× | 1.3× | 3.5× |
| Long text, verified | 1.7× | 2.4× | 2.6× | 5.1× |
| Long text, not verified | 2.1× | 2.9× | 3.2× | 6.5× |
| 1 user, verified | 0.9× | 0.7× | 0.6× | 1.2× |
| 1 user, not verified | 1.3× | 1.0× | 0.8× | 1.7× |
GitHub Actions ubuntu-latest, AMD EPYC 9V74 80-Core Processor, headless Chromium 156, Firefox 157, WebKit 27.2, Node 22.23, 2026-11-07, commit 445c39f. Median of 10 runs per runtime, each in a fresh process or browser. Runner CPUs vary between runs and move some rows by 10–25%; a few Firefox rows change by up to 2× between browser launches. Synthetic data, 30% of names in Cyrillic. Source: generated.md.
Size after compression
Relative to JSON with the same compressor. Shaded cells: JSON is smaller.
| Payload | gzip-6 | brotli-4 | brotli-6 | zstd-3 |
|---|---|---|---|---|
| 1000 users | −8% | −18% | −19% | −6% |
| 500 products, long text | 0% | −9% | −9% | −3% |
| 20 users | +10% | +13% | +10% | +10% |
| 100k points vs JSON number arrays | −1% | +9% | +12% | +2% |
| 100k points vs JSON objects | −21% | −24% | −24% | −27% |
generated-size.md. Decompression time is not measured.
Client bundle, min + gzip
- Runtime and client
- 5.3 KB
- Dashboard example, 3 procedures and a stream
- 13.3 KB
- Fixture with every supported type
- 13.3 KB
size.md, esbuild. The client gets only input encoders and output decoders.
Against other binary formats
Arrow, Flechette and Colyseus, on the same machine.
How many times faster ts-bin-rpc is, the lowest and highest of Node, Chromium, Firefox, WebKit, and the bytes of each message. Shaded cells: the other library wins.
| Workload | Against | ts-bin-rpc is | Bytes, ts-bin-rpc | Bytes, theirs |
|---|---|---|---|---|
| Table, every field1000 users, every field of every row read | Arrow JS | 7.5–11× faster | 64 KB 21 KB gz | 75 KB 28 KB gz |
| Flechette | 5.7–7.3× faster | 64 KB 21 KB gz | 75 KB 28 KB gz | |
| Table, numbers1000 users, the numeric columns read | Arrow JS | 2.6–3.1× faster | 64 KB 21 KB gz | 75 KB 28 KB gz |
| Flechette | 1.3–1.8× faster | 64 KB 21 KB gz | 75 KB 28 KB gz | |
| Series100k points in four columns, every value read | Arrow JS | 1.1–1.8× faster | 1953 KB 1303 KB gz | 1954 KB 1303 KB gz |
| Flechette | 1.0–1.7× faster | 1953 KB 1303 KB gz | 1954 KB 1303 KB gz | |
| Game state1000 entities, encoded and decoded | Colyseus | 12–16× faster | 34 KB 22 KB gz | 52 KB 35 KB gz |
| Small patch5 of 100 entities move: encode, decode, apply | Colyseus | 1.4–1.9× faster | 180 B 151 B gz | 75 B 98 B gz |
| Large patch50 of 1000 entities move: encode, decode, apply | Colyseus | 5.9–7.1× faster | 824 B 694 B gz | 750 B 694 B gz |
Intel Xeon Processor (Icelake), Node and headless Chromium, Firefox and WebKit, commit 491f807. Median of 5 runs per runtime. Arrow and Flechette read whole columns, their fastest way; ts-bin-rpc reads rows. A patch of ts-bin-rpc is its live-state frame; Colyseus finds changes in its setters, so its time includes that.All benchmark tables; source: libs.md.
Honest fit
When not to use it.
The format is built for many objects, numbers and partial reads. It does not try to beat JSON everywhere.
A good fit
- A TypeScript client and a TypeScript server that ship together.
- Lists of many objects, numeric series, dashboards, realtime frames.
- Screens that read a few fields out of large responses.
- You want tRPC-style types end to end without a JSON payload.
Stay with JSON when
- Public APIs and other languages. Use JSON, OpenAPI or protobuf; this is for one TypeScript app talking to its own backend.
- Small, text-heavy responses. 20 users come out 10–13% larger than JSON after compression; long product descriptions come out 0–9% smaller.
- Debugging with curl | jq. Bodies are binary. The DevTools panel, debug: true and tbr decode decode them, but curl shows bytes.
- You need the tRPC ecosystem. tRPC links, adapters and plugins do not work here; ts-bin-rpc has its own client and integrations.
- You need a release proven in production. The beta fixes the wire format and the API, but few apps run it yet.