ts-procedures 5.3.0 → 5.4.0

package/agent_config/claude-code/skills/scaffold/templates/hono-api.md

@@ -0,0 +1,169 @@
+# Hono API Template: {{Name}}
+
+## Implementation — `{{Name}}.api.ts`
+
+```typescript
+import { Procedures, ProcedureError, ProcedureValidationError } from 'ts-procedures'
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import type { APIConfig, APIInput } from 'ts-procedures/http'
+import { Type } from 'typebox'
+
+// ─── Context ──────────────────────────────────────────────
+
+type {{Name}}Context = {
+  userId: string
+  requestId: string
+}
+
+// ─── Procedures ───────────────────────────────────────────
+
+const API = Procedures<{{Name}}Context, APIConfig>()
+
+export const { GetItem } = API.Create(
+  'GetItem',
+  {
+    path: '/{{name}}/:id',  // TODO: set route path
+    method: 'get',
+    description: 'Fetch item by ID',
+    schema: {
+      input: {
+        pathParams: Type.Object({ id: Type.String() }),
+      } satisfies APIInput,
+      returnType: Type.Object({
+        id: Type.String(),
+        name: Type.String(),
+      }),
+    },
+  },
+  async (ctx, { pathParams }) => {
+    // TODO: implement
+    return { id: pathParams.id, name: 'Example' }
+  }
+)
+
+export const { CreateItem } = API.Create(
+  'CreateItem',
+  {
+    path: '/{{name}}',
+    method: 'post',
+    description: 'Create a new item',
+    schema: {
+      input: {
+        body: Type.Object({
+          name: Type.String(),
+        }),
+      } satisfies APIInput,
+      returnType: Type.Object({
+        id: Type.String(),
+        name: Type.String(),
+      }),
+    },
+  },
+  async (ctx, { body }) => {
+    // TODO: implement
+    return { id: 'new-id', name: body.name }
+  }
+)
+
+export const { DeleteItem } = API.Create(
+  'DeleteItem',
+  {
+    path: '/{{name}}/:id',
+    method: 'delete',
+    schema: {
+      input: {
+        pathParams: Type.Object({ id: Type.String() }),
+      } satisfies APIInput,
+    },
+  },
+  async (ctx, { pathParams }) => {
+    // TODO: implement deletion
+  }
+)
+
+// ─── Hono App Builder ─────────────────────────────────────
+
+export const {{name}}App = await new HonoAPIAppBuilder({
+  pathPrefix: '/api',
+  onError: (procedure, c, error) => {
+    if (error instanceof ProcedureValidationError) {
+      return c.json({
+        error: error.message,
+        details: error.errors,
+        procedure: error.procedureName,
+      }, 400)
+    } else if (error instanceof ProcedureError) {
+      return c.json({
+        error: error.message,
+        meta: error.meta,
+        procedure: error.procedureName,
+      }, 422)
+    }
+    return c.json({ error: 'Internal server error' }, 500)
+  },
+})
+  .register(API, (c) => ({
+    userId: c.req.header('x-user-id') || 'anonymous',
+    requestId: c.req.header('x-request-id') || crypto.randomUUID(),
+  }))
+  .build()
+
+// Route map:
+// GET    /api/{{name}}/:id → 200
+// POST   /api/{{name}}     → 201
+// DELETE /api/{{name}}/:id → 204
+
+// Documentation: builder.docs (access before .build() resolves)
+```
+
+## Test — `{{Name}}.api.test.ts`
+
+```typescript
+import { describe, test, expect } from 'vitest'
+import { {{name}}App } from './{{Name}}.api'
+
+describe('{{Name}} API', () => {
+  test('GET item returns expected result', async () => {
+    const app = await {{name}}App
+    const res = await app.request('/api/{{name}}/item-1')
+
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body).toEqual({ id: 'item-1', name: 'Example' })
+  })
+
+  test('POST item returns 201', async () => {
+    const app = await {{name}}App
+    const res = await app.request('/api/{{name}}', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name: 'New Item' }),
+    })
+
+    expect(res.status).toBe(201)
+    const body = await res.json()
+    expect(body).toHaveProperty('id')
+    expect(body.name).toBe('New Item')
+  })
+
+  test('DELETE item returns 204', async () => {
+    const app = await {{name}}App
+    const res = await app.request('/api/{{name}}/item-1', {
+      method: 'DELETE',
+    })
+
+    expect(res.status).toBe(204)
+  })
+
+  test('returns 400 for invalid POST body', async () => {
+    const app = await {{name}}App
+    const res = await app.request('/api/{{name}}', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    })
+
+    expect(res.status).toBe(400)
+  })
+})
+```

package/agent_config/copilot/copilot-instructions.md

@@ -34,6 +34,10 @@ import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'
 
 // Hono Streaming
 import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
+
+// Hono API (REST-style)
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import type { APIConfig, APIInput } from 'ts-procedures/hono-api'
 ```
 
 ## Architecture Rules
@@ -156,6 +160,34 @@ const app = new HonoStreamAppBuilder({ defaultStreamMode: 'sse' })
 // GET|POST /events/feed/1
 ```
 
+## Hono API Pattern (REST-style)
+
+```typescript
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import type { APIConfig } from 'ts-procedures/http'
+
+const API = Procedures<AppContext, APIConfig>()
+
+API.Create('GetUser', {
+  path: '/users/:id', method: 'get',
+  schema: {
+    input: { pathParams: Type.Object({ id: Type.String() }) },
+  },
+}, async (ctx, { pathParams }) => fetchUser(pathParams.id))
+
+API.Create('CreateUser', {
+  path: '/users', method: 'post',
+  schema: {
+    input: { body: Type.Object({ name: Type.String() }) },
+  },
+}, async (ctx, { body }) => createUser(body))
+
+const app = await new HonoAPIAppBuilder({ pathPrefix: '/api' })
+  .register(API, (c) => ({ userId: c.req.header('x-user-id') }))
+  .build()
+// GET /api/users/:id → 200, POST /api/users → 201
+```
+
 ## Error Handling
 
 | Error Class | Trigger | HTTP Status |
@@ -206,6 +238,7 @@ onRequestStart → factoryContext() → validation → onStreamStart → handler
 - Express → `ExpressRPCAppBuilder`
 - Hono (standard) → `HonoRPCAppBuilder`
 - Hono (streaming) → `HonoStreamAppBuilder`
+- Hono (REST-style, per-channel input) → `HonoAPIAppBuilder`
 
 **Stream mode?**
 - Browser EventSource → `'sse'` (default)
@@ -223,6 +256,8 @@ onRequestStart → factoryContext() → validation → onStreamStart → handler
 8. **Never swallow errors without re-throwing** — hides failures
 9. **Never assume extra params fields survive** — `removeAdditional: true` strips them
 10. **Never manually parse types AJV coerces** — `coerceTypes: true` handles it
+11. **Never define both schema.params and schema.input** — mutually exclusive, throws ProcedureRegistrationError
+12. **Never forget to await HonoAPIAppBuilder.build()** — it's async (resolves query parser)
 
 ## Testing
 

package/agent_config/cursor/cursorrules

@@ -34,6 +34,10 @@ import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'
 
 // Hono Streaming
 import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
+
+// Hono API (REST-style)
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import type { APIConfig, APIInput } from 'ts-procedures/hono-api'
 ```
 
 ## Architecture Rules
@@ -156,6 +160,34 @@ const app = new HonoStreamAppBuilder({ defaultStreamMode: 'sse' })
 // GET|POST /events/feed/1
 ```
 
+## Hono API Pattern (REST-style)
+
+```typescript
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import type { APIConfig } from 'ts-procedures/http'
+
+const API = Procedures<AppContext, APIConfig>()
+
+API.Create('GetUser', {
+  path: '/users/:id', method: 'get',
+  schema: {
+    input: { pathParams: Type.Object({ id: Type.String() }) },
+  },
+}, async (ctx, { pathParams }) => fetchUser(pathParams.id))
+
+API.Create('CreateUser', {
+  path: '/users', method: 'post',
+  schema: {
+    input: { body: Type.Object({ name: Type.String() }) },
+  },
+}, async (ctx, { body }) => createUser(body))
+
+const app = await new HonoAPIAppBuilder({ pathPrefix: '/api' })
+  .register(API, (c) => ({ userId: c.req.header('x-user-id') }))
+  .build()
+// GET /api/users/:id → 200, POST /api/users → 201
+```
+
 ## Error Handling
 
 | Error Class | Trigger | HTTP Status |
@@ -206,6 +238,7 @@ onRequestStart → factoryContext() → validation → onStreamStart → handler
 - Express → `ExpressRPCAppBuilder`
 - Hono (standard) → `HonoRPCAppBuilder`
 - Hono (streaming) → `HonoStreamAppBuilder`
+- Hono (REST-style, per-channel input) → `HonoAPIAppBuilder`
 
 **Stream mode?**
 - Browser EventSource → `'sse'` (default)
@@ -223,6 +256,8 @@ onRequestStart → factoryContext() → validation → onStreamStart → handler
 8. **Never swallow errors without re-throwing** — hides failures
 9. **Never assume extra params fields survive** — `removeAdditional: true` strips them
 10. **Never manually parse types AJV coerces** — `coerceTypes: true` handles it
+11. **Never define both schema.params and schema.input** — mutually exclusive, throws ProcedureRegistrationError
+12. **Never forget to await HonoAPIAppBuilder.build()** — it's async (resolves query parser)
 
 ## Testing
 

package/build/implementations/http/hono-api/index.d.ts

@@ -0,0 +1,102 @@
+import { Hono, Context } from 'hono';
+import { TProcedureRegistration } from '../../../index.js';
+import { ExtractConfig, ExtractContext, ProceduresFactory, APIConfig, APIHttpRouteDoc, APIInput, HttpMethod } from '../../types.js';
+export type { APIConfig, APIHttpRouteDoc, APIInput, HttpMethod };
+export type QueryParser = (queryString: string) => Record<string, unknown>;
+export type HonoAPIAppBuilderConfig = {
+    /**
+     * An existing Hono application instance to use.
+     * If not provided, a new instance will be created.
+     */
+    app?: Hono;
+    /** Optional path prefix for all API routes. */
+    pathPrefix?: string;
+    /**
+     * Custom query string parser. Receives the raw query string (without '?').
+     * Default: uses `qs` (optional peer dependency) if available, otherwise native URLSearchParams.
+     */
+    queryParser?: QueryParser;
+    onRequestStart?: (c: Context) => void;
+    onRequestEnd?: (c: Context) => void;
+    onSuccess?: (procedure: TProcedureRegistration, c: Context) => void;
+    /**
+     * Error handler called when a procedure throws an error.
+     */
+    onError?: (procedure: TProcedureRegistration, c: Context, error: Error) => Response | Promise<Response>;
+};
+/**
+ * Builder class for creating a Hono application with REST-style API routes.
+ *
+ * Uses `schema.input` for per-channel type safety:
+ *   - `input.pathParams` → validated path parameters
+ *   - `input.query` → validated query string parameters
+ *   - `input.body` → validated request body
+ *   - `input.headers` → validated request headers
+ *
+ * Usage:
+ *   const API = Procedures<MyContext, APIConfig>()
+ *
+ *   API.Create('GetUser', {
+ *     path: '/users/:id',
+ *     method: 'get',
+ *     schema: {
+ *       input: {
+ *         pathParams: Type.Object({ id: Type.String() }),
+ *         query: Type.Object({ include: Type.Optional(Type.String()) }),
+ *       },
+ *       returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+ *     }
+ *   }, async (ctx, { pathParams, query }) => {
+ *     return { id: pathParams.id, name: 'John' }
+ *   })
+ *
+ *   const apiApp = new HonoAPIAppBuilder()
+ *     .register(API, (c) => ({ ... }))
+ *     .build()
+ */
+export declare class HonoAPIAppBuilder {
+    readonly config?: HonoAPIAppBuilderConfig | undefined;
+    constructor(config?: HonoAPIAppBuilderConfig | undefined);
+    private factories;
+    private _app;
+    private _docs;
+    get app(): Hono;
+    get docs(): APIHttpRouteDoc[];
+    /**
+     * Registers a procedure factory with its context.
+     * @param factory - The procedure factory created by Procedures<Context, APIConfig>()
+     * @param factoryContext - Context for handlers. Direct value, sync function, or async function.
+     * @param extendProcedureDoc - Custom function to extend the generated route documentation.
+     */
+    register<TFactory extends ProceduresFactory>(factory: TFactory, factoryContext: ExtractContext<TFactory> | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>), extendProcedureDoc?: (params: {
+        base: APIHttpRouteDoc;
+        procedure: TProcedureRegistration<any, ExtractConfig<TFactory>>;
+    }) => Record<string, any>): this;
+    /**
+     * Resolves the full path for a route, combining pathPrefix and the procedure's path.
+     */
+    private resolveFullPath;
+    /**
+     * Builds and returns the Hono application with registered API routes.
+     * Async because it resolves the query parser (qs optional peer dep) once at build time.
+     */
+    build(): Promise<Hono>;
+    /**
+     * Validates that path parameter names in the path template match the schema.input.pathParams declaration.
+     */
+    private validatePathParamConsistency;
+    /**
+     * Creates the async route handler for a procedure.
+     */
+    private createRouteHandler;
+    /**
+     * Extracts and assembles structured input params from HTTP request sources.
+     * Each channel (pathParams, query, body, headers) is extracted from its HTTP source.
+     * The core validates each channel independently via schema.input validators.
+     */
+    private extractInputParams;
+    /**
+     * Generates the API HTTP route documentation for the given procedure.
+     */
+    private buildApiHttpRouteDoc;
+}