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' })

v8 Migration — Unified HonoAppBuilder

The three Hono builders (HonoRPCAppBuilder, HonoAPIAppBuilder, HonoStreamAppBuilder) are replaced in v8 by a single HonoAppBuilder that accepts any Procedures<>() factory and dispatches all four procedure kinds (rpc, rpc-stream, http, http-stream) by procedure.kind from a single register() call.

// Before (v7)
const rpc = new HonoRPCAppBuilder({ app, errors }).register(F1, ctx1)
const api = new HonoAPIAppBuilder({ app, errors, queryParser }).register(F2, ctx2)
const stream = new HonoStreamAppBuilder({ app, errors, onMidStreamError }).register(F3, ctx3)

// After (v8)
const builder = new HonoAppBuilder({
  app,
  errors,
  api: { queryParser },
  stream: { onMidStreamError },
}).register(F1, ctx1).register(F2, ctx2).register(F3, ctx3)

Kind-specific config knobs are stratified into rpc.*, api.*, and stream.* blocks. Single-app users can call builder.toDocEnvelope() directly (no DocRegistry needed). DocRegistry remains for multi-app aggregation.

Subpath imports change from ts-procedures/hono-rpc, ts-procedures/hono-api, ts-procedures/hono-stream to ts-procedures/hono.

HTTP Routes (v8) — CreateHttp

v8 introduces CreateHttp and CreateHttpStream as first-class HTTP creators. HTTP fields (path, method, scope, errors) live on the creator config directly; no factory type parameter is required.

import { Procedures } from 'ts-procedures'
import { HonoAppBuilder } from 'ts-procedures/hono'
import { Type } from 'typebox'

type AppContext = { userId: string }
const API = Procedures<AppContext>()

// Input channels: pathParams, query, body, headers (schema.req)
// Response: schema.res.body (docs) + schema.res.headers (makes handler return { body, headers })
API.CreateHttp('GetUser', {
  path: '/users/:id',
  method: 'get',
  schema: {
    req: { pathParams: Type.Object({ id: Type.String() }) },
    res: { body: Type.Object({ id: Type.String(), name: Type.String() }) },
  },
}, async (ctx, { pathParams }) => fetchUser(pathParams.id))

API.CreateHttp('CreateUser', {
  path: '/users',
  method: 'post',
  schema: {
    req: { body: Type.Object({ name: Type.String(), email: Type.String() }) },
  },
}, async (ctx, { body }) => createUser(body))

const app = new HonoAppBuilder({ pathPrefix: '/api' })
  .register(API, (c) => ({ userId: c.req.header('x-user-id') || 'anonymous' }))
  .build()
// GET /api/users/:id → 200, POST /api/users → 201

Migrating from v7? Replace Procedures<Ctx, APIConfig>() → Procedures<Ctx>(), .Create( → .CreateHttp(, and schema.input → schema.req. Then re-run npx ts-procedures-codegen. See CHANGELOG.md for the full breaking-changes list.

Features

• Core Procedures — Type-safe procedure definitions with Procedures(), Create, CreateHttp, 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. CreateHttpStream supports response headers via TypedStream.headers.

• HTTP Integrations — HonoAppBuilder with lifecycle hooks, route documentation, DocRegistry for composing docs, and per-channel input validation via schema.req.

• 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