ts-procedures 8.5.0 → 9.0.0

package/src/adapters/hono/__fixtures__/parity-envelope.json

@@ -0,0 +1,389 @@
+{
+  "basePath": "/api",
+  "headers": [],
+  "errors": [
+    {
+      "name": "ProcedureValidationError",
+      "statusCode": 400,
+      "description": "Schema validation failed for the procedure input parameters.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "const": "ProcedureValidationError"
+          },
+          "procedureName": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "errors": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "instancePath": {
+                  "type": "string"
+                },
+                "message": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "required": [
+          "name",
+          "procedureName",
+          "message"
+        ]
+      }
+    },
+    {
+      "name": "ProcedureYieldValidationError",
+      "statusCode": 500,
+      "description": "Schema validation failed for a yielded value in a streaming procedure.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "const": "ProcedureYieldValidationError"
+          },
+          "procedureName": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "errors": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "instancePath": {
+                  "type": "string"
+                },
+                "message": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "required": [
+          "name",
+          "procedureName",
+          "message"
+        ]
+      }
+    },
+    {
+      "name": "ProcedureError",
+      "statusCode": 500,
+      "description": "An error thrown from within a procedure handler via ctx.error().",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "const": "ProcedureError"
+          },
+          "procedureName": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          },
+          "meta": {
+            "type": "object"
+          }
+        },
+        "required": [
+          "name",
+          "procedureName",
+          "message"
+        ]
+      }
+    },
+    {
+      "name": "ProcedureRegistrationError",
+      "statusCode": 500,
+      "description": "An invalid schema or configuration was detected at procedure registration time.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "const": "ProcedureRegistrationError"
+          },
+          "procedureName": {
+            "type": "string"
+          },
+          "message": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "name",
+          "procedureName",
+          "message"
+        ]
+      }
+    },
+    {
+      "name": "Teapot",
+      "statusCode": 418,
+      "description": "Short and stout.",
+      "schema": {
+        "type": "object",
+        "properties": {
+          "name": {
+            "type": "string",
+            "const": "Teapot"
+          },
+          "message": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "name",
+          "message"
+        ]
+      }
+    }
+  ],
+  "routes": [
+    {
+      "kind": "rpc",
+      "name": "GetUser",
+      "version": 1,
+      "scope": "users",
+      "path": "/api/users/get-user/1",
+      "method": "post",
+      "jsonSchema": {
+        "body": {
+          "type": "object",
+          "required": [
+            "id"
+          ],
+          "properties": {
+            "id": {
+              "type": "string"
+            }
+          }
+        },
+        "response": {
+          "type": "object",
+          "required": [
+            "id",
+            "name"
+          ],
+          "properties": {
+            "id": {
+              "type": "string"
+            },
+            "name": {
+              "type": "string"
+            }
+          }
+        }
+      },
+      "errors": [
+        "Teapot"
+      ]
+    },
+    {
+      "kind": "stream",
+      "name": "WatchUser",
+      "version": 2,
+      "scope": [
+        "users",
+        "live"
+      ],
+      "path": "/api/users/live/watch-user/2",
+      "methods": [
+        "post",
+        "get"
+      ],
+      "streamMode": "sse",
+      "jsonSchema": {
+        "params": {
+          "type": "object",
+          "required": [
+            "id"
+          ],
+          "properties": {
+            "id": {
+              "type": "string"
+            }
+          }
+        },
+        "yieldType": {
+          "type": "object",
+          "description": "SSE message envelope. The data field contains the procedure yield value.",
+          "required": [
+            "data",
+            "event",
+            "id"
+          ],
+          "properties": {
+            "data": {
+              "type": "object",
+              "required": [
+                "at"
+              ],
+              "properties": {
+                "at": {
+                  "type": "number"
+                }
+              }
+            },
+            "event": {
+              "type": "string"
+            },
+            "id": {
+              "type": "string"
+            },
+            "retry": {
+              "type": "number"
+            }
+          }
+        },
+        "returnType": {
+          "type": "object",
+          "required": [
+            "total"
+          ],
+          "properties": {
+            "total": {
+              "type": "number"
+            }
+          }
+        }
+      }
+    },
+    {
+      "kind": "api",
+      "name": "UpdateUser",
+      "scope": "users",
+      "path": "/users/:id",
+      "method": "put",
+      "fullPath": "/api/users/:id",
+      "jsonSchema": {
+        "req": {
+          "pathParams": {
+            "type": "object",
+            "required": [
+              "id"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              }
+            }
+          },
+          "query": {
+            "type": "object",
+            "properties": {
+              "dryRun": {
+                "type": "boolean"
+              }
+            }
+          },
+          "body": {
+            "type": "object",
+            "required": [
+              "name"
+            ],
+            "properties": {
+              "name": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "res": {
+          "body": {
+            "type": "object",
+            "required": [
+              "id",
+              "name"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              }
+            }
+          },
+          "headers": {
+            "type": "object",
+            "required": [
+              "x-rev"
+            ],
+            "properties": {
+              "x-rev": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      },
+      "successStatus": 200,
+      "errors": [
+        "Teapot"
+      ]
+    },
+    {
+      "kind": "http-stream",
+      "name": "TailUser",
+      "scope": "users",
+      "path": "/users/:id/tail",
+      "method": "get",
+      "fullPath": "/api/users/:id/tail",
+      "streamMode": "sse",
+      "jsonSchema": {
+        "req": {
+          "pathParams": {
+            "type": "object",
+            "required": [
+              "id"
+            ],
+            "properties": {
+              "id": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "yield": {
+          "type": "object",
+          "required": [
+            "line"
+          ],
+          "properties": {
+            "line": {
+              "type": "string"
+            }
+          }
+        },
+        "returnType": {
+          "type": "object",
+          "required": [
+            "lines"
+          ],
+          "properties": {
+            "lines": {
+              "type": "number"
+            }
+          }
+        }
+      }
+    }
+  ]
+}

package/src/adapters/hono/envelope-parity.test.ts

@@ -0,0 +1,126 @@
+import { readFile } from 'node:fs/promises'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { Type } from 'typebox'
+import { Procedures } from '../../core/procedures.js'
+import { HonoAppBuilder, defineErrorTaxonomy } from './index.js'
+import type { RPCConfig } from '../../server/types.js'
+
+/**
+ * THE envelope contract test: the v9 builder must emit a DocEnvelope
+ * deep-equal to what v8.6.0 emitted for the same procedure set. The fixture
+ * was captured from the v8 build by `tools/capture-parity-envelope.mjs` —
+ * the procedure set below is that script's twin and MUST stay in sync with it.
+ *
+ * The envelope is codegen's input; if this test fails, generated client output
+ * WILL drift.
+ *
+ * ONE documented deviation from the raw v8 capture: v8's CreateHttpStream
+ * dropped the `yield` schema (and `res.headers`) from http-stream route docs —
+ * the registration stored `yieldType` while the doc builder read `yield`. v9
+ * fixes that, so the fixture's TailUser route was patched to include the
+ * `yield` schema the builder now (correctly) emits. Everything else is the
+ * untouched v8 capture.
+ */
+class TeapotError extends Error {}
+
+describe('DocEnvelope parity with v8.6.0', () => {
+  it('emits a deep-equal envelope for the reference procedure set', async () => {
+    const factory = Procedures<unknown, RPCConfig>()
+    const { Create, CreateStream, CreateHttp, CreateHttpStream } = factory
+
+    Create(
+      'GetUser',
+      {
+        scope: 'users',
+        version: 1,
+        errors: ['Teapot'],
+        description: 'Fetch one user',
+        schema: {
+          params: Type.Object({ id: Type.String() }),
+          returnType: Type.Object({ id: Type.String(), name: Type.String() }),
+        },
+      },
+      async (_ctx, params) => ({ id: params.id, name: 'x' }),
+    )
+
+    CreateStream(
+      'WatchUser',
+      {
+        scope: ['users', 'live'],
+        version: 2,
+        schema: {
+          params: Type.Object({ id: Type.String() }),
+          yieldType: Type.Object({ at: Type.Number() }),
+          returnType: Type.Object({ total: Type.Number() }),
+        },
+      },
+      async function* () {
+        yield { at: 1 }
+        return { total: 1 }
+      },
+    )
+
+    CreateHttp(
+      'UpdateUser',
+      {
+        path: '/users/:id',
+        method: 'put',
+        successStatus: 200,
+        scope: 'users',
+        errors: ['Teapot'],
+        schema: {
+          req: {
+            pathParams: Type.Object({ id: Type.String() }),
+            query: Type.Object({ dryRun: Type.Optional(Type.Boolean()) }),
+            body: Type.Object({ name: Type.String() }),
+          },
+          res: {
+            body: Type.Object({ id: Type.String(), name: Type.String() }),
+            headers: Type.Object({ 'x-rev': Type.String() }),
+          },
+        },
+      },
+      async (_ctx, req) => ({
+        body: { id: req.pathParams.id, name: req.body.name },
+        headers: { 'x-rev': '1' },
+      }),
+    )
+
+    CreateHttpStream(
+      'TailUser',
+      {
+        path: '/users/:id/tail',
+        method: 'get',
+        scope: 'users',
+        schema: {
+          req: { pathParams: Type.Object({ id: Type.String() }) },
+          yield: Type.Object({ line: Type.String() }),
+          returnType: Type.Object({ lines: Type.Number() }),
+        },
+      },
+      async function* () {
+        yield { line: 'a' }
+        return { lines: 1 }
+      },
+    )
+
+    const taxonomy = defineErrorTaxonomy({
+      Teapot: { class: TeapotError, statusCode: 418, description: 'Short and stout.' },
+    })
+
+    const builder = new HonoAppBuilder({ pathPrefix: '/api', errors: taxonomy })
+    builder.register(factory, {})
+    builder.build()
+
+    const fixturePath = resolve(
+      dirname(fileURLToPath(import.meta.url)),
+      '__fixtures__/parity-envelope.json',
+    )
+    const expected = JSON.parse(await readFile(fixturePath, 'utf-8'))
+    const actual = JSON.parse(JSON.stringify(builder.toDocEnvelope()))
+
+    expect(actual).toEqual(expected)
+  })
+})

package/src/{implementations/http → adapters}/hono/handlers/http-stream.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test } from 'vitest'
 import { Hono } from 'hono'
 import { Type } from 'typebox'
-import { Procedures } from '../../../../index.js'
+import { Procedures } from '../../../core/procedures.js'
 import { installHttpStreamRoute } from './http-stream.js'
 
 function buildApp(setup: (P: ReturnType<typeof Procedures<{ uid: string }>>) => void, cfg: any = {}) {

package/src/adapters/hono/handlers/http-stream.ts

@@ -0,0 +1,73 @@
+import type { Context, Hono } from 'hono'
+import { streamSSE } from 'hono/streaming'
+import type { THttpStreamProcedureRegistration } from '../../../core/types.js'
+import { dispatchMidStreamError, dispatchPreStreamError } from '../../../server/errors/dispatch.js'
+import { buildHttpStreamRouteDoc } from '../../../server/docs/http-stream-doc.js'
+import { resolveFactoryContext } from '../../../server/context.js'
+import { extractReqChannels } from '../../../server/request/params.js'
+import { parseQueryNative } from '../../../server/request/query.js'
+import { SseEventSequencer } from '../../../server/sse.js'
+import { honoRequestSource, respondToDispatch } from '../request.js'
+import { midStreamErrorConfig, preStreamErrorConfig } from '../types.js'
+import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem } from '../types.js'
+
+export function installHttpStreamRoute(params: {
+  app: Hono
+  procedure: THttpStreamProcedureRegistration<any>
+  factoryItem: HonoFactoryItem
+  cfg: HonoAppBuilderConfig
+  docs: DocAccumulator
+}): void {
+  const { app, procedure, factoryItem, cfg, docs } = params
+  const queryParser = cfg.api?.queryParser ?? parseQueryNative
+
+  const route = buildHttpStreamRouteDoc(procedure, cfg.pathPrefix, factoryItem.extendProcedureDoc as any)
+  docs.push(route)
+
+  const reqSchema = procedure.config.schema?.req
+
+  app.on(procedure.config.method.toUpperCase(), route.fullPath, async (c: Context) => {
+    try {
+      const context = await resolveFactoryContext(factoryItem.factoryContext, c)
+
+      const reqParams = reqSchema
+        ? await extractReqChannels(honoRequestSource(c), procedure.config.method, reqSchema as Record<string, unknown>, queryParser)
+        : undefined
+
+      const { stream: gen, initialHeaders } = await procedure.handler(
+        { ...context, signal: c.req.raw.signal },
+        reqParams,
+      )
+
+      if (initialHeaders) {
+        for (const [k, v] of Object.entries(initialHeaders)) c.header(k, v)
+      }
+
+      cfg.stream?.onStreamStart?.(procedure, c, 'sse')
+
+      return streamSSE(c, async (stream) => {
+        const events = new SseEventSequencer((e) => stream.writeSSE(e), procedure.name)
+        try {
+          await events.pump(gen)
+        } catch (error) {
+          const dispatched = await dispatchMidStreamError({
+            err: error,
+            procedure,
+            raw: c,
+            cfg: midStreamErrorConfig(cfg),
+          })
+          await events.writeError(dispatched)
+          if (dispatched.runOnCatch) await dispatched.runOnCatch()
+        } finally {
+          cfg.stream?.onStreamEnd?.(procedure, c, 'sse')
+          cfg.onRequestEnd?.(c)
+        }
+      })
+    } catch (error) {
+      return respondToDispatch(
+        c,
+        await dispatchPreStreamError({ err: error, procedure, raw: c, cfg: preStreamErrorConfig(cfg) }),
+      )
+    }
+  })
+}

package/src/{implementations/http → adapters}/hono/handlers/http.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, test, vi } from 'vitest'
 import { Hono } from 'hono'
 import { Type } from 'typebox'
-import { Procedures } from '../../../../index.js'
+import { Procedures } from '../../../core/procedures.js'
 import { installHttpRoute } from './http.js'
 
 function buildApp(setup: (P: ReturnType<typeof Procedures<{ uid: string }>>) => void, cfg: any = {}) {

package/src/adapters/hono/handlers/http.ts

@@ -0,0 +1,70 @@
+import type { Context, Hono } from 'hono'
+import type { THttpProcedureRegistration } from '../../../core/types.js'
+import { dispatchPreStreamError } from '../../../server/errors/dispatch.js'
+import { buildHttpRouteDoc } from '../../../server/docs/http-doc.js'
+import { resolveFactoryContext } from '../../../server/context.js'
+import { defaultSuccessStatus, extractReqChannels } from '../../../server/request/params.js'
+import { parseQueryNative } from '../../../server/request/query.js'
+import { honoRequestSource, respondToDispatch } from '../request.js'
+import { preStreamErrorConfig } from '../types.js'
+import type { DocAccumulator, HonoAppBuilderConfig, HonoFactoryItem } from '../types.js'
+
+export function installHttpRoute(params: {
+  app: Hono
+  procedure: THttpProcedureRegistration<any>
+  factoryItem: HonoFactoryItem
+  cfg: HonoAppBuilderConfig
+  docs: DocAccumulator
+}): void {
+  const { app, procedure, factoryItem, cfg, docs } = params
+  const queryParser = cfg.api?.queryParser ?? parseQueryNative
+
+  const route = buildHttpRouteDoc(procedure, cfg.pathPrefix, factoryItem.extendProcedureDoc as any)
+  docs.push(route)
+
+  const successStatus = procedure.config.successStatus ?? defaultSuccessStatus(procedure.config.method)
+  const reqSchema = procedure.config.schema?.req
+
+  app.on(procedure.config.method.toUpperCase(), route.fullPath, async (c: Context) => {
+    try {
+      const context = await resolveFactoryContext(factoryItem.factoryContext, c)
+
+      const reqParams = reqSchema
+        ? await extractReqChannels(honoRequestSource(c), procedure.config.method, reqSchema, queryParser)
+        : undefined
+
+      const result = await procedure.handler({ ...context, signal: c.req.raw.signal }, reqParams)
+
+      cfg.api?.onSuccess?.(procedure, c)
+
+      // The `{ body, headers }` envelope is OPT-IN via `schema.res.headers`: when
+      // the route declares response headers, the handler returns `{ body, headers }`;
+      // otherwise its return value IS the body. Gating on the schema (rather than
+      // duck-typing the result for a `body`/`headers` key) lets a domain object
+      // safely carry its own `body`/`headers` field without being unwrapped.
+      const hasResHeaders = procedure.config.schema?.res?.headers != null
+      const { body, headers } = hasResHeaders
+        ? ((result ?? {}) as { body?: unknown; headers?: unknown })
+        : { body: result, headers: undefined }
+
+      if (headers && typeof headers === 'object') {
+        for (const [k, v] of Object.entries(headers as Record<string, string>)) c.header(k, v)
+      }
+
+      // No body to send — a 204 status, or an `undefined` return (a `void`
+      // handler, or a headers-only `res: { headers }` envelope). Emit a clean
+      // bodyless response instead of `c.json(undefined)`, which would send an
+      // empty, unparseable body under an `application/json` content-type.
+      if (successStatus === 204 || body === undefined) {
+        return c.body(null, successStatus as any)
+      }
+
+      return c.json(body, successStatus as any)
+    } catch (error) {
+      return respondToDispatch(
+        c,
+        await dispatchPreStreamError({ err: error, procedure, raw: c, cfg: preStreamErrorConfig(cfg) }),
+      )
+    }
+  })
+}

package/src/{implementations/http → adapters}/hono/handlers/rpc.test.ts

@@ -1,8 +1,8 @@
 import { describe, expect, test, vi } from 'vitest'
 import { Hono } from 'hono'
 import { Type } from 'typebox'
-import { Procedures } from '../../../../index.js'
-import type { RPCConfig } from '../../../types.js'
+import { Procedures } from '../../../core/procedures.js'
+import type { RPCConfig } from '../../../server/types.js'
 import { installRpcRoute } from './rpc.js'
 
 function buildApp(register: (factory: ReturnType<typeof Procedures<{ userId: string }, RPCConfig>>) => void, cfg: any = {}) {