ts-procedures 2.1.0 → 3.0.0

package/src/implementations/http/express-rpc/index.ts

@@ -6,6 +6,31 @@ import { castArray } from 'es-toolkit/compat'
 import { ExpressFactoryItem, ExtractContext, ProceduresFactory } from './types.js'
 
 export type { RPCConfig, RPCHttpRouteDoc }
+
+export type ExpressRPCAppBuilderConfig = {
+  /**
+   * An existing Express application instance to use.
+   * When provided, ensure to set up necessary middleware (e.g., json/body parser) beforehand.
+   * If not provided, a new instance will be created.
+   */
+  app?: express.Express
+  /** Optional path prefix for all RPC routes. */
+  pathPrefix?: string
+  onRequestStart?: (req: express.Request) => void
+  onRequestEnd?: (req: express.Request, res: express.Response) => void
+  onSuccess?: (
+    procedure: TProcedureRegistration,
+    req: express.Request,
+    res: express.Response
+  ) => void
+  error?: (
+    procedure: TProcedureRegistration,
+    req: express.Request,
+    res: express.Response,
+    error: Error
+  ) => void
+}
+
 /**
  * Builder class for creating an Express application with RPC routes.
  *
@@ -27,29 +52,7 @@ export class ExpressRPCAppBuilder {
    *
    * @param config
    */
-  constructor(
-    readonly config?: {
-      /**
-       * An existing Express application instance to use.
-       * When provided, ensure to set up necessary middleware (e.g., json/body parser) beforehand.
-       * If not provided, a new instance will be created.
-       */
-      app?: express.Express
-      onRequestStart?: (req: express.Request) => void
-      onRequestEnd?: (req: express.Request, res: express.Response) => void
-      onSuccess?: (
-        procedure: TProcedureRegistration,
-        req: express.Request,
-        res: express.Response
-      ) => void
-      error?: (
-        procedure: TProcedureRegistration,
-        req: express.Request,
-        res: express.Response,
-        error: Error
-      ) => void
-    }
-  ) {
+  constructor(readonly config?: ExpressRPCAppBuilderConfig) {
     if (config?.app) {
       this._app = config.app
     } else {
@@ -74,6 +77,41 @@ export class ExpressRPCAppBuilder {
     }
   }
 
+  /**
+   * Generates the RPC route path based on the RPC configuration.
+   * The RPCConfig name can be a string or an array of strings to form nested paths.
+   *
+   * Example
+   *  name: ['string', 'string-string', 'string']
+   *  path: /string/string-string/string/version
+   * @param config
+   */
+  static makeRPCHttpRoutePath({
+    name,
+    config,
+    prefix,
+  }: {
+    name: string
+    prefix?: string
+    config: RPCConfig
+  }) {
+    const normalizedPrefix = prefix ? (prefix.startsWith('/') ? prefix : `/${prefix}`) : ''
+
+    return `${normalizedPrefix}/${castArray(config.scope).map(kebabCase).join('/')}/${kebabCase(name)}/${String(config.version).trim()}`
+  }
+
+  /**
+   * Instance method wrapper for makeRPCHttpRoutePath that uses the builder's pathPrefix.
+   * @param config - The RPC configuration
+   */
+  makeRPCHttpRoutePath(name: string, config: RPCConfig): string {
+    return ExpressRPCAppBuilder.makeRPCHttpRoutePath({
+      name,
+      config,
+      prefix: this.config?.pathPrefix,
+    })
+  }
+
   private factories: ExpressFactoryItem<any>[] = []
 
   private _app: express.Express = express()
@@ -153,9 +191,13 @@ export class ExpressRPCAppBuilder {
    * Generates the RPC HTTP route for the given procedure.
    * @param procedure
    */
-  buildRpcHttpRouteDoc(procedure: TProcedureRegistration<any, RPCConfig>): RPCHttpRouteDoc {
+  private buildRpcHttpRouteDoc(procedure: TProcedureRegistration<any, RPCConfig>): RPCHttpRouteDoc {
     const { config } = procedure
-    const path = this.makeRPCHttpRoutePath(config)
+    const path = ExpressRPCAppBuilder.makeRPCHttpRoutePath({
+      name: procedure.name,
+      config,
+      prefix: this.config?.pathPrefix,
+    })
     const method = 'post' // RPCs use POST method
     const jsonSchema: { body?: object; response?: object } = {}
 
@@ -172,17 +214,4 @@ export class ExpressRPCAppBuilder {
       jsonSchema,
     }
   }
-
-  /**
-   * Generates the RPC route path based on the RPC configuration.
-   * The RPCConfig name can be a string or an array of strings to form nested paths.
-   *
-   * Example
-   *  name: ['string', 'string-string', 'string']
-   *  path: /rpc/string/string-string/string/version
-   * @param config
-   */
-  makeRPCHttpRoutePath(config: RPCConfig) {
-    return `/rpc/${castArray(config.name).map(kebabCase).join('/')}/${String(config.version).trim()}`
-  }
 }

package/src/implementations/http/hono-rpc/README.md

@@ -0,0 +1,293 @@
+# HonoRPCAppBuilder
+
+Hono integration for `ts-procedures` that creates type-safe RPC endpoints as POST routes. Works with Bun, Deno, Cloudflare Workers, and Node.js.
+
+## Installation
+
+```bash
+npm install ts-procedures hono
+```
+
+## Quick Start
+
+```typescript
+import { Hono } from 'hono'
+import { Procedures } from 'ts-procedures'
+import { HonoRPCAppBuilder, RPCConfig } from 'ts-procedures/implementations/http/hono-rpc'
+import { v } from 'suretype'
+
+// Define your context type
+type AppContext = { userId: string }
+
+// Create a procedure factory
+const RPC = Procedures<AppContext, RPCConfig>()
+
+// Define procedures
+RPC.Create(
+  'GetUser',
+  {
+    scope: ['users', 'profile'],
+    version: 1,
+    schema: {
+      params: v.object({ id: v.string() }),
+      returnType: v.object({ id: v.string(), name: v.string() })
+    }
+  },
+  async (ctx, params) => {
+    return { id: params.id, name: 'John Doe' }
+  }
+)
+
+// Build the Hono app
+const builder = new HonoRPCAppBuilder({ pathPrefix: '/rpc' })
+  .register(RPC, (c) => ({
+    userId: c.req.header('x-user-id') || 'anonymous'
+  }))
+
+const app = builder.build()
+
+// Bun
+export default app
+
+// Node.js
+// import { serve } from '@hono/node-server'
+// serve(app)
+
+// POST /rpc/users/profile/get-user/1 → { id: "123", name: "John Doe" }
+```
+
+## Configuration
+
+```typescript
+type HonoRPCAppBuilderConfig = {
+  app?: Hono                 // Existing Hono app (optional)
+  pathPrefix?: string        // Prefix for all routes (e.g., '/rpc/v1')
+  onRequestStart?: (c: Context) => void
+  onRequestEnd?: (c: Context) => void
+  onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
+  error?: (procedure: TProcedureRegistration, c: Context, error: Error) => Response | Promise<Response>
+}
+```
+
+| Option | Type | Description                                       |
+|--------|------|---------------------------------------------------|
+| `app` | `Hono` | Use existing Hono app instead of creating new one |
+| `pathPrefix` | `string` | Prefix all routes (e.g., `/rpc/v1`)               |
+| `onRequestStart` | `(c) => void` | Called at start of each request                   |
+| `onRequestEnd` | `(c) => void` | Called after handler completes                    |
+| `onSuccess` | `(proc, c) => void` | Called on successful handler execution            |
+| `error` | `(proc, c, err) => Response` | Custom error handler (must return Response)       |
+
+## Context Resolution
+
+The context resolver receives the Hono `Context` object:
+
+```typescript
+builder.register(RPC, (c: Context) => ({
+  userId: c.req.header('x-user-id') || 'anonymous',
+  userAgent: c.req.header('user-agent'),
+  ip: c.req.raw.headers.get('cf-connecting-ip')  // Cloudflare
+}))
+
+// Async context resolution
+builder.register(RPC, async (c) => {
+  const token = c.req.header('authorization')?.replace('Bearer ', '')
+  const user = await verifyToken(token)
+  return { userId: user.id, roles: user.roles }
+})
+```
+
+## Error Handling
+
+Custom error handler receives the procedure, context, and error. **Must return a Response:**
+
+```typescript
+const builder = new HonoRPCAppBuilder({
+  error: (procedure, c, error) => {
+    console.error(`Error in ${procedure.name}:`, error)
+
+    if (error instanceof ValidationError) {
+      return c.json({ error: error.message, code: 'VALIDATION_ERROR' }, 400)
+    }
+
+    if (error instanceof AuthError) {
+      return c.json({ error: 'Unauthorized', code: 'AUTH_ERROR' }, 401)
+    }
+
+    return c.json({ error: 'Internal server error' }, 500)
+  }
+})
+```
+
+**Default error handling:** Returns `{ error: message }` with status 500.
+
+## Using Existing Hono App
+
+You can add RPC routes to an existing Hono application:
+
+```typescript
+const app = new Hono()
+
+// Add custom middleware and routes
+app.use('*', cors())
+app.get('/custom', (c) => c.json({ custom: true }))
+
+const builder = new HonoRPCAppBuilder({ app })
+  .register(RPC, contextResolver)
+
+builder.build()  // Adds RPC routes to existing app
+```
+
+## Runtime Compatibility
+
+HonoRPCAppBuilder works across all Hono-supported runtimes:
+
+### Bun
+
+```typescript
+const app = builder.build()
+export default app
+```
+
+### Node.js
+
+```typescript
+import { serve } from '@hono/node-server'
+
+const app = builder.build()
+serve(app)
+```
+
+### Deno
+
+```typescript
+import { serve } from 'https://deno.land/std/http/server.ts'
+
+const app = builder.build()
+serve(app.fetch)
+```
+
+### Cloudflare Workers
+
+```typescript
+const app = builder.build()
+export default app
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new HonoRPCAppBuilder(config?: HonoRPCAppBuilderConfig)
+```
+
+### Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `register` | `register<T>(factory, context): this` | Register procedure factory with context |
+| `build` | `build(): Hono` | Build routes and return app |
+| `makeRPCHttpRoutePath` | `makeRPCHttpRoutePath(config: RPCConfig): string` | Generate route path |
+
+### Static Methods
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `makeRPCHttpRoutePath` | `static makeRPCHttpRoutePath({ config, prefix }): string` | Generate route path with custom prefix |
+
+### Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `app` | `Hono` | The Hono application instance |
+| `docs` | `RPCHttpRouteDoc[]` | Route documentation (after `build()`) |
+| `config` | `HonoRPCAppBuilderConfig` | The configuration object |
+
+## TypeScript Types
+
+```typescript
+import {
+  HonoRPCAppBuilder,
+  HonoRPCAppBuilderConfig,
+  RPCConfig,
+  RPCHttpRouteDoc
+} from 'ts-procedures/implementations/http/hono-rpc'
+```
+
+## Full Example
+
+```typescript
+import { Hono, Context } from 'hono'
+import { Procedures } from 'ts-procedures'
+import { HonoRPCAppBuilder, RPCConfig } from 'ts-procedures/implementations/http/hono-rpc'
+import { v } from 'suretype'
+
+// Context types
+type PublicContext = { source: 'public' }
+type AuthContext = { source: 'auth'; userId: string }
+
+// Create factories
+const PublicRPC = Procedures<PublicContext, RPCConfig>()
+const AuthRPC = Procedures<AuthContext, RPCConfig>()
+
+// Public procedures
+PublicRPC.Create('HealthCheck', { scope: 'health', version: 1 }, async () => ({
+  status: 'ok'
+}))
+
+PublicRPC.Create('GetVersion', { scope: ['system', 'version'], version: 1 }, async () => ({
+  version: '1.0.0'
+}))
+
+// Authenticated procedures
+AuthRPC.Create(
+  'GetProfile',
+  {
+    scope: ['users', 'profile'],
+    version: 1,
+    schema: { returnType: v.object({ userId: v.string() }) }
+  },
+  async (ctx) => ({ userId: ctx.userId })
+)
+
+AuthRPC.Create(
+  'UpdateProfile',
+  {
+    scope: ['users', 'profile'],
+    version: 2,
+    schema: { params: v.object({ name: v.string() }) }
+  },
+  async (ctx, params) => ({ userId: ctx.userId, name: params.name })
+)
+
+// Build app
+const builder = new HonoRPCAppBuilder({
+  pathPrefix: '/rpc',
+  onRequestStart: (c) => console.log(`→ ${c.req.method} ${c.req.path}`),
+  onRequestEnd: (c) => console.log(`← completed`),
+  onSuccess: (proc) => console.log(`✓ ${proc.name}`),
+  error: (proc, c, err) => {
+    console.error(`✗ ${proc.name}:`, err.message)
+    return c.json({ error: err.message }, 500)
+  }
+})
+
+builder
+  .register(PublicRPC, () => ({ source: 'public' as const }))
+  .register(AuthRPC, (c) => ({
+    source: 'auth' as const,
+    userId: c.req.header('x-user-id') || 'anonymous'
+  }))
+
+const app = builder.build()
+
+// Generated routes:
+// POST /rpc/health/1
+// POST /rpc/system/version/get-version/1
+// POST /rpc/users/profile/get-user/1
+// POST /rpc/users/profile/get-user/2
+
+console.log('Routes:', builder.docs.map(d => d.path))
+export default app
+```