ts-procedures 7.3.0 → 8.1.0

package/src/codegen/emit-types.ts

@@ -91,6 +91,45 @@ export interface ExtractedTypeOutput {
   body: string
 }
 
+/**
+ * Splits a block of ajsc output into individual top-level declarations.
+ *
+ * ajsc glues sibling extracted declarations with a single `\n`, but each
+ * declaration may itself span multiple lines (multi-line enums, object bodies
+ * with per-property JSDoc). A simple line/`export`-prefix split would therefore
+ * break multi-line declarations apart. Instead we walk lines tracking brace
+ * depth and close a declaration when depth returns to 0 on a line that ends in
+ * a statement terminator (`;` or `}`). Any leading comment lines (JSDoc) stay
+ * attached to the declaration that follows them.
+ */
+function splitTopLevelDeclarations(block: string): string[] {
+  const decls: string[] = []
+  let current: string[] = []
+  let depth = 0
+
+  const flush = () => {
+    const joined = current.join('\n').trim()
+    if (joined) decls.push(joined)
+    current = []
+  }
+
+  for (const line of block.split('\n')) {
+    current.push(line)
+    for (const ch of line) {
+      if (ch === '{') depth += 1
+      else if (ch === '}') depth -= 1
+    }
+    const trimmed = line.trimEnd()
+    if (depth <= 0 && (trimmed.endsWith(';') || trimmed.endsWith('}'))) {
+      flush()
+      depth = 0
+    }
+  }
+  flush()
+
+  return decls
+}
+
 /**
  * Converts a JSON Schema to extracted TypeScript types using ajsc with
  * `inlineTypes: false`. This produces named sub-types (objects, enums) that
@@ -122,13 +161,23 @@ export async function jsonSchemaToExtractedTypes(
     )
   }
 
-  // ajsc with inlineTypes: false produces blocks separated by blank lines:
+  // ajsc with inlineTypes: false produces output like:
   //   export enum Status { Active = "active" }
   //   export type Contact = { name: string; };
+  //
   //   export type Root = { status: Status; contacts: Array<Contact>; };
   //
-  // The Root type is always the last declaration.
+  // Crucially, *sibling* extracted declarations are joined by a SINGLE "\n"
+  // (one block) while the Root is separated by a blank line ("\n\n"). Splitting
+  // only on blank lines would therefore fuse two or more sibling declarations
+  // into one array element — and every downstream consumer (extractedDeclName,
+  // renameExtractedTypes, the namespace dedup) assumes one declaration per
+  // element, so the non-first siblings would be mis-parsed and emitted twice
+  // (`error TS2300: Duplicate identifier`). We split on blank lines first, then
+  // split each block into individual statements so each element holds exactly
+  // one declaration. The Root type is always the last declaration.
   const blocks = code.split(/\n\n+/).map((b) => b.trim()).filter(Boolean)
+  const rawDecls = blocks.flatMap(splitTopLevelDeclarations)
 
   const declarations: string[] = []
   let body = ''
@@ -139,13 +188,13 @@ export async function jsonSchemaToExtractedTypes(
   // declarations branch instead of being eaten as the body.
   const rootDeclPattern = /^export\s+type\s+Root\s*=\s*/
 
-  for (const block of blocks) {
-    if (rootDeclPattern.test(block)) {
+  for (const decl of rawDecls) {
+    if (rootDeclPattern.test(decl)) {
       // Strip "export type Root = " prefix and trailing ";"
-      body = block.replace(rootDeclPattern, '').replace(/;\s*$/, '').trim()
+      body = decl.replace(rootDeclPattern, '').replace(/;\s*$/, '').trim()
     } else {
       // Sub-type or enum declaration — remove trailing ";" for consistency
-      declarations.push(block.replace(/;\s*$/, ''))
+      declarations.push(decl.replace(/;\s*$/, ''))
     }
   }
 
@@ -188,25 +237,28 @@ export function extractedDeclName(decl: string): string | undefined {
  * alias is generated (`Params` → `ParamsInner`, then `ParamsInner2`, …) so
  * the renamed type reads like a real, intentional name (not a placeholder).
  * The declaration is rewritten with the new name and every word-boundary
- * occurrence in `result.body` is substituted so the body keeps referencing
- * the renamed type.
+ * occurrence of the old name is substituted in `result.body` AND in every
+ * sibling declaration. The sibling patch matters because extracted sub-types
+ * reference each other (e.g. `Contact = { address: Address }`): renaming
+ * `Address` → `AddressInner` must update that reference too, otherwise the
+ * renamed type silently resolves to a different schema's sub-type of the same
+ * name (a latent wrong-type bug that only hides when the shapes happen to match).
  */
 export function renameExtractedTypes(
   result: ExtractedTypeOutput,
   taken: Set<string>,
 ): ExtractedTypeOutput {
-  let body = result.body
-  const declarations: string[] = []
+  // Work on a mutable copy so we can patch cross-references after renaming.
+  const declarations = [...result.declarations]
+  const renames = new Map<string, string>()
 
-  for (const decl of result.declarations) {
+  // Pass 1: decide renames and rewrite each declaration's leading identifier.
+  for (let i = 0; i < declarations.length; i += 1) {
+    const decl = declarations[i]!
     const name = extractedDeclName(decl)
-    if (name == null) {
-      declarations.push(decl)
-      continue
-    }
+    if (name == null) continue
     if (!taken.has(name)) {
       taken.add(name)
-      declarations.push(decl)
       continue
     }
 
@@ -220,16 +272,25 @@ export function renameExtractedTypes(
       suffix += 1
     }
     taken.add(alias)
+    renames.set(name, alias)
 
-    // Rewrite the declaration's leading identifier.
-    const renamedDecl = decl.replace(
+    declarations[i] = decl.replace(
       new RegExp(`^(export\\s+(?:type|enum|interface)\\s+)${name}\\b`),
       `$1${alias}`,
     )
-    declarations.push(renamedDecl)
+  }
 
-    // Patch every word-boundary occurrence of the old name in the body.
-    body = body.replace(new RegExp(`\\b${name}\\b`, 'g'), alias)
+  // Pass 2: patch every reference to a renamed name — in the body and in every
+  // declaration body — so cross-references between sibling sub-types follow the
+  // rename. `\bAddress\b` does not match inside `AddressInner` (no word
+  // boundary between `s` and `I`), so already-renamed identifiers are untouched.
+  let body = result.body
+  for (const [name, alias] of renames) {
+    const re = new RegExp(`\\b${name}\\b`, 'g')
+    body = body.replace(re, alias)
+    for (let i = 0; i < declarations.length; i += 1) {
+      declarations[i] = declarations[i]!.replace(re, alias)
+    }
   }
 
   return { declarations, body }

package/src/codegen/pipeline.test.ts

@@ -375,7 +375,7 @@ describe('runPipeline (kotlin target)', () => {
           scope: 'users',
           method: 'GET',
           fullPath: '/users/:id',
-          schema: { input: { pathParams: { type: 'object' } }, returnType: { type: 'object' } },
+          jsonSchema: { req: { pathParams: { type: 'object' } }, res: { body: { type: 'object' } } },
           errors: [],
         },
       ],
@@ -438,7 +438,7 @@ describe('runPipeline (kotlin target)', () => {
       routes: [
         {
           kind: 'api', name: 'GetUser', scope: 'users', method: 'GET', fullPath: '/users/:id',
-          schema: { input: { pathParams: { type: 'object' } }, returnType: { type: 'object' } },
+          jsonSchema: { req: { pathParams: { type: 'object' } }, res: { body: { type: 'object' } } },
           errors: [],
         },
       ],
@@ -466,9 +466,9 @@ describe('runPipeline (kotlin target)', () => {
       const envelope = {
         basePath: '/api', headers: [], version: '1' as const, errors: [],
         routes: [
-          { kind: 'stream', name: 'WatchA', scope: 's', method: 'GET', path: '/a', schema: {}, errors: [] },
-          { kind: 'stream', name: 'WatchB', scope: 's', method: 'GET', path: '/b', schema: {}, errors: [] },
-          { kind: 'api', name: 'GetThing', scope: 's', method: 'GET', fullPath: '/c', schema: { returnType: { type: 'object' } }, errors: [] },
+          { kind: 'stream', name: 'WatchA', scope: 's', method: 'GET', path: '/a', jsonSchema: {}, errors: [] },
+          { kind: 'stream', name: 'WatchB', scope: 's', method: 'GET', path: '/b', jsonSchema: {}, errors: [] },
+          { kind: 'api', name: 'GetThing', scope: 's', method: 'GET', fullPath: '/c', jsonSchema: { res: { body: { type: 'object' } } }, errors: [] },
         ],
       } as any
       await runPipeline({
@@ -493,7 +493,7 @@ describe('runPipeline (kotlin target)', () => {
     try {
       const envelope = {
         basePath: '/api', headers: [], version: '1' as const, errors: [],
-        routes: [{ kind: 'api', name: 'X', scope: 's', method: 'GET', fullPath: '/x', schema: { returnType: { type: 'object' } }, errors: [] }],
+        routes: [{ kind: 'api', name: 'X', scope: 's', method: 'GET', fullPath: '/x', jsonSchema: { res: { body: { type: 'object' } } }, errors: [] }],
       } as any
       await runPipeline({
         envelope, outDir: 'out', dryRun: true,
@@ -518,7 +518,7 @@ describe('runPipeline (kotlin target)', () => {
 
     const envelope = {
       basePath: '/api', headers: [], version: '1' as const, errors: [],
-      routes: [{ kind: 'api', name: 'GetUser', scope: 'users', method: 'GET', fullPath: '/u', schema: { returnType: { type: 'object' } }, errors: [] }],
+      routes: [{ kind: 'api', name: 'GetUser', scope: 'users', method: 'GET', fullPath: '/u', jsonSchema: { res: { body: { type: 'object' } } }, errors: [] }],
     } as any
 
     await runPipeline({

package/src/codegen/resolve-envelope.test.ts

@@ -54,11 +54,11 @@ describe('resolveEnvelope', () => {
   })
 
   // Defensive (downstream bug repro): forgetting `builder.build()` is a common
-  // cause of an empty routes array because hono-rpc/hono-api/hono-stream/express-rpc
-  // builders only populate their `_docs` array inside `build()`. The current
-  // error message says "Register at least one procedure", which led the
-  // downstream dev to look in the wrong place. The message should mention
-  // `.build()` as a likely cause so the next person hits the right fix faster.
+  // cause of an empty routes array because the hono builder only populates
+  // its `_docs` array inside `build()`. The current error message says
+  // "Register at least one procedure", which led the downstream dev to look
+  // in the wrong place. The message should mention `.build()` as a likely
+  // cause so the next person hits the right fix faster.
   it('empty-routes error message mentions builder.build() as a likely cause', async () => {
     const empty: DocEnvelope = { basePath: '', headers: [], errors: [], routes: [] }
     await expect(resolveEnvelope({ envelope: empty })).rejects.toThrow(/\.build\(\)/)

package/src/codegen/resolve-envelope.ts

@@ -55,7 +55,7 @@ export async function resolveEnvelope(input: ResolveInput): Promise<DocEnvelope>
     throw new Error(
       '[ts-procedures-codegen] DocEnvelope has an empty "routes" array. ' +
       'Common causes: (1) you forgot to call `builder.build()` before passing ' +
-      'the builder to `DocRegistry.from(...)` — hono/express builders only populate ' +
+      'the builder to `DocRegistry.from(...)` — hono builders only populate ' +
       '`docs` inside `build()`; (2) no procedures registered with the builder.'
     )
   }

package/src/codegen/targets/_shared/route-slots.test.ts

@@ -2,54 +2,137 @@ import { describe, expect, it } from 'vitest'
 import { extractRouteSlots } from './route-slots.js'
 import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
 
-const r = (schema: Record<string, unknown> | undefined): AnyHttpRouteDoc =>
-  ({ name: 'X', kind: 'api', method: 'GET', fullPath: '/x', schema } as unknown as AnyHttpRouteDoc)
+// Helpers for constructing minimal route docs per kind
+function apiRoute(jsonSchema: Record<string, unknown>): AnyHttpRouteDoc {
+  return { name: 'X', kind: 'api', method: 'get', path: '/x', fullPath: '/x', jsonSchema } as unknown as AnyHttpRouteDoc
+}
 
-describe('extractRouteSlots', () => {
-  it('returns no slots when schema is undefined', () => {
-    expect(extractRouteSlots(r(undefined))).toEqual([])
-  })
+function httpStreamRoute(jsonSchema: Record<string, unknown>): AnyHttpRouteDoc {
+  return { name: 'X', kind: 'http-stream', method: 'get', path: '/x', fullPath: '/x', streamMode: 'sse', jsonSchema } as unknown as AnyHttpRouteDoc
+}
+
+function rpcRoute(jsonSchema: Record<string, unknown>): AnyHttpRouteDoc {
+  return { name: 'X', kind: 'rpc', method: 'post', path: '/x', scope: 'x', version: 1, jsonSchema } as unknown as AnyHttpRouteDoc
+}
 
-  it('returns no slots when schema is empty', () => {
-    expect(extractRouteSlots(r({}))).toEqual([])
+function streamRoute(jsonSchema: Record<string, unknown>): AnyHttpRouteDoc {
+  return { name: 'X', kind: 'stream', path: '/x', scope: 'x', version: 1, methods: ['get'], streamMode: 'sse', jsonSchema } as unknown as AnyHttpRouteDoc
+}
+
+describe('extractRouteSlots — api kind', () => {
+  it('returns no slots when jsonSchema is empty', () => {
+    expect(extractRouteSlots(apiRoute({}))).toEqual([])
   })
 
-  it('returns the deterministic slot order: PathParams, Query, Body, Response', () => {
+  it('returns the deterministic slot order: PathParams, Query, Body, Headers, Response, ResponseHeaders', () => {
     const slots = extractRouteSlots(
-      r({
-        input: {
-          body: { type: 'object', x: 'body' },
-          query: { type: 'object', x: 'query' },
-          pathParams: { type: 'object', x: 'path' },
+      apiRoute({
+        req: {
+          body: { type: 'object', tag: 'body' },
+          query: { type: 'object', tag: 'query' },
+          pathParams: { type: 'object', tag: 'path' },
+          headers: { type: 'object', tag: 'headers' },
+        },
+        res: {
+          body: { type: 'object', tag: 'response' },
+          headers: { type: 'object', tag: 'resHeaders' },
         },
-        returnType: { type: 'object', x: 'response' },
       }),
     )
-    expect(slots.map((s) => s.rootName)).toEqual(['PathParams', 'Query', 'Body', 'Response'])
+    expect(slots.map((s) => s.rootName)).toEqual(['PathParams', 'Query', 'Body', 'Headers', 'Response', 'ResponseHeaders'])
   })
 
   it('omits slots whose source is null or undefined', () => {
     const slots = extractRouteSlots(
-      r({
-        input: { pathParams: { type: 'object' }, query: null, body: undefined },
-        // returnType missing
+      apiRoute({
+        req: { pathParams: { type: 'object' }, query: null, body: undefined },
       }),
     )
     expect(slots.map((s) => s.rootName)).toEqual(['PathParams'])
   })
 
-  it('attaches the source schema verbatim to each slot', () => {
+  it('attaches source schemas verbatim', () => {
     const path = { type: 'object', tag: 'p' }
-    const ret = { type: 'object', tag: 'r' }
-    const slots = extractRouteSlots(r({ input: { pathParams: path }, returnType: ret }))
+    const body = { type: 'object', tag: 'b' }
+    const slots = extractRouteSlots(apiRoute({ req: { pathParams: path, body }, res: {} }))
     expect(slots).toEqual([
       { rootName: 'PathParams', source: path },
-      { rootName: 'Response', source: ret },
+      { rootName: 'Body', source: body },
+    ])
+  })
+
+  it('reads responseHeaders from res.headers', () => {
+    const resHeaders = { type: 'object', tag: 'rh' }
+    const slots = extractRouteSlots(apiRoute({ res: { headers: resHeaders } }))
+    expect(slots).toEqual([{ rootName: 'ResponseHeaders', source: resHeaders }])
+  })
+})
+
+describe('extractRouteSlots — http-stream kind', () => {
+  it('returns no slots when jsonSchema is empty', () => {
+    expect(extractRouteSlots(httpStreamRoute({}))).toEqual([])
+  })
+
+  it('returns the deterministic slot order: PathParams, Query, Body, Headers, ResponseHeaders, Yield, ReturnType', () => {
+    const slots = extractRouteSlots(
+      httpStreamRoute({
+        req: {
+          pathParams: { type: 'object', tag: 'path' },
+          query: { type: 'object', tag: 'query' },
+          body: { type: 'object', tag: 'body' },
+          headers: { type: 'object', tag: 'headers' },
+        },
+        res: { headers: { type: 'object', tag: 'resHeaders' } },
+        yield: { type: 'object', tag: 'yield' },
+        returnType: { type: 'object', tag: 'return' },
+      }),
+    )
+    expect(slots.map((s) => s.rootName)).toEqual([
+      'PathParams', 'Query', 'Body', 'Headers', 'ResponseHeaders', 'Yield', 'ReturnType',
     ])
   })
 
-  it('returns no slots for stream/no-schema routes', () => {
-    const stream = { name: 'S', kind: 'stream', method: 'GET', path: '/s' } as unknown as AnyHttpRouteDoc
-    expect(extractRouteSlots(stream)).toEqual([])
+  it('attaches yield and returnType sources correctly', () => {
+    const yieldSchema = { type: 'object', tag: 'y' }
+    const returnSchema = { type: 'object', tag: 'r' }
+    const slots = extractRouteSlots(httpStreamRoute({ yield: yieldSchema, returnType: returnSchema }))
+    expect(slots).toEqual([
+      { rootName: 'Yield', source: yieldSchema },
+      { rootName: 'ReturnType', source: returnSchema },
+    ])
+  })
+})
+
+describe('extractRouteSlots — rpc kind', () => {
+  it('returns no slots when jsonSchema is empty', () => {
+    expect(extractRouteSlots(rpcRoute({}))).toEqual([])
+  })
+
+  it('maps body and response slots', () => {
+    const body = { type: 'object', tag: 'b' }
+    const response = { type: 'object', tag: 'r' }
+    const slots = extractRouteSlots(rpcRoute({ body, response }))
+    expect(slots).toEqual([
+      { rootName: 'Body', source: body },
+      { rootName: 'Response', source: response },
+    ])
+  })
+})
+
+describe('extractRouteSlots — stream kind', () => {
+  it('returns no slots when jsonSchema is empty', () => {
+    expect(extractRouteSlots(streamRoute({}))).toEqual([])
+  })
+
+  it('maps params→Body, yieldType→Yield, returnType→ReturnType', () => {
+    const params = { type: 'object', tag: 'p' }
+    const yieldType = { type: 'object', tag: 'y' }
+    const returnType = { type: 'object', tag: 'r' }
+    const slots = extractRouteSlots(streamRoute({ params, yieldType, returnType }))
+    expect(slots).toEqual([
+      { rootName: 'Body', source: params },
+      { rootName: 'Yield', source: yieldType },
+      { rootName: 'ReturnType', source: returnType },
+    ])
   })
 })

package/src/codegen/targets/_shared/route-slots.ts

@@ -1,9 +1,8 @@
 import type { AnyHttpRouteDoc } from '../../../implementations/types.js'
 
 /**
- * A "slot" is one of the deterministic schema sources a route exposes:
- * `pathParams`, `query`, `body` (under `schema.input`) and the response
- * (`schema.returnType`). Targets emit one type per non-null slot.
+ * A "slot" is one of the deterministic schema sources a route exposes.
+ * Targets emit one type per non-null slot.
  */
 export interface RouteSlot {
   /** Stable identifier used as the emitted type's `rootTypeName`. */
@@ -15,18 +14,56 @@ export interface RouteSlot {
 /**
  * Returns the deterministic ordered slot list for a route, filtered to slots
  * with non-null sources. Order is fixed at the module level for stable output.
+ *
+ * Kind dispatch:
+ * - `'api'`         — reads from `jsonSchema.req` / `jsonSchema.res` (new envelope shape)
+ * - `'http-stream'` — reads from `jsonSchema.req` / `jsonSchema.res` / `jsonSchema.yield` / `jsonSchema.returnType`
+ * - `'rpc'`         — reads from `jsonSchema.body` / `jsonSchema.response`
+ * - `'stream'`      — reads from `jsonSchema.params` / `jsonSchema.yieldType` / `jsonSchema.returnType`
  */
 export function extractRouteSlots(route: AnyHttpRouteDoc): RouteSlot[] {
-  const schema = (route as { schema?: Record<string, unknown> }).schema ?? {}
-  const input = (schema.input ?? {}) as Record<string, unknown>
+  const kind = route.kind
 
   // Order is load-bearing: targets emit slots in this sequence.
-  const slots: RouteSlot[] = [
-    { rootName: 'PathParams', source: input.pathParams },
-    { rootName: 'Query', source: input.query },
-    { rootName: 'Body', source: input.body },
-    { rootName: 'Response', source: schema.returnType },
-  ]
+  let slots: RouteSlot[]
+
+  if (kind === 'api') {
+    const req = route.jsonSchema.req ?? {}
+    const res = route.jsonSchema.res ?? {}
+    slots = [
+      { rootName: 'PathParams', source: req.pathParams },
+      { rootName: 'Query', source: req.query },
+      { rootName: 'Body', source: req.body },
+      { rootName: 'Headers', source: req.headers },
+      { rootName: 'Response', source: res.body },
+      { rootName: 'ResponseHeaders', source: res.headers },
+    ]
+  } else if (kind === 'http-stream') {
+    const req = route.jsonSchema.req ?? {}
+    const res = route.jsonSchema.res ?? {}
+    slots = [
+      { rootName: 'PathParams', source: req.pathParams },
+      { rootName: 'Query', source: req.query },
+      { rootName: 'Body', source: req.body },
+      { rootName: 'Headers', source: req.headers },
+      { rootName: 'ResponseHeaders', source: res.headers },
+      { rootName: 'Yield', source: route.jsonSchema.yield },
+      { rootName: 'ReturnType', source: route.jsonSchema.returnType },
+    ]
+  } else if (kind === 'rpc') {
+    slots = [
+      { rootName: 'Body', source: route.jsonSchema.body },
+      { rootName: 'Response', source: route.jsonSchema.response },
+    ]
+  } else if (kind === 'stream') {
+    slots = [
+      { rootName: 'Body', source: route.jsonSchema.params },
+      { rootName: 'Yield', source: route.jsonSchema.yieldType },
+      { rootName: 'ReturnType', source: route.jsonSchema.returnType },
+    ]
+  } else {
+    slots = []
+  }
 
   return slots.filter((s) => s.source != null)
 }

package/src/codegen/targets/kotlin/__fixtures__/users-golden.kt

@@ -118,4 +118,77 @@ object Users {
             )
         }
     }
+
+    object DownloadUser {
+        const val method = "GET"
+        const val pathTemplate = "/users/{id}/download"
+        fun path(p: PathParams): String = "/users/${p.id}/download"
+
+        @Serializable
+        data class PathParams(
+            val id: String,
+        )
+
+        @Serializable
+        data class Response(
+            val id: String,
+            val name: String,
+            @SerialName("created-at") @Contextual val createdAt: java.time.Instant,
+            val address: Address,
+        ) {
+            @Serializable
+            data class Address(
+                val street: String,
+                val city: String,
+            )
+        }
+
+        @Serializable
+        data class ResponseHeaders(
+            @SerialName("x-download-token") val xDownloadToken: String,
+            @SerialName("content-disposition") val contentDisposition: String? = null,
+        )
+    }
+
+    object WatchUsers {
+        const val method = "GET"
+        const val pathTemplate = "/users/watch"
+        const val path = "/users/watch"
+
+        @Serializable
+        data class Query(
+            val status: Status? = null,
+            val limit: Long? = null,
+        ) {
+            @Serializable
+            enum class Status {
+                @SerialName("active") ACTIVE,
+                @SerialName("inactive") INACTIVE,
+            }
+        }
+
+        @Serializable
+        data class ResponseHeaders(
+            @SerialName("x-download-token") val xDownloadToken: String,
+            @SerialName("content-disposition") val contentDisposition: String? = null,
+        )
+
+        @Serializable
+        data class Yield(
+            val id: String,
+            val event: Event,
+        ) {
+            @Serializable
+            enum class Event {
+                @SerialName("created") CREATED,
+                @SerialName("updated") UPDATED,
+                @SerialName("deleted") DELETED,
+            }
+        }
+
+        @Serializable
+        data class ReturnType(
+            val count: Long,
+        )
+    }
 }