ts-procedures 6.0.2 → 6.2.0

package/src/codegen/targets/_shared/pick-defined.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, it } from 'vitest'
+import { pickDefined } from './pick-defined.js'
+
+describe('pickDefined', () => {
+  it('returns only the keys whose values are not undefined', () => {
+    expect(
+      pickDefined(
+        { a: 1, b: undefined, c: 3 } as { a?: number; b?: number; c?: number },
+        ['a', 'b', 'c'],
+      ),
+    ).toEqual({ a: 1, c: 3 })
+  })
+
+  it('preserves the literal `false` value for boolean opts', () => {
+    expect(
+      pickDefined(
+        { depluralize: false, x: undefined } as { depluralize?: boolean; x?: number },
+        ['depluralize', 'x'],
+      ),
+    ).toEqual({ depluralize: false })
+  })
+
+  it('preserves the literal `false` for `string | false` opts (e.g. arrayItemNaming)', () => {
+    type Opts = { arrayItemNaming?: string | false }
+    const result = pickDefined<Opts, keyof Opts>({ arrayItemNaming: false }, ['arrayItemNaming'])
+    expect(result).toEqual({ arrayItemNaming: false })
+    expect('arrayItemNaming' in result).toBe(true)
+  })
+
+  it('omits keys not in the keys list even if they are defined on src', () => {
+    expect(
+      pickDefined({ a: 1, b: 2 } as { a?: number; b?: number }, ['a']),
+    ).toEqual({ a: 1 })
+  })
+
+  it('returns an empty object when all keys are undefined', () => {
+    expect(
+      pickDefined(
+        { a: undefined, b: undefined } as { a?: number; b?: number },
+        ['a', 'b'],
+      ),
+    ).toEqual({})
+  })
+
+  it('returns an empty object when keys is empty', () => {
+    expect(pickDefined({ a: 1 }, [] as never[])).toEqual({})
+  })
+})

package/src/codegen/targets/_shared/pick-defined.ts

@@ -0,0 +1,23 @@
+/**
+ * Returns a new object containing only the keys of `src` whose values are
+ * not `undefined`. Useful for building option objects where unset keys must
+ * be ABSENT (not `undefined`-valued), so they don't shadow downstream
+ * defaults — e.g., when forwarding into a target's `Emit*Options`.
+ *
+ * @example
+ *   pickDefined({ a: 1, b: undefined, c: false }, ['a', 'b', 'c'])
+ *   // → { a: 1, c: false }
+ */
+export function pickDefined<T extends object, K extends keyof T>(
+  src: T,
+  keys: readonly K[],
+): Partial<Pick<T, K>> {
+  const out: Partial<Pick<T, K>> = {}
+  for (const key of keys) {
+    const value = src[key]
+    if (value !== undefined) {
+      out[key] = value
+    }
+  }
+  return out
+}

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

@@ -0,0 +1,55 @@
+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)
+
+describe('extractRouteSlots', () => {
+  it('returns no slots when schema is undefined', () => {
+    expect(extractRouteSlots(r(undefined))).toEqual([])
+  })
+
+  it('returns no slots when schema is empty', () => {
+    expect(extractRouteSlots(r({}))).toEqual([])
+  })
+
+  it('returns the deterministic slot order: PathParams, Query, Body, Response', () => {
+    const slots = extractRouteSlots(
+      r({
+        input: {
+          body: { type: 'object', x: 'body' },
+          query: { type: 'object', x: 'query' },
+          pathParams: { type: 'object', x: 'path' },
+        },
+        returnType: { type: 'object', x: 'response' },
+      }),
+    )
+    expect(slots.map((s) => s.rootName)).toEqual(['PathParams', 'Query', 'Body', 'Response'])
+  })
+
+  it('omits slots whose source is null or undefined', () => {
+    const slots = extractRouteSlots(
+      r({
+        input: { pathParams: { type: 'object' }, query: null, body: undefined },
+        // returnType missing
+      }),
+    )
+    expect(slots.map((s) => s.rootName)).toEqual(['PathParams'])
+  })
+
+  it('attaches the source schema verbatim to each slot', () => {
+    const path = { type: 'object', tag: 'p' }
+    const ret = { type: 'object', tag: 'r' }
+    const slots = extractRouteSlots(r({ input: { pathParams: path }, returnType: ret }))
+    expect(slots).toEqual([
+      { rootName: 'PathParams', source: path },
+      { rootName: 'Response', source: ret },
+    ])
+  })
+
+  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([])
+  })
+})

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

@@ -0,0 +1,32 @@
+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.
+ */
+export interface RouteSlot {
+  /** Stable identifier used as the emitted type's `rootTypeName`. */
+  rootName: string
+  /** The raw JSON Schema source for this slot, or `null`/`undefined` when absent. */
+  source: unknown
+}
+
+/**
+ * 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.
+ */
+export function extractRouteSlots(route: AnyHttpRouteDoc): RouteSlot[] {
+  const schema = (route as { schema?: Record<string, unknown> }).schema ?? {}
+  const input = (schema.input ?? {}) as Record<string, unknown>
+
+  // 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 },
+  ]
+
+  return slots.filter((s) => s.source != null)
+}

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

@@ -0,0 +1,28 @@
+import type { DocEnvelope } from '../../../implementations/types.js'
+import type { ScopeGroup } from '../../group-routes.js'
+import type { AjscOptions } from '../../emit-types.js'
+
+/**
+ * Inputs the dispatcher prepares once and forwards to every per-target
+ * `run*Pipeline` module. Each target module reads only the fields it needs.
+ *
+ * The fields here are deliberately narrow: target-specific knobs (e.g.
+ * `kotlinPackage`, `swiftSerializer`) are passed as additional options on
+ * each per-target input shape, not on this base.
+ */
+export interface TargetRunInput {
+  envelope: DocEnvelope
+  outDir: string
+  /** MD5 hash of the envelope JSON, prefix-stamped into every emitted file. */
+  hash: string
+  /** Pre-grouped routes (one entry per scope key). */
+  groups: ScopeGroup[]
+  /** Validated service name (defaults to `Api` upstream). */
+  serviceName: string
+  ajsc?: AjscOptions
+  clientImportPath?: string
+  dryRun?: boolean
+  namespaceTypes?: boolean
+  selfContained?: boolean
+  cleanOutDir?: boolean
+}

package/src/codegen/targets/_shared/write-files.test.ts

@@ -0,0 +1,110 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { mkdir, readFile, rm, writeFile, stat, mkdtemp } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { writeGeneratedFiles } from './write-files.js'
+
+describe('writeGeneratedFiles', () => {
+  describe('dryRun mode', () => {
+    let logSpy: ReturnType<typeof vi.spyOn>
+
+    beforeEach(() => {
+      logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+    })
+
+    afterEach(() => {
+      logSpy.mockRestore()
+    })
+
+    it('logs each file with its byte length and does not touch the filesystem', async () => {
+      const dir = '/nonexistent/should-not-be-created'
+      await writeGeneratedFiles(
+        [
+          { path: `${dir}/a.txt`, code: 'hello' },
+          { path: `${dir}/b.txt`, code: 'hi' },
+        ],
+        dir,
+        { dryRun: true },
+      )
+      expect(logSpy).toHaveBeenCalledWith(`[dry-run] Would write: ${dir}/a.txt (5 bytes)`)
+      expect(logSpy).toHaveBeenCalledWith(`[dry-run] Would write: ${dir}/b.txt (2 bytes)`)
+      // Sanity: the dir was not created.
+      await expect(stat(dir)).rejects.toBeInstanceOf(Error)
+    })
+
+    it('logs a clean-outDir notice when cleanOutDir is true', async () => {
+      await writeGeneratedFiles([], '/out', { dryRun: true, cleanOutDir: true })
+      expect(logSpy).toHaveBeenCalledWith('[dry-run] Would clean outDir: /out')
+    })
+
+    it('does not log clean-outDir when cleanOutDir is false', async () => {
+      await writeGeneratedFiles([{ path: '/out/x', code: 'x' }], '/out', { dryRun: true })
+      const messages = logSpy.mock.calls.map((c: unknown[]) => c[0])
+      expect(messages.find((m: unknown) => String(m).includes('Would clean'))).toBeUndefined()
+    })
+
+    it('counts bytes as utf-8', async () => {
+      // "é" is 2 bytes in utf-8.
+      await writeGeneratedFiles([{ path: '/x/e.txt', code: 'é' }], '/x', { dryRun: true })
+      expect(logSpy).toHaveBeenCalledWith('[dry-run] Would write: /x/e.txt (2 bytes)')
+    })
+  })
+
+  describe('real write mode', () => {
+    let outDir: string
+
+    beforeEach(async () => {
+      outDir = await mkdtemp(join(tmpdir(), 'write-files-test-'))
+    })
+
+    afterEach(async () => {
+      await rm(outDir, { recursive: true, force: true })
+    })
+
+    it('writes each file with utf-8 contents', async () => {
+      await writeGeneratedFiles(
+        [
+          { path: join(outDir, 'a.txt'), code: 'alpha' },
+          { path: join(outDir, 'b.txt'), code: 'beta' },
+        ],
+        outDir,
+      )
+      expect(await readFile(join(outDir, 'a.txt'), 'utf-8')).toBe('alpha')
+      expect(await readFile(join(outDir, 'b.txt'), 'utf-8')).toBe('beta')
+    })
+
+    it('creates outDir recursively if missing', async () => {
+      const nested = join(outDir, 'a', 'b', 'c')
+      await writeGeneratedFiles([{ path: join(nested, 'x.txt'), code: 'x' }], nested)
+      expect(await readFile(join(nested, 'x.txt'), 'utf-8')).toBe('x')
+    })
+
+    it('removes outDir when cleanOutDir is true before writing', async () => {
+      // Pre-populate a stale file.
+      await mkdir(outDir, { recursive: true })
+      await writeFile(join(outDir, 'stale.txt'), 'stale', 'utf-8')
+
+      await writeGeneratedFiles(
+        [{ path: join(outDir, 'fresh.txt'), code: 'fresh' }],
+        outDir,
+        { cleanOutDir: true },
+      )
+
+      await expect(readFile(join(outDir, 'stale.txt'), 'utf-8')).rejects.toBeInstanceOf(Error)
+      expect(await readFile(join(outDir, 'fresh.txt'), 'utf-8')).toBe('fresh')
+    })
+
+    it('does not remove outDir when cleanOutDir is false', async () => {
+      await mkdir(outDir, { recursive: true })
+      await writeFile(join(outDir, 'keep.txt'), 'keep', 'utf-8')
+
+      await writeGeneratedFiles(
+        [{ path: join(outDir, 'new.txt'), code: 'new' }],
+        outDir,
+      )
+
+      expect(await readFile(join(outDir, 'keep.txt'), 'utf-8')).toBe('keep')
+      expect(await readFile(join(outDir, 'new.txt'), 'utf-8')).toBe('new')
+    })
+  })
+})

package/src/codegen/targets/_shared/write-files.ts

@@ -0,0 +1,53 @@
+import { mkdir, rm, writeFile } from 'node:fs/promises'
+
+export interface GeneratedFile {
+  path: string
+  code: string
+}
+
+export interface WriteOptions {
+  /** When true, log what would happen instead of touching the filesystem. */
+  dryRun?: boolean
+  /** When true, recursively delete `outDir` before writing. */
+  cleanOutDir?: boolean
+}
+
+/**
+ * Persists the generated files to disk (or simulates the writes under
+ * `dryRun`). Centralises the dryRun / cleanOutDir / mkdir / writeFile
+ * sequence shared by every codegen target so per-target run modules don't
+ * duplicate it.
+ *
+ * Behaviour:
+ * - `dryRun: true` — logs `[dry-run] Would write: <path> (<bytes> bytes)` per
+ *   file, plus a leading `[dry-run] Would clean outDir: <outDir>` when
+ *   `cleanOutDir: true`. No filesystem mutation.
+ * - `dryRun: false` (default) — when `cleanOutDir`, recursively removes
+ *   `outDir`; then ensures it exists; then writes each file as utf-8.
+ */
+export async function writeGeneratedFiles(
+  files: readonly GeneratedFile[],
+  outDir: string,
+  opts: WriteOptions = {},
+): Promise<void> {
+  const { dryRun = false, cleanOutDir = false } = opts
+
+  if (dryRun) {
+    if (cleanOutDir) {
+      console.log(`[dry-run] Would clean outDir: ${outDir}`)
+    }
+    for (const f of files) {
+      const bytes = Buffer.byteLength(f.code, 'utf-8')
+      console.log(`[dry-run] Would write: ${f.path} (${bytes} bytes)`)
+    }
+    return
+  }
+
+  if (cleanOutDir) {
+    await rm(outDir, { recursive: true, force: true })
+  }
+  await mkdir(outDir, { recursive: true })
+  for (const f of files) {
+    await writeFile(f.path, f.code, 'utf-8')
+  }
+}

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

@@ -0,0 +1,121 @@
+package com.example.api
+
+// Source hash: <PLACEHOLDER>
+
+import kotlinx.serialization.Contextual
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.json.JsonClassDiscriminator
+
+object Users {
+    object GetUser {
+        const val method = "GET"
+        const val pathTemplate = "/users/{id}"
+        fun path(p: PathParams): String = "/users/${p.id}"
+
+        @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,
+            )
+        }
+
+        object Errors {
+            @Serializable
+            data class NotFound(
+                val name: String = "NotFound",
+                val message: String,
+            )
+        }
+    }
+
+    object CreateUser {
+        const val method = "POST"
+        const val pathTemplate = "/users"
+        const val path = "/users"
+
+        @Serializable
+        @JsonClassDiscriminator("kind")
+        sealed interface Body {
+            @Serializable
+            @SerialName("guest")
+            data class GuestBody(
+                val displayName: String,
+            ) : Body
+
+            @Serializable
+            @SerialName("registered")
+            data class RegisteredBody(
+                val email: String,
+                val name: String,
+            ) : Body
+        }
+
+        @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,
+            )
+        }
+
+        object Errors {
+            @Serializable
+            data class ValidationError(
+                val name: String = "ValidationError",
+                val message: String,
+                val field: String? = null,
+            )
+        }
+    }
+
+    object ListUsers {
+        const val method = "GET"
+        const val pathTemplate = "/users"
+        const val path = "/users"
+
+        @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 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,
+            )
+        }
+    }
+}

package/src/codegen/targets/kotlin/__snapshots__/probe-unsupported-unions.test.ts.snap

@@ -0,0 +1,27 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`ajsc.emitKotlin — untagged oneOf behavior > produces a deterministic fallback shape for an untagged oneOf 1`] = `
+{
+  "code": "@Serializable
+data class Mixed()
+",
+  "extractedTypeNames": [],
+  "imports": [
+    "kotlinx.serialization.Serializable",
+  ],
+  "rootTypeName": "Mixed",
+}
+`;
+
+exports[`ajsc.emitKotlin — untagged oneOf behavior > silently falls back to empty data class when unsupportedUnions is not specified 1`] = `
+{
+  "code": "@Serializable
+data class Mixed()
+",
+  "extractedTypeNames": [],
+  "imports": [
+    "kotlinx.serialization.Serializable",
+  ],
+  "rootTypeName": "Mixed",
+}
+`;

package/src/codegen/targets/kotlin/ajsc-adapter.test.ts

@@ -0,0 +1,47 @@
+import { describe, expect, it } from 'vitest'
+import { createStubKotlinEmitter, resolveProductionKotlinEmitter, type KotlinEmitResult } from './ajsc-adapter.js'
+
+describe('createStubKotlinEmitter', () => {
+  it('returns the configured EmitResult for the matching root name', () => {
+    const expected: KotlinEmitResult = {
+      code: '@Serializable data class User(val id: String)',
+      rootTypeName: 'User',
+      extractedTypeNames: [],
+      imports: ['kotlinx.serialization.Serializable'],
+    }
+    const emitter = createStubKotlinEmitter({ User: expected })
+    expect(
+      emitter.emit(
+        { type: 'object' },
+        {
+          rootTypeName: 'User',
+          inlineTypes: true,
+          serializer: 'kotlinx',
+          unsupportedUnions: 'throw',
+        },
+      ),
+    ).toEqual(expected)
+  })
+
+  it('throws when asked to emit a name not in the stub map', () => {
+    const emitter = createStubKotlinEmitter({})
+    expect(() => emitter.emit({}, { rootTypeName: 'Missing' })).toThrow(/Missing/)
+  })
+})
+
+describe('resolveProductionKotlinEmitter', () => {
+  it('returns a working emitter that invokes ajsc.emitKotlin when ajsc is installed', async () => {
+    const emitter = await resolveProductionKotlinEmitter()
+    const result = emitter.emit(
+      { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+      { rootTypeName: 'Probe' },
+    )
+    expect(typeof result.code).toBe('string')
+    expect(result.code.length).toBeGreaterThan(0)
+    expect(result.rootTypeName).toBe('Probe')
+    expect(Array.isArray(result.imports)).toBe(true)
+  })
+  // Note: testing the failure path (ajsc unavailable) requires module mocking;
+  // we leave that as a manual-verification path. The error message is pinned
+  // by the message text below so any change requires updating both call sites.
+})

package/src/codegen/targets/kotlin/ajsc-adapter.ts

@@ -0,0 +1,66 @@
+export interface KotlinEmitResult {
+  code: string
+  rootTypeName: string
+  extractedTypeNames: string[]
+  imports: string[]
+}
+
+export interface KotlinEmitOptions {
+  rootTypeName: string
+  /** Always set true at our call sites; v7.2 default is false. */
+  inlineTypes?: boolean
+  serializer?: 'kotlinx' | 'none'
+  unsupportedUnions?: 'throw' | 'fallback'
+  arrayItemNaming?: string | false
+  depluralize?: boolean
+  uncountableWords?: string[]
+}
+
+export interface KotlinEmitter {
+  emit(schema: Record<string, unknown>, opts: KotlinEmitOptions): KotlinEmitResult
+}
+
+export function createStubKotlinEmitter(
+  results: Record<string, KotlinEmitResult>,
+): KotlinEmitter {
+  return {
+    emit(_schema, opts) {
+      const result = results[opts.rootTypeName]
+      if (result == null) {
+        throw new Error(
+          `[stub-kotlin-emitter] No stubbed result for rootTypeName "${opts.rootTypeName}". ` +
+            `Provide one in the results map.`,
+        )
+      }
+      return result
+    },
+  }
+}
+
+/**
+ * Resolves the production Kotlin emitter from `ajsc`. Throws a clear error
+ * if ajsc is not installed or does not expose `emitKotlin` (e.g. consumer
+ * ran `npm install --omit=optional` since ajsc is in optionalDependencies).
+ */
+export async function resolveProductionKotlinEmitter(): Promise<KotlinEmitter> {
+  let ajsc: { emitKotlin?: unknown } | null = null
+  let importError: unknown
+  try {
+    ajsc = (await import('ajsc')) as { emitKotlin?: unknown }
+  } catch (err) {
+    importError = err
+  }
+  const emitKotlin = ajsc?.emitKotlin
+  if (typeof emitKotlin !== 'function') {
+    throw new Error(
+      '[ts-procedures-codegen] ajsc.emitKotlin is not available. ' +
+      'Install ajsc (`npm install ajsc`) — it is an optional dependency.',
+      importError !== undefined ? { cause: importError } : undefined,
+    )
+  }
+  return {
+    emit(schema, opts) {
+      return (emitKotlin as (s: unknown, o: unknown) => KotlinEmitResult)(schema, opts)
+    },
+  }
+}