ts-procedures 5.9.1 → 5.10.2

package/src/codegen/pipeline.test.ts

@@ -0,0 +1,316 @@
+import { describe, it, expect, afterEach, vi } from 'vitest'
+import { generateClient } from './index.js'
+import { runPipeline } from './pipeline.js'
+import { mkdirSync, rmSync, readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import type { DocEnvelope } from '../implementations/types.js'
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const envelope: DocEnvelope = {
+  basePath: '/api',
+  headers: [],
+  errors: [],
+  routes: [
+    {
+      kind: 'rpc',
+      name: 'GetUser',
+      path: '/users/1',
+      method: 'post',
+      scope: 'users',
+      version: 1,
+      jsonSchema: {
+        body: {
+          type: 'object',
+          properties: { id: { type: 'string' } },
+          required: ['id'],
+        },
+        response: {
+          type: 'object',
+          properties: { name: { type: 'string' } },
+          required: ['name'],
+        },
+      },
+    },
+    {
+      kind: 'rpc',
+      name: 'CreateInvoice',
+      path: '/billing/1',
+      method: 'post',
+      scope: 'billing',
+      version: 1,
+      jsonSchema: {
+        body: {
+          type: 'object',
+          properties: { amount: { type: 'number' } },
+          required: ['amount'],
+        },
+        response: {
+          type: 'object',
+          properties: { invoiceId: { type: 'string' } },
+          required: ['invoiceId'],
+        },
+      },
+    },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeTmpDir(): string {
+  const dir = join(tmpdir(), `ts-proc-pipeline-test-${Date.now()}-${Math.random().toString(36).slice(2)}`)
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('generateClient pipeline', () => {
+  let tmpDir: string
+
+  afterEach(() => {
+    if (tmpDir && existsSync(tmpDir)) {
+      rmSync(tmpDir, { recursive: true, force: true })
+    }
+  })
+
+  it('creates scope file for each unique scope (users.ts, billing.ts)', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    expect(existsSync(join(tmpDir, 'users.ts'))).toBe(true)
+    expect(existsSync(join(tmpDir, 'billing.ts'))).toBe(true)
+  })
+
+  it('creates index.ts', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    expect(existsSync(join(tmpDir, 'index.ts'))).toBe(true)
+  })
+
+  it('users.ts contains bindUsersScope function', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'users.ts'), 'utf-8')
+    expect(content).toContain('bindUsersScope')
+    expect(content).toContain('GetUser')
+  })
+
+  it('billing.ts contains bindBillingScope function', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'billing.ts'), 'utf-8')
+    expect(content).toContain('bindBillingScope')
+    expect(content).toContain('CreateInvoice')
+  })
+
+  it('index.ts exports from both scope files and has createScopeBindings', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'index.ts'), 'utf-8')
+    expect(content).toContain("from './users'")
+    expect(content).toContain("from './billing'")
+    expect(content).toContain('createScopeBindings')
+  })
+
+  it('creates outDir if it does not exist', async () => {
+    tmpDir = makeTmpDir()
+    const nested = join(tmpDir, 'nested', 'output')
+    await generateClient({ envelope, outDir: nested })
+
+    expect(existsSync(join(nested, 'index.ts'))).toBe(true)
+  })
+
+  it('all generated files have the auto-generated header comment', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    for (const file of ['users.ts', 'billing.ts', 'index.ts']) {
+      const content = readFileSync(join(tmpDir, file), 'utf-8')
+      expect(content).toContain('// Auto-generated by ts-procedures-codegen — do not edit')
+    }
+  })
+
+  it('generated files include source hash comment', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    for (const file of ['users.ts', 'billing.ts', 'index.ts']) {
+      const content = readFileSync(join(tmpDir, file), 'utf-8')
+      const lines = content.split('\n')
+      expect(lines[1]).toMatch(/^\/\/ Source hash: [a-f0-9]{32}$/)
+    }
+  })
+
+  it('dry-run mode does not create files on disk', async () => {
+    tmpDir = makeTmpDir()
+    const dryDir = join(tmpDir, 'dry-output')
+    await runPipeline({ envelope, outDir: dryDir, dryRun: true })
+    expect(existsSync(dryDir)).toBe(false)
+  })
+
+  it('dry-run mode returns generated file entries', async () => {
+    tmpDir = makeTmpDir()
+    const dryDir = join(tmpDir, 'dry-output')
+    const files = await runPipeline({ envelope, outDir: dryDir, dryRun: true })
+    expect(files.length).toBe(3) // users.ts, billing.ts, index.ts
+    const paths = files.map((f) => f.path)
+    expect(paths).toContain(join(dryDir, 'users.ts'))
+    expect(paths).toContain(join(dryDir, 'billing.ts'))
+    expect(paths).toContain(join(dryDir, 'index.ts'))
+    for (const file of files) {
+      expect(file.code).toContain('// Auto-generated by ts-procedures-codegen — do not edit')
+    }
+  })
+
+  it('selfContained: true produces _types.ts and _client.ts', async () => {
+    tmpDir = makeTmpDir()
+    const files = await runPipeline({ envelope, outDir: tmpDir, selfContained: true })
+    const paths = files.map((f) => f.path)
+    expect(paths).toContain(join(tmpDir, '_types.ts'))
+    expect(paths).toContain(join(tmpDir, '_client.ts'))
+
+    // Verify both files have auto-generated header and source hash
+    const typesFile = files.find((f) => f.path.endsWith('_types.ts'))!
+    const clientFile = files.find((f) => f.path.endsWith('_client.ts'))!
+    expect(typesFile.code).toContain('// Auto-generated by ts-procedures-codegen — do not edit')
+    expect(clientFile.code).toContain('// Auto-generated by ts-procedures-codegen — do not edit')
+    const typesLines = typesFile.code.split('\n')
+    expect(typesLines[1]).toMatch(/^\/\/ Source hash: [a-f0-9]{32}$/)
+    const clientLines = clientFile.code.split('\n')
+    expect(clientLines[1]).toMatch(/^\/\/ Source hash: [a-f0-9]{32}$/)
+  })
+
+  it('selfContained: true makes scope files import from ./_types', async () => {
+    tmpDir = makeTmpDir()
+    const files = await runPipeline({ envelope, outDir: tmpDir, selfContained: true })
+    const scopeFiles = files.filter((f) => !f.path.endsWith('index.ts') && !f.path.startsWith(join(tmpDir, '_')))
+    expect(scopeFiles.length).toBeGreaterThan(0)
+    for (const file of scopeFiles) {
+      expect(file.code).toContain("from './_types'")
+      expect(file.code).not.toContain("from 'ts-procedures/client'")
+    }
+  })
+
+  it('selfContained + clientImportPath emits a console.warn', async () => {
+    tmpDir = makeTmpDir()
+    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
+    try {
+      await runPipeline({ envelope, outDir: tmpDir, selfContained: true, clientImportPath: './my-client' })
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[ts-procedures-codegen] --self-contained overrides --client-import-path; using ./_types'
+      )
+    } finally {
+      warnSpy.mockRestore()
+    }
+  })
+
+  it('serviceName + namespaceTypes produces prefixed error namespace in _errors.ts', async () => {
+    tmpDir = makeTmpDir()
+    const envelopeWithErrors: DocEnvelope = {
+      ...envelope,
+      errors: [
+        {
+          name: 'ProcedureError',
+          statusCode: 500,
+          description: 'Handler error',
+          schema: {
+            type: 'object',
+            properties: { name: { type: 'string' }, message: { type: 'string' } },
+            required: ['name', 'message'],
+          },
+        },
+      ],
+    }
+    await generateClient({ envelope: envelopeWithErrors, outDir: tmpDir, serviceName: 'Auth', namespaceTypes: true })
+
+    const errorsContent = readFileSync(join(tmpDir, '_errors.ts'), 'utf-8')
+    expect(errorsContent).toContain('export namespace AuthErrors {')
+    expect(errorsContent).not.toContain('export namespace Errors {')
+    expect(errorsContent).toContain('AuthProcedureErrorUnion')
+  })
+
+  it('serviceName prefixes ProcedureErrorUnion in flat mode _errors.ts', async () => {
+    tmpDir = makeTmpDir()
+    const envelopeWithErrors: DocEnvelope = {
+      ...envelope,
+      errors: [
+        {
+          name: 'ProcedureError',
+          statusCode: 500,
+          description: 'Handler error',
+          schema: {
+            type: 'object',
+            properties: { name: { type: 'string' }, message: { type: 'string' } },
+            required: ['name', 'message'],
+          },
+        },
+      ],
+    }
+    await generateClient({ envelope: envelopeWithErrors, outDir: tmpDir, serviceName: 'Auth' })
+
+    const errorsContent = readFileSync(join(tmpDir, '_errors.ts'), 'utf-8')
+    expect(errorsContent).toContain('export type AuthProcedureErrorUnion =')
+    expect(errorsContent).not.toContain('export type ProcedureErrorUnion =')
+  })
+
+  it('rejects invalid serviceName', async () => {
+    tmpDir = makeTmpDir()
+    await expect(
+      generateClient({ envelope, outDir: tmpDir, serviceName: '---' })
+    ).rejects.toThrow('empty')
+  })
+
+  it('rejects serviceName starting with a digit', async () => {
+    tmpDir = makeTmpDir()
+    await expect(
+      generateClient({ envelope, outDir: tmpDir, serviceName: '123svc' })
+    ).rejects.toThrow('starts with a digit')
+  })
+
+  it('serviceName generates custom factory function name in index.ts', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir, serviceName: 'Auth' })
+
+    const content = readFileSync(join(tmpDir, 'index.ts'), 'utf-8')
+    expect(content).toContain('createAuthBindings')
+    expect(content).not.toContain('createScopeBindings')
+  })
+
+  it('throws when a scope key collides with _types in selfContained mode', async () => {
+    tmpDir = makeTmpDir()
+    const collisionEnvelope: DocEnvelope = {
+      ...envelope,
+      routes: [
+        {
+          kind: 'rpc',
+          name: 'GetUser',
+          path: '/users/1',
+          method: 'post',
+          scope: '_types',
+          version: 1,
+          jsonSchema: {
+            body: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+            response: { type: 'object', properties: { name: { type: 'string' } }, required: ['name'] },
+          },
+        },
+      ],
+    }
+    await expect(
+      runPipeline({ envelope: collisionEnvelope, outDir: tmpDir, selfContained: true })
+    ).rejects.toThrow(
+      '[ts-procedures-codegen] Scope "_types" conflicts with self-contained mode reserved filename "_types.ts". Rename the scope to avoid collision.'
+    )
+  })
+})

package/src/codegen/pipeline.ts

@@ -0,0 +1,108 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+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 { emitScopeFile } from './emit-scope.js'
+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 { validateServiceName } from './naming.js'
+
+export interface PipelineOptions {
+  envelope: DocEnvelope
+  outDir: string
+  ajsc?: AjscOptions
+  clientImportPath?: string
+  dryRun?: boolean
+  namespaceTypes?: boolean
+  selfContained?: boolean
+  serviceName?: string
+}
+
+export interface GeneratedFile {
+  path: string
+  code: string
+}
+
+export async function runPipeline(options: PipelineOptions): Promise<GeneratedFile[]> {
+  const { envelope, outDir, ajsc: ajscOpts, dryRun = false, namespaceTypes = false, selfContained = false, serviceName } = options
+  if (serviceName != null) {
+    validateServiceName(serviceName)
+  }
+  const clientImportPath = selfContained ? './_types' : options.clientImportPath
+  if (selfContained && options.clientImportPath != null) {
+    console.warn('[ts-procedures-codegen] --self-contained overrides --client-import-path; using ./_types')
+  }
+
+  const hash = createHash('md5').update(JSON.stringify(envelope)).digest('hex')
+  const hashComment = `// Source hash: ${hash}`
+
+  const groups = groupRoutesByScope(envelope.routes)
+  const groupArray = Array.from(groups.values())
+
+  if (selfContained) {
+    for (const group of groupArray) {
+      if (group.scopeKey === '_types' || group.scopeKey === '_client') {
+        throw new Error(
+          `[ts-procedures-codegen] Scope "${group.scopeKey}" conflicts with self-contained mode reserved filename "${group.scopeKey}.ts". Rename the scope to avoid collision.`
+        )
+      }
+    }
+  }
+
+  const files: GeneratedFile[] = []
+
+  for (const group of groupArray) {
+    const rawCode = await emitScopeFile(group, { ajsc: ajscOpts, clientImportPath, namespaceTypes })
+    const lines = rawCode.split('\n')
+    lines.splice(1, 0, hashComment)
+    const code = lines.join('\n')
+    files.push({ path: join(outDir, `${group.scopeKey}.ts`), code })
+  }
+
+  const errorsCode = await emitErrorsFile(envelope.errors, { ajsc: ajscOpts, clientImportPath, namespaceTypes, serviceName })
+  const hasErrors = errorsCode != null
+  if (errorsCode != null) {
+    const errorsLines = errorsCode.split('\n')
+    errorsLines.splice(1, 0, hashComment)
+    const errorsWithHash = errorsLines.join('\n')
+    files.push({ path: join(outDir, '_errors.ts'), code: errorsWithHash })
+  }
+
+  const rawIndexCode = emitIndexFile(groupArray, { clientImportPath, hasErrors, serviceName })
+  const indexLines = rawIndexCode.split('\n')
+  indexLines.splice(1, 0, hashComment)
+  const indexCode = indexLines.join('\n')
+  files.push({ path: join(outDir, 'index.ts'), code: indexCode })
+
+  if (selfContained) {
+    const rawTypesCode = await emitClientTypesFile()
+    const typesLines = rawTypesCode.split('\n')
+    typesLines.splice(1, 0, hashComment)
+    const typesCode = typesLines.join('\n')
+    files.push({ path: join(outDir, '_types.ts'), code: typesCode })
+
+    const rawClientCode = await emitClientRuntimeFile()
+    const clientLines = rawClientCode.split('\n')
+    clientLines.splice(1, 0, hashComment)
+    const clientCode = clientLines.join('\n')
+    files.push({ path: join(outDir, '_client.ts'), code: clientCode })
+  }
+
+  if (dryRun) {
+    for (const file of files) {
+      const bytes = Buffer.byteLength(file.code, 'utf-8')
+      console.log(`[dry-run] Would write: ${file.path} (${bytes} bytes)`)
+    }
+  } else {
+    await mkdir(outDir, { recursive: true })
+    for (const file of files) {
+      await writeFile(file.path, file.code, 'utf-8')
+    }
+  }
+
+  return files
+}

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

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest'
+import { writeFile, mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { resolveEnvelope } from './resolve-envelope.js'
+import type { DocEnvelope } from '../implementations/types.js'
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const minimalEnvelope: DocEnvelope = {
+  basePath: '/api',
+  headers: [],
+  errors: [],
+  routes: [
+    {
+      kind: 'rpc',
+      name: 'Ping',
+      path: '/ping/1',
+      method: 'post',
+      scope: 'ping',
+      version: 1,
+      jsonSchema: {},
+    },
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('resolveEnvelope', () => {
+  it('accepts a DocEnvelope object directly', async () => {
+    const result = await resolveEnvelope({ envelope: minimalEnvelope })
+    expect(result).toEqual(minimalEnvelope)
+  })
+
+  it('reads a DocEnvelope from a JSON file', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'ts-proc-test-'))
+    const filePath = join(dir, 'envelope.json')
+    try {
+      await writeFile(filePath, JSON.stringify(minimalEnvelope), 'utf8')
+      const result = await resolveEnvelope({ file: filePath })
+      expect(result).toEqual(minimalEnvelope)
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('throws when routes array is empty (envelope input)', async () => {
+    const empty: DocEnvelope = { basePath: '', headers: [], errors: [], routes: [] }
+    await expect(resolveEnvelope({ envelope: empty })).rejects.toThrow(/routes/)
+  })
+
+  it('throws when routes array is empty (file input)', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'ts-proc-test-'))
+    const filePath = join(dir, 'empty.json')
+    const empty: DocEnvelope = { basePath: '', headers: [], errors: [], routes: [] }
+    try {
+      await writeFile(filePath, JSON.stringify(empty), 'utf8')
+      await expect(resolveEnvelope({ file: filePath })).rejects.toThrow(/routes/)
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+
+  it('throws when no input source is provided', async () => {
+    await expect(resolveEnvelope({})).rejects.toThrow(/input/)
+  })
+
+  // URL test skipped — requires network mock
+  it.skip('fetches a DocEnvelope from a URL', async () => {
+    // Would require mocking fetch
+  })
+})

package/src/codegen/resolve-envelope.ts

@@ -0,0 +1,61 @@
+import { readFile } from 'node:fs/promises'
+import type { DocEnvelope } from '../implementations/types.js'
+
+export interface ResolveInput {
+  url?: string
+  file?: string
+  envelope?: DocEnvelope
+}
+
+export async function resolveEnvelope(input: ResolveInput): Promise<DocEnvelope> {
+  let envelope: DocEnvelope
+
+  if (input.envelope !== undefined) {
+    envelope = input.envelope
+  } else if (input.file !== undefined) {
+    const raw = await readFile(input.file, 'utf8')
+    envelope = JSON.parse(raw) as DocEnvelope
+  } else if (input.url !== undefined) {
+    let response: Response
+    try {
+      response = await fetch(input.url)
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err)
+      throw new Error(`[ts-procedures-codegen] Failed to connect to ${input.url}: ${msg}`)
+    }
+    if (!response.ok) {
+      throw new Error(`[ts-procedures-codegen] ${input.url} returned HTTP ${response.status} ${response.statusText}`)
+    }
+    try {
+      envelope = (await response.json()) as DocEnvelope
+    } catch {
+      throw new Error(`[ts-procedures-codegen] ${input.url} returned non-JSON response. Expected a DocEnvelope JSON object.`)
+    }
+  } else {
+    throw new Error(
+      'resolveEnvelope: no input source provided. Pass one of: envelope, file, or url.'
+    )
+  }
+
+  if (!envelope || typeof envelope !== 'object') {
+    throw new Error(
+      `[ts-procedures-codegen] Invalid DocEnvelope: expected an object with a "routes" array, got ${typeof envelope}`
+    )
+  }
+
+  if (!Array.isArray(envelope.routes)) {
+    const keys = Object.keys(envelope).join(', ')
+    throw new Error(
+      `[ts-procedures-codegen] DocEnvelope is missing "routes" array. Found keys: [${keys}]. ` +
+      `Make sure your server uses DocRegistry.toJSON() to produce the envelope.`
+    )
+  }
+
+  if (envelope.routes.length === 0) {
+    throw new Error(
+      '[ts-procedures-codegen] DocEnvelope has an empty "routes" array. Register at least one procedure before generating.'
+    )
+  }
+
+  return envelope
+}