Skip to content

Types

Which TypeScript types go over the wire, how they are encoded and what the client gets back.

The contract is the TypeScript types of your router: procedure inputs, outputs and everything they reach. tbr generate turns each type into a wire layout. A type it cannot send is an error that names the file, line and field path:

src/router.ts:18:3 User.meta: type 'unknown' is not serializable
TypeScriptOn the wireOn the client
boolean1 byteboolean
numberf64, 8 bytesnumber
u8 i8 u16 i16 u32 i32 f32 f641–8 bytesnumber
u64 i64, bigint8 bytes (bigint is i64)bigint
stringa string block per messagestring, decoded on first read
Datef64 millisecondsDate
'a' | 'b' | 'c'enum, u8 index (u16 past 256 values)the literal
Uint8ArraybytesUint8Array over the response
Float32Array, Float64Array, Int32Array …aligned blockthe same typed array over the response
T[]vector; arrays of objects are stored column by columna real Array
interface or object literaltable with a field per propertya view
x?: T, T | undefinedthe field is absentundefined
T | nulla null bitnull
{ kind: 'a'; … } | { kind: 'b'; … }tag + the variant’s tablea view of the variant
generics (Page<User>)one table per instantiationa view
recursive types (manager: User | null)through referencesa view
'ok' and other single literalsnothing, the value is knownthe literal

number is a 64-bit float, as in JavaScript. To send an integer in fewer bytes, or as a real integer, use a brand:

import type { u8, u16, u32, i32, f32, u64 } from 'ts-bin-rpc';
interface Pixel {
x: u16;
y: u16;
rgba: u32;
depth: f32;
}

A brand is number with an optional, invisible tag, so assignments need no casts. You still write { x: 1, y: 2, rgba: 0xff00ffff, depth: 0.5 }. The tag survives aliases: type UserId = u32 is still a u32.

The range cannot be checked by types, so the encoder checks it at run time. -1, 1.5 or 5n in a u32 field throws an EncodeError with the path to the value:

EncodeError: at [17].manager.age: expected u8, got 300

u64 and i64 are bigint. Plain bigint is i64.

Two encodings make realtime feeds smaller without changing what your code reads:

import type { Delta, i32, Scale, u32 } from 'ts-bin-rpc';
interface Tick {
t: Date & Delta; // time stamps as differences
price: i32 & Scale<100> & Delta; // cents in an i32, as differences
size: u32;
side: 'buy' | 'sell';
}
  • Scale<N> on an integer brand stores Math.round(value * N) in it: i32 & Scale<100> keeps two decimals in 4 bytes, i16 & Scale<100> coordinates of ±327 in 2. You write and read plain numbers (64250.25); a value that does not fit the brand after scaling is an EncodeError, and a column of it in columns() is a Float64Array of the scaled-back values.
  • Delta sends a column of an array of objects as its first value and the differences between neighbours, in 1, 2 or 4 bytes each, whichever fits. It works on 8–32 bit integer brands, scaled ones included, and on Date. It pays off on sorted or slowly changing values: time stamps, sequence numbers, prices. The encoder falls back to the plain column when differences would not be smaller, so on an 8-bit brand, whose differences take a byte as well, Delta has no effect.

The price is zero-copy: such a column is decoded into its own typed array when the view of the array is created, instead of being a window into the message. That is one pass over the column, which costs nothing next to the network on a feed, but Delta is not for a column you mostly do not read.

16 ticks per message, 300 messages, deflate with a context for the whole stream (deltas.md):

TickRawDeflate
JSON979 B159 B
t: number; price: f32328 B144 B
t: Date & Delta; price: i32 & Scale<100> & Delta180 B77 B

Without any of this, optional and nullable columns that are empty in most rows (patches of live state, sparse fields) are packed: only the rows that have a value take space.

Both are part of the field’s type for tbr check: adding or removing Delta or changing N is a breaking change, as changing the brand is.

Interfaces, type aliases of object types and inline object literals all work. An inline type gets a name from where it appears, for example user.get:input. The name shows up in errors and in the lockfile.

An object may have up to 30 optional or nullable fields. An object with an index signature is a record.

Three kinds of unions work:

  • String literal unions ('admin' | 'user') become enums. The index of each value is fixed in the lockfile, so reordering the union is safe.

  • Discriminated unions of objects. Every variant needs a property with a distinct string literal; that property is the tag.

    type Shape =
    | { kind: 'circle'; r: f32 }
    | { kind: 'rect'; w: f32; h: f32 };

    The client gets a view of the variant, and switch (shape.kind) narrows as usual.

  • T | null and T | undefined, with any T above.

Anything else is rejected with a message that says what is supported: numeric literal unions, unions of unrelated objects, string | number.

Use typed arrays for series, coordinates, samples and pixels, anything you hand to a chart, WebGL or WASM. Use T[] for lists you will map, filter and render.

Arrays of objects (User[]) are stored column by column: all ids together, then all names, and so on. This is why reading two fields of 1000 users is several times faster than reading all of them. The client still gets a real Array of views.

interface Inventory {
stock: Record<string, u32>; // a plain object
byId: Map<u32, Item>; // a Map
corner: [f32, f32]; // an array of two
range: [Date, Date | null];
}
  • Record<string, T> and { [key: string]: T } arrive as plain objects, Map<K, V> and ReadonlyMap<K, V> as a Map. A record takes only string keys; for numeric keys use a Map.
  • Map keys are strings, string literal unions, numbers, bigints or booleans. Date and object keys are rejected: a Map compares them by identity, so no key would match after a round trip.
  • Values, like array elements, cannot be null or undefined. An object with an index signature cannot have other fields; move them to a field of their own.
  • Record<'a' | 'b', T> is not a map: it is an object with the fields a and b.
  • Tuples have a fixed length. Elements may be T | null or T | undefined; optional ([a?: T]) and rest ([...T[]]) elements are rejected. readonly [A, B] works.

On the wire a map is two arrays, its keys and its values. Record<string, T> and Map<string, T> are the same bytes, so a field can change from one to the other without breaking clients. The values of a map of objects are stored column by column, like any array of objects.

A view builds the map or the tuple when the field is read first, and keeps it: the keys are read then, the values are views. The encoder checks the shape: a record must be a plain object (a Map passed for one would lose its entries), a tuple must have its length. A __proto__ key is an own property of the record that arrives, not its prototype.

  • Input: at most one parameter before the context. It may be optional; it may not be null.
  • Output: any supported type, or void. It cannot be null or undefined at the top level: wrap it, as in { user: User | null }.
  • Overloaded functions are rejected.
  • Names: no procedure or namespace may be called then (promises look it up, so await api.user would call it) or after a method of ts-bin-rpc/tanstack: pathKey, queryKey, queryOptions, infiniteQueryKey, infiniteQueryOptions, mutationOptions.
TypeStatus
any, unknown, never, objectnever: declare the fields
functions, symbolnever
classesnever: their private fields would go out with the rest; declare an interface
TypeScript enumuse a string literal union
Setuse an array
optional and rest elements of tuplesuse an object or an array
Record<number, T>, symbol and template literal keysuse a Map or string keys
numeric literal unions (1 | 2)planned; use string literals or a brand