ts-procedures 6.2.0 → 7.0.0-beta.1

package/src/client/types.ts

@@ -30,11 +30,52 @@
 // eslint-disable-next-line @typescript-eslint/no-empty-object-type
 export interface RequestMeta {}
 
+// ── Error Classifier ─────────────────────────────────────
+
+/**
+ * Classification context — supplies provenance the classifier needs that's
+ * not derivable from the raw error itself.
+ *
+ * `timeoutSignal` and `userSignal` let the classifier distinguish a timeout
+ * abort from a user-initiated abort when an `AbortError` lands.
+ */
+export interface ClassifyErrorContext {
+  procedureName: string
+  scope: string
+  timeoutSignal?: AbortSignal
+  userSignal?: AbortSignal
+  timeoutMs?: number
+}
+
+/**
+ * The output shape of a successful classification. Contract: `error` is
+ * always an `Error` subclass (the framework class). Non-`Error` values fall
+ * through to `null` (handled by `executeCall` as `kind: 'unknown'`).
+ */
+export interface ClassifiedError {
+  kind: string
+  error: Error
+}
+
+/**
+ * Adapter-provided classifier — runs before `defaultClassifyError`. Return
+ * `null` to fall through to the default. Adapter authors should compose with
+ * the default explicitly:
+ *
+ *     classifyError: (e, ctx) => myClassify(e, ctx) ?? defaultClassifyError(e, ctx)
+ */
+export type ErrorClassifier = (
+  raw: unknown,
+  ctx: ClassifyErrorContext,
+) => ClassifiedError | null
+
 // ── Adapter ──────────────────────────────────────────────
 
 export interface ClientAdapter {
   request(config: AdapterRequest): Promise<AdapterResponse>
   stream(config: AdapterRequest): Promise<AdapterStreamResponse>
+  /** Optional adapter-level error classifier — composes with `defaultClassifyError`. */
+  classifyError?: ErrorClassifier
 }
 
 export interface AdapterRequest {
@@ -63,7 +104,7 @@ export interface AdapterStreamResponse {
   /**
    * Populated when `status` is non-2xx — the parsed response body. Surfaced so
    * `executeStream` can dispatch typed errors via the error registry instead
-   * of always falling back to `ClientRequestError` with `body: null`.
+   * of always falling back to `ClientHttpError` with `body: null`.
    */
   errorBody?: unknown
 }
@@ -177,7 +218,7 @@ export interface ErrorFactory {
 /**
  * Maps `body.name` values (taxonomy keys) to error class factories. When the
  * client sees a non-2xx response whose body has a `name` matching a registry
- * entry, it throws the typed error instead of a generic `ClientRequestError`.
+ * entry, it throws the typed error instead of a generic `ClientHttpError`.
  */
 export type ErrorRegistry = Record<string, ErrorFactory>
 
@@ -191,7 +232,36 @@ export interface ClientInstance {
   /** Optional registry for runtime dispatch of typed errors by `body.name`. */
   errorRegistry?: ErrorRegistry
   call<TResponse>(descriptor: CallDescriptor, options?: ProcedureCallOptions): Promise<TResponse>
+  safeCall<TResponse, ETyped = never>(
+    descriptor: CallDescriptor,
+    options?: ProcedureCallOptions,
+  ): Promise<Result<TResponse, ETyped>>
   stream<TYield, TReturn>(descriptor: StreamDescriptor, options?: ProcedureCallOptions): TypedStream<TYield, TReturn>
+  /**
+   * Wires a callable with a `.safe` sibling for routes without declared typed errors.
+   * Used by codegen to produce a compact one-line callable per route.
+   *
+   * The returned function's `.name` is set to `descriptor.name` for nicer stack traces.
+   */
+  bindCallable<TParams, TResponse>(
+    descriptor: Omit<CallDescriptor, 'params'>,
+  ): {
+    (params: TParams, options?: ProcedureCallOptions): Promise<TResponse>
+    safe(params: TParams, options?: ProcedureCallOptions): Promise<ResultNoTyped<TResponse>>
+  }
+  /**
+   * Wires a callable with a `.safe` sibling for routes with declared typed errors.
+   * The `.safe` form returns `Result<TResponse, ETyped>` where `ETyped` is the
+   * union of route-declared error classes.
+   *
+   * The returned function's `.name` is set to `descriptor.name` for nicer stack traces.
+   */
+  bindCallableTyped<TParams, TResponse, ETyped>(
+    descriptor: Omit<CallDescriptor, 'params'>,
+  ): {
+    (params: TParams, options?: ProcedureCallOptions): Promise<TResponse>
+    safe(params: TParams, options?: ProcedureCallOptions): Promise<Result<TResponse, ETyped>>
+  }
 }
 
 // ── createClient Config ──────────────────────────────────
@@ -211,7 +281,71 @@ export interface CreateClientConfig<TScopes> {
    * Optional error-dispatch registry. When a non-2xx response body has a
    * `name` field matching a registry key, the client throws the typed error
    * constructed via that entry's `fromResponse`. When absent or when no key
-   * matches, falls back to `ClientRequestError` (transport error shape).
+   * matches, falls back to `ClientHttpError` (transport error shape).
    */
   errorRegistry?: ErrorRegistry
 }
+
+// ── Result Types ─────────────────────────────────────────
+
+import type {
+  ClientHttpError,
+  ClientNetworkError,
+  ClientTimeoutError,
+  ClientAbortError,
+  ClientParseError,
+  ClientPathParamError,
+} from './errors.js'
+
+/**
+ * Augmentable map of `kind` discriminant → error class for the framework's
+ * non-typed failure categories. Mirrors the `RequestMeta` augmentation
+ * pattern: extend via TypeScript declaration merging.
+ *
+ * @example
+ * ```ts
+ * declare module 'ts-procedures/client' {
+ *   interface ClientErrorMap {
+ *     rateLimited: MyRateLimitError
+ *     paymentRequired: MyPaymentError
+ *   }
+ * }
+ * ```
+ *
+ * **`'typed'` is reserved** — it's the discriminant used by `Result` for
+ * route-declared errors and is not part of `ClientErrorMap`. Attempting to
+ * register it produces a TS error about overlapping discriminants.
+ */
+export interface ClientErrorMap {
+  http: ClientHttpError
+  network: ClientNetworkError
+  timeout: ClientTimeoutError
+  aborted: ClientAbortError
+  parse: ClientParseError
+  usage: ClientPathParamError
+  unknown: unknown
+}
+
+/** Distributed union of every framework failure kind. */
+export type FrameworkFailure = {
+  [K in keyof ClientErrorMap]: { ok: false; kind: K; error: ClientErrorMap[K] }
+}[keyof ClientErrorMap]
+
+/**
+ * Discriminated result type for the `.safe()` form. `kind: 'typed'` carries
+ * route-declared errors (registry-dispatched); other kinds carry framework
+ * failures. Use `ResultNoTyped<T>` for routes without declared errors.
+ */
+export type Result<T, ETyped> =
+  | { ok: true; value: T }
+  | { ok: false; kind: 'typed'; error: ETyped }
+  | FrameworkFailure
+
+/**
+ * `Result` for routes that don't declare typed errors. Omits the `'typed'`
+ * arm entirely so IDE hovers stay clean (TS doesn't collapse `never`-payload
+ * arms in tooltip output).
+ */
+export type ResultNoTyped<T> =
+  | { ok: true; value: T }
+  | FrameworkFailure

package/src/codegen/bundle-size.test.ts

@@ -0,0 +1,76 @@
+import { describe, it, expect, beforeAll } from 'vitest'
+import { generateClient } from './index.js'
+import * as path from 'node:path'
+import * as os from 'node:os'
+import * as fs from 'node:fs/promises'
+import type { DocEnvelope } from '../implementations/types.js'
+
+function makeEnvelope(routeCount: number): DocEnvelope {
+  const routes = Array.from({ length: routeCount }, (_, i) => ({
+    kind: 'rpc' as const,
+    name: `Op${i}`,
+    scope: 'ops',
+    method: 'post' as const,
+    path: `/ops/op${i}`,
+    version: 1,
+    jsonSchema: {
+      body: { type: 'object' as const, properties: { x: { type: 'string' as const } } },
+      response: { type: 'object' as const, properties: { y: { type: 'string' as const } } },
+    },
+    errors: [] as string[],
+  }))
+  return { basePath: '/api', headers: [], errors: [], routes }
+}
+
+describe('bundle size budget', () => {
+  let perRouteDelta: number
+  let totalChars: number
+
+  beforeAll(async () => {
+    const tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'tsproc-bundle-'))
+    await generateClient({
+      envelope: makeEnvelope(100),
+      outDir: tmp,
+      selfContained: false,
+    })
+    const scopeFile = await fs.readFile(path.join(tmp, 'ops.ts'), 'utf-8')
+
+    // Strip whitespace, line comments, block comments. This is a stable proxy
+    // for minification — actual minified bytes will be lower, but the *delta*
+    // between commits is what this test guards against.
+    const stripped = scopeFile
+      .replace(/\/\*[\s\S]*?\*\//g, '')   // block comments
+      .replace(/\/\/.*$/gm, '')           // line comments
+      .replace(/\s+/g, ' ')               // collapse whitespace
+    totalChars = stripped.length
+    perRouteDelta = totalChars / 100
+  })
+
+  it('stays within 1500 chars per route post-strip', () => {
+    // Initial budget — refine after first measurement. The .safe sibling adds
+    // roughly 400 chars of unminified emission per route (Object.assign wrapper
+    // + duplicated descriptor literal). Post-strip should land well under 1500.
+    //
+    // RELATIONSHIP TO SPEC TARGET: The spec sets a "200 bytes per route
+    // post-minify" goal. This whitespace-strip proxy is a coarse stand-in
+    // chosen to avoid an esbuild dep — actual minified bytes will be lower
+    // than `perRouteDelta` here. If a future task swaps in real esbuild
+    // minification, tighten the budget to ~250 bytes (200 + 25% headroom)
+    // and link back to spec section "Tests / item 10". For now this guard
+    // catches catastrophic regressions only, not subtle bloat.
+    //
+    // PERROUTEDELTA_BASELINE: 613.2 (7.0.0-beta.0, Object.assign inline emission)
+    // After bindCallable refactor (beta.1): baseline dropped to 218.8 (~64% reduction)
+    // — Object.assign + duplicated descriptor removed; one helper call per route.
+    expect(perRouteDelta).toBeLessThan(1500)
+  })
+
+  it('logs the baseline measurement for review', () => {
+    // This isn't a strict assertion — it surfaces the actual numbers to the
+    // test output so reviewers can update PERROUTEDELTA_BASELINE in the
+    // comment above without having to re-run locally.
+    // eslint-disable-next-line no-console
+    console.log(`[bundle-size] 100 routes, scope file = ${totalChars} chars stripped, per-route = ${perRouteDelta.toFixed(1)}`)
+    expect(totalChars).toBeGreaterThan(0)
+  })
+})

package/src/codegen/e2e.test.ts

@@ -223,12 +223,12 @@ describe('E2E: generateClient full pipeline', () => {
     expect(content).toContain('bindUsersScope')
   })
 
-  it('users.ts uses client.call for RPC route', async () => {
+  it('users.ts uses client.bindCallable for RPC route', async () => {
     tmpDir = makeTmpDir()
     await generateClient({ envelope, outDir: tmpDir })
 
     const content = readFileSync(join(tmpDir, 'users.ts'), 'utf-8')
-    expect(content).toContain('client.call')
+    expect(content).toContain('client.bindCallable<')
   })
 
   // ── events.ts — Stream route ───────────────────────────────────────────────
@@ -422,7 +422,7 @@ describe('E2E: generateClient full pipeline', () => {
       expect(content).toContain('ProcedureCallOptions')
     })
 
-    it('_client.ts is generated and contains createClient, createFetchAdapter, ClientRequestError', async () => {
+    it('_client.ts is generated and contains createClient, createFetchAdapter, ClientHttpError (+ deprecated ClientRequestError alias)', async () => {
       tmpDir = makeTmpDir()
       await generateClient({ envelope, outDir: tmpDir, selfContained: true })
 
@@ -430,6 +430,7 @@ describe('E2E: generateClient full pipeline', () => {
       const content = readFileSync(join(tmpDir, '_client.ts'), 'utf-8')
       expect(content).toContain('createClient')
       expect(content).toContain('createFetchAdapter')
+      expect(content).toContain('ClientHttpError')
       expect(content).toContain('ClientRequestError')
     })
 
@@ -584,6 +585,112 @@ void run
       }).not.toThrow()
     })
 
+    it('generated .safe callable type-checks against bundled Result/ResultNoTyped types', async () => {
+      // Use an envelope with two routes:
+      //   - GetUser: has errors: ['ProcedureError'] → .safe returns Result<T, GetUserErrors>
+      //   - ListUsers: has errors: []               → .safe returns ResultNoTyped<T>
+      // This verifies both the typed-error and no-typed-error branches of .safe.
+      tmpDir = makeTmpDir()
+      const safeEnvelope: DocEnvelope = {
+        basePath: '/api',
+        headers: [],
+        errors: [procedureErrorDoc],
+        routes: [
+          {
+            kind: 'rpc',
+            name: 'GetUser',
+            path: '/users/1',
+            method: 'post',
+            scope: 'users',
+            version: 1,
+            errors: ['ProcedureError'],
+            jsonSchema: {
+              body: {
+                type: 'object',
+                properties: { id: { type: 'string' } },
+                required: ['id'],
+              },
+              response: {
+                type: 'object',
+                properties: { name: { type: 'string' } },
+                required: ['name'],
+              },
+            },
+          } as RPCHttpRouteDoc,
+          {
+            kind: 'rpc',
+            name: 'ListUsers',
+            path: '/users',
+            method: 'post',
+            scope: 'users',
+            version: 1,
+            errors: [],
+            jsonSchema: {
+              body: { type: 'object' },
+              response: {
+                type: 'array',
+                items: {
+                  type: 'object',
+                  properties: { name: { type: 'string' } },
+                  required: ['name'],
+                },
+              },
+            },
+          } as RPCHttpRouteDoc,
+        ],
+      }
+
+      await generateClient({ envelope: safeEnvelope, outDir: tmpDir, selfContained: true })
+
+      // Consumer exercises .safe on both routes and verifies the Result types
+      // are assignable (type-only assertions via declared variables).
+      const consumer = `
+import type { Result, ResultNoTyped } from './_types'
+import { createApiClient } from './index'
+import { createFetchAdapter } from './_client'
+
+const client = createApiClient({
+  adapter: createFetchAdapter(),
+  basePath: 'https://api.example.com',
+})
+
+// Throwing form still compiles
+const _p1: Promise<{ name: string }> = client.users.GetUser({ id: '1' })
+void _p1
+
+// .safe on a route with declared errors returns Result<T, Errors>
+const _p2 = client.users.GetUser.safe({ id: '1' })
+const _p2check: Promise<Result<{ name: string }, unknown>> = _p2 as Promise<Result<{ name: string }, unknown>>
+void _p2check
+
+// .safe on a route without declared errors returns ResultNoTyped<T>
+const _p3 = client.users.ListUsers.safe({})
+const _p3check: Promise<ResultNoTyped<unknown>> = _p3 as Promise<ResultNoTyped<unknown>>
+void _p3check
+`
+      const { writeFileSync } = await import('node:fs')
+      writeFileSync(join(tmpDir, 'consumer.ts'), consumer)
+
+      const tsconfig = {
+        compilerOptions: {
+          strict: true,
+          target: 'ES2022',
+          module: 'ES2022',
+          moduleResolution: 'bundler',
+          noEmit: true,
+          skipLibCheck: true,
+        },
+        include: ['_types.ts', '_client.ts', 'index.ts', 'users.ts', '_errors.ts', 'consumer.ts'],
+      }
+      writeFileSync(join(tmpDir, 'tsconfig.json'), JSON.stringify(tsconfig))
+
+      const { execSync } = await import('node:child_process')
+      const tscPath = join(process.cwd(), 'node_modules', '.bin', 'tsc')
+      expect(() => {
+        execSync(`${tscPath} --noEmit --project ${join(tmpDir, 'tsconfig.json')}`, { stdio: 'pipe' })
+      }).not.toThrow()
+    })
+
     it('augmented RequestMeta rejects wrong types (compile error)', async () => {
       tmpDir = makeTmpDir()
       await generateClient({ envelope, outDir: tmpDir, selfContained: true })
@@ -657,10 +764,9 @@ void run
       await generateClient({ envelope, outDir: tmpDir, namespaceTypes: true })
 
       const content = readFileSync(join(tmpDir, 'users.ts'), 'utf-8')
-      expect(content).toContain('params: Users.GetUser.Params')
-      expect(content).toContain('Promise<Users.GetUser.Response>')
-      expect(content).toContain('params: Users.UpdateUser.Params')
-      expect(content).toContain('Promise<Users.UpdateUser.Response>')
+      // New emission: client.bindCallable<Users.GetUser.Params, Users.GetUser.Response>({...})
+      expect(content).toContain('client.bindCallable<Users.GetUser.Params, Users.GetUser.Response>')
+      expect(content).toContain('client.bindCallable<Users.UpdateUser.Params, Users.UpdateUser.Response>')
     })
 
     it('events.ts wraps stream types in namespace', async () => {

package/src/codegen/emit-client-runtime.test.ts

@@ -46,9 +46,14 @@ describe('emitClientRuntimeFile', () => {
     expect(result).toMatch(/export function createFetchAdapter/)
   })
 
-  it('contains export class ClientRequestError', async () => {
+  it('contains export class ClientHttpError (renamed from ClientRequestError)', async () => {
     const result = await emitClientRuntimeFile()
-    expect(result).toMatch(/export class ClientRequestError/)
+    expect(result).toMatch(/export class ClientHttpError/)
+  })
+
+  it('contains deprecated ClientRequestError alias', async () => {
+    const result = await emitClientRuntimeFile()
+    expect(result).toContain('ClientRequestError')
   })
 
   it('contains export class ClientPathParamError', async () => {

package/src/codegen/emit-client-runtime.ts

@@ -23,6 +23,13 @@ const TYPES_IMPORT = `import type {
   ErrorRegistry,
   ErrorFactory,
   ErrorResponseMeta,
+  ErrorClassifier,
+  ClassifyErrorContext,
+  ClassifiedError,
+  Result,
+  ResultNoTyped,
+  ClientErrorMap,
+  FrameworkFailure,
 } from './_types'`
 
 /**
@@ -31,6 +38,7 @@ const TYPES_IMPORT = `import type {
  */
 const SOURCE_FILES = [
   'errors.ts',
+  'classify-error.ts',
   'error-dispatch.ts',
   'request-builder.ts',
   'resolve-options.ts',

package/src/codegen/emit-client-types.test.ts

@@ -19,21 +19,36 @@ describe('emitClientTypesFile', () => {
 
   it('no import statements', async () => {
     const result = await emitClientTypesFile()
-    // types.ts has zero imports — the emitted file should be fully self-contained
+    // errors.ts and types.ts imports are stripped — the emitted file should be fully self-contained
     expect(result).not.toMatch(/^import\s/m)
   })
 
-  it('output content (after header) matches src/client/types.ts verbatim', async () => {
+  it('includes errors.ts content before types.ts content', async () => {
     const result = await emitClientTypesFile()
 
     const __filename = fileURLToPath(import.meta.url)
     const __dirname = dirname(__filename)
     const packageRoot = resolve(__dirname, '../..')
-    const typesPath = resolve(packageRoot, 'src/client/types.ts')
-    const typesContent = await readFile(typesPath, 'utf-8')
 
-    // The function prepends CODEGEN_HEADER + '\n' + '\n' before the file content
-    const expected = [CODEGEN_HEADER, '', typesContent].join('\n')
-    expect(result).toBe(expected)
+    // Check that both files' unique identifiers are present
+    // errors.ts contains class definitions
+    expect(result).toContain('class ClientHttpError')
+    expect(result).toContain('class ClientNetworkError')
+    // types.ts contains interfaces
+    expect(result).toContain('interface RequestMeta')
+    expect(result).toContain('interface ClientAdapter')
+
+    // errors.ts content should appear before types.ts content
+    const errorsIdx = result.indexOf('class ClientHttpError')
+    const typesIdx = result.indexOf('interface RequestMeta')
+    expect(errorsIdx).toBeLessThan(typesIdx)
+  })
+
+  it('includes Result, ResultNoTyped, ClientErrorMap from types.ts', async () => {
+    const result = await emitClientTypesFile()
+    expect(result).toContain('interface ClientErrorMap')
+    expect(result).toContain('type FrameworkFailure')
+    expect(result).toContain('type Result<T, ETyped>')
+    expect(result).toContain('type ResultNoTyped<T>')
   })
 })

package/src/codegen/emit-client-types.ts

@@ -4,8 +4,26 @@ import { readFile, access } from 'node:fs/promises'
 import { CODEGEN_HEADER } from './constants.js'
 
 /**
- * Reads `src/client/types.ts` from the package root and returns it as the
- * content of a `_types.ts` file, prepended with the auto-generated header.
+ * Strips all `import` statements from source content.
+ * These are inter-file imports that become unnecessary in a single bundled file.
+ *
+ * Note: the regex requires a `from` clause, so side-effect imports like
+ * `import './polyfill.js'` are NOT stripped. This is intentional — src/client/
+ * has no side-effect imports.
+ */
+function stripImports(content: string): string {
+  // Handle both single-line and multi-line import statements
+  return content.replace(/^import\s[\s\S]*?from\s+['"][^'"]+['"]\s*;?\s*$/gm, '')
+}
+
+/**
+ * Reads `src/client/errors.ts` and `src/client/types.ts` from the package
+ * root and returns them bundled as the content of a `_types.ts` file,
+ * prepended with the auto-generated header.
+ *
+ * `errors.ts` is included first (with imports stripped) because `types.ts`
+ * imports the error classes from it. Together they form a fully self-contained
+ * `_types.ts` with no external dependencies.
  *
  * This enables a self-contained codegen mode where consumers don't need
  * `ts-procedures` as a runtime dependency.
@@ -15,13 +33,20 @@ export async function emitClientTypesFile(): Promise<string> {
   const __dirname = dirname(__filename)
   // Works from both src/codegen/ (source) and build/codegen/ (compiled)
   const packageRoot = resolve(__dirname, '../..')
+  const errorsPath = resolve(packageRoot, 'src/client/errors.ts')
   const typesPath = resolve(packageRoot, 'src/client/types.ts')
-  await access(typesPath).catch(() => {
-    throw new Error(
-      `[ts-procedures-codegen] Cannot locate src/client/types.ts at expected path: ${typesPath}. ` +
-      `Ensure ts-procedures is installed correctly.`
-    )
-  })
-  const content = await readFile(typesPath, 'utf-8')
-  return [CODEGEN_HEADER, '', content].join('\n')
+
+  for (const [label, filePath] of [['errors.ts', errorsPath], ['types.ts', typesPath]] as const) {
+    await access(filePath).catch(() => {
+      throw new Error(
+        `[ts-procedures-codegen] Cannot locate src/client/${label} at expected path: ${filePath}. ` +
+        `Ensure ts-procedures is installed correctly.`
+      )
+    })
+  }
+
+  const errorsContent = stripImports(await readFile(errorsPath, 'utf-8')).trim()
+  const typesContent = stripImports(await readFile(typesPath, 'utf-8')).trim()
+
+  return [CODEGEN_HEADER, '', errorsContent, '', typesContent, ''].join('\n')
 }

package/src/codegen/emit-errors.ts

@@ -26,7 +26,7 @@ export interface EmitErrorsOptions {
  *
  * The registry `<ServiceName>ErrorRegistry` maps body `name` values to
  * classes, consumed by the client's `dispatchTypedError` to produce typed
- * errors instead of generic `ClientRequestError` instances.
+ * errors instead of generic `ClientHttpError` instances.
  *
  * When `namespaceTypes` is on, everything is wrapped in `export namespace
  * <ServiceName>Errors { ... }`. Returns `undefined` if no errors have schemas.

package/src/codegen/emit-index.ts

@@ -112,7 +112,7 @@ export function emitIndexFile(groups: ScopeGroup[], options?: EmitIndexOptions):
       ` * Creates a typed client for this service with the generated error`,
       ` * registry pre-configured. Non-2xx responses whose body \`name\` matches`,
       ` * a registered error are thrown as typed class instances instead of`,
-      ` * generic \`ClientRequestError\`s.`,
+      ` * generic \`ClientHttpError\`s.`,
       ` */`,
       `export function ${clientFactoryName}(`,
       `  config: Omit<CreateClientConfig<ReturnType<typeof ${factoryName}>>, 'scopes' | 'errorRegistry'>`,