ts-procedures 7.3.0 → 8.0.0

package/src/schema/parser.ts

@@ -8,12 +8,13 @@ export type TSchemaParsed = {
     params?: TJSONSchema
     returnType?: TJSONSchema
     yieldType?: TJSONSchema
-    input?: Record<string, TJSONSchema>
+    req?: Record<string, TJSONSchema>
+    res?: { body?: TJSONSchema; headers?: TJSONSchema }
   }
   validation: {
     params?: (params: any) => { errors?: TSchemaValidationError[] }
     yield?: (value: any) => { errors?: TSchemaValidationError[] }
-    input?: Record<string, (value: any) => { errors?: TSchemaValidationError[] }>
+    req?: Record<string, (value: any) => { errors?: TSchemaValidationError[] }>
   }
 }
 
@@ -30,7 +31,13 @@ const ajv = addFormats(
 )
 
 export function schemaParser(
-  schema: { params?: unknown; returnType?: unknown; yieldType?: unknown; input?: Record<string, unknown> },
+  schema: {
+    params?: unknown
+    returnType?: unknown
+    yieldType?: unknown
+    req?: Record<string, unknown>
+    res?: { body?: unknown; headers?: unknown }
+  },
   onParseError: (errors: Record<string, string>) => void
 ): TSchemaParsed {
   const jsonSchema: TSchemaParsed['jsonSchema'] = {}
@@ -150,11 +157,11 @@ export function schemaParser(
     }
   }
 
-  if (schema.input) {
-    jsonSchema.input = {}
-    validation.input = {}
+  if (schema.req) {
+    jsonSchema.req = {}
+    validation.req = {}
 
-    for (const [channelName, channelSchema] of Object.entries(schema.input)) {
+    for (const [channelName, channelSchema] of Object.entries(schema.req)) {
       if (!channelSchema) continue
 
       let channelJsonSchema: TJSONSchema | undefined
@@ -163,17 +170,17 @@ export function schemaParser(
         const extracted = extractJsonSchema(channelSchema as TJSONSchema)
         if (extracted) {
           channelJsonSchema = extracted
-          jsonSchema.input[channelName] = extracted
+          jsonSchema.req![channelName] = extracted
         }
       } catch (e: any) {
         onParseError({
-          [`input.${channelName}`]: `Error extracting json schema schema.input.${channelName} - ${e.message}`,
+          [`req.${channelName}`]: `Error extracting json schema schema.req.${channelName} - ${e.message}`,
         })
       }
 
       if (!channelJsonSchema) {
         onParseError({
-          [`input.${channelName}`]: `Error extracting json schema schema.input.${channelName} - might be empty or not a valid suretype or typebox type`,
+          [`req.${channelName}`]: `Error extracting json schema schema.req.${channelName} - might be empty or not a valid suretype or typebox type`,
         })
       } else {
         let channelValidator: AJV.ValidateFunction | undefined
@@ -182,11 +189,11 @@ export function schemaParser(
           channelValidator = ajv.compile(channelJsonSchema as TJSONSchema)
         } catch (e: any) {
           onParseError({
-            [`input.${channelName}`]: `Error compiling schema.input.${channelName} for validator - ${e.message}`,
+            [`req.${channelName}`]: `Error compiling schema.req.${channelName} for validator - ${e.message}`,
           })
         }
 
-        validation.input[channelName] = (value: any) => {
+        validation.req![channelName] = (value: any) => {
           if (!channelValidator) {
             return {
               errors: [
@@ -211,5 +218,48 @@ export function schemaParser(
     }
   }
 
+  // res: compute JSON Schema for body and headers (documentation/codegen only — no validators)
+  if (schema.res) {
+    jsonSchema.res = {}
+
+    if (schema.res.body) {
+      try {
+        const extracted = extractJsonSchema(schema.res.body as TJSONSchema)
+        if (extracted) {
+          jsonSchema.res.body = extracted
+        }
+      } catch (e: any) {
+        onParseError({
+          'res.body': `Error extracting json schema schema.res.body - ${e.message}`,
+        })
+      }
+
+      if (!jsonSchema.res.body) {
+        onParseError({
+          'res.body': `Error extracting json schema schema.res.body - might be empty or not a valid suretype or typebox type`,
+        })
+      }
+    }
+
+    if (schema.res.headers) {
+      try {
+        const extracted = extractJsonSchema(schema.res.headers as TJSONSchema)
+        if (extracted) {
+          jsonSchema.res.headers = extracted
+        }
+      } catch (e: any) {
+        onParseError({
+          'res.headers': `Error extracting json schema schema.res.headers - ${e.message}`,
+        })
+      }
+
+      if (!jsonSchema.res.headers) {
+        onParseError({
+          'res.headers': `Error extracting json schema schema.res.headers - might be empty or not a valid suretype or typebox type`,
+        })
+      }
+    }
+  }
+
   return { jsonSchema, validation }
 }

package/src/stack-utils.ts

@@ -23,6 +23,14 @@ export type DefinitionInfo = {
 const INTERNAL_FILES = [
   '/index.ts',
   '/index.js',
+  '/create.ts',
+  '/create.js',
+  '/create-stream.ts',
+  '/create-stream.js',
+  '/create-http.ts',
+  '/create-http.js',
+  '/create-http-stream.ts',
+  '/create-http-stream.js',
   '/errors.ts',
   '/errors.js',
   '/stack-utils.ts',

package/src/types.ts

@@ -0,0 +1,133 @@
+import { ProcedureError } from './errors.js'
+import { TJSONSchema } from './schema/types.js'
+
+export type TNoContextProvided = unknown
+
+export type TLocalContext = {
+  error: (message: string, meta?: object) => ProcedureError
+  signal?: AbortSignal
+}
+
+export type TStreamContext = TLocalContext & {
+  signal: AbortSignal
+}
+
+/**
+ * Discriminant on every procedure registration that drives builder routing.
+ *
+ * - `'rpc'` — Create() registration
+ * - `'rpc-stream'` — CreateStream() registration
+ * - `'http'` — CreateHttp() registration
+ * - `'http-stream'` — CreateHttpStream() registration
+ *
+ * `HonoAppBuilder` dispatches all four kinds from a single registration. Use
+ * `kind` for any logic that needs to distinguish procedure shape; the legacy
+ * `isStream` field on TStreamProcedureRegistration is kept for back-compat but
+ * new code should branch on `kind`.
+ */
+export type ProcedureKind = 'rpc' | 'rpc-stream' | 'http' | 'http-stream'
+
+export type TProcedureRegistration<TContext = unknown, TExtendedConfig = unknown> = {
+  name: string
+  kind: 'rpc'
+  config: {
+    description?: string
+    schema?: {
+      params?: TJSONSchema
+      returnType?: TJSONSchema
+    }
+    validation?: {
+      params?: (params: any) => { errors?: any[] }
+    }
+  } & TExtendedConfig
+  handler: (ctx: TContext, params?: any) => Promise<any>
+}
+
+export type TStreamProcedureRegistration<TContext = unknown, TExtendedConfig = unknown> = {
+  name: string
+  kind: 'rpc-stream'
+  isStream: true
+  config: {
+    description?: string
+    schema?: {
+      params?: TJSONSchema
+      yieldType?: TJSONSchema
+      returnType?: TJSONSchema
+    }
+    validation?: {
+      params?: (params: any) => { errors?: any[] }
+      yield?: (value: any) => { errors?: any[] }
+    }
+    validateYields?: boolean
+  } & TExtendedConfig
+  handler: (ctx: TContext, params?: any) => AsyncGenerator<any, any, unknown>
+}
+
+export type TBuilderConfig = {
+  /**
+   * Skip per-call AJV runtime validation. JSON Schema is still computed at
+   * registration time. Intended for trusted internal factories whose callers
+   * are already type-checked at build time.
+   */
+  noRuntimeValidation?: true
+}
+
+export type HttpMethod = 'get' | 'post' | 'put' | 'delete' | 'patch' | 'head'
+
+export type TCreateHttpConfig<TReq, TRes, TErrorKey extends string = string> = {
+  path: string
+  method: HttpMethod
+  successStatus?: number
+  scope?: string
+  errors?: TErrorKey[]
+  description?: string
+  schema: {
+    req?: TReq
+    res?: TRes
+  }
+}
+
+export type THttpProcedureRegistration<TContext = unknown> = {
+  name: string
+  kind: 'http'
+  config: {
+    path: string
+    method: HttpMethod
+    successStatus?: number
+    scope?: string
+    errors?: string[]
+    description?: string
+    schema?: {
+      req?: Record<string, TJSONSchema>
+      res?: { body?: TJSONSchema; headers?: TJSONSchema }
+    }
+    validation?: {
+      req?: Record<string, (value: any) => { errors?: any[] }>
+    }
+  }
+  handler: (ctx: TContext, req?: any) => Promise<any>
+}
+
+export type THttpStreamProcedureRegistration<TContext = unknown> = {
+  name: string
+  kind: 'http-stream'
+  config: {
+    path: string
+    method: HttpMethod
+    scope?: string
+    errors?: string[]
+    description?: string
+    schema?: {
+      req?: Record<string, TJSONSchema>
+      res?: { headers?: TJSONSchema }
+      yield?: TJSONSchema
+      returnType?: TJSONSchema
+    }
+    validation?: {
+      req?: Record<string, (value: any) => { errors?: any[] }>
+      yield?: (value: any) => { errors?: any[] }
+    }
+    validateYields?: boolean
+  }
+  handler: (ctx: TContext, req?: any) => Promise<{ stream: AsyncGenerator<any, any, unknown>; initialHeaders?: Record<string, string> }>
+}

package/agent_config/claude-code/skills/ts-procedures-scaffold/templates/express-rpc.md

@@ -1,137 +0,0 @@
-# Express RPC Template: {{Name}}
-
-## Implementation — `{{Name}}.rpc.ts`
-
-```typescript
-import { Procedures } from 'ts-procedures'
-import { defineErrorTaxonomy } from 'ts-procedures/express-rpc'
-import { ExpressRPCAppBuilder } from 'ts-procedures/express-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 }
-  }
-)
-
-// ─── Error Taxonomy ───────────────────────────────────────
-// Declare the error classes this service throws. Framework errors
-// (ProcedureValidationError → 400, ctx.error() → 500) are caught by the
-// default taxonomy automatically. Add your own classes here — handlers just
-// `throw` them and the builder serializes via this map. See
-// docs/http-integrations.md#error-handling for the full contract.
-
-const {{name}}Errors = defineErrorTaxonomy({
-  // Example — replace with your app's error classes:
-  // NotFoundError: { class: NotFoundError, statusCode: 404 },
-  // AuthError:     { class: AuthError,     statusCode: 401 },
-})
-
-// ─── Express App Builder ──────────────────────────────────
-
-export const {{name}}App = new ExpressRPCAppBuilder({
-  pathPrefix: '/api',
-  errors: {{name}}Errors,
-  unknownError: {
-    statusCode: 500,
-    toResponse: () => ({ name: 'InternalServerError', message: 'Unexpected error' }),
-    onCatch: (err, { procedure }) => console.error(`[${procedure.name}]`, err),
-  },
-})
-  .register(RPC, async (req) => ({
-    userId: req.headers['x-user-id'] as string || 'anonymous',
-    requestId: req.headers['x-request-id'] as string || 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 supertest from 'supertest'
-import { {{name}}App } from './{{Name}}.rpc'
-
-describe('{{Name}} RPC', () => {
-  test('GET item returns expected result', async () => {
-    const res = await supertest({{name}}App)
-      .post('/api/{{name}}/get-item/1')
-      .send({ id: 'item-1' })
-      .expect(200)
-
-    expect(res.body).toEqual({ id: 'item-1', name: 'Example' })
-  })
-
-  test('returns 400 for invalid params', async () => {
-    const res = await supertest({{name}}App)
-      .post('/api/{{name}}/get-item/1')
-      .send({})
-      .expect(400)
-
-    expect(res.body.error).toBeDefined()
-  })
-
-  test('LIST items returns array', async () => {
-    const res = await supertest({{name}}App)
-      .post('/api/{{name}}/list-items/1')
-      .send({ page: 1, limit: 10 })
-      .expect(200)
-
-    expect(res.body).toHaveProperty('items')
-    expect(res.body).toHaveProperty('total')
-  })
-})
-```

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

@@ -1,173 +0,0 @@
-# Hono API Template: {{Name}}
-
-## Implementation — `{{Name}}.api.ts`
-
-```typescript
-import { Procedures } from 'ts-procedures'
-import { defineErrorTaxonomy } from 'ts-procedures/hono-api'
-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
-  }
-)
-
-// ─── Error Taxonomy ───────────────────────────────────────
-// Declare the error classes this service throws. Framework errors
-// (ProcedureValidationError → 400, ctx.error() → 500) are caught by the
-// default taxonomy automatically. Add your own classes here — handlers just
-// `throw` them and the builder serializes via this map. See
-// docs/http-integrations.md#error-handling for the full contract.
-
-const {{name}}Errors = defineErrorTaxonomy({
-  // Example — replace with your app's error classes:
-  // NotFoundError: { class: NotFoundError, statusCode: 404 },
-  // AuthError:     { class: AuthError,     statusCode: 401 },
-})
-
-// ─── Hono App Builder ─────────────────────────────────────
-
-export const {{name}}App = new HonoAPIAppBuilder({
-  pathPrefix: '/api',
-  errors: {{name}}Errors,
-  unknownError: {
-    statusCode: 500,
-    toResponse: () => ({ name: 'InternalServerError', message: 'Unexpected error' }),
-    onCatch: (err, { procedure }) => console.error(`[${procedure.name}]`, err),
-  },
-})
-  .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 or compose with DocRegistry from 'ts-procedures/http-docs'
-```
-
-## 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)
-  })
-})
-```