ts-procedures 8.3.0 → 8.5.0

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,20 @@ 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
+  /** Single module every $id-bearing model re-exports from (convention; `sharedTypesImport` entries override). */
+  sharedModelsModule?: string
+  /** Hard-fail codegen if any $id-bearing model would be generated as a local structural twin. */
+  strictSharedModels?: boolean
+  /**
+   * Sink for non-error progress messages (e.g. the shared-models summary).
+   * Omitted by default so programmatic callers produce no console output; pass
+   * `console.log` to opt in. The CLI wires this to stdout.
+   */
+  logger?: (message: string) => void
   target?: 'ts' | 'kotlin' | 'swift'
   kotlinPackage?: string
   kotlinSerializer?: 'kotlinx' | 'none'
@@ -37,6 +52,11 @@ export async function generateClient(options: GenerateClientOptions): Promise<Ge
     selfContained: options.selfContained,
     serviceName: options.serviceName,
     cleanOutDir: options.cleanOutDir,
+    shareModels: options.shareModels,
+    sharedTypesImport: options.sharedTypesImport,
+    sharedModelsModule: options.sharedModelsModule,
+    strictSharedModels: options.strictSharedModels,
+    logger: options.logger,
     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 }
+}

package/src/codegen/pipeline.ts

@@ -2,6 +2,7 @@ import { createHash } from 'node:crypto'
 import type { DocEnvelope } from '../implementations/types.js'
 import type { AjscOptions } from './emit-types.js'
 import { groupRoutesByScope } from './group-routes.js'
+import type { SharedTypesImportMap } from './collect-models.js'
 import { validateServiceName } from './naming.js'
 import type { GeneratedFile } from './targets/_shared/write-files.js'
 import type { KotlinEmitter } from './targets/kotlin/ajsc-adapter.js'
@@ -20,6 +21,12 @@ export interface PipelineOptions {
   selfContained?: boolean
   serviceName?: string
   cleanOutDir?: boolean
+  shareModels?: boolean
+  sharedTypesImport?: SharedTypesImportMap
+  sharedModelsModule?: string
+  strictSharedModels?: boolean
+  /** Sink for non-error progress messages (shared-models summary). Defaults to silent. */
+  logger?: (message: string) => void
   target?: 'ts' | 'kotlin' | 'swift'
   kotlinPackage?: string
   kotlinSerializer?: 'kotlinx' | 'none'
@@ -43,7 +50,7 @@ export type { GeneratedFile } from './targets/_shared/write-files.js'
  * `_shared/write-files.ts`).
  */
 export async function runPipeline(options: PipelineOptions): Promise<GeneratedFile[]> {
-  const { envelope, outDir, ajsc: ajscOpts, dryRun = false, namespaceTypes = false, selfContained = false, cleanOutDir = true } = options
+  const { envelope, outDir, ajsc: ajscOpts, dryRun = false, namespaceTypes = false, selfContained = false, cleanOutDir = true, shareModels = true } = options
   const serviceName = options.serviceName ?? 'Api'
   validateServiceName(serviceName)
 
@@ -67,6 +74,11 @@ export async function runPipeline(options: PipelineOptions): Promise<GeneratedFi
     namespaceTypes,
     selfContained,
     cleanOutDir,
+    shareModels,
+    sharedTypesImport: options.sharedTypesImport,
+    sharedModelsModule: options.sharedModelsModule,
+    strictSharedModels: options.strictSharedModels,
+    logger: options.logger,
   }
 
   switch (options.target) {

package/src/codegen/schema-walk.test.ts

@@ -0,0 +1,37 @@
+import { describe, it, expect } from 'vitest'
+import { walkSubschemas } from './schema-walk.js'
+
+describe('walkSubschemas', () => {
+  it('visits every plain-object node, including nested and array-nested ones', () => {
+    const tree = {
+      type: 'object',
+      properties: {
+        a: { type: 'string' },
+        b: { type: 'array', items: { type: 'number' } },
+      },
+      anyOf: [{ const: 1 }, { const: 2 }],
+    }
+    const seen: Array<Record<string, unknown>> = []
+    walkSubschemas(tree, (obj) => seen.push(obj))
+    // root + properties + a + b + items + 2 anyOf entries = 7 object nodes
+    expect(seen).toHaveLength(7)
+    expect(seen[0]).toBe(tree)
+    expect(seen).toContainEqual({ type: 'number' })
+    expect(seen).toContainEqual({ const: 1 })
+  })
+
+  it('does not invoke visit on arrays or primitives', () => {
+    const seen: Array<Record<string, unknown>> = []
+    walkSubschemas([1, 'two', { x: 1 }], (obj) => seen.push(obj))
+    expect(seen).toEqual([{ x: 1 }])
+  })
+
+  it('is a no-op for null, primitives, and bare arrays of primitives', () => {
+    const seen: Array<Record<string, unknown>> = []
+    walkSubschemas(null, (obj) => seen.push(obj))
+    walkSubschemas('str', (obj) => seen.push(obj))
+    walkSubschemas(42, (obj) => seen.push(obj))
+    walkSubschemas(['a', 'b'], (obj) => seen.push(obj))
+    expect(seen).toEqual([])
+  })
+})

package/src/codegen/schema-walk.ts

@@ -0,0 +1,23 @@
+/**
+ * Read-only recursive traversal of a JSON-Schema-shaped value.
+ *
+ * Recurses into arrays and into the values of plain objects, invoking `visit`
+ * on every plain-object node encountered (including the root, if it is one).
+ * Arrays are not passed to `visit` — only object nodes are. The traversal does
+ * not mutate the tree and does not prune: a visited node's children are always
+ * recursed.
+ *
+ * For mutation/substitution semantics (deep-clone, replace-and-prune), see
+ * `substituteModelRefs` in `model-refs.ts`, which keeps its own bespoke walk.
+ */
+export function walkSubschemas(node: unknown, visit: (obj: Record<string, unknown>) => void): void {
+  if (Array.isArray(node)) {
+    for (const item of node) walkSubschemas(item, visit)
+    return
+  }
+  if (!node || typeof node !== 'object') return
+
+  const obj = node as Record<string, unknown>
+  visit(obj)
+  for (const value of Object.values(obj)) walkSubschemas(value, visit)
+}

package/src/codegen/targets/_shared/target-run.ts

@@ -1,6 +1,7 @@
 import type { DocEnvelope } from '../../../implementations/types.js'
 import type { ScopeGroup } from '../../group-routes.js'
 import type { AjscOptions } from '../../emit-types.js'
+import type { SharedTypesImportMap } from '../../collect-models.js'
 
 /**
  * Inputs the dispatcher prepares once and forwards to every per-target
@@ -25,4 +26,18 @@ export interface TargetRunInput {
   namespaceTypes?: boolean
   selfContained?: boolean
   cleanOutDir?: boolean
+  /** Hoist `$id`-bearing schemas into a shared `_models.ts` (TS target only). */
+  shareModels?: boolean
+  /** Maps a model `$id` to an external import (re-exported instead of generated). */
+  sharedTypesImport?: SharedTypesImportMap
+  /** Single module every $id-bearing model re-exports from (convention; map entries override). */
+  sharedModelsModule?: string
+  /** When true, hard-fail if any $id-bearing model has no shared-type mapping (would be a local twin). */
+  strictSharedModels?: boolean
+  /**
+   * Sink for non-error progress messages (e.g. the shared-models summary).
+   * Defaults to undefined — programmatic callers stay silent; the CLI injects
+   * `console.log`. Output belongs to the caller, not the run module.
+   */
+  logger?: (message: string) => void
 }

package/src/codegen/targets/ts/run.ts

@@ -14,6 +14,8 @@ import { emitIndexFile } from '../../emit-index.js'
 import { emitErrorsFile } from '../../emit-errors.js'
 import { emitClientTypesFile } from '../../emit-client-types.js'
 import { emitClientRuntimeFile } from '../../emit-client-runtime.js'
+import { collectModels, resolveModelImports } from '../../collect-models.js'
+import { emitModelsFile } from '../../emit-models.js'
 
 export type TsRunInput = TargetRunInput
 
@@ -30,7 +32,12 @@ export async function runTsPipeline(input: TsRunInput): Promise<GeneratedFile[]>
     namespaceTypes = false,
     selfContained = false,
     cleanOutDir = false,
+    sharedTypesImport,
+    sharedModelsModule,
+    strictSharedModels = false,
+    logger,
   } = input
+  const shareModels = input.shareModels ?? false
 
   const hashComment = `// Source hash: ${hash}`
 
@@ -51,6 +58,39 @@ export async function runTsPipeline(input: TsRunInput): Promise<GeneratedFile[]>
     }
   }
 
+  // Shared models: hoist every `$id`-bearing schema into `_models.ts` and pass an
+  // id→name map so scope emission references them instead of inlining. The map
+  // covers ALL models (generated AND externally-imported) since scopes always
+  // import shared types from `./_models`.
+  const models = shareModels
+    ? resolveModelImports(collectModels(envelope.routes), { sharedTypesImport, sharedModelsModule })
+    : []
+  const idToModelName = new Map(models.map((m) => [m.id, m.name]))
+
+  if (shareModels) {
+    for (const group of groups) {
+      if (group.scopeKey === '_models') {
+        throw new Error(
+          `[ts-procedures-codegen] Scope "_models" conflicts with shared-models reserved filename "_models.ts". Rename the scope to avoid collision.`,
+        )
+      }
+    }
+  }
+
+  if (shareModels && models.length > 0) {
+    const generated = models.filter((m) => m.import == null)
+    if (strictSharedModels && generated.length > 0) {
+      const list = generated.map((m) => `"${m.id}" (${m.name})`).join(', ')
+      throw new Error(
+        `[ts-procedures-codegen] --strict-shared-models: ${generated.length} $id-bearing schema(s) have no shared-type mapping and would be generated as local structural twins: ${list}. Add a sharedTypesImport entry, set sharedModelsModule, or drop --strict-shared-models.`,
+      )
+    }
+    const reExported = models.length - generated.length
+    logger?.(
+      `[ts-procedures-codegen] Shared models: ${models.length} total — ${reExported} re-exported, ${generated.length} generated locally.`,
+    )
+  }
+
   const files: GeneratedFile[] = []
 
   for (const group of groups) {
@@ -60,6 +100,7 @@ export async function runTsPipeline(input: TsRunInput): Promise<GeneratedFile[]>
       namespaceTypes,
       serviceName,
       errorKeys: errorKeys.size > 0 ? errorKeys : undefined,
+      idToModelName,
     })
     const lines = rawCode.split('\n')
     lines.splice(1, 0, hashComment)
@@ -67,6 +108,15 @@ export async function runTsPipeline(input: TsRunInput): Promise<GeneratedFile[]>
     files.push({ path: join(outDir, `${group.scopeKey}.ts`), code })
   }
 
+  if (models.length > 0) {
+    const modelsCode = await emitModelsFile(models, { ajsc: ajscOpts })
+    if (modelsCode != null) {
+      const ml = modelsCode.split('\n')
+      ml.splice(1, 0, hashComment)
+      files.push({ path: join(outDir, '_models.ts'), code: ml.join('\n') })
+    }
+  }
+
   const errorsCode = await emitErrorsFile(envelope.errors, {
     ajsc: ajscOpts,
     clientImportPath,