npm - ts-procedures - Versions diffs - 7.3.0 → 8.0.0 - Mend

ts-procedures 7.3.0 → 8.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (325) hide show

package/src/codegen/emit-scope.ts CHANGED Viewed

@@ -3,6 +3,7 @@ import type {
   RPCHttpRouteDoc,
   APIHttpRouteDoc,
   StreamHttpRouteDoc,
+  HttpStreamRouteDoc,
 } from '../implementations/types.js'
 import {
   jsonSchemaToTypeString,
@@ -58,7 +59,8 @@ interface EmitRouteContext {
  * This provides backward compatibility with servers running older ts-procedures
  * versions that don't set `kind` on route docs.
  */
-function inferRouteKind(route: Record<string, unknown>): 'rpc' | 'api' | 'stream' {
+function inferRouteKind(route: Record<string, unknown>): 'rpc' | 'api' | 'stream' | 'http-stream' {
+  if ('streamMode' in route && 'fullPath' in route) return 'http-stream'
   if ('streamMode' in route) return 'stream'
   if ('fullPath' in route) return 'api'
   return 'rpc'
@@ -291,92 +293,383 @@ async function emitRpcRoute(route: RPCHttpRouteDoc, ctx: EmitRouteContext): Prom
   return { typeDeclarations: declarations, callable, hasStream: false, hasErrors: hasErrorsInjected }
 }
+/**
+ * Formats a group of named types into a nested sub-namespace block (for namespace mode).
+ * Returns an array of lines to be inserted into the parent namespace, and a map of
+ * shortName → qualified type reference for use in callables.
+ *
+ * In flat mode, returns declarations like `export type ${prefix}${shortName} = ...`
+ * and refs like `${prefix}${shortName}`.
+ */
+async function formatSubNamespace(
+  routePascal: string,
+  nsName: string,           // e.g. 'Req' or 'Response'
+  types: NamedType[],
+  ctx: EmitRouteContext,
+  taken: Set<string>,
+): Promise<{ nsBlock: string | null; refs: Record<string, string> }> {
+  const refs: Record<string, string> = {}
+  const nsLines: string[] = []
+  const seenDeclarations = new Set<string>()
+  // Pre-reserve short names to prevent sub-type extraction collision
+  for (const t of types) {
+    if (t.schema != null) taken.add(t.shortName)
+  }
+  for (const { shortName, schema } of types) {
+    if (schema == null) continue
+    if (ctx.namespaceTypes) {
+      const rawResult = await jsonSchemaToExtractedTypes(schema, ctx.ajsc)
+      if (rawResult == null) continue
+      const result = renameExtractedTypes(rawResult, taken)
+      for (const decl of result.declarations) {
+        if (!seenDeclarations.has(decl)) {
+          seenDeclarations.add(decl)
+          nsLines.push(indent(decl, '      '))
+        }
+      }
+      nsLines.push(`      export type ${shortName} = ${result.body}`)
+      refs[shortName] = `${ctx.scopePascal}.${routePascal}.${nsName}.${shortName}`
+    } else {
+      const flatName = `${routePascal}${nsName}${shortName}`
+      const body = await jsonSchemaToTypeBody(schema, ctx.ajsc)
+      if (body == null) continue
+      refs[shortName] = flatName
+    }
+  }
+  if (ctx.namespaceTypes) {
+    if (nsLines.length === 0) return { nsBlock: null, refs }
+    const nsBlock = `    export namespace ${nsName} {\n${nsLines.join('\n')}\n    }`
+    return { nsBlock, refs }
+  }
+  return { nsBlock: null, refs }
+}
+/**
+ * Builds the conditional return type string for an API or http-stream callable.
+ *
+ * - Both body + headers → `{ body: <Body>; headers: <Headers> }`
+ * - Only body           → `<Body>`
+ * - Only headers        → `{ headers: <Headers> }`
+ * - Neither             → `void`
+ */
+function buildApiReturnType(
+  bodyRef: string | undefined,
+  headersRef: string | undefined,
+): string {
+  if (bodyRef && headersRef) {
+    return `{ body: ${bodyRef}; headers: ${headersRef} }`
+  }
+  if (bodyRef) return bodyRef
+  if (headersRef) return `{ headers: ${headersRef} }`
+  return 'void'
+}
 async function emitApiRoute(route: APIHttpRouteDoc, ctx: EmitRouteContext): Promise<RouteChunks> {
   const pascal = toPascalCase(route.name)
-  const channelKeys = ['pathParams', 'query', 'body', 'headers'] as const
+  const req = route.jsonSchema.req ?? {}
+  const res = route.jsonSchema.res ?? {}
-  // Build channel types + structured Params type
-  const channelTypes: NamedType[] = []
+  // Request channels
+  const reqChannelKeys = ['pathParams', 'query', 'body', 'headers'] as const
+  const reqTypes: NamedType[] = []
   const presentChannels: string[] = []
-  for (const channel of channelKeys) {
-    const channelSchema = route.jsonSchema[channel]
-    if (channelSchema != null) {
-      channelTypes.push({ shortName: toPascalCase(channel), schema: channelSchema })
+  for (const channel of reqChannelKeys) {
+    const schema = req[channel]
+    if (schema != null) {
+      reqTypes.push({ shortName: toPascalCase(channel), schema })
       presentChannels.push(channel)
     }
   }
-  // Add response
-  channelTypes.push({ shortName: 'Response', schema: route.jsonSchema.response })
+  // Response slots
+  const resTypes: NamedType[] = [
+    { shortName: 'Body', schema: res.body },
+    { shortName: 'Headers', schema: res.headers },
+  ]
-  // `Params` is injected into the namespace below (after formatTypes), so
-  // reserve it up-front to keep ajsc-extracted sub-types from shadowing it.
-  const { declarations, refs } = await formatTypes(
-    pascal,
-    channelTypes,
-    ctx,
-    new Set(['Params']),
-  )
+  const scopeStr = route.scope ?? 'default'
+  const errorUnion = buildErrorUnion(route.errors, ctx)
+  const hasErrors = errorUnion !== null
+  const errorsRef = ctx.namespaceTypes
+    ? `${ctx.scopePascal}.${pascal}.Errors`
+    : `${pascal}Errors`
-  // Compose structured Params type from channels
+  const declarations: string[] = []
   let paramsTypeName = 'unknown'
-  if (presentChannels.length > 0) {
-    if (ctx.namespaceTypes) {
-      const structureFields = presentChannels
-        .map((ch) => `${ch}: ${toPascalCase(ch)}`)
+  let returnTypeName = 'void'
+  // Track reserved names across all sub-namespaces
+  const taken = new Set<string>(['Req', 'Response'])
+  if (ctx.namespaceTypes) {
+    // Namespace mode: emit nested Req {} and Response {} namespaces inside route namespace.
+    // Also emit merged type aliases `export type Req = { ... }` and `export type Response = ...`
+    // so they can be used as type arguments to bindCallable (TS requires a TYPE, not a namespace).
+    const nsLines: string[] = []
+    const { nsBlock: reqBlock, refs: reqRefs } = await formatSubNamespace(
+      pascal, 'Req', reqTypes, ctx, taken
+    )
+    if (reqBlock) {
+      nsLines.push(reqBlock)
+      // Merged type alias for Req so it can be used as a generic type arg
+      const reqFields = presentChannels
+        .map((ch) => `${ch}: Req.${toPascalCase(ch)}`)
         .join('; ')
-      // Insert Params type into the namespace block (before closing brace)
-      const lastIdx = declarations.length - 1
-      if (lastIdx >= 0) {
-        const lastDecl = declarations[lastIdx]!
-        const closingIdx = lastDecl.lastIndexOf('  }')
-        if (closingIdx !== -1) {
-          declarations[lastIdx] =
-            lastDecl.slice(0, closingIdx) +
-            `    export type Params = { ${structureFields} }\n` +
-            lastDecl.slice(closingIdx)
-        }
-      }
-      paramsTypeName = `${ctx.scopePascal}.${pascal}.Params`
-    } else {
+      nsLines.push(`    export type Req = { ${reqFields} }`)
+    }
+    const { nsBlock: resBlock, refs: resRefs } = await formatSubNamespace(
+      pascal, 'Response', resTypes, ctx, taken
+    )
+    if (resBlock) {
+      nsLines.push(resBlock)
+      // No merged Response type alias needed: we reference Response.Body / Response.Headers
+      // directly in the return type string, which are namespace-qualified paths (valid).
+    }
+    // Emit Errors type last (injected by injectRouteErrors below)
+    // Build the route namespace block
+    if (nsLines.length > 0) {
+      declarations.push(`  export namespace ${pascal} {\n${nsLines.join('\n\n')}\n  }`)
+    }
+    // Params type: use the merged Req type alias
+    if (presentChannels.length > 0) {
+      paramsTypeName = `${ctx.scopePascal}.${pascal}.Req`
+    }
+    // Return type
+    const bodyRef = resRefs['Body']
+    const headersRef = resRefs['Headers']
+    returnTypeName = buildApiReturnType(bodyRef, headersRef)
+  } else {
+    // Flat mode: emit individual types prefixed with route + sub-namespace name
+    for (const { shortName, schema } of reqTypes) {
+      if (schema == null) continue
+      const flatName = `${pascal}Req${shortName}`
+      const body = await jsonSchemaToTypeBody(schema, ctx.ajsc)
+      if (body == null) continue
+      declarations.push(`export type ${flatName} = ${body}`)
+    }
+    // Flat mode: compose structured Req type
+    if (presentChannels.length > 0) {
       const structureFields = presentChannels
-        .map((ch) => `${ch}: ${refs[toPascalCase(ch)]}`)
+        .map((ch) => `${ch}: ${pascal}Req${toPascalCase(ch)}`)
         .join('; ')
-      declarations.push(`export type ${pascal}Params = { ${structureFields} }`)
-      paramsTypeName = `${pascal}Params`
+      declarations.push(`export type ${pascal}Req = { ${structureFields} }`)
+      paramsTypeName = `${pascal}Req`
     }
-  }
-  const responseTypeName = refs['Response'] ?? 'unknown'
-  const scopeStr = route.scope ?? 'default'
+    // Flat mode: emit response types
+    let bodyRef: string | undefined
+    let headersRef: string | undefined
-  const errorUnion = buildErrorUnion(route.errors, ctx)
-  const hasErrors = errorUnion !== null
-  const errorsRef = ctx.namespaceTypes
-    ? `${ctx.scopePascal}.${pascal}.Errors`
-    : `${pascal}Errors`
+    for (const { shortName, schema } of resTypes) {
+      if (schema == null) continue
+      const flatName = `${pascal}Response${shortName}`
+      const body = await jsonSchemaToTypeBody(schema, ctx.ajsc)
+      if (body == null) continue
+      declarations.push(`export type ${flatName} = ${body}`)
+      if (shortName === 'Body') bodyRef = flatName
+      if (shortName === 'Headers') headersRef = flatName
+    }
+    returnTypeName = buildApiReturnType(bodyRef, headersRef)
+    // Flat mode errors
+    if (errorUnion) {
+      declarations.push(`export type ${pascal}Errors = ${errorUnion}`)
+    }
+  }
+  const responseHeadersDeclared = res.headers != null
   const helperCall = hasErrors
-    ? `client.bindCallableTyped<${paramsTypeName}, ${responseTypeName}, ${errorsRef}>`
-    : `client.bindCallable<${paramsTypeName}, ${responseTypeName}>`
+    ? `client.bindCallableTyped<${paramsTypeName}, ${returnTypeName}, ${errorsRef}>`
+    : `client.bindCallable<${paramsTypeName}, ${returnTypeName}>`
-  // Property key uses route.name verbatim (preserving the prior API emission contract).
-  const callable = [
-    `    /** ${route.method.toUpperCase()} ${route.fullPath} */`,
-    `    ${route.name}: ${helperCall}({`,
+  const descriptorLines = [
     `      name: '${route.name}',`,
     `      scope: '${scopeStr}',`,
     `      path: '${route.fullPath}',`,
     `      method: '${route.method}',`,
     `      kind: 'api',`,
+    ...(responseHeadersDeclared ? [`      responseHeadersDeclared: true,`] : []),
+  ]
+  const callable = [
+    `    /** ${route.method.toUpperCase()} ${route.fullPath} */`,
+    `    ${route.name}: ${helperCall}({`,
+    ...descriptorLines,
     `    }),`,
   ].join('\n')
-  const hasErrorsInjected = injectRouteErrors(declarations, pascal, errorUnion, ctx.namespaceTypes)
+  const hasErrorsInjected = ctx.namespaceTypes
+    ? injectRouteErrors(declarations, pascal, errorUnion, ctx.namespaceTypes)
+    : errorUnion !== null  // flat mode already emitted errors above
   return { typeDeclarations: declarations, callable, hasStream: false, hasErrors: hasErrorsInjected }
 }
+async function emitHttpStreamRoute(route: HttpStreamRouteDoc, ctx: EmitRouteContext): Promise<RouteChunks> {
+  const pascal = toPascalCase(route.name)
+  const req = route.jsonSchema.req ?? {}
+  const res = route.jsonSchema.res ?? {}
+  // Request channels
+  const reqChannelKeys = ['pathParams', 'query', 'body', 'headers'] as const
+  const reqTypes: NamedType[] = []
+  const presentChannels: string[] = []
+  for (const channel of reqChannelKeys) {
+    const schema = req[channel]
+    if (schema != null) {
+      reqTypes.push({ shortName: toPascalCase(channel), schema })
+      presentChannels.push(channel)
+    }
+  }
+  // Yield + ReturnType
+  const yieldSchema = route.jsonSchema.yield
+  const returnSchema = route.jsonSchema.returnType
+  const resHeadersSchema = res.headers
+  const scopeStr = route.scope ?? 'default'
+  const declarations: string[] = []
+  let paramsTypeName = 'unknown'
+  let yieldTypeName = 'unknown'
+  let returnTypeName = 'void'
+  const taken = new Set<string>(['Req', 'Response', 'Yield', 'ReturnType'])
+  if (ctx.namespaceTypes) {
+    const nsLines: string[] = []
+    // Req sub-namespace
+    const { nsBlock: reqBlock, refs: reqRefs } = await formatSubNamespace(
+      pascal, 'Req', reqTypes, ctx, taken
+    )
+    if (reqBlock) {
+      nsLines.push(reqBlock)
+      // Merged type alias so Req can be used as a generic type arg (same pattern as emitApiRoute)
+      const reqFields = presentChannels
+        .map((ch) => `${ch}: Req.${toPascalCase(ch)}`)
+        .join('; ')
+      nsLines.push(`    export type Req = { ${reqFields} }`)
+    }
+    // Response sub-namespace (headers only for http-stream)
+    const resTypes: NamedType[] = [{ shortName: 'Headers', schema: resHeadersSchema }]
+    const { nsBlock: resBlock } = await formatSubNamespace(
+      pascal, 'Response', resTypes, ctx, taken
+    )
+    if (resBlock) nsLines.push(resBlock)
+    // Yield and ReturnType directly in the route namespace
+    const directTypes: NamedType[] = [
+      { shortName: 'Yield', schema: yieldSchema },
+      { shortName: 'ReturnType', schema: returnSchema },
+    ]
+    const seenDeclarations = new Set<string>()
+    for (const { shortName, schema } of directTypes) {
+      if (schema == null) continue
+      const rawResult = await jsonSchemaToExtractedTypes(schema, ctx.ajsc)
+      if (rawResult == null) continue
+      const result = renameExtractedTypes(rawResult, taken)
+      for (const decl of result.declarations) {
+        if (!seenDeclarations.has(decl)) {
+          seenDeclarations.add(decl)
+          nsLines.push(indent(decl, '    '))
+        }
+      }
+      nsLines.push(`    export type ${shortName} = ${result.body}`)
+    }
+    if (nsLines.length > 0) {
+      declarations.push(`  export namespace ${pascal} {\n${nsLines.join('\n')}\n  }`)
+    }
+    if (presentChannels.length > 0) {
+      paramsTypeName = `${ctx.scopePascal}.${pascal}.Req`
+    }
+    if (yieldSchema != null) yieldTypeName = `${ctx.scopePascal}.${pascal}.Yield`
+    if (returnSchema != null) returnTypeName = `${ctx.scopePascal}.${pascal}.ReturnType`
+  } else {
+    // Flat mode
+    for (const { shortName, schema } of reqTypes) {
+      if (schema == null) continue
+      const flatName = `${pascal}Req${shortName}`
+      const body = await jsonSchemaToTypeBody(schema, ctx.ajsc)
+      if (body == null) continue
+      declarations.push(`export type ${flatName} = ${body}`)
+    }
+    if (presentChannels.length > 0) {
+      const structureFields = presentChannels
+        .map((ch) => `${ch}: ${pascal}Req${toPascalCase(ch)}`)
+        .join('; ')
+      declarations.push(`export type ${pascal}Req = { ${structureFields} }`)
+      paramsTypeName = `${pascal}Req`
+    }
+    if (resHeadersSchema != null) {
+      const body = await jsonSchemaToTypeBody(resHeadersSchema, ctx.ajsc)
+      if (body != null) declarations.push(`export type ${pascal}ResponseHeaders = ${body}`)
+    }
+    if (yieldSchema != null) {
+      const body = await jsonSchemaToTypeBody(yieldSchema, ctx.ajsc)
+      if (body != null) {
+        declarations.push(`export type ${pascal}Yield = ${body}`)
+        yieldTypeName = `${pascal}Yield`
+      }
+    }
+    if (returnSchema != null) {
+      const body = await jsonSchemaToTypeBody(returnSchema, ctx.ajsc)
+      if (body != null) {
+        declarations.push(`export type ${pascal}ReturnType = ${body}`)
+        returnTypeName = `${pascal}ReturnType`
+      }
+    }
+  }
+  const callable = [
+    `    /** ${route.method.toUpperCase()} ${route.fullPath} */`,
+    `    ${route.name}(req: ${paramsTypeName}, options?: ProcedureCallOptions): TypedStream<${yieldTypeName}, ${returnTypeName}> {`,
+    `      return client.stream<${yieldTypeName}, ${returnTypeName}>({`,
+    `        name: '${route.name}',`,
+    `        scope: '${scopeStr}',`,
+    `        path: '${route.fullPath}',`,
+    `        method: '${route.method}',`,
+    `        kind: 'http-stream',`,
+    `        streamMode: '${route.streamMode}',`,
+    `        params: req,`,
+    `      }, options)`,
+    `    },`,
+  ].join('\n')
+  const hasErrors = injectRouteErrors(
+    declarations,
+    pascal,
+    buildErrorUnion(route.errors, ctx),
+    ctx.namespaceTypes
+  )
+  return { typeDeclarations: declarations, callable, hasStream: true, hasErrors }
+}
 async function emitStreamRoute(route: StreamHttpRouteDoc, ctx: EmitRouteContext): Promise<RouteChunks> {
   const pascal = versionedPascal(route.name, route.version)
@@ -470,6 +763,8 @@ export async function emitScopeFile(
         chunks = await emitApiRoute(route as APIHttpRouteDoc, ctx)
       } else if (kind === 'stream') {
         chunks = await emitStreamRoute(route as StreamHttpRouteDoc, ctx)
+      } else if (kind === 'http-stream') {
+        chunks = await emitHttpStreamRoute(route as HttpStreamRouteDoc, ctx)
       } else {
         throw new Error(`Unknown route kind "${kind}"`)
       }

package/src/codegen/pipeline.test.ts CHANGED Viewed

@@ -375,7 +375,7 @@ describe('runPipeline (kotlin target)', () => {
           scope: 'users',
           method: 'GET',
           fullPath: '/users/:id',
-          schema: { input: { pathParams: { type: 'object' } }, returnType: { type: 'object' } },
+          jsonSchema: { req: { pathParams: { type: 'object' } }, res: { body: { type: 'object' } } },
           errors: [],
         },
       ],
@@ -438,7 +438,7 @@ describe('runPipeline (kotlin target)', () => {
       routes: [
         {
           kind: 'api', name: 'GetUser', scope: 'users', method: 'GET', fullPath: '/users/:id',
-          schema: { input: { pathParams: { type: 'object' } }, returnType: { type: 'object' } },
+          jsonSchema: { req: { pathParams: { type: 'object' } }, res: { body: { type: 'object' } } },
           errors: [],
         },
       ],
@@ -466,9 +466,9 @@ describe('runPipeline (kotlin target)', () => {
       const envelope = {
         basePath: '/api', headers: [], version: '1' as const, errors: [],
         routes: [
-          { kind: 'stream', name: 'WatchA', scope: 's', method: 'GET', path: '/a', schema: {}, errors: [] },
-          { kind: 'stream', name: 'WatchB', scope: 's', method: 'GET', path: '/b', schema: {}, errors: [] },
-          { kind: 'api', name: 'GetThing', scope: 's', method: 'GET', fullPath: '/c', schema: { returnType: { type: 'object' } }, errors: [] },
+          { kind: 'stream', name: 'WatchA', scope: 's', method: 'GET', path: '/a', jsonSchema: {}, errors: [] },
+          { kind: 'stream', name: 'WatchB', scope: 's', method: 'GET', path: '/b', jsonSchema: {}, errors: [] },
+          { kind: 'api', name: 'GetThing', scope: 's', method: 'GET', fullPath: '/c', jsonSchema: { res: { body: { type: 'object' } } }, errors: [] },
         ],
       } as any
       await runPipeline({
@@ -493,7 +493,7 @@ describe('runPipeline (kotlin target)', () => {
     try {
       const envelope = {
         basePath: '/api', headers: [], version: '1' as const, errors: [],
-        routes: [{ kind: 'api', name: 'X', scope: 's', method: 'GET', fullPath: '/x', schema: { returnType: { type: 'object' } }, errors: [] }],
+        routes: [{ kind: 'api', name: 'X', scope: 's', method: 'GET', fullPath: '/x', jsonSchema: { res: { body: { type: 'object' } } }, errors: [] }],
       } as any
       await runPipeline({
         envelope, outDir: 'out', dryRun: true,
@@ -518,7 +518,7 @@ describe('runPipeline (kotlin target)', () => {
     const envelope = {
       basePath: '/api', headers: [], version: '1' as const, errors: [],
-      routes: [{ kind: 'api', name: 'GetUser', scope: 'users', method: 'GET', fullPath: '/u', schema: { returnType: { type: 'object' } }, errors: [] }],
+      routes: [{ kind: 'api', name: 'GetUser', scope: 'users', method: 'GET', fullPath: '/u', jsonSchema: { res: { body: { type: 'object' } } }, errors: [] }],
     } as any
     await runPipeline({

package/src/codegen/resolve-envelope.test.ts CHANGED Viewed

@@ -54,11 +54,11 @@ describe('resolveEnvelope', () => {
   })
   // Defensive (downstream bug repro): forgetting `builder.build()` is a common
-  // cause of an empty routes array because hono-rpc/hono-api/hono-stream/express-rpc
-  // builders only populate their `_docs` array inside `build()`. The current
-  // error message says "Register at least one procedure", which led the
-  // downstream dev to look in the wrong place. The message should mention
-  // `.build()` as a likely cause so the next person hits the right fix faster.
+  // cause of an empty routes array because the hono builder only populates
+  // its `_docs` array inside `build()`. The current error message says
+  // "Register at least one procedure", which led the downstream dev to look
+  // in the wrong place. The message should mention `.build()` as a likely
+  // cause so the next person hits the right fix faster.
   it('empty-routes error message mentions builder.build() as a likely cause', async () => {
     const empty: DocEnvelope = { basePath: '', headers: [], errors: [], routes: [] }
     await expect(resolveEnvelope({ envelope: empty })).rejects.toThrow(/\.build\(\)/)

package/src/codegen/resolve-envelope.ts CHANGED Viewed

@@ -55,7 +55,7 @@ export async function resolveEnvelope(input: ResolveInput): Promise<DocEnvelope>
     throw new Error(
       '[ts-procedures-codegen] DocEnvelope has an empty "routes" array. ' +
       'Common causes: (1) you forgot to call `builder.build()` before passing ' +
-      'the builder to `DocRegistry.from(...)` — hono/express builders only populate ' +
+      'the builder to `DocRegistry.from(...)` — hono builders only populate ' +
       '`docs` inside `build()`; (2) no procedures registered with the builder.'
     )
   }