ts-procedures 8.4.0 → 8.6.0

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

@@ -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')
+  })
+})

package/src/codegen/emit-scope.ts

@@ -387,6 +387,35 @@ function injectRouteErrors(
 // Route emitters
 // ---------------------------------------------------------------------------
 
+/**
+ * Builds the multi-line JSDoc comment for a route callable. Surfaces the
+ * second `options` argument (the per-call AbortSignal/timeout seam — DX #8) and,
+ * for routes that declare typed errors, points at the route's `Errors` type and
+ * how to narrow it on the throwing path (DX #10). Indented for placement inside
+ * the bind-object (4 spaces).
+ */
+function buildCallableJsDoc(opts: {
+  methodLabel: string
+  path: string
+  errorsRef: string | null
+}): string {
+  const lines = [
+    `    /**`,
+    `     * ${opts.methodLabel} ${opts.path}`,
+    `     *`,
+    `     * @param options Optional per-call {@link ProcedureCallOptions} —`,
+    `     *   \`signal\` (cancel on dispose), \`timeout\`, \`headers\`, \`basePath\`.`,
+  ]
+  if (opts.errorsRef) {
+    lines.push(
+      `     * @throws Declared typed errors: {@link ${opts.errorsRef}}. Narrow with`,
+      `     *   \`instanceof\` on the throwing path, or call \`.safe()\` for a \`Result\`.`,
+    )
+  }
+  lines.push(`     */`)
+  return lines.join('\n')
+}
+
 async function emitRpcRoute(route: RPCHttpRouteDoc, ctx: EmitRouteContext): Promise<RouteChunks> {
   const pascal = versionedPascal(route.name, route.version)
 
@@ -395,7 +424,7 @@ async function emitRpcRoute(route: RPCHttpRouteDoc, ctx: EmitRouteContext): Prom
     { shortName: 'Response', schema: route.jsonSchema.response },
   ], ctx)
 
-  const paramsTypeName = refs['Params'] ?? 'unknown'
+  const paramsTypeName = refs['Params'] ?? 'void'
   const responseTypeName = refs['Response'] ?? 'unknown'
   const scopeStr = Array.isArray(route.scope) ? route.scope.join('-') : route.scope
 
@@ -409,7 +438,11 @@ async function emitRpcRoute(route: RPCHttpRouteDoc, ctx: EmitRouteContext): Prom
     : `client.bindCallable<${paramsTypeName}, ${responseTypeName}>`
 
   const callable = [
-    `    /** ${route.method.toUpperCase()} ${route.path} */`,
+    buildCallableJsDoc({
+      methodLabel: route.method.toUpperCase(),
+      path: route.path,
+      errorsRef: hasErrors ? errorsRef : null,
+    }),
     `    ${pascal}: ${helperCall}({`,
     `      name: '${pascal}',`,
     `      scope: '${scopeStr}',`,
@@ -533,7 +566,7 @@ async function emitApiRoute(route: APIHttpRouteDoc, ctx: EmitRouteContext): Prom
     : `${pascal}Errors`
 
   const declarations: string[] = []
-  let paramsTypeName = 'unknown'
+  let paramsTypeName = 'void'
   let returnTypeName = 'void'
 
   // Track reserved names across all sub-namespaces. Model names are reserved
@@ -638,7 +671,11 @@ async function emitApiRoute(route: APIHttpRouteDoc, ctx: EmitRouteContext): Prom
   ]
 
   const callable = [
-    `    /** ${route.method.toUpperCase()} ${route.fullPath} */`,
+    buildCallableJsDoc({
+      methodLabel: route.method.toUpperCase(),
+      path: route.fullPath,
+      errorsRef: hasErrors ? errorsRef : null,
+    }),
     `    ${route.name}: ${helperCall}({`,
     ...descriptorLines,
     `    }),`,
@@ -676,7 +713,7 @@ async function emitHttpStreamRoute(route: HttpStreamRouteDoc, ctx: EmitRouteCont
 
   const scopeStr = route.scope ?? 'default'
   const declarations: string[] = []
-  let paramsTypeName = 'unknown'
+  let paramsTypeName = 'void'
   let yieldTypeName = 'unknown'
   let returnTypeName = 'void'
 
@@ -774,7 +811,11 @@ async function emitHttpStreamRoute(route: HttpStreamRouteDoc, ctx: EmitRouteCont
   }
 
   const callable = [
-    `    /** ${route.method.toUpperCase()} ${route.fullPath} */`,
+    buildCallableJsDoc({
+      methodLabel: route.method.toUpperCase(),
+      path: route.fullPath,
+      errorsRef: null,
+    }),
     `    ${route.name}(req: ${paramsTypeName}, options?: ProcedureCallOptions): TypedStream<${yieldTypeName}, ${returnTypeName}> {`,
     `      return client.stream<${yieldTypeName}, ${returnTypeName}>({`,
     `        name: '${route.name}',`,
@@ -813,13 +854,17 @@ async function emitStreamRoute(route: StreamHttpRouteDoc, ctx: EmitRouteContext)
     { shortName: 'Return', schema: route.jsonSchema.returnType },
   ], ctx)
 
-  const paramsTypeName = refs['Params'] ?? 'unknown'
+  const paramsTypeName = refs['Params'] ?? 'void'
   const yieldTypeName = refs['Yield'] ?? 'unknown'
   const returnTypeName = refs['Return'] ?? 'void'
   const scopeStr = Array.isArray(route.scope) ? route.scope.join('-') : route.scope
 
   const callable = [
-    `    /** ${route.methods.map((m) => m.toUpperCase()).join('|')} ${route.path} */`,
+    buildCallableJsDoc({
+      methodLabel: route.methods.map((m) => m.toUpperCase()).join('|'),
+      path: route.path,
+      errorsRef: null,
+    }),
     `    ${pascal}(params: ${paramsTypeName}, options?: ProcedureCallOptions): TypedStream<${yieldTypeName}, ${returnTypeName}> {`,
     `      return client.stream<${yieldTypeName}, ${returnTypeName}>({`,
     `        name: '${pascal}',`,

package/src/codegen/index.ts

@@ -18,6 +18,16 @@ export interface GenerateClientOptions extends ResolveInput {
   shareModels?: boolean
   /** Maps a model `$id` to an external import so a shared model is re-exported rather than generated. */
   sharedTypesImport?: SharedTypesImportMap
+  /** Single module every $id-bearing model re-exports from (convention; `sharedTypesImport` entries override). */
+  sharedModelsModule?: string
+  /** Hard-fail codegen if any $id-bearing model would be generated as a local structural twin. */
+  strictSharedModels?: boolean
+  /**
+   * Sink for non-error progress messages (e.g. the shared-models summary).
+   * Omitted by default so programmatic callers produce no console output; pass
+   * `console.log` to opt in. The CLI wires this to stdout.
+   */
+  logger?: (message: string) => void
   target?: 'ts' | 'kotlin' | 'swift'
   kotlinPackage?: string
   kotlinSerializer?: 'kotlinx' | 'none'
@@ -44,6 +54,9 @@ export async function generateClient(options: GenerateClientOptions): Promise<Ge
     cleanOutDir: options.cleanOutDir,
     shareModels: options.shareModels,
     sharedTypesImport: options.sharedTypesImport,
+    sharedModelsModule: options.sharedModelsModule,
+    strictSharedModels: options.strictSharedModels,
+    logger: options.logger,
     target: options.target,
     kotlinPackage: options.kotlinPackage,
     kotlinSerializer: options.kotlinSerializer,

package/src/codegen/pipeline.ts

@@ -23,6 +23,10 @@ export interface PipelineOptions {
   cleanOutDir?: boolean
   shareModels?: boolean
   sharedTypesImport?: SharedTypesImportMap
+  sharedModelsModule?: string
+  strictSharedModels?: boolean
+  /** Sink for non-error progress messages (shared-models summary). Defaults to silent. */
+  logger?: (message: string) => void
   target?: 'ts' | 'kotlin' | 'swift'
   kotlinPackage?: string
   kotlinSerializer?: 'kotlinx' | 'none'
@@ -72,6 +76,9 @@ export async function runPipeline(options: PipelineOptions): Promise<GeneratedFi
     cleanOutDir,
     shareModels,
     sharedTypesImport: options.sharedTypesImport,
+    sharedModelsModule: options.sharedModelsModule,
+    strictSharedModels: options.strictSharedModels,
+    logger: options.logger,
   }
 
   switch (options.target) {

package/src/codegen/targets/_shared/target-run.ts

@@ -30,4 +30,14 @@ export interface TargetRunInput {
   shareModels?: boolean
   /** Maps a model `$id` to an external import (re-exported instead of generated). */
   sharedTypesImport?: SharedTypesImportMap
+  /** Single module every $id-bearing model re-exports from (convention; map entries override). */
+  sharedModelsModule?: string
+  /** When true, hard-fail if any $id-bearing model has no shared-type mapping (would be a local twin). */
+  strictSharedModels?: boolean
+  /**
+   * Sink for non-error progress messages (e.g. the shared-models summary).
+   * Defaults to undefined — programmatic callers stay silent; the CLI injects
+   * `console.log`. Output belongs to the caller, not the run module.
+   */
+  logger?: (message: string) => void
 }

package/src/codegen/targets/kotlin/__fixtures__/users-golden.kt

@@ -192,4 +192,10 @@ object Users {
             val count: Long,
         )
     }
+
+    object Heartbeat {
+        const val method = "GET"
+        const val pathTemplate = "/users/heartbeat"
+        const val path = "/users/heartbeat"
+    }
 }

package/src/codegen/targets/swift/__fixtures__/users-golden.swift

@@ -199,4 +199,10 @@ public enum Users {
             public let count: Int64
         }
     }
+
+    public enum Heartbeat {
+        public static let method = "GET"
+        public static let pathTemplate = "/users/heartbeat"
+        public static let path = "/users/heartbeat"
+    }
 }

package/src/codegen/targets/ts/run.ts

@@ -33,6 +33,9 @@ export async function runTsPipeline(input: TsRunInput): Promise<GeneratedFile[]>
     selfContained = false,
     cleanOutDir = false,
     sharedTypesImport,
+    sharedModelsModule,
+    strictSharedModels = false,
+    logger,
   } = input
   const shareModels = input.shareModels ?? false
 
@@ -60,7 +63,7 @@ export async function runTsPipeline(input: TsRunInput): Promise<GeneratedFile[]>
   // covers ALL models (generated AND externally-imported) since scopes always
   // import shared types from `./_models`.
   const models = shareModels
-    ? resolveModelImports(collectModels(envelope.routes), sharedTypesImport)
+    ? resolveModelImports(collectModels(envelope.routes), { sharedTypesImport, sharedModelsModule })
     : []
   const idToModelName = new Map(models.map((m) => [m.id, m.name]))
 
@@ -74,6 +77,20 @@ export async function runTsPipeline(input: TsRunInput): Promise<GeneratedFile[]>
     }
   }
 
+  if (shareModels && models.length > 0) {
+    const generated = models.filter((m) => m.import == null)
+    if (strictSharedModels && generated.length > 0) {
+      const list = generated.map((m) => `"${m.id}" (${m.name})`).join(', ')
+      throw new Error(
+        `[ts-procedures-codegen] --strict-shared-models: ${generated.length} $id-bearing schema(s) have no shared-type mapping and would be generated as local structural twins: ${list}. Add a sharedTypesImport entry, set sharedModelsModule, or drop --strict-shared-models.`,
+      )
+    }
+    const reExported = models.length - generated.length
+    logger?.(
+      `[ts-procedures-codegen] Shared models: ${models.length} total — ${reExported} re-exported, ${generated.length} generated locally.`,
+    )
+  }
+
   const files: GeneratedFile[] = []
 
   for (const group of groups) {

package/src/codegen/targets/ts/shared-models.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect } from 'vitest'
+import { describe, it, expect, vi } from 'vitest'
 import { runPipeline } from '../../pipeline.js'
 import type { DocEnvelope } from '../../../implementations/types.js'
 import type { GeneratedFile } from '../_shared/write-files.js'
@@ -233,6 +233,114 @@ describe('shared models (TS target, ajsc x-named-type)', () => {
     expect(messages.code).toContain("import type { Message } from './_models'")
   })
 
+  it('sharedModelsModule re-exports every $id model from the convention module', async () => {
+    const files = await runPipeline({
+      envelope: modelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: true,
+      namespaceTypes: true,
+      selfContained: false,
+      sharedModelsModule: '@app/schemas',
+    })
+
+    const modelsFile = findFile(files, '_models.ts')!
+    // Re-exported, not generated.
+    expect(modelsFile.code).toContain("export { Message } from '@app/schemas'")
+    expect(countMatches(modelsFile.code, /export type Message =/g)).toBe(0)
+
+    // Scopes still import the shared name from ./_models.
+    expect(findFile(files, 'messages.ts')!.code).toContain("from './_models'")
+  })
+
+  it('explicit sharedTypesImport overrides the sharedModelsModule convention per $id', async () => {
+    const files = await runPipeline({
+      envelope: modelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: true,
+      namespaceTypes: true,
+      selfContained: false,
+      sharedModelsModule: '@app/schemas',
+      sharedTypesImport: { 'urn:msg': { module: '@override/pkg', name: 'Message' } },
+    })
+    expect(findFile(files, '_models.ts')!.code).toContain("export { Message } from '@override/pkg'")
+  })
+
+  it('emits a neutral summary of the re-exported / generated split via the injected logger', async () => {
+    const lines: string[] = []
+    await runPipeline({
+      envelope: modelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: true,
+      namespaceTypes: true,
+      selfContained: false,
+      logger: (m) => lines.push(m),
+    })
+    expect(lines.join('\n')).toContain('Shared models: 1 total — 0 re-exported, 1 generated locally.')
+  })
+
+  it('does not emit a summary when there are no $id-bearing models', async () => {
+    const lines: string[] = []
+    await runPipeline({
+      envelope: noModelEnvelope(),
+      outDir: 'out',
+      dryRun: true,
+      shareModels: true,
+      namespaceTypes: true,
+      selfContained: false,
+      logger: (m) => lines.push(m),
+    })
+    expect(lines.join('\n')).not.toContain('Shared models:')
+  })
+
+  it('stays silent (no console output) when no logger is injected', async () => {
+    const log = vi.spyOn(console, 'log').mockImplementation(() => {})
+    try {
+      await runPipeline({
+        envelope: modelEnvelope(),
+        outDir: 'out',
+        dryRun: true,
+        shareModels: true,
+        namespaceTypes: true,
+        selfContained: false,
+      })
+      expect(log.mock.calls.flat().join('\n')).not.toContain('Shared models:')
+    } finally {
+      log.mockRestore()
+    }
+  })
+
+  it('strictSharedModels throws listing the offending $id and derived name', async () => {
+    await expect(
+      runPipeline({
+        envelope: modelEnvelope(),
+        outDir: 'out',
+        dryRun: true,
+        shareModels: true,
+        namespaceTypes: true,
+        selfContained: false,
+        strictSharedModels: true,
+      }),
+    ).rejects.toThrow(/--strict-shared-models[\s\S]*urn:msg[\s\S]*Message/)
+  })
+
+  it('strictSharedModels passes once every model is covered by the convention', async () => {
+    await expect(
+      runPipeline({
+        envelope: modelEnvelope(),
+        outDir: 'out',
+        dryRun: true,
+        shareModels: true,
+        namespaceTypes: true,
+        selfContained: false,
+        strictSharedModels: true,
+        sharedModelsModule: '@app/schemas',
+      }),
+    ).resolves.toBeDefined()
+  })
+
   it('fails loudly when a shared model name collides with a property-derived sub-type', async () => {
     // `latest` references the Message model; a sibling property literally named
     // `message` would make ajsc extract a structural sub-type ALSO named