ts-procedures 8.6.0 → 9.1.0

package/src/codegen/bin/flag-specs.ts

@@ -1,51 +1,63 @@
 export interface FlagSpec {
   name: string
+  /** Display-only value placeholder rendered in --help (e.g. `<url>`). */
   arg?: string
   description: string
   group: 'Source' | 'Output' | 'Codegen' | 'Targets' | 'Misc'
   default?: string
+  /**
+   * Whether the flag consumes the next argv token as its value. This is the
+   * parsing-arity source of truth consumed by parseArgs; `arg` above is its
+   * display twin. A test asserts the two never diverge.
+   */
+  takesValue: boolean
 }
 
 export const FLAG_SPECS: readonly FlagSpec[] = [
   // Source
-  { name: '--url', arg: '<url>', description: 'Fetch the doc envelope from a running server', group: 'Source' },
-  { name: '--file', arg: '<path>', description: 'Read the doc envelope from a JSON file (see writeDocEnvelope)', group: 'Source' },
-  { name: '--config', arg: '<path>', description: 'Load options from a JSON config file', group: 'Source' },
+  { name: '--url', arg: '<url>', takesValue: true, description: 'Fetch the doc envelope from a running server', group: 'Source' },
+  { name: '--file', arg: '<path>', takesValue: true, description: 'Read the doc envelope from a JSON file (see writeDocEnvelope)', group: 'Source' },
+  { name: '--config', arg: '<path>', takesValue: true, description: 'Load options from a JSON config file', group: 'Source' },
   // Output
-  { name: '--out', arg: '<dir>', description: 'Output directory for generated files', group: 'Output' },
-  { name: '--dry-run', description: 'Print what would be written without touching disk', group: 'Output' },
-  { name: '--clean-out-dir', description: 'Prune orphaned generator-owned files before writing', group: 'Output', default: 'on' },
-  { name: '--no-clean-out-dir', description: 'Disable orphan pruning', group: 'Output' },
-  { name: '--watch', description: 'Regenerate on envelope change', group: 'Output' },
-  { name: '--interval', arg: '<ms>', description: 'Poll interval for --watch (default 3000)', group: 'Output' },
+  { name: '--out', arg: '<dir>', takesValue: true, description: 'Output directory for generated files', group: 'Output' },
+  { name: '--dry-run', takesValue: false, description: 'Print what would be written without touching disk', group: 'Output' },
+  { name: '--clean-out-dir', takesValue: false, description: 'Prune orphaned generator-owned files before writing', group: 'Output', default: 'on' },
+  { name: '--no-clean-out-dir', takesValue: false, description: 'Disable orphan pruning', group: 'Output' },
+  { name: '--watch', takesValue: false, description: 'Regenerate on envelope change', group: 'Output' },
+  { name: '--interval', arg: '<ms>', takesValue: true, description: 'Poll interval for --watch (default 3000)', group: 'Output' },
   // Codegen
-  { name: '--service-name', arg: '<name>', description: 'Service identifier driving generated names', group: 'Codegen', default: 'Api' },
-  { name: '--namespace-types', description: 'Wrap types in nested namespaces', group: 'Codegen', default: 'on' },
-  { name: '--no-namespace-types', description: 'Flat type names', group: 'Codegen' },
-  { name: '--self-contained', description: 'Bundle the client runtime into the output dir', group: 'Codegen', default: 'on' },
-  { name: '--no-self-contained', description: 'Import the client runtime from ts-procedures/client', group: 'Codegen' },
-  { name: '--client-import-path', arg: '<path>', description: 'Override the client runtime import path', group: 'Codegen' },
-  { name: '--share-models', description: 'Hoist $id-bearing schemas into a shared _models.ts', group: 'Codegen', default: 'on' },
-  { name: '--no-share-models', description: 'Inline every type per route (legacy behaviour)', group: 'Codegen' },
-  { name: '--shared-models-module', arg: '<module>', description: 'Re-export every $id model from one module (convention; sharedTypesImport overrides)', group: 'Codegen' },
-  { name: '--strict-shared-models', description: 'Fail if any $id model would be generated as a local twin', group: 'Codegen' },
-  { name: '--jsdoc', description: 'Emit JSDoc on generated types', group: 'Codegen', default: 'on' },
-  { name: '--no-jsdoc', description: 'Suppress JSDoc', group: 'Codegen' },
-  { name: '--enum-style', arg: '<union|enum>', description: 'How to emit enums (namespace mode)', group: 'Codegen' },
-  { name: '--depluralize', description: 'Depluralize extracted array-item type names', group: 'Codegen' },
-  { name: '--array-item-naming', arg: '<name|false>', description: 'Naming for extracted array-item types', group: 'Codegen' },
-  { name: '--uncountable-words', arg: '<csv>', description: 'Words exempt from depluralization', group: 'Codegen' },
+  { name: '--service-name', arg: '<name>', takesValue: true, description: 'Service identifier driving generated names', group: 'Codegen', default: 'Api' },
+  { name: '--namespace-types', takesValue: false, description: 'Wrap types in nested namespaces', group: 'Codegen', default: 'on' },
+  { name: '--no-namespace-types', takesValue: false, description: 'Flat type names', group: 'Codegen' },
+  { name: '--self-contained', takesValue: false, description: 'Bundle the client runtime into the output dir', group: 'Codegen', default: 'on' },
+  { name: '--no-self-contained', takesValue: false, description: 'Import the client runtime from ts-procedures/client', group: 'Codegen' },
+  { name: '--client-import-path', arg: '<path>', takesValue: true, description: 'Override the client runtime import path', group: 'Codegen' },
+  { name: '--share-models', takesValue: false, description: 'Hoist $id-bearing schemas into a shared _models.ts', group: 'Codegen', default: 'on' },
+  { name: '--no-share-models', takesValue: false, description: 'Inline every type per route (legacy behaviour)', group: 'Codegen' },
+  { name: '--shared-models-module', arg: '<module>', takesValue: true, description: 'Re-export every $id model from one module (convention; sharedTypesImport overrides)', group: 'Codegen' },
+  { name: '--strict-shared-models', takesValue: false, description: 'Fail if any $id model would be generated as a local twin', group: 'Codegen' },
+  { name: '--jsdoc', takesValue: false, description: 'Emit JSDoc on generated types', group: 'Codegen', default: 'on' },
+  { name: '--no-jsdoc', takesValue: false, description: 'Suppress JSDoc', group: 'Codegen' },
+  { name: '--enum-style', arg: '<union|enum>', takesValue: true, description: 'How to emit enums (namespace mode)', group: 'Codegen' },
+  { name: '--depluralize', takesValue: false, description: 'Depluralize extracted array-item type names', group: 'Codegen' },
+  { name: '--array-item-naming', arg: '<name|false>', takesValue: true, description: 'Naming for extracted array-item types', group: 'Codegen' },
+  { name: '--uncountable-words', arg: '<csv>', takesValue: true, description: 'Words exempt from depluralization', group: 'Codegen' },
   // Targets
-  { name: '--target', arg: '<ts|kotlin|swift>', description: 'Output language', group: 'Targets', default: 'ts' },
-  { name: '--kotlin-package', arg: '<pkg>', description: 'Package for Kotlin output (required for --target kotlin)', group: 'Targets' },
-  { name: '--kotlin-serializer', arg: '<kotlinx|none>', description: 'Kotlin serialization annotations', group: 'Targets', default: 'kotlinx' },
-  { name: '--swift-serializer', arg: '<codable|none>', description: 'Swift Codable conformance', group: 'Targets', default: 'codable' },
-  { name: '--swift-access-level', arg: '<public|internal>', description: 'Swift access level', group: 'Targets', default: 'public' },
-  { name: '--unsupported-unions', arg: '<throw|fallback>', description: 'Behaviour for untagged oneOf schemas', group: 'Targets', default: 'throw' },
+  { name: '--target', arg: '<ts|kotlin|swift>', takesValue: true, description: 'Output language', group: 'Targets', default: 'ts' },
+  { name: '--kotlin-package', arg: '<pkg>', takesValue: true, description: 'Package for Kotlin output (required for --target kotlin)', group: 'Targets' },
+  { name: '--kotlin-serializer', arg: '<kotlinx|none>', takesValue: true, description: 'Kotlin serialization annotations', group: 'Targets', default: 'kotlinx' },
+  { name: '--swift-serializer', arg: '<codable|none>', takesValue: true, description: 'Swift Codable conformance', group: 'Targets', default: 'codable' },
+  { name: '--swift-access-level', arg: '<public|internal>', takesValue: true, description: 'Swift access level', group: 'Targets', default: 'public' },
+  { name: '--unsupported-unions', arg: '<throw|fallback>', takesValue: true, description: 'Behaviour for untagged oneOf schemas', group: 'Targets', default: 'throw' },
 ]
 
 export const KNOWN_FLAGS: readonly string[] = FLAG_SPECS.map((s) => s.name)
 
+/** Name-keyed view of FLAG_SPECS for O(1) lookup during parsing. */
+export const FLAG_SPEC_BY_NAME: ReadonlyMap<string, FlagSpec> = new Map(
+  FLAG_SPECS.map((s) => [s.name, s]),
+)
+
 const GROUP_ORDER: FlagSpec['group'][] = ['Source', 'Output', 'Codegen', 'Targets', 'Misc']
 
 export function formatHelp(): string {

package/src/codegen/bundle-size.test.ts

@@ -3,7 +3,7 @@ import { generateClient } from './index.js'
 import * as path from 'node:path'
 import * as os from 'node:os'
 import * as fs from 'node:fs/promises'
-import type { DocEnvelope } from '../implementations/types.js'
+import type { DocEnvelope } from '../server/types.js'
 
 function makeEnvelope(routeCount: number): DocEnvelope {
   const routes = Array.from({ length: routeCount }, (_, i) => ({

package/src/codegen/collect-models.ts

@@ -1,4 +1,4 @@
-import type { AnyHttpRouteDoc } from '../implementations/types.js'
+import type { AnyHttpRouteDoc } from '../server/types.js'
 import { toPascalCase } from './naming.js'
 import { walkSubschemas } from './schema-walk.js'
 

package/src/codegen/e2e.test.ts

@@ -3,7 +3,7 @@ import { generateClient } from './index.js'
 import { mkdirSync, rmSync, readFileSync, writeFileSync, existsSync } from 'node:fs'
 import { join } from 'node:path'
 import { tmpdir } from 'node:os'
-import type { DocEnvelope, RPCHttpRouteDoc, APIHttpRouteDoc, StreamHttpRouteDoc, HttpStreamRouteDoc, ErrorDoc } from '../implementations/types.js'
+import type { DocEnvelope, RPCHttpRouteDoc, APIHttpRouteDoc, StreamHttpRouteDoc, HttpStreamRouteDoc, ErrorDoc } from '../server/types.js'
 import { runTsc } from './test-helpers/run-tsc.js'
 import { Type } from 'typebox'
 

package/src/codegen/emit/api-route.ts

@@ -0,0 +1,184 @@
+/**
+ * Emitter for `kind: 'api'` routes — structured multi-channel `Req` types,
+ * `Response.Body` / `Response.Headers` slots, and the bindCallable /
+ * bindCallableTyped callable.
+ */
+import type { APIHttpRouteDoc } from '../../server/types.js'
+import { toPascalCase } from '../naming.js'
+import type { EmitRouteContext, RouteChunks } from './context.js'
+import { convertBody, formatSubNamespace, type NamedType } from './format-types.js'
+import { buildCallableJsDoc, buildErrorUnion, injectRouteErrors } from './route-shared.js'
+
+/**
+ * Builds the conditional return type string for an API or http-stream callable.
+ *
+ * - Both body + headers → `{ body: <Body>; headers: <Headers> }`
+ * - Only body           → `<Body>`
+ * - Only headers        → `{ headers: <Headers> }`
+ * - Neither             → `void`
+ */
+function buildApiReturnType(
+  bodyRef: string | undefined,
+  headersRef: string | undefined,
+): string {
+  if (bodyRef && headersRef) {
+    return `{ body: ${bodyRef}; headers: ${headersRef} }`
+  }
+  if (bodyRef) return bodyRef
+  if (headersRef) return `{ headers: ${headersRef} }`
+  return 'void'
+}
+
+export async function emitApiRoute(route: APIHttpRouteDoc, ctx: EmitRouteContext): Promise<RouteChunks> {
+  const pascal = toPascalCase(route.name)
+  const req = route.jsonSchema.req ?? {}
+  const res = route.jsonSchema.res ?? {}
+
+  // Request channels
+  const reqChannelKeys = ['pathParams', 'query', 'body', 'headers'] as const
+  const reqTypes: NamedType[] = []
+  const presentChannels: string[] = []
+
+  for (const channel of reqChannelKeys) {
+    const schema = req[channel]
+    if (schema != null) {
+      reqTypes.push({ shortName: toPascalCase(channel), schema })
+      presentChannels.push(channel)
+    }
+  }
+
+  // Response slots
+  const resTypes: NamedType[] = [
+    { shortName: 'Body', schema: res.body },
+    { shortName: 'Headers', schema: res.headers },
+  ]
+
+  const scopeStr = route.scope ?? 'default'
+  const errorUnion = buildErrorUnion(route.errors, ctx)
+  const hasErrors = errorUnion !== null
+  const errorsRef = ctx.namespaceTypes
+    ? `${ctx.scopePascal}.${pascal}.Errors`
+    : `${pascal}Errors`
+
+  const declarations: string[] = []
+  let paramsTypeName = 'void'
+  let returnTypeName = 'void'
+
+  // Track reserved names across all sub-namespaces. Model names are reserved
+  // so an ajsc-extracted sub-type can't silently merge with a referenced model.
+  const taken = new Set<string>(['Req', 'Response'])
+
+  if (ctx.namespaceTypes) {
+    // Namespace mode: emit nested Req {} and Response {} namespaces inside route namespace.
+    // Also emit merged type aliases `export type Req = { ... }` and `export type Response = ...`
+    // so they can be used as type arguments to bindCallable (TS requires a TYPE, not a namespace).
+    const nsLines: string[] = []
+
+    const { nsBlock: reqBlock, refs: reqRefs } = await formatSubNamespace(
+      pascal, 'Req', reqTypes, ctx, taken
+    )
+    if (reqBlock) {
+      nsLines.push(reqBlock)
+      // Merged type alias for Req so it can be used as a generic type arg
+      const reqFields = presentChannels
+        .map((ch) => `${ch}: Req.${toPascalCase(ch)}`)
+        .join('; ')
+      nsLines.push(`    export type Req = { ${reqFields} }`)
+    }
+
+    const { nsBlock: resBlock, refs: resRefs } = await formatSubNamespace(
+      pascal, 'Response', resTypes, ctx, taken
+    )
+    if (resBlock) {
+      nsLines.push(resBlock)
+      // No merged Response type alias needed: we reference Response.Body / Response.Headers
+      // directly in the return type string, which are namespace-qualified paths (valid).
+    }
+
+    // Emit Errors type last (injected by injectRouteErrors below)
+    // Build the route namespace block
+    if (nsLines.length > 0) {
+      declarations.push(`  export namespace ${pascal} {\n${nsLines.join('\n\n')}\n  }`)
+    }
+
+    // Params type: use the merged Req type alias
+    if (presentChannels.length > 0) {
+      paramsTypeName = `${ctx.scopePascal}.${pascal}.Req`
+    }
+
+    // Return type
+    const bodyRef = resRefs['Body']
+    const headersRef = resRefs['Headers']
+    returnTypeName = buildApiReturnType(bodyRef, headersRef)
+  } else {
+    // Flat mode: emit individual types prefixed with route + sub-namespace name
+    for (const { shortName, schema } of reqTypes) {
+      if (schema == null) continue
+      const flatName = `${pascal}Req${shortName}`
+      const body = await convertBody(schema, ctx)
+      if (body == null) continue
+      declarations.push(`export type ${flatName} = ${body}`)
+    }
+
+    // Flat mode: compose structured Req type
+    if (presentChannels.length > 0) {
+      const structureFields = presentChannels
+        .map((ch) => `${ch}: ${pascal}Req${toPascalCase(ch)}`)
+        .join('; ')
+      declarations.push(`export type ${pascal}Req = { ${structureFields} }`)
+      paramsTypeName = `${pascal}Req`
+    }
+
+    // Flat mode: emit response types
+    let bodyRef: string | undefined
+    let headersRef: string | undefined
+
+    for (const { shortName, schema } of resTypes) {
+      if (schema == null) continue
+      const flatName = `${pascal}Response${shortName}`
+      const body = await convertBody(schema, ctx)
+      if (body == null) continue
+      declarations.push(`export type ${flatName} = ${body}`)
+      if (shortName === 'Body') bodyRef = flatName
+      if (shortName === 'Headers') headersRef = flatName
+    }
+
+    returnTypeName = buildApiReturnType(bodyRef, headersRef)
+
+    // Flat mode errors
+    if (errorUnion) {
+      declarations.push(`export type ${pascal}Errors = ${errorUnion}`)
+    }
+  }
+
+  const responseHeadersDeclared = res.headers != null
+  const helperCall = hasErrors
+    ? `client.bindCallableTyped<${paramsTypeName}, ${returnTypeName}, ${errorsRef}>`
+    : `client.bindCallable<${paramsTypeName}, ${returnTypeName}>`
+
+  const descriptorLines = [
+    `      name: '${route.name}',`,
+    `      scope: '${scopeStr}',`,
+    `      path: '${route.fullPath}',`,
+    `      method: '${route.method}',`,
+    `      kind: 'api',`,
+    ...(responseHeadersDeclared ? [`      responseHeadersDeclared: true,`] : []),
+  ]
+
+  const callable = [
+    buildCallableJsDoc({
+      methodLabel: route.method.toUpperCase(),
+      path: route.fullPath,
+      errorsRef: hasErrors ? errorsRef : null,
+    }),
+    `    ${route.name}: ${helperCall}({`,
+    ...descriptorLines,
+    `    }),`,
+  ].join('\n')
+
+  const hasErrorsInjected = ctx.namespaceTypes
+    ? injectRouteErrors(declarations, pascal, errorUnion, ctx.namespaceTypes)
+    : errorUnion !== null  // flat mode already emitted errors above
+
+  return { typeDeclarations: declarations, callable, hasStream: false, hasErrors: hasErrorsInjected }
+}

package/src/codegen/emit/context.ts

@@ -0,0 +1,32 @@
+/**
+ * Shared per-route emission contracts for the TS scope emitter.
+ *
+ * `EmitRouteContext` is threaded through every route emitter and formatting
+ * helper; `RouteChunks` is what each per-kind emitter returns to
+ * `emitScopeFile` for final assembly.
+ */
+import type { AjscOptions } from '../emit-types.js'
+
+export interface RouteChunks {
+  typeDeclarations: string[]
+  callable: string
+  hasStream: boolean
+  /** True when this route emitted an `Errors` type (drives the `_errors` import at the top of the scope file). */
+  hasErrors: boolean
+}
+
+export interface EmitRouteContext {
+  ajsc?: AjscOptions
+  namespaceTypes: boolean
+  scopePascal: string
+  serviceName: string
+  errorKeys?: Set<string>
+  /** `$id` → shared model type name; drives the substitute wrappers. */
+  idToModelName?: Map<string, string>
+  /**
+   * Accumulates the model names ajsc reported as `referencedNamedTypes` across
+   * every route in the scope. Drives the `import type { … } from './_models'`
+   * line assembled in `emitScopeFile`.
+   */
+  referencedModels: Set<string>
+}

package/src/codegen/emit/declarations.ts

@@ -0,0 +1,49 @@
+/**
+ * Declaration bookkeeping for namespace-mode emission: the `indent` text
+ * helper and the `DeclarationCollector` duplicate-identifier guard.
+ */
+import { extractedDeclName } from '../emit-types.js'
+
+/** Indent each line of a multi-line string by a given prefix. */
+export function indent(text: string, prefix: string): string {
+  return text.split('\n').map((line) => (line ? prefix + line : line)).join('\n')
+}
+
+/**
+ * Tracks extracted declarations emitted into a single namespace, guarding
+ * against duplicate identifiers (defense-in-depth on top of the rename pass).
+ *
+ * - Exact-string duplicates (the same sub-type extracted from two schemas) are
+ *   silently skipped.
+ * - A same-name-but-different-body declaration is a genuine collision the
+ *   rename pass failed to resolve; emitting it would produce an opaque
+ *   `TS2300: Duplicate identifier` in the consumer's build. We fail fast at
+ *   codegen with a message that names the offending identifier instead.
+ *
+ * Returns the indented declaration line to push, or `null` when it should be
+ * skipped (exact duplicate).
+ */
+export class DeclarationCollector {
+  private readonly seenStrings = new Set<string>()
+  private readonly seenNames = new Map<string, string>()
+
+  constructor(private readonly context: string) {}
+
+  /** Returns the indented line to emit, or `null` for an exact duplicate. */
+  accept(decl: string, indentPrefix: string): string | null {
+    if (this.seenStrings.has(decl)) return null
+    const name = extractedDeclName(decl)
+    if (name != null) {
+      if (this.seenNames.has(name)) {
+        throw new Error(
+          `[ts-procedures-codegen] duplicate identifier '${name}' while emitting ${this.context}. ` +
+            `An extracted sub-type collided with another of the same name and could not be renamed. ` +
+            `This is a codegen bug — please report it with the offending schema.`,
+        )
+      }
+      this.seenNames.set(name, decl)
+    }
+    this.seenStrings.add(decl)
+    return indent(decl, indentPrefix)
+  }
+}

package/src/codegen/emit/format-types.ts

@@ -0,0 +1,232 @@
+/**
+ * Schema → TypeScript conversion layer for the scope emitter: shared-model
+ * conversion wrappers (`convertExtracted` / `convertBody`), the
+ * `assertNoModelNameCollision` guard, and the `formatTypes` /
+ * `formatSubNamespace` declaration builders used by the per-kind route
+ * emitters.
+ */
+import {
+  jsonSchemaToTypeBody,
+  jsonSchemaToTypeBodyWithRefs,
+  jsonSchemaToExtractedTypes,
+  renameExtractedTypes,
+  type ExtractedTypeOutput,
+} from '../emit-types.js'
+import { substituteModelRefs } from '../model-refs.js'
+import type { EmitRouteContext } from './context.js'
+import { DeclarationCollector } from './declarations.js'
+
+// ---------------------------------------------------------------------------
+// Shared-model conversion wrappers (ajsc x-named-type)
+// ---------------------------------------------------------------------------
+
+/**
+ * Drop-in replacement for `jsonSchemaToExtractedTypes` that, when shared models
+ * are in play, rewrites every `$id` subschema into an `x-named-type` node before
+ * ajsc. ajsc emits each as a bare verbatim reference and reports it via
+ * `referencedNamedTypes`; this wrapper folds those names into
+ * `ctx.referencedModels` so `emitScopeFile` can build the `_models` import.
+ *
+ * Short-circuits to the exact original call when no models are configured, so
+ * output is byte-identical for envelopes without `$id` models.
+ */
+export async function convertExtracted(
+  schema: Record<string, unknown>,
+  ctx: EmitRouteContext,
+): Promise<ExtractedTypeOutput | undefined> {
+  if (ctx.idToModelName == null || ctx.idToModelName.size === 0) {
+    return jsonSchemaToExtractedTypes(schema, ctx.ajsc)
+  }
+  const { schema: sub } = substituteModelRefs(schema, ctx.idToModelName)
+  const result = await jsonSchemaToExtractedTypes(sub, ctx.ajsc)
+  if (result != null) {
+    assertNoModelNameCollision(result)
+    for (const name of result.referencedNamedTypes) ctx.referencedModels.add(name)
+  }
+  return result
+}
+
+/**
+ * Guards ajsc's documented `x-named-type` collision caveat. If a shared-model
+ * name (referenced via `x-named-type`) also matches the name ajsc derives for a
+ * sibling *structural* sub-type, ajsc silently MERGES them — the model reference
+ * resolves to the unrelated structural type. The merge happens inside ajsc's own
+ * pass, so it can't be disentangled afterward (a post-hoc rename would rewrite
+ * the model reference too, producing a silently-wrong type). Instead we detect
+ * the collision — a name present in BOTH `referencedNamedTypes` AND
+ * `extractedTypeNames` (ajsc's own documented collision signal) — and fail fast
+ * with an actionable message. The throw is wrapped with the route's name/scope
+ * by `emitScopeFile`.
+ */
+function assertNoModelNameCollision(result: ExtractedTypeOutput): void {
+  if (result.referencedNamedTypes.length === 0 || result.extractedTypeNames.length === 0) return
+  const extracted = new Set(result.extractedTypeNames)
+  const collisions = result.referencedNamedTypes.filter((name) => extracted.has(name))
+  if (collisions.length === 0) return
+  const names = collisions.map((n) => `'${n}'`).join(', ')
+  throw new Error(
+    `shared model ${names} collides with a generated type of the same name derived ` +
+      `from a property in this route's schema — ajsc would silently merge them. Rename ` +
+      `the colliding property, or change the model's $id/title so the generated names differ`,
+  )
+}
+
+/**
+ * Drop-in replacement for `jsonSchemaToTypeBody` mirroring {@link convertExtracted}
+ * for the bare-body (flat / merged-alias) conversion path.
+ */
+export async function convertBody(
+  schema: Record<string, unknown>,
+  ctx: EmitRouteContext,
+): Promise<string | undefined> {
+  if (ctx.idToModelName == null || ctx.idToModelName.size === 0) {
+    return jsonSchemaToTypeBody(schema, ctx.ajsc)
+  }
+  const { schema: sub } = substituteModelRefs(schema, ctx.idToModelName)
+  const result = await jsonSchemaToTypeBodyWithRefs(sub, ctx.ajsc)
+  if (result == null) return undefined
+  for (const name of result.referencedNamedTypes) ctx.referencedModels.add(name)
+  return result.body
+}
+
+export interface NamedType {
+  /** Short name for namespace mode (e.g., 'Params', 'Response'). */
+  shortName: string
+  /** Schema to convert, or undefined if not present. */
+  schema: Record<string, unknown> | undefined
+}
+
+export interface FormattedTypes {
+  /** Type declarations to add to the file. */
+  declarations: string[]
+  /** Map of shortName → qualified type reference (for callables). */
+  refs: Record<string, string>
+}
+
+/**
+ * Converts multiple schemas into type declarations and type references.
+ * In flat mode: `export type ${routePascal}${shortName} = <body>`
+ * In namespace mode: extracted sub-types + named types inside `export namespace ${routePascal} { ... }`
+ *
+ * `extraReserved` lets the caller pre-reserve identifier names that the route
+ * will inject AFTER formatTypes returns (e.g. emitApiRoute's structured
+ * `Params`). Without this, an ajsc-extracted sub-type could shadow the
+ * injected one and produce duplicate `export type Params` declarations.
+ */
+export async function formatTypes(
+  routePascal: string,
+  types: NamedType[],
+  ctx: EmitRouteContext,
+  extraReserved?: ReadonlySet<string>,
+): Promise<FormattedTypes> {
+  const declarations: string[] = []
+  const refs: Record<string, string> = {}
+
+  if (ctx.namespaceTypes) {
+    const nsLines: string[] = []
+    const collector = new DeclarationCollector(`namespace ${routePascal}`)
+
+    // Pre-reserve every name the route will declare itself (each shortName +
+    // any caller-supplied extras). Extracted sub-types whose names land in
+    // this set get renamed (e.g. `Params` → `Params_`) by renameExtractedTypes,
+    // and the body string is patched in lockstep so the reference still
+    // resolves. The set is mutated as we go, so a sub-type renamed in schema A
+    // is also reserved against schema B.
+    const taken = new Set<string>(extraReserved ?? [])
+    for (const t of types) {
+      if (t.schema != null) taken.add(t.shortName)
+    }
+
+    for (const { shortName, schema } of types) {
+      if (schema == null) continue
+
+      const rawResult = await convertExtracted(schema, ctx)
+      if (rawResult == null) continue
+
+      const result = renameExtractedTypes(rawResult, taken)
+
+      // Collect extracted sub-types (dedupe exact dups; throw on real collisions)
+      for (const decl of result.declarations) {
+        const line = collector.accept(decl, '    ')
+        if (line != null) nsLines.push(line)
+      }
+
+      nsLines.push(`    export type ${shortName} = ${result.body}`)
+      refs[shortName] = `${ctx.scopePascal}.${routePascal}.${shortName}`
+    }
+
+    if (nsLines.length > 0) {
+      declarations.push(`  export namespace ${routePascal} {\n${nsLines.join('\n')}\n  }`)
+    }
+  } else {
+    for (const { shortName, schema } of types) {
+      if (schema == null) continue
+
+      const flatName = `${routePascal}${shortName}`
+      const body = await convertBody(schema, ctx)
+      if (body == null) continue
+
+      declarations.push(`export type ${flatName} = ${body}`)
+      refs[shortName] = flatName
+    }
+  }
+
+  return { declarations, refs }
+}
+
+/**
+ * Formats a group of named types into a nested sub-namespace block (for namespace mode).
+ * Returns an array of lines to be inserted into the parent namespace, and a map of
+ * shortName → qualified type reference for use in callables.
+ *
+ * In flat mode, returns declarations like `export type ${prefix}${shortName} = ...`
+ * and refs like `${prefix}${shortName}`.
+ */
+export async function formatSubNamespace(
+  routePascal: string,
+  nsName: string,           // e.g. 'Req' or 'Response'
+  types: NamedType[],
+  ctx: EmitRouteContext,
+  taken: Set<string>,
+): Promise<{ nsBlock: string | null; refs: Record<string, string> }> {
+  const refs: Record<string, string> = {}
+  const nsLines: string[] = []
+  const collector = new DeclarationCollector(`namespace ${routePascal}.${nsName}`)
+
+  // Pre-reserve short names to prevent sub-type extraction collision
+  for (const t of types) {
+    if (t.schema != null) taken.add(t.shortName)
+  }
+
+  for (const { shortName, schema } of types) {
+    if (schema == null) continue
+
+    if (ctx.namespaceTypes) {
+      const rawResult = await convertExtracted(schema, ctx)
+      if (rawResult == null) continue
+
+      const result = renameExtractedTypes(rawResult, taken)
+
+      for (const decl of result.declarations) {
+        const line = collector.accept(decl, '      ')
+        if (line != null) nsLines.push(line)
+      }
+
+      nsLines.push(`      export type ${shortName} = ${result.body}`)
+      refs[shortName] = `${ctx.scopePascal}.${routePascal}.${nsName}.${shortName}`
+    } else {
+      const flatName = `${routePascal}${nsName}${shortName}`
+      const body = await convertBody(schema, ctx)
+      if (body == null) continue
+      refs[shortName] = flatName
+    }
+  }
+
+  if (ctx.namespaceTypes) {
+    if (nsLines.length === 0) return { nsBlock: null, refs }
+    const nsBlock = `    export namespace ${nsName} {\n${nsLines.join('\n')}\n    }`
+    return { nsBlock, refs }
+  }
+
+  return { nsBlock: null, refs }
+}