ts-procedures 8.5.0 → 9.0.0

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

@@ -180,6 +180,40 @@ describe('emitIndexFile', () => {
     })
   })
 
+  describe('per-scope client types (DX #15)', () => {
+    const groups = [usersGroup, billingGroup]
+
+    it('emits the aggregate client type from the factory return type', () => {
+      const out = emitIndexFile(groups, { serviceName: 'Api' })
+      expect(out).toContain('export type ApiClient = ReturnType<typeof createApiBindings>')
+    })
+
+    it('emits one per-scope client type as an indexed access into the aggregate', () => {
+      const out = emitIndexFile(groups, { serviceName: 'Api' })
+      expect(out).toContain("export type UsersClient = ApiClient['users']")
+      expect(out).toContain("export type BillingClient = ApiClient['billing']")
+    })
+
+    it('honors a custom serviceName in the client type names', () => {
+      const out = emitIndexFile(groups, { serviceName: 'Catalog' })
+      expect(out).toContain('export type CatalogClient = ReturnType<typeof createCatalogBindings>')
+      expect(out).toContain("export type UsersClient = CatalogClient['users']")
+    })
+
+    it('documents the aggregate and per-scope client types so the DI-seam intent is visible in the generated file', () => {
+      const out = emitIndexFile(groups, { serviceName: 'Api' })
+      // Aggregate type carries a one-line summary.
+      expect(out).toContain('/** Full typed client surface — every scope of `Api`. */')
+      // Each per-scope type names the scope and points at the DI use case.
+      expect(out).toContain(
+        '/** Narrow port for the `users` scope — inject as a DI seam without casting the aggregate client. */',
+      )
+      expect(out).toContain(
+        '/** Narrow port for the `billing` scope — inject as a DI seam without casting the aggregate client. */',
+      )
+    })
+  })
+
   describe('clientImportPath', () => {
     it('uses custom clientImportPath in both import statements', () => {
       const output = emitIndexFile([usersGroup], { clientImportPath: '@my-app/client' })

package/src/codegen/emit-index.ts

@@ -106,6 +106,25 @@ export function emitIndexFile(groups: ScopeGroup[], options?: EmitIndexOptions):
     '',
   ]
 
+  // Per-scope client interfaces, derived from the bindings factory's return type
+  // (DX #15). Reuses the `ReturnType<typeof factory>` pattern already used by the
+  // convenience client below. Lets a consumer type a dependency as the narrow scope
+  // port — `constructor(client: UsersClient = api.users)` — and a fake satisfies just
+  // that scope with no `as unknown as typeof api` cast. `${Service}Client` is the
+  // callable bundle; it does NOT collide with the `${Service}.<Scope>` type namespace.
+  // Each type carries a JSDoc line so the DI-seam intent is visible to a developer
+  // reading the generated file — not just in this emitter's source comment above.
+  const aggregateClientType = `${servicePascal}Client`
+  pieces.push(
+    `/** Full typed client surface — every scope of \`${servicePascal}\`. */`,
+    `export type ${aggregateClientType} = ReturnType<typeof ${factoryName}>`,
+    ...groups.flatMap((g) => [
+      `/** Narrow port for the \`${g.camelCase}\` scope — inject as a DI seam without casting the aggregate client. */`,
+      `export type ${toPascalCase(g.camelCase)}Client = ${aggregateClientType}['${g.camelCase}']`,
+    ]),
+    '',
+  )
+
   // `createApiClient` is a convenience wrapper that wires `createClient` with
   // the generated error registry baked in, then invokes the bindings factory.
   // Consumers that want manual control over `createClient` still use the

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

@@ -1,7 +1,7 @@
 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'
+import type { RPCHttpRouteDoc, APIHttpRouteDoc, StreamHttpRouteDoc } from '../server/types.js'
 
 // ---------------------------------------------------------------------------
 // Fixtures
@@ -1151,7 +1151,7 @@ describe('emitScopeFile streams omit .safe sibling', () => {
 // API conditional return type (body-only, headers-only, both, void)
 // ---------------------------------------------------------------------------
 
-import type { HttpStreamRouteDoc } from '../implementations/types.js'
+import type { HttpStreamRouteDoc } from '../server/types.js'
 
 const apiGroupBodyOnly: ScopeGroup = {
   scopeKey: 'reports',
@@ -1250,9 +1250,10 @@ describe('emitScopeFile API conditional return type', () => {
       expect(out).toContain('{ headers: GetPreflightResponseHeaders }')
     })
 
-    it('neither body nor headers: return type is void', async () => {
+    it('neither body nor headers: param type is void, return type is void', async () => {
       const out = await emitScopeFile(apiGroupNoBody)
-      expect(out).toContain('client.bindCallable<unknown, void>')
+      expect(out).toContain('client.bindCallable<void, void>')
+      expect(out).not.toContain('client.bindCallable<unknown,')
     })
   })
 
@@ -1276,9 +1277,9 @@ describe('emitScopeFile API conditional return type', () => {
       expect(out).toContain('{ headers: Preflight.GetPreflight.Response.Headers }')
     })
 
-    it('neither body nor headers: return type is void', async () => {
+    it('neither body nor headers: param type is void, return type is void', async () => {
       const out = await emitScopeFile(apiGroupNoBody, { namespaceTypes: true })
-      expect(out).toContain('client.bindCallable<unknown, void>')
+      expect(out).toContain('client.bindCallable<void, void>')
     })
   })
 })
@@ -1586,3 +1587,92 @@ describe('emitScopeFile http-stream kind', () => {
     })
   })
 })
+
+// Input-less RPC (no body) and stream (no params) — exercise the void-param fallback
+// across the RPC and stream emission paths, not just API.
+const rpcGroupNoInput: ScopeGroup = {
+  scopeKey: 'session',
+  camelCase: 'session',
+  routes: [
+    {
+      kind: 'rpc',
+      name: 'Logout',
+      path: '/session/logout',
+      method: 'post',
+      scope: 'session',
+      version: 1,
+      jsonSchema: {
+        response: { type: 'object', properties: { ok: { type: 'boolean' } }, required: ['ok'] },
+      },
+    } satisfies RPCHttpRouteDoc,
+  ],
+}
+
+const streamGroupNoParams: ScopeGroup = {
+  scopeKey: 'ticks',
+  camelCase: 'ticks',
+  routes: [
+    {
+      kind: 'stream',
+      name: 'WatchTicks',
+      path: '/ticks/stream',
+      methods: ['get'],
+      streamMode: 'sse',
+      scope: 'ticks',
+      version: 1,
+      jsonSchema: {
+        params: undefined,
+        yieldType: { type: 'object', properties: { n: { type: 'number' } }, required: ['n'] },
+        returnType: undefined,
+      },
+    } satisfies StreamHttpRouteDoc,
+  ],
+}
+
+describe('emitScopeFile input-less routes (void params)', () => {
+  it('RPC route with no body emits void as the params type arg', async () => {
+    const out = await emitScopeFile(rpcGroupNoInput)
+    expect(out).toContain('client.bindCallable<void,')
+    expect(out).not.toContain('client.bindCallable<unknown,')
+  })
+
+  it('stream route with no params emits void as the params type', async () => {
+    const out = await emitScopeFile(streamGroupNoParams)
+    // Stream callables are direct methods: WatchTicks(params: void, options?)
+    expect(out).toContain('WatchTicks(params: void')
+    expect(out).not.toContain('WatchTicks(params: unknown')
+  })
+})
+
+describe('emitScopeFile callable JSDoc surfaces options + errors', () => {
+  it('mentions the per-call options bag on an RPC callable', async () => {
+    const out = await emitScopeFile(rpcGroup)
+    expect(out).toContain('POST') // existing method label preserved
+    expect(out).toContain('@param options')
+    expect(out).toContain('ProcedureCallOptions')
+    expect(out).toContain('signal')
+  })
+
+  it('mentions declared errors + Scope.Route.Errors on a route with errors (namespace)', async () => {
+    const out = await emitScopeFile(rpcGroupWithErrors, {
+      namespaceTypes: true,
+      errorKeys: new Set(['NotFound']),
+      serviceName: 'Api',
+    })
+    expect(out).toContain('@throws')
+    expect(out).toContain('Users.GetUser.Errors')
+    expect(out).toContain('instanceof')
+  })
+
+  it('omits the @throws line when a route declares no errors', async () => {
+    const out = await emitScopeFile(rpcGroupNoErrors, { serviceName: 'Api' })
+    expect(out).not.toContain('@throws')
+    expect(out).toContain('@param options') // options line still present
+  })
+
+  it('mentions options on a stream callable but no @throws', async () => {
+    const out = await emitScopeFile(streamGroup)
+    expect(out).toContain('@param options')
+    expect(out).not.toContain('@throws')
+  })
+})