ts-procedures 5.2.0 → 5.3.0

package/agent_config/claude-code/skills/guide/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: guide
+description: "ts-procedures framework reference — core API, schema validation, error classes, context shape, HTTP implementations, and decision framework. Auto-loaded when ts-procedures imports are detected."
+invocable_by:
+  - model
+---
+
+# 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. Always follow these rules when writing or reviewing code.
+
+## 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 }
+```
+
+## Factory API
+
+```typescript
+const { Create, CreateStream, getProcedures, getProcedure, removeProcedure, clear } =
+  Procedures<TContext, TExtendedConfig>({
+    onCreate: (procedure) => { /* called on each registration */ }
+  })
+```
+
+| Method | Purpose |
+|--------|---------|
+| `Create(name, config, handler)` | Register standard async procedure |
+| `CreateStream(name, config, handler)` | Register streaming procedure (async generator) |
+| `getProcedures()` | Returns array of all registered procedures |
+| `getProcedure(name)` | Get single procedure by name |
+| `removeProcedure(name)` | Remove procedure by name |
+| `clear()` | Remove all procedures |
+
+## Context
+
+Handlers receive `(ctx, params)` where ctx includes:
+
+| Property | Type | Availability |
+|----------|------|-------------|
+| Base context fields | `TContext` | Always |
+| `error(message, meta?)` | `(string, object?) => ProcedureError` | Always |
+| `signal` | `AbortSignal` | **Guaranteed** in CreateStream; optional in Create (present when HTTP impl provides it) |
+| `isPrevalidated` | `boolean` | Set by HTTP impls to skip redundant validation |
+
+## Schema System
+
+Uses **TypeBox** for schema definitions (`import { Type } from 'typebox'`):
+
+| Library | Detection | Example |
+|---------|-----------|---------|
+| **TypeBox** | `~kind` symbol | `Type.Object({ name: Type.String() })` |
+
+### Validation Rules
+
+- `schema.params` — **Validated at runtime** via AJV
+- `schema.returnType` — **Documentation only**, never validated
+- `schema.yieldType` — Validated only if `validateYields: true` in CreateStream config
+- AJV config: `allErrors: true`, `coerceTypes: true`, `removeAdditional: true`
+
+## Error Classes
+
+| Error Class | Trigger | Key Properties |
+|-------------|---------|----------------|
+| `ProcedureError` | `ctx.error()` in handlers, or unhandled handler exceptions | `procedureName`, `message`, `meta`, `cause`, `definedAt` |
+| `ProcedureValidationError` | Schema params validation failure | `procedureName`, `errors[]` (AJV errors) |
+| `ProcedureYieldValidationError` | Stream yield validation failure | `procedureName`, `errors[]` (AJV errors) |
+| `ProcedureRegistrationError` | Invalid schema at registration time | `procedureName`, `message` |
+
+All errors include `definedAt` (file:line:column) and enhanced stack traces pointing to the procedure definition location.
+
+## HTTP Implementations
+
+| Builder | Import | Transport |
+|---------|--------|-----------|
+| `ExpressRPCAppBuilder` | `ts-procedures/express-rpc` | POST JSON |
+| `HonoRPCAppBuilder` | `ts-procedures/hono-rpc` | POST JSON |
+| `HonoStreamAppBuilder` | `ts-procedures/hono-stream` | SSE or newline-delimited JSON |
+
+### Route Path Format
+
+```
+{pathPrefix}/{scope}/{kebab-case-name}/{version}
+```
+
+Example: `Create('GetUser', { scope: 'users', version: 1 }, ...)` → `POST /users/get-user/1`
+
+### Builder Pattern
+
+```typescript
+const app = new ExpressRPCAppBuilder({ pathPrefix: '/api' })
+  .register(factory, (req) => ({ /* context */ }))
+  .build()
+```
+
+### Lifecycle Hooks (HTTP builders)
+
+| Hook | When |
+|------|------|
+| `onRequestStart` | Before context resolution |
+| `onRequestEnd` | After response sent |
+| `onSuccess` | After successful handler execution |
+| `onError` | On handler error (return custom response) |
+| `onStreamStart` | Before first yield (HonoStreamAppBuilder) |
+| `onStreamEnd` | After stream closes (HonoStreamAppBuilder) |
+| `onPreStreamError` | Validation/context error before streaming starts |
+| `onMidStreamError` | Error during streaming (return data to yield as final event) |
+
+## Decision Framework
+
+**Which procedure type?**
+- Request → single response → **Create**
+- Request → multiple values over time → **CreateStream**
+
+**Which schema library?**
+- Use **TypeBox** (`import { Type } from 'typebox'`)
+- TypeBox schemas are valid JSON Schema directly
+- Use `Type.Optional(...)` for optional fields
+
+**Which HTTP implementation?**
+- Express app → **ExpressRPCAppBuilder**
+- Hono app (standard RPC) → **HonoRPCAppBuilder**
+- Hono app (streaming) → **HonoStreamAppBuilder**
+- SSE with browser EventSource → `streamMode: 'sse'`
+- Simple text streaming → `streamMode: 'text'`
+
+**How to group procedures?**
+- By domain: `UserProcedures`, `OrderProcedures`
+- By access level: `PublicRPC`, `AuthenticatedRPC`
+- Each group = one `Procedures()` factory call
+
+## Supporting Files
+
+For complete API details, see `api-reference.md` in this skill directory.
+For prescribed patterns with code examples, see `patterns.md`.
+For common mistakes to avoid, see `anti-patterns.md`.

package/agent_config/claude-code/skills/guide/anti-patterns.md

@@ -0,0 +1,502 @@
+# ts-procedures Anti-Patterns
+
+These are common mistakes when using ts-procedures. Each anti-pattern includes a fix.
+
+---
+
+## 1. Throwing Raw Errors Instead of ctx.error()
+
+**Problem:** Throwing plain `Error` loses procedure metadata and makes error handling inconsistent.
+
+```typescript
+// BAD
+async (ctx, params) => {
+  if (!params.id) {
+    throw new Error('ID is required')
+  }
+}
+```
+
+**Fix:** Use `ctx.error()` for business logic errors.
+
+```typescript
+// GOOD
+async (ctx, params) => {
+  if (!params.id) {
+    throw ctx.error('ID is required', { code: 'MISSING_ID' })
+  }
+}
+```
+
+**Why:** `ctx.error()` creates a `ProcedureError` with `procedureName`, `meta`, `definedAt`, and enhanced stack trace. Raw errors get wrapped but lose the `meta` field and intentional error semantics.
+
+---
+
+## 2. Putting Validation Logic in the Handler
+
+**Problem:** Manually validating params when schema validation handles it automatically.
+
+```typescript
+// BAD
+Create('GetUser', {}, async (ctx, params) => {
+  if (!params.userId || typeof params.userId !== 'string') {
+    throw ctx.error('userId is required and must be a string')
+  }
+  return fetchUser(params.userId)
+})
+```
+
+**Fix:** Use `schema.params` — AJV validates automatically.
+
+```typescript
+// GOOD
+Create('GetUser', {
+  schema: {
+    params: Type.Object({ userId: Type.String() }),
+  },
+}, async (ctx, params) => {
+  // params.userId is guaranteed to be a string
+  return fetchUser(params.userId)
+})
+```
+
+**Why:** AJV provides detailed error messages, collects all errors (`allErrors: true`), coerces types, and removes additional properties. Manual validation duplicates this and is less thorough.
+
+---
+
+## 3. Expecting returnType to Be Validated at Runtime
+
+**Problem:** Assuming `schema.returnType` validates the handler's return value.
+
+```typescript
+// BAD — developer expects runtime validation of return value
+Create('GetUser', {
+  schema: {
+    params: Type.Object({ id: Type.String() }),
+    returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+  },
+}, async (ctx, params) => {
+  return { id: 123, wrong: 'field' }  // No error thrown!
+})
+```
+
+**Fix:** Understand that `returnType` is documentation only. Rely on TypeScript for return type safety.
+
+```typescript
+// GOOD — TypeScript enforces return type via generic inference
+Create('GetUser', {
+  schema: {
+    params: Type.Object({ id: Type.String() }),
+    returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+  },
+}, async (ctx, params): Promise<{ id: string; name: string }> => {
+  return { id: params.id, name: 'John' }  // TypeScript catches mismatches
+})
+```
+
+---
+
+## 4. Ignoring ctx.signal in Async Operations
+
+**Problem:** Not passing `signal` to downstream calls, preventing cancellation on client disconnect.
+
+```typescript
+// BAD
+async (ctx, params) => {
+  const data = await fetch('https://api.example.com/heavy-query')
+  const processed = await heavyComputation(data)
+  return processed
+}
+```
+
+**Fix:** Pass `ctx.signal` to all async calls.
+
+```typescript
+// GOOD
+async (ctx, params) => {
+  const data = await fetch('https://api.example.com/heavy-query', {
+    signal: ctx.signal,
+  })
+  const processed = await heavyComputation(data, { signal: ctx.signal })
+  return processed
+}
+```
+
+**Why:** When a client disconnects, the HTTP implementation aborts the signal. Without passing it, the handler continues wasting resources on a response nobody will receive.
+
+---
+
+## 5. Not Checking signal.aborted in Stream Loops
+
+**Problem:** Stream continues producing values after client disconnects.
+
+```typescript
+// BAD
+async function* (ctx, params) {
+  while (true) {
+    const data = await pollForData()
+    yield data
+    await delay(1000)
+  }
+}
+```
+
+**Fix:** Check `ctx.signal.aborted` in the loop condition.
+
+```typescript
+// GOOD
+async function* (ctx, params) {
+  while (!ctx.signal.aborted) {
+    const data = await pollForData({ signal: ctx.signal })
+    yield data
+    await delay(1000)
+  }
+}
+```
+
+---
+
+## 6. Duplicate Procedure Names
+
+**Problem:** Registering two procedures with the same name in the same factory.
+
+```typescript
+// BAD — throws ProcedureRegistrationError
+Create('GetUser', { scope: 'users', version: 1 }, handler1)
+Create('GetUser', { scope: 'admin', version: 1 }, handler2)
+```
+
+**Fix:** Use unique names. Use scope/version to differentiate routes.
+
+```typescript
+// GOOD
+Create('GetUser', { scope: 'users', version: 1 }, handler1)
+Create('GetUserAdmin', { scope: 'admin', version: 1 }, handler2)
+
+// Or use separate factories
+const UserRPC = Procedures<UserContext, RPCConfig>()
+const AdminRPC = Procedures<AdminContext, RPCConfig>()
+UserRPC.Create('GetUser', { scope: 'users', version: 1 }, handler1)
+AdminRPC.Create('GetUser', { scope: 'admin', version: 1 }, handler2)
+```
+
+---
+
+## 7. Using validateYields Without yieldType Schema
+
+**Problem:** Setting `validateYields: true` without providing a `yieldType` schema.
+
+```typescript
+// BAD — validateYields has no effect without yieldType schema
+CreateStream('Stream', {
+  validateYields: true,
+  schema: {
+    params: Type.Object({ id: Type.String() }),
+  },
+}, async function* (ctx, params) {
+  yield { anything: 'goes' }
+})
+```
+
+**Fix:** Provide `yieldType` schema when using `validateYields`.
+
+```typescript
+// GOOD
+CreateStream('Stream', {
+  validateYields: true,
+  schema: {
+    params: Type.Object({ id: Type.String() }),
+    yieldType: Type.Object({ id: Type.String(), value: Type.Number() }),
+  },
+}, async function* (ctx, params) {
+  yield { id: '1', value: 42 }
+})
+```
+
+---
+
+## 8. Swallowing Errors in Handlers
+
+**Problem:** Catching errors without re-throwing, hiding failures from the caller.
+
+```typescript
+// BAD
+async (ctx, params) => {
+  try {
+    return await riskyOperation(params)
+  } catch (err) {
+    console.error('Operation failed:', err)
+    return null  // Caller thinks it succeeded
+  }
+}
+```
+
+**Fix:** Let errors propagate. The framework wraps them in `ProcedureError` with enhanced stack traces.
+
+```typescript
+// GOOD — let the framework handle it
+async (ctx, params) => {
+  return await riskyOperation(params)
+}
+
+// Or rethrow as a business error with context
+async (ctx, params) => {
+  try {
+    return await riskyOperation(params)
+  } catch (err) {
+    throw ctx.error('Operation failed', { originalError: err.message, params })
+  }
+}
+```
+
+---
+
+## 9. Not Using AJV's coerceTypes Behavior
+
+**Problem:** Treating query string values as strings when AJV will coerce them.
+
+```typescript
+// BAD — unnecessary manual parsing
+async (ctx, params) => {
+  const page = parseInt(params.page, 10)
+  const limit = parseInt(params.limit, 10)
+  return fetchPage(page, limit)
+}
+```
+
+**Fix:** Let AJV coerce types via the schema.
+
+```typescript
+// GOOD — AJV coerces "5" → 5 automatically
+Create('ListUsers', {
+  schema: {
+    params: Type.Object({
+      page: Type.Number(),
+      limit: Type.Number(),
+    }),
+  },
+}, async (ctx, params) => {
+  // params.page and params.limit are already numbers
+  return fetchPage(params.page, params.limit)
+})
+```
+
+**Why:** AJV is configured with `coerceTypes: true`. String `"5"` from query params becomes number `5` after validation.
+
+---
+
+## 10. Forgetting removeAdditional Strips Extra Fields
+
+**Problem:** Passing extra fields in params and expecting them to survive validation.
+
+```typescript
+// BAD — extra fields silently removed
+const result = await GetUser(ctx, {
+  userId: '123',
+  debug: true,        // Stripped by AJV
+  extraData: 'value', // Stripped by AJV
+})
+```
+
+**Fix:** Only pass fields defined in the schema. If you need additional fields, add them to the schema.
+
+```typescript
+// GOOD
+Create('GetUser', {
+  schema: {
+    params: Type.Object({
+      userId: Type.String(),
+      debug: Type.Optional(Type.Boolean()),  // Include in schema if needed
+    }),
+  },
+}, handler)
+```
+
+**Why:** AJV is configured with `removeAdditional: true`. Any property not defined in the schema is silently removed before the handler receives params.
+
+---
+
+## 11. Creating Factory Without Context Type When Using HTTP Builders
+
+**Problem:** Using `Procedures()` without a context type, then registering with an HTTP builder that injects context.
+
+```typescript
+// BAD — handler ctx has no type information
+const { Create } = Procedures()
+
+Create('GetUser', {}, async (ctx, params) => {
+  ctx.userId  // Type error: Property 'userId' does not exist
+})
+```
+
+**Fix:** Always specify the context type.
+
+```typescript
+// GOOD
+const { Create } = Procedures<{ userId: string }>()
+
+Create('GetUser', {}, async (ctx, params) => {
+  ctx.userId  // Typed correctly
+})
+```
+
+---
+
+## 12. Registering Standard Procedures with HonoStreamAppBuilder
+
+**Problem:** Using `Create` procedures with `HonoStreamAppBuilder` — it only handles `CreateStream` procedures.
+
+```typescript
+// BAD — Create procedures are silently ignored
+const { Create, CreateStream } = Procedures<AppContext, RPCConfig>()
+Create('GetUser', { scope: 'users', version: 1 }, handler)
+CreateStream('StreamEvents', { scope: 'events', version: 1 }, streamHandler)
+
+new HonoStreamAppBuilder()
+  .register(factory, ctx)  // Only StreamEvents is registered
+  .build()
+```
+
+**Fix:** Use `HonoRPCAppBuilder` or `ExpressRPCAppBuilder` for standard procedures. Use `HonoStreamAppBuilder` only for stream procedures.
+
+```typescript
+// GOOD
+const rpcApp = new HonoRPCAppBuilder().register(RPC, ctx).build()
+const streamApp = new HonoStreamAppBuilder().register(StreamRPC, ctx).build()
+```
+
+---
+
+## 13. Missing Schema at Registration Time
+
+**Problem:** Providing malformed or incompatible schema objects.
+
+```typescript
+// BAD — plain objects are not valid schemas
+Create('GetUser', {
+  schema: {
+    params: { type: 'object', properties: { id: { type: 'string' } } },
+  },
+}, handler)
+```
+
+**Fix:** Use TypeBox schema builders.
+
+```typescript
+// GOOD — TypeBox
+Create('GetUser', {
+  schema: { params: Type.Object({ id: Type.String() }) },
+}, handler)
+```
+
+**Why:** ts-procedures detects schema type via TypeBox's `~kind` symbol. Plain JSON Schema objects are not recognized and will throw `ProcedureRegistrationError`.
+
+---
+
+## 14. Not Handling Pre-Stream vs Mid-Stream Errors Differently
+
+**Problem:** Using a single error handler for both validation errors (before streaming) and runtime errors (during streaming).
+
+```typescript
+// BAD — onError doesn't apply to streaming
+new HonoStreamAppBuilder({
+  onError: (proc, c, err) => { /* This doesn't exist */ },
+})
+```
+
+**Fix:** Use `onPreStreamError` for validation errors and `onMidStreamError` for runtime errors.
+
+```typescript
+// GOOD
+new HonoStreamAppBuilder({
+  onPreStreamError: (proc, c, error) => {
+    // Validation/context error — return normal HTTP response
+    return c.json({ error: error.message }, 400)
+  },
+  onMidStreamError: (proc, c, error) => {
+    // Runtime error during streaming — yield error event, then close
+    return { data: { error: error.message }, closeStream: true }
+  },
+})
+```
+
+---
+
+## 15. Not Using extendProcedureDoc for Documentation
+
+**Problem:** Manually building documentation from procedure metadata instead of using the built-in extension point.
+
+```typescript
+// BAD — manual doc building, fragile and incomplete
+const docs = getProcedures().map(p => ({
+  name: p.name,
+  path: `/${p.config.scope}/${p.name}/${p.config.version}`,
+}))
+```
+
+**Fix:** Use `extendProcedureDoc` in the HTTP builder registration.
+
+```typescript
+// GOOD — base doc auto-generated with correct paths and schemas
+builder.register(factory, context, ({ base, procedure }) => ({
+  summary: procedure.config.description,
+  tags: [base.scope],
+}))
+
+// Access via builder.docs
+console.log(builder.docs)
+```
+
+**Why:** The builder generates correct kebab-case paths, includes JSON schemas for body/response, and merges your extensions. Manual building duplicates this logic and easily drifts.
+
+---
+
+## 16. Using Async Context Factory Without Error Handling
+
+**Problem:** Async context factories that throw unhandled errors, crashing the request.
+
+```typescript
+// BAD — if authenticate() throws, request crashes
+builder.register(factory, async (req) => {
+  const user = await authenticate(req.headers.authorization)
+  return { userId: user.id }
+})
+```
+
+**Fix:** Use the builder's `onError` callback to handle context resolution failures gracefully.
+
+```typescript
+// GOOD
+new ExpressRPCAppBuilder({
+  onError: (procedure, req, res, error) => {
+    if (error.message.includes('Unauthorized')) {
+      res.status(401).json({ error: 'Unauthorized' })
+    } else {
+      res.status(500).json({ error: 'Internal server error' })
+    }
+  },
+})
+```
+
+---
+
+## Summary Table
+
+| # | Anti-Pattern | Risk | Severity |
+|---|-------------|------|----------|
+| 1 | Raw Error instead of ctx.error() | Lost metadata, inconsistent handling | CRITICAL |
+| 2 | Manual validation in handler | Duplicated logic, less thorough | WARNING |
+| 3 | Expecting returnType validation | Silent data contract violations | CRITICAL |
+| 4 | Ignoring ctx.signal | Resource waste on cancelled requests | WARNING |
+| 5 | No signal check in stream loops | Infinite resource consumption | CRITICAL |
+| 6 | Duplicate procedure names | ProcedureRegistrationError at startup | CRITICAL |
+| 7 | validateYields without yieldType | Silent no-op, false confidence | WARNING |
+| 8 | Swallowing errors | Hidden failures, debugging difficulty | CRITICAL |
+| 9 | Manual type coercion | Unnecessary code, coercion mismatch | SUGGESTION |
+| 10 | Expecting extra fields to survive | Silent data loss | WARNING |
+| 11 | Missing context type | No type safety in handlers | WARNING |
+| 12 | Create with HonoStreamAppBuilder | Procedures silently ignored | CRITICAL |
+| 13 | Plain JSON Schema objects instead of TypeBox | ProcedureRegistrationError | CRITICAL |
+| 14 | Wrong error handler for streams | Unhandled errors or wrong response format | WARNING |
+| 15 | Manual doc building | Fragile, incomplete documentation | SUGGESTION |
+| 16 | Unhandled async context factory | Request crashes | WARNING |