ts-procedures 5.2.0 → 5.3.0

package/agent_config/claude-code/skills/scaffold/templates/stream-procedure.md

@@ -0,0 +1,113 @@
+# Stream Procedure Template: {{Name}}
+
+## Implementation — `{{Name}}.stream.ts`
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { Type } from 'typebox'
+
+type AppContext = {
+  userId: string
+  signal?: AbortSignal
+}
+
+const { CreateStream } = Procedures<AppContext>()
+
+export const { {{Name}}, procedure: {{Name}}Procedure, info: {{Name}}Info } = CreateStream(
+  '{{Name}}',
+  {
+    description: 'TODO: describe what {{Name}} streams',
+    schema: {
+      params: Type.Object({
+        // TODO: define input parameters
+        channel: Type.String(),
+      }),
+      yieldType: Type.Object({
+        // TODO: define shape of each yielded value
+        id: Type.String(),
+        data: Type.Any(),
+        timestamp: Type.Number(),
+      }),
+    },
+    // Set to true to validate each yielded value against yieldType schema
+    // validateYields: false,
+  },
+  async function* (ctx, params) {
+    // ctx.signal is ALWAYS present in stream handlers (guaranteed AbortSignal)
+
+    // TODO: implement streaming logic
+    // Example: poll-based streaming
+    let counter = 0
+    while (!ctx.signal.aborted) {
+      const data = await fetchLatestData(params.channel, { signal: ctx.signal })
+
+      yield {
+        id: String(counter++),
+        data,
+        timestamp: Date.now(),
+      }
+
+      // Wait between polls (pass signal for cancellation)
+      await new Promise((resolve, reject) => {
+        const timeout = setTimeout(resolve, 1000)
+        ctx.signal.addEventListener('abort', () => {
+          clearTimeout(timeout)
+          resolve(undefined)
+        }, { once: true })
+      })
+    }
+
+    // After loop exits, signal.reason tells you why:
+    // - 'stream-completed': consumer finished reading (normal)
+    // - other: client disconnected or external abort
+  }
+)
+
+// Placeholder — replace with real data fetching
+async function fetchLatestData(channel: string, opts?: { signal?: AbortSignal }) {
+  return { value: Math.random() }
+}
+```
+
+## Test — `{{Name}}.stream.test.ts`
+
+```typescript
+import { describe, test, expect } from 'vitest'
+import { ProcedureValidationError } from 'ts-procedures'
+import { {{Name}} } from './{{Name}}.stream'
+
+const mockContext = { userId: 'test-user' }
+
+describe('{{Name}}', () => {
+  test('yields expected values', async () => {
+    const values = []
+    for await (const val of {{Name}}(mockContext, { channel: 'test' })) {
+      values.push(val)
+      if (values.length >= 3) break  // Don't consume indefinitely
+    }
+
+    expect(values).toHaveLength(3)
+    expect(values[0]).toHaveProperty('id')
+    expect(values[0]).toHaveProperty('data')
+    expect(values[0]).toHaveProperty('timestamp')
+  })
+
+  test('throws ProcedureValidationError for invalid params', async () => {
+    const gen = {{Name}}(mockContext, {} as any)
+    await expect(gen.next()).rejects.toThrow(ProcedureValidationError)
+  })
+
+  test('respects signal abort', async () => {
+    const ac = new AbortController()
+    const values = []
+
+    setTimeout(() => ac.abort(), 100)
+
+    for await (const val of {{Name}}({ ...mockContext, signal: ac.signal }, { channel: 'test' })) {
+      values.push(val)
+    }
+
+    expect(values.length).toBeGreaterThanOrEqual(0)
+  })
+})
+```

package/agent_config/copilot/copilot-instructions.md

@@ -0,0 +1,255 @@
+# ts-procedures Framework Reference
+
+You are assisting a developer using **ts-procedures**, a TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition.
+
+## Core Flow
+
+```
+Procedures<TContext, TExtendedConfig>(builder?)
+    ↓
+Create(name, config, handler)       → Standard async procedure
+CreateStream(name, config, handler) → Streaming async generator
+    ↓
+Returns: { [name]: handler, procedure: handler, info: metadata }
+```
+
+## Imports
+
+```typescript
+// Core
+import { Procedures } from 'ts-procedures'
+import type { TLocalContext, TStreamContext, TProcedureRegistration, TStreamProcedureRegistration } from 'ts-procedures'
+
+// Errors
+import { ProcedureError, ProcedureValidationError, ProcedureYieldValidationError, ProcedureRegistrationError } from 'ts-procedures'
+
+// HTTP types
+import type { RPCConfig, RPCHttpRouteDoc, StreamHttpRouteDoc, StreamMode } from 'ts-procedures/http'
+
+// Express RPC
+import { ExpressRPCAppBuilder } from 'ts-procedures/express-rpc'
+
+// Hono RPC
+import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'
+
+// Hono Streaming
+import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
+```
+
+## Architecture Rules
+
+1. **schema.params is validated at runtime; schema.returnType is documentation only.** Never expect returnType to be validated. Use TypeScript for return type safety.
+
+2. **Use ctx.error() for business logic errors.** Never throw raw `Error` instances. `ctx.error(message, meta?)` creates `ProcedureError` with procedure name, metadata, and enhanced stack trace.
+
+3. **Pass ctx.signal to all downstream async calls.** HTTP implementations inject AbortSignal automatically. Pass it to fetch, database queries, and other async operations for cancellation support.
+
+4. **Stream handlers always have ctx.signal (guaranteed AbortSignal).** Standard handlers get it when HTTP implementations provide it. Check `signal.reason === 'stream-completed'` to distinguish normal completion from client disconnect.
+
+5. **Use TypeBox for schemas** (`import { Type } from 'typebox'`). Plain JSON Schema objects are not recognized. AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`.
+
+6. **One factory per access level.** Separate `Procedures()` factories for public, authenticated, admin contexts.
+
+7. **onCreate callback enables framework integration.** Use for route registration, OpenAPI generation, logging.
+
+8. **getProcedures() for introspection.** Returns all registered procedures with metadata.
+
+## Procedure Pattern
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { Type } from 'typebox'
+
+type AppContext = { userId: string; signal?: AbortSignal }
+
+const { Create, CreateStream } = Procedures<AppContext>()
+
+// Standard procedure
+const { GetUser } = Create(
+  'GetUser',
+  {
+    description: 'Fetch user by ID',
+    schema: {
+      params: Type.Object({ id: Type.String() }),
+      returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+    },
+  },
+  async (ctx, params) => {
+    // params.id guaranteed string (AJV validated)
+    const user = await fetchUser(params.id, { signal: ctx.signal })
+    if (!user) throw ctx.error('Not found', { code: 'NOT_FOUND' })
+    return user
+  }
+)
+```
+
+## Stream Procedure Pattern
+
+```typescript
+const { StreamEvents } = CreateStream(
+  'StreamEvents',
+  {
+    schema: {
+      params: Type.Object({ channel: Type.String() }),
+      yieldType: Type.Object({ type: Type.String(), data: Type.Any() }),
+    },
+  },
+  async function* (ctx, params) {
+    // ctx.signal always present in streams
+    while (!ctx.signal.aborted) {
+      const event = await pollEvents(params.channel, { signal: ctx.signal })
+      yield event
+    }
+  }
+)
+```
+
+## Express RPC Pattern
+
+```typescript
+import { ExpressRPCAppBuilder } from 'ts-procedures/express-rpc'
+import type { RPCConfig } from 'ts-procedures/http'
+
+const RPC = Procedures<AppContext, RPCConfig>()
+
+RPC.Create('GetUser', {
+  scope: 'users', version: 1,
+  schema: { params: Type.Object({ id: Type.String() }) },
+}, async (ctx, params) => fetchUser(params.id))
+
+const app = new ExpressRPCAppBuilder({ pathPrefix: '/api' })
+  .register(RPC, async (req) => ({ userId: await authenticate(req) }))
+  .build()
+// POST /api/users/get-user/1
+```
+
+## Hono RPC Pattern
+
+```typescript
+import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'
+
+const app = new HonoRPCAppBuilder({ pathPrefix: '/api' })
+  .register(RPC, (c) => ({ userId: c.req.header('x-user-id') }))
+  .build()
+```
+
+## Hono Streaming Pattern
+
+```typescript
+import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
+
+const StreamRPC = Procedures<AppContext, RPCConfig>()
+
+StreamRPC.CreateStream('Feed', {
+  scope: 'events', version: 1,
+  schema: { params: Type.Object({ channel: Type.String() }) },
+}, async function* (ctx, params) {
+  while (!ctx.signal.aborted) {
+    const event = await poll({ signal: ctx.signal })
+    yield sse(event, { event: 'update' })
+  }
+})
+
+const app = new HonoStreamAppBuilder({ defaultStreamMode: 'sse' })
+  .register(StreamRPC, (c) => ({ userId: c.req.header('x-user-id') }))
+  .build()
+// GET|POST /events/feed/1
+```
+
+## Error Handling
+
+| Error Class | Trigger | HTTP Status |
+|-------------|---------|-------------|
+| `ProcedureValidationError` | Schema params validation failure | 400 |
+| `ProcedureError` | `ctx.error()` or unhandled handler exception | 422/500 |
+| `ProcedureYieldValidationError` | Yield validation failure (validateYields: true) | N/A (mid-stream) |
+| `ProcedureRegistrationError` | Invalid schema or duplicate name at registration | N/A (startup) |
+
+```typescript
+// In HTTP builder
+onError: (procedure, req, res, error) => {
+  if (error instanceof ProcedureValidationError) {
+    res.status(400).json({ error: error.message, details: error.errors })
+  } else if (error instanceof ProcedureError) {
+    res.status(422).json({ error: error.message, meta: error.meta })
+  } else {
+    res.status(500).json({ error: 'Internal server error' })
+  }
+}
+```
+
+## Lifecycle Hook Order
+
+### Standard RPC
+```
+onRequestStart → factoryContext() → handler() → onSuccess → onRequestEnd
+                                  → onError  → onRequestEnd
+```
+
+### Streaming
+```
+onRequestStart → factoryContext() → validation → onStreamStart → handler yields → onStreamEnd → onRequestEnd
+                                               → onPreStreamError → onRequestEnd
+                                                                  → onMidStreamError → onStreamEnd → onRequestEnd
+```
+
+## Decision Framework
+
+**Which procedure type?**
+- Single response → `Create`
+- Multiple values over time → `CreateStream`
+
+**Which schema library?**
+- **TypeBox** (`import { Type } from 'typebox'`)
+
+**Which HTTP implementation?**
+- Express → `ExpressRPCAppBuilder`
+- Hono (standard) → `HonoRPCAppBuilder`
+- Hono (streaming) → `HonoStreamAppBuilder`
+
+**Stream mode?**
+- Browser EventSource → `'sse'` (default)
+- Simple HTTP client → `'text'` (newline-delimited JSON)
+
+## Anti-Patterns — NEVER Do These
+
+1. **Never throw raw Error** — use `ctx.error(message, meta?)`
+2. **Never expect returnType runtime validation** — it's docs only
+3. **Never put validation logic in handler** — use `schema.params`
+4. **Never ignore ctx.signal** — pass to all async calls
+5. **Never skip signal.aborted check in stream loops** — causes resource leaks
+6. **Never register Create procedures with HonoStreamAppBuilder** — they're silently ignored
+7. **Never use plain JSON Schema objects** — use TypeBox builders
+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
+
+## Testing
+
+```typescript
+import { describe, test, expect } from 'vitest'
+import { ProcedureError, ProcedureValidationError } from 'ts-procedures'
+
+describe('GetUser', () => {
+  test('valid params', async () => {
+    const result = await GetUser(mockCtx, { id: 'user-1' })
+    expect(result.id).toBe('user-1')
+  })
+
+  test('invalid params', async () => {
+    await expect(GetUser(mockCtx, {})).rejects.toThrow(ProcedureValidationError)
+  })
+
+  test('business error', async () => {
+    await expect(GetUser(mockCtx, { id: 'missing' })).rejects.toThrow(ProcedureError)
+  })
+})
+```
+
+## HTTP Route Path Format
+
+`{pathPrefix}/{scope}/{kebab-case-name}/{version}`
+
+- `scope` can be string or string[] (joined as path segments)
+- Procedure name auto-converted to kebab-case
+- Stream routes support both GET (query params) and POST (JSON body)

package/agent_config/cursor/cursorrules

@@ -0,0 +1,255 @@
+# ts-procedures Framework Reference
+
+You are assisting a developer using **ts-procedures**, a TypeScript RPC framework that creates type-safe, schema-validated procedure calls with a single function definition.
+
+## Core Flow
+
+```
+Procedures<TContext, TExtendedConfig>(builder?)
+    ↓
+Create(name, config, handler)       → Standard async procedure
+CreateStream(name, config, handler) → Streaming async generator
+    ↓
+Returns: { [name]: handler, procedure: handler, info: metadata }
+```
+
+## Imports
+
+```typescript
+// Core
+import { Procedures } from 'ts-procedures'
+import type { TLocalContext, TStreamContext, TProcedureRegistration, TStreamProcedureRegistration } from 'ts-procedures'
+
+// Errors
+import { ProcedureError, ProcedureValidationError, ProcedureYieldValidationError, ProcedureRegistrationError } from 'ts-procedures'
+
+// HTTP types
+import type { RPCConfig, RPCHttpRouteDoc, StreamHttpRouteDoc, StreamMode } from 'ts-procedures/http'
+
+// Express RPC
+import { ExpressRPCAppBuilder } from 'ts-procedures/express-rpc'
+
+// Hono RPC
+import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'
+
+// Hono Streaming
+import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
+```
+
+## Architecture Rules
+
+1. **schema.params is validated at runtime; schema.returnType is documentation only.** Never expect returnType to be validated. Use TypeScript for return type safety.
+
+2. **Use ctx.error() for business logic errors.** Never throw raw `Error` instances. `ctx.error(message, meta?)` creates `ProcedureError` with procedure name, metadata, and enhanced stack trace.
+
+3. **Pass ctx.signal to all downstream async calls.** HTTP implementations inject AbortSignal automatically. Pass it to fetch, database queries, and other async operations for cancellation support.
+
+4. **Stream handlers always have ctx.signal (guaranteed AbortSignal).** Standard handlers get it when HTTP implementations provide it. Check `signal.reason === 'stream-completed'` to distinguish normal completion from client disconnect.
+
+5. **Use TypeBox for schemas** (`import { Type } from 'typebox'`). Plain JSON Schema objects are not recognized. AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`.
+
+6. **One factory per access level.** Separate `Procedures()` factories for public, authenticated, admin contexts.
+
+7. **onCreate callback enables framework integration.** Use for route registration, OpenAPI generation, logging.
+
+8. **getProcedures() for introspection.** Returns all registered procedures with metadata.
+
+## Procedure Pattern
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { Type } from 'typebox'
+
+type AppContext = { userId: string; signal?: AbortSignal }
+
+const { Create, CreateStream } = Procedures<AppContext>()
+
+// Standard procedure
+const { GetUser } = Create(
+  'GetUser',
+  {
+    description: 'Fetch user by ID',
+    schema: {
+      params: Type.Object({ id: Type.String() }),
+      returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+    },
+  },
+  async (ctx, params) => {
+    // params.id guaranteed string (AJV validated)
+    const user = await fetchUser(params.id, { signal: ctx.signal })
+    if (!user) throw ctx.error('Not found', { code: 'NOT_FOUND' })
+    return user
+  }
+)
+```
+
+## Stream Procedure Pattern
+
+```typescript
+const { StreamEvents } = CreateStream(
+  'StreamEvents',
+  {
+    schema: {
+      params: Type.Object({ channel: Type.String() }),
+      yieldType: Type.Object({ type: Type.String(), data: Type.Any() }),
+    },
+  },
+  async function* (ctx, params) {
+    // ctx.signal always present in streams
+    while (!ctx.signal.aborted) {
+      const event = await pollEvents(params.channel, { signal: ctx.signal })
+      yield event
+    }
+  }
+)
+```
+
+## Express RPC Pattern
+
+```typescript
+import { ExpressRPCAppBuilder } from 'ts-procedures/express-rpc'
+import type { RPCConfig } from 'ts-procedures/http'
+
+const RPC = Procedures<AppContext, RPCConfig>()
+
+RPC.Create('GetUser', {
+  scope: 'users', version: 1,
+  schema: { params: Type.Object({ id: Type.String() }) },
+}, async (ctx, params) => fetchUser(params.id))
+
+const app = new ExpressRPCAppBuilder({ pathPrefix: '/api' })
+  .register(RPC, async (req) => ({ userId: await authenticate(req) }))
+  .build()
+// POST /api/users/get-user/1
+```
+
+## Hono RPC Pattern
+
+```typescript
+import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'
+
+const app = new HonoRPCAppBuilder({ pathPrefix: '/api' })
+  .register(RPC, (c) => ({ userId: c.req.header('x-user-id') }))
+  .build()
+```
+
+## Hono Streaming Pattern
+
+```typescript
+import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
+
+const StreamRPC = Procedures<AppContext, RPCConfig>()
+
+StreamRPC.CreateStream('Feed', {
+  scope: 'events', version: 1,
+  schema: { params: Type.Object({ channel: Type.String() }) },
+}, async function* (ctx, params) {
+  while (!ctx.signal.aborted) {
+    const event = await poll({ signal: ctx.signal })
+    yield sse(event, { event: 'update' })
+  }
+})
+
+const app = new HonoStreamAppBuilder({ defaultStreamMode: 'sse' })
+  .register(StreamRPC, (c) => ({ userId: c.req.header('x-user-id') }))
+  .build()
+// GET|POST /events/feed/1
+```
+
+## Error Handling
+
+| Error Class | Trigger | HTTP Status |
+|-------------|---------|-------------|
+| `ProcedureValidationError` | Schema params validation failure | 400 |
+| `ProcedureError` | `ctx.error()` or unhandled handler exception | 422/500 |
+| `ProcedureYieldValidationError` | Yield validation failure (validateYields: true) | N/A (mid-stream) |
+| `ProcedureRegistrationError` | Invalid schema or duplicate name at registration | N/A (startup) |
+
+```typescript
+// In HTTP builder
+onError: (procedure, req, res, error) => {
+  if (error instanceof ProcedureValidationError) {
+    res.status(400).json({ error: error.message, details: error.errors })
+  } else if (error instanceof ProcedureError) {
+    res.status(422).json({ error: error.message, meta: error.meta })
+  } else {
+    res.status(500).json({ error: 'Internal server error' })
+  }
+}
+```
+
+## Lifecycle Hook Order
+
+### Standard RPC
+```
+onRequestStart → factoryContext() → handler() → onSuccess → onRequestEnd
+                                  → onError  → onRequestEnd
+```
+
+### Streaming
+```
+onRequestStart → factoryContext() → validation → onStreamStart → handler yields → onStreamEnd → onRequestEnd
+                                               → onPreStreamError → onRequestEnd
+                                                                  → onMidStreamError → onStreamEnd → onRequestEnd
+```
+
+## Decision Framework
+
+**Which procedure type?**
+- Single response → `Create`
+- Multiple values over time → `CreateStream`
+
+**Which schema library?**
+- **TypeBox** (`import { Type } from 'typebox'`)
+
+**Which HTTP implementation?**
+- Express → `ExpressRPCAppBuilder`
+- Hono (standard) → `HonoRPCAppBuilder`
+- Hono (streaming) → `HonoStreamAppBuilder`
+
+**Stream mode?**
+- Browser EventSource → `'sse'` (default)
+- Simple HTTP client → `'text'` (newline-delimited JSON)
+
+## Anti-Patterns — NEVER Do These
+
+1. **Never throw raw Error** — use `ctx.error(message, meta?)`
+2. **Never expect returnType runtime validation** — it's docs only
+3. **Never put validation logic in handler** — use `schema.params`
+4. **Never ignore ctx.signal** — pass to all async calls
+5. **Never skip signal.aborted check in stream loops** — causes resource leaks
+6. **Never register Create procedures with HonoStreamAppBuilder** — they're silently ignored
+7. **Never use plain JSON Schema objects** — use TypeBox builders
+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
+
+## Testing
+
+```typescript
+import { describe, test, expect } from 'vitest'
+import { ProcedureError, ProcedureValidationError } from 'ts-procedures'
+
+describe('GetUser', () => {
+  test('valid params', async () => {
+    const result = await GetUser(mockCtx, { id: 'user-1' })
+    expect(result.id).toBe('user-1')
+  })
+
+  test('invalid params', async () => {
+    await expect(GetUser(mockCtx, {})).rejects.toThrow(ProcedureValidationError)
+  })
+
+  test('business error', async () => {
+    await expect(GetUser(mockCtx, { id: 'missing' })).rejects.toThrow(ProcedureError)
+  })
+})
+```
+
+## HTTP Route Path Format
+
+`{pathPrefix}/{scope}/{kebab-case-name}/{version}`
+
+- `scope` can be string or string[] (joined as path segments)
+- Procedure name auto-converted to kebab-case
+- Stream routes support both GET (query params) and POST (JSON body)