ts-procedures

A TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition. Define your procedures once and get full type inference, runtime validation and procedure documentation/configuration.

Goals of this Project

1. Full type safety
2. Auto generated documentation and client api spec
3. Fast and performant
4. Excellent DX (and agent documentation)

Installation

npm install ts-procedures

Quick Start

import { Procedures } from 'ts-procedures'
import { Type } from 'typebox'

// Create a procedures factory
const { Create } = Procedures()

// Define a procedure with schema validation
const { GetUser, procedure, info } = Create(
  'GetUser',
  {
    description: 'Fetches a user by ID',
    schema: {
      params: Type.Object({ userId: Type.String() }),
      returnType: Type.Object({ id: Type.String(), name: Type.String() }),
    },
  },
  async (ctx, params /* typed as { userId: string } */) => {
    
    // returnType is inferred as { id: string; name: string }
    return { id: params.userId, name: 'John Doe' }
  },
)

// Call the procedure directly
const user = await GetUser({}, { userId: '123' })
// Or use the generic reference
const user2 = await procedure({}, { userId: '456' })

Features

• Core Procedures — Type-safe procedure definitions with Procedures(), Create, and CreateStream. Includes schema validation with TypeBox, error handling, generics, testing patterns, and the full API reference.

• Streaming — Async generator procedures with yield validation, abort signal integration, SSE examples, and stream error handling.

• HTTP Integrations — Express and Hono builders with lifecycle hooks, route documentation, DocRegistry for composing docs, and per-channel input validation.

• Client Code Generation — Generate type-safe client SDKs from your server's DocRegistry. CLI and programmatic API, adapters, hooks, streaming support, and self-contained mode.

• Typed Error Handling — Declarative defineErrorTaxonomy maps thrown error classes to HTTP responses across every builder; generated clients throw typed class instances you can catch with instanceof.

• Client Error Handling — Normalized framework error classes (ClientHttpError, ClientNetworkError, ClientTimeoutError, ClientAbortError, ClientParseError), .safe() Result API for exhaustive narrowing without try/catch, and augmentable ClientErrorMap for custom error categories.

• AI Agent Setup — Built-in configuration for Claude Code, Cursor, and GitHub Copilot. Auto-updates on npm install.

Full documentation is available on GitHub.

License

MIT