@orpc/openapi 2.0.0-beta.3 → 2.0.0-beta.30

package/dist/shared/{openapi.B2SK0ZAr.mjs → openapi.BlHXe8vI.mjs}

@@ -1,14 +1,13 @@
-import { isORPCErrorJson, createORPCErrorFromJson, ORPCError } from '@orpc/client';
+import { createORPCErrorFromMalformedResponse, isORPCErrorJson, createORPCErrorFromJson } from '@orpc/client';
 import { getRouterContract, ProcedureContract } from '@orpc/contract';
 import { unlazy } from '@orpc/server';
 import { value, pathToHttpPath, mergeHttpPath, isTypescriptObject, stringifyJSON } from '@orpc/shared';
-import { mergeStandardHeaders, parseStandardUrl, isStandardHeaders } from '@standardserver/core';
+import { mergeStandardHeaders, parseStandardUrl } from '@standardserver/core';
 import { toStandardHeaders } from '@standardserver/fetch';
-import { O as OpenAPISerializer, D as DEFAULT_OPENAPI_METHOD, a as DEFAULT_OPENAPI_INPUT_STRUCTURE, g as getDynamicPathParams, b as DEFAULT_OPENAPI_OUTPUT_STRUCTURE } from './openapi.DmAa7YPO.mjs';
+import { O as OpenAPISerializer, D as DEFAULT_OPENAPI_METHOD, a as DEFAULT_OPENAPI_INPUT_STRUCTURE, g as getDynamicPathParams, i as isBodylessMethod, b as DEFAULT_OPENAPI_OUTPUT_STRUCTURE } from './openapi.0yE-t1W-.mjs';
 import { g as getOpenAPIMeta } from './openapi.B9PQzqBn.mjs';
+import { s as serializeHeaders } from './openapi.BaqI61Xi.mjs';
 
-class OpenAPILinkCodecError extends TypeError {
-}
 const END_SLASH_REGEX = /\/$/;
 class OpenAPILinkCodec {
   constructor(router, options = {}) {
@@ -42,7 +41,7 @@ class OpenAPILinkCodec {
       let data = input;
       if (dynamicParams?.length) {
         if (!isTypescriptObject(input)) {
-          throw new OpenAPILinkCodecError(
+          throw new TypeError(
             `Input must be an object with "compact" input structure when the path has dynamic params (${dynamicParams.map((p) => p.parameterName).join(", ")}) in call to procedure (${path.join(".")}).`
           );
         }
@@ -56,7 +55,7 @@ class OpenAPILinkCodec {
         data = Object.keys(remaining).length > 0 ? remaining : void 0;
       }
       pathname = `${basePathname.replace(END_SLASH_REGEX, "")}${pathname}`;
-      if (method === "GET") {
+      if (isBodylessMethod(method)) {
         const queryString2 = this.serializeQueryString(data, meta?.queryStyles);
         const search2 = combineSearch(baseSearch, queryString2);
         const url3 = `${pathname}${search2 ?? ""}${baseHash ?? ""}`;
@@ -78,12 +77,12 @@ class OpenAPILinkCodec {
       };
     }
     if (!isValidDetailedInput(input)) {
-      throw new OpenAPILinkCodecError(`
+      throw new TypeError(`
         Invalid "detailed" input structure in call to procedure (${path.join(".")}):
         \u2022 Expected an object or undefined with optional properties:
           - params (object, required when the path has dynamic params)
           - query (object)
-          - headers (Record<string, string | string[] | undefined>)
+          - headers (object)
           - body (any)
 
         Actual value:
@@ -92,7 +91,7 @@ class OpenAPILinkCodec {
     }
     if (dynamicParams?.length) {
       if (!input?.params) {
-        throw new OpenAPILinkCodecError(
+        throw new TypeError(
           `The "params" property is required for "detailed" input when the path has dynamic params (${dynamicParams.map((p) => p.parameterName).join(", ")}) in call to procedure (${path.join(".")}).`
         );
       }
@@ -104,13 +103,13 @@ class OpenAPILinkCodec {
       }
     }
     if (input?.headers) {
-      headers = mergeStandardHeaders(headers, input.headers);
+      headers = mergeStandardHeaders(headers, serializeHeaders(input.headers, this.serializer));
     }
     pathname = `${basePathname.replace(END_SLASH_REGEX, "")}${pathname}`;
     const queryString = this.serializeQueryString(input?.query, meta?.queryStyles);
     const search = combineSearch(baseSearch, queryString);
     const url = `${pathname}${search ?? ""}${baseHash ?? ""}`;
-    if (method === "GET") {
+    if (isBodylessMethod(method)) {
       return {
         body: void 0,
         method,
@@ -144,7 +143,7 @@ class OpenAPILinkCodec {
       }
     }
     if (!encoded) {
-      throw new OpenAPILinkCodecError(`Path param "${param.parameterName}" cannot be empty in call to procedure (${path.join(".")}).`);
+      throw new TypeError(`Path param "${param.parameterName}" cannot be empty in call to procedure (${path.join(".")}).`);
     }
     return encoded;
   }
@@ -243,22 +242,17 @@ class OpenAPILinkCodec {
     return query || void 0;
   }
   async decodeResponse(response, path, _options) {
-    const isOk = response.status >= 200 && response.status < 400;
+    const isOk = response.status < 400;
     const procedure = await this.resolveProcedure(path);
     const meta = getOpenAPIMeta(procedure);
+    const body = await response.resolveBody(meta?.responseBodyHint);
     const deserialized = await (async () => {
-      let isBodyOk = false;
       try {
-        const body = await response.resolveBody(meta?.responseBodyHint);
-        isBodyOk = true;
         return this.serializer.deserialize(body);
       } catch (error) {
-        if (!isBodyOk) {
-          throw new Error("Cannot parse response body, please check the response body and content-type.", {
-            cause: error
-          });
-        }
-        throw new Error("Invalid OpenAPI response format.", {
+        throw createORPCErrorFromMalformedResponse({
+          message: "Invalid OpenAPI response format.",
+          response: { status: response.status, headers: response.headers, body },
           cause: error
         });
       }
@@ -273,9 +267,7 @@ class OpenAPILinkCodec {
       }
       return {
         kind: "error",
-        error: new ORPCError("MALFORMED_ORPC_ERROR_RESPONSE", {
-          data: { headers: response.headers, status: response.status, body: deserialized }
-        })
+        error: createORPCErrorFromMalformedResponse({ response: { headers: response.headers, status: response.status, body } })
       };
     }
     const outputStructure = meta?.outputStructure ?? DEFAULT_OPENAPI_OUTPUT_STRUCTURE;
@@ -291,7 +283,7 @@ class OpenAPILinkCodec {
   async resolveProcedure(path) {
     const { default: maybeProcedure } = await unlazy(getRouterContract(this.router, path));
     if (!(maybeProcedure instanceof ProcedureContract)) {
-      throw new OpenAPILinkCodecError(`Expected a procedure or contract at path (${path.join(".")})`);
+      throw new TypeError(`Expected a procedure or contract at path (${path.join(".")})`);
     }
     return maybeProcedure;
   }
@@ -324,7 +316,7 @@ function isValidDetailedInput(input) {
   if (input.query !== void 0 && !isTypescriptObject(input.query)) {
     return false;
   }
-  if (input.headers !== void 0 && !isStandardHeaders(input.headers)) {
+  if (input.headers !== void 0 && !isTypescriptObject(input.headers)) {
     return false;
   }
   return true;
@@ -356,4 +348,4 @@ function encodeDelimitedObject(entries, encodedDelimiter) {
   ).join(encodedDelimiter);
 }
 
-export { OpenAPILinkCodec as O, OpenAPILinkCodecError as a };
+export { OpenAPILinkCodec as O };

package/dist/shared/openapi.D1CqEIRy.d.ts

@@ -0,0 +1,45 @@
+import { ClientContext, ClientOptions, AnyORPCError } from '@orpc/client';
+import { StandardLinkCodec, StandardLinkCodecDecodedResponse } from '@orpc/client/standard';
+import { RouterContract } from '@orpc/contract';
+import { Value, Promisable } from '@orpc/shared';
+import { StandardUrl, StandardHeaders, StandardLazyResponse, StandardRequest } from '@standardserver/core';
+import { O as OpenAPISerializer } from './openapi.Dz-JaXHo.js';
+
+interface OpenAPILinkCodecOptions<T extends ClientContext> {
+    /**
+     * Base URL for all requests, without origin. Should match the OpenAPI handler mount path.
+     *
+     * @example '/api'
+     * @default '/'
+     */
+    url?: Value<Promisable<StandardUrl>, [options: ClientOptions<T>, path: string[], input: unknown]>;
+    /**
+     * Inject headers into the request.
+     */
+    headers?: Value<Promisable<StandardHeaders | Headers>, [options: ClientOptions<T>, path: string[], input: unknown]>;
+    /**
+     * Override the default OpenAPI serializer.
+     */
+    serializer?: Pick<OpenAPISerializer, keyof OpenAPISerializer>;
+    /**
+     * Customize how an error response body is converted into an ORPC error.
+     * Return `null` or `undefined` to fall back to the default decoding behavior.
+     */
+    customErrorResponseBodyDecoder?: (deserializedBody: unknown, response: StandardLazyResponse) => AnyORPCError | null | undefined;
+}
+declare class OpenAPILinkCodec<T extends ClientContext> implements StandardLinkCodec<T> {
+    private readonly router;
+    private readonly baseUrl;
+    private readonly headers;
+    private readonly serializer;
+    private readonly customErrorResponseBodyDecoder;
+    constructor(router: RouterContract, options?: OpenAPILinkCodecOptions<T>);
+    encodeInput(input: unknown, path: string[], options: ClientOptions<T>): Promise<StandardRequest>;
+    private encodePathParam;
+    private serializeQueryString;
+    decodeResponse(response: StandardLazyResponse, path: string[], _options: ClientOptions<T>): Promise<StandardLinkCodecDecodedResponse>;
+    private resolveProcedure;
+}
+
+export { OpenAPILinkCodec as a };
+export type { OpenAPILinkCodecOptions as O };

package/dist/shared/{openapi.BQzzr4-4.d.ts → openapi.DTYZZ6Ph.d.ts}

@@ -2,7 +2,7 @@ import { AnySchema, ErrorMap, MetaPlugin, AnyProcedureContract } from '@orpc/con
 import { Lazy } from '@orpc/server';
 import { Value } from '@orpc/shared';
 import { StandardBodyHint } from '@standardserver/core';
-import { O as OpenAPIOperationObject } from './openapi.CYgMBSUF.js';
+import { d as OpenAPIOperationObject } from './openapi.DfTTLtn5.js';
 
 interface OpenAPIMeta {
     /**
@@ -10,11 +10,12 @@ interface OpenAPIMeta {
      *
      * @default 'POST'
      */
-    method?: 'HEAD' | 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | undefined;
+    method?: 'HEAD' | 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'QUERY' | undefined;
     /**
-     * URL path for this procedure. Supports dynamic segments via `${}` syntax.
+     * URL path for this procedure. Supports dynamic parameters via `{param}` syntax,
+     * and `{+param}` to allow slashes in the matched value.
      *
-     * @example `/users`, `/users/${id}`
+     * @example `/users`, `/users/{id}`, `/files/{+path}`
      * @default Router segments joined by `'/`
      */
     path?: `/${string}` | undefined;
@@ -39,11 +40,13 @@ interface OpenAPIMeta {
     /**
      * Tags associated with this procedure.
      *
-     * **Note**: Tags are merged when defined multiple times.
+     * **Merging**: When defined multiple times, tags are concatenated in definition order.
+     * Explicitly setting `undefined` resets the tags instead of merging.
      */
     tags?: string[] | undefined;
     /**
-     * HTTP status code returned on success. Must be in the 200–399 range.
+     * HTTP status code returned on success.
+     * Should be in the `2xx` range and must be less than `400`.
      *
      * @default 200
      */
@@ -57,7 +60,9 @@ interface OpenAPIMeta {
     /**
      * Controls how individual path parameters are decoded.
      *
-     * **Note**: Param styles are merged when defined multiple times.
+     * **Merging**: When defined multiple times, styles are merged per parameter.
+     * The most recent style defined for a parameter wins.
+     * Explicitly setting `undefined` resets the styles instead of merging.
      *
      * Each key maps a path parameter name to one of the following strategies:
      *
@@ -102,7 +107,9 @@ interface OpenAPIMeta {
     /**
      * Controls how individual query parameters are encoding/decoding.
      *
-     * **Note**: Query styles are merged when defined multiple times.
+     * **Merging**: When defined multiple times, styles are merged per parameter.
+     * The most recent style defined for a parameter wins.
+     * Explicitly setting `undefined` resets the styles instead of merging.
      *
      * Each key maps a query parameter name to one of the following strategies:
      *
@@ -260,13 +267,20 @@ interface OpenAPIMeta {
      * Pass a plain object to replace entire operation object, or a function that receives the current
      * operation object and returns the modified version.
      *
-     * **Note**: Spec is merged when defined multiple times.
+     * **Merging**: When defined multiple times:
+     *
+     * - Two functions are chained: the most recent function receives the result of the previous one.
+     * - A function combined with an object: the function is applied to that object.
+     * - Two objects: the most recent object wins.
+     *
+     * Explicitly setting `undefined` resets the spec instead of merging.
      */
     spec?: Value<OpenAPIOperationObject, [current: OpenAPIOperationObject]>;
     /**
      * Prefix for the path. Useful when you want to apply a common path prefix across multiple procedures.
      *
-     * **Note**: Prefixes are merged when defined multiple times.
+     * **Merging**: When defined multiple times, prefixes are concatenated in definition order.
+     * Explicitly setting `undefined` resets the prefix instead of merging.
      */
     prefix?: `/${string}` | undefined;
 }
@@ -292,7 +306,19 @@ interface OpenAPIFunction {
     spec(method: OpenAPIMeta['spec']): OpenAPISpecMetaPlugin<any, any, any>;
     prefix(method: OpenAPIMeta['prefix']): OpenAPIPrefixMetaPlugin<any, any, any>;
 }
+/**
+ * Creates OpenAPI meta plugins that control how a procedure is exposed over HTTP,
+ * such as its method, path, prefix, and OpenAPI operation spec.
+ *
+ * @see {@link https://orpc.dev/docs/openapi/routing | OpenAPI Routing}
+ * @see {@link https://orpc.dev/docs/openapi/specification | OpenAPI Specification}
+ */
 declare const openapi: OpenAPIFunction;
+/**
+ * Retrieves the OpenAPI metadata attached to a procedure or router, or `undefined` if not set.
+ *
+ * @see {@link https://orpc.dev/docs/rpc/handler#enabling-the-get-method | RPC Handler - Enabling the GET Method}
+ */
 declare function getOpenAPIMeta(procedureOrLazy: AnyProcedureContract | Lazy<any>): OpenAPIMeta | undefined;
 
 export { getOpenAPIMeta as g, openapi as o };

package/dist/shared/{openapi.CYgMBSUF.d.mts → openapi.DfTTLtn5.d.mts}

@@ -1,18 +1,32 @@
 import { OpenAPIV3_1 } from '@hey-api/spec-types';
-import { ORPCError, AnyNestedClient, Client } from '@orpc/client';
+import { AnyNestedClient, Client, ORPCError } from '@orpc/client';
+import { AsyncIteratorClass } from '@orpc/shared';
 
-type OpenAPIDocument = OpenAPIV3_1.Document;
 type OpenAPIOperationObject = OpenAPIV3_1.OperationObject;
+/**
+ * An OpenAPI 3.1 document with the OpenAPI 3.2 QUERY additions used by oRPC.
+ * This type does not claim support for the complete OpenAPI 3.2 specification.
+ */
+type OpenAPIDocument = Omit<OpenAPIV3_1.Document, 'openapi' | 'paths'> & {
+    openapi: OpenAPIV3_1.Document['openapi'] | '3.2.0';
+    paths?: undefined | (OpenAPIV3_1.PathsObject & {
+        [path: `/${string}`]: OpenAPIV3_1.PathItemObject & {
+            query?: OpenAPIOperationObject | undefined;
+        };
+    });
+};
 type JsonifiedValue<T> = T extends string ? T : T extends number ? T : T extends boolean ? T : T extends null ? T : T extends undefined ? T : T extends Array<unknown> ? JsonifiedArray<T> : T extends Record<string, unknown> ? {
     [K in keyof T]: JsonifiedValue<T[K]>;
-} : T extends Date ? string : T extends bigint ? string : T extends File ? File : T extends Blob ? Blob : T extends RegExp ? string : T extends URL ? string : T extends Map<infer K, infer V> ? JsonifiedArray<[K, V][]> : T extends Set<infer U> ? JsonifiedArray<U[]> : T extends AsyncIteratorObject<infer U, infer V> ? AsyncIteratorObject<JsonifiedValue<U>, JsonifiedValue<V>> : unknown;
+} : T extends Date ? string : T extends bigint ? string : T extends File ? File : T extends Blob ? Blob : T extends RegExp ? string : T extends URL ? string : T extends Map<infer K, infer V> ? JsonifiedArray<[K, V][]> : T extends Set<infer U> ? JsonifiedArray<U[]> : T extends AsyncIteratorClass<infer U, infer V> ? AsyncIteratorClass<JsonifiedValue<U>, JsonifiedValue<V>> : T extends AsyncGenerator<infer U, infer V> ? AsyncGenerator<JsonifiedValue<U>, JsonifiedValue<V>> : T extends AsyncIteratorObject<infer U, infer V> ? AsyncIteratorObject<JsonifiedValue<U>, JsonifiedValue<V>> : unknown;
 type JsonifiedArray<T extends Array<unknown>> = T extends readonly [] ? [] : T extends readonly [infer U, ...infer V] ? [U extends undefined ? null : JsonifiedValue<U>, ...JsonifiedArray<V>] : T extends Array<infer U> ? Array<JsonifiedValue<U>> : unknown;
 type JsonifiedClientError<T> = T extends ORPCError<infer UCode, infer UData> ? ORPCError<UCode, JsonifiedValue<UData>> : T;
 /**
- * Convert types that JSON not support to corresponding json types
+ * Client type whose outputs and error data replace types JSON cannot represent with their JSON equivalents.
+ *
+ * @see {@link https://orpc.dev/docs/openapi/link | OpenAPI Link}
  */
 type JsonifiedClient<T extends AnyNestedClient> = T extends Client<infer UClientContext, infer UInput, infer UOutput, infer UError> ? Client<UClientContext, UInput, JsonifiedValue<UOutput>, JsonifiedClientError<UError>> : {
     [K in keyof T]: T[K] extends AnyNestedClient ? JsonifiedClient<T[K]> : T[K];
 };
 
-export type { JsonifiedValue as J, OpenAPIOperationObject as O, OpenAPIDocument as a, JsonifiedClientError as b, JsonifiedClient as c, JsonifiedArray as d };
+export type { JsonifiedClient as J, OpenAPIDocument as O, JsonifiedArray as a, JsonifiedClientError as b, JsonifiedValue as c, OpenAPIOperationObject as d };

package/dist/shared/{openapi.CYgMBSUF.d.ts → openapi.DfTTLtn5.d.ts}

@@ -1,18 +1,32 @@
 import { OpenAPIV3_1 } from '@hey-api/spec-types';
-import { ORPCError, AnyNestedClient, Client } from '@orpc/client';
+import { AnyNestedClient, Client, ORPCError } from '@orpc/client';
+import { AsyncIteratorClass } from '@orpc/shared';
 
-type OpenAPIDocument = OpenAPIV3_1.Document;
 type OpenAPIOperationObject = OpenAPIV3_1.OperationObject;
+/**
+ * An OpenAPI 3.1 document with the OpenAPI 3.2 QUERY additions used by oRPC.
+ * This type does not claim support for the complete OpenAPI 3.2 specification.
+ */
+type OpenAPIDocument = Omit<OpenAPIV3_1.Document, 'openapi' | 'paths'> & {
+    openapi: OpenAPIV3_1.Document['openapi'] | '3.2.0';
+    paths?: undefined | (OpenAPIV3_1.PathsObject & {
+        [path: `/${string}`]: OpenAPIV3_1.PathItemObject & {
+            query?: OpenAPIOperationObject | undefined;
+        };
+    });
+};
 type JsonifiedValue<T> = T extends string ? T : T extends number ? T : T extends boolean ? T : T extends null ? T : T extends undefined ? T : T extends Array<unknown> ? JsonifiedArray<T> : T extends Record<string, unknown> ? {
     [K in keyof T]: JsonifiedValue<T[K]>;
-} : T extends Date ? string : T extends bigint ? string : T extends File ? File : T extends Blob ? Blob : T extends RegExp ? string : T extends URL ? string : T extends Map<infer K, infer V> ? JsonifiedArray<[K, V][]> : T extends Set<infer U> ? JsonifiedArray<U[]> : T extends AsyncIteratorObject<infer U, infer V> ? AsyncIteratorObject<JsonifiedValue<U>, JsonifiedValue<V>> : unknown;
+} : T extends Date ? string : T extends bigint ? string : T extends File ? File : T extends Blob ? Blob : T extends RegExp ? string : T extends URL ? string : T extends Map<infer K, infer V> ? JsonifiedArray<[K, V][]> : T extends Set<infer U> ? JsonifiedArray<U[]> : T extends AsyncIteratorClass<infer U, infer V> ? AsyncIteratorClass<JsonifiedValue<U>, JsonifiedValue<V>> : T extends AsyncGenerator<infer U, infer V> ? AsyncGenerator<JsonifiedValue<U>, JsonifiedValue<V>> : T extends AsyncIteratorObject<infer U, infer V> ? AsyncIteratorObject<JsonifiedValue<U>, JsonifiedValue<V>> : unknown;
 type JsonifiedArray<T extends Array<unknown>> = T extends readonly [] ? [] : T extends readonly [infer U, ...infer V] ? [U extends undefined ? null : JsonifiedValue<U>, ...JsonifiedArray<V>] : T extends Array<infer U> ? Array<JsonifiedValue<U>> : unknown;
 type JsonifiedClientError<T> = T extends ORPCError<infer UCode, infer UData> ? ORPCError<UCode, JsonifiedValue<UData>> : T;
 /**
- * Convert types that JSON not support to corresponding json types
+ * Client type whose outputs and error data replace types JSON cannot represent with their JSON equivalents.
+ *
+ * @see {@link https://orpc.dev/docs/openapi/link | OpenAPI Link}
  */
 type JsonifiedClient<T extends AnyNestedClient> = T extends Client<infer UClientContext, infer UInput, infer UOutput, infer UError> ? Client<UClientContext, UInput, JsonifiedValue<UOutput>, JsonifiedClientError<UError>> : {
     [K in keyof T]: T[K] extends AnyNestedClient ? JsonifiedClient<T[K]> : T[K];
 };
 
-export type { JsonifiedValue as J, OpenAPIOperationObject as O, OpenAPIDocument as a, JsonifiedClientError as b, JsonifiedClient as c, JsonifiedArray as d };
+export type { JsonifiedClient as J, OpenAPIDocument as O, JsonifiedArray as a, JsonifiedClientError as b, JsonifiedValue as c, OpenAPIOperationObject as d };

package/dist/shared/{openapi.BcEtAxQj.d.mts → openapi.Drcd0PuL.d.mts}

@@ -2,7 +2,7 @@ import { AnySchema, ErrorMap, MetaPlugin, AnyProcedureContract } from '@orpc/con
 import { Lazy } from '@orpc/server';
 import { Value } from '@orpc/shared';
 import { StandardBodyHint } from '@standardserver/core';
-import { O as OpenAPIOperationObject } from './openapi.CYgMBSUF.mjs';
+import { d as OpenAPIOperationObject } from './openapi.DfTTLtn5.mjs';
 
 interface OpenAPIMeta {
     /**
@@ -10,11 +10,12 @@ interface OpenAPIMeta {
      *
      * @default 'POST'
      */
-    method?: 'HEAD' | 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | undefined;
+    method?: 'HEAD' | 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'QUERY' | undefined;
     /**
-     * URL path for this procedure. Supports dynamic segments via `${}` syntax.
+     * URL path for this procedure. Supports dynamic parameters via `{param}` syntax,
+     * and `{+param}` to allow slashes in the matched value.
      *
-     * @example `/users`, `/users/${id}`
+     * @example `/users`, `/users/{id}`, `/files/{+path}`
      * @default Router segments joined by `'/`
      */
     path?: `/${string}` | undefined;
@@ -39,11 +40,13 @@ interface OpenAPIMeta {
     /**
      * Tags associated with this procedure.
      *
-     * **Note**: Tags are merged when defined multiple times.
+     * **Merging**: When defined multiple times, tags are concatenated in definition order.
+     * Explicitly setting `undefined` resets the tags instead of merging.
      */
     tags?: string[] | undefined;
     /**
-     * HTTP status code returned on success. Must be in the 200–399 range.
+     * HTTP status code returned on success.
+     * Should be in the `2xx` range and must be less than `400`.
      *
      * @default 200
      */
@@ -57,7 +60,9 @@ interface OpenAPIMeta {
     /**
      * Controls how individual path parameters are decoded.
      *
-     * **Note**: Param styles are merged when defined multiple times.
+     * **Merging**: When defined multiple times, styles are merged per parameter.
+     * The most recent style defined for a parameter wins.
+     * Explicitly setting `undefined` resets the styles instead of merging.
      *
      * Each key maps a path parameter name to one of the following strategies:
      *
@@ -102,7 +107,9 @@ interface OpenAPIMeta {
     /**
      * Controls how individual query parameters are encoding/decoding.
      *
-     * **Note**: Query styles are merged when defined multiple times.
+     * **Merging**: When defined multiple times, styles are merged per parameter.
+     * The most recent style defined for a parameter wins.
+     * Explicitly setting `undefined` resets the styles instead of merging.
      *
      * Each key maps a query parameter name to one of the following strategies:
      *
@@ -260,13 +267,20 @@ interface OpenAPIMeta {
      * Pass a plain object to replace entire operation object, or a function that receives the current
      * operation object and returns the modified version.
      *
-     * **Note**: Spec is merged when defined multiple times.
+     * **Merging**: When defined multiple times:
+     *
+     * - Two functions are chained: the most recent function receives the result of the previous one.
+     * - A function combined with an object: the function is applied to that object.
+     * - Two objects: the most recent object wins.
+     *
+     * Explicitly setting `undefined` resets the spec instead of merging.
      */
     spec?: Value<OpenAPIOperationObject, [current: OpenAPIOperationObject]>;
     /**
      * Prefix for the path. Useful when you want to apply a common path prefix across multiple procedures.
      *
-     * **Note**: Prefixes are merged when defined multiple times.
+     * **Merging**: When defined multiple times, prefixes are concatenated in definition order.
+     * Explicitly setting `undefined` resets the prefix instead of merging.
      */
     prefix?: `/${string}` | undefined;
 }
@@ -292,7 +306,19 @@ interface OpenAPIFunction {
     spec(method: OpenAPIMeta['spec']): OpenAPISpecMetaPlugin<any, any, any>;
     prefix(method: OpenAPIMeta['prefix']): OpenAPIPrefixMetaPlugin<any, any, any>;
 }
+/**
+ * Creates OpenAPI meta plugins that control how a procedure is exposed over HTTP,
+ * such as its method, path, prefix, and OpenAPI operation spec.
+ *
+ * @see {@link https://orpc.dev/docs/openapi/routing | OpenAPI Routing}
+ * @see {@link https://orpc.dev/docs/openapi/specification | OpenAPI Specification}
+ */
 declare const openapi: OpenAPIFunction;
+/**
+ * Retrieves the OpenAPI metadata attached to a procedure or router, or `undefined` if not set.
+ *
+ * @see {@link https://orpc.dev/docs/rpc/handler#enabling-the-get-method | RPC Handler - Enabling the GET Method}
+ */
 declare function getOpenAPIMeta(procedureOrLazy: AnyProcedureContract | Lazy<any>): OpenAPIMeta | undefined;
 
 export { getOpenAPIMeta as g, openapi as o };

package/dist/shared/{openapi.C7m7NAmH.d.mts → openapi.Dz-JaXHo.d.mts}

@@ -95,10 +95,15 @@ interface OpenAPIJsonSerializerOptions {
     omitUndefinedProperties?: boolean | undefined;
 }
 declare class OpenAPIJsonSerializer {
-    private readonly handlers;
+    private readonly inlineBuiltInHandlers;
+    private readonly handlerEntries;
     private readonly omitUndefinedProperties;
     constructor(options?: OpenAPIJsonSerializerOptions);
     serialize(data: unknown): OpenAPIJsonSerialization;
+    /**
+     * `segments` is a shared mutable stack (push/pop while walking),
+     * so it must be copied before being stored in `maps`.
+     */
     private serializeValue;
     deserialize(serialized: OpenAPIJsonSerialization): unknown;
 }
@@ -118,7 +123,7 @@ interface OpenAPISerializerSerializeOptions {
      */
     asFormData?: boolean | undefined;
 }
-interface OpenAPISerializerOptions extends OpenAPIJsonSerializerOptions, OpenAPISerializerSerializeOptions {
+interface OpenAPISerializerOptions extends OpenAPIJsonSerializerOptions {
     /**
      * Options for bracket notation serializer, like maxExplicitDeserializingArrayIndex
      */
@@ -128,6 +133,12 @@ interface OpenAPISerializerOptions extends OpenAPIJsonSerializerOptions, OpenAPI
      */
     serialize?: OpenAPISerializerSerializeOptions | undefined;
 }
+/**
+ * Handles one-way serialization of oRPC payloads into JSON-friendly formats,
+ * partially supporting complex data types beyond plain JSON such as `Date`, `BigInt`, and `Set`.
+ *
+ * @see {@link https://orpc.dev/docs/openapi/serializer | OpenAPI Serializer}
+ */
 declare class OpenAPISerializer {
     private readonly jsonSerializer;
     private readonly bracketNotation;

package/dist/shared/{openapi.C7m7NAmH.d.ts → openapi.Dz-JaXHo.d.ts}

@@ -95,10 +95,15 @@ interface OpenAPIJsonSerializerOptions {
     omitUndefinedProperties?: boolean | undefined;
 }
 declare class OpenAPIJsonSerializer {
-    private readonly handlers;
+    private readonly inlineBuiltInHandlers;
+    private readonly handlerEntries;
     private readonly omitUndefinedProperties;
     constructor(options?: OpenAPIJsonSerializerOptions);
     serialize(data: unknown): OpenAPIJsonSerialization;
+    /**
+     * `segments` is a shared mutable stack (push/pop while walking),
+     * so it must be copied before being stored in `maps`.
+     */
     private serializeValue;
     deserialize(serialized: OpenAPIJsonSerialization): unknown;
 }
@@ -118,7 +123,7 @@ interface OpenAPISerializerSerializeOptions {
      */
     asFormData?: boolean | undefined;
 }
-interface OpenAPISerializerOptions extends OpenAPIJsonSerializerOptions, OpenAPISerializerSerializeOptions {
+interface OpenAPISerializerOptions extends OpenAPIJsonSerializerOptions {
     /**
      * Options for bracket notation serializer, like maxExplicitDeserializingArrayIndex
      */
@@ -128,6 +133,12 @@ interface OpenAPISerializerOptions extends OpenAPIJsonSerializerOptions, OpenAPI
      */
     serialize?: OpenAPISerializerSerializeOptions | undefined;
 }
+/**
+ * Handles one-way serialization of oRPC payloads into JSON-friendly formats,
+ * partially supporting complex data types beyond plain JSON such as `Date`, `BigInt`, and `Set`.
+ *
+ * @see {@link https://orpc.dev/docs/openapi/serializer | OpenAPI Serializer}
+ */
 declare class OpenAPISerializer {
     private readonly jsonSerializer;
     private readonly bracketNotation;

package/dist/shared/{openapi.DBYxUpK8.d.ts → openapi.YCiBHaJ-.d.ts}

@@ -1,10 +1,10 @@
 import { AnyORPCError } from '@orpc/client';
 import { AnyProcedure, AnyRouter, Context } from '@orpc/server';
-import { StandardHandlerHandleOptions, StandardHandlerCodec, StandardHandlerCodecResolvedProcedure } from '@orpc/server/standard';
+import { StandardHandlerCodec, StandardHandlerHandleOptions, StandardHandlerCodecResolvedProcedure } from '@orpc/server/standard';
 import { Value, Promisable } from '@orpc/shared';
 import { StandardLazyRequest, StandardResponse } from '@standardserver/core';
 import { AnyProcedureContract } from '@orpc/contract';
-import { O as OpenAPISerializer } from './openapi.C7m7NAmH.js';
+import { O as OpenAPISerializer } from './openapi.Dz-JaXHo.js';
 
 interface OpenAPIMatcherOptions {
     /**
@@ -18,7 +18,7 @@ declare class OpenAPIMatcher {
     private readonly filter;
     private readonly rootRouter;
     private readonly tree;
-    private pendingLazyRouters;
+    private readonly pendingLazyRouters;
     constructor(router: AnyRouter, options?: OpenAPIMatcherOptions);
     private index;
     match(method: string, pathname: `/${string}`, prefix: `/${string}` | undefined): Promise<{
@@ -26,8 +26,10 @@ declare class OpenAPIMatcher {
         procedure: AnyProcedure;
         params?: Record<string, string> | undefined;
     } | undefined>;
-    private matchPathname;
     private resolvePendingLazyRouters;
+    private loadPendingLazyRouters;
+    private loadPendingLazyRouter;
+    private indexPendingLazyRouter;
     private resolveProcedure;
 }
 
@@ -38,8 +40,9 @@ interface OpenAPIHandlerCodecCoreOptions<_T extends Context> {
     serializer?: Pick<OpenAPISerializer, keyof OpenAPISerializer>;
     /**
      * Mapping ORPCError Code -> HTTP Status Code
+     * The status code should be in the `4xx` or `5xx` range (must be greater than or equal to `400`).
      *
-     * @default COMMON_ERROR_STATUS_MAP, DEFAULT_ERROR_STATUS
+     * @default COMMON_ERROR_STATUS_MAP
      */
     errorStatusMap?: Record<string, number> | undefined;
     /**
@@ -65,8 +68,8 @@ declare class OpenAPIHandlerCodecCore<T extends Context> {
     /**
      * @throws {TypeError} If `outputStructure` is "detailed" and the output doesn't match the expected structure.
      */
-    encodeOutput(output: unknown, procedure: AnyProcedure, path: string[], _options: StandardHandlerHandleOptions<T>): Promisable<StandardResponse>;
-    encodeError(error: AnyORPCError, _procedure: AnyProcedure, _path: string[], _options: StandardHandlerHandleOptions<T>): Promisable<StandardResponse>;
+    encodeOutput(output: unknown, procedure: AnyProcedure, path: string[]): Promisable<StandardResponse>;
+    encodeError(error: AnyORPCError): Promisable<StandardResponse>;
     private deserializeQuery;
     private deserializeParams;
 }