@orpc/openapi 2.0.0-beta.2 → 2.0.0-beta.20

package/dist/plugins/index.d.mts

@@ -4,7 +4,7 @@ import { Value, Promisable } from '@orpc/shared';
 import { ApiReferenceConfiguration } from '@scalar/api-reference';
 import { StandardUrl } from '@standardserver/core';
 import { SwaggerUIOptions } from 'swagger-ui';
-import { a as OpenAPIDocument } from '../shared/openapi.CYgMBSUF.mjs';
+import { a as OpenAPIDocument } from '../shared/openapi.ByT4oUeY.mjs';
 import '@hey-api/spec-types';
 import '@orpc/client';
 

package/dist/plugins/index.d.ts

@@ -4,7 +4,7 @@ import { Value, Promisable } from '@orpc/shared';
 import { ApiReferenceConfiguration } from '@scalar/api-reference';
 import { StandardUrl } from '@standardserver/core';
 import { SwaggerUIOptions } from 'swagger-ui';
-import { a as OpenAPIDocument } from '../shared/openapi.CYgMBSUF.js';
+import { a as OpenAPIDocument } from '../shared/openapi.ByT4oUeY.js';
 import '@hey-api/spec-types';
 import '@orpc/client';
 

package/dist/shared/{openapi.BYcWgK1j.d.ts → openapi.B6hEbRyF.d.ts}

@@ -4,7 +4,7 @@ import { StandardHandlerCodec, StandardHandlerHandleOptions, StandardHandlerCode
 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.BOOA-bde.js';
 
 interface OpenAPIMatcherOptions {
     /**
@@ -31,17 +31,16 @@ declare class OpenAPIMatcher {
     private resolveProcedure;
 }
 
-declare class OpenAPIHandlerCodecError extends TypeError {
-}
-interface OpenAPIHandlerCodecOptions<_T extends Context> extends OpenAPIMatcherOptions {
+interface OpenAPIHandlerCodecCoreOptions<_T extends Context> {
     /**
      * Override the default OpenAPI serializer.
      */
     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;
     /**
@@ -55,25 +54,30 @@ interface OpenAPIHandlerCodecOptions<_T extends Context> extends OpenAPIMatcherO
      */
     customErrorResponseBodyEncoder?: (error: AnyORPCError) => unknown;
 }
-declare class OpenAPIHandlerCodec<T extends Context> implements StandardHandlerCodec<T> {
-    private readonly matcher;
+declare class OpenAPIHandlerCodecCore<T extends Context> {
     private readonly serializer;
     private readonly errorStatusMap;
     private readonly customErrorResponseBodySerializer;
-    constructor(router: AnyRouter, options?: OpenAPIHandlerCodecOptions<T>);
+    constructor(options?: OpenAPIHandlerCodecCoreOptions<T>);
     decodeInput(matched: {
         procedure: AnyProcedure;
         params?: undefined | Record<string, string>;
     }, request: StandardLazyRequest): Promise<unknown>;
-    resolveProcedure(request: StandardLazyRequest, options: StandardHandlerHandleOptions<T>): Promise<StandardHandlerCodecResolvedProcedure | undefined>;
     /**
-     * @throws {Error} If `outputStructure` is "detailed" and the output doesn't match the expected structure.
+     * @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;
 }
+interface OpenAPIHandlerCodecOptions<T extends Context> extends OpenAPIHandlerCodecCoreOptions<T>, OpenAPIMatcherOptions {
+}
+declare class OpenAPIHandlerCodec<T extends Context> extends OpenAPIHandlerCodecCore<T> implements StandardHandlerCodec<T> {
+    private readonly matcher;
+    constructor(router: AnyRouter, options?: OpenAPIHandlerCodecOptions<T>);
+    resolveProcedure(request: StandardLazyRequest, options: StandardHandlerHandleOptions<T>): Promise<StandardHandlerCodecResolvedProcedure | undefined>;
+}
 
-export { OpenAPIHandlerCodec as a, OpenAPIHandlerCodecError as b, OpenAPIMatcher as c };
-export type { OpenAPIHandlerCodecOptions as O, OpenAPIMatcherOptions as d };
+export { OpenAPIHandlerCodec as a, OpenAPIHandlerCodecCore as b, OpenAPIMatcher as d };
+export type { OpenAPIHandlerCodecOptions as O, OpenAPIHandlerCodecCoreOptions as c, OpenAPIMatcherOptions as e };

package/dist/shared/{openapi.C7m7NAmH.d.mts → openapi.BOOA-bde.d.mts}

@@ -118,7 +118,7 @@ interface OpenAPISerializerSerializeOptions {
      */
     asFormData?: boolean | undefined;
 }
-interface OpenAPISerializerOptions extends OpenAPIJsonSerializerOptions, OpenAPISerializerSerializeOptions {
+interface OpenAPISerializerOptions extends OpenAPIJsonSerializerOptions {
     /**
      * Options for bracket notation serializer, like maxExplicitDeserializingArrayIndex
      */

package/dist/shared/{openapi.C7m7NAmH.d.ts → openapi.BOOA-bde.d.ts}

@@ -118,7 +118,7 @@ interface OpenAPISerializerSerializeOptions {
      */
     asFormData?: boolean | undefined;
 }
-interface OpenAPISerializerOptions extends OpenAPIJsonSerializerOptions, OpenAPISerializerSerializeOptions {
+interface OpenAPISerializerOptions extends OpenAPIJsonSerializerOptions {
     /**
      * Options for bracket notation serializer, like maxExplicitDeserializingArrayIndex
      */

package/dist/shared/{openapi.XeW6_5tm.d.mts → openapi.BafbB3uM.d.mts}

@@ -4,7 +4,7 @@ import { StandardHandlerCodec, StandardHandlerHandleOptions, StandardHandlerCode
 import { Value, Promisable } from '@orpc/shared';
 import { StandardLazyRequest, StandardResponse } from '@standardserver/core';
 import { AnyProcedureContract } from '@orpc/contract';
-import { O as OpenAPISerializer } from './openapi.C7m7NAmH.mjs';
+import { O as OpenAPISerializer } from './openapi.BOOA-bde.mjs';
 
 interface OpenAPIMatcherOptions {
     /**
@@ -31,17 +31,16 @@ declare class OpenAPIMatcher {
     private resolveProcedure;
 }
 
-declare class OpenAPIHandlerCodecError extends TypeError {
-}
-interface OpenAPIHandlerCodecOptions<_T extends Context> extends OpenAPIMatcherOptions {
+interface OpenAPIHandlerCodecCoreOptions<_T extends Context> {
     /**
      * Override the default OpenAPI serializer.
      */
     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;
     /**
@@ -55,25 +54,30 @@ interface OpenAPIHandlerCodecOptions<_T extends Context> extends OpenAPIMatcherO
      */
     customErrorResponseBodyEncoder?: (error: AnyORPCError) => unknown;
 }
-declare class OpenAPIHandlerCodec<T extends Context> implements StandardHandlerCodec<T> {
-    private readonly matcher;
+declare class OpenAPIHandlerCodecCore<T extends Context> {
     private readonly serializer;
     private readonly errorStatusMap;
     private readonly customErrorResponseBodySerializer;
-    constructor(router: AnyRouter, options?: OpenAPIHandlerCodecOptions<T>);
+    constructor(options?: OpenAPIHandlerCodecCoreOptions<T>);
     decodeInput(matched: {
         procedure: AnyProcedure;
         params?: undefined | Record<string, string>;
     }, request: StandardLazyRequest): Promise<unknown>;
-    resolveProcedure(request: StandardLazyRequest, options: StandardHandlerHandleOptions<T>): Promise<StandardHandlerCodecResolvedProcedure | undefined>;
     /**
-     * @throws {Error} If `outputStructure` is "detailed" and the output doesn't match the expected structure.
+     * @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;
 }
+interface OpenAPIHandlerCodecOptions<T extends Context> extends OpenAPIHandlerCodecCoreOptions<T>, OpenAPIMatcherOptions {
+}
+declare class OpenAPIHandlerCodec<T extends Context> extends OpenAPIHandlerCodecCore<T> implements StandardHandlerCodec<T> {
+    private readonly matcher;
+    constructor(router: AnyRouter, options?: OpenAPIHandlerCodecOptions<T>);
+    resolveProcedure(request: StandardLazyRequest, options: StandardHandlerHandleOptions<T>): Promise<StandardHandlerCodecResolvedProcedure | undefined>;
+}
 
-export { OpenAPIHandlerCodec as a, OpenAPIHandlerCodecError as b, OpenAPIMatcher as c };
-export type { OpenAPIHandlerCodecOptions as O, OpenAPIMatcherOptions as d };
+export { OpenAPIHandlerCodec as a, OpenAPIHandlerCodecCore as b, OpenAPIMatcher as d };
+export type { OpenAPIHandlerCodecOptions as O, OpenAPIHandlerCodecCoreOptions as c, OpenAPIMatcherOptions as e };

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

@@ -1,5 +1,5 @@
 import { OpenAPIV3_1 } from '@hey-api/spec-types';
-import { ORPCError, AnyNestedClient, Client } from '@orpc/client';
+import { AnyNestedClient, Client, ORPCError } from '@orpc/client';
 
 type OpenAPIDocument = OpenAPIV3_1.Document;
 type OpenAPIOperationObject = OpenAPIV3_1.OperationObject;
@@ -15,4 +15,4 @@ type JsonifiedClient<T extends AnyNestedClient> = T extends Client<infer UClient
     [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, OpenAPIOperationObject as O, OpenAPIDocument as a, JsonifiedArray as b, JsonifiedClientError as c, JsonifiedValue as d };

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

@@ -1,5 +1,5 @@
 import { OpenAPIV3_1 } from '@hey-api/spec-types';
-import { ORPCError, AnyNestedClient, Client } from '@orpc/client';
+import { AnyNestedClient, Client, ORPCError } from '@orpc/client';
 
 type OpenAPIDocument = OpenAPIV3_1.Document;
 type OpenAPIOperationObject = OpenAPIV3_1.OperationObject;
@@ -15,4 +15,4 @@ type JsonifiedClient<T extends AnyNestedClient> = T extends Client<infer UClient
     [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, OpenAPIOperationObject as O, OpenAPIDocument as a, JsonifiedArray as b, JsonifiedClientError as c, JsonifiedValue as d };

package/dist/shared/{openapi.B2SK0ZAr.mjs → openapi.C-p_Q2lb.mjs}

@@ -4,7 +4,7 @@ import { unlazy } from '@orpc/server';
 import { value, pathToHttpPath, mergeHttpPath, isTypescriptObject, stringifyJSON } from '@orpc/shared';
 import { mergeStandardHeaders, parseStandardUrl, isStandardHeaders } 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.zZH_UksW.mjs';
 import { g as getOpenAPIMeta } from './openapi.B9PQzqBn.mjs';
 
 class OpenAPILinkCodecError extends TypeError {
@@ -56,7 +56,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 ?? ""}`;
@@ -110,7 +110,7 @@ class OpenAPILinkCodec {
     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,
@@ -243,7 +243,7 @@ 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 deserialized = await (async () => {

package/dist/shared/{openapi.DR-y5p-D.mjs → openapi.CVgUshDP.mjs}

@@ -2,7 +2,7 @@ import { COMMON_ERROR_STATUS_MAP } from '@orpc/client';
 import { walkProcedureContractsSync, Procedure, unlazy, getRouter, createContractProcedure, DEFAULT_SUCCESS_STATUS, DEFAULT_ERROR_STATUS } from '@orpc/server';
 import { value, pathToHttpPath, mergeHttpPath, normalizeHttpPath, tryDecodeURIComponent, isPlainObject, stringifyJSON, parseEmptyableJSON, isTypescriptObject, NullProtoObj } from '@orpc/shared';
 import { parseStandardUrl, isStandardHeaders } from '@standardserver/core';
-import { D as DEFAULT_OPENAPI_METHOD, g as getDynamicPathParams, O as OpenAPISerializer, a as DEFAULT_OPENAPI_INPUT_STRUCTURE, b as DEFAULT_OPENAPI_OUTPUT_STRUCTURE } from './openapi.DmAa7YPO.mjs';
+import { D as DEFAULT_OPENAPI_METHOD, g as getDynamicPathParams, O as OpenAPISerializer, a as DEFAULT_OPENAPI_INPUT_STRUCTURE, i as isBodylessMethod, b as DEFAULT_OPENAPI_OUTPUT_STRUCTURE } from './openapi.zZH_UksW.mjs';
 import { g as getOpenAPIMeta } from './openapi.B9PQzqBn.mjs';
 import { createRouter, addRoute, findRoute, routeToRegExp } from 'rou3';
 
@@ -124,15 +124,11 @@ function decodeParams(params) {
   return Object.fromEntries(Object.entries(params).map(([key, val]) => [key, tryDecodeURIComponent(val)]));
 }
 
-class OpenAPIHandlerCodecError extends TypeError {
-}
-class OpenAPIHandlerCodec {
-  matcher;
+class OpenAPIHandlerCodecCore {
   serializer;
   errorStatusMap;
   customErrorResponseBodySerializer;
-  constructor(router, options = {}) {
-    this.matcher = new OpenAPIMatcher(router, options);
+  constructor(options = {}) {
     this.serializer = options.serializer ?? new OpenAPISerializer();
     this.errorStatusMap = options.errorStatusMap ?? COMMON_ERROR_STATUS_MAP;
     this.customErrorResponseBodySerializer = options.customErrorResponseBodyEncoder;
@@ -144,7 +140,7 @@ class OpenAPIHandlerCodec {
     const params = this.deserializeParams(matched.params, meta?.paramsStyles);
     const query = this.deserializeQuery(search, meta?.queryStyles);
     if (inputStructure === "compact") {
-      const data = request.method === "GET" ? query : this.serializer.deserialize(await request.resolveBody(meta?.requestBodyHint));
+      const data = isBodylessMethod(request.method) ? query : this.serializer.deserialize(await request.resolveBody(meta?.requestBodyHint));
       if (data === void 0) {
         return params;
       }
@@ -166,22 +162,10 @@ class OpenAPIHandlerCodec {
       body: this.serializer.deserialize(await request.resolveBody(meta?.requestBodyHint))
     };
   }
-  async resolveProcedure(request, options) {
-    const [pathname] = parseStandardUrl(request.url);
-    const matched = await this.matcher.match(request.method, pathname, options.prefix);
-    if (!matched) {
-      return void 0;
-    }
-    return {
-      procedure: matched.procedure,
-      path: matched.path,
-      decodeInput: () => this.decodeInput(matched, request)
-    };
-  }
   /**
-   * @throws {Error} If `outputStructure` is "detailed" and the output doesn't match the expected structure.
+   * @throws {TypeError} If `outputStructure` is "detailed" and the output doesn't match the expected structure.
    */
-  encodeOutput(output, procedure, path, _options) {
+  encodeOutput(output, procedure, path) {
     const meta = getOpenAPIMeta(procedure);
     const successStatus = meta?.successStatus ?? DEFAULT_SUCCESS_STATUS;
     const outputStructure = meta?.outputStructure ?? DEFAULT_OPENAPI_OUTPUT_STRUCTURE;
@@ -193,7 +177,7 @@ class OpenAPIHandlerCodec {
       };
     }
     if (!isValidDetailedOutput(output)) {
-      throw new OpenAPIHandlerCodecError(`
+      throw new TypeError(`
         Invalid "detailed" output structure returned by procedure (${path.join(".")}):
         \u2022 Expected an object with optional properties:
           - status (number 200-399)
@@ -211,7 +195,7 @@ class OpenAPIHandlerCodec {
       body: this.serializer.serialize(output.body)
     };
   }
-  encodeError(error, _procedure, _path, _options) {
+  encodeError(error) {
     const status = this.errorStatusMap[error.code] ?? DEFAULT_ERROR_STATUS;
     return {
       status,
@@ -278,6 +262,25 @@ class OpenAPIHandlerCodec {
     return parsed;
   }
 }
+class OpenAPIHandlerCodec extends OpenAPIHandlerCodecCore {
+  matcher;
+  constructor(router, options = {}) {
+    super(options);
+    this.matcher = new OpenAPIMatcher(router, options);
+  }
+  async resolveProcedure(request, options) {
+    const [pathname] = parseStandardUrl(request.url);
+    const matched = await this.matcher.match(request.method, pathname, options.prefix);
+    if (!matched) {
+      return void 0;
+    }
+    return {
+      procedure: matched.procedure,
+      path: matched.path,
+      decodeInput: () => this.decodeInput(matched, request)
+    };
+  }
+}
 function isValidDetailedOutput(output) {
   if (!isTypescriptObject(output)) {
     return false;
@@ -312,4 +315,4 @@ function decodeDelimitedObject(value, delimiter) {
   return obj;
 }
 
-export { OpenAPIHandlerCodec as O, OpenAPIHandlerCodecError as a, OpenAPIMatcher as b };
+export { OpenAPIHandlerCodec as O, OpenAPIHandlerCodecCore as a, OpenAPIMatcher as b };

package/dist/shared/{openapi.BQzzr4-4.d.ts → openapi.DNNo0V-l.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 { O as OpenAPIOperationObject } from './openapi.ByT4oUeY.js';
 
 interface OpenAPIMeta {
     /**
@@ -12,9 +12,10 @@ interface OpenAPIMeta {
      */
     method?: 'HEAD' | 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 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;
 }

package/dist/shared/{openapi.BcEtAxQj.d.mts → openapi.hg_rhZ4x.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 { O as OpenAPIOperationObject } from './openapi.ByT4oUeY.mjs';
 
 interface OpenAPIMeta {
     /**
@@ -12,9 +12,10 @@ interface OpenAPIMeta {
      */
     method?: 'HEAD' | 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 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;
 }

package/dist/shared/{openapi.DmAa7YPO.mjs → openapi.zZH_UksW.mjs}

@@ -1,4 +1,4 @@
-import { wrapEventIteratorPreservingMeta, toORPCError, isORPCErrorJson, createORPCErrorFromJson } from '@orpc/client';
+import { wrapAsyncIteratorPreservingEventMeta, toORPCError, isORPCErrorJson, createORPCErrorFromJson } from '@orpc/client';
 import { isPlainObject, isAsyncIteratorObject } from '@orpc/shared';
 import { ErrorEvent } from '@standardserver/core';
 import { B as BracketNotationSerializer } from './openapi.Bt87OzTt.mjs';
@@ -173,7 +173,7 @@ class OpenAPISerializer {
         return data;
       }
       if (isAsyncIteratorObject(data)) {
-        return wrapEventIteratorPreservingMeta(data, {
+        return wrapAsyncIteratorPreservingEventMeta(data, {
           mapResult: (result) => {
             if (result.value === void 0) {
               return result;
@@ -211,7 +211,7 @@ class OpenAPISerializer {
       return data;
     }
     if (isAsyncIteratorObject(data)) {
-      return wrapEventIteratorPreservingMeta(data, {
+      return wrapAsyncIteratorPreservingEventMeta(data, {
         mapResult: (result) => {
           if (result.value === void 0) {
             return result;
@@ -236,6 +236,9 @@ class OpenAPISerializer {
   }
 }
 
+function isBodylessMethod(method) {
+  return method === "GET" || method === "HEAD";
+}
 const PARAMETER_NAME_REGEX = /^[\w-]+$/;
 function getDynamicPathParams(path) {
   if (!path.includes("{")) {
@@ -272,4 +275,4 @@ function getDynamicPathParams(path) {
   return params;
 }
 
-export { DEFAULT_OPENAPI_METHOD as D, OpenAPISerializer as O, DEFAULT_OPENAPI_INPUT_STRUCTURE as a, DEFAULT_OPENAPI_OUTPUT_STRUCTURE as b, DEFAULT_OPENAPI_SUCCESS_DESCRIPTION as c, OpenAPIJsonSerializer as d, getDynamicPathParams as g };
+export { DEFAULT_OPENAPI_METHOD as D, OpenAPISerializer as O, DEFAULT_OPENAPI_INPUT_STRUCTURE as a, DEFAULT_OPENAPI_OUTPUT_STRUCTURE as b, DEFAULT_OPENAPI_SUCCESS_DESCRIPTION as c, OpenAPIJsonSerializer as d, getDynamicPathParams as g, isBodylessMethod as i };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@orpc/openapi",
   "type": "module",
-  "version": "2.0.0-beta.2",
+  "version": "2.0.0-beta.20",
   "license": "MIT",
   "homepage": "https://orpc.dev",
   "repository": {
@@ -57,22 +57,38 @@
   "files": [
     "dist"
   ],
+  "peerDependencies": {
+    "@scalar/api-reference": ">=1.57.2",
+    "@types/swagger-ui": ">=5.32.0",
+    "swagger-ui": ">=5.32.6"
+  },
+  "peerDependenciesMeta": {
+    "@scalar/api-reference": {
+      "optional": true
+    },
+    "@types/swagger-ui": {
+      "optional": true
+    },
+    "swagger-ui": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@hey-api/spec-types": "0.0.0-next-20260408030107",
+    "@standardserver/core": "^0.5.0",
+    "@standardserver/fetch": "^0.5.0",
+    "rou3": "^0.9.1",
+    "@orpc/client": "2.0.0-beta.20",
+    "@orpc/contract": "2.0.0-beta.20",
+    "@orpc/server": "2.0.0-beta.20",
+    "@orpc/shared": "2.0.0-beta.20",
+    "@orpc/json-schema": "2.0.0-beta.20"
+  },
+  "devDependencies": {
     "@scalar/api-reference": "^1.57.2",
-    "@standardserver/core": "^0.0.25",
-    "@standardserver/fetch": "^0.0.25",
     "@types/swagger-ui": "^5.32.0",
-    "rou3": "^0.8.1",
+    "fastify": "^5.8.5",
     "swagger-ui": "^5.32.6",
-    "@orpc/client": "2.0.0-beta.2",
-    "@orpc/json-schema": "2.0.0-beta.2",
-    "@orpc/server": "2.0.0-beta.2",
-    "@orpc/shared": "2.0.0-beta.2",
-    "@orpc/contract": "2.0.0-beta.2"
-  },
-  "devDependencies": {
-    "fastify": "^5.6.2",
     "zod": "^4.4.3"
   },
   "scripts": {