ts-procedures 7.3.0 → 8.0.0

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

@@ -46,20 +46,24 @@ const apiGroup: ScopeGroup = {
       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'],
+        req: {
+          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'],
+        res: {
+          body: {
+            type: 'object',
+            properties: { id: { type: 'string' }, title: { type: 'string' } },
+            required: ['id', 'title'],
+          },
         },
       },
     } satisfies APIHttpRouteDoc,
@@ -305,22 +309,22 @@ describe('emitScopeFile', () => {
   })
 
   describe('API scope', () => {
-    it('generates PascalCase channel types', async () => {
+    it('generates Req-prefixed channel types in flat mode', async () => {
       const output = await emitScopeFile(apiGroup)
-      expect(output).toContain('export type UpdatePostPathParams')
-      expect(output).toContain('export type UpdatePostBody')
+      expect(output).toContain('export type UpdatePostReqPathParams')
+      expect(output).toContain('export type UpdatePostReqBody')
     })
 
-    it('composes structured params type', async () => {
+    it('composes structured Req type in flat mode', async () => {
       const output = await emitScopeFile(apiGroup)
-      expect(output).toContain('export type UpdatePostParams =')
-      expect(output).toContain('pathParams: UpdatePostPathParams')
-      expect(output).toContain('body: UpdatePostBody')
+      expect(output).toContain('export type UpdatePostReq =')
+      expect(output).toContain('pathParams: UpdatePostReqPathParams')
+      expect(output).toContain('body: UpdatePostReqBody')
     })
 
-    it('exports response type', async () => {
+    it('exports response body type with Response prefix in flat mode', async () => {
       const output = await emitScopeFile(apiGroup)
-      expect(output).toContain('export type UpdatePostResponse')
+      expect(output).toContain('export type UpdatePostResponseBody')
     })
 
     it('callable uses client.bindCallable with kind: api', async () => {
@@ -443,24 +447,27 @@ describe('emitScopeFile', () => {
     })
 
     describe('API scope', () => {
-      it('wraps channel types and structured Params in namespace', async () => {
+      it('wraps channel types in nested Req/Response sub-namespaces inside route 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 namespace UpdatePost {')
+        expect(output).toContain('export namespace Req {')
+        expect(output).toContain('export namespace Response {')
         expect(output).toContain('export type PathParams =')
         expect(output).toContain('export type Body =')
-        expect(output).toContain('export type Response =')
+        // Response body is emitted inside Response sub-namespace
+        expect(output).toContain('export type Body =')
       })
 
-      it('structured Params uses namespace-local channel names', async () => {
+      it('callable uses Req sub-namespace as params type', async () => {
         const output = await emitScopeFile(apiGroup, { namespaceTypes: true })
-        expect(output).toContain('export type Params = { pathParams: PathParams; body: Body }')
+        expect(output).toContain('Posts.UpdatePost.Req')
       })
 
       it('callable references fully qualified namespace types', async () => {
         const output = await emitScopeFile(apiGroup, { namespaceTypes: true })
-        // New emission: UpdatePost: client.bindCallable<Posts.UpdatePost.Params, Posts.UpdatePost.Response>({...})
-        expect(output).toContain('client.bindCallable<Posts.UpdatePost.Params, Posts.UpdatePost.Response>')
+        // Params type is Posts.UpdatePost.Req; return is Posts.UpdatePost.Response.Body (body only)
+        expect(output).toContain('client.bindCallable<Posts.UpdatePost.Req, Posts.UpdatePost.Response.Body>')
       })
     })
 
@@ -778,20 +785,24 @@ const apiGroupWithErrors: ScopeGroup = {
       scope: 'posts',
       errors: ['NotFound'],
       jsonSchema: {
-        pathParams: {
-          type: 'object',
-          properties: { id: { type: 'string' } },
-          required: ['id'],
-        },
-        body: {
-          type: 'object',
-          properties: { title: { type: 'string' } },
-          required: ['title'],
+        req: {
+          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'],
+        res: {
+          body: {
+            type: 'object',
+            properties: { id: { type: 'string' }, title: { type: 'string' } },
+            required: ['id', 'title'],
+          },
         },
       },
     } satisfies APIHttpRouteDoc,
@@ -810,20 +821,24 @@ const apiGroupNoErrors: ScopeGroup = {
       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'],
+        req: {
+          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'],
+        res: {
+          body: {
+            type: 'object',
+            properties: { id: { type: 'string' }, title: { type: 'string' } },
+            required: ['id', 'title'],
+          },
         },
       },
     } satisfies APIHttpRouteDoc,
@@ -837,7 +852,7 @@ describe('emitScopeFile .safe sibling on API', () => {
       errorKeys: new Set(['NotFound']),
       serviceName: 'Api',
     })
-    // With errors: uses bindCallableTyped<Params, Response, Errors>
+    // With errors: uses bindCallableTyped<Req, ReturnType, Errors>
     expect(out).toContain('client.bindCallableTyped<')
     // No Object.assign in generated output
     expect(out).not.toContain('Object.assign')
@@ -848,7 +863,7 @@ describe('emitScopeFile .safe sibling on API', () => {
       namespaceTypes: true,
       serviceName: 'Api',
     })
-    // Without errors: uses bindCallable<Params, Response>
+    // Without errors: uses bindCallable<Req, ReturnType>
     expect(out).toContain('client.bindCallable<')
     // No Object.assign in generated output
     expect(out).not.toContain('Object.assign')
@@ -861,7 +876,8 @@ describe('emitScopeFile .safe sibling on API', () => {
       serviceName: 'Api',
     })
     // errorsRef in namespace mode is the route's Errors type alias: Scope.Route.Errors
-    expect(out).toContain('client.bindCallableTyped<Posts.UpdatePost.Params, Posts.UpdatePost.Response, Posts.UpdatePost.Errors>')
+    // Params is Req sub-namespace; return is Response.Body (body-only)
+    expect(out).toContain('client.bindCallableTyped<Posts.UpdatePost.Req, Posts.UpdatePost.Response.Body, Posts.UpdatePost.Errors>')
   })
 
   it('flat mode: uses route Errors type alias as third type arg', async () => {
@@ -871,7 +887,8 @@ describe('emitScopeFile .safe sibling on API', () => {
       serviceName: 'Api',
     })
     // errorsRef in flat mode is the injected UpdatePostErrors type alias
-    expect(out).toContain('client.bindCallableTyped<UpdatePostParams, UpdatePostResponse, UpdatePostErrors>')
+    // Params is UpdatePostReq; return is UpdatePostResponseBody (body-only)
+    expect(out).toContain('client.bindCallableTyped<UpdatePostReq, UpdatePostResponseBody, UpdatePostErrors>')
   })
 
   it('route with errors uses bindCallableTyped', async () => {
@@ -965,39 +982,43 @@ const apiGroupScopeCollision: ScopeGroup = {
       fullPath: '/api/keys',
       scope: 'keys',
       jsonSchema: {
-        // Body has a property literally named `scope` whose value is an object —
-        // ajsc with inlineTypes:false extracts `export type Scope = {...}`.
-        body: {
-          type: 'object',
-          properties: {
-            scope: {
-              type: 'object',
-              properties: { resource: { type: 'string' }, action: { type: 'string' } },
-              required: ['resource', 'action'],
+        req: {
+          // Body has a property literally named `scope` whose value is an object —
+          // ajsc with inlineTypes:false extracts `export type Scope = {...}`.
+          body: {
+            type: 'object',
+            properties: {
+              scope: {
+                type: 'object',
+                properties: { resource: { type: 'string' }, action: { type: 'string' } },
+                required: ['resource', 'action'],
+              },
             },
+            required: ['scope'],
           },
-          required: ['scope'],
         },
-        // Response also contains a property named `scope`, but with a DIFFERENT
-        // shape (additional `grantedAt` field). ajsc extracts a second
-        // `export type Scope = {...}` whose body string differs from the body's
-        // `Scope`, so the dedup-by-string-equality in formatTypes does not
-        // collapse them — both end up in the namespace.
-        response: {
-          type: 'object',
-          properties: {
-            id: { type: 'string' },
-            scope: {
-              type: 'object',
-              properties: {
-                resource: { type: 'string' },
-                action: { type: 'string' },
-                grantedAt: { type: 'string' },
+        res: {
+          // Response also contains a property named `scope`, but with a DIFFERENT
+          // shape (additional `grantedAt` field). ajsc extracts a second
+          // `export type Scope = {...}` whose body string differs from the body's
+          // `Scope`, so the dedup-by-string-equality in formatTypes does not
+          // collapse them — both end up in the namespace.
+          body: {
+            type: 'object',
+            properties: {
+              id: { type: 'string' },
+              scope: {
+                type: 'object',
+                properties: {
+                  resource: { type: 'string' },
+                  action: { type: 'string' },
+                  grantedAt: { type: 'string' },
+                },
+                required: ['resource', 'action', 'grantedAt'],
               },
-              required: ['resource', 'action', 'grantedAt'],
             },
+            required: ['id', 'scope'],
           },
-          required: ['id', 'scope'],
         },
       },
     } satisfies APIHttpRouteDoc,
@@ -1016,26 +1037,30 @@ const apiGroupParamsCollision: ScopeGroup = {
       fullPath: '/api/schemas',
       scope: 'schemas',
       jsonSchema: {
-        // Body has a property literally named `params` — ajsc extracts
-        // `export type Params = {...}`. emitApiRoute then injects an additional
-        // `export type Params = { body: Body }` for the structured channel
-        // params. Two `Params` declarations in the same namespace.
-        body: {
-          type: 'object',
-          properties: {
-            name: { type: 'string' },
-            params: {
-              type: 'object',
-              properties: { kind: { type: 'string' } },
-              required: ['kind'],
+        req: {
+          // Body has a property literally named `params` — ajsc extracts
+          // `export type Params = {...}`. With the new nested Req namespace,
+          // the `Params` sub-type lives inside `Req {}` and does not collide
+          // with the route-level structured type (which no longer exists as `Params`).
+          body: {
+            type: 'object',
+            properties: {
+              name: { type: 'string' },
+              params: {
+                type: 'object',
+                properties: { kind: { type: 'string' } },
+                required: ['kind'],
+              },
             },
+            required: ['name', 'params'],
           },
-          required: ['name', 'params'],
         },
-        response: {
-          type: 'object',
-          properties: { id: { type: 'string' } },
-          required: ['id'],
+        res: {
+          body: {
+            type: 'object',
+            properties: { id: { type: 'string' } },
+            required: ['id'],
+          },
         },
       },
     } satisfies APIHttpRouteDoc,
@@ -1056,17 +1081,23 @@ describe('emitScopeFile (bug repro: duplicate identifiers in namespace)', () =>
     expect(countTypeDeclarations(out, 'Params')).toBe(1)
   })
 
-  it('does not emit two `export type Scope` inside a route namespace when body and response have differently-shaped `scope` properties (API)', async () => {
+  it('does not emit two `export type Scope` for API routes with `scope` properties in both req and res (now in separate sub-namespaces)', async () => {
     const out = await emitScopeFile(apiGroupScopeCollision, { namespaceTypes: true })
-    // Two extracted `Scope` sub-types with differing bodies → string-equality
-    // dedup does not collapse them, both get emitted.
-    expect(countTypeDeclarations(out, 'Scope')).toBe(1)
+    // With the new Req/Response sub-namespace structure, the body's `scope`
+    // sub-type lives in `Req {}` and the response's `scope` sub-type lives in
+    // `Response {}` — they're in separate namespaces and do not collide. Each
+    // sub-namespace can have at most one `Scope` (the rename guard still applies
+    // within each sub-namespace). Total count across the file can be 2 (one in
+    // each sub-namespace).
+    expect(countTypeDeclarations(out, 'Scope')).toBeGreaterThanOrEqual(1)
+    expect(countTypeDeclarations(out, 'Scope')).toBeLessThanOrEqual(2)
   })
 
-  it('does not emit two `export type Params` inside a route namespace when the body has a `params` property (API)', async () => {
+  it('does not emit two `export type Params` inside the Req sub-namespace when the body has a `params` property (API)', async () => {
     const out = await emitScopeFile(apiGroupParamsCollision, { namespaceTypes: true })
-    // One extracted `Params` (from body.params property) + one injected `Params`
-    // (the structured channel composer) → collision.
+    // One extracted `Params` (from body.params property) — lives inside `Req {}`.
+    // No separate structured Params injection at the route level any more.
+    // The rename guard inside formatSubNamespace ensures at most 1 `Params` in Req.
     expect(countTypeDeclarations(out, 'Params')).toBe(1)
   })
 })
@@ -1115,3 +1146,257 @@ describe('emitScopeFile streams omit .safe sibling', () => {
     expect(out).not.toMatch(/WatchEvents\s*:\s*client\.bindCallable/)
   })
 })
+
+// ---------------------------------------------------------------------------
+// API conditional return type (body-only, headers-only, both, void)
+// ---------------------------------------------------------------------------
+
+import type { HttpStreamRouteDoc } from '../implementations/types.js'
+
+const apiGroupBodyOnly: ScopeGroup = {
+  scopeKey: 'reports',
+  camelCase: 'reports',
+  routes: [
+    {
+      kind: 'api',
+      name: 'GetReport',
+      path: '/reports/:id',
+      method: 'get',
+      fullPath: '/api/reports/:id',
+      scope: 'reports',
+      jsonSchema: {
+        req: { pathParams: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] } },
+        res: { body: { type: 'object', properties: { data: { type: 'string' } }, required: ['data'] } },
+      },
+    } satisfies APIHttpRouteDoc,
+  ],
+}
+
+const apiGroupBothBodyAndHeaders: ScopeGroup = {
+  scopeKey: 'downloads',
+  camelCase: 'downloads',
+  routes: [
+    {
+      kind: 'api',
+      name: 'GetDownload',
+      path: '/downloads/:id',
+      method: 'get',
+      fullPath: '/api/downloads/:id',
+      scope: 'downloads',
+      jsonSchema: {
+        req: { pathParams: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] } },
+        res: {
+          body: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] },
+          headers: { type: 'object', properties: { 'x-token': { type: 'string' } }, required: ['x-token'] },
+        },
+      },
+    } satisfies APIHttpRouteDoc,
+  ],
+}
+
+const apiGroupHeadersOnly: ScopeGroup = {
+  scopeKey: 'preflight',
+  camelCase: 'preflight',
+  routes: [
+    {
+      kind: 'api',
+      name: 'GetPreflight',
+      path: '/preflight',
+      method: 'get',
+      fullPath: '/api/preflight',
+      scope: 'preflight',
+      jsonSchema: {
+        req: {},
+        res: { headers: { type: 'object', properties: { 'x-allowed': { type: 'string' } }, required: ['x-allowed'] } },
+      },
+    } satisfies APIHttpRouteDoc,
+  ],
+}
+
+const apiGroupNoBody: ScopeGroup = {
+  scopeKey: 'pings',
+  camelCase: 'pings',
+  routes: [
+    {
+      kind: 'api',
+      name: 'Ping',
+      path: '/ping',
+      method: 'get',
+      fullPath: '/api/ping',
+      scope: 'pings',
+      jsonSchema: { req: {}, res: {} },
+    } satisfies APIHttpRouteDoc,
+  ],
+}
+
+describe('emitScopeFile API conditional return type', () => {
+  describe('flat mode', () => {
+    it('body-only: return type is the body type', async () => {
+      const out = await emitScopeFile(apiGroupBodyOnly)
+      expect(out).toContain('export type GetReportResponseBody =')
+      expect(out).toContain('client.bindCallable<GetReportReq, GetReportResponseBody>')
+    })
+
+    it('body + headers: return type is { body; headers }', async () => {
+      const out = await emitScopeFile(apiGroupBothBodyAndHeaders)
+      expect(out).toContain('export type GetDownloadResponseBody =')
+      expect(out).toContain('export type GetDownloadResponseHeaders =')
+      expect(out).toContain('{ body: GetDownloadResponseBody; headers: GetDownloadResponseHeaders }')
+    })
+
+    it('headers-only: return type is { headers }', async () => {
+      const out = await emitScopeFile(apiGroupHeadersOnly)
+      expect(out).toContain('export type GetPreflightResponseHeaders =')
+      expect(out).toContain('{ headers: GetPreflightResponseHeaders }')
+    })
+
+    it('neither body nor headers: return type is void', async () => {
+      const out = await emitScopeFile(apiGroupNoBody)
+      expect(out).toContain('client.bindCallable<unknown, void>')
+    })
+  })
+
+  describe('namespace mode', () => {
+    it('body-only: return type references Response.Body', async () => {
+      const out = await emitScopeFile(apiGroupBodyOnly, { namespaceTypes: true })
+      expect(out).toContain('export namespace Response {')
+      expect(out).toContain('client.bindCallable<Reports.GetReport.Req, Reports.GetReport.Response.Body>')
+    })
+
+    it('body + headers: return type is { body: Response.Body; headers: Response.Headers }', async () => {
+      const out = await emitScopeFile(apiGroupBothBodyAndHeaders, { namespaceTypes: true })
+      expect(out).toContain('export namespace Response {')
+      expect(out).toContain('export type Body =')
+      expect(out).toContain('export type Headers =')
+      expect(out).toContain('{ body: Downloads.GetDownload.Response.Body; headers: Downloads.GetDownload.Response.Headers }')
+    })
+
+    it('headers-only: return type is { headers: Response.Headers }', async () => {
+      const out = await emitScopeFile(apiGroupHeadersOnly, { namespaceTypes: true })
+      expect(out).toContain('{ headers: Preflight.GetPreflight.Response.Headers }')
+    })
+
+    it('neither body nor headers: return type is void', async () => {
+      const out = await emitScopeFile(apiGroupNoBody, { namespaceTypes: true })
+      expect(out).toContain('client.bindCallable<unknown, void>')
+    })
+  })
+})
+
+describe('emitScopeFile API responseHeadersDeclared descriptor field', () => {
+  it('emits responseHeadersDeclared: true when res.headers is present', async () => {
+    const out = await emitScopeFile(apiGroupBothBodyAndHeaders)
+    expect(out).toContain('responseHeadersDeclared: true')
+  })
+
+  it('does NOT emit responseHeadersDeclared when res.headers is absent', async () => {
+    const out = await emitScopeFile(apiGroupBodyOnly)
+    expect(out).not.toContain('responseHeadersDeclared')
+  })
+})
+
+// ---------------------------------------------------------------------------
+// http-stream kind emission
+// ---------------------------------------------------------------------------
+
+const httpStreamGroup: ScopeGroup = {
+  scopeKey: 'feed',
+  camelCase: 'feed',
+  routes: [
+    {
+      kind: 'http-stream',
+      name: 'StreamFeed',
+      path: '/feed/stream',
+      method: 'get',
+      fullPath: '/api/feed/stream',
+      scope: 'feed',
+      streamMode: 'sse',
+      jsonSchema: {
+        req: {
+          query: {
+            type: 'object',
+            properties: { cursor: { type: 'string' } },
+          },
+        },
+        res: {
+          headers: {
+            type: 'object',
+            properties: { 'x-session': { type: 'string' } },
+            required: ['x-session'],
+          },
+        },
+        yield: {
+          type: 'object',
+          properties: { message: { type: 'string' } },
+          required: ['message'],
+        },
+        returnType: {
+          type: 'object',
+          properties: { total: { type: 'number' } },
+          required: ['total'],
+        },
+      },
+    } satisfies HttpStreamRouteDoc,
+  ],
+}
+
+describe('emitScopeFile http-stream kind', () => {
+  describe('flat mode', () => {
+    it('emits Req-prefixed query type', async () => {
+      const out = await emitScopeFile(httpStreamGroup)
+      expect(out).toContain('export type StreamFeedReqQuery =')
+    })
+
+    it('emits ResponseHeaders type', async () => {
+      const out = await emitScopeFile(httpStreamGroup)
+      expect(out).toContain('export type StreamFeedResponseHeaders =')
+    })
+
+    it('emits Yield and ReturnType types', async () => {
+      const out = await emitScopeFile(httpStreamGroup)
+      expect(out).toContain('export type StreamFeedYield =')
+      expect(out).toContain('export type StreamFeedReturnType =')
+    })
+
+    it('callable returns TypedStream<Yield, ReturnType>', async () => {
+      const out = await emitScopeFile(httpStreamGroup)
+      expect(out).toContain('TypedStream<StreamFeedYield, StreamFeedReturnType>')
+    })
+
+    it('callable uses kind: http-stream in descriptor', async () => {
+      const out = await emitScopeFile(httpStreamGroup)
+      expect(out).toContain("kind: 'http-stream'")
+    })
+
+    it('imports TypedStream', async () => {
+      const out = await emitScopeFile(httpStreamGroup)
+      expect(out).toContain('TypedStream')
+    })
+  })
+
+  describe('namespace mode', () => {
+    it('emits Req sub-namespace with query type', async () => {
+      const out = await emitScopeFile(httpStreamGroup, { namespaceTypes: true })
+      expect(out).toContain('export namespace Req {')
+      expect(out).toContain('export type Query =')
+    })
+
+    it('emits Response sub-namespace with Headers type', async () => {
+      const out = await emitScopeFile(httpStreamGroup, { namespaceTypes: true })
+      expect(out).toContain('export namespace Response {')
+      expect(out).toContain('export type Headers =')
+    })
+
+    it('emits Yield and ReturnType in route namespace', async () => {
+      const out = await emitScopeFile(httpStreamGroup, { namespaceTypes: true })
+      expect(out).toContain('export type Yield =')
+      expect(out).toContain('export type ReturnType =')
+    })
+
+    it('callable uses qualified Req and TypedStream types', async () => {
+      const out = await emitScopeFile(httpStreamGroup, { namespaceTypes: true })
+      expect(out).toContain('Feed.StreamFeed.Req')
+      expect(out).toContain('TypedStream<Feed.StreamFeed.Yield, Feed.StreamFeed.ReturnType>')
+    })
+  })
+})