ts-procedures 8.2.1 → 8.4.0

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,8 @@ export interface PipelineOptions {
   selfContained?: boolean
   serviceName?: string
   cleanOutDir?: boolean
+  shareModels?: boolean
+  sharedTypesImport?: SharedTypesImportMap
   target?: 'ts' | 'kotlin' | 'swift'
   kotlinPackage?: string
   kotlinSerializer?: 'kotlinx' | 'none'
@@ -43,7 +46,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 +70,8 @@ export async function runPipeline(options: PipelineOptions): Promise<GeneratedFi
     namespaceTypes,
     selfContained,
     cleanOutDir,
+    shareModels,
+    sharedTypesImport: options.sharedTypesImport,
   }
 
   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,8 @@ 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
 }

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,9 @@ export async function runTsPipeline(input: TsRunInput): Promise<GeneratedFile[]>
     namespaceTypes = false,
     selfContained = false,
     cleanOutDir = false,
+    sharedTypesImport,
   } = input
+  const shareModels = input.shareModels ?? false
 
   const hashComment = `// Source hash: ${hash}`
 
@@ -51,6 +55,25 @@ 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)
+    : []
+  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.`,
+        )
+      }
+    }
+  }
+
   const files: GeneratedFile[] = []
 
   for (const group of groups) {
@@ -60,6 +83,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 +91,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,

package/src/codegen/targets/ts/shared-models.test.ts

@@ -0,0 +1,283 @@
+import { describe, it, expect } from 'vitest'
+import { runPipeline } from '../../pipeline.js'
+import type { DocEnvelope } from '../../../implementations/types.js'
+import type { GeneratedFile } from '../_shared/write-files.js'
+import { makeApiRoute, makeEnvelope } from '../../__fixtures__/make-envelope.js'
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+/** A reusable `$id`-bearing schema — appears verbatim in multiple routes/scopes. */
+const messageModel = {
+  $id: 'urn:msg',
+  title: 'Message',
+  type: 'object',
+  properties: {
+    id: { type: 'string' },
+    body: { type: 'string' },
+  },
+  required: ['id', 'body'],
+} as const
+
+/**
+ * The same `urn:msg` model appears as a nested property in two scopes
+ * (`messages`, `threads`), and once as the WHOLE response body of a route
+ * (top-level `$id`).
+ */
+function modelEnvelope(): DocEnvelope {
+  return makeEnvelope([
+    makeApiRoute({
+      name: 'GetMessage',
+      scope: 'messages',
+      fullPath: '/messages/:id',
+      jsonSchema: {
+        req: {
+          pathParams: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+          },
+        },
+        // Whole response body IS the model (top-level $id) → `Response = Message`.
+        res: { body: { ...messageModel } },
+      },
+    }),
+    makeApiRoute({
+      name: 'ListMessages',
+      scope: 'messages',
+      fullPath: '/messages',
+      jsonSchema: {
+        res: {
+          body: {
+            type: 'object',
+            properties: {
+              // Model nested inside an array → referenced, not inlined.
+              items: { type: 'array', items: { ...messageModel } },
+            },
+            required: ['items'],
+          },
+        },
+      },
+    }),
+    makeApiRoute({
+      name: 'GetThread',
+      scope: 'threads',
+      fullPath: '/threads/:id',
+      jsonSchema: {
+        res: {
+          body: {
+            type: 'object',
+            properties: {
+              // Same model in a SECOND scope.
+              latest: { ...messageModel },
+            },
+            required: ['latest'],
+          },
+        },
+      },
+    }),
+  ])
+}
+
+/** Identical to {@link modelEnvelope} but with every `$id`/`title` stripped. */
+function noModelEnvelope(): DocEnvelope {
+  return makeEnvelope([
+    makeApiRoute({
+      name: 'GetMessage',
+      scope: 'messages',
+      fullPath: '/messages/:id',
+      jsonSchema: {
+        req: {
+          pathParams: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+          },
+        },
+        res: {
+          body: {
+            type: 'object',
+            properties: { id: { type: 'string' }, body: { type: 'string' } },
+            required: ['id', 'body'],
+          },
+        },
+      },
+    }),
+  ])
+}
+
+function findFile(files: GeneratedFile[], suffix: string): GeneratedFile | undefined {
+  return files.find((f) => f.path.endsWith(suffix))
+}
+
+const countMatches = (haystack: string, re: RegExp): number =>
+  (haystack.match(re) ?? []).length
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('shared models (TS target, ajsc x-named-type)', () => {
+  it('shareModels:true emits _models.ts with exactly one Message type; scopes reference it', async () => {
+    const files = await runPipeline({
+      envelope: modelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: true,
+      namespaceTypes: true,
+      selfContained: false,
+    })
+
+    const modelsFile = findFile(files, '_models.ts')
+    expect(modelsFile).toBeDefined()
+    expect(countMatches(modelsFile!.code, /export type Message =/g)).toBe(1)
+
+    // Both scopes that use the model import it and reference Message by name.
+    const messages = findFile(files, 'messages.ts')!
+    const threads = findFile(files, 'threads.ts')!
+    for (const scope of [messages, threads]) {
+      expect(scope.code).toContain("from './_models'")
+      expect(scope.code).toContain('Message')
+      // No inlined model object literal — the body shape lives only in _models.ts.
+      expect(scope.code).not.toMatch(/body:\s*string;[^}]*}\s*\)/)
+    }
+  })
+
+  it('a route whose entire response IS the model emits `Response = Message`', async () => {
+    const files = await runPipeline({
+      envelope: modelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: true,
+      namespaceTypes: true,
+    })
+    const messages = findFile(files, 'messages.ts')!
+    // GetMessage's response body IS the whole model (top-level $id) → the Body
+    // alias is exactly `Message`, the single token replacing the whole schema.
+    expect(messages.code).toMatch(/export type Body = Message\b/)
+    // And the nested-array case references the same model inside Array<…>.
+    expect(messages.code).toMatch(/Array<Message>/)
+  })
+
+  it('shareModels:false emits NO _models.ts and inlines as before', async () => {
+    const files = await runPipeline({
+      envelope: modelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: false,
+      namespaceTypes: true,
+    })
+    expect(findFile(files, '_models.ts')).toBeUndefined()
+    const messages = findFile(files, 'messages.ts')!
+    // The model is inlined: its properties appear in the scope, no _models import.
+    expect(messages.code).not.toContain("from './_models'")
+    expect(messages.code).toContain('body')
+  })
+
+  it('regression: a no-$id envelope produces byte-identical scope output for true vs false', async () => {
+    const on = await runPipeline({
+      envelope: noModelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: true,
+      namespaceTypes: true,
+    })
+    const off = await runPipeline({
+      envelope: noModelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: false,
+      namespaceTypes: true,
+    })
+
+    // No models exist, so neither run emits _models.ts.
+    expect(findFile(on, '_models.ts')).toBeUndefined()
+    expect(findFile(off, '_models.ts')).toBeUndefined()
+
+    const onScope = findFile(on, 'messages.ts')!
+    const offScope = findFile(off, 'messages.ts')!
+    expect(onScope.code).toBe(offScope.code)
+  })
+
+  it('sharedTypesImport re-exports the model and skips generating its body', async () => {
+    const files = await runPipeline({
+      envelope: modelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: true,
+      namespaceTypes: true,
+      sharedTypesImport: { 'urn:msg': { module: '@shared/schemas', name: 'Message' } },
+    })
+
+    const modelsFile = findFile(files, '_models.ts')!
+    expect(modelsFile.code).toContain("export { Message } from '@shared/schemas'")
+    // No generated body when the model is externally imported.
+    expect(modelsFile.code).not.toMatch(/export type Message =/)
+
+    // Scopes still import Message from ./_models (the single hub).
+    const messages = findFile(files, 'messages.ts')!
+    expect(messages.code).toContain("from './_models'")
+    expect(messages.code).toContain('Message')
+  })
+
+  it('flat mode (namespaceTypes:false) imports Message from ./_models', async () => {
+    const files = await runPipeline({
+      envelope: modelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: true,
+      namespaceTypes: false,
+    })
+    const messages = findFile(files, 'messages.ts')!
+    expect(messages.code).toContain("import type { Message } from './_models'")
+  })
+
+  it('fails loudly when a shared model name collides with a property-derived sub-type', async () => {
+    // `latest` references the Message model; a sibling property literally named
+    // `message` would make ajsc extract a structural sub-type ALSO named
+    // `Message`. ajsc silently merges the two (the model reference resolves to
+    // the unrelated structural type), so codegen must reject this rather than
+    // emit a silently-wrong type. See assertNoModelNameCollision in emit-scope.
+    const collision = makeEnvelope([
+      makeApiRoute({
+        name: 'GetThread',
+        scope: 'chat',
+        fullPath: '/thread',
+        jsonSchema: {
+          res: {
+            body: {
+              type: 'object',
+              required: ['latest', 'message'],
+              properties: {
+                latest: {
+                  type: 'object',
+                  $id: 'urn:msg',
+                  title: 'Message',
+                  required: ['id'],
+                  properties: { id: { type: 'string' } },
+                },
+                message: {
+                  type: 'object',
+                  required: ['unread'],
+                  properties: { unread: { type: 'boolean' } },
+                },
+              },
+            },
+          },
+        },
+      }),
+    ])
+
+    await expect(
+      runPipeline({
+        envelope: collision,
+        outDir: 'out',
+        dryRun: true,
+        shareModels: true,
+        namespaceTypes: true,
+        selfContained: false,
+      }),
+    ).rejects.toThrow(/shared model 'Message' collides/)
+  })
+})

package/src/doc-envelope.test.ts

@@ -0,0 +1,35 @@
+import { describe, it, expect, afterEach } from 'vitest'
+import { readFile, rm, mkdtemp } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { writeDocEnvelope } from './doc-envelope.js'
+import type { DocEnvelope } from './implementations/types.js'
+
+const envelope: DocEnvelope = { basePath: '', headers: [], errors: [], routes: [] }
+
+describe('writeDocEnvelope', () => {
+  let dir: string
+  afterEach(async () => { if (dir) await rm(dir, { recursive: true, force: true }) })
+
+  it('writes a plain DocEnvelope as pretty JSON', async () => {
+    dir = await mkdtemp(join(tmpdir(), 'tsp-'))
+    const out = join(dir, 'nested', 'docs.json')
+    await writeDocEnvelope(envelope, out)
+    const parsed = JSON.parse(await readFile(out, 'utf8'))
+    expect(parsed).toEqual(envelope)
+  })
+
+  it('accepts a builder-like object with toDocEnvelope()', async () => {
+    dir = await mkdtemp(join(tmpdir(), 'tsp-'))
+    const out = join(dir, 'docs.json')
+    await writeDocEnvelope({ toDocEnvelope: () => envelope }, out)
+    expect(JSON.parse(await readFile(out, 'utf8'))).toEqual(envelope)
+  })
+
+  it('accepts a DocRegistry-like object (toJSON)', async () => {
+    dir = await mkdtemp(join(tmpdir(), 'tsp-'))
+    const out = join(dir, 'docs.json')
+    await writeDocEnvelope({ toJSON: () => envelope }, out)
+    expect(JSON.parse(await readFile(out, 'utf8'))).toEqual(envelope)
+  })
+})

package/src/doc-envelope.ts

@@ -0,0 +1,30 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import type { DocEnvelope } from './implementations/types.js'
+
+export type DocEnvelopeSource =
+  | DocEnvelope
+  | { toDocEnvelope(): DocEnvelope }
+  | { toJSON(): DocEnvelope }
+
+function coerceToEnvelope(source: DocEnvelopeSource): DocEnvelope {
+  if (typeof (source as { toDocEnvelope?: unknown }).toDocEnvelope === 'function') {
+    return (source as { toDocEnvelope(): DocEnvelope }).toDocEnvelope()
+  }
+  if (typeof (source as { toJSON?: unknown }).toJSON === 'function') {
+    return (source as { toJSON(): DocEnvelope }).toJSON()
+  }
+  return source as DocEnvelope
+}
+
+/**
+ * Serializes a doc envelope to disk as pretty JSON so codegen can run offline
+ * via `--file <path>` without a running server. Accepts a plain `DocEnvelope`,
+ * a builder exposing `toDocEnvelope()`, or a `DocRegistry` exposing `toJSON()`.
+ * Parent directories are created as needed.
+ */
+export async function writeDocEnvelope(source: DocEnvelopeSource, path: string): Promise<void> {
+  const envelope = coerceToEnvelope(source)
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, JSON.stringify(envelope, null, 2), 'utf8')
+}

package/src/exports.ts

@@ -7,3 +7,5 @@ export * from './schema/resolve-schema-lib.js'
 export * from './schema/types.js'
 export type { HttpReturn } from './create-http.js'
 export type { TCreateHttpConfig } from './types.js'
+export { writeDocEnvelope, type DocEnvelopeSource } from './doc-envelope.js'
+export type { DocEnvelope } from './implementations/types.js'