ts-procedures 8.5.0 → 8.6.0

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/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"
+    }
 }