ts-procedures 5.9.0 → 5.10.0

package/src/codegen/emit-scope.test.ts

@@ -0,0 +1,624 @@
+import { describe, expect, it } from 'vitest'
+import { emitScopeFile } from './emit-scope.js'
+import type { ScopeGroup } from './group-routes.js'
+import type { RPCHttpRouteDoc, APIHttpRouteDoc, StreamHttpRouteDoc } from '../implementations/types.js'
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const rpcGroup: ScopeGroup = {
+  scopeKey: 'users',
+  camelCase: 'users',
+  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'],
+        },
+      },
+    } satisfies RPCHttpRouteDoc,
+  ],
+}
+
+const apiGroup: ScopeGroup = {
+  scopeKey: 'posts',
+  camelCase: 'posts',
+  routes: [
+    {
+      kind: 'api',
+      name: 'UpdatePost',
+      path: '/posts/:id',
+      method: 'put',
+      fullPath: '/api/posts/:id',
+      scope: 'posts',
+      jsonSchema: {
+        pathParams: {
+          type: 'object',
+          properties: { id: { type: 'string' } },
+          required: ['id'],
+        },
+        body: {
+          type: 'object',
+          properties: { title: { type: 'string' } },
+          required: ['title'],
+        },
+        response: {
+          type: 'object',
+          properties: { id: { type: 'string' }, title: { type: 'string' } },
+          required: ['id', 'title'],
+        },
+      },
+    } satisfies APIHttpRouteDoc,
+  ],
+}
+
+const streamGroup: ScopeGroup = {
+  scopeKey: 'events',
+  camelCase: 'events',
+  routes: [
+    {
+      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: data wraps the actual yield type
+        yieldType: {
+          type: 'object',
+          properties: {
+            data: {
+              type: 'object',
+              properties: { message: { type: 'string' } },
+              required: ['message'],
+            },
+            event: { type: 'string' },
+            id: { type: 'string' },
+            retry: { type: 'number' },
+          },
+          required: ['data'],
+        },
+        returnType: {
+          type: 'object',
+          properties: { total: { type: 'number' } },
+          required: ['total'],
+        },
+      },
+    } satisfies StreamHttpRouteDoc,
+  ],
+}
+
+// Versioned fixtures: v1 and v2 of the same RPC in one scope
+const rpcVersionedGroup: ScopeGroup = {
+  scopeKey: 'users',
+  camelCase: 'users',
+  routes: [
+    {
+      kind: 'rpc',
+      name: 'GetUser',
+      path: '/users/get-user/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'],
+        },
+      },
+    } satisfies RPCHttpRouteDoc,
+    {
+      kind: 'rpc',
+      name: 'GetUser',
+      path: '/users/get-user/2',
+      method: 'post',
+      scope: 'users',
+      version: 2,
+      jsonSchema: {
+        body: {
+          type: 'object',
+          properties: { id: { type: 'string' }, includeProfile: { type: 'boolean' } },
+          required: ['id'],
+        },
+        response: {
+          type: 'object',
+          properties: { name: { type: 'string' }, profile: { type: 'object' } },
+          required: ['name'],
+        },
+      },
+    } satisfies RPCHttpRouteDoc,
+  ],
+}
+
+// Versioned stream fixture
+const streamVersionedGroup: ScopeGroup = {
+  scopeKey: 'events',
+  camelCase: 'events',
+  routes: [
+    {
+      kind: 'stream',
+      name: 'WatchEvents',
+      path: '/events/watch-events/1',
+      methods: ['get'],
+      streamMode: 'sse',
+      scope: 'events',
+      version: 1,
+      jsonSchema: {
+        params: {
+          type: 'object',
+          properties: { filter: { type: 'string' } },
+          required: [],
+        },
+        yieldType: { type: 'object', properties: { message: { type: 'string' } }, required: ['message'] },
+        returnType: { type: 'object', properties: { total: { type: 'number' } }, required: ['total'] },
+      },
+    } satisfies StreamHttpRouteDoc,
+    {
+      kind: 'stream',
+      name: 'WatchEvents',
+      path: '/events/watch-events/2',
+      methods: ['get', 'post'],
+      streamMode: 'sse',
+      scope: 'events',
+      version: 2,
+      jsonSchema: {
+        params: {
+          type: 'object',
+          properties: { filter: { type: 'string' }, cursor: { type: 'string' } },
+          required: [],
+        },
+        yieldType: { type: 'object', properties: { message: { type: 'string' }, ts: { type: 'number' } }, required: ['message', 'ts'] },
+        returnType: { type: 'object', properties: { total: { type: 'number' }, nextCursor: { type: 'string' } }, required: ['total'] },
+      },
+    } satisfies StreamHttpRouteDoc,
+  ],
+}
+
+const streamGroupText: ScopeGroup = {
+  scopeKey: 'feed',
+  camelCase: 'feed',
+  routes: [
+    {
+      kind: 'stream',
+      name: 'GetFeed',
+      path: '/feed/stream',
+      methods: ['get'],
+      streamMode: 'text',
+      scope: 'feed',
+      version: 1,
+      jsonSchema: {
+        params: undefined,
+        yieldType: {
+          type: 'string',
+        },
+        returnType: undefined,
+      },
+    } satisfies StreamHttpRouteDoc,
+  ],
+}
+
+// Fixture with nested objects for testing extracted sub-types
+const rpcGroupNested: ScopeGroup = {
+  scopeKey: 'accounts',
+  camelCase: 'accounts',
+  routes: [
+    {
+      kind: 'rpc',
+      name: 'CreateAccount',
+      path: '/accounts',
+      method: 'post',
+      scope: 'accounts',
+      version: 1,
+      jsonSchema: {
+        body: {
+          type: 'object',
+          properties: {
+            owner: {
+              type: 'object',
+              properties: { name: { type: 'string' }, email: { type: 'string' } },
+              required: ['name', 'email'],
+            },
+            status: { type: 'string', enum: ['active', 'pending'] },
+          },
+          required: ['owner', 'status'],
+        },
+        response: {
+          type: 'object',
+          properties: { id: { type: 'string' } },
+          required: ['id'],
+        },
+      },
+    } satisfies RPCHttpRouteDoc,
+  ],
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('emitScopeFile', () => {
+  describe('RPC scope', () => {
+    it('includes the auto-generated header comment', async () => {
+      const output = await emitScopeFile(rpcGroup)
+      expect(output).toContain('// Auto-generated by ts-procedures-codegen — do not edit')
+    })
+
+    it('imports ClientInstance and ProcedureCallOptions but not TypedStream', async () => {
+      const output = await emitScopeFile(rpcGroup)
+      expect(output).toContain("import type { ClientInstance, ProcedureCallOptions } from 'ts-procedures/client'")
+      expect(output).not.toContain('TypedStream')
+    })
+
+    it('exports param type from jsonSchema.body', async () => {
+      const output = await emitScopeFile(rpcGroup)
+      expect(output).toContain('export type GetUserParams')
+    })
+
+    it('exports response type from jsonSchema.response', async () => {
+      const output = await emitScopeFile(rpcGroup)
+      expect(output).toContain('export type GetUserResponse')
+    })
+
+    it('emits the bindUsersScope function', async () => {
+      const output = await emitScopeFile(rpcGroup)
+      expect(output).toContain('export function bindUsersScope(client: ClientInstance)')
+    })
+
+    it('callable uses client.call with kind: rpc', async () => {
+      const output = await emitScopeFile(rpcGroup)
+      expect(output).toContain("kind: 'rpc'")
+      expect(output).toContain('client.call')
+    })
+
+    it('callable includes JSDoc with method and path', async () => {
+      const output = await emitScopeFile(rpcGroup)
+      expect(output).toContain('POST')
+      expect(output).toContain('/users/1')
+    })
+  })
+
+  describe('API scope', () => {
+    it('generates PascalCase channel types', async () => {
+      const output = await emitScopeFile(apiGroup)
+      expect(output).toContain('export type UpdatePostPathParams')
+      expect(output).toContain('export type UpdatePostBody')
+    })
+
+    it('composes structured params type', async () => {
+      const output = await emitScopeFile(apiGroup)
+      expect(output).toContain('export type UpdatePostParams =')
+      expect(output).toContain('pathParams: UpdatePostPathParams')
+      expect(output).toContain('body: UpdatePostBody')
+    })
+
+    it('exports response type', async () => {
+      const output = await emitScopeFile(apiGroup)
+      expect(output).toContain('export type UpdatePostResponse')
+    })
+
+    it('callable uses client.call with kind: api', async () => {
+      const output = await emitScopeFile(apiGroup)
+      expect(output).toContain("kind: 'api'")
+      expect(output).toContain('client.call')
+    })
+
+    it('callable includes JSDoc with method and fullPath', async () => {
+      const output = await emitScopeFile(apiGroup)
+      expect(output).toContain('PUT')
+      expect(output).toContain('/api/posts/:id')
+    })
+
+    it('callable path field uses fullPath not path', async () => {
+      const output = await emitScopeFile(apiGroup)
+      expect(output).toContain("path: '/api/posts/:id'")
+      expect(output).not.toContain("path: '/posts/:id'")
+    })
+  })
+
+  describe('Stream scope', () => {
+    it('imports TypedStream when stream routes are present', async () => {
+      const output = await emitScopeFile(streamGroup)
+      expect(output).toContain('TypedStream')
+      expect(output).toContain("import type { ClientInstance, ProcedureCallOptions, TypedStream } from 'ts-procedures/client'")
+    })
+
+    it('unwraps SSE envelope for yieldType', async () => {
+      const output = await emitScopeFile(streamGroup)
+      expect(output).toContain('export type WatchEventsYield')
+      const yieldTypeMatch = output.match(/export type WatchEventsYield = ([^;]+)/)
+      expect(yieldTypeMatch).not.toBeNull()
+    })
+
+    it('emits params type from jsonSchema.params', async () => {
+      const output = await emitScopeFile(streamGroup)
+      expect(output).toContain('export type WatchEventsParams')
+    })
+
+    it('emits return type from jsonSchema.returnType', async () => {
+      const output = await emitScopeFile(streamGroup)
+      expect(output).toContain('export type WatchEventsReturn')
+    })
+
+    it('callable uses client.stream with kind: stream and streamMode', async () => {
+      const output = await emitScopeFile(streamGroup)
+      expect(output).toContain("kind: 'stream'")
+      expect(output).toContain("streamMode: 'sse'")
+      expect(output).toContain('client.stream')
+    })
+
+    it('callable returns TypedStream<Yield, Return>', async () => {
+      const output = await emitScopeFile(streamGroup)
+      expect(output).toContain('TypedStream<WatchEventsYield, WatchEventsReturn>')
+    })
+
+    it('does not import TypedStream for non-stream scopes', async () => {
+      const output = await emitScopeFile(rpcGroup)
+      expect(output).not.toContain('TypedStream')
+    })
+
+    it('handles text stream without SSE unwrapping', async () => {
+      const output = await emitScopeFile(streamGroupText)
+      expect(output).toContain('export type GetFeedYield')
+    })
+
+    it('omits params type when params schema is undefined', async () => {
+      const output = await emitScopeFile(streamGroupText)
+      expect(output).not.toContain('GetFeedParams')
+    })
+  })
+
+  describe('bindScope function structure', () => {
+    it('wraps callables in the bind function return object', async () => {
+      const output = await emitScopeFile(rpcGroup)
+      expect(output).toMatch(/export function bindUsersScope\(client: ClientInstance\)/)
+      expect(output).toContain('return {')
+    })
+
+    it('places types section before callables section', async () => {
+      const output = await emitScopeFile(rpcGroup)
+      const typesIdx = output.indexOf('// ── Types')
+      const callablesIdx = output.indexOf('// ── Callables')
+      expect(typesIdx).toBeLessThan(callablesIdx)
+    })
+  })
+
+  describe('namespaceTypes', () => {
+    describe('RPC scope', () => {
+      it('wraps types in outer scope namespace and inner route namespace', async () => {
+        const output = await emitScopeFile(rpcGroup, { namespaceTypes: true })
+        expect(output).toContain('export namespace Users {')
+        expect(output).toContain('  export namespace GetUser {')
+      })
+
+      it('uses simplified type names inside namespace', async () => {
+        const output = await emitScopeFile(rpcGroup, { namespaceTypes: true })
+        expect(output).toContain('export type Params =')
+        expect(output).toContain('export type Response =')
+        expect(output).not.toContain('export type GetUserParams')
+        expect(output).not.toContain('export type GetUserResponse')
+      })
+
+      it('callable references fully qualified namespace types', async () => {
+        const output = await emitScopeFile(rpcGroup, { namespaceTypes: true })
+        expect(output).toContain('params: Users.GetUser.Params')
+        expect(output).toContain('Promise<Users.GetUser.Response>')
+      })
+
+      it('still emits the bind function', async () => {
+        const output = await emitScopeFile(rpcGroup, { namespaceTypes: true })
+        expect(output).toContain('export function bindUsersScope(client: ClientInstance)')
+      })
+    })
+
+    describe('API scope', () => {
+      it('wraps channel types and structured Params in namespace', async () => {
+        const output = await emitScopeFile(apiGroup, { namespaceTypes: true })
+        expect(output).toContain('export namespace Posts {')
+        expect(output).toContain('  export namespace UpdatePost {')
+        expect(output).toContain('export type PathParams =')
+        expect(output).toContain('export type Body =')
+        expect(output).toContain('export type Response =')
+      })
+
+      it('structured Params uses namespace-local channel names', async () => {
+        const output = await emitScopeFile(apiGroup, { namespaceTypes: true })
+        expect(output).toContain('export type Params = { pathParams: PathParams; body: Body }')
+      })
+
+      it('callable references fully qualified namespace types', async () => {
+        const output = await emitScopeFile(apiGroup, { namespaceTypes: true })
+        expect(output).toContain('params: Posts.UpdatePost.Params')
+        expect(output).toContain('Promise<Posts.UpdatePost.Response>')
+      })
+    })
+
+    describe('Stream scope', () => {
+      it('wraps stream types in namespace', async () => {
+        const output = await emitScopeFile(streamGroup, { namespaceTypes: true })
+        expect(output).toContain('export namespace Events {')
+        expect(output).toContain('  export namespace WatchEvents {')
+        expect(output).toContain('export type Params =')
+        expect(output).toContain('export type Yield =')
+        expect(output).toContain('export type Return =')
+      })
+
+      it('callable references fully qualified namespace types', async () => {
+        const output = await emitScopeFile(streamGroup, { namespaceTypes: true })
+        expect(output).toContain('params: Events.WatchEvents.Params')
+        expect(output).toContain('TypedStream<Events.WatchEvents.Yield, Events.WatchEvents.Return>')
+      })
+    })
+
+    describe('extracted sub-types (inlineTypes: false)', () => {
+      it('extracts nested object types into the namespace', async () => {
+        const output = await emitScopeFile(rpcGroupNested, { namespaceTypes: true })
+        // ajsc should extract the nested 'owner' object as a named type
+        expect(output).toContain('export namespace Accounts {')
+        expect(output).toContain('export namespace CreateAccount {')
+        expect(output).toContain('export type Owner =')
+        expect(output).toContain('export type Params =')
+      })
+
+      it('enables enumStyle: enum in namespace mode', async () => {
+        const output = await emitScopeFile(rpcGroupNested, {
+          namespaceTypes: true,
+          ajsc: { enumStyle: 'enum' },
+        })
+        // With enumStyle: 'enum', the status enum should be extracted
+        expect(output).toContain('export enum Status')
+      })
+
+      it('ajsc formatting options are ignored in flat mode', async () => {
+        const output = await emitScopeFile(rpcGroupNested, {
+          ajsc: { enumStyle: 'enum' },
+        })
+        // In flat mode (inlineTypes: true), enumStyle: 'enum' has no effect
+        expect(output).not.toContain('export enum')
+        expect(output).toContain('"active" | "pending"')
+      })
+    })
+
+    it('defaults to flat mode when namespaceTypes is false', async () => {
+      const output = await emitScopeFile(rpcGroup, { namespaceTypes: false })
+      expect(output).not.toContain('export namespace')
+      expect(output).toContain('export type GetUserParams')
+    })
+  })
+
+  describe('version suffix', () => {
+    describe('RPC routes', () => {
+      it('v1 types have no version suffix', async () => {
+        const output = await emitScopeFile(rpcVersionedGroup)
+        expect(output).toContain('export type GetUserParams')
+        expect(output).toContain('export type GetUserResponse')
+      })
+
+      it('v2 types use V2 suffix', async () => {
+        const output = await emitScopeFile(rpcVersionedGroup)
+        expect(output).toContain('export type GetUserV2Params')
+        expect(output).toContain('export type GetUserV2Response')
+      })
+
+      it('v1 callable has no version suffix', async () => {
+        const output = await emitScopeFile(rpcVersionedGroup)
+        expect(output).toContain('GetUser(params: GetUserParams')
+      })
+
+      it('v2 callable uses V2 suffix', async () => {
+        const output = await emitScopeFile(rpcVersionedGroup)
+        expect(output).toContain('GetUserV2(params: GetUserV2Params')
+      })
+
+      it('v1 callable uses its own path', async () => {
+        const output = await emitScopeFile(rpcVersionedGroup)
+        expect(output).toContain("path: '/users/get-user/1'")
+      })
+
+      it('v2 callable uses its own path', async () => {
+        const output = await emitScopeFile(rpcVersionedGroup)
+        expect(output).toContain("path: '/users/get-user/2'")
+      })
+    })
+
+    describe('Stream routes', () => {
+      it('v1 types have no version suffix', async () => {
+        const output = await emitScopeFile(streamVersionedGroup)
+        expect(output).toContain('export type WatchEventsParams')
+        expect(output).toContain('export type WatchEventsYield')
+        expect(output).toContain('export type WatchEventsReturn')
+      })
+
+      it('v2 types use V2 suffix', async () => {
+        const output = await emitScopeFile(streamVersionedGroup)
+        expect(output).toContain('export type WatchEventsV2Params')
+        expect(output).toContain('export type WatchEventsV2Yield')
+        expect(output).toContain('export type WatchEventsV2Return')
+      })
+
+      it('v1 callable has no version suffix', async () => {
+        const output = await emitScopeFile(streamVersionedGroup)
+        expect(output).toContain('WatchEvents(params: WatchEventsParams')
+      })
+
+      it('v2 callable uses V2 suffix', async () => {
+        const output = await emitScopeFile(streamVersionedGroup)
+        expect(output).toContain('WatchEventsV2(params: WatchEventsV2Params')
+      })
+
+      it('v2 callable returns TypedStream with V2 types', async () => {
+        const output = await emitScopeFile(streamVersionedGroup)
+        expect(output).toContain('TypedStream<WatchEventsV2Yield, WatchEventsV2Return>')
+      })
+    })
+
+    describe('namespace mode', () => {
+      it('v1 uses unversioned namespace name', async () => {
+        const output = await emitScopeFile(rpcVersionedGroup, { namespaceTypes: true })
+        expect(output).toContain('export namespace GetUser {')
+      })
+
+      it('v2 uses versioned namespace name', async () => {
+        const output = await emitScopeFile(rpcVersionedGroup, { namespaceTypes: true })
+        expect(output).toContain('export namespace GetUserV2 {')
+      })
+
+      it('v1 callable references unversioned namespace types', async () => {
+        const output = await emitScopeFile(rpcVersionedGroup, { namespaceTypes: true })
+        expect(output).toContain('params: Users.GetUser.Params')
+        expect(output).toContain('Promise<Users.GetUser.Response>')
+      })
+
+      it('v2 callable references versioned namespace types', async () => {
+        const output = await emitScopeFile(rpcVersionedGroup, { namespaceTypes: true })
+        expect(output).toContain('params: Users.GetUserV2.Params')
+        expect(output).toContain('Promise<Users.GetUserV2.Response>')
+      })
+    })
+  })
+
+  describe('clientImportPath', () => {
+    it('uses custom clientImportPath in import statement', async () => {
+      const output = await emitScopeFile(rpcGroup, { clientImportPath: '@my-app/client' })
+      expect(output).toContain("from '@my-app/client'")
+      expect(output).not.toContain("from 'ts-procedures/client'")
+    })
+
+    it('uses custom clientImportPath for stream scope imports', async () => {
+      const output = await emitScopeFile(streamGroup, { clientImportPath: '@my-app/client' })
+      expect(output).toContain("from '@my-app/client'")
+      expect(output).toContain('TypedStream')
+    })
+
+    it('defaults to ts-procedures/client when not specified', async () => {
+      const output = await emitScopeFile(rpcGroup)
+      expect(output).toContain("from 'ts-procedures/client'")
+    })
+  })
+})