@orpc/contract 2.0.0-beta.22 → 2.0.0-beta.24

package/README.md

@@ -44,6 +44,7 @@ You can read the documentation [here](https://orpc.dev).
 
 - [@orpc/publisher](https://www.npmjs.com/package/@orpc/publisher): Pub/Sub with memory, Redis, and Upstash adapters.
 - [@orpc/ratelimit](https://www.npmjs.com/package/@orpc/ratelimit): Rate limiting with memory, Redis, and Upstash adapters.
+- [@orpc/hibernation](https://www.npmjs.com/package/@orpc/hibernation): Leverage Hibernation APIs like [Cloudflare's Hibernation WebSocket](https://developers.cloudflare.com/durable-objects/best-practices/websockets/#durable-objects-hibernation-websocket-api).
 - [@orpc/json-schema](https://www.npmjs.com/package/@orpc/json-schema): Smart coercion for OpenAPI requests.
 
 **Framework & ecosystem integrations**
@@ -114,6 +115,7 @@ Like what we build over at [middleapi](https://github.com/middleapi)? You can he
   </tr>
   <tr>
    <td align="center"><a href="https://github.com/itigoore01?ref=orpc" target="_blank" rel="noopener" title="shota"><img src="https://avatars.githubusercontent.com/u/11831107?u=c976a6dc7e055eb026304c46c99100ed22b0c8e0&amp;v=4" width="139" alt="shota"/><br />shota</a></td>
+   <td align="center"><a href="https://github.com/ellis-driscoll?ref=orpc" target="_blank" rel="noopener" title="Ellis Driscoll"><img src="https://avatars.githubusercontent.com/u/70685966?u=c5f95bc33b5991d9744abe00052542e4a2ed3cb9&amp;v=4" width="139" alt="Ellis Driscoll"/><br />Ellis Driscoll</a></td>
   </tr>
 </table>
 
@@ -139,8 +141,9 @@ Like what we build over at [middleapi](https://github.com/middleapi)? You can he
    <td align="center"><a href="https://github.com/mr-kelly?ref=orpc" target="_blank" rel="noopener" title="Kelly Peilin Chan"><img src="https://avatars.githubusercontent.com/u/520852?u=6b0f7105f694e7b5cacf410a3f04c7044b469dc8&amp;v=4" width="119" alt="Kelly Peilin Chan"/><br />Kelly Peilin Chan</a></td>
   </tr>
   <tr>
+   <td align="center"><a href="https://github.com/guyariely?ref=orpc" target="_blank" rel="noopener" title="Guy Ariely"><img src="https://avatars.githubusercontent.com/u/42813496?u=edb6b7f563bf28e160a290832e7da57c0506f8ca&amp;v=4" width="119" alt="Guy Ariely"/><br />Guy Ariely</a></td>
    <td align="center"><a href="https://github.com/piscis?ref=orpc" target="_blank" rel="noopener" title="Alex"><img src="https://avatars.githubusercontent.com/u/326163?u=b245f368bd940cf51d08c0b6bf55f8257f359437&amp;v=4" width="119" alt="Alex"/><br />Alex</a></td>
-   <td align="center"><a href="https://github.com/finom?ref=orpc" target="_blank" rel="noopener" title="Andrey Gubanov"><img src="https://avatars.githubusercontent.com/u/1082083?u=29e91400dbd4a9c217048a8f59562c4f740498e6&amp;v=4" width="119" alt="Andrey Gubanov"/><br />Andrey Gubanov</a></td>
+   <td align="center"><a href="https://github.com/finom?ref=orpc" target="_blank" rel="noopener" title="Andrey Gubanov"><img src="https://avatars.githubusercontent.com/u/1082083?u=c5f2daf7ebece498e85c83367bb37b4e10e2649d&amp;v=4" width="119" alt="Andrey Gubanov"/><br />Andrey Gubanov</a></td>
   </tr>
 </table>
 

package/dist/index.d.mts

@@ -1,8 +1,8 @@
-import { E as ErrorMap, A as AnySchema, P as ProcedureContract, M as MetaPlugin, a as MergedSchema, b as Meta, c as AnyMetaPlugin, R as RouterContract, d as AnyProcedureContract, S as Schema, I as InferSchemaInput, e as InferSchemaOutput, O as ORPCErrorFromErrorMap, f as SchemaIssue } from './shared/contract.Do92aRJ4.mjs';
-export { g as ErrorMapItem, H as HIDDEN_META_PLUGINS_SYMBOL, h as InferRouterContractError, i as InferRouterContractErrorMap, j as InferRouterContractErrors, k as InferRouterContractInputs, l as InferRouterContractOutputs, m as MetaPluginDefinition, n as ProcedureContractDefinition, V as ValidationError, o as ValidationErrorOptions, p as getHiddenMetaPlugins, s as setHiddenMetaPlugins } from './shared/contract.Do92aRJ4.mjs';
-import { AnyORPCError, ClientContext, Client, ORPCClientOptions, ClientLink } from '@orpc/client';
+import { E as ErrorMap, A as AnySchema, P as ProcedureContract, M as MetaPlugin, a as MergedSchema, b as Meta, c as AnyMetaPlugin, R as RouterContract, d as AnyProcedureContract, S as Schema, I as InferSchemaInput, e as InferSchemaOutput, O as ORPCErrorFromErrorMap, f as ErrorMapItem, g as SchemaIssue } from './shared/contract.C06qWQqK.mjs';
+export { H as HIDDEN_META_PLUGINS_SYMBOL, h as InferContractRouterErrorMap, i as InferContractRouterInputs, j as InferContractRouterOutputs, k as InferRouterContractError, h as InferRouterContractErrorMap, l as InferRouterContractErrors, i as InferRouterContractInputs, j as InferRouterContractOutputs, m as MetaPluginDefinition, n as ProcedureContractDefinition, V as ValidationError, o as ValidationErrorOptions, p as getHiddenMetaPlugins, s as setHiddenMetaPlugins } from './shared/contract.C06qWQqK.mjs';
+import { AnyORPCError, ClientContext, Client, ORPCClientOptions, ClientLink, ORPCErrorCode, ORPCErrorOptions, ORPCError } from '@orpc/client';
 export { Client, ClientContext, ClientOptions, ClientRest, FriendlyClientOptions } from '@orpc/client';
-import { ThrowableError, AsyncIteratorClass, Promisable, IsEqual } from '@orpc/shared';
+import { ThrowableError, MaybeOptionalOptions, AsyncIteratorClass, Promisable, IsEqual } from '@orpc/shared';
 export { PromiseWithError, Registry, ThrowableError } from '@orpc/shared';
 import '@standard-schema/spec';
 
@@ -43,6 +43,15 @@ interface AugmentContractRouterOptions<TErrorMap extends ErrorMap> {
 declare function augmentContractRouter<T extends RouterContract, TErrorMap extends ErrorMap>(router: T, options: AugmentContractRouterOptions<TErrorMap>): AugmentedContractRouter<T, TErrorMap>;
 declare function getRouterContract(router: RouterContract, path: readonly string[]): RouterContract | undefined;
 declare function getProcedureContractOrThrow(router: RouterContract, path: readonly string[]): AnyProcedureContract;
+/**
+ * Minifies a router contract so it can be safely exported to the client
+ * without exposing internal logic.
+ *
+ * @remarks
+ * **Note**: Only the metadata needed by the client is preserved; all other data is stripped out.
+ *
+ * @see {@link https://orpc.dev/docs/contract/router | Router Contract}
+ */
 declare function minifyRouterContract(router: RouterContract): RouterContract;
 
 type InitialInputSchema = Schema<void, unknown>;
@@ -60,10 +69,22 @@ declare class ContractBuilder<TErrorMap extends ErrorMap> extends ProcedureContr
     output<T extends AnySchema>(schema: T): ProcedureContractBuilderWithOutput<T, TErrorMap>;
     router<T extends RouterContract>(router: T): AugmentedContractRouter<T, TErrorMap>;
 }
+/**
+ * The contract builder — the entry point for defining procedure and router contracts
+ * (input/output schemas, errors, and metadata) without any business logic.
+ *
+ * @see {@link https://orpc.dev/docs/contract/procedure | Procedure Contract}
+ */
 declare const oc: ContractBuilder<object>;
 
 type ProcedureContractClient<TClientContext extends ClientContext, TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap> = Client<TClientContext, InferSchemaInput<TInputSchema>, InferSchemaOutput<TOutputSchema>, ORPCErrorFromErrorMap<TErrorMap> | ThrowableError>;
 
+/**
+ * Client type inferred from a router contract, preserving its shape.
+ * Useful for typing a client without importing the server router.
+ *
+ * @see {@link https://orpc.dev/docs/client/client-side | Client-Side Clients}
+ */
 type RouterContractClient<TRouter extends RouterContract, TClientContext extends ClientContext = object> = TRouter extends ProcedureContract<infer UInputSchema, infer UOutputSchema, infer UErrorMap> ? ProcedureContractClient<TClientContext, UInputSchema, UOutputSchema, UErrorMap> : {
     [K in keyof TRouter]: TRouter[K] extends RouterContract ? RouterContractClient<TRouter[K], TClientContext> : never;
 };
@@ -79,11 +100,103 @@ interface ContractClientFactoryOptions<TClientContext extends ClientContext> ext
      */
     contractRef?: undefined | RouterContract;
 }
+/**
+ * Creates a client factory that builds a client from any procedure or router contract,
+ * so large projects can import individual contracts instead of a single root client.
+ *
+ * @remarks
+ * **Warning**: Every procedure contract passed to the factory must define `meta.path` matching its location in the root contract.
+ *
+ * @see {@link https://orpc.dev/docs/advanced/scaling-large-projects#contract-client-factory | Scaling Large Projects - Contract Client Factory}
+ */
 declare function createContractClientFactory<TClientContext extends ClientContext>(link: ClientLink<TClientContext>, options?: ContractClientFactoryOptions<TClientContext>): ContractClientFactory<TClientContext>;
 
+interface ORPCErrorFactoryOptions<TData> {
+    /**
+     * Optional schema used to type and validate the error data.
+     * Must be a synchronous schema.
+     */
+    data?: Schema<TData>;
+    /**
+     * Optional default message, can be overridden when constructing an error.
+     */
+    message?: string;
+}
+interface ORPCErrorFactory<TCode extends ORPCErrorCode, TData> extends ErrorMapItem {
+    code: TCode;
+    data: Schema<TData>;
+    new (...rest: MaybeOptionalOptions<ORPCErrorOptions<TData>>): ORPCError<TCode, TData>;
+}
+/**
+ * Creates a reusable error class ({@link ORPCErrorFactory}) for the given code,
+ * default message, and data schema.
+ *
+ * @example
+ * ```ts
+ * const RateLimitedError = error('RATE_LIMITED', {
+ *   message: 'You are being rate limited',
+ *   data: z.object({ retryAfter: z.number() }),
+ * })
+ *
+ * const procedure = os
+ *   .errors({ [RateLimitedError.code]: RateLimitedError })
+ *   .handler(() => {
+ *     throw new RateLimitedError({ data: { retryAfter: 60 } })
+ *   })
+ *
+ * try {
+ *   const output = call(procedure)
+ * } catch (error) {
+ *   if (error instanceof RateLimitedError) {
+ *     console.log(error.data.retryAfter)
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link https://orpc.dev/docs/error-handling#error-factory | Error Handling - Error Factory}
+ */
+declare function error<TCode extends ORPCErrorCode, TData = unknown>(code: TCode, { data: dataSchema, message }?: ORPCErrorFactoryOptions<TData>): ORPCErrorFactory<TCode, TData>;
+type ORPCErrorConstructorMapItemOptions<TData> = Omit<ORPCErrorOptions<TData>, 'status'>;
+interface ORPCErrorConstructorMapItem<TCode extends ORPCErrorCode, TInData> {
+    (...rest: MaybeOptionalOptions<ORPCErrorConstructorMapItemOptions<TInData>>): ORPCError<TCode, TInData>;
+}
+type ORPCErrorConstructorMap<T extends ErrorMap> = {
+    [K in keyof T]: T[K] extends ErrorMapItem ? ORPCErrorConstructorMapItem<K & ORPCErrorCode, T[K]['data'] extends AnySchema ? InferSchemaInput<T[K]['data']> : unknown> : never;
+};
+/**
+ * Creates a map of ORPC error constructors.
+ *
+ * The returned object is a `Proxy` that allows access to arbitrary error codes:
+ * - If the code exists in the provided `errorMap`, the corresponding constructor
+ *   will create a **defined** `ORPCError`.
+ * - If the code does not exist, a fallback `ORPCError` constructor is returned.
+ *
+ * The `in` operator can be used to check whether an error code is explicitly
+ * defined in the map.
+ *
+ * @example
+ * ```ts
+ * const errorMap = createORPCErrorConstructorMap({
+ *   NOT_FOUND: {
+ *     message: 'Not Found',
+ *   },
+ * })
+ *
+ * throw errorMap.NOT_FOUND()
+ * ```
+ */
+declare function createORPCErrorConstructorMap<T extends ErrorMap>(errorMap: T): ORPCErrorConstructorMap<T>;
+
 interface PathMetaPlugin<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap> extends MetaPlugin<TInputSchema, TOutputSchema, TErrorMap> {
     name: '~path';
 }
+/**
+ * Built-in metadata plugins.
+ * `meta.path` records a procedure contract's path inside the root contract,
+ * which is required for the contract client factory pattern.
+ *
+ * @see {@link https://orpc.dev/docs/advanced/scaling-large-projects | Scaling Large Projects}
+ */
 declare const meta: {
     path<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap>(path: string[]): PathMetaPlugin<TInputSchema, TOutputSchema, TErrorMap>;
 };
@@ -143,6 +256,8 @@ declare function resolveMetaPlugins<TInputSchema extends AnySchema, TOutputSchem
  * @returns A `[metaPlugin, getMeta]` tuple:
  *   - `metaPlugin(metadata)` - Attaches metadata to a procedure under `name`.
  *   - `getMeta(procedureOrLazy)` - Retrieves the metadata, or `undefined` if not set.
+ *
+ * @see {@link https://orpc.dev/docs/metadata | Metadata}
  */
 declare function defineMeta<TName extends string, TData>(name: TName, merge: (incoming: TData, current: TData | undefined) => TData): [
     metaPlugin: (meta: TData) => AnyMetaPlugin & {
@@ -160,7 +275,10 @@ interface AsyncIteratorObjectSchemaDetails {
     returnSchema?: AnySchema;
 }
 /**
- * Define schema for an AsyncIteratorObject.
+ * Defines a schema for an AsyncIteratorObject, validating each yielded value
+ * (and optionally the return value) with the given schemas.
+ *
+ * @see {@link https://orpc.dev/docs/async-iterator-object | AsyncIteratorObject (SSE)}
  */
 declare function asyncIteratorObject<TYieldIn, TYieldOut, TReturnIn = unknown, TReturnOut = unknown>(yieldSchema: Schema<TYieldIn, TYieldOut>, returnSchema?: Schema<TReturnIn, TReturnOut>): Schema<AsyncIteratorObject<TYieldIn, TReturnIn, void>, AsyncIteratorClass<TYieldOut, TReturnOut, void>>;
 declare function getAsyncIteratorObjectSchemaDetails(schema: AnySchema | undefined): undefined | AsyncIteratorObjectSchemaDetails;
@@ -176,7 +294,7 @@ type TypeRest<TInput, TOutput> = [map: (input: TInput) => Promisable<TOutput>] |
  * const withMap = type<number, string>(input => input.toString())
  *```
  *
- * @see {@link https://orpc.dev/docs/procedure#type-utility Type Utility Docs}
+ * @see {@link https://orpc.dev/docs/procedure#type-utility | Procedure - type Utility}
  */
 declare function type<TInput, TOutput = TInput>(...[map]: TypeRest<TInput, TOutput>): Schema<TInput, TOutput>;
 /**
@@ -184,5 +302,5 @@ declare function type<TInput, TOutput = TInput>(...[map]: TypeRest<TInput, TOutp
  */
 declare function isSchemaIssue(issue: unknown): issue is SchemaIssue;
 
-export { AnyMetaPlugin, AnyProcedureContract, AnySchema, ContractBuilder, ErrorMap, InferSchemaInput, InferSchemaOutput, MergedSchema, Meta, MetaPlugin, ORPCErrorFromErrorMap, ProcedureContract, RouterContract, Schema, SchemaIssue, asyncIteratorObject, augmentContractRouter, createContractClientFactory, defineMeta, asyncIteratorObject as eventIterator, getAsyncIteratorObjectSchemaDetails, getPathMeta, getProcedureContractOrThrow, getRouterContract, isSchemaIssue, mergeErrorMap, meta, minifyRouterContract, oc, reconcileORPCError, resolveBasePathMeta, resolveMetaPlugins, type };
-export type { AsyncIteratorObjectSchemaDetails, AugmentContractRouterOptions, AugmentedContractRouter, ContractClientFactory, ContractClientFactoryOptions, InitialInputSchema, InitialOutputSchema, MergedErrorMap, PathMetaPlugin, ProcedureContractBuilderWithInput, ProcedureContractBuilderWithInputOutput, ProcedureContractBuilderWithOutput, ProcedureContractClient, RouterContractClient, TypeRest };
+export { AnyProcedureContract as AnyContractProcedure, RouterContract as AnyContractRouter, AnyMetaPlugin, AnyProcedureContract, AnySchema, ContractBuilder, ErrorMap, ErrorMapItem, InferSchemaInput, InferSchemaOutput, MergedSchema, Meta, MetaPlugin, ORPCErrorFromErrorMap, ProcedureContract, RouterContract, Schema, SchemaIssue, asyncIteratorObject, augmentContractRouter, createContractClientFactory, createORPCErrorConstructorMap, defineMeta, error, asyncIteratorObject as eventIterator, getAsyncIteratorObjectSchemaDetails, getRouterContract as getContractRouter, getPathMeta, getProcedureContractOrThrow, getRouterContract, isSchemaIssue, mergeErrorMap, meta, minifyRouterContract as minifyContractRouter, minifyRouterContract, oc, reconcileORPCError, resolveBasePathMeta, resolveMetaPlugins, type };
+export type { AsyncIteratorObjectSchemaDetails, AugmentContractRouterOptions, AugmentedContractRouter, ContractClientFactory, ContractClientFactoryOptions, InitialInputSchema, InitialOutputSchema, MergedErrorMap, ORPCErrorConstructorMap, ORPCErrorConstructorMapItem, ORPCErrorConstructorMapItemOptions, ORPCErrorFactory, ORPCErrorFactoryOptions, PathMetaPlugin, ProcedureContractBuilderWithInput, ProcedureContractBuilderWithInputOutput, ProcedureContractBuilderWithOutput, ProcedureContractClient, RouterContractClient, TypeRest };

package/dist/index.d.ts

@@ -1,8 +1,8 @@
-import { E as ErrorMap, A as AnySchema, P as ProcedureContract, M as MetaPlugin, a as MergedSchema, b as Meta, c as AnyMetaPlugin, R as RouterContract, d as AnyProcedureContract, S as Schema, I as InferSchemaInput, e as InferSchemaOutput, O as ORPCErrorFromErrorMap, f as SchemaIssue } from './shared/contract.Do92aRJ4.js';
-export { g as ErrorMapItem, H as HIDDEN_META_PLUGINS_SYMBOL, h as InferRouterContractError, i as InferRouterContractErrorMap, j as InferRouterContractErrors, k as InferRouterContractInputs, l as InferRouterContractOutputs, m as MetaPluginDefinition, n as ProcedureContractDefinition, V as ValidationError, o as ValidationErrorOptions, p as getHiddenMetaPlugins, s as setHiddenMetaPlugins } from './shared/contract.Do92aRJ4.js';
-import { AnyORPCError, ClientContext, Client, ORPCClientOptions, ClientLink } from '@orpc/client';
+import { E as ErrorMap, A as AnySchema, P as ProcedureContract, M as MetaPlugin, a as MergedSchema, b as Meta, c as AnyMetaPlugin, R as RouterContract, d as AnyProcedureContract, S as Schema, I as InferSchemaInput, e as InferSchemaOutput, O as ORPCErrorFromErrorMap, f as ErrorMapItem, g as SchemaIssue } from './shared/contract.C06qWQqK.js';
+export { H as HIDDEN_META_PLUGINS_SYMBOL, h as InferContractRouterErrorMap, i as InferContractRouterInputs, j as InferContractRouterOutputs, k as InferRouterContractError, h as InferRouterContractErrorMap, l as InferRouterContractErrors, i as InferRouterContractInputs, j as InferRouterContractOutputs, m as MetaPluginDefinition, n as ProcedureContractDefinition, V as ValidationError, o as ValidationErrorOptions, p as getHiddenMetaPlugins, s as setHiddenMetaPlugins } from './shared/contract.C06qWQqK.js';
+import { AnyORPCError, ClientContext, Client, ORPCClientOptions, ClientLink, ORPCErrorCode, ORPCErrorOptions, ORPCError } from '@orpc/client';
 export { Client, ClientContext, ClientOptions, ClientRest, FriendlyClientOptions } from '@orpc/client';
-import { ThrowableError, AsyncIteratorClass, Promisable, IsEqual } from '@orpc/shared';
+import { ThrowableError, MaybeOptionalOptions, AsyncIteratorClass, Promisable, IsEqual } from '@orpc/shared';
 export { PromiseWithError, Registry, ThrowableError } from '@orpc/shared';
 import '@standard-schema/spec';
 
@@ -43,6 +43,15 @@ interface AugmentContractRouterOptions<TErrorMap extends ErrorMap> {
 declare function augmentContractRouter<T extends RouterContract, TErrorMap extends ErrorMap>(router: T, options: AugmentContractRouterOptions<TErrorMap>): AugmentedContractRouter<T, TErrorMap>;
 declare function getRouterContract(router: RouterContract, path: readonly string[]): RouterContract | undefined;
 declare function getProcedureContractOrThrow(router: RouterContract, path: readonly string[]): AnyProcedureContract;
+/**
+ * Minifies a router contract so it can be safely exported to the client
+ * without exposing internal logic.
+ *
+ * @remarks
+ * **Note**: Only the metadata needed by the client is preserved; all other data is stripped out.
+ *
+ * @see {@link https://orpc.dev/docs/contract/router | Router Contract}
+ */
 declare function minifyRouterContract(router: RouterContract): RouterContract;
 
 type InitialInputSchema = Schema<void, unknown>;
@@ -60,10 +69,22 @@ declare class ContractBuilder<TErrorMap extends ErrorMap> extends ProcedureContr
     output<T extends AnySchema>(schema: T): ProcedureContractBuilderWithOutput<T, TErrorMap>;
     router<T extends RouterContract>(router: T): AugmentedContractRouter<T, TErrorMap>;
 }
+/**
+ * The contract builder — the entry point for defining procedure and router contracts
+ * (input/output schemas, errors, and metadata) without any business logic.
+ *
+ * @see {@link https://orpc.dev/docs/contract/procedure | Procedure Contract}
+ */
 declare const oc: ContractBuilder<object>;
 
 type ProcedureContractClient<TClientContext extends ClientContext, TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap> = Client<TClientContext, InferSchemaInput<TInputSchema>, InferSchemaOutput<TOutputSchema>, ORPCErrorFromErrorMap<TErrorMap> | ThrowableError>;
 
+/**
+ * Client type inferred from a router contract, preserving its shape.
+ * Useful for typing a client without importing the server router.
+ *
+ * @see {@link https://orpc.dev/docs/client/client-side | Client-Side Clients}
+ */
 type RouterContractClient<TRouter extends RouterContract, TClientContext extends ClientContext = object> = TRouter extends ProcedureContract<infer UInputSchema, infer UOutputSchema, infer UErrorMap> ? ProcedureContractClient<TClientContext, UInputSchema, UOutputSchema, UErrorMap> : {
     [K in keyof TRouter]: TRouter[K] extends RouterContract ? RouterContractClient<TRouter[K], TClientContext> : never;
 };
@@ -79,11 +100,103 @@ interface ContractClientFactoryOptions<TClientContext extends ClientContext> ext
      */
     contractRef?: undefined | RouterContract;
 }
+/**
+ * Creates a client factory that builds a client from any procedure or router contract,
+ * so large projects can import individual contracts instead of a single root client.
+ *
+ * @remarks
+ * **Warning**: Every procedure contract passed to the factory must define `meta.path` matching its location in the root contract.
+ *
+ * @see {@link https://orpc.dev/docs/advanced/scaling-large-projects#contract-client-factory | Scaling Large Projects - Contract Client Factory}
+ */
 declare function createContractClientFactory<TClientContext extends ClientContext>(link: ClientLink<TClientContext>, options?: ContractClientFactoryOptions<TClientContext>): ContractClientFactory<TClientContext>;
 
+interface ORPCErrorFactoryOptions<TData> {
+    /**
+     * Optional schema used to type and validate the error data.
+     * Must be a synchronous schema.
+     */
+    data?: Schema<TData>;
+    /**
+     * Optional default message, can be overridden when constructing an error.
+     */
+    message?: string;
+}
+interface ORPCErrorFactory<TCode extends ORPCErrorCode, TData> extends ErrorMapItem {
+    code: TCode;
+    data: Schema<TData>;
+    new (...rest: MaybeOptionalOptions<ORPCErrorOptions<TData>>): ORPCError<TCode, TData>;
+}
+/**
+ * Creates a reusable error class ({@link ORPCErrorFactory}) for the given code,
+ * default message, and data schema.
+ *
+ * @example
+ * ```ts
+ * const RateLimitedError = error('RATE_LIMITED', {
+ *   message: 'You are being rate limited',
+ *   data: z.object({ retryAfter: z.number() }),
+ * })
+ *
+ * const procedure = os
+ *   .errors({ [RateLimitedError.code]: RateLimitedError })
+ *   .handler(() => {
+ *     throw new RateLimitedError({ data: { retryAfter: 60 } })
+ *   })
+ *
+ * try {
+ *   const output = call(procedure)
+ * } catch (error) {
+ *   if (error instanceof RateLimitedError) {
+ *     console.log(error.data.retryAfter)
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link https://orpc.dev/docs/error-handling#error-factory | Error Handling - Error Factory}
+ */
+declare function error<TCode extends ORPCErrorCode, TData = unknown>(code: TCode, { data: dataSchema, message }?: ORPCErrorFactoryOptions<TData>): ORPCErrorFactory<TCode, TData>;
+type ORPCErrorConstructorMapItemOptions<TData> = Omit<ORPCErrorOptions<TData>, 'status'>;
+interface ORPCErrorConstructorMapItem<TCode extends ORPCErrorCode, TInData> {
+    (...rest: MaybeOptionalOptions<ORPCErrorConstructorMapItemOptions<TInData>>): ORPCError<TCode, TInData>;
+}
+type ORPCErrorConstructorMap<T extends ErrorMap> = {
+    [K in keyof T]: T[K] extends ErrorMapItem ? ORPCErrorConstructorMapItem<K & ORPCErrorCode, T[K]['data'] extends AnySchema ? InferSchemaInput<T[K]['data']> : unknown> : never;
+};
+/**
+ * Creates a map of ORPC error constructors.
+ *
+ * The returned object is a `Proxy` that allows access to arbitrary error codes:
+ * - If the code exists in the provided `errorMap`, the corresponding constructor
+ *   will create a **defined** `ORPCError`.
+ * - If the code does not exist, a fallback `ORPCError` constructor is returned.
+ *
+ * The `in` operator can be used to check whether an error code is explicitly
+ * defined in the map.
+ *
+ * @example
+ * ```ts
+ * const errorMap = createORPCErrorConstructorMap({
+ *   NOT_FOUND: {
+ *     message: 'Not Found',
+ *   },
+ * })
+ *
+ * throw errorMap.NOT_FOUND()
+ * ```
+ */
+declare function createORPCErrorConstructorMap<T extends ErrorMap>(errorMap: T): ORPCErrorConstructorMap<T>;
+
 interface PathMetaPlugin<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap> extends MetaPlugin<TInputSchema, TOutputSchema, TErrorMap> {
     name: '~path';
 }
+/**
+ * Built-in metadata plugins.
+ * `meta.path` records a procedure contract's path inside the root contract,
+ * which is required for the contract client factory pattern.
+ *
+ * @see {@link https://orpc.dev/docs/advanced/scaling-large-projects | Scaling Large Projects}
+ */
 declare const meta: {
     path<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap>(path: string[]): PathMetaPlugin<TInputSchema, TOutputSchema, TErrorMap>;
 };
@@ -143,6 +256,8 @@ declare function resolveMetaPlugins<TInputSchema extends AnySchema, TOutputSchem
  * @returns A `[metaPlugin, getMeta]` tuple:
  *   - `metaPlugin(metadata)` - Attaches metadata to a procedure under `name`.
  *   - `getMeta(procedureOrLazy)` - Retrieves the metadata, or `undefined` if not set.
+ *
+ * @see {@link https://orpc.dev/docs/metadata | Metadata}
  */
 declare function defineMeta<TName extends string, TData>(name: TName, merge: (incoming: TData, current: TData | undefined) => TData): [
     metaPlugin: (meta: TData) => AnyMetaPlugin & {
@@ -160,7 +275,10 @@ interface AsyncIteratorObjectSchemaDetails {
     returnSchema?: AnySchema;
 }
 /**
- * Define schema for an AsyncIteratorObject.
+ * Defines a schema for an AsyncIteratorObject, validating each yielded value
+ * (and optionally the return value) with the given schemas.
+ *
+ * @see {@link https://orpc.dev/docs/async-iterator-object | AsyncIteratorObject (SSE)}
  */
 declare function asyncIteratorObject<TYieldIn, TYieldOut, TReturnIn = unknown, TReturnOut = unknown>(yieldSchema: Schema<TYieldIn, TYieldOut>, returnSchema?: Schema<TReturnIn, TReturnOut>): Schema<AsyncIteratorObject<TYieldIn, TReturnIn, void>, AsyncIteratorClass<TYieldOut, TReturnOut, void>>;
 declare function getAsyncIteratorObjectSchemaDetails(schema: AnySchema | undefined): undefined | AsyncIteratorObjectSchemaDetails;
@@ -176,7 +294,7 @@ type TypeRest<TInput, TOutput> = [map: (input: TInput) => Promisable<TOutput>] |
  * const withMap = type<number, string>(input => input.toString())
  *```
  *
- * @see {@link https://orpc.dev/docs/procedure#type-utility Type Utility Docs}
+ * @see {@link https://orpc.dev/docs/procedure#type-utility | Procedure - type Utility}
  */
 declare function type<TInput, TOutput = TInput>(...[map]: TypeRest<TInput, TOutput>): Schema<TInput, TOutput>;
 /**
@@ -184,5 +302,5 @@ declare function type<TInput, TOutput = TInput>(...[map]: TypeRest<TInput, TOutp
  */
 declare function isSchemaIssue(issue: unknown): issue is SchemaIssue;
 
-export { AnyMetaPlugin, AnyProcedureContract, AnySchema, ContractBuilder, ErrorMap, InferSchemaInput, InferSchemaOutput, MergedSchema, Meta, MetaPlugin, ORPCErrorFromErrorMap, ProcedureContract, RouterContract, Schema, SchemaIssue, asyncIteratorObject, augmentContractRouter, createContractClientFactory, defineMeta, asyncIteratorObject as eventIterator, getAsyncIteratorObjectSchemaDetails, getPathMeta, getProcedureContractOrThrow, getRouterContract, isSchemaIssue, mergeErrorMap, meta, minifyRouterContract, oc, reconcileORPCError, resolveBasePathMeta, resolveMetaPlugins, type };
-export type { AsyncIteratorObjectSchemaDetails, AugmentContractRouterOptions, AugmentedContractRouter, ContractClientFactory, ContractClientFactoryOptions, InitialInputSchema, InitialOutputSchema, MergedErrorMap, PathMetaPlugin, ProcedureContractBuilderWithInput, ProcedureContractBuilderWithInputOutput, ProcedureContractBuilderWithOutput, ProcedureContractClient, RouterContractClient, TypeRest };
+export { AnyProcedureContract as AnyContractProcedure, RouterContract as AnyContractRouter, AnyMetaPlugin, AnyProcedureContract, AnySchema, ContractBuilder, ErrorMap, ErrorMapItem, InferSchemaInput, InferSchemaOutput, MergedSchema, Meta, MetaPlugin, ORPCErrorFromErrorMap, ProcedureContract, RouterContract, Schema, SchemaIssue, asyncIteratorObject, augmentContractRouter, createContractClientFactory, createORPCErrorConstructorMap, defineMeta, error, asyncIteratorObject as eventIterator, getAsyncIteratorObjectSchemaDetails, getRouterContract as getContractRouter, getPathMeta, getProcedureContractOrThrow, getRouterContract, isSchemaIssue, mergeErrorMap, meta, minifyRouterContract as minifyContractRouter, minifyRouterContract, oc, reconcileORPCError, resolveBasePathMeta, resolveMetaPlugins, type };
+export type { AsyncIteratorObjectSchemaDetails, AugmentContractRouterOptions, AugmentedContractRouter, ContractClientFactory, ContractClientFactoryOptions, InitialInputSchema, InitialOutputSchema, MergedErrorMap, ORPCErrorConstructorMap, ORPCErrorConstructorMapItem, ORPCErrorConstructorMapItemOptions, ORPCErrorFactory, ORPCErrorFactoryOptions, PathMetaPlugin, ProcedureContractBuilderWithInput, ProcedureContractBuilderWithInputOutput, ProcedureContractBuilderWithOutput, ProcedureContractClient, RouterContractClient, TypeRest };

package/dist/index.mjs

@@ -1,7 +1,7 @@
-import { isTypescriptObject, toArray, get, set, ORPC_NAME, isAsyncIteratorObject, isPropertyKey } from '@orpc/shared';
-import { P as ProcedureContract, r as resolveMetaPlugins, m as mergeErrorMap, a as augmentContractRouter, V as ValidationError } from './shared/contract.CW-2wl1i.mjs';
-export { d as defineMeta, g as getProcedureContractOrThrow, b as getRouterContract, c as minifyRouterContract, e as reconcileORPCError } from './shared/contract.CW-2wl1i.mjs';
-import { createORPCClient, wrapAsyncIteratorPreservingEventMeta, ORPCError } from '@orpc/client';
+import { isTypescriptObject, toArray, get, set, isPropertyKey, ORPC_NAME, resolveMaybeOptionalOptions, isAsyncIteratorObject } from '@orpc/shared';
+import { P as ProcedureContract, r as resolveMetaPlugins, m as mergeErrorMap, a as augmentContractRouter, V as ValidationError } from './shared/contract.CxBuBhym.mjs';
+export { d as defineMeta, g as getContractRouter, b as getProcedureContractOrThrow, g as getRouterContract, c as minifyContractRouter, c as minifyRouterContract, e as reconcileORPCError } from './shared/contract.CxBuBhym.mjs';
+import { createORPCClient, ORPCError, wrapAsyncIteratorPreservingEventMeta } from '@orpc/client';
 
 const HIDDEN_META_PLUGINS_SYMBOL = Symbol.for("ORPC_HIDDEN_META_PLUGINS");
 function getHiddenMetaPlugins(container) {
@@ -148,6 +148,105 @@ function createContractClientFactory(link, options = {}) {
   return factory;
 }
 
+function type(...[map]) {
+  return {
+    "~standard": {
+      vendor: ORPC_NAME,
+      version: 1,
+      async validate(value) {
+        if (map) {
+          return { value: await map(value) };
+        }
+        return { value };
+      }
+    }
+  };
+}
+function isSchemaIssue(issue) {
+  if (!isTypescriptObject(issue) || typeof issue.message !== "string") {
+    return false;
+  }
+  if (issue.path !== void 0) {
+    if (!Array.isArray(issue.path)) {
+      return false;
+    }
+    if (!issue.path.every((segment) => isPropertyKey(segment) || isTypescriptObject(segment) && isPropertyKey(segment.key))) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function error(code, { data: dataSchema, message } = {}) {
+  const validateData = (schema, value) => {
+    const result = schema["~standard"].validate(value);
+    if (result instanceof Promise) {
+      throw new TypeError(
+        `Error factory "${code}" does not support async data schemas.`
+      );
+    }
+    return result;
+  };
+  return class extends ORPCError {
+    static code = code;
+    static data = dataSchema ?? type();
+    static message = message;
+    constructor(...rest) {
+      const options = resolveMaybeOptionalOptions(rest);
+      let data = options.data;
+      if (dataSchema) {
+        const result = validateData(dataSchema, options.data);
+        if (result.issues) {
+          throw new ValidationError({
+            message: `Error factory "${code}" data validation failed`,
+            issues: result.issues,
+            invalidData: options.data
+          });
+        }
+        data = result.value;
+      }
+      super(code, { message, ...options, data });
+    }
+    static [Symbol.hasInstance](instance) {
+      if (!(instance instanceof ORPCError)) {
+        return false;
+      }
+      if (instance.code !== code) {
+        return false;
+      }
+      if (dataSchema && validateData(dataSchema, instance.data).issues) {
+        return false;
+      }
+      return true;
+    }
+  };
+}
+function createORPCErrorConstructorMap(errorMap) {
+  const proxy = new Proxy(errorMap, {
+    get(target, code) {
+      if (typeof code !== "string") {
+        return Reflect.get(target, code);
+      }
+      const item = (...rest) => {
+        const options = resolveMaybeOptionalOptions(rest);
+        const config = errorMap[code];
+        const error2 = new ORPCError(code, {
+          message: options.message ?? config?.message,
+          data: options.data,
+          cause: options.cause
+        });
+        if (config) {
+          error2.defined = true;
+          error2.inferable = true;
+        }
+        return error2;
+      };
+      return item;
+    }
+  });
+  return proxy;
+}
+
 const ASYNC_ITERATOR_OBJECT_SCHEMA_DETAILS_SYMBOL = Symbol.for("ORPC_ASYNC_ITERATOR_OBJECT_SCHEMA_DETAILS");
 function asyncIteratorObject(yieldSchema, returnSchema) {
   return {
@@ -191,33 +290,4 @@ function getAsyncIteratorObjectSchemaDetails(schema) {
   return schema["~standard"][ASYNC_ITERATOR_OBJECT_SCHEMA_DETAILS_SYMBOL];
 }
 
-function type(...[map]) {
-  return {
-    "~standard": {
-      vendor: ORPC_NAME,
-      version: 1,
-      async validate(value) {
-        if (map) {
-          return { value: await map(value) };
-        }
-        return { value };
-      }
-    }
-  };
-}
-function isSchemaIssue(issue) {
-  if (!isTypescriptObject(issue) || typeof issue.message !== "string") {
-    return false;
-  }
-  if (issue.path !== void 0) {
-    if (!Array.isArray(issue.path)) {
-      return false;
-    }
-    if (!issue.path.every((segment) => isPropertyKey(segment) || isTypescriptObject(segment) && isPropertyKey(segment.key))) {
-      return false;
-    }
-  }
-  return true;
-}
-
-export { ContractBuilder, HIDDEN_META_PLUGINS_SYMBOL, ProcedureContract, ValidationError, asyncIteratorObject, augmentContractRouter, createContractClientFactory, asyncIteratorObject as eventIterator, getAsyncIteratorObjectSchemaDetails, getHiddenMetaPlugins, getPathMeta, isSchemaIssue, mergeErrorMap, meta, oc, resolveBasePathMeta, resolveMetaPlugins, setHiddenMetaPlugins, type };
+export { ContractBuilder, HIDDEN_META_PLUGINS_SYMBOL, ProcedureContract, ValidationError, asyncIteratorObject, augmentContractRouter, createContractClientFactory, createORPCErrorConstructorMap, error, asyncIteratorObject as eventIterator, getAsyncIteratorObjectSchemaDetails, getHiddenMetaPlugins, getPathMeta, isSchemaIssue, mergeErrorMap, meta, oc, resolveBasePathMeta, resolveMetaPlugins, setHiddenMetaPlugins, type };

package/dist/plugins/index.d.mts

@@ -1,6 +1,6 @@
 import { ClientContext } from '@orpc/client';
 import { StandardLinkPlugin, StandardLinkOptions } from '@orpc/client/standard';
-import { R as RouterContract } from '../shared/contract.Do92aRJ4.mjs';
+import { R as RouterContract } from '../shared/contract.C06qWQqK.mjs';
 import '@orpc/shared';
 import '@standard-schema/spec';
 
@@ -18,6 +18,9 @@ interface RequestValidationLinkPluginOptions<_T extends ClientContext> {
 }
 /**
  * Validates client request input against contract schemas before the request is encoded.
+ * This is useful when your application relies on server-side validation.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/request-validation | Request Validation Plugin}
  */
 declare class RequestValidationLinkPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
     private readonly contract;
@@ -27,6 +30,12 @@ declare class RequestValidationLinkPlugin<T extends ClientContext> implements St
     init(options: StandardLinkOptions<T>): StandardLinkOptions<T>;
 }
 
+/**
+ * Validates server responses against contract schemas before your application uses them.
+ * This helps ensure the data returned by the server matches the types defined in your contract.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/response-validation | Response Validation Plugin}
+ */
 declare class ResponseValidationLinkPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
     private readonly contract;
     name: string;
@@ -34,5 +43,5 @@ declare class ResponseValidationLinkPlugin<T extends ClientContext> implements S
     init(options: StandardLinkOptions<T>): StandardLinkOptions<T>;
 }
 
-export { RequestValidationLinkPlugin, ResponseValidationLinkPlugin };
+export { RequestValidationLinkPlugin, RequestValidationLinkPlugin as RequestValidationPlugin, ResponseValidationLinkPlugin, ResponseValidationLinkPlugin as ResponseValidationPlugin };
 export type { RequestValidationLinkPluginOptions };

package/dist/plugins/index.d.ts

@@ -1,6 +1,6 @@
 import { ClientContext } from '@orpc/client';
 import { StandardLinkPlugin, StandardLinkOptions } from '@orpc/client/standard';
-import { R as RouterContract } from '../shared/contract.Do92aRJ4.js';
+import { R as RouterContract } from '../shared/contract.C06qWQqK.js';
 import '@orpc/shared';
 import '@standard-schema/spec';
 
@@ -18,6 +18,9 @@ interface RequestValidationLinkPluginOptions<_T extends ClientContext> {
 }
 /**
  * Validates client request input against contract schemas before the request is encoded.
+ * This is useful when your application relies on server-side validation.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/request-validation | Request Validation Plugin}
  */
 declare class RequestValidationLinkPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
     private readonly contract;
@@ -27,6 +30,12 @@ declare class RequestValidationLinkPlugin<T extends ClientContext> implements St
     init(options: StandardLinkOptions<T>): StandardLinkOptions<T>;
 }
 
+/**
+ * Validates server responses against contract schemas before your application uses them.
+ * This helps ensure the data returned by the server matches the types defined in your contract.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/response-validation | Response Validation Plugin}
+ */
 declare class ResponseValidationLinkPlugin<T extends ClientContext> implements StandardLinkPlugin<T> {
     private readonly contract;
     name: string;
@@ -34,5 +43,5 @@ declare class ResponseValidationLinkPlugin<T extends ClientContext> implements S
     init(options: StandardLinkOptions<T>): StandardLinkOptions<T>;
 }
 
-export { RequestValidationLinkPlugin, ResponseValidationLinkPlugin };
+export { RequestValidationLinkPlugin, RequestValidationLinkPlugin as RequestValidationPlugin, ResponseValidationLinkPlugin, ResponseValidationLinkPlugin as ResponseValidationPlugin };
 export type { RequestValidationLinkPluginOptions };

package/dist/plugins/index.mjs

@@ -1,6 +1,6 @@
 import { ORPCError } from '@orpc/client';
 import { toArray } from '@orpc/shared';
-import { g as getProcedureContractOrThrow, V as ValidationError, e as reconcileORPCError } from '../shared/contract.CW-2wl1i.mjs';
+import { b as getProcedureContractOrThrow, V as ValidationError, e as reconcileORPCError } from '../shared/contract.CxBuBhym.mjs';
 
 class RequestValidationLinkPlugin {
   constructor(contract, options = {}) {
@@ -87,4 +87,4 @@ class ResponseValidationLinkPlugin {
   }
 }
 
-export { RequestValidationLinkPlugin, ResponseValidationLinkPlugin };
+export { RequestValidationLinkPlugin, RequestValidationLinkPlugin as RequestValidationPlugin, ResponseValidationLinkPlugin, ResponseValidationLinkPlugin as ResponseValidationPlugin };

package/dist/shared/{contract.Do92aRJ4.d.mts → contract.C06qWQqK.d.mts}

@@ -6,27 +6,61 @@ import { StandardSchemaV1 } from '@standard-schema/spec';
  * TOutput default = TInput for better readability (shorter) in-case both TInput, TOutput is equal
  */
 type Schema<TInput, TOutput = TInput> = StandardSchemaV1<TInput, TOutput>;
+/**
+ * Any Standard Schema compatible schema, regardless of its input and output types.
+ *
+ * @see {@link https://orpc.dev/docs/integrations/standard-schema | Standard Schema Integration}
+ */
 type AnySchema = Schema<any>;
 type SchemaIssue = StandardSchemaV1.Issue;
+/**
+ * Infers the input type of a schema.
+ *
+ * @see {@link https://orpc.dev/docs/metadata | Metadata}
+ */
 type InferSchemaInput<T extends AnySchema> = T extends StandardSchemaV1<infer UInput, any> ? UInput : never;
+/**
+ * Infers the output type of a schema.
+ *
+ * @see {@link https://orpc.dev/docs/metadata | Metadata}
+ */
 type InferSchemaOutput<T extends AnySchema> = T extends StandardSchemaV1<any, infer UOutput> ? UOutput : never;
 type MergedSchema<T extends AnySchema, U extends AnySchema> = T extends Schema<infer TInput, infer TOutput> ? U extends Schema<infer UInput, infer UOutput> ? Schema<TInput & UInput, TOutput & UOutput> : never : never;
 
-interface ErrorMapItem<TDataSchema extends AnySchema> {
-    message?: string;
-    data?: TDataSchema;
+interface ErrorMapItem {
+    /**
+     * Default message, can be overridden when constructing an error.
+     */
+    message?: undefined | string;
+    /**
+     * Schema used to type and validate the error data.
+     */
+    data?: undefined | AnySchema;
 }
+/**
+ * Map of error codes to their definitions, as passed to `.errors(...)`.
+ * Errors defined here remain properly typed on the client.
+ *
+ * @see {@link https://orpc.dev/docs/metadata | Metadata}
+ */
 type ErrorMap = {
-    [key in ORPCErrorCode]?: ErrorMapItem<AnySchema>;
+    [key in ORPCErrorCode]?: ErrorMapItem;
 };
 type ORPCErrorFromErrorMap<TErrorMap extends ErrorMap> = {
-    [K in keyof TErrorMap]: K extends string ? TErrorMap[K] extends ErrorMapItem<infer TDataSchema extends Schema<unknown>> ? ORPCError<K, InferSchemaOutput<TDataSchema>> : never : never;
+    [K in keyof TErrorMap]: TErrorMap[K] extends ErrorMapItem ? ORPCError<K & ORPCErrorCode, TErrorMap[K]['data'] extends AnySchema ? InferSchemaOutput<TErrorMap[K]['data']> : unknown> : never;
 }[keyof TErrorMap];
 interface ValidationErrorOptions extends ErrorOptions {
     message: string;
     issues: readonly SchemaIssue[];
     invalidData: unknown;
 }
+/**
+ * Error thrown when input, output, or error data fails schema validation,
+ * carrying the standard-schema `issues` and the invalid data.
+ * Usually found as the `cause` of an `ORPCError`.
+ *
+ * @see {@link https://orpc.dev/docs/advanced/validation-customization | Validation Customization}
+ */
 declare class ValidationError extends Error {
     /**
      * This array is readonly because the upstream Standard Schema returns readonly issues.
@@ -36,6 +70,12 @@ declare class ValidationError extends Error {
     constructor(options: ValidationErrorOptions);
 }
 
+/**
+ * Arbitrary metadata attached to a procedure.
+ * Middleware, plugins, and tooling can read it later to control behavior.
+ *
+ * @see {@link https://orpc.dev/docs/metadata | Metadata}
+ */
 interface Meta {
     [key: PropertyKey]: unknown;
 }
@@ -50,6 +90,12 @@ interface MetaPluginDefinition<TInputSchema extends AnySchema, TOutputSchema ext
         type: TErrorMap;
     };
 }
+/**
+ * A metadata plugin passed to `.meta(...)`.
+ * Defines how metadata is initialized and merged, and can infer or restrict procedure types.
+ *
+ * @see {@link https://orpc.dev/docs/metadata | Metadata}
+ */
 interface MetaPlugin<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap> {
     /** This only for types, so it should be optional */
     '~orpc'?: MetaPluginDefinition<TInputSchema, TOutputSchema, TErrorMap> | undefined;
@@ -66,6 +112,12 @@ interface MetaPlugin<TInputSchema extends AnySchema, TOutputSchema extends AnySc
      */
     'apply'?: (meta: Meta) => Meta;
 }
+/**
+ * A `MetaPlugin` with all type parameters relaxed to `any`.
+ *
+ * @see {@link https://orpc.dev/docs/contract/procedure | Procedure Contract}
+ * @see {@link https://orpc.dev/docs/procedure | Procedure}
+ */
 type AnyMetaPlugin = MetaPlugin<any, any, any>;
 declare const HIDDEN_META_PLUGINS_SYMBOL: unique symbol;
 declare function getHiddenMetaPlugins(container: unknown): AnyMetaPlugin[] | undefined;
@@ -91,36 +143,60 @@ declare class ProcedureContract<TInputSchema extends AnySchema, TOutputSchema ex
     '~orpc': ProcedureContractDefinition<TInputSchema, TOutputSchema, TErrorMap>;
     constructor(def: ProcedureContractDefinition<TInputSchema, TOutputSchema, TErrorMap>);
     /**
-     * Checks if the given instance satisfies the {@see ProcedureContract} class/interface.
+     * Checks if the given instance satisfies the {@link ProcedureContract} class/interface.
      */
     static [Symbol.hasInstance](instance: unknown): boolean;
 }
 type AnyProcedureContract = ProcedureContract<any, any, any>;
 
+/**
+ * A router contract: a single procedure contract or a nested record of them.
+ *
+ * @see {@link https://orpc.dev/docs/advanced/scaling-large-projects | Scaling Large Projects}
+ */
 type RouterContract = AnyProcedureContract | {
     [k: string]: RouterContract;
 };
+/**
+ * Infer the input types for each procedure-contract, preserving the router-contract shape.
+ *
+ * @see {@link https://orpc.dev/docs/contract/router#infer-router-contract-inputs | Router Contract - Infer Router Contract Inputs}
+ */
 type InferRouterContractInputs<T extends RouterContract> = T extends ProcedureContract<infer UInputSchema, any, any> ? InferSchemaInput<UInputSchema> : {
     [K in keyof T]: T[K] extends RouterContract ? InferRouterContractInputs<T[K]> : never;
 };
+/**
+ * Infer the output types for each procedure-contract, preserving the router-contract shape.
+ *
+ * @see {@link https://orpc.dev/docs/contract/router#infer-router-contract-outputs | Router Contract - Infer Router Contract Outputs}
+ */
 type InferRouterContractOutputs<T extends RouterContract> = T extends ProcedureContract<any, infer UOutputSchema, any> ? InferSchemaOutput<UOutputSchema> : {
     [K in keyof T]: T[K] extends RouterContract ? InferRouterContractOutputs<T[K]> : never;
 };
+/**
+ * Infer the union of error maps defined across the entire router-contract.
+ *
+ * @see {@link https://orpc.dev/docs/contract/router#infer-router-contract-error-map | Router Contract - Infer Router Contract Error Map}
+ */
 type InferRouterContractErrorMap<T extends RouterContract> = T extends ProcedureContract<any, any, infer UErrorMap> ? UErrorMap : {
     [K in keyof T]: T[K] extends RouterContract ? InferRouterContractErrorMap<T[K]> : never;
 }[keyof T];
 /**
  * Infer the union of throwable errors for entire router-contract.
+ *
+ * @see {@link https://orpc.dev/docs/contract/router#infer-router-contract-error | Router Contract - Infer Router Contract Error}
  */
 type InferRouterContractError<T extends RouterContract> = T extends ProcedureContract<any, any, infer UErrorMap> ? ORPCErrorFromErrorMap<UErrorMap> | ThrowableError : {
     [K in keyof T]: T[K] extends RouterContract ? InferRouterContractError<T[K]> : never;
 }[keyof T];
 /**
  * Infer throwable errors for each procedure-contract, preserving the router-contract shape.
+ *
+ * @see {@link https://orpc.dev/docs/contract/router#infer-router-contract-errors | Router Contract - Infer Router Contract Errors}
  */
 type InferRouterContractErrors<T extends RouterContract> = T extends ProcedureContract<any, any, infer UErrorMap> ? ORPCErrorFromErrorMap<UErrorMap> | ThrowableError : {
     [K in keyof T]: T[K] extends RouterContract ? InferRouterContractErrors<T[K]> : never;
 };
 
 export { HIDDEN_META_PLUGINS_SYMBOL as H, ProcedureContract as P, ValidationError as V, getHiddenMetaPlugins as p, setHiddenMetaPlugins as s };
-export type { AnySchema as A, ErrorMap as E, InferSchemaInput as I, MetaPlugin as M, ORPCErrorFromErrorMap as O, RouterContract as R, Schema as S, MergedSchema as a, Meta as b, AnyMetaPlugin as c, AnyProcedureContract as d, InferSchemaOutput as e, SchemaIssue as f, ErrorMapItem as g, InferRouterContractError as h, InferRouterContractErrorMap as i, InferRouterContractErrors as j, InferRouterContractInputs as k, InferRouterContractOutputs as l, MetaPluginDefinition as m, ProcedureContractDefinition as n, ValidationErrorOptions as o };
+export type { AnySchema as A, ErrorMap as E, InferSchemaInput as I, MetaPlugin as M, ORPCErrorFromErrorMap as O, RouterContract as R, Schema as S, MergedSchema as a, Meta as b, AnyMetaPlugin as c, AnyProcedureContract as d, InferSchemaOutput as e, ErrorMapItem as f, SchemaIssue as g, InferRouterContractErrorMap as h, InferRouterContractInputs as i, InferRouterContractOutputs as j, InferRouterContractError as k, InferRouterContractErrors as l, MetaPluginDefinition as m, ProcedureContractDefinition as n, ValidationErrorOptions as o };

package/dist/shared/{contract.Do92aRJ4.d.ts → contract.C06qWQqK.d.ts}

@@ -6,27 +6,61 @@ import { StandardSchemaV1 } from '@standard-schema/spec';
  * TOutput default = TInput for better readability (shorter) in-case both TInput, TOutput is equal
  */
 type Schema<TInput, TOutput = TInput> = StandardSchemaV1<TInput, TOutput>;
+/**
+ * Any Standard Schema compatible schema, regardless of its input and output types.
+ *
+ * @see {@link https://orpc.dev/docs/integrations/standard-schema | Standard Schema Integration}
+ */
 type AnySchema = Schema<any>;
 type SchemaIssue = StandardSchemaV1.Issue;
+/**
+ * Infers the input type of a schema.
+ *
+ * @see {@link https://orpc.dev/docs/metadata | Metadata}
+ */
 type InferSchemaInput<T extends AnySchema> = T extends StandardSchemaV1<infer UInput, any> ? UInput : never;
+/**
+ * Infers the output type of a schema.
+ *
+ * @see {@link https://orpc.dev/docs/metadata | Metadata}
+ */
 type InferSchemaOutput<T extends AnySchema> = T extends StandardSchemaV1<any, infer UOutput> ? UOutput : never;
 type MergedSchema<T extends AnySchema, U extends AnySchema> = T extends Schema<infer TInput, infer TOutput> ? U extends Schema<infer UInput, infer UOutput> ? Schema<TInput & UInput, TOutput & UOutput> : never : never;
 
-interface ErrorMapItem<TDataSchema extends AnySchema> {
-    message?: string;
-    data?: TDataSchema;
+interface ErrorMapItem {
+    /**
+     * Default message, can be overridden when constructing an error.
+     */
+    message?: undefined | string;
+    /**
+     * Schema used to type and validate the error data.
+     */
+    data?: undefined | AnySchema;
 }
+/**
+ * Map of error codes to their definitions, as passed to `.errors(...)`.
+ * Errors defined here remain properly typed on the client.
+ *
+ * @see {@link https://orpc.dev/docs/metadata | Metadata}
+ */
 type ErrorMap = {
-    [key in ORPCErrorCode]?: ErrorMapItem<AnySchema>;
+    [key in ORPCErrorCode]?: ErrorMapItem;
 };
 type ORPCErrorFromErrorMap<TErrorMap extends ErrorMap> = {
-    [K in keyof TErrorMap]: K extends string ? TErrorMap[K] extends ErrorMapItem<infer TDataSchema extends Schema<unknown>> ? ORPCError<K, InferSchemaOutput<TDataSchema>> : never : never;
+    [K in keyof TErrorMap]: TErrorMap[K] extends ErrorMapItem ? ORPCError<K & ORPCErrorCode, TErrorMap[K]['data'] extends AnySchema ? InferSchemaOutput<TErrorMap[K]['data']> : unknown> : never;
 }[keyof TErrorMap];
 interface ValidationErrorOptions extends ErrorOptions {
     message: string;
     issues: readonly SchemaIssue[];
     invalidData: unknown;
 }
+/**
+ * Error thrown when input, output, or error data fails schema validation,
+ * carrying the standard-schema `issues` and the invalid data.
+ * Usually found as the `cause` of an `ORPCError`.
+ *
+ * @see {@link https://orpc.dev/docs/advanced/validation-customization | Validation Customization}
+ */
 declare class ValidationError extends Error {
     /**
      * This array is readonly because the upstream Standard Schema returns readonly issues.
@@ -36,6 +70,12 @@ declare class ValidationError extends Error {
     constructor(options: ValidationErrorOptions);
 }
 
+/**
+ * Arbitrary metadata attached to a procedure.
+ * Middleware, plugins, and tooling can read it later to control behavior.
+ *
+ * @see {@link https://orpc.dev/docs/metadata | Metadata}
+ */
 interface Meta {
     [key: PropertyKey]: unknown;
 }
@@ -50,6 +90,12 @@ interface MetaPluginDefinition<TInputSchema extends AnySchema, TOutputSchema ext
         type: TErrorMap;
     };
 }
+/**
+ * A metadata plugin passed to `.meta(...)`.
+ * Defines how metadata is initialized and merged, and can infer or restrict procedure types.
+ *
+ * @see {@link https://orpc.dev/docs/metadata | Metadata}
+ */
 interface MetaPlugin<TInputSchema extends AnySchema, TOutputSchema extends AnySchema, TErrorMap extends ErrorMap> {
     /** This only for types, so it should be optional */
     '~orpc'?: MetaPluginDefinition<TInputSchema, TOutputSchema, TErrorMap> | undefined;
@@ -66,6 +112,12 @@ interface MetaPlugin<TInputSchema extends AnySchema, TOutputSchema extends AnySc
      */
     'apply'?: (meta: Meta) => Meta;
 }
+/**
+ * A `MetaPlugin` with all type parameters relaxed to `any`.
+ *
+ * @see {@link https://orpc.dev/docs/contract/procedure | Procedure Contract}
+ * @see {@link https://orpc.dev/docs/procedure | Procedure}
+ */
 type AnyMetaPlugin = MetaPlugin<any, any, any>;
 declare const HIDDEN_META_PLUGINS_SYMBOL: unique symbol;
 declare function getHiddenMetaPlugins(container: unknown): AnyMetaPlugin[] | undefined;
@@ -91,36 +143,60 @@ declare class ProcedureContract<TInputSchema extends AnySchema, TOutputSchema ex
     '~orpc': ProcedureContractDefinition<TInputSchema, TOutputSchema, TErrorMap>;
     constructor(def: ProcedureContractDefinition<TInputSchema, TOutputSchema, TErrorMap>);
     /**
-     * Checks if the given instance satisfies the {@see ProcedureContract} class/interface.
+     * Checks if the given instance satisfies the {@link ProcedureContract} class/interface.
      */
     static [Symbol.hasInstance](instance: unknown): boolean;
 }
 type AnyProcedureContract = ProcedureContract<any, any, any>;
 
+/**
+ * A router contract: a single procedure contract or a nested record of them.
+ *
+ * @see {@link https://orpc.dev/docs/advanced/scaling-large-projects | Scaling Large Projects}
+ */
 type RouterContract = AnyProcedureContract | {
     [k: string]: RouterContract;
 };
+/**
+ * Infer the input types for each procedure-contract, preserving the router-contract shape.
+ *
+ * @see {@link https://orpc.dev/docs/contract/router#infer-router-contract-inputs | Router Contract - Infer Router Contract Inputs}
+ */
 type InferRouterContractInputs<T extends RouterContract> = T extends ProcedureContract<infer UInputSchema, any, any> ? InferSchemaInput<UInputSchema> : {
     [K in keyof T]: T[K] extends RouterContract ? InferRouterContractInputs<T[K]> : never;
 };
+/**
+ * Infer the output types for each procedure-contract, preserving the router-contract shape.
+ *
+ * @see {@link https://orpc.dev/docs/contract/router#infer-router-contract-outputs | Router Contract - Infer Router Contract Outputs}
+ */
 type InferRouterContractOutputs<T extends RouterContract> = T extends ProcedureContract<any, infer UOutputSchema, any> ? InferSchemaOutput<UOutputSchema> : {
     [K in keyof T]: T[K] extends RouterContract ? InferRouterContractOutputs<T[K]> : never;
 };
+/**
+ * Infer the union of error maps defined across the entire router-contract.
+ *
+ * @see {@link https://orpc.dev/docs/contract/router#infer-router-contract-error-map | Router Contract - Infer Router Contract Error Map}
+ */
 type InferRouterContractErrorMap<T extends RouterContract> = T extends ProcedureContract<any, any, infer UErrorMap> ? UErrorMap : {
     [K in keyof T]: T[K] extends RouterContract ? InferRouterContractErrorMap<T[K]> : never;
 }[keyof T];
 /**
  * Infer the union of throwable errors for entire router-contract.
+ *
+ * @see {@link https://orpc.dev/docs/contract/router#infer-router-contract-error | Router Contract - Infer Router Contract Error}
  */
 type InferRouterContractError<T extends RouterContract> = T extends ProcedureContract<any, any, infer UErrorMap> ? ORPCErrorFromErrorMap<UErrorMap> | ThrowableError : {
     [K in keyof T]: T[K] extends RouterContract ? InferRouterContractError<T[K]> : never;
 }[keyof T];
 /**
  * Infer throwable errors for each procedure-contract, preserving the router-contract shape.
+ *
+ * @see {@link https://orpc.dev/docs/contract/router#infer-router-contract-errors | Router Contract - Infer Router Contract Errors}
  */
 type InferRouterContractErrors<T extends RouterContract> = T extends ProcedureContract<any, any, infer UErrorMap> ? ORPCErrorFromErrorMap<UErrorMap> | ThrowableError : {
     [K in keyof T]: T[K] extends RouterContract ? InferRouterContractErrors<T[K]> : never;
 };
 
 export { HIDDEN_META_PLUGINS_SYMBOL as H, ProcedureContract as P, ValidationError as V, getHiddenMetaPlugins as p, setHiddenMetaPlugins as s };
-export type { AnySchema as A, ErrorMap as E, InferSchemaInput as I, MetaPlugin as M, ORPCErrorFromErrorMap as O, RouterContract as R, Schema as S, MergedSchema as a, Meta as b, AnyMetaPlugin as c, AnyProcedureContract as d, InferSchemaOutput as e, SchemaIssue as f, ErrorMapItem as g, InferRouterContractError as h, InferRouterContractErrorMap as i, InferRouterContractErrors as j, InferRouterContractInputs as k, InferRouterContractOutputs as l, MetaPluginDefinition as m, ProcedureContractDefinition as n, ValidationErrorOptions as o };
+export type { AnySchema as A, ErrorMap as E, InferSchemaInput as I, MetaPlugin as M, ORPCErrorFromErrorMap as O, RouterContract as R, Schema as S, MergedSchema as a, Meta as b, AnyMetaPlugin as c, AnyProcedureContract as d, InferSchemaOutput as e, ErrorMapItem as f, SchemaIssue as g, InferRouterContractErrorMap as h, InferRouterContractInputs as i, InferRouterContractOutputs as j, InferRouterContractError as k, InferRouterContractErrors as l, MetaPluginDefinition as m, ProcedureContractDefinition as n, ValidationErrorOptions as o };

package/dist/shared/{contract.CW-2wl1i.mjs → contract.CxBuBhym.mjs}

@@ -82,7 +82,7 @@ class ProcedureContract {
     this["~orpc"] = def;
   }
   /**
-   * Checks if the given instance satisfies the {@see ProcedureContract} class/interface.
+   * Checks if the given instance satisfies the {@link ProcedureContract} class/interface.
    */
   static [Symbol.hasInstance](instance) {
     if (this !== ProcedureContract) {
@@ -177,4 +177,4 @@ class ValidationError extends Error {
   }
 }
 
-export { ProcedureContract as P, ValidationError as V, augmentContractRouter as a, getRouterContract as b, minifyRouterContract as c, defineMeta as d, reconcileORPCError as e, getProcedureContractOrThrow as g, mergeErrorMap as m, resolveMetaPlugins as r };
+export { ProcedureContract as P, ValidationError as V, augmentContractRouter as a, getProcedureContractOrThrow as b, minifyRouterContract as c, defineMeta as d, reconcileORPCError as e, getRouterContract as g, mergeErrorMap as m, resolveMetaPlugins as r };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@orpc/contract",
   "type": "module",
-  "version": "2.0.0-beta.22",
+  "version": "2.0.0-beta.24",
   "license": "MIT",
   "homepage": "https://orpc.dev",
   "repository": {
@@ -31,8 +31,8 @@
   ],
   "dependencies": {
     "@standard-schema/spec": "^1.1.0",
-    "@orpc/client": "2.0.0-beta.22",
-    "@orpc/shared": "2.0.0-beta.22"
+    "@orpc/client": "2.0.0-beta.24",
+    "@orpc/shared": "2.0.0-beta.24"
   },
   "devDependencies": {
     "arktype": "^2.2.1",