ts-procedures 8.5.0 → 9.0.0

package/src/{implementations/http/error-taxonomy.test.ts → server/errors/taxonomy.test.ts}

@@ -3,9 +3,9 @@ import {
   ProcedureError,
   ProcedureValidationError,
   ProcedureYieldValidationError,
-} from '../../errors.js'
-import type { TProcedureRegistration } from '../../index.js'
-import * as AJV from 'ajv'
+} from '../../core/errors.js'
+import type { TProcedureRegistration } from '../../core/types.js'
+import { Ajv } from 'ajv'
 import {
   defineErrorTaxonomy,
   resolveErrorResponse,
@@ -13,7 +13,7 @@ import {
   taxonomyToErrorDocs,
   defaultErrorSchema,
   defaultErrorBody,
-} from './error-taxonomy.js'
+} from './taxonomy.js'
 
 class UseCaseError extends Error {
   constructor(
@@ -34,7 +34,12 @@ class AuthError extends Error {
   }
 }
 
-const fakeProcedure = { name: 'Test', config: {}, handler: async () => {} } as unknown as TProcedureRegistration
+const fakeProcedure = {
+  name: 'Test',
+  kind: 'rpc',
+  config: {},
+  handler: async () => {},
+} as unknown as TProcedureRegistration
 
 describe('defineErrorTaxonomy', () => {
   test('validates exactly one discriminator per entry', () => {
@@ -78,8 +83,8 @@ describe('resolveErrorResponse', () => {
       procedure: fakeProcedure,
       raw: {},
     })
-    expect(resolved?.statusCode).toBe(422)
-    expect(resolved?.body).toEqual({ name: 'UseCaseError', message: 'external' })
+    expect(resolved!.statusCode).toBe(422)
+    expect(resolved!.body).toEqual({ name: 'UseCaseError', message: 'external' })
   })
 
   test('match predicate catches 3rd-party errors', () => {
@@ -97,8 +102,8 @@ describe('resolveErrorResponse', () => {
       procedure: fakeProcedure,
       raw: {},
     })
-    expect(resolved?.statusCode).toBe(409)
-    expect(resolved?.body).toEqual({ name: 'Conflict' })
+    expect(resolved!.statusCode).toBe(409)
+    expect(resolved!.body).toEqual({ name: 'Conflict' })
   })
 
   test('default toResponse emits { name, message } from entry key', () => {
@@ -111,7 +116,7 @@ describe('resolveErrorResponse', () => {
       procedure: fakeProcedure,
       raw: {},
     })
-    expect(resolved?.body).toEqual({ name: 'AuthError', message: 'unauthenticated' })
+    expect(resolved!.body).toEqual({ name: 'AuthError', message: 'unauthenticated' })
   })
 
   test('first matching entry wins — subclass declared before base', () => {
@@ -134,8 +139,8 @@ describe('resolveErrorResponse', () => {
       includeDefaults: false,
       raw: {},
     })
-    expect(resolved?.statusCode).toBe(400)
-    expect(resolved?.body).toEqual({ name: 'ProcedureValidationError', kind: 'validation' })
+    expect(resolved!.statusCode).toBe(400)
+    expect(resolved!.body).toEqual({ name: 'ProcedureValidationError', kind: 'validation' })
   })
 
   test('topological sort fixes a subclass that was declared after its base', () => {
@@ -160,8 +165,8 @@ describe('resolveErrorResponse', () => {
       includeDefaults: false,
       raw: {},
     })
-    expect(resolved?.statusCode).toBe(400)
-    expect(resolved?.body).toEqual({ name: 'ProcedureValidationError', kind: 'validation' })
+    expect(resolved!.statusCode).toBe(400)
+    expect(resolved!.body).toEqual({ name: 'ProcedureValidationError', kind: 'validation' })
   })
 
   test('falls through to unknownError when nothing matches', () => {
@@ -178,8 +183,8 @@ describe('resolveErrorResponse', () => {
       procedure: fakeProcedure,
       raw: {},
     })
-    expect(resolved?.statusCode).toBe(500)
-    expect(resolved?.body).toEqual({ name: 'InternalServerError' })
+    expect(resolved!.statusCode).toBe(500)
+    expect(resolved!.body).toEqual({ name: 'InternalServerError' })
   })
 
   test('returns null when nothing matches and no unknownError', () => {
@@ -201,8 +206,8 @@ describe('resolveErrorResponse', () => {
       procedure: fakeProcedure,
       raw: {},
     })
-    expect(resolved?.statusCode).toBe(400)
-    expect((resolved?.body as any).name).toBe('ProcedureValidationError')
+    expect(resolved!.statusCode).toBe(400)
+    expect((resolved!.body as any).name).toBe('ProcedureValidationError')
   })
 
   test('default taxonomy catches ProcedureYieldValidationError with status 500', () => {
@@ -211,8 +216,8 @@ describe('resolveErrorResponse', () => {
       procedure: fakeProcedure,
       raw: {},
     })
-    expect(resolved?.statusCode).toBe(500)
-    expect((resolved?.body as any).name).toBe('ProcedureYieldValidationError')
+    expect(resolved!.statusCode).toBe(500)
+    expect((resolved!.body as any).name).toBe('ProcedureYieldValidationError')
   })
 
   test('includeDefaults: false disables the default taxonomy', () => {
@@ -238,8 +243,8 @@ describe('resolveErrorResponse', () => {
       procedure: fakeProcedure,
       raw: {},
     })
-    expect(resolved?.statusCode).toBe(418)
-    expect(resolved?.body).toEqual({ name: 'ProcedureValidationError', overridden: true })
+    expect(resolved!.statusCode).toBe(418)
+    expect(resolved!.body).toEqual({ name: 'ProcedureValidationError', overridden: true })
   })
 
   test('onCatch is awaited via runOnCatch', async () => {
@@ -300,15 +305,15 @@ describe('resolveErrorResponse', () => {
       err: new AuthError('forbidden'),
       userTaxonomy: taxonomy,
       procedure: fakeProcedure,
-      raw: { marker: 'hono-context' },
+      raw: { marker: 'adapter-context' },
     })
     await resolved!.runOnCatch()
     expect(received.procedure).toBe(fakeProcedure)
     expect(received.key).toBe('AuthError')
-    expect(received.raw).toEqual({ marker: 'hono-context' })
+    expect(received.raw).toEqual({ marker: 'adapter-context' })
   })
 
-  test('defaultErrorTaxonomy exposes all four framework error mappings', () => {
+  test('defaultErrorTaxonomy exposes the framework error mappings', () => {
     expect(defaultErrorTaxonomy.ProcedureValidationError.statusCode).toBe(400)
     expect(defaultErrorTaxonomy.ProcedureYieldValidationError.statusCode).toBe(500)
     expect(defaultErrorTaxonomy.ProcedureError.statusCode).toBe(500)
@@ -335,8 +340,8 @@ describe('resolveErrorResponse', () => {
       procedure: fakeProcedure,
       raw: {},
     })
-    expect(resolved?.statusCode).toBe(422)
-    expect(resolved?.body).toEqual({ name: 'UseCaseError', message: 'public' })
+    expect(resolved!.statusCode).toBe(422)
+    expect(resolved!.body).toEqual({ name: 'UseCaseError', message: 'public' })
   })
 
   test('wrapped ProcedureError falls through default taxonomy to unknownError', () => {
@@ -353,8 +358,8 @@ describe('resolveErrorResponse', () => {
       procedure: fakeProcedure,
       raw: {},
     })
-    expect(resolved?.statusCode).toBe(500)
-    expect(resolved?.body).toEqual({ name: 'InternalServerError', type: 'TypeError' })
+    expect(resolved!.statusCode).toBe(500)
+    expect(resolved!.body).toEqual({ name: 'InternalServerError', type: 'TypeError' })
   })
 
   test('direct ProcedureError (no cause) still caught by default entry', () => {
@@ -364,8 +369,8 @@ describe('resolveErrorResponse', () => {
       procedure: fakeProcedure,
       raw: {},
     })
-    expect(resolved?.statusCode).toBe(500)
-    expect((resolved?.body as any).name).toBe('ProcedureError')
+    expect(resolved!.statusCode).toBe(500)
+    expect((resolved!.body as any).name).toBe('ProcedureError')
   })
 
   test('auto-injects name when toResponse omits it', () => {
@@ -383,7 +388,7 @@ describe('resolveErrorResponse', () => {
       procedure: fakeProcedure,
       raw: {},
     })
-    expect(resolved?.body).toEqual({ name: 'UseCaseError', message: 'ext', detail: 'int' })
+    expect(resolved!.body).toEqual({ name: 'UseCaseError', message: 'ext', detail: 'int' })
   })
 
   test('preserves explicit name in toResponse output', () => {
@@ -400,7 +405,7 @@ describe('resolveErrorResponse', () => {
       procedure: fakeProcedure,
       raw: {},
     })
-    expect((resolved?.body as any).name).toBe('CustomAlias')
+    expect((resolved!.body as any).name).toBe('CustomAlias')
   })
 
   test('defineErrorTaxonomy topologically sorts class entries (subclass before base)', () => {
@@ -427,7 +432,7 @@ describe('resolveErrorResponse', () => {
       procedure: fakeProcedure,
       raw: {},
     })
-    expect(resolved?.statusCode).toBe(400)
+    expect(resolved!.statusCode).toBe(400)
   })
 
   test('topological sort preserves declared order for unrelated classes', () => {
@@ -448,8 +453,9 @@ describe('taxonomyToErrorDocs', () => {
     })
     const docs = taxonomyToErrorDocs(taxonomy)
     const auth = docs.find((d) => d.name === 'AuthError')
-    expect(auth?.statusCode).toBe(401)
-    expect(auth?.schema).toEqual({
+    expect(auth).toBeDefined()
+    expect(auth!.statusCode).toBe(401)
+    expect(auth!.schema).toEqual({
       type: 'object',
       properties: {
         name: { type: 'string', const: 'AuthError' },
@@ -469,7 +475,7 @@ describe('taxonomyToErrorDocs', () => {
     })
     const docs = taxonomyToErrorDocs(taxonomy)
     const useCase = docs.find((d) => d.name === 'UseCaseError')
-    expect(useCase?.schema).toBeUndefined()
+    expect(useCase!.schema).toBeUndefined()
   })
 
   test('preserves an explicit schema untouched', () => {
@@ -490,7 +496,7 @@ describe('taxonomyToErrorDocs', () => {
     })
     const docs = taxonomyToErrorDocs(taxonomy)
     const useCase = docs.find((d) => d.name === 'UseCaseError')
-    expect(useCase?.schema).toBe(explicitSchema)
+    expect(useCase!.schema).toBe(explicitSchema)
   })
 })
 
@@ -529,7 +535,7 @@ describe('defaultErrorSchema', () => {
 // against the schema codegen turns into the client error class. If either side
 // changes shape, this fails before consumers see a mismatch.
 describe('defaultErrorBody / defaultErrorSchema invariant', () => {
-  const ajv = new AJV.Ajv()
+  const ajv = new Ajv()
 
   test('default body validates against the synthesized schema', () => {
     const schema = defaultErrorSchema('AuthError', { class: AuthError, statusCode: 401 })

package/src/{implementations/http/error-taxonomy.ts → server/errors/taxonomy.ts}

@@ -2,12 +2,12 @@ import {
   ProcedureError,
   ProcedureValidationError,
   ProcedureYieldValidationError,
-} from '../../errors.js'
-import type { TProcedureRegistration, TStreamProcedureRegistration, THttpProcedureRegistration, THttpStreamProcedureRegistration } from '../../index.js'
+} from '../../core/errors.js'
+import type { AnyProcedureRegistration } from '../../core/types.js'
 import type { ErrorDoc } from '../types.js'
 
 /** Any procedure registration — accepted by taxonomy callbacks. */
-export type TAnyProcedureRegistration = TProcedureRegistration | TStreamProcedureRegistration | THttpProcedureRegistration<any> | THttpStreamProcedureRegistration<any>
+export type TAnyProcedureRegistration = AnyProcedureRegistration<any, any>
 
 /**
  * An entry in an {@link ErrorTaxonomy}. Describes how to recognize a thrown
@@ -35,7 +35,7 @@ export type ErrorTaxonomyEntry<TError = any, TBody = unknown> = {
   toResponse?: (err: TError, meta: { key: string }) => TBody
   /**
    * Side effect on catch (logging, metrics). Awaited before the response is sent.
-   * `raw` is the framework-specific request context (e.g., Hono `Context`) —
+   * `raw` is the server-adapter-specific request context (e.g., Hono `Context`) —
    * cast as needed.
    */
   onCatch?: (
@@ -222,24 +222,15 @@ export function defaultErrorBody(key: string, err: unknown): { name: string; mes
  * Synthesizes the response-body JSON Schema for a taxonomy entry that ships
  * neither an explicit `schema` nor a custom `toResponse`.
  *
- * The common case for `defineErrorTaxonomy` is `{ class, statusCode }` only.
- * For those entries the default `toResponse` (see `resolveErrorResponse`) emits
- * exactly `{ name: <key>, message }`. Without a schema, `taxonomyToErrorDocs`
- * produced a schema-less `ErrorDoc`, and codegen (`emit-errors.ts`) only emits a
- * typed client error class for docs that carry a schema — so these entries
- * silently fell back to the untyped `ClientHttpError`, while framework errors
- * (which ship schemas) worked. That mismatch was confusing.
- *
- * By describing the default envelope here, the entry becomes self-describing and
- * codegen emits a typed client error class with zero ceremony from the consumer.
- *
  * Rules:
- * - Entry has an explicit `schema` → caller keeps it (this is not consulted).
+ * - Entry has an explicit `schema` → caller keeps it.
  * - Entry has a custom `toResponse` but no `schema` → returns `undefined`; the
  *   body shape is unknown and we never guess it.
  * - Entry has neither → returns the `{ name: const <key>, message }` schema that
  *   describes {@link defaultErrorBody} — the exact body the runtime serializes.
- *   (An invariant test keeps the two from drifting.)
+ *   (An invariant test keeps the two from drifting.) This makes bare
+ *   `{ class, statusCode }` entries self-describing so codegen emits a typed
+ *   client error class with zero ceremony from the consumer.
  */
 export function defaultErrorSchema(
   key: string,

package/src/server/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Transport-agnostic HTTP server layer.
+ *
+ * Everything a server adapter (Hono, Fastify, Express, ...) needs to serve the
+ * four procedure kinds without each adapter re-implementing the framework:
+ * route docs, error taxonomy + dispatch, request channel extraction, SSE
+ * metadata, path resolution, and the doc registry. Adapters are thin glue:
+ * read the request via their framework, call into this layer, write the
+ * response via their framework.
+ *
+ * No framework imports are allowed in this subtree (enforced by test).
+ */
+export * from './types.js'
+export * from './paths.js'
+export * from './context.js'
+export * from './sse.js'
+export { BODY_METHODS, defaultSuccessStatus, extractReqChannels } from './request/params.js'
+export type { RequestSource } from './request/params.js'
+export { parseQueryNative, extractQuery } from './request/query.js'
+export type { QueryParser } from './request/query.js'
+export * from './errors/taxonomy.js'
+export * from './errors/dispatch.js'
+export { buildRpcRouteDoc } from './docs/rpc-doc.js'
+export { buildStreamRouteDoc } from './docs/stream-doc.js'
+export { buildHttpRouteDoc } from './docs/http-doc.js'
+export { buildHttpStreamRouteDoc } from './docs/http-stream-doc.js'
+export { DocRegistry } from './doc-registry.js'
+export { writeDocEnvelope } from './doc-envelope.js'
+export type { DocEnvelopeSource } from './doc-envelope.js'

package/src/server/no-framework-imports.test.ts

@@ -0,0 +1,43 @@
+import { readFile, readdir } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Enforces the transport-agnostic guarantee: nothing under src/server may
+ * import a web framework. Adapters (src/adapters/*) are the only place
+ * framework imports belong.
+ */
+const FRAMEWORKS = ['hono', 'astro', 'express', 'fastify']
+const IMPORT_RE = new RegExp(
+  `(?:from\\s+|import\\s*\\()\\s*['"](?:${FRAMEWORKS.join('|')})(?:/|['"])`,
+)
+
+async function collectSourceFiles(dir: string): Promise<string[]> {
+  const entries = await readdir(dir, { withFileTypes: true })
+  const files: string[] = []
+  for (const entry of entries) {
+    const full = join(dir, entry.name)
+    if (entry.isDirectory()) {
+      files.push(...(await collectSourceFiles(full)))
+    } else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.test.ts')) {
+      files.push(full)
+    }
+  }
+  return files
+}
+
+describe('server layer is framework-free', () => {
+  it('no file under src/server imports hono/astro/express/fastify', async () => {
+    const serverDir = dirname(fileURLToPath(import.meta.url))
+    const files = await collectSourceFiles(serverDir)
+    expect(files.length).toBeGreaterThan(10)
+
+    const offenders: string[] = []
+    for (const file of files) {
+      const content = await readFile(file, 'utf-8')
+      if (IMPORT_RE.test(content)) offenders.push(file)
+    }
+    expect(offenders, 'framework imports found in server layer').toEqual([])
+  })
+})

package/src/server/paths.test.ts

@@ -0,0 +1,141 @@
+import { describe, expect, test } from 'vitest'
+import type { AnyProcedureRegistration, ProcedureKind } from '../core/types.js'
+import { makeRoutePath, resolveFullPath } from './paths.js'
+
+function rpcLike(
+  kind: 'rpc' | 'rpc-stream',
+  name: string,
+  scope: string | string[],
+  version: number,
+): AnyProcedureRegistration<any, any> {
+  return {
+    name,
+    kind,
+    config: { scope, version },
+    handler: async () => {},
+  } as unknown as AnyProcedureRegistration<any, any>
+}
+
+function httpLike(
+  kind: 'http' | 'http-stream',
+  name: string,
+  path: string,
+): AnyProcedureRegistration<any, any> {
+  return {
+    name,
+    kind,
+    config: { path, method: 'get' },
+    handler: async () => {},
+  } as unknown as AnyProcedureRegistration<any, any>
+}
+
+describe('makeRoutePath', () => {
+  describe('rpc / rpc-stream kinds', () => {
+    test('builds /{kebab(scope)}/{kebab(name)}/{version}', () => {
+      const path = makeRoutePath({
+        procedure: rpcLike('rpc', 'GetUser', 'userAccounts', 1),
+        prefix: undefined,
+      })
+      expect(path).toBe('/user-accounts/get-user/1')
+    })
+
+    test.each(['rpc', 'rpc-stream'] as ProcedureKind[])(
+      '%s kind uses the rpc path shape',
+      (kind) => {
+        const path = makeRoutePath({
+          procedure: rpcLike(kind as 'rpc' | 'rpc-stream', 'Echo', 'echo', 2),
+          prefix: undefined,
+        })
+        expect(path).toBe('/echo/echo/2')
+      },
+    )
+
+    test('prefix without a leading slash is normalized', () => {
+      const path = makeRoutePath({
+        procedure: rpcLike('rpc', 'GetUser', 'users', 1),
+        prefix: 'api',
+      })
+      expect(path).toBe('/api/users/get-user/1')
+    })
+
+    test('prefix with a leading slash is kept as-is', () => {
+      const path = makeRoutePath({
+        procedure: rpcLike('rpc', 'GetUser', 'users', 1),
+        prefix: '/api',
+      })
+      expect(path).toBe('/api/users/get-user/1')
+    })
+
+    test('empty prefix adds nothing', () => {
+      const path = makeRoutePath({
+        procedure: rpcLike('rpc', 'GetUser', 'users', 1),
+        prefix: '',
+      })
+      expect(path).toBe('/users/get-user/1')
+    })
+
+    test('array scope joins segments with "/" (each kebab-cased)', () => {
+      const path = makeRoutePath({
+        procedure: rpcLike('rpc-stream', 'WatchOrders', ['admin', 'orderEvents'], 3),
+        prefix: '/api',
+      })
+      expect(path).toBe('/api/admin/order-events/watch-orders/3')
+    })
+  })
+
+  describe('http / http-stream kinds', () => {
+    test('http kind resolves prefix + config.path', () => {
+      const path = makeRoutePath({
+        procedure: httpLike('http', 'GetUser', '/users/:id'),
+        prefix: '/api',
+      })
+      expect(path).toBe('/api/users/:id')
+    })
+
+    test('http-stream kind resolves prefix + config.path', () => {
+      const path = makeRoutePath({
+        procedure: httpLike('http-stream', 'Tail', '/streams/logs'),
+        prefix: 'api',
+      })
+      expect(path).toBe('/api/streams/logs')
+    })
+
+    test('path is used as-given when there is no prefix', () => {
+      const path = makeRoutePath({
+        procedure: httpLike('http', 'GetUser', '/users/:id'),
+        prefix: undefined,
+      })
+      expect(path).toBe('/users/:id')
+    })
+  })
+})
+
+describe('resolveFullPath', () => {
+  test('path without a leading slash gets one', () => {
+    expect(resolveFullPath('users')).toBe('/users')
+  })
+
+  test('path with a leading slash is unchanged', () => {
+    expect(resolveFullPath('/users')).toBe('/users')
+  })
+
+  test('prefix without a leading slash is normalized', () => {
+    expect(resolveFullPath('/users', 'api')).toBe('/api/users')
+  })
+
+  test('prefix with a leading slash is kept', () => {
+    expect(resolveFullPath('/users', '/api')).toBe('/api/users')
+  })
+
+  test('both unslashed → single slashes everywhere', () => {
+    expect(resolveFullPath('users', 'api')).toBe('/api/users')
+  })
+
+  test('empty prefix adds nothing', () => {
+    expect(resolveFullPath('/users', '')).toBe('/users')
+  })
+
+  test('undefined prefix adds nothing', () => {
+    expect(resolveFullPath('users', undefined)).toBe('/users')
+  })
+})

package/src/{implementations/http/hono/path.ts → server/paths.ts}

@@ -1,17 +1,6 @@
 import { kebabCase } from 'es-toolkit/string'
 import { castArray } from 'es-toolkit/compat'
-import type {
-  TProcedureRegistration,
-  TStreamProcedureRegistration,
-  THttpProcedureRegistration,
-  THttpStreamProcedureRegistration,
-} from '../../../types.js'
-
-export type AnyProcedureRegistration =
-  | TProcedureRegistration
-  | TStreamProcedureRegistration
-  | THttpProcedureRegistration<any>
-  | THttpStreamProcedureRegistration<any>
+import type { AnyProcedureRegistration } from '../core/types.js'
 
 function normalizePrefix(prefix?: string): string {
   if (!prefix) return ''
@@ -28,7 +17,7 @@ export function makeRoutePath({
   procedure,
   prefix,
 }: {
-  procedure: AnyProcedureRegistration
+  procedure: AnyProcedureRegistration<any, any>
   prefix?: string
 }): string {
   const normalizedPrefix = normalizePrefix(prefix)

package/src/server/request/params.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, test } from 'vitest'
+import type { HttpMethod } from '../types.js'
+import type { RequestSource } from './params.js'
+import { BODY_METHODS, defaultSuccessStatus, extractReqChannels } from './params.js'
+import { parseQueryNative } from './query.js'
+
+function makeSource(overrides?: Partial<RequestSource>): RequestSource {
+  return {
+    pathParams: () => ({ id: '42' }),
+    url: () => 'http://localhost/users/42?limit=10&tag=a&tag=b',
+    json: async () => ({ name: 'Ada' }),
+    headers: () => ({ 'x-api-key': 'secret' }),
+    ...overrides,
+  }
+}
+
+describe('extractReqChannels', () => {
+  test('extracts only the declared channels', async () => {
+    const params = await extractReqChannels(
+      makeSource(),
+      'get',
+      { query: {} },
+      parseQueryNative,
+    )
+    expect(Object.keys(params)).toEqual(['query'])
+    expect(params.query).toEqual({ limit: '10', tag: ['a', 'b'] })
+  })
+
+  test('extracts pathParams channel', async () => {
+    const params = await extractReqChannels(
+      makeSource(),
+      'get',
+      { pathParams: {} },
+      parseQueryNative,
+    )
+    expect(params).toEqual({ pathParams: { id: '42' } })
+  })
+
+  test('extracts headers channel (lowercased keys come from the source)', async () => {
+    const params = await extractReqChannels(
+      makeSource(),
+      'get',
+      { headers: {} },
+      parseQueryNative,
+    )
+    expect(params).toEqual({ headers: { 'x-api-key': 'secret' } })
+  })
+
+  test('extracts all four channels for a body-carrying method', async () => {
+    const params = await extractReqChannels(
+      makeSource(),
+      'post',
+      { pathParams: {}, query: {}, body: {}, headers: {} },
+      parseQueryNative,
+    )
+    expect(params).toEqual({
+      pathParams: { id: '42' },
+      query: { limit: '10', tag: ['a', 'b'] },
+      body: { name: 'Ada' },
+      headers: { 'x-api-key': 'secret' },
+    })
+  })
+
+  test.each(['post', 'put', 'patch'] as HttpMethod[])(
+    'parses the body for %s',
+    async (method) => {
+      const params = await extractReqChannels(makeSource(), method, { body: {} }, parseQueryNative)
+      expect(params.body).toEqual({ name: 'Ada' })
+    },
+  )
+
+  test.each(['get', 'head', 'delete'] as HttpMethod[])(
+    'skips the body for %s (never calls source.json)',
+    async (method) => {
+      let jsonCalled = false
+      const source = makeSource({
+        json: async () => {
+          jsonCalled = true
+          return {}
+        },
+      })
+      const params = await extractReqChannels(source, method, { body: {} }, parseQueryNative)
+      expect(jsonCalled).toBe(false)
+      expect('body' in params).toBe(false)
+    },
+  )
+
+  test('JSON parse failure yields {} so validation reports the missing fields', async () => {
+    const source = makeSource({
+      json: async () => {
+        throw new SyntaxError('Unexpected token')
+      },
+    })
+    const params = await extractReqChannels(source, 'post', { body: {} }, parseQueryNative)
+    expect(params.body).toEqual({})
+  })
+
+  test('unknown channel is set to undefined (key present, no extraction)', async () => {
+    const params = await extractReqChannels(
+      makeSource(),
+      'get',
+      { cookies: {} },
+      parseQueryNative,
+    )
+    expect('cookies' in params).toBe(true)
+    expect(params.cookies).toBeUndefined()
+  })
+
+  test('empty schema extracts nothing', async () => {
+    const params = await extractReqChannels(makeSource(), 'post', {}, parseQueryNative)
+    expect(params).toEqual({})
+  })
+
+  test('custom query parser is used for the query channel', async () => {
+    const params = await extractReqChannels(
+      makeSource(),
+      'get',
+      { query: {} },
+      (raw) => ({ raw }),
+    )
+    expect(params.query).toEqual({ raw: 'limit=10&tag=a&tag=b' })
+  })
+})
+
+describe('BODY_METHODS', () => {
+  test('contains exactly post, put, patch', () => {
+    expect(BODY_METHODS).toEqual(['post', 'put', 'patch'])
+  })
+})
+
+describe('defaultSuccessStatus', () => {
+  test('post → 201', () => {
+    expect(defaultSuccessStatus('post')).toBe(201)
+  })
+
+  test('delete → 204', () => {
+    expect(defaultSuccessStatus('delete')).toBe(204)
+  })
+
+  test.each(['get', 'put', 'patch', 'head'] as HttpMethod[])('%s → 200', (method) => {
+    expect(defaultSuccessStatus(method)).toBe(200)
+  })
+})