ts-procedures 5.2.0 → 5.4.0

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

@@ -0,0 +1,727 @@
+# ts-procedures Prescribed Patterns
+
+Follow these patterns exactly when writing ts-procedures code.
+
+> All examples use `import { Type } from 'typebox'` for schema definitions. This import is assumed unless shown explicitly.
+
+---
+
+## Basic Procedure Setup
+
+```typescript
+import { Procedures } from 'ts-procedures'
+
+// 1. Define context type
+type AppContext = { userId: string; requestId: string }
+
+// 2. Create factory (optionally with extended config)
+const { Create, CreateStream, getProcedures } = Procedures<AppContext>()
+
+// 3. Register procedures
+const { GetUser, procedure, info } = Create(
+  'GetUser',
+  { description: 'Fetch user by ID' },
+  async (ctx, params) => {
+    return { id: ctx.userId, name: 'John' }
+  }
+)
+
+// 4. Call procedure
+const result = await GetUser({ userId: 'u1', requestId: 'r1' }, {})
+// or: await procedure({ userId: 'u1', requestId: 'r1' }, {})
+```
+
+---
+
+## Schema Validation with TypeBox
+
+```typescript
+import { Type } from 'typebox'
+
+const { Create } = Procedures<AppContext>()
+
+const { GetUser } = Create(
+  'GetUser',
+  {
+    schema: {
+      params: Type.Object({
+        userId: Type.String(),
+      }),
+      returnType: Type.Object({
+        id: Type.String(),
+        name: Type.String(),
+        email: Type.String(),
+      }),
+    },
+  },
+  async (ctx, params) => {
+    // params is typed as { userId: string }
+    // params.userId is guaranteed to be a string (validated by AJV)
+    const user = await fetchUser(params.userId)
+    return user
+  }
+)
+```
+
+---
+
+## Error Handling in Handlers
+
+Use `ctx.error()` for business logic errors. Never throw raw Error instances.
+
+```typescript
+const { TransferFunds } = Create(
+  'TransferFunds',
+  {
+    schema: {
+      params: Type.Object({
+        fromAccountId: Type.String(),
+        toAccountId: Type.String(),
+        amount: Type.Number(),
+      }),
+    },
+  },
+  async (ctx, params) => {
+    const account = await getAccount(params.fromAccountId)
+
+    if (!account) {
+      throw ctx.error('Account not found', { code: 'NOT_FOUND', accountId: params.fromAccountId })
+    }
+
+    if (account.balance < params.amount) {
+      throw ctx.error('Insufficient funds', {
+        code: 'INSUFFICIENT_FUNDS',
+        balance: account.balance,
+        requested: params.amount,
+      })
+    }
+
+    return await executeTransfer(params)
+  }
+)
+```
+
+---
+
+## Stream Procedures
+
+```typescript
+const { StreamNotifications } = CreateStream(
+  'StreamNotifications',
+  {
+    description: 'Real-time notification feed',
+    schema: {
+      params: Type.Object({
+        userId: Type.String(),
+      }),
+      yieldType: Type.Object({
+        id: Type.String(),
+        message: Type.String(),
+        timestamp: Type.Number(),
+      }),
+    },
+  },
+  async function* (ctx, params) {
+    // ctx.signal is always present in stream handlers
+    const subscription = subscribeToNotifications(params.userId)
+
+    try {
+      for await (const notification of subscription) {
+        if (ctx.signal.aborted) break
+        yield notification
+      }
+    } finally {
+      subscription.close()
+    }
+  }
+)
+```
+
+---
+
+## AbortSignal in Stream Handlers
+
+Always check `ctx.signal` for cancellation. Distinguish normal completion from client disconnect.
+
+```typescript
+const { StreamData } = CreateStream(
+  'StreamData',
+  {},
+  async function* (ctx) {
+    try {
+      while (!ctx.signal.aborted) {
+        const data = await fetchLatestData({ signal: ctx.signal })
+        yield data
+        await delay(1000)
+      }
+    } finally {
+      if (ctx.signal.reason === 'stream-completed') {
+        // Normal completion — consumer finished reading
+        console.log('Stream completed normally')
+      } else {
+        // Client disconnected or external abort
+        console.log('Stream aborted:', ctx.signal.reason)
+      }
+    }
+  }
+)
+```
+
+---
+
+## AbortSignal in Standard Handlers
+
+Pass the signal to downstream async calls for automatic cancellation.
+
+```typescript
+const { LongOperation } = Create(
+  'LongOperation',
+  {},
+  async (ctx, params) => {
+    // ctx.signal is available when HTTP implementation provides it
+    const data = await fetch('https://api.example.com/data', {
+      signal: ctx.signal,
+    })
+
+    const processed = await processData(data, { signal: ctx.signal })
+    return processed
+  }
+)
+```
+
+---
+
+## Extended Config with RPCConfig
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { Type } from 'typebox'
+import type { RPCConfig } from 'ts-procedures/http'
+
+type AppContext = { userId: string }
+
+const { Create } = Procedures<AppContext, RPCConfig>()
+
+// Every procedure now MUST include scope and version
+const { GetUser } = Create(
+  'GetUser',
+  {
+    scope: 'users',        // URL path segment
+    version: 1,            // API version
+    description: 'Fetch user by ID',
+    schema: {
+      params: Type.Object({ userId: Type.String() }),
+    },
+  },
+  async (ctx, params) => {
+    return await fetchUser(params.userId)
+  }
+)
+// Route: POST /users/get-user/1
+```
+
+---
+
+## Custom Extended Config
+
+```typescript
+interface AppConfig extends RPCConfig {
+  permissions?: string[]
+  deprecated?: boolean
+}
+
+const { Create, getProcedures } = Procedures<AppContext, AppConfig>()
+
+const { AdminAction } = Create(
+  'AdminAction',
+  {
+    scope: 'admin',
+    version: 1,
+    permissions: ['admin:write'],
+    description: 'Perform admin action',
+  },
+  async (ctx, params) => { /* ... */ }
+)
+
+// Use getProcedures() for introspection
+for (const proc of getProcedures()) {
+  console.log(proc.name, proc.config.permissions)
+}
+```
+
+---
+
+## Express RPC Integration
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { ExpressRPCAppBuilder } from 'ts-procedures/express-rpc'
+import { Type } from 'typebox'
+import type { RPCConfig } from 'ts-procedures/http'
+
+// 1. Define context and procedures
+type AppContext = { userId: string; requestId: string }
+const { Create } = Procedures<AppContext, RPCConfig>()
+
+const { GetUser } = Create(
+  'GetUser',
+  { scope: 'users', version: 1, schema: { params: Type.Object({ id: Type.String() }) } },
+  async (ctx, params) => fetchUser(params.id)
+)
+
+const { UpdateUser } = Create(
+  'UpdateUser',
+  { scope: 'users', version: 1 },
+  async (ctx, params) => updateUser(params)
+)
+
+// 2. Build Express app
+const app = new ExpressRPCAppBuilder({
+  pathPrefix: '/api',
+  onError: (procedure, req, res, error) => {
+    if (error instanceof ProcedureValidationError) {
+      res.status(400).json({ error: error.message, details: error.errors })
+    } else {
+      res.status(500).json({ error: error.message })
+    }
+  },
+})
+  .register(
+    { getProcedures: () => [GetUser.info, UpdateUser.info] },  // Or use the factory directly
+    async (req) => ({
+      userId: await getUserIdFromToken(req.headers.authorization),
+      requestId: req.headers['x-request-id'] || crypto.randomUUID(),
+    })
+  )
+  .build()
+
+// Routes created:
+// POST /api/users/get-user/1
+// POST /api/users/update-user/1
+```
+
+---
+
+## Hono RPC Integration
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'
+import type { RPCConfig } from 'ts-procedures/http'
+
+type AppContext = { userId: string }
+const RPC = Procedures<AppContext, RPCConfig>()
+
+RPC.Create('GetUser', { scope: 'users', version: 1 }, async (ctx, params) => {
+  return fetchUser(params.id)
+})
+
+const app = new HonoRPCAppBuilder({ pathPrefix: '/api' })
+  .register(RPC, (c) => ({
+    userId: c.req.header('x-user-id') || 'anonymous',
+  }))
+  .build()
+```
+
+---
+
+## Hono Streaming Integration
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
+import { Type } from 'typebox'
+import type { RPCConfig } from 'ts-procedures/http'
+
+type StreamContext = { userId: string }
+const StreamRPC = Procedures<StreamContext, RPCConfig>()
+
+const { StreamEvents } = StreamRPC.CreateStream(
+  'StreamEvents',
+  {
+    scope: 'events',
+    version: 1,
+    schema: {
+      params: Type.Object({ channel: Type.String() }),
+      yieldType: Type.Object({ type: Type.String(), payload: Type.Any() }),
+    },
+  },
+  async function* (ctx, params) {
+    const sub = subscribe(params.channel, { signal: ctx.signal })
+    for await (const event of sub) {
+      // Attach SSE metadata
+      yield sse(event, { event: event.type, id: event.id })
+    }
+  }
+)
+
+const app = new HonoStreamAppBuilder({
+  pathPrefix: '/api',
+  defaultStreamMode: 'sse',
+  onMidStreamError: (procedure, c, error) => ({
+    data: { error: error.message },
+    closeStream: true,
+  }),
+})
+  .register(StreamRPC, (c) => ({
+    userId: c.req.header('x-user-id') || 'anonymous',
+  }))
+  .build()
+
+// Routes: GET|POST /api/events/stream-events/1
+```
+
+---
+
+## Text Streaming Mode
+
+```typescript
+const app = new HonoStreamAppBuilder({
+  defaultStreamMode: 'text',  // Newline-delimited JSON
+})
+  .register(StreamRPC, contextFactory)
+  .build()
+
+// Each yield becomes: {"type":"event","payload":{...}}\n
+```
+
+---
+
+## Hono API Integration (REST-style)
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { HonoAPIAppBuilder } from 'ts-procedures/hono-api'
+import type { APIConfig } from 'ts-procedures/http'
+import { Type } from 'typebox'
+
+type AppContext = { userId: string }
+const API = Procedures<AppContext, APIConfig>()
+
+API.Create('GetUser', {
+  path: '/users/:id',
+  method: 'get',
+  schema: {
+    input: {
+      pathParams: Type.Object({ id: Type.String() }),
+    },
+    returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+  },
+}, async (ctx, { pathParams }) => {
+  return await fetchUser(pathParams.id)
+})
+
+API.Create('CreateUser', {
+  path: '/users',
+  method: 'post',
+  schema: {
+    input: {
+      body: Type.Object({ name: Type.String(), email: Type.String() }),
+    },
+  },
+}, async (ctx, { body }) => {
+  return await createUser(body)
+})
+
+API.Create('DeleteUser', {
+  path: '/users/:id',
+  method: 'delete',
+  schema: {
+    input: {
+      pathParams: Type.Object({ id: Type.String() }),
+    },
+  },
+}, async (ctx, { pathParams }) => {
+  await deleteUser(pathParams.id)
+})
+
+const app = await new HonoAPIAppBuilder({
+  pathPrefix: '/api',
+  onError: (procedure, c, error) => {
+    if (error instanceof ProcedureValidationError) {
+      return c.json({ error: error.message, details: error.errors }, 400)
+    }
+    return c.json({ error: error.message }, 500)
+  },
+})
+  .register(API, (c) => ({
+    userId: c.req.header('x-user-id') || 'anonymous',
+  }))
+  .build()
+
+// Routes:
+// GET    /api/users/:id → 200
+// POST   /api/users     → 201
+// DELETE /api/users/:id → 204
+```
+
+---
+
+## Extended Config with APIConfig
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import type { APIConfig } from 'ts-procedures/http'
+
+type AppContext = { userId: string }
+
+const { Create } = Procedures<AppContext, APIConfig>()
+
+// Every procedure now MUST include path and method
+const { GetUser } = Create(
+  'GetUser',
+  {
+    path: '/users/:id',
+    method: 'get',
+    schema: {
+      input: {
+        pathParams: Type.Object({ id: Type.String() }),
+        query: Type.Object({ include: Type.Optional(Type.String()) }),
+      },
+    },
+  },
+  async (ctx, { pathParams, query }) => {
+    return await fetchUser(pathParams.id, { include: query.include })
+  }
+)
+```
+
+---
+
+## schema.input — Multi-Channel Structured Input
+
+Use `schema.input` instead of `schema.params` for structured per-channel validation:
+
+```typescript
+const { Create } = Procedures<AppContext, APIConfig>()
+
+Create('UpdateUserField', {
+  path: '/users/:id',
+  method: 'put',
+  schema: {
+    input: {
+      pathParams: Type.Object({ id: Type.String() }),
+      query: Type.Object({ notify: Type.Optional(Type.Boolean()) }),
+      body: Type.Object({ field: Type.String(), value: Type.String() }),
+      headers: Type.Object({ 'x-idempotency-key': Type.String() }),
+    },
+    returnType: Type.Object({ ok: Type.Boolean() }),
+  },
+}, async (ctx, { pathParams, query, body, headers }) => {
+  // Each channel independently typed and validated
+  // Validation errors include channel name: "Validation error for UpdateUserField in input.body"
+  await updateField(pathParams.id, body.field, body.value, {
+    idempotencyKey: headers['x-idempotency-key'],
+  })
+  if (query.notify) await notifyUser(pathParams.id)
+  return { ok: true }
+})
+```
+
+---
+
+## APIInput Channel Constraint
+
+Use `satisfies APIInput` to catch channel name typos at compile time:
+
+```typescript
+import type { APIInput } from 'ts-procedures/hono-api'
+
+Create('Search', {
+  path: '/search',
+  method: 'get',
+  schema: {
+    input: {
+      query: Type.Object({ q: Type.String() }),
+    } satisfies APIInput,
+  },
+}, async (ctx, { query }) => {
+  return await search(query.q)
+})
+```
+
+---
+
+## onCreate Callback for Framework Integration
+
+```typescript
+const registeredProcedures: TProcedureRegistration[] = []
+
+const { Create } = Procedures<AppContext>({
+  onCreate: (procedure) => {
+    registeredProcedures.push(procedure)
+    console.log(`Registered: ${procedure.name}`)
+  },
+})
+
+// Use for:
+// - Route registration in custom frameworks
+// - OpenAPI spec generation
+// - Logging/monitoring setup
+// - Permission registration
+```
+
+---
+
+## getProcedures() for Introspection
+
+```typescript
+const { Create, getProcedures } = Procedures<AppContext, RPCConfig>()
+
+Create('GetUser', { scope: 'users', version: 1 }, async (ctx) => ({}))
+Create('ListUsers', { scope: 'users', version: 1 }, async (ctx) => [])
+
+// Generate documentation
+const docs = getProcedures().map(proc => ({
+  name: proc.name,
+  path: `/${proc.config.scope}/${kebabCase(proc.name)}/${proc.config.version}`,
+  params: proc.config.schema?.params,
+  returnType: proc.config.schema?.returnType,
+}))
+```
+
+---
+
+## Multiple Factories for Access Control
+
+```typescript
+type PublicContext = { requestId: string }
+type AuthContext = { userId: string; requestId: string }
+
+const PublicRPC = Procedures<PublicContext, RPCConfig>()
+const AuthRPC = Procedures<AuthContext, RPCConfig>()
+
+PublicRPC.Create('HealthCheck', { scope: 'health', version: 1 }, async () => ({ status: 'ok' }))
+AuthRPC.Create('GetProfile', { scope: 'users', version: 1 }, async (ctx) => fetchProfile(ctx.userId))
+
+// Register with different context resolvers
+const app = new ExpressRPCAppBuilder({ pathPrefix: '/api' })
+  .register(PublicRPC, (req) => ({ requestId: req.headers['x-request-id'] }))
+  .register(AuthRPC, async (req) => ({
+    userId: await authenticate(req),
+    requestId: req.headers['x-request-id'],
+  }))
+  .build()
+```
+
+---
+
+## Documentation Generation with extendProcedureDoc
+
+```typescript
+const app = new ExpressRPCAppBuilder({ pathPrefix: '/api' })
+  .register(RPC, contextFactory, ({ base, procedure }) => ({
+    summary: procedure.config.description,
+    tags: [base.scope],
+    security: procedure.config.permissions
+      ? [{ bearerAuth: [] }]
+      : [],
+  }))
+  .build()
+
+// Access generated docs
+const openApiPaths = app.docs.map(doc => ({
+  [doc.path]: {
+    [doc.method]: {
+      summary: doc.summary,
+      tags: doc.tags,
+      requestBody: doc.jsonSchema.body
+        ? { content: { 'application/json': { schema: doc.jsonSchema.body } } }
+        : undefined,
+      responses: {
+        200: doc.jsonSchema.response
+          ? { content: { 'application/json': { schema: doc.jsonSchema.response } } }
+          : { description: 'Success' },
+      },
+    },
+  },
+}))
+```
+
+---
+
+## Testing Procedures
+
+```typescript
+import { describe, test, expect } from 'vitest'
+
+describe('GetUser', () => {
+  test('returns user for valid params', async () => {
+    const result = await GetUser(
+      { userId: 'caller-1', requestId: 'test' },
+      { id: 'user-123' }
+    )
+    expect(result).toEqual({ id: 'user-123', name: 'John' })
+  })
+
+  test('throws ProcedureValidationError for invalid params', async () => {
+    await expect(
+      GetUser({ userId: 'caller-1', requestId: 'test' }, {})
+    ).rejects.toThrow(ProcedureValidationError)
+  })
+
+  test('throws ProcedureError for business logic errors', async () => {
+    await expect(
+      GetUser({ userId: 'caller-1', requestId: 'test' }, { id: 'not-found' })
+    ).rejects.toThrow(ProcedureError)
+  })
+})
+```
+
+---
+
+## Testing Stream Procedures
+
+```typescript
+describe('StreamNotifications', () => {
+  test('yields notifications', async () => {
+    const values = []
+    for await (const val of StreamNotifications({ userId: 'u1' }, { userId: 'u1' })) {
+      values.push(val)
+      if (values.length >= 3) break
+    }
+    expect(values).toHaveLength(3)
+  })
+})
+```
+
+---
+
+## Testing HTTP Builders
+
+```typescript
+import supertest from 'supertest'
+
+describe('Express RPC', () => {
+  const app = new ExpressRPCAppBuilder({ pathPrefix: '/api' })
+    .register(RPC, { userId: 'test-user', requestId: 'test' })
+    .build()
+
+  test('POST /api/users/get-user/1', async () => {
+    const res = await supertest(app)
+      .post('/api/users/get-user/1')
+      .send({ id: 'user-123' })
+      .expect(200)
+
+    expect(res.body).toEqual({ id: 'user-123', name: 'John' })
+  })
+})
+```
+
+---
+
+## Lifecycle Hook Execution Order
+
+### Standard RPC (Express/Hono)
+```
+onRequestStart → factoryContext() → handler() → onSuccess → onRequestEnd
+                                  → onError  →              onRequestEnd
+```
+
+### Streaming (HonoStreamAppBuilder)
+```
+onRequestStart → factoryContext() → params validation
+                                  → onPreStreamError (if invalid) → onRequestEnd
+                                  → onStreamStart → handler yields → onStreamEnd → onRequestEnd
+                                                  → onMidStreamError (if throw) → onStreamEnd → onRequestEnd
+```