ts-procedures 8.3.0 → 8.4.0

package/src/codegen/emit-models.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest'
+import { emitModelsFile } from './emit-models.js'
+import type { ResolvedModel } from './collect-models.js'
+
+const thread: ResolvedModel = {
+  id: 'urn:thread', name: 'Thread',
+  schema: { type: 'object', $id: 'urn:thread', title: 'Thread',
+    properties: { id: { type: 'string' }, author: { type: 'object', $id: 'urn:msg', title: 'Message', properties: { id: { type: 'string' } } } } } as any,
+}
+const messageGenerated: ResolvedModel = {
+  id: 'urn:msg', name: 'Message',
+  schema: { type: 'object', $id: 'urn:msg', title: 'Message', properties: { id: { type: 'string' } } } as any,
+}
+const messageImported: ResolvedModel = {
+  id: 'urn:msg', name: 'Message', schema: {} as any,
+  import: { module: '@shared/schemas', name: 'Message' },
+}
+
+describe('emitModelsFile', () => {
+  it('returns null when there are no models', async () => {
+    expect(await emitModelsFile([], { ajsc: {} })).toBeNull()
+  })
+
+  it('declares a generated model as a named type', async () => {
+    const code = await emitModelsFile([messageGenerated], { ajsc: {} })
+    expect(code).toMatch(/export type Message =/)
+  })
+
+  it('re-exports a mapped model from the user package', async () => {
+    const code = await emitModelsFile([messageImported], { ajsc: {} })
+    expect(code).toContain("export { Message } from '@shared/schemas'")
+  })
+
+  it('aliases a re-export when local name differs from the package name', async () => {
+    const m: ResolvedModel = { id: 'urn:msg', name: 'ChatMessage', schema: {} as any, import: { module: '@shared/schemas', name: 'Message' } }
+    const code = await emitModelsFile([m], { ajsc: {} })
+    expect(code).toContain("export { Message as ChatMessage } from '@shared/schemas'")
+  })
+
+  it('a generated model that nests another model references it by name, not inlined', async () => {
+    // Thread.author is the Message model — Thread should reference Message, not inline { id }
+    const code = await emitModelsFile([thread, messageGenerated], { ajsc: {} })
+    // Thread's author property is typed as Message (the model), referenced by bare name
+    expect(code).toMatch(/author\??:\s*Message/)
+    // and there is no leftover placeholder token
+    expect(code).not.toContain('__MODELREF__')
+  })
+})

package/src/codegen/emit-models.ts

@@ -0,0 +1,63 @@
+import { jsonSchemaToTypeBody, type AjscOptions } from './emit-types.js'
+import { substituteModelRefs } from './model-refs.js'
+import { CODEGEN_HEADER } from './constants.js'
+import type { ResolvedModel } from './collect-models.js'
+
+export interface EmitModelsOptions {
+  ajsc?: AjscOptions
+}
+
+/**
+ * Emits the shared `_models.ts` hub: one named TypeScript type per `$id`-bearing
+ * schema so routes can reference a single entity type instead of inlining copies.
+ *
+ * Two kinds of model:
+ *   - **Imported** (`model.import` set): re-exported from the user's package —
+ *     `export { <PkgName>[ as <LocalName>] } from '<module>'`.
+ *   - **Generated** (no `import`): converted from JSON Schema to a TS type via
+ *     ajsc. Nested OTHER models are first rewritten to `x-named-type` nodes
+ *     ({@link substituteModelRefs} with `skipSelfId` so the model's own root
+ *     `$id` is not self-referenced); ajsc (≥7.3.0) then emits each nested model
+ *     as a bare verbatim reference rather than re-inlining its shape.
+ *
+ * Declarations are kept FLAT at the top level regardless of `namespaceTypes` —
+ * scopes import these by bare name and TS `type` aliases permit forward
+ * references, so declaration order does not matter. Re-exports are emitted first,
+ * then generated declarations.
+ *
+ * Returns `null` when there are no models.
+ */
+export async function emitModelsFile(
+  models: ResolvedModel[],
+  opts: EmitModelsOptions,
+): Promise<string | null> {
+  if (models.length === 0) return null
+
+  const idToName = new Map(models.map((m) => [m.id, m.name]))
+
+  const reExports: string[] = []
+  const declarations: string[] = []
+
+  for (const model of models) {
+    if (model.import) {
+      const pkgName = model.import.name
+      const localName = model.name
+      const clause = pkgName === localName ? pkgName : `${pkgName} as ${localName}`
+      reExports.push(`export { ${clause} } from '${model.import.module}'`)
+      continue
+    }
+
+    // Generated model: rewrite nested OTHER models to `x-named-type` nodes so
+    // ajsc emits them as bare references, then convert to a TS body.
+    const substituted = substituteModelRefs(model.schema, idToName, model.id)
+    const body = await jsonSchemaToTypeBody(substituted.schema, opts.ajsc)
+    if (body == null) continue
+    declarations.push(`export type ${model.name} = ${body}`)
+  }
+
+  const blocks: string[] = []
+  if (reExports.length > 0) blocks.push(reExports.join('\n'))
+  for (const decl of declarations) blocks.push(decl)
+
+  return [CODEGEN_HEADER, '', blocks.join('\n\n')].join('\n')
+}

package/src/codegen/emit-scope.ts

@@ -8,12 +8,14 @@ import type {
 import {
   jsonSchemaToTypeString,
   jsonSchemaToTypeBody,
+  jsonSchemaToTypeBodyWithRefs,
   jsonSchemaToExtractedTypes,
   renameExtractedTypes,
   extractedDeclName,
   type AjscOptions,
   type ExtractedTypeOutput,
 } from './emit-types.js'
+import { substituteModelRefs } from './model-refs.js'
 import { CODEGEN_HEADER } from './constants.js'
 import { toPascalCase } from './naming.js'
 
@@ -33,6 +35,16 @@ export interface EmitScopeOptions {
    * so generated code never references undefined types.
    */
   errorKeys?: Set<string>
+  /**
+   * Maps a model `$id` to its shared model type name (built by the run module
+   * from ALL models — generated and imported). When present and non-empty,
+   * `$id` subschemas are rewritten to `x-named-type` nodes before ajsc; ajsc
+   * emits bare references and reports them via `referencedNamedTypes`, which
+   * drives the `import type { … } from './_models'` line. Absent/empty →
+   * identical inlining behaviour (the conversion wrappers short-circuit so
+   * output is byte-identical for envelopes without models).
+   */
+  idToModelName?: Map<string, string>
 }
 
 interface RouteChunks {
@@ -49,6 +61,14 @@ interface EmitRouteContext {
   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>
 }
 
 // ---------------------------------------------------------------------------
@@ -110,6 +130,79 @@ function indent(text: string, prefix: string): string {
   return text.split('\n').map((line) => (line ? prefix + line : line)).join('\n')
 }
 
+// ---------------------------------------------------------------------------
+// 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.
+ */
+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.
+ */
+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
+}
+
 /**
  * Tracks extracted declarations emitted into a single namespace, guarding
  * against duplicate identifiers (defense-in-depth on top of the rename pass).
@@ -200,7 +293,7 @@ async function formatTypes(
     for (const { shortName, schema } of types) {
       if (schema == null) continue
 
-      const rawResult = await jsonSchemaToExtractedTypes(schema, ctx.ajsc)
+      const rawResult = await convertExtracted(schema, ctx)
       if (rawResult == null) continue
 
       const result = renameExtractedTypes(rawResult, taken)
@@ -223,7 +316,7 @@ async function formatTypes(
       if (schema == null) continue
 
       const flatName = `${routePascal}${shortName}`
-      const body = await jsonSchemaToTypeBody(schema, ctx.ajsc)
+      const body = await convertBody(schema, ctx)
       if (body == null) continue
 
       declarations.push(`export type ${flatName} = ${body}`)
@@ -359,7 +452,7 @@ async function formatSubNamespace(
     if (schema == null) continue
 
     if (ctx.namespaceTypes) {
-      const rawResult = await jsonSchemaToExtractedTypes(schema, ctx.ajsc)
+      const rawResult = await convertExtracted(schema, ctx)
       if (rawResult == null) continue
 
       const result = renameExtractedTypes(rawResult, taken)
@@ -373,7 +466,7 @@ async function formatSubNamespace(
       refs[shortName] = `${ctx.scopePascal}.${routePascal}.${nsName}.${shortName}`
     } else {
       const flatName = `${routePascal}${nsName}${shortName}`
-      const body = await jsonSchemaToTypeBody(schema, ctx.ajsc)
+      const body = await convertBody(schema, ctx)
       if (body == null) continue
       refs[shortName] = flatName
     }
@@ -443,7 +536,8 @@ async function emitApiRoute(route: APIHttpRouteDoc, ctx: EmitRouteContext): Prom
   let paramsTypeName = 'unknown'
   let returnTypeName = 'void'
 
-  // Track reserved names across all sub-namespaces
+  // 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) {
@@ -493,7 +587,7 @@ async function emitApiRoute(route: APIHttpRouteDoc, ctx: EmitRouteContext): Prom
     for (const { shortName, schema } of reqTypes) {
       if (schema == null) continue
       const flatName = `${pascal}Req${shortName}`
-      const body = await jsonSchemaToTypeBody(schema, ctx.ajsc)
+      const body = await convertBody(schema, ctx)
       if (body == null) continue
       declarations.push(`export type ${flatName} = ${body}`)
     }
@@ -514,7 +608,7 @@ async function emitApiRoute(route: APIHttpRouteDoc, ctx: EmitRouteContext): Prom
     for (const { shortName, schema } of resTypes) {
       if (schema == null) continue
       const flatName = `${pascal}Response${shortName}`
-      const body = await jsonSchemaToTypeBody(schema, ctx.ajsc)
+      const body = await convertBody(schema, ctx)
       if (body == null) continue
       declarations.push(`export type ${flatName} = ${body}`)
       if (shortName === 'Body') bodyRef = flatName
@@ -619,7 +713,7 @@ async function emitHttpStreamRoute(route: HttpStreamRouteDoc, ctx: EmitRouteCont
     const collector = new DeclarationCollector(`namespace ${pascal}`)
     for (const { shortName, schema } of directTypes) {
       if (schema == null) continue
-      const rawResult = await jsonSchemaToExtractedTypes(schema, ctx.ajsc)
+      const rawResult = await convertExtracted(schema, ctx)
       if (rawResult == null) continue
       const result = renameExtractedTypes(rawResult, taken)
       for (const decl of result.declarations) {
@@ -644,7 +738,7 @@ async function emitHttpStreamRoute(route: HttpStreamRouteDoc, ctx: EmitRouteCont
     for (const { shortName, schema } of reqTypes) {
       if (schema == null) continue
       const flatName = `${pascal}Req${shortName}`
-      const body = await jsonSchemaToTypeBody(schema, ctx.ajsc)
+      const body = await convertBody(schema, ctx)
       if (body == null) continue
       declarations.push(`export type ${flatName} = ${body}`)
     }
@@ -658,12 +752,12 @@ async function emitHttpStreamRoute(route: HttpStreamRouteDoc, ctx: EmitRouteCont
     }
 
     if (resHeadersSchema != null) {
-      const body = await jsonSchemaToTypeBody(resHeadersSchema, ctx.ajsc)
+      const body = await convertBody(resHeadersSchema, ctx)
       if (body != null) declarations.push(`export type ${pascal}ResponseHeaders = ${body}`)
     }
 
     if (yieldSchema != null) {
-      const body = await jsonSchemaToTypeBody(yieldSchema, ctx.ajsc)
+      const body = await convertBody(yieldSchema, ctx)
       if (body != null) {
         declarations.push(`export type ${pascal}Yield = ${body}`)
         yieldTypeName = `${pascal}Yield`
@@ -671,7 +765,7 @@ async function emitHttpStreamRoute(route: HttpStreamRouteDoc, ctx: EmitRouteCont
     }
 
     if (returnSchema != null) {
-      const body = await jsonSchemaToTypeBody(returnSchema, ctx.ajsc)
+      const body = await convertBody(returnSchema, ctx)
       if (body != null) {
         declarations.push(`export type ${pascal}ReturnType = ${body}`)
         returnTypeName = `${pascal}ReturnType`
@@ -770,15 +864,19 @@ export async function emitScopeFile(
     namespaceTypes = false,
     serviceName = 'Api',
     errorKeys,
+    idToModelName,
   } = options ?? {}
 
   const pascal = toPascalCase(group.camelCase)
+  const referencedModels = new Set<string>()
   const ctx: EmitRouteContext = {
     ajsc: ajscOpts,
     namespaceTypes,
     scopePascal: pascal,
     serviceName,
     errorKeys,
+    idToModelName,
+    referencedModels,
   }
 
   const allTypeDeclarations: string[] = []
@@ -833,10 +931,13 @@ export async function emitScopeFile(
     }
   }
 
-  const importsBlock = [clientImports, errorsImport].filter(Boolean).join('\n')
-
   const callablesBlock = callables.join('\n\n')
 
+  // Assemble the type + callable section for this scope. ajsc already emitted
+  // bare model references (via `x-named-type`); `convertExtracted` / `convertBody`
+  // folded the reported names into `ctx.referencedModels`, which drives the
+  // `_models` import below. No post-pass over the body is needed.
+  let body: string
   if (namespaceTypes) {
     // Namespace mode: types AND `bindScope` live inside `export namespace ${pascal}`.
     // Putting the function inside the namespace makes the merged symbol
@@ -857,36 +958,47 @@ export async function emitScopeFile(
       ].join('\n'),
     ].join('\n\n')
 
-    return [
-      CODEGEN_HEADER,
-      importsBlock,
-      '',
+    body = [
       `export namespace ${pascal} {`,
       namespaceMembers,
       '}',
       '',
     ].join('\n')
+  } else {
+    // Flat mode: types at module level, `bind${pascal}Scope` standalone.
+    const typesBlock = allTypeDeclarations.length > 0
+      ? allTypeDeclarations.join('\n') + '\n'
+      : ''
+
+    body = [
+      '// ── Types ────────────────────────────────────────',
+      '',
+      typesBlock,
+      '// ── Callables ────────────────────────────────────',
+      '',
+      `export function bind${pascal}Scope(client: ClientInstance) {`,
+      '  return {',
+      callablesBlock,
+      '  }',
+      '}',
+      '',
+    ].join('\n')
   }
 
-  // Flat mode: types at module level, `bind${pascal}Scope` standalone.
-  const typesBlock = allTypeDeclarations.length > 0
-    ? allTypeDeclarations.join('\n') + '\n'
-    : ''
+  // Build the shared-models import line when any route referenced a `$id` model.
+  // Matches the `_errors` import convention exactly: `'./_models'` with no `.js`.
+  let modelsImport = ''
+  if (referencedModels.size > 0) {
+    const names = [...referencedModels].sort().join(', ')
+    modelsImport = `import type { ${names} } from './_models'`
+  }
+
+  const importsBlock = [clientImports, errorsImport, modelsImport].filter(Boolean).join('\n')
 
   return [
     CODEGEN_HEADER,
     importsBlock,
     '',
-    '// ── Types ────────────────────────────────────────',
-    '',
-    typesBlock,
-    '// ── Callables ────────────────────────────────────',
-    '',
-    `export function bind${pascal}Scope(client: ClientInstance) {`,
-    '  return {',
-    callablesBlock,
-    '  }',
-    '}',
-    '',
+    body,
   ].join('\n')
 }

package/src/codegen/emit-types.ts

@@ -22,7 +22,7 @@ async function validateAjscFormat() {
 async function resolveTypeBody(
   schema: Record<string, unknown>,
   options?: AjscOptions,
-): Promise<string> {
+): Promise<{ body: string; referencedNamedTypes: string[] }> {
   await validateAjscFormat()
 
   const { TypescriptConverter } = await import('ajsc')
@@ -43,7 +43,9 @@ async function resolveTypeBody(
   // Remove trailing semicolons and newlines
   code = code.replace(/;\s*$/, '').trim()
 
-  return code
+  const referencedNamedTypes = (converter.referencedNamedTypes as string[] | undefined) ?? []
+
+  return { body: code, referencedNamedTypes }
 }
 
 /**
@@ -60,8 +62,8 @@ export async function jsonSchemaToTypeString(
   options?: AjscOptions,
 ): Promise<string | undefined> {
   if (schema == null) return undefined
-  const code = await resolveTypeBody(schema, options)
-  return `export type ${typeName} = ${code}`
+  const { body } = await resolveTypeBody(schema, options)
+  return `export type ${typeName} = ${body}`
 }
 
 /**
@@ -76,6 +78,23 @@ export async function jsonSchemaToTypeBody(
   schema: Record<string, unknown> | undefined,
   options?: AjscOptions,
 ): Promise<string | undefined> {
+  if (schema == null) return undefined
+  const { body } = await resolveTypeBody(schema, options)
+  return body
+}
+
+/**
+ * Like {@link jsonSchemaToTypeBody} but also surfaces the ajsc converter's
+ * `referencedNamedTypes` — the bare type names emitted verbatim because they
+ * carried an `x-named-type` keyword (see `model-refs.ts`). Drives the
+ * `_models` import in flat-mode scope emission.
+ *
+ * Returns undefined for undefined or null schema.
+ */
+export async function jsonSchemaToTypeBodyWithRefs(
+  schema: Record<string, unknown> | undefined,
+  options?: AjscOptions,
+): Promise<{ body: string; referencedNamedTypes: string[] } | undefined> {
   if (schema == null) return undefined
   return resolveTypeBody(schema, options)
 }
@@ -89,6 +108,19 @@ export interface ExtractedTypeOutput {
   declarations: string[]
   /** The root type body (bare literal, e.g., `{ user: User; }`) without the `export type Root =` wrapper. */
   body: string
+  /**
+   * Bare type names ajsc emitted verbatim (because they carried an
+   * `x-named-type` keyword — see `model-refs.ts`). Drives the `_models`
+   * import in namespace-mode scope emission. Empty when no models referenced.
+   */
+  referencedNamedTypes: string[]
+  /**
+   * Names ajsc declared/extracted as named sub-types in this output (its own
+   * `extractedTypeNames`). Intersecting this with {@link referencedNamedTypes}
+   * is ajsc's documented signal that an `x-named-type` model collided with a
+   * structural sub-type of the same name (see `assertNoModelNameCollision`).
+   */
+  extractedTypeNames: string[]
 }
 
 /**
@@ -154,6 +186,9 @@ export async function jsonSchemaToExtractedTypes(
     inlineTypes: false,
   })
 
+  const referencedNamedTypes = (converter.referencedNamedTypes as string[] | undefined) ?? []
+  const extractedTypeNames = (converter.extractedTypeNames as string[] | undefined) ?? []
+
   const code = (converter.code as string).trim()
   if (!code) {
     throw new Error(
@@ -206,7 +241,7 @@ export async function jsonSchemaToExtractedTypes(
       .trim()
   }
 
-  return { declarations, body }
+  return { declarations, body, referencedNamedTypes, extractedTypeNames }
 }
 
 /**
@@ -245,7 +280,8 @@ export function extractedDeclName(decl: string): string | undefined {
  * name (a latent wrong-type bug that only hides when the shapes happen to match).
  */
 export function renameExtractedTypes(
-  result: ExtractedTypeOutput,
+  result: Omit<ExtractedTypeOutput, 'referencedNamedTypes' | 'extractedTypeNames'> &
+    Partial<Pick<ExtractedTypeOutput, 'referencedNamedTypes' | 'extractedTypeNames'>>,
   taken: Set<string>,
 ): ExtractedTypeOutput {
   // Work on a mutable copy so we can patch cross-references after renaming.
@@ -293,5 +329,10 @@ export function renameExtractedTypes(
     }
   }
 
-  return { declarations, body }
+  return {
+    declarations,
+    body,
+    referencedNamedTypes: result.referencedNamedTypes ?? [],
+    extractedTypeNames: result.extractedTypeNames ?? [],
+  }
 }

package/src/codegen/index.ts

@@ -1,6 +1,7 @@
 import { resolveEnvelope, type ResolveInput } from './resolve-envelope.js'
 import { runPipeline, type GeneratedFile } from './pipeline.js'
 import type { AjscOptions } from './emit-types.js'
+import type { SharedTypesImportMap } from './collect-models.js'
 import type { KotlinEmitter } from './targets/kotlin/ajsc-adapter.js'
 import type { SwiftEmitter } from './targets/swift/ajsc-adapter.js'
 
@@ -13,6 +14,10 @@ export interface GenerateClientOptions extends ResolveInput {
   selfContained?: boolean
   serviceName?: string
   cleanOutDir?: boolean
+  /** Hoist `$id`-bearing schemas into a shared `_models.ts` and reference them from scopes (TS target). */
+  shareModels?: boolean
+  /** Maps a model `$id` to an external import so a shared model is re-exported rather than generated. */
+  sharedTypesImport?: SharedTypesImportMap
   target?: 'ts' | 'kotlin' | 'swift'
   kotlinPackage?: string
   kotlinSerializer?: 'kotlinx' | 'none'
@@ -37,6 +42,8 @@ export async function generateClient(options: GenerateClientOptions): Promise<Ge
     selfContained: options.selfContained,
     serviceName: options.serviceName,
     cleanOutDir: options.cleanOutDir,
+    shareModels: options.shareModels,
+    sharedTypesImport: options.sharedTypesImport,
     target: options.target,
     kotlinPackage: options.kotlinPackage,
     kotlinSerializer: options.kotlinSerializer,

package/src/codegen/model-refs.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest'
+import { substituteModelRefs } from './model-refs.js'
+
+const message = { type: 'object', $id: 'urn:msg', title: 'Message', properties: { id: { type: 'string' } } }
+
+describe('substituteModelRefs', () => {
+  it('replaces an $id subschema with an x-named-type node keyed by model name', () => {
+    const schema = { type: 'object', properties: { author: message, tags: { type: 'array', items: message } } }
+    const idToName = new Map([['urn:msg', 'Message']])
+    const { schema: out, referenced } = substituteModelRefs(schema, idToName)
+    expect((out as any).properties.author).toEqual({ 'x-named-type': 'Message' })
+    expect((out as any).properties.tags.items).toEqual({ 'x-named-type': 'Message' })
+    expect([...referenced]).toEqual(['Message'])
+  })
+
+  it('does not mutate the input schema', () => {
+    const schema = { type: 'object', properties: { author: message } }
+    const before = JSON.stringify(schema)
+    substituteModelRefs(schema, new Map([['urn:msg', 'Message']]))
+    expect(JSON.stringify(schema)).toBe(before)
+  })
+
+  it('leaves the schema untouched when no $id is in the registry', () => {
+    const schema = { type: 'object', properties: { author: message } }
+    const { schema: out, referenced } = substituteModelRefs(schema, new Map())
+    expect(out).toEqual(schema)
+    expect(referenced.size).toBe(0)
+  })
+
+  it('does NOT replace the node when its own $id is the registry root being emitted (optional skipSelfId)', () => {
+    // When emitting the Message model itself, we don't want Message to become a ref to itself.
+    const idToName = new Map([['urn:msg', 'Message']])
+    const { schema: out } = substituteModelRefs(message, idToName, 'urn:msg')
+    expect(out).not.toHaveProperty('x-named-type')
+    expect(out.$id).toBe('urn:msg')
+  })
+})

package/src/codegen/model-refs.ts

@@ -0,0 +1,57 @@
+/**
+ * Shared-`$id` model referencing via ajsc's `x-named-type` keyword (ajsc ≥7.3.0).
+ *
+ * ajsc inlines plain `$ref`s, so to make a route reference a hoisted model by
+ * name instead of re-inlining its shape, {@link substituteModelRefs} rewrites
+ * each `$id` subschema (BEFORE ajsc runs) into `{ 'x-named-type': '<Name>' }`.
+ * ajsc then emits a bare verbatim reference to `<Name>` (surviving arrays and
+ * both `inlineTypes` modes, never extracted as a sub-type) and reports it via
+ * the converter's `referencedNamedTypes` — which the emitter uses to add the
+ * `import type { … } from './_models'` line.
+ */
+
+/**
+ * Returns a deep-cloned schema where every object node carrying a `$id` present
+ * in `idToName` is replaced by `{ 'x-named-type': '<Name>' }`. The input is
+ * never mutated.
+ *
+ * - Replaced nodes are NOT recursed into (they're gone).
+ * - A node whose `$id === skipSelfId` is left in place (used when emitting that
+ *   model itself), but its CHILDREN are still recursed so nested OTHER models are
+ *   still referenced.
+ *
+ * @returns the rewritten schema and the set of referenced model names.
+ */
+export function substituteModelRefs(
+  schema: Record<string, unknown>,
+  idToName: Map<string, string>,
+  skipSelfId?: string
+): { schema: Record<string, unknown>; referenced: Set<string> } {
+  const referenced = new Set<string>()
+
+  const walk = (node: unknown): unknown => {
+    if (Array.isArray(node)) {
+      return node.map((item) => walk(item))
+    }
+    if (!node || typeof node !== 'object') return node
+
+    const obj = node as Record<string, unknown>
+    const id = typeof obj.$id === 'string' ? obj.$id : undefined
+
+    if (id !== undefined && id !== skipSelfId && idToName.has(id)) {
+      const name = idToName.get(id)!
+      referenced.add(name)
+      // Replace entirely — do not recurse into a node that's being swapped out.
+      return { 'x-named-type': name }
+    }
+
+    // Either no $id, or the self node we're emitting: deep-clone children and recurse.
+    const out: Record<string, unknown> = {}
+    for (const [k, v] of Object.entries(obj)) {
+      out[k] = walk(v)
+    }
+    return out
+  }
+
+  return { schema: walk(structuredClone(schema)) as Record<string, unknown>, referenced }
+}