ts-procedures 7.3.0 → 8.1.0

package/src/implementations/http/hono/types.ts

@@ -0,0 +1,93 @@
+import type { Context, Hono } from 'hono'
+import type { ErrorTaxonomy, UnknownErrorConfig } from '../error-taxonomy.js'
+import type {
+  AnyProcedureRegistration,
+  OnRequestErrorObserver,
+  OnMidStreamError,
+  PreStreamOnError,
+} from '../error-dispatch.js'
+import type {
+  ProceduresFactory,
+  ExtractContext,
+  StreamMode,
+  AnyHttpRouteDoc,
+  RPCHttpRouteDoc,
+  APIHttpRouteDoc,
+  StreamHttpRouteDoc,
+  HttpStreamRouteDoc,
+} from '../../types.js'
+import type {
+  TProcedureRegistration,
+  TStreamProcedureRegistration,
+  THttpProcedureRegistration,
+  THttpStreamProcedureRegistration,
+} from '../../../types.js'
+
+export type { AnyProcedureRegistration } from '../error-dispatch.js'
+
+/** Default query parser using URLSearchParams. */
+export type QueryParser = (queryString: string) => Record<string, unknown>
+
+export type OnRequestErrorContext = {
+  err: unknown
+  procedure: AnyProcedureRegistration
+  raw: Context
+}
+
+export type ExtendProcedureDoc = (params: {
+  base: RPCHttpRouteDoc | APIHttpRouteDoc | StreamHttpRouteDoc | HttpStreamRouteDoc
+  procedure: AnyProcedureRegistration
+}) => Record<string, unknown>
+
+export type HonoFactoryItem<TFactory extends ProceduresFactory = ProceduresFactory> = {
+  factory: TFactory
+  factoryContext:
+    | ExtractContext<TFactory>
+    | ((c: Context) => ExtractContext<TFactory> | Promise<ExtractContext<TFactory>>)
+  streamMode?: StreamMode
+  extendProcedureDoc?: ExtendProcedureDoc
+}
+
+export type HonoAppBuilderConfig<TStreamErrorData = unknown> = {
+  /** Existing Hono app. If omitted, a new instance is created. */
+  app?: Hono
+  /** Path prefix applied to every route across all kinds. */
+  pathPrefix?: string
+
+  // Error handling — peers
+  errors?: ErrorTaxonomy
+  unknownError?: UnknownErrorConfig
+  onError?: PreStreamOnError
+  /** Cross-cutting observer — fires for every caught error before dispatch. */
+  onRequestError?: OnRequestErrorObserver
+
+  // Lifecycle (every kind)
+  onRequestStart?: (c: Context) => void
+  onRequestEnd?: (c: Context) => void
+
+  // Kind-specific blocks
+  rpc?: {
+    onSuccess?: (procedure: TProcedureRegistration, c: Context) => void
+  }
+  api?: {
+    queryParser?: QueryParser
+    onSuccess?: (procedure: THttpProcedureRegistration<any>, c: Context) => void
+  }
+  stream?: {
+    /** Default for both rpc-stream and http-stream. */
+    defaultStreamMode?: StreamMode
+    onStreamStart?: (
+      procedure: TStreamProcedureRegistration | THttpStreamProcedureRegistration<any>,
+      c: Context,
+      streamMode: StreamMode,
+    ) => void
+    onStreamEnd?: (
+      procedure: TStreamProcedureRegistration | THttpStreamProcedureRegistration<any>,
+      c: Context,
+      streamMode: StreamMode,
+    ) => void
+    onMidStreamError?: OnMidStreamError<TStreamErrorData>
+  }
+}
+
+export type DocAccumulator = AnyHttpRouteDoc[]

package/src/implementations/http/on-request-error.test.ts

@@ -2,7 +2,7 @@
 /**
  * Cross-builder tests for the `onRequestError` observer hook.
  *
- * Invariants verified once per builder:
+ * Invariants verified per builder:
  *   1. Fires exactly once for every caught error.
  *   2. Runs BEFORE dispatch (taxonomy / onError / hard default).
  *   3. Is awaited — async observer work completes before the response is sent.
@@ -12,82 +12,13 @@
  *      path still produces a response.
  */
 import { describe, expect, test, vi } from 'vitest'
-import request from 'supertest'
 import { Type } from 'typebox'
 import { Procedures } from '../../index.js'
-import { APIConfig, RPCConfig } from '../types.js'
-import { HonoAPIAppBuilder } from './hono-api/index.js'
-import { HonoRPCAppBuilder } from './hono-rpc/index.js'
-import { ExpressRPCAppBuilder } from './express-rpc/index.js'
-import { HonoStreamAppBuilder } from './hono-stream/index.js'
+import { RPCConfig } from '../types.js'
+import { HonoAppBuilder } from './hono/index.js'
 
-describe('onRequestError — HonoAPIAppBuilder', () => {
-  function boomApp(config: ConstructorParameters<typeof HonoAPIAppBuilder>[0]) {
-    const API = Procedures<{}, APIConfig>()
-    API.Create(
-      'Boom',
-      { path: '/boom', method: 'get', schema: { returnType: Type.Object({}) } },
-      async () => {
-        throw new TypeError('boom')
-      }
-    )
-    return new HonoAPIAppBuilder(config).register(API, () => ({})).build()
-  }
-
-  test('fires exactly once and before dispatch', async () => {
-    const order: string[] = []
-    const onRequestError = vi.fn(() => {
-      order.push('observer')
-    })
-    const onError = vi.fn((_p: any, c: any) => {
-      order.push('onError')
-      return c.json({ handled: true }, 418)
-    })
-
-    const app = boomApp({ onRequestError, onError })
-    await app.request('/boom')
-    expect(onRequestError).toHaveBeenCalledTimes(1)
-    expect(order).toEqual(['observer', 'onError'])
-  })
-
-  test('is awaited — async work completes before response is sent', async () => {
-    const log: string[] = []
-    const onRequestError = async () => {
-      await new Promise((r) => setTimeout(r, 5))
-      log.push('observer-done')
-    }
-    const app = boomApp({
-      onRequestError,
-      onError: (_p, c) => {
-        log.push('onError-called')
-        return c.json({ ok: true }, 500)
-      },
-    })
-    await app.request('/boom')
-    expect(log).toEqual(['observer-done', 'onError-called'])
-  })
-
-  test('observer-thrown errors are swallowed — dispatch still produces a response', async () => {
-    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
-    const app = boomApp({
-      onRequestError: () => {
-        throw new Error('observer exploded')
-      },
-    })
-    const res = await app.request('/boom')
-    expect(res.status).toBe(500)
-    consoleSpy.mockRestore()
-  })
-
-  test('omitting observer preserves existing behavior', async () => {
-    const app = boomApp({ onError: (_p, c) => c.json({ ok: true }, 418) })
-    const res = await app.request('/boom')
-    expect(res.status).toBe(418)
-  })
-})
-
-describe('onRequestError — HonoRPCAppBuilder', () => {
-  function boomApp(config: ConstructorParameters<typeof HonoRPCAppBuilder>[0]) {
+describe('onRequestError — HonoAppBuilder (rpc kind)', () => {
+  function boomApp(config: ConstructorParameters<typeof HonoAppBuilder>[0]) {
     const RPC = Procedures<{}, RPCConfig>()
     RPC.Create(
       'Boom',
@@ -96,7 +27,7 @@ describe('onRequestError — HonoRPCAppBuilder', () => {
         throw new TypeError('boom')
       }
     )
-    return new HonoRPCAppBuilder(config).register(RPC, () => ({})).build()
+    return new HonoAppBuilder(config).register(RPC, () => ({})).build()
   }
 
   test('fires once; runs before onError', async () => {
@@ -128,51 +59,13 @@ describe('onRequestError — HonoRPCAppBuilder', () => {
   })
 })
 
-describe('onRequestError — ExpressRPCAppBuilder', () => {
-  function boomApp(config: ConstructorParameters<typeof ExpressRPCAppBuilder>[0]) {
-    const RPC = Procedures<{}, RPCConfig>()
-    RPC.Create(
-      'Boom',
-      { scope: 'test', version: 1, schema: { params: Type.Object({}) } },
-      async () => {
-        throw new TypeError('boom')
-      }
-    )
-    return new ExpressRPCAppBuilder(config).register(RPC, () => ({})).build()
-  }
-
-  test('fires once; raw is { req, res }', async () => {
-    let rawSeen: any
-    const app = boomApp({
-      onRequestError: (ctx) => {
-        rawSeen = ctx.raw
-      },
-    })
-    await request(app).post('/test/boom/1').send({})
-    expect(rawSeen.req).toBeDefined()
-    expect(rawSeen.res).toBeDefined()
-  })
-
-  test('observer throws are swallowed', async () => {
-    const consoleSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
-    const app = boomApp({
-      onRequestError: () => {
-        throw new Error('observer bug')
-      },
-    })
-    const res = await request(app).post('/test/boom/1').send({})
-    expect(res.status).toBe(500)
-    consoleSpy.mockRestore()
-  })
-})
-
-describe('onRequestError — HonoStreamAppBuilder (pre-stream)', () => {
-  function boomApp(config: ConstructorParameters<typeof HonoStreamAppBuilder>[0]) {
+describe('onRequestError — HonoAppBuilder (rpc-stream pre-stream)', () => {
+  function boomApp(config: ConstructorParameters<typeof HonoAppBuilder>[0]) {
     const RPC = Procedures<{}, RPCConfig>()
     RPC.CreateStream('Stream', { scope: 'test', version: 1 }, async function* () {
       yield { ok: true }
     })
-    return new HonoStreamAppBuilder(config)
+    return new HonoAppBuilder(config)
       .register(RPC, () => {
         throw new TypeError('context failed')
       })
@@ -199,3 +92,4 @@ describe('onRequestError — HonoStreamAppBuilder (pre-stream)', () => {
     consoleSpy.mockRestore()
   })
 })
+

package/src/implementations/http/route-errors.test.ts

@@ -3,10 +3,7 @@ import { describe, expect, test } from 'vitest'
 import { Type } from 'typebox'
 import { Procedures } from '../../index.js'
 import { APIConfig, RPCConfig } from '../types.js'
-import { HonoAPIAppBuilder } from './hono-api/index.js'
-import { HonoRPCAppBuilder } from './hono-rpc/index.js'
-import { ExpressRPCAppBuilder } from './express-rpc/index.js'
-import { HonoStreamAppBuilder } from './hono-stream/index.js'
+import { HonoAppBuilder } from './hono/index.js'
 import { DocRegistry } from './doc-registry.js'
 import { defineErrorTaxonomy } from './error-taxonomy.js'
 
@@ -26,39 +23,13 @@ const appErrors = defineErrorTaxonomy({
 })
 
 describe('per-route errors declaration', () => {
-  test('hono-api copies config.errors onto the route doc', () => {
-    const API = Procedures<{}, APIConfig<keyof typeof appErrors & string>>()
-    API.Create(
-      'GetUser',
-      {
-        path: '/users/:id',
-        method: 'get',
-        errors: ['UseCaseError', 'AuthError'],
-        schema: {
-          input: { pathParams: Type.Object({ id: Type.String() }) },
-          returnType: Type.Object({}),
-        },
-      },
-      async () => ({})
-    )
-    const builder = new HonoAPIAppBuilder().register(API, () => ({}))
-    builder.build()
-    expect(builder.docs[0]!.errors).toEqual(['UseCaseError', 'AuthError'])
-  })
+  // migrated to schema.req in Phase 3+ (CreateHttp)
+  test.todo('hono-api copies config.errors onto the route doc')
 
-  test('hono-api route doc omits errors when not declared', () => {
-    const API = Procedures<{}, APIConfig>()
-    API.Create(
-      'Health',
-      { path: '/health', method: 'get', schema: { returnType: Type.Object({}) } },
-      async () => ({})
-    )
-    const builder = new HonoAPIAppBuilder().register(API, () => ({}))
-    builder.build()
-    expect(builder.docs[0]!.errors).toBeUndefined()
-  })
+  // migrated to schema.req in Phase 3+ (CreateHttp)
+  test.todo('hono-api route doc omits errors when not declared')
 
-  test('hono-rpc copies config.errors onto the route doc', () => {
+  test('hono rpc copies config.errors onto the route doc', () => {
     const RPC = Procedures<{}, RPCConfig<keyof typeof appErrors & string>>()
     RPC.Create(
       'DoThing',
@@ -70,29 +41,12 @@ describe('per-route errors declaration', () => {
       },
       async () => ({})
     )
-    const builder = new HonoRPCAppBuilder().register(RPC, () => ({}))
+    const builder = new HonoAppBuilder().register(RPC, () => ({}))
     builder.build()
     expect(builder.docs[0]!.errors).toEqual(['UseCaseError'])
   })
 
-  test('express-rpc copies config.errors onto the route doc', () => {
-    const RPC = Procedures<{}, RPCConfig<keyof typeof appErrors & string>>()
-    RPC.Create(
-      'DoThing',
-      {
-        scope: 'things',
-        version: 1,
-        errors: ['AuthError'],
-        schema: { params: Type.Object({}) },
-      },
-      async () => ({})
-    )
-    const builder = new ExpressRPCAppBuilder().register(RPC, () => ({}))
-    builder.build()
-    expect(builder.docs[0]!.errors).toEqual(['AuthError'])
-  })
-
-  test('hono-stream copies config.errors onto the route doc', () => {
+  test('hono stream copies config.errors onto the route doc', () => {
     const Stream = Procedures<{}, RPCConfig<keyof typeof appErrors & string>>()
     Stream.CreateStream(
       'Watch',
@@ -101,7 +55,7 @@ describe('per-route errors declaration', () => {
         yield { ok: true }
       }
     )
-    const builder = new HonoStreamAppBuilder().register(Stream, () => ({}))
+    const builder = new HonoAppBuilder().register(Stream, () => ({}))
     builder.build()
     expect(builder.docs[0]!.errors).toEqual(['AuthError'])
   })
@@ -151,26 +105,6 @@ describe('DocRegistry with taxonomy input', () => {
     expect(count).toBe(1)
   })
 
-  test('registered route errors survive DocRegistry composition', () => {
-    const API = Procedures<{}, APIConfig<keyof typeof appErrors & string>>()
-    API.Create(
-      'GetUser',
-      {
-        path: '/users/:id',
-        method: 'get',
-        errors: ['UseCaseError'],
-        schema: {
-          input: { pathParams: Type.Object({ id: Type.String() }) },
-          returnType: Type.Object({}),
-        },
-      },
-      async () => ({})
-    )
-    const app = new HonoAPIAppBuilder().register(API, () => ({}))
-    app.build()
-
-    const envelope = new DocRegistry({ errors: appErrors }).from(app).toJSON()
-    const route = envelope.routes.find((r) => r.kind === 'api' && r.name === 'GetUser')
-    expect(route?.errors).toEqual(['UseCaseError'])
-  })
+  // migrated to schema.req in Phase 3+ (CreateHttp)
+  test.todo('registered route errors survive DocRegistry composition')
 })

package/src/implementations/types.ts

@@ -66,20 +66,28 @@ export interface APIConfig<TErrorKey extends string = string> {
   errors?: TErrorKey[]
 }
 
-export interface APIHttpRouteDoc extends APIConfig {
+export interface APIHttpRouteDoc {
   kind: 'api'
   name: string
+  scope?: string
+  path: string
+  method: HttpMethod
   /** Full resolved path including pathPrefix */
   fullPath: string
+  successStatus?: number
+  errors?: string[]
   jsonSchema: {
-    pathParams?: Record<string, unknown>
-    query?: Record<string, unknown>
-    body?: Record<string, unknown>
-    headers?: Record<string, unknown>
-    response?: Record<string, unknown>
+    req?: {
+      pathParams?: Record<string, unknown>
+      query?: Record<string, unknown>
+      body?: Record<string, unknown>
+      headers?: Record<string, unknown>
+    }
+    res?: {
+      body?: Record<string, unknown>
+      headers?: Record<string, unknown>
+    }
   }
-  /** Taxonomy keys for errors this route may emit. */
-  errors?: string[]
 }
 
 /**
@@ -121,6 +129,30 @@ export interface StreamHttpRouteDoc extends RPCConfig {
   errors?: string[]
 }
 
+export interface HttpStreamRouteDoc {
+  kind: 'http-stream'
+  name: string
+  scope?: string
+  path: string
+  method: HttpMethod
+  fullPath: string
+  streamMode: StreamMode
+  errors?: string[]
+  jsonSchema: {
+    req?: {
+      pathParams?: Record<string, unknown>
+      query?: Record<string, unknown>
+      body?: Record<string, unknown>
+      headers?: Record<string, unknown>
+    }
+    res?: {
+      headers?: Record<string, unknown>
+    }
+    yield?: Record<string, unknown>
+    returnType?: Record<string, unknown>
+  }
+}
+
 // ================
 // Utility types
 // ================
@@ -152,19 +184,22 @@ export type ExtractConfig<TFactory> = TFactory extends {
 export type ProceduresFactory = {
   getProcedures: () => Array<{
     name: string
+    kind?: import('../types.js').ProcedureKind
     isStream?: boolean
     config: any
     handler: (ctx: any, params?: any) => Promise<any> | AsyncGenerator<any, any, unknown>
   }>
   Create: (...args: any[]) => any
   CreateStream?: (...args: any[]) => any
+  CreateHttp?: (...args: any[]) => any
+  CreateHttpStream?: (...args: any[]) => any
 }
 
 // ================
 // DocRegistry types
 // ================
 
-export type AnyHttpRouteDoc = RPCHttpRouteDoc | APIHttpRouteDoc | StreamHttpRouteDoc
+export type AnyHttpRouteDoc = RPCHttpRouteDoc | APIHttpRouteDoc | StreamHttpRouteDoc | HttpStreamRouteDoc
 
 export interface DocSource<T = AnyHttpRouteDoc> {
   readonly docs: T[]