ts-procedures 5.2.0 → 5.4.0

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

@@ -0,0 +1,139 @@
+# Hono RPC Template: {{Name}}
+
+## Implementation — `{{Name}}.rpc.ts`
+
+```typescript
+import { Procedures, ProcedureError, ProcedureValidationError } from 'ts-procedures'
+import { HonoRPCAppBuilder } from 'ts-procedures/hono-rpc'
+import type { RPCConfig } from 'ts-procedures/http'
+import { Type } from 'typebox'
+
+// ─── Context ──────────────────────────────────────────────
+
+type {{Name}}Context = {
+  userId: string
+  requestId: string
+}
+
+// ─── Procedures ───────────────────────────────────────────
+
+const RPC = Procedures<{{Name}}Context, RPCConfig>()
+
+export const { GetItem } = RPC.Create(
+  'GetItem',
+  {
+    scope: '{{name}}',  // TODO: set URL scope
+    version: 1,
+    description: 'Fetch item by ID',
+    schema: {
+      params: Type.Object({
+        id: Type.String(),
+      }),
+      returnType: Type.Object({
+        id: Type.String(),
+        name: Type.String(),
+      }),
+    },
+  },
+  async (ctx, params) => {
+    // TODO: implement
+    return { id: params.id, name: 'Example' }
+  }
+)
+
+export const { ListItems } = RPC.Create(
+  'ListItems',
+  {
+    scope: '{{name}}',
+    version: 1,
+    description: 'List all items',
+    schema: {
+      params: Type.Object({
+        page: Type.Optional(Type.Number()),
+        limit: Type.Optional(Type.Number()),
+      }),
+    },
+  },
+  async (ctx, params) => {
+    // TODO: implement
+    return { items: [], total: 0 }
+  }
+)
+
+// ─── Hono App Builder ─────────────────────────────────────
+
+export const {{name}}App = new HonoRPCAppBuilder({
+  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(RPC, (c) => ({
+    userId: c.req.header('x-user-id') || 'anonymous',
+    requestId: c.req.header('x-request-id') || crypto.randomUUID(),
+  }))
+  .build()
+
+// Route map:
+// POST /api/{{name}}/get-item/1
+// POST /api/{{name}}/list-items/1
+
+// Documentation: {{name}}App.docs
+```
+
+## Test — `{{Name}}.rpc.test.ts`
+
+```typescript
+import { describe, test, expect } from 'vitest'
+import { {{name}}App } from './{{Name}}.rpc'
+
+describe('{{Name}} RPC', () => {
+  test('GET item returns expected result', async () => {
+    const res = await {{name}}App.request('/api/{{name}}/get-item/1', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ id: 'item-1' }),
+    })
+
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body).toEqual({ id: 'item-1', name: 'Example' })
+  })
+
+  test('returns 400 for invalid params', async () => {
+    const res = await {{name}}App.request('/api/{{name}}/get-item/1', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+    })
+
+    expect(res.status).toBe(400)
+  })
+
+  test('LIST items returns array', async () => {
+    const res = await {{name}}App.request('/api/{{name}}/list-items/1', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ page: 1, limit: 10 }),
+    })
+
+    expect(res.status).toBe(200)
+    const body = await res.json()
+    expect(body).toHaveProperty('items')
+    expect(body).toHaveProperty('total')
+  })
+})
+```

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

@@ -0,0 +1,134 @@
+# Hono Stream Template: {{Name}}
+
+## Implementation — `{{Name}}.stream-rpc.ts`
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { HonoStreamAppBuilder, sse } from 'ts-procedures/hono-stream'
+import type { RPCConfig } from 'ts-procedures/http'
+import { Type } from 'typebox'
+
+// ─── Context ──────────────────────────────────────────────
+
+type {{Name}}Context = {
+  userId: string
+}
+
+// ─── Stream Procedures ────────────────────────────────────
+
+const StreamRPC = Procedures<{{Name}}Context, RPCConfig>()
+
+export const { {{Name}}Stream } = StreamRPC.CreateStream(
+  '{{Name}}Stream',
+  {
+    scope: '{{name}}',  // TODO: set URL scope
+    version: 1,
+    description: 'TODO: describe what this streams',
+    schema: {
+      params: Type.Object({
+        // TODO: define input parameters
+        channel: Type.String(),
+      }),
+      yieldType: Type.Object({
+        // TODO: define shape of each yielded value
+        type: Type.String(),
+        payload: Type.Any(),
+        timestamp: Type.Number(),
+      }),
+    },
+  },
+  async function* (ctx, params) {
+    // ctx.signal is ALWAYS present in stream handlers
+
+    // TODO: implement streaming logic
+    let counter = 0
+    while (!ctx.signal.aborted) {
+      const event = await pollForEvents(params.channel, { signal: ctx.signal })
+
+      // Use sse() to attach SSE metadata (event type, id, retry)
+      yield sse(
+        { type: event.type, payload: event.data, timestamp: Date.now() },
+        { event: event.type, id: String(counter++) }
+      )
+    }
+  }
+)
+
+// Placeholder — replace with real event source
+async function pollForEvents(channel: string, opts?: { signal?: AbortSignal }) {
+  await new Promise(r => setTimeout(r, 1000))
+  return { type: 'update', data: { value: Math.random() } }
+}
+
+// ─── Hono Stream App Builder ──────────────────────────────
+
+export const {{name}}StreamApp = new HonoStreamAppBuilder({
+  pathPrefix: '/api',
+  defaultStreamMode: 'sse',  // or 'text' for newline-delimited JSON
+  onPreStreamError: (procedure, c, error) => {
+    return c.json({ error: error.message }, 400)
+  },
+  onMidStreamError: (procedure, c, error) => ({
+    data: { type: 'error', payload: { message: error.message }, timestamp: Date.now() },
+    closeStream: true,
+  }),
+})
+  .register(StreamRPC, (c) => ({
+    userId: c.req.header('x-user-id') || 'anonymous',
+  }))
+  .build()
+
+// Routes:
+// GET  /api/{{name}}/{{name}}-stream/1?channel=test
+// POST /api/{{name}}/{{name}}-stream/1  (body: { channel: "test" })
+
+// SSE output per yield:
+// event: {{Name}}Stream
+// id: 0
+// data: {"type":"update","payload":{...},"timestamp":1234567890}
+```
+
+## Test — `{{Name}}.stream-rpc.test.ts`
+
+```typescript
+import { describe, test, expect } from 'vitest'
+import { {{name}}StreamApp } from './{{Name}}.stream-rpc'
+
+describe('{{Name}} Stream RPC', () => {
+  test('GET returns SSE stream', async () => {
+    const res = await {{name}}StreamApp.request(
+      '/api/{{name}}/{{name}}-stream/1?channel=test'
+    )
+
+    expect(res.status).toBe(200)
+    expect(res.headers.get('content-type')).toContain('text/event-stream')
+  })
+
+  test('POST returns SSE stream', async () => {
+    const res = await {{name}}StreamApp.request(
+      '/api/{{name}}/{{name}}-stream/1',
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ channel: 'test' }),
+      }
+    )
+
+    expect(res.status).toBe(200)
+    expect(res.headers.get('content-type')).toContain('text/event-stream')
+  })
+
+  test('returns 400 for invalid params', async () => {
+    const res = await {{name}}StreamApp.request(
+      '/api/{{name}}/{{name}}-stream/1',
+      {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({}),
+      }
+    )
+
+    expect(res.status).toBe(400)
+  })
+})
+```

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

@@ -0,0 +1,77 @@
+# Procedure Template: {{Name}}
+
+## Implementation — `{{Name}}.procedure.ts`
+
+```typescript
+import { Procedures } from 'ts-procedures'
+import { Type } from 'typebox'
+
+// Define context type (adjust to match your app's context)
+type AppContext = {
+  userId: string
+  signal?: AbortSignal
+}
+
+const { Create } = Procedures<AppContext>()
+
+export const { {{Name}}, procedure: {{Name}}Procedure, info: {{Name}}Info } = Create(
+  '{{Name}}',
+  {
+    description: 'TODO: describe what {{Name}} does',
+    schema: {
+      params: Type.Object({
+        // TODO: define input parameters
+        id: Type.String(),
+      }),
+      returnType: Type.Object({
+        // TODO: define return shape (documentation only, not validated at runtime)
+        id: Type.String(),
+        // ...fields
+      }),
+    },
+  },
+  async (ctx, params) => {
+    // params.id is guaranteed to be a string (validated by AJV)
+
+    // Use ctx.error() for business logic errors
+    // throw ctx.error('Not found', { code: 'NOT_FOUND', id: params.id })
+
+    // Pass ctx.signal to downstream async calls
+    // const data = await fetch(url, { signal: ctx.signal })
+
+    // TODO: implement handler logic
+    return { id: params.id }
+  }
+)
+```
+
+## Test — `{{Name}}.procedure.test.ts`
+
+```typescript
+import { describe, test, expect } from 'vitest'
+import { ProcedureError, ProcedureValidationError } from 'ts-procedures'
+import { {{Name}} } from './{{Name}}.procedure'
+
+const mockContext = { userId: 'test-user' }
+
+describe('{{Name}}', () => {
+  test('returns expected result for valid params', async () => {
+    const result = await {{Name}}(mockContext, { id: 'test-id' })
+    expect(result).toBeDefined()
+    expect(result.id).toBe('test-id')
+  })
+
+  test('throws ProcedureValidationError for invalid params', async () => {
+    await expect(
+      {{Name}}(mockContext, {} as any)
+    ).rejects.toThrow(ProcedureValidationError)
+  })
+
+  test('throws ProcedureError for business logic failures', async () => {
+    // TODO: test ctx.error() scenarios
+    // await expect(
+    //   {{Name}}(mockContext, { id: 'invalid' })
+    // ).rejects.toThrow(ProcedureError)
+  })
+})
+```

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)
+  })
+})
+```