ts-procedures 8.6.0 → 9.1.0

package/src/codegen/__goldens__/ts-flat--users/_errors.ts

@@ -0,0 +1,87 @@
+// Auto-generated by ts-procedures-codegen (v8.6.0) — do not edit
+// Source hash: 7b621d913616819f78563ff671bffa03
+
+/** Base class for every generated error in this service. Catch with `instanceof`. */
+export class ApiProcedureError<TBody = unknown> extends Error {
+  readonly status: number
+  readonly procedureName: string
+  readonly scope: string
+  readonly body: TBody
+  constructor(args: {
+    name: string
+    message: string
+    status: number
+    procedureName: string
+    scope: string
+    body: TBody
+  }) {
+    super(args.message)
+    this.name = args.name
+    this.status = args.status
+    this.procedureName = args.procedureName
+    this.scope = args.scope
+    this.body = args.body
+    Object.setPrototypeOf(this, new.target.prototype)
+  }
+}
+
+/** Response body for NotFound. */
+export type NotFoundBody = { name: "NotFound"; message: string; }
+
+/** Resource not found (HTTP 404) */
+export class NotFound extends ApiProcedureError<NotFoundBody> {
+  static readonly errorName = 'NotFound' as const
+  static readonly statusCode = 404
+  static fromResponse(
+    body: NotFoundBody,
+    meta: { status: number; procedureName: string; scope: string }
+  ): NotFound {
+    const message =
+      body && typeof (body as { message?: unknown }).message === 'string'
+        ? (body as { message: string }).message
+        : 'NotFound'
+    return new NotFound({
+      name: 'NotFound',
+      message,
+      status: meta.status,
+      procedureName: meta.procedureName,
+      scope: meta.scope,
+      body,
+    })
+  }
+}
+
+/** Response body for ValidationError. */
+export type ValidationErrorBody = { name: "ValidationError"; message: string; field?: string; }
+
+/** Input failed validation (HTTP 400) */
+export class ValidationError extends ApiProcedureError<ValidationErrorBody> {
+  static readonly errorName = 'ValidationError' as const
+  static readonly statusCode = 400
+  static fromResponse(
+    body: ValidationErrorBody,
+    meta: { status: number; procedureName: string; scope: string }
+  ): ValidationError {
+    const message =
+      body && typeof (body as { message?: unknown }).message === 'string'
+        ? (body as { message: string }).message
+        : 'ValidationError'
+    return new ValidationError({
+      name: 'ValidationError',
+      message,
+      status: meta.status,
+      procedureName: meta.procedureName,
+      scope: meta.scope,
+      body,
+    })
+  }
+}
+
+/** Union of every generated error in this service. */
+export type ApiProcedureErrorUnion = NotFound | ValidationError
+
+/** Runtime registry consumed by the client to dispatch by `body.name`. */
+export const ApiErrorRegistry = {
+  NotFound,
+  ValidationError,
+} as const

package/src/codegen/__goldens__/ts-flat--users/_types.ts

@@ -0,0 +1,502 @@
+// Auto-generated by ts-procedures-codegen (v8.6.0) — do not edit
+// Source hash: 7b621d913616819f78563ff671bffa03
+
+export class ClientHttpError extends Error {
+  readonly name = 'ClientHttpError'
+  readonly status: number
+  readonly headers: Record<string, string>
+  readonly body: unknown
+  readonly procedureName: string
+  readonly scope: string
+
+  constructor(opts: {
+    status: number
+    headers: Record<string, string>
+    body: unknown
+    procedureName: string
+    scope: string
+    cause?: unknown
+  }) {
+    super(
+      `${opts.procedureName} (${opts.scope}) failed with status ${opts.status}`,
+      { cause: opts.cause }
+    )
+    this.status = opts.status
+    this.headers = opts.headers
+    this.body = opts.body
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+  }
+}
+
+/** @deprecated Renamed to `ClientHttpError`. The alias is retained for one minor release after the 7.0.0 major bump and will be removed in a subsequent minor (e.g. 7.1.0). Migrate to `ClientHttpError` now. */
+ 
+export const ClientRequestError = ClientHttpError
+/** @deprecated Renamed to `ClientHttpError`. The alias is retained for one minor release after the 7.0.0 major bump and will be removed in a subsequent minor (e.g. 7.1.0). Migrate to `ClientHttpError` now. */
+// eslint-disable-next-line no-redeclare
+export type ClientRequestError = ClientHttpError
+
+export class ClientPathParamError extends Error {
+  readonly name = 'ClientPathParamError'
+
+  constructor(param: string, path: string, procedureName: string, cause?: unknown) {
+    super(`Missing path parameter "${param}" in "${path}" for procedure ${procedureName}`, { cause })
+  }
+}
+
+export class ClientStreamError extends Error {
+  readonly name = 'ClientStreamError'
+  readonly procedureName: string
+  readonly scope: string
+
+  constructor(message: string, procedureName: string, scope: string, cause?: unknown) {
+    super(message, { cause })
+    this.procedureName = procedureName
+    this.scope = scope
+  }
+}
+
+export class ClientNetworkError extends Error {
+  readonly name = 'ClientNetworkError'
+  readonly procedureName: string
+  readonly scope: string
+
+  constructor(opts: { procedureName: string; scope: string; cause?: unknown; message?: string }) {
+    super(opts.message ?? `${opts.procedureName} (${opts.scope}) failed: network error`, { cause: opts.cause })
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+  }
+}
+
+export class ClientTimeoutError extends Error {
+  readonly name = 'ClientTimeoutError'
+  readonly procedureName: string
+  readonly scope: string
+  readonly timeoutMs: number
+
+  constructor(opts: { procedureName: string; scope: string; timeoutMs: number; cause?: unknown }) {
+    super(`${opts.procedureName} (${opts.scope}) timed out after ${opts.timeoutMs}ms`, { cause: opts.cause })
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+    this.timeoutMs = opts.timeoutMs
+  }
+}
+
+export class ClientAbortError extends Error {
+  readonly name = 'ClientAbortError'
+  readonly procedureName: string
+  readonly scope: string
+  readonly reason: unknown
+
+  constructor(opts: { procedureName: string; scope: string; reason?: unknown; cause?: unknown }) {
+    super(`${opts.procedureName} (${opts.scope}) aborted`, { cause: opts.cause })
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+    this.reason = opts.reason
+  }
+}
+
+export class ClientParseError extends Error {
+  readonly name = 'ClientParseError'
+  readonly procedureName: string
+  readonly scope: string
+
+  constructor(opts: { procedureName: string; scope: string; cause?: unknown; message?: string }) {
+    super(opts.message ?? `${opts.procedureName} (${opts.scope}) response could not be parsed`, { cause: opts.cause })
+    this.procedureName = opts.procedureName
+    this.scope = opts.scope
+  }
+}
+
+// ── Request Metadata ─────────────────────────────────────
+
+/**
+ * Per-request metadata visible to adapters and hooks. Defined as an empty
+ * interface so consumers can augment it via TypeScript declaration merging
+ * to get end-to-end type safety for their own metadata fields.
+ *
+ * @example With a non-self-contained client:
+ * ```ts
+ * declare module 'ts-procedures/client' {
+ *   interface RequestMeta {
+ *     traceId?: string
+ *     priority?: 'high' | 'low'
+ *   }
+ * }
+ * ```
+ *
+ * @example With a self-contained (code-generated) client:
+ * ```ts
+ * declare module './generated/_types' {
+ *   interface RequestMeta {
+ *     traceId?: string
+ *   }
+ * }
+ * ```
+ *
+ * After augmentation, `request.meta.traceId` is typed everywhere — per-call
+ * options, hooks, and adapters.
+ */
+// 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 {
+  url: string
+  method: string
+  headers?: Record<string, string>
+  body?: unknown
+  signal?: AbortSignal
+  /**
+   * Per-request metadata. Augment `RequestMeta` via declaration merging to
+   * type your own fields. See {@link RequestMeta}.
+   */
+  meta?: RequestMeta
+}
+
+export interface AdapterResponse {
+  status: number
+  headers: Record<string, string>
+  body: unknown
+}
+
+export interface AdapterStreamResponse {
+  status: number
+  /**
+   * Platform `Headers` object populated by the adapter. Passed through to
+   * `TypedStream.headers` when the route declares `res.headers`.
+   */
+  headers: Headers
+  body: AsyncIterable<unknown>
+  /**
+   * 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 `ClientHttpError` with `body: null`.
+   */
+  errorBody?: unknown
+}
+
+// ── Hooks ────────────────────────────────────────────────
+
+export interface ClientHooks {
+  onBeforeRequest?(context: BeforeRequestContext): BeforeRequestContext | Promise<BeforeRequestContext>
+  onAfterResponse?(context: AfterResponseContext): void | Promise<void>
+  onError?(context: ErrorContext): void | Promise<void>
+}
+
+export interface BeforeRequestContext {
+  procedureName: string
+  scope: string
+  request: AdapterRequest
+}
+
+export interface AfterResponseContext {
+  procedureName: string
+  scope: string
+  request: AdapterRequest
+  response: AdapterResponse
+}
+
+export interface ErrorContext {
+  procedureName: string
+  scope: string
+  request: AdapterRequest
+  error: unknown
+}
+
+// ── Descriptors ──────────────────────────────────────────
+
+export interface CallDescriptor {
+  name: string
+  scope: string
+  path: string
+  method: string
+  kind: 'rpc' | 'api' | 'stream' | 'http-stream'
+  params: unknown
+  /**
+   * Set by codegen when the route declares `schema.res.headers`. Drives
+   * whether `executeCall` returns bare body (`undefined`/false) or a
+   * `{ body, headers }` envelope (`true`). Mirrors the `HttpReturn<TRes>`
+   * conditional return shape on the server side.
+   */
+  responseHeadersDeclared?: boolean
+}
+
+export interface StreamDescriptor extends CallDescriptor {
+  kind: 'stream' | 'http-stream'
+  streamMode: 'sse' | 'text'
+}
+
+// ── TypedStream ──────────────────────────────────────────
+
+export interface TypedStream<TYield, TReturn = void> extends AsyncIterable<TYield> {
+  /**
+   * Resolves when the stream completes with the final return value.
+   * Rejects if the stream errors before completing.
+   * Note: iteration must begin (via for-await) for this promise to settle,
+   * since resolution depends on the async generator running to completion.
+   */
+  result: Promise<TReturn>
+  /**
+   * Platform `Headers` from the initial stream response. Populated only when
+   * the route declares `res.headers` (i.e. `responseHeadersDeclared: true` on
+   * the descriptor). Undefined otherwise — consumers without declared response
+   * headers should not rely on this field.
+   */
+  headers?: Headers
+}
+
+// ── Request Options ──────────────────────────────────────
+
+/**
+ * Request-level configuration that can be set as client-level defaults
+ * (via `CreateClientConfig.defaults`) or per-call (via `ProcedureCallOptions`).
+ *
+ * - `signal`: AbortSignal for cancellation. When both a default and per-call
+ *   signal are provided, they're combined — whichever aborts first wins.
+ * - `timeout`: Timeout in milliseconds. Combined with `signal` the same way.
+ *   A per-call `timeout: 0` disables an inherited default timeout.
+ * - `headers`: Extra headers merged into the request, as a static record OR a
+ *   (possibly async) function evaluated per request. Per-call keys win over
+ *   default keys. Use the function form for values that change between calls
+ *   (e.g. a rotating bearer token) so they don't go stale. Still subject to
+ *   further mutation by `onBeforeRequest` hooks.
+ * - `basePath`: Override the base path for this call. Per-call > default > config.
+ * - `meta`: Per-request metadata typed via the {@link RequestMeta} interface.
+ *   Merged shallowly (per-call keys win over default keys).
+ */
+/**
+ * Request headers as a static record OR a (possibly async) function evaluated
+ * per request. Use the function form for values that change between calls — e.g.
+ * a rotating bearer token: `headers: () => ({ Authorization: `Bearer ${session.token}` })`.
+ * A static record captured at construction goes stale; a function is re-evaluated each call.
+ *
+ * Named `ClientHeadersInit` (not `HeadersInit`) to avoid shadowing the DOM lib's
+ * global `HeadersInit`, which has a different shape.
+ */
+export type ClientHeadersInit =
+  | Record<string, string>
+  | (() => Record<string, string> | Promise<Record<string, string>>)
+
+export interface ProcedureCallDefaults {
+  signal?: AbortSignal
+  timeout?: number
+  headers?: ClientHeadersInit
+  basePath?: string
+  meta?: RequestMeta
+}
+
+/**
+ * Per-call options. Extends both `ProcedureCallDefaults` (request config) and
+ * `ClientHooks` (hooks), so a single options bag covers both concerns.
+ */
+export interface ProcedureCallOptions extends ProcedureCallDefaults, ClientHooks {}
+
+// ── Error Registry ───────────────────────────────────────
+
+/**
+ * Metadata attached to a typed error at construction. Supplies the transport
+ * context (status, procedure, scope) that isn't part of the response body.
+ */
+export interface ErrorResponseMeta {
+  status: number
+  procedureName: string
+  scope: string
+}
+
+/**
+ * A factory for a typed error class — constructed from the response body plus
+ * transport metadata. Generated error classes expose this as a static method.
+ */
+export interface ErrorFactory {
+  fromResponse(body: unknown, meta: ErrorResponseMeta): Error
+}
+
+/**
+ * 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 `ClientHttpError`.
+ */
+export type ErrorRegistry = Record<string, ErrorFactory>
+
+// ── Client Instance ──────────────────────────────────────
+
+export interface ClientInstance {
+  basePath: string
+  adapter: ClientAdapter
+  hooks: ClientHooks
+  defaults: ProcedureCallDefaults
+  /** 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 ──────────────────────────────────
+
+export interface CreateClientConfig<TScopes> {
+  adapter: ClientAdapter
+  basePath: string
+  scopes: (client: ClientInstance) => TScopes
+  hooks?: ClientHooks
+  /**
+   * Default request options applied to every call. Per-call options override
+   * these (except `signal`, which combines via AbortSignal.any — whichever
+   * fires first cancels the request).
+   */
+  defaults?: ProcedureCallDefaults
+  /**
+   * 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 `ClientHttpError` (transport error shape).
+   */
+  errorRegistry?: ErrorRegistry
+  /**
+   * Returns the current bearer token, re-evaluated per request (so a rotating
+   * token never goes stale). Wired internally to the `Authorization: Bearer
+   * <token>` header — a `null`/`undefined` token omits the header entirely.
+   *
+   * This is sugar over a function-valued `defaults.headers`; it composes with
+   * `defaults.headers` (both are applied, auth last) and is still subject to
+   * per-call `headers` and `onBeforeRequest`, which run after and can override.
+   *
+   * @example
+   * ```ts
+   * createClient({ adapter, basePath, auth: () => session.token, scopes })
+   * ```
+   */
+  auth?: () => string | null | undefined | Promise<string | null | undefined>
+}
+
+// ── Result Types ─────────────────────────────────────────
+
+
+/**
+ * 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/__goldens__/ts-flat--users/index.ts

@@ -0,0 +1,34 @@
+// Auto-generated by ts-procedures-codegen (v8.6.0) — do not edit
+// Source hash: 7b621d913616819f78563ff671bffa03
+import { createClient } from './_client'
+import type { ClientInstance, CreateClientConfig } from './_types'
+import * as _users from './users'
+import * as _errorsModule from './_errors'
+
+
+export function createApiBindings(client: ClientInstance) {
+  return {
+    users: _users.bindUsersScope(client),
+  }
+}
+
+/** Full typed client surface — every scope of `Api`. */
+export type ApiClient = ReturnType<typeof createApiBindings>
+/** Narrow port for the `users` scope — inject as a DI seam without casting the aggregate client. */
+export type UsersClient = ApiClient['users']
+
+/**
+ * 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 `ClientHttpError`s.
+ */
+export function createApiClient(
+  config: Omit<CreateClientConfig<ReturnType<typeof createApiBindings>>, 'scopes' | 'errorRegistry'>
+) {
+  return createClient({
+    ...config,
+    errorRegistry: _errorsModule.ApiErrorRegistry,
+    scopes: (client) => createApiBindings(client),
+  })
+}