ts-procedures 5.9.1 → 5.10.2

package/src/codegen/e2e.test.ts

@@ -0,0 +1,565 @@
+import { describe, it, expect, afterEach } from 'vitest'
+import { generateClient } from './index.js'
+import { mkdirSync, rmSync, readFileSync, existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import type { DocEnvelope, RPCHttpRouteDoc, APIHttpRouteDoc, StreamHttpRouteDoc, ErrorDoc } from '../implementations/types.js'
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const rpcRoute: RPCHttpRouteDoc = {
+  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' }, email: { type: 'string' } },
+      required: ['name', 'email'],
+    },
+  },
+}
+
+const apiRoute: APIHttpRouteDoc = {
+  kind: 'api',
+  name: 'UpdateUser',
+  path: '/users/:id',
+  fullPath: '/api/users/:id',
+  method: 'put',
+  scope: 'users',
+  jsonSchema: {
+    pathParams: {
+      type: 'object',
+      properties: { id: { type: 'string' } },
+      required: ['id'],
+    },
+    body: {
+      type: 'object',
+      properties: { name: { type: 'string' } },
+      required: ['name'],
+    },
+    response: {
+      type: 'object',
+      properties: { id: { type: 'string' }, name: { type: 'string' } },
+      required: ['id', 'name'],
+    },
+  },
+}
+
+const streamRoute: StreamHttpRouteDoc = {
+  kind: 'stream',
+  name: 'WatchEvents',
+  path: '/events/stream',
+  methods: ['get'],
+  streamMode: 'sse',
+  scope: 'events',
+  version: 1,
+  jsonSchema: {
+    params: {
+      type: 'object',
+      properties: { filter: { type: 'string' } },
+      required: [],
+    },
+    // SSE envelope wrapping the actual yield payload
+    yieldType: {
+      type: 'object',
+      properties: {
+        data: {
+          type: 'object',
+          properties: { type: { type: 'string' }, payload: { type: 'string' } },
+          required: ['type'],
+        },
+        event: { type: 'string' },
+        id: { type: 'string' },
+        retry: { type: 'number' },
+      },
+      required: ['data'],
+    },
+    returnType: {
+      type: 'object',
+      properties: { count: { type: 'number' } },
+      required: ['count'],
+    },
+  },
+}
+
+const procedureErrorDoc: ErrorDoc = {
+  name: 'ProcedureError',
+  statusCode: 500,
+  description: 'An error thrown from within a procedure handler via ctx.error().',
+  schema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', const: 'ProcedureError' },
+      procedureName: { type: 'string' },
+      message: { type: 'string' },
+      meta: { type: 'object' },
+    },
+    required: ['name', 'procedureName', 'message'],
+  },
+}
+
+const validationErrorDoc: ErrorDoc = {
+  name: 'ProcedureValidationError',
+  statusCode: 400,
+  description: 'Schema validation failed for the procedure input parameters.',
+  schema: {
+    type: 'object',
+    properties: {
+      name: { type: 'string', const: 'ProcedureValidationError' },
+      procedureName: { type: 'string' },
+      message: { type: 'string' },
+    },
+    required: ['name', 'procedureName', 'message'],
+  },
+}
+
+const envelope: DocEnvelope = {
+  basePath: '/api',
+  headers: [],
+  errors: [procedureErrorDoc, validationErrorDoc],
+  routes: [rpcRoute, apiRoute, streamRoute],
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeTmpDir(): string {
+  const dir = join(
+    tmpdir(),
+    `ts-proc-e2e-test-${Date.now()}-${Math.random().toString(36).slice(2)}`
+  )
+  mkdirSync(dir, { recursive: true })
+  return dir
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('E2E: generateClient full pipeline', () => {
+  let tmpDir: string
+
+  afterEach(() => {
+    if (tmpDir && existsSync(tmpDir)) {
+      rmSync(tmpDir, { recursive: true, force: true })
+    }
+  })
+
+  // ── File existence ─────────────────────────────────────────────────────────
+
+  it('creates users.ts, events.ts, and index.ts', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    expect(existsSync(join(tmpDir, 'users.ts'))).toBe(true)
+    expect(existsSync(join(tmpDir, 'events.ts'))).toBe(true)
+    expect(existsSync(join(tmpDir, 'index.ts'))).toBe(true)
+  })
+
+  // ── users.ts — RPC route ───────────────────────────────────────────────────
+
+  it('users.ts contains GetUserParams type', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'users.ts'), 'utf-8')
+    expect(content).toContain('GetUserParams')
+  })
+
+  it('users.ts contains GetUserResponse type', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'users.ts'), 'utf-8')
+    expect(content).toContain('GetUserResponse')
+  })
+
+  // ── users.ts — API route ───────────────────────────────────────────────────
+
+  it('users.ts contains UpdateUserParams type', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'users.ts'), 'utf-8')
+    expect(content).toContain('UpdateUserParams')
+  })
+
+  it('users.ts contains UpdateUserResponse type', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'users.ts'), 'utf-8')
+    expect(content).toContain('UpdateUserResponse')
+  })
+
+  it('users.ts API callable uses fullPath in the path field', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'users.ts'), 'utf-8')
+    // fullPath ('/api/users/:id') should appear in the callable body
+    expect(content).toContain("path: '/api/users/:id'")
+    // bare path without prefix should NOT appear as path: value for the api route
+    expect(content).not.toContain("path: '/users/:id'")
+  })
+
+  it('users.ts exports bindUsersScope function', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'users.ts'), 'utf-8')
+    expect(content).toContain('bindUsersScope')
+  })
+
+  it('users.ts uses client.call for RPC route', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'users.ts'), 'utf-8')
+    expect(content).toContain('client.call')
+  })
+
+  // ── events.ts — Stream route ───────────────────────────────────────────────
+
+  it('events.ts contains WatchEventsYield type', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'events.ts'), 'utf-8')
+    expect(content).toContain('WatchEventsYield')
+  })
+
+  it('events.ts contains WatchEventsReturn type', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'events.ts'), 'utf-8')
+    expect(content).toContain('WatchEventsReturn')
+  })
+
+  it('events.ts imports TypedStream', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'events.ts'), 'utf-8')
+    expect(content).toContain('TypedStream')
+  })
+
+  it('events.ts uses client.stream', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'events.ts'), 'utf-8')
+    expect(content).toContain('client.stream')
+  })
+
+  it("events.ts callable has streamMode: 'sse'", async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'events.ts'), 'utf-8')
+    expect(content).toContain("streamMode: 'sse'")
+  })
+
+  it('events.ts SSE envelope is unwrapped — yield type does NOT contain event/id/retry fields', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'events.ts'), 'utf-8')
+    // Extract the WatchEventsYield type declaration line
+    const yieldMatch = content.match(/export type WatchEventsYield = (.+)/)
+    expect(yieldMatch).not.toBeNull()
+
+    const yieldTypeBody = yieldMatch![1]
+    // The SSE envelope properties should not appear in the resolved yield type
+    expect(yieldTypeBody).not.toContain('event')
+    expect(yieldTypeBody).not.toContain('retry')
+  })
+
+  // ── index.ts ───────────────────────────────────────────────────────────────
+
+  it('index.ts contains createScopeBindings', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'index.ts'), 'utf-8')
+    expect(content).toContain('createScopeBindings')
+  })
+
+  it('index.ts re-exports from users scope', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'index.ts'), 'utf-8')
+    expect(content).toContain("from './users'")
+  })
+
+  it('index.ts re-exports from events scope', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'index.ts'), 'utf-8')
+    expect(content).toContain("from './events'")
+  })
+
+  it('index.ts imports and uses bindUsersScope', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'index.ts'), 'utf-8')
+    expect(content).toContain('bindUsersScope')
+  })
+
+  it('index.ts imports and uses bindEventsScope', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'index.ts'), 'utf-8')
+    expect(content).toContain('bindEventsScope')
+  })
+
+  // ── _errors.ts ─────────────────────────────────────────────────────────────
+
+  it('_errors.ts file exists when envelope has errors with schemas', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    expect(existsSync(join(tmpDir, '_errors.ts'))).toBe(true)
+  })
+
+  it('_errors.ts contains ProcedureError type', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, '_errors.ts'), 'utf-8')
+    expect(content).toContain('export type ProcedureError =')
+  })
+
+  it('_errors.ts contains ProcedureErrorUnion', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, '_errors.ts'), 'utf-8')
+    expect(content).toContain('export type ProcedureErrorUnion =')
+    expect(content).toContain('ProcedureError')
+    expect(content).toContain('ProcedureValidationError')
+  })
+
+  it('index.ts re-exports from _errors when errors are present', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'index.ts'), 'utf-8')
+    expect(content).toContain("export * from './_errors'")
+  })
+
+  it('_errors.ts is not generated when no errors have schemas', async () => {
+    tmpDir = makeTmpDir()
+    const envelopeNoErrors: DocEnvelope = { ...envelope, errors: [] }
+    await generateClient({ envelope: envelopeNoErrors, outDir: tmpDir })
+
+    expect(existsSync(join(tmpDir, '_errors.ts'))).toBe(false)
+  })
+
+  it('index.ts does not re-export _errors when no errors are present', async () => {
+    tmpDir = makeTmpDir()
+    const envelopeNoErrors: DocEnvelope = { ...envelope, errors: [] }
+    await generateClient({ envelope: envelopeNoErrors, outDir: tmpDir })
+
+    const content = readFileSync(join(tmpDir, 'index.ts'), 'utf-8')
+    expect(content).not.toContain("_errors")
+  })
+
+  // ── Auto-generated headers ─────────────────────────────────────────────────
+
+  it('all generated files have the auto-generated header comment', async () => {
+    tmpDir = makeTmpDir()
+    await generateClient({ envelope, outDir: tmpDir })
+
+    for (const file of ['users.ts', 'events.ts', 'index.ts', '_errors.ts']) {
+      const content = readFileSync(join(tmpDir, file), 'utf-8')
+      expect(content).toContain('// Auto-generated by ts-procedures-codegen — do not edit')
+    }
+  })
+
+  // ── selfContained mode ────────────────────────────────────────────────────
+
+  describe('selfContained: true', () => {
+    it('_types.ts is generated and contains ClientInstance, TypedStream, ProcedureCallOptions', async () => {
+      tmpDir = makeTmpDir()
+      await generateClient({ envelope, outDir: tmpDir, selfContained: true })
+
+      expect(existsSync(join(tmpDir, '_types.ts'))).toBe(true)
+      const content = readFileSync(join(tmpDir, '_types.ts'), 'utf-8')
+      expect(content).toContain('ClientInstance')
+      expect(content).toContain('TypedStream')
+      expect(content).toContain('ProcedureCallOptions')
+    })
+
+    it('_client.ts is generated and contains createClient, createFetchAdapter, ClientRequestError', async () => {
+      tmpDir = makeTmpDir()
+      await generateClient({ envelope, outDir: tmpDir, selfContained: true })
+
+      expect(existsSync(join(tmpDir, '_client.ts'))).toBe(true)
+      const content = readFileSync(join(tmpDir, '_client.ts'), 'utf-8')
+      expect(content).toContain('createClient')
+      expect(content).toContain('createFetchAdapter')
+      expect(content).toContain('ClientRequestError')
+    })
+
+    it('_client.ts imports from ./_types and NOT from ts-procedures/client', async () => {
+      tmpDir = makeTmpDir()
+      await generateClient({ envelope, outDir: tmpDir, selfContained: true })
+
+      const content = readFileSync(join(tmpDir, '_client.ts'), 'utf-8')
+      expect(content).toContain("from './_types'")
+      expect(content).not.toContain("from 'ts-procedures/client'")
+    })
+
+    it('scope files import from ./_types and NOT from ts-procedures/client', async () => {
+      tmpDir = makeTmpDir()
+      await generateClient({ envelope, outDir: tmpDir, selfContained: true })
+
+      const content = readFileSync(join(tmpDir, 'users.ts'), 'utf-8')
+      expect(content).toContain("from './_types'")
+      expect(content).not.toContain("from 'ts-procedures/client'")
+    })
+
+    it('index.ts imports from ./_types', async () => {
+      tmpDir = makeTmpDir()
+      await generateClient({ envelope, outDir: tmpDir, selfContained: true })
+
+      const content = readFileSync(join(tmpDir, 'index.ts'), 'utf-8')
+      expect(content).toContain("from './_types'")
+    })
+
+    it('_types.ts + _client.ts compile together as valid TypeScript', async () => {
+      tmpDir = makeTmpDir()
+      await generateClient({ envelope, outDir: tmpDir, selfContained: true })
+
+      // Write a minimal tsconfig for the generated files
+      const tsconfig = {
+        compilerOptions: {
+          strict: true,
+          target: 'ES2022',
+          module: 'ES2022',
+          moduleResolution: 'bundler',
+          noEmit: true,
+          skipLibCheck: true,
+        },
+        include: ['_types.ts', '_client.ts'],
+      }
+      const { writeFileSync } = await import('node:fs')
+      writeFileSync(join(tmpDir, 'tsconfig.json'), JSON.stringify(tsconfig))
+
+      const { execSync } = await import('node:child_process')
+      // Use the project's tsc binary directly (temp dir has no node_modules)
+      const tscPath = join(process.cwd(), 'node_modules', '.bin', 'tsc')
+      // tsc --noEmit --project tsconfig.json should succeed with exit code 0
+      expect(() => {
+        execSync(`${tscPath} --noEmit --project ${join(tmpDir, 'tsconfig.json')}`, { stdio: 'pipe' })
+      }).not.toThrow()
+    })
+  })
+
+  // ── namespaceTypes mode ───────────────────────────────────────────────────
+
+  describe('namespaceTypes: true', () => {
+    it('users.ts wraps types in namespace Users with inner route namespaces', async () => {
+      tmpDir = makeTmpDir()
+      await generateClient({ envelope, outDir: tmpDir, namespaceTypes: true })
+
+      const content = readFileSync(join(tmpDir, 'users.ts'), 'utf-8')
+      expect(content).toContain('export namespace Users {')
+      expect(content).toContain('export namespace GetUser {')
+      expect(content).toContain('export namespace UpdateUser {')
+    })
+
+    it('users.ts uses qualified type references in callables', async () => {
+      tmpDir = makeTmpDir()
+      await generateClient({ envelope, outDir: tmpDir, namespaceTypes: true })
+
+      const content = readFileSync(join(tmpDir, 'users.ts'), 'utf-8')
+      expect(content).toContain('params: Users.GetUser.Params')
+      expect(content).toContain('Promise<Users.GetUser.Response>')
+      expect(content).toContain('params: Users.UpdateUser.Params')
+      expect(content).toContain('Promise<Users.UpdateUser.Response>')
+    })
+
+    it('events.ts wraps stream types in namespace', async () => {
+      tmpDir = makeTmpDir()
+      await generateClient({ envelope, outDir: tmpDir, namespaceTypes: true })
+
+      const content = readFileSync(join(tmpDir, 'events.ts'), 'utf-8')
+      expect(content).toContain('export namespace Events {')
+      expect(content).toContain('export namespace WatchEvents {')
+      expect(content).toContain('TypedStream<Events.WatchEvents.Yield, Events.WatchEvents.Return>')
+    })
+
+    it('does not contain flat-style prefixed types', async () => {
+      tmpDir = makeTmpDir()
+      await generateClient({ envelope, outDir: tmpDir, namespaceTypes: true })
+
+      const content = readFileSync(join(tmpDir, 'users.ts'), 'utf-8')
+      expect(content).not.toContain('export type GetUserParams')
+      expect(content).not.toContain('export type GetUserResponse')
+      expect(content).not.toContain('export type UpdateUserPathParams')
+    })
+
+    it('enumStyle: enum produces named enums inside namespace', async () => {
+      // Create envelope with an enum field
+      const enumRoute: RPCHttpRouteDoc = {
+        kind: 'rpc',
+        name: 'SetStatus',
+        path: '/status',
+        method: 'post',
+        scope: 'admin',
+        version: 1,
+        jsonSchema: {
+          body: {
+            type: 'object',
+            properties: {
+              status: { type: 'string', enum: ['active', 'pending', 'disabled'] },
+            },
+            required: ['status'],
+          },
+          response: {
+            type: 'object',
+            properties: { ok: { type: 'boolean' } },
+            required: ['ok'],
+          },
+        },
+      }
+      const enumEnvelope: DocEnvelope = {
+        basePath: '/api',
+        headers: [],
+        errors: [],
+        routes: [enumRoute],
+      }
+
+      tmpDir = makeTmpDir()
+      await generateClient({
+        envelope: enumEnvelope,
+        outDir: tmpDir,
+        namespaceTypes: true,
+        ajsc: { enumStyle: 'enum' },
+      })
+
+      const content = readFileSync(join(tmpDir, 'admin.ts'), 'utf-8')
+      expect(content).toContain('export namespace Admin {')
+      expect(content).toContain('export enum Status')
+    })
+  })
+})

package/src/codegen/emit-client-runtime.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest'
+import { emitClientRuntimeFile } from './emit-client-runtime.js'
+
+import { CODEGEN_HEADER } from './constants.js'
+
+describe('emitClientRuntimeFile', () => {
+  it('returns a string', async () => {
+    const result = await emitClientRuntimeFile()
+    expect(typeof result).toBe('string')
+  })
+
+  it('contains the auto-generated header comment', async () => {
+    const result = await emitClientRuntimeFile()
+    expect(result.startsWith(CODEGEN_HEADER)).toBe(true)
+  })
+
+  it("imports from './_types' (not './types.js' or 'ts-procedures/client')", async () => {
+    const result = await emitClientRuntimeFile()
+    expect(result).toContain("from './_types'")
+    expect(result).not.toContain("from './types.js'")
+    expect(result).not.toContain("from 'ts-procedures/client'")
+  })
+
+  it('contains NO inter-file imports from sibling modules', async () => {
+    const result = await emitClientRuntimeFile()
+    const interFileImports = [
+      './errors.js',
+      './hooks.js',
+      './request-builder.js',
+      './call.js',
+      './stream.js',
+      './fetch-adapter.js',
+    ]
+    for (const mod of interFileImports) {
+      expect(result).not.toContain(`from '${mod}'`)
+    }
+  })
+
+  it('contains export function createClient', async () => {
+    const result = await emitClientRuntimeFile()
+    expect(result).toMatch(/export function createClient/)
+  })
+
+  it('contains export function createFetchAdapter', async () => {
+    const result = await emitClientRuntimeFile()
+    expect(result).toMatch(/export function createFetchAdapter/)
+  })
+
+  it('contains export class ClientRequestError', async () => {
+    const result = await emitClientRuntimeFile()
+    expect(result).toMatch(/export class ClientRequestError/)
+  })
+
+  it('contains export class ClientPathParamError', async () => {
+    const result = await emitClientRuntimeFile()
+    expect(result).toMatch(/export class ClientPathParamError/)
+  })
+
+  it('contains export class ClientStreamError', async () => {
+    const result = await emitClientRuntimeFile()
+    expect(result).toMatch(/export class ClientStreamError/)
+  })
+
+  it('contains export async function executeCall', async () => {
+    const result = await emitClientRuntimeFile()
+    expect(result).toMatch(/export async function executeCall/)
+  })
+
+  it('contains export async function executeStream', async () => {
+    const result = await emitClientRuntimeFile()
+    expect(result).toMatch(/export async function executeStream/)
+  })
+
+  it('contains export function createTypedStream', async () => {
+    const result = await emitClientRuntimeFile()
+    expect(result).toMatch(/export function createTypedStream/)
+  })
+
+  it('contains export interface FetchAdapterConfig', async () => {
+    const result = await emitClientRuntimeFile()
+    expect(result).toMatch(/export interface FetchAdapterConfig/)
+  })
+
+  it('does NOT contain export type { re-export blocks from index.ts barrel', async () => {
+    const result = await emitClientRuntimeFile()
+    expect(result).not.toMatch(/export type \{[\s\S]*?\} from/)
+  })
+
+  it('does NOT contain orphaned "Barrel exports" section comment', async () => {
+    const result = await emitClientRuntimeFile()
+    expect(result).not.toContain('// ── Barrel exports')
+  })
+})