ts-bin-rpc 0.0.0-stage → 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Artem Shaov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# ts-bin-rpc
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A code-first TypeScript RPC with a binary wire format. Your router's TypeScript types are the
+schema: [`ts-bin-rpc-cli`](https://www.npmjs.com/package/ts-bin-rpc-cli) reads them and generates
+codecs. The client gets lazy views over the response bytes, and numeric arrays arrive as
+`TypedArray` columns with no parsing.
+
+This package is the runtime: `ts-bin-rpc/server`, `ts-bin-rpc/client`, `ts-bin-rpc/node`, the
+numeric brands and the codec runtime the generated code imports.
+
+```sh
+npm install ts-bin-rpc@alpha
+npm install -D ts-bin-rpc-cli@alpha typescript@7.1.0-beta
+```
+
+**Alpha.** The wire format may change before 1.0. Docs: https://tom4ikss.github.io/ts-bin-RPC/.
+Source and issues: https://github.com/Tom4ikss/ts-bin-RPC. MIT license.

package/dist/brands.d.ts

@@ -0,0 +1,31 @@
+export declare const tbr: unique symbol;
+export type u8 = number & {
+    readonly [tbr]?: 'u8';
+};
+export type i8 = number & {
+    readonly [tbr]?: 'i8';
+};
+export type u16 = number & {
+    readonly [tbr]?: 'u16';
+};
+export type i16 = number & {
+    readonly [tbr]?: 'i16';
+};
+export type u32 = number & {
+    readonly [tbr]?: 'u32';
+};
+export type i32 = number & {
+    readonly [tbr]?: 'i32';
+};
+export type f32 = number & {
+    readonly [tbr]?: 'f32';
+};
+export type f64 = number & {
+    readonly [tbr]?: 'f64';
+};
+export type u64 = bigint & {
+    readonly [tbr]?: 'u64';
+};
+export type i64 = bigint & {
+    readonly [tbr]?: 'i64';
+};

package/dist/brands.js

@@ -0,0 +1 @@
+export {};

package/dist/client.d.ts

@@ -0,0 +1,30 @@
+import { type Limits } from './runtime.js';
+import { type ClientProcedures } from './rpc.js';
+import type { Client, DecodeMode, ProcedurePath } from './router.js';
+export interface ClientOptions<R = unknown> {
+    /** Base URL of the procedures, e.g. `/rpc` or `https://api.example.com/rpc`. */
+    url: string;
+    /** `clientProcedures` (or `procedures`) from generated code. */
+    procedures: ClientProcedures;
+    /** Default: globalThis.fetch. */
+    fetch?: typeof fetch;
+    /** Sent with every call; a function is called before each one. */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /**
+     * What calls return. `'lazy'` (default): views that read the response bytes on access. `'eager'`:
+     * plain objects, as `toPlain` gives, safe to mutate, spread and clone. A map sets it per procedure,
+     * `CallOptions.decode` per call.
+     */
+    decode?: DecodeMode | {
+        readonly [P in ProcedurePath<R>]?: DecodeMode;
+    };
+    /**
+     * Verify responses before reading them. Default: on in development, off in production builds
+     * (`process.env.NODE_ENV === 'production'`, which bundlers replace at build time).
+     */
+    verify?: boolean;
+    limits?: Partial<Limits>;
+    /** Log every call to the console: procedure, time, size, result. */
+    debug?: boolean;
+}
+export declare function createClient<R>(options: ClientOptions<R>): Client<R>;

package/dist/client.js

@@ -0,0 +1,111 @@
+// createClient<AppRouter>: a proxy whose calls POST the encoded input and return views over the response.
+import { decodeError, FLAG_ERROR, toPlain, VerifyError } from './runtime.js';
+import { codeForStatus, CONTENT_TYPE, RpcError, SCHEMA_HEADER } from './rpc.js';
+const decoder = new TextDecoder();
+/** Production builds skip response verification by default; without a bundler this is false. */
+function production() {
+    try {
+        return process.env.NODE_ENV === 'production';
+    }
+    catch {
+        return false;
+    }
+}
+export function createClient(options) {
+    const { procedures, verify = !production(), limits, debug = false } = options;
+    const decode = options.decode;
+    const base = options.url.replace(/\/+$/, '');
+    const warned = new Set();
+    async function call(path, args) {
+        const proc = procedures[path];
+        if (!proc)
+            throw new RpcError('NOT_FOUND', `procedure '${path}' is not in the generated code; run tbr generate`);
+        const [input, opts = {}] = (proc.input ? args : [undefined, args[0]]);
+        opts.signal?.throwIfAborted();
+        const body = proc.input && !(input === undefined && proc.inputOptional) ? proc.input.encode(input) : new Uint8Array(0);
+        const headers = new Headers(typeof options.headers === 'function' ? await options.headers() : options.headers);
+        if (opts.headers)
+            new Headers(opts.headers).forEach((v, k) => headers.set(k, v));
+        headers.set('content-type', CONTENT_TYPE);
+        headers.set(SCHEMA_HEADER, proc.hash);
+        const t0 = debug ? performance.now() : 0;
+        const fetchFn = options.fetch ?? globalThis.fetch;
+        const res = await fetchFn(`${base}/${path}`, { method: 'POST', body, headers, signal: opts.signal });
+        const bytes = new Uint8Array(await res.arrayBuffer());
+        let result;
+        let error;
+        if (res.headers.get('content-type')?.split(';')[0].trim() !== CONTENT_TYPE) {
+            error = new RpcError(res.ok ? 'BAD_RESPONSE' : codeForStatus(res.status), `HTTP ${res.status}: not a ts-bin-rpc response`, undefined, { status: res.status });
+        }
+        else if (!res.ok || (bytes.length > 3 && bytes[3] & FLAG_ERROR)) {
+            error = readError(bytes, res.status);
+        }
+        else if (proc.output) {
+            try {
+                const mode = opts.decode ?? (typeof decode === 'string' ? decode : decode?.[path]);
+                result = mode === 'eager' ? proc.output.decode(bytes, { verify, limits }) : proc.output.view(bytes, { verify, limits });
+            }
+            catch (e) {
+                if (!(e instanceof VerifyError))
+                    throw e;
+                error = new RpcError('BAD_RESPONSE', `invalid response: ${e.message}`, undefined, { status: res.status, cause: e });
+            }
+        }
+        if (debug) {
+            const ms = (performance.now() - t0).toFixed(1);
+            console.groupCollapsed(`tbr ${path} ${error ? error.code : res.status} ${ms} ms, ${body.length} B → ${bytes.length} B`);
+            if (proc.input)
+                console.log('input', input);
+            if (error)
+                console.log('error', error);
+            else
+                console.log('output', toPlain(result));
+            console.groupEnd();
+            const serverHash = res.headers.get(SCHEMA_HEADER);
+            if (serverHash && serverHash !== proc.hash && !warned.has(path)) {
+                warned.add(path);
+                console.warn(`ts-bin-rpc: '${path}': the server has another version of this procedure (client ${proc.hash}, server ${serverHash})`);
+            }
+        }
+        if (error)
+            throw error;
+        return result;
+    }
+    const proxy = (path) => {
+        const children = new Map();
+        return new Proxy(() => { }, {
+            get(_, key) {
+                // `then` stays undefined so that `await api.user` does not try to call a procedure.
+                if (typeof key !== 'string' || key === 'then')
+                    return undefined;
+                let child = children.get(key);
+                if (!child)
+                    children.set(key, (child = proxy(path ? `${path}.${key}` : key)));
+                return child;
+            },
+            apply(_, __, args) {
+                return call(path, args);
+            },
+        });
+    };
+    return proxy('');
+}
+function readError(bytes, status) {
+    let e;
+    try {
+        e = decodeError(bytes);
+    }
+    catch (cause) {
+        return new RpcError('BAD_RESPONSE', `HTTP ${status}: malformed error response`, undefined, { status, cause });
+    }
+    let data;
+    if (e.data) {
+        try {
+            data = JSON.parse(decoder.decode(e.data));
+        }
+        catch {
+            data = undefined;
+        }
+    }
+    return new RpcError(e.code, e.message, data, { status });
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export type { u8, i8, u16, i16, u32, i32, f32, f64, u64, i64 } from './brands.js';
+export type { Client, ClientProcedure, CallOptions, DecodeMode, ProcedurePath, InputOf, OutputOf } from './router.js';
+export { RpcError, STATUS, CONTENT_TYPE, SCHEMA_HEADER, type ClientProcedures, type ServerProcedures, type ClientEntry, type ServerEntry } from './rpc.js';
+export { toPlain, EncodeError, VerifyError } from './runtime.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { RpcError, STATUS, CONTENT_TYPE, SCHEMA_HEADER } from './rpc.js';
+export { toPlain, EncodeError, VerifyError } from './runtime.js';

package/dist/node.d.ts

@@ -0,0 +1,6 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+export interface NodeListenerOptions {
+    /** Requests with a larger body are answered 413 before the handler runs. Default: 64 MB. */
+    maxBytes?: number;
+}
+export declare function toNodeListener(handler: (request: Request) => Response | Promise<Response>, options?: NodeListenerOptions): (req: IncomingMessage, res: ServerResponse) => Promise<void>;

package/dist/node.js

@@ -0,0 +1,48 @@
+import { DEFAULT_LIMITS } from './runtime.js';
+export function toNodeListener(handler, options = {}) {
+    const maxBytes = options.maxBytes ?? DEFAULT_LIMITS.maxBytes;
+    return async (req, res) => {
+        try {
+            const chunks = [];
+            let size = 0;
+            for await (const chunk of req) {
+                size += chunk.length;
+                if (size > maxBytes) {
+                    res.writeHead(413).end();
+                    req.destroy();
+                    return;
+                }
+                chunks.push(chunk);
+            }
+            const body = new Uint8Array(size);
+            let at = 0;
+            for (const c of chunks) {
+                body.set(c, at);
+                at += c.length;
+            }
+            const headers = new Headers();
+            for (const [k, v] of Object.entries(req.headers)) {
+                if (Array.isArray(v))
+                    for (const x of v)
+                        headers.append(k, x);
+                else if (v !== undefined)
+                    headers.set(k, v);
+            }
+            const method = req.method ?? 'GET';
+            const url = new URL(req.url ?? '/', `http://${req.headers.host ?? 'localhost'}`);
+            const response = await handler(new Request(url, { method, headers, body: method === 'GET' || method === 'HEAD' ? undefined : body }));
+            res.statusCode = response.status;
+            response.headers.forEach((v, k) => res.setHeader(k, v));
+            res.end(new Uint8Array(await response.arrayBuffer()));
+        }
+        catch (e) {
+            // The client went away (an aborted fetch, a closed tab): nobody to answer, nothing to report.
+            if (req.destroyed || res.destroyed)
+                return;
+            console.error('ts-bin-rpc: request failed:', e);
+            if (!res.headersSent)
+                res.writeHead(500);
+            res.end();
+        }
+    };
+}

package/dist/router.d.ts

@@ -0,0 +1,34 @@
+export type AnyProcedure = (...args: any[]) => unknown;
+export type AnyRouter = {
+    readonly [key: string]: AnyProcedure | AnyRouter;
+};
+/** `'user.get' | 'user.list' | ...` */
+export type ProcedurePath<R, P extends string = ''> = {
+    [K in keyof R & string]: R[K] extends AnyProcedure ? `${P}${K}` : ProcedurePath<R[K], `${P}${K}.`>;
+}[keyof R & string];
+export type ProcedureAt<R, P extends string> = P extends `${infer H}.${infer T}` ? H extends keyof R ? ProcedureAt<R[H], T> : never : P extends keyof R ? R[P] : never;
+/** Input of a procedure without `undefined`; `never` when it takes none. */
+export type InputOf<R, P extends string> = Exclude<Parameters<Extract<ProcedureAt<R, P>, AnyProcedure>>[0], undefined | void>;
+export type InputOptional<R, P extends string> = undefined extends Parameters<Extract<ProcedureAt<R, P>, AnyProcedure>>[0] ? true : false;
+export type OutputOf<R, P extends string> = Awaited<ReturnType<Extract<ProcedureAt<R, P>, AnyProcedure>>>;
+/** Client arguments for a procedure's parameter list: the input only, `ctx` stays on the server. */
+export type InputArgs<A extends unknown[]> = A extends [] ? [] : A extends [infer I, ...unknown[]] ? [I] extends [void] ? [] : undefined extends I ? [input?: I] : [input: I] : A extends [input?: infer I, ...rest: unknown[]] ? [input?: I] : [];
+/** What a call returns: `'lazy'` views that read the response on access, or `'eager'` plain objects. */
+export type DecodeMode = 'lazy' | 'eager';
+export interface CallOptions {
+    signal?: AbortSignal;
+    headers?: HeadersInit;
+    /** Overrides the client's `decode` for this call. */
+    decode?: DecodeMode;
+}
+export type ClientProcedure<F> = F extends (...args: infer A) => infer O ? (...args: [...InputArgs<A>, options?: CallOptions]) => Promise<Awaited<O>> : never;
+export type Client<R> = {
+    readonly [K in keyof R]: R[K] extends AnyProcedure ? ClientProcedure<R[K]> : Client<R[K]>;
+};
+/** Shows up in a type error when generated code no longer matches the router. */
+export interface StaleCodegen_RunTbrGenerate<Where extends string> {
+    readonly where: Where;
+}
+/** `true` when the generated and the source type accept the same values, else a readable error type. */
+export type Same<Generated, Source, Where extends string> = [Generated] extends [Source] ? [Source] extends [Generated] ? true : StaleCodegen_RunTbrGenerate<Where> : StaleCodegen_RunTbrGenerate<Where>;
+export type Expect<T extends true> = T;

package/dist/router.js

@@ -0,0 +1,3 @@
+// Types derived from a router: a plain object of `(input, ctx) => result` functions, nested by namespace.
+// Shared by the client (call signatures), the server (lookup) and generated code (staleness checks).
+export {};

package/dist/rpc.d.ts

@@ -0,0 +1,39 @@
+import type { Decoder, Encoder } from './runtime.js';
+export declare const CONTENT_TYPE = "application/vnd.tbr";
+/** Request: the client's hash of the procedure's contract. Response: the server's. */
+export declare const SCHEMA_HEADER = "x-tbr-schema";
+/** HTTP status per error code. Codes not listed here are application errors and map to 400. */
+export declare const STATUS: Readonly<Record<string, number>>;
+export interface RpcErrorOptions {
+    status?: number;
+    cause?: unknown;
+}
+/** Thrown by procedures to send an error to the client; the client rethrows it with the same code. */
+export declare class RpcError<Data = unknown> extends Error {
+    name: string;
+    readonly code: string;
+    readonly data: Data | undefined;
+    readonly status: number;
+    constructor(code: string, message: string, data?: Data, options?: RpcErrorOptions);
+}
+interface Entry<In, Out> {
+    input: In | null;
+    inputOptional: boolean;
+    output: Out | null;
+    /** Hash of the contract: the lockfile entries of every type the procedure reaches. */
+    hash: string;
+}
+/** What the client needs of a procedure: encode the input, read the output. */
+export type ClientEntry = Entry<Encoder<any>, Decoder<any>>;
+/** What the server needs of a procedure: read the input, encode the output. */
+export type ServerEntry = Entry<Decoder<any>, Encoder<any>>;
+/** `clientProcedures` of generated code (`procedures` fits too). */
+export type ClientProcedures = {
+    readonly [path: string]: ClientEntry;
+};
+/** `serverProcedures` of generated code (`procedures` fits too). */
+export type ServerProcedures = {
+    readonly [path: string]: ServerEntry;
+};
+export declare function codeForStatus(status: number): string;
+export {};

package/dist/rpc.js

@@ -0,0 +1,38 @@
+export const CONTENT_TYPE = 'application/vnd.tbr';
+/** Request: the client's hash of the procedure's contract. Response: the server's. */
+export const SCHEMA_HEADER = 'x-tbr-schema';
+/** HTTP status per error code. Codes not listed here are application errors and map to 400. */
+export const STATUS = {
+    BAD_INPUT: 400,
+    UNAUTHORIZED: 401,
+    FORBIDDEN: 403,
+    NOT_FOUND: 404,
+    METHOD_NOT_ALLOWED: 405,
+    CONFLICT: 409,
+    SCHEMA_MISMATCH: 409,
+    PAYLOAD_TOO_LARGE: 413,
+    UNSUPPORTED_MEDIA_TYPE: 415,
+    TOO_MANY_REQUESTS: 429,
+    INTERNAL: 500,
+    BAD_OUTPUT: 500,
+    BAD_RESPONSE: 502,
+};
+/** Thrown by procedures to send an error to the client; the client rethrows it with the same code. */
+export class RpcError extends Error {
+    name = 'RpcError';
+    code;
+    data;
+    status;
+    constructor(code, message, data, options = {}) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.code = code;
+        this.data = data;
+        this.status = options.status ?? STATUS[code] ?? 400;
+    }
+}
+export function codeForStatus(status) {
+    for (const code in STATUS)
+        if (STATUS[code] === status)
+            return code;
+    return status >= 500 ? 'INTERNAL' : 'BAD_RESPONSE';
+}