@orpc/openapi 2.0.0-beta.4 → 2.0.0-beta.41

package/dist/shared/{openapi.CTlpLuKN.mjs → openapi.Bi1qxGF9.mjs}

@@ -1,8 +1,8 @@
 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 { value, pathToHttpPath, mergeHttpPath, normalizeHttpPath, safeDecodeURIComponent, NullProtoObj, isTypescriptObject, isPlainObject, stringifyJSON, getOwn, parseEmptyableJSON } from '@orpc/shared';
+import { parseStandardUrl } from '@standard-server/core';
+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.Bu_PfTtX.mjs';
 import { g as getOpenAPIMeta } from './openapi.B9PQzqBn.mjs';
 import { createRouter, addRoute, findRoute, routeToRegExp } from 'rou3';
 
@@ -10,7 +10,7 @@ class OpenAPIMatcher {
   filter;
   rootRouter;
   tree = createRouter();
-  pendingLazyRouters = [];
+  pendingLazyRouters = /* @__PURE__ */ new Set();
   constructor(router, options = {}) {
     this.filter = options.filter ?? true;
     this.rootRouter = router;
@@ -32,13 +32,13 @@ class OpenAPIMatcher {
         procedure: contract instanceof Procedure ? contract : void 0
       });
     }, path);
-    this.pendingLazyRouters.push(...lazyResults.map((result) => {
+    for (const result of lazyResults) {
       const prefix = getOpenAPIMeta(result.router)?.prefix;
-      return {
+      this.pendingLazyRouters.add({
         ...result,
         matcher: prefix ? toRou3PrefixMatcher(prefix) : void 0
-      };
-    }));
+      });
+    }
   }
   async match(method, pathname, prefix) {
     if (prefix) {
@@ -56,44 +56,58 @@ class OpenAPIMatcher {
         return void 0;
       }
     }
-    const result = await this.matchPathname(method, pathname);
-    if (!result && pathname.includes("%")) {
-      return this.matchPathname(method, normalizeHttpPath(pathname));
+    const loading = this.resolvePendingLazyRouters(pathname);
+    if (loading !== void 0) {
+      await loading;
     }
-    return result;
-  }
-  async matchPathname(method, pathname) {
-    await this.resolvePendingLazyRouters(pathname);
-    const match = findRoute(this.tree, method, pathname);
-    if (!match) {
+    let match = findRoute(this.tree, method, pathname);
+    if (match === void 0 && pathname.includes("%")) {
+      const normalizedPathname = normalizeHttpPath(pathname);
+      const normalizedLoading = this.resolvePendingLazyRouters(normalizedPathname);
+      if (normalizedLoading !== void 0) {
+        await normalizedLoading;
+      }
+      match = findRoute(this.tree, method, normalizedPathname);
+    }
+    if (match === void 0) {
       return void 0;
     }
-    const procedure = await this.resolveProcedure(match.data);
+    const entry = match.data;
     return {
-      path: match.data.path,
-      procedure,
+      path: entry.path,
+      procedure: entry.procedure ?? await this.resolveProcedure(entry),
       params: match.params ? decodeParams(match.params) : void 0
     };
   }
-  async resolvePendingLazyRouters(pathname) {
-    if (!this.pendingLazyRouters.length) {
-      return;
+  resolvePendingLazyRouters(pathname) {
+    for (const pending of this.pendingLazyRouters) {
+      if (pending.matcher === void 0 || pending.matcher.test(pathname)) {
+        return this.loadPendingLazyRouters(pathname);
+      }
     }
-    const stillPending = [];
+  }
+  async loadPendingLazyRouters(pathname) {
     for (const pending of this.pendingLazyRouters) {
-      if (!pending.matcher || pending.matcher.test(pathname)) {
-        const { default: router } = await unlazy(pending.router);
-        this.index(router, pending.path);
-      } else {
-        stillPending.push(pending);
+      if (pending.matcher === void 0 || pending.matcher.test(pathname)) {
+        await this.loadPendingLazyRouter(pending);
       }
     }
-    this.pendingLazyRouters = stillPending;
   }
-  async resolveProcedure(entry) {
-    if (entry.procedure) {
-      return entry.procedure;
+  loadPendingLazyRouter(pending) {
+    if (pending.loading === void 0) {
+      pending.loading = this.indexPendingLazyRouter(pending).catch((error) => {
+        pending.loading = void 0;
+        throw error;
+      });
     }
+    return pending.loading;
+  }
+  async indexPendingLazyRouter(pending) {
+    const { default: router } = await unlazy(pending.router);
+    this.index(router, pending.path);
+    this.pendingLazyRouters.delete(pending);
+  }
+  async resolveProcedure(entry) {
     const { default: maybeProcedure } = await unlazy(getRouter(this.rootRouter, entry.path));
     if (!(maybeProcedure instanceof Procedure)) {
       throw new TypeError(
@@ -121,7 +135,42 @@ function toRou3PrefixMatcher(path) {
   return routeToRegExp(pattern === "/" ? "/**" : `${pattern}/**`);
 }
 function decodeParams(params) {
-  return Object.fromEntries(Object.entries(params).map(([key, val]) => [key, tryDecodeURIComponent(val)]));
+  return Object.fromEntries(Object.entries(params).map(([key, val]) => [key, safeDecodeURIComponent(val)]));
+}
+
+function serializeHeaders(headers, serializer) {
+  const result = new NullProtoObj();
+  for (const [key, value] of Object.entries(headers)) {
+    if (Array.isArray(value)) {
+      const lines = [];
+      for (const item of value) {
+        const line2 = serializeHeaderValue(item, serializer);
+        if (line2 !== void 0) {
+          lines.push(line2);
+        }
+      }
+      result[key] = lines;
+      continue;
+    }
+    const line = serializeHeaderValue(value, serializer);
+    if (line !== void 0) {
+      result[key] = line;
+    }
+  }
+  return result;
+}
+function serializeHeaderValue(value, serializer) {
+  const serialized = serializer.serialize(value);
+  if (Array.isArray(serialized)) {
+    return serialized.filter((item) => item !== void 0 && item !== null).map(String).join(",");
+  }
+  if (isTypescriptObject(serialized)) {
+    return Object.entries(serialized).filter(([, val]) => val !== void 0 && val !== null).map(([key, val]) => `${String(key)},${String(val)}`).join(",");
+  }
+  if (serialized !== void 0 && serialized !== null) {
+    return String(serialized);
+  }
+  return void 0;
 }
 
 class OpenAPIHandlerCodecCore {
@@ -134,30 +183,28 @@ class OpenAPIHandlerCodecCore {
     this.customErrorResponseBodySerializer = options.customErrorResponseBodyEncoder;
   }
   async decodeInput(matched, request) {
-    const [_, search] = parseStandardUrl(request.url);
     const meta = getOpenAPIMeta(matched.procedure);
     const inputStructure = meta?.inputStructure ?? DEFAULT_OPENAPI_INPUT_STRUCTURE;
     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) ? this.deserializeQuery(request.url, meta?.queryStyles) : this.serializer.deserialize(await request.resolveBody(meta?.requestBodyHint));
       if (data === void 0) {
         return params;
       }
       if (!params || Object.keys(params).length < 1) {
         return data;
       }
-      if (isPlainObject(data)) {
-        return {
-          ...params,
-          ...data
-        };
+      if (!isPlainObject(data)) {
+        return params;
       }
-      return data;
+      return {
+        ...data,
+        ...params
+      };
     }
     return {
       params,
-      query,
+      query: this.deserializeQuery(request.url, meta?.queryStyles),
       headers: request.headers,
       body: this.serializer.deserialize(await request.resolveBody(meta?.requestBodyHint))
     };
@@ -180,8 +227,8 @@ class OpenAPIHandlerCodecCore {
       throw new TypeError(`
         Invalid "detailed" output structure returned by procedure (${path.join(".")}):
         \u2022 Expected an object with optional properties:
-          - status (number 200-399)
-          - headers (Record<string, string | string[] | undefined>)
+          - status (number <400)
+          - headers (object)
           - body (any)
         \u2022 No extra keys allowed.
 
@@ -191,19 +238,20 @@ class OpenAPIHandlerCodecCore {
     }
     return {
       status: output.status ?? successStatus,
-      headers: output.headers ?? {},
+      headers: output.headers !== void 0 ? serializeHeaders(output.headers, this.serializer) : {},
       body: this.serializer.serialize(output.body)
     };
   }
   encodeError(error) {
-    const status = this.errorStatusMap[error.code] ?? DEFAULT_ERROR_STATUS;
+    const status = getOwn(this.errorStatusMap, error.code) ?? DEFAULT_ERROR_STATUS;
     return {
       status,
       headers: {},
       body: this.serializer.serialize(this.customErrorResponseBodySerializer?.(error) ?? error.toJSON())
     };
   }
-  deserializeQuery(search, styles) {
+  deserializeQuery(url, styles) {
+    const [, search] = parseStandardUrl(url);
     const searchParams = new URLSearchParams(search);
     const parsed = this.serializer.deserialize(searchParams);
     if (!styles || !isPlainObject(parsed)) {
@@ -249,10 +297,10 @@ class OpenAPIHandlerCodecCore {
     }
     const parsed = { ...params };
     Object.entries(styles).forEach(([key, hint]) => {
-      if (hint === void 0 || hint === "primitive") {
+      const value = getOwn(params, key);
+      if (hint === void 0 || hint === "primitive" || value === void 0) {
         return;
       }
-      const value = params[key];
       if (hint === "comma-delimited-array") {
         parsed[key] = decodeDelimitedArray(value, ",");
       } else {
@@ -288,10 +336,10 @@ function isValidDetailedOutput(output) {
   if (Object.keys(output).some((key) => key !== "status" && key !== "headers" && key !== "body")) {
     return false;
   }
-  if (output.status !== void 0 && (typeof output.status !== "number" || !Number.isInteger(output.status) || output.status < 200 || output.status > 399)) {
+  if (output.status !== void 0 && (typeof output.status !== "number" || !Number.isInteger(output.status) || output.status > 399)) {
     return false;
   }
-  if (output.headers !== void 0 && !isStandardHeaders(output.headers)) {
+  if (output.headers !== void 0 && !isTypescriptObject(output.headers)) {
     return false;
   }
   return true;
@@ -315,4 +363,4 @@ function decodeDelimitedObject(value, delimiter) {
   return obj;
 }
 
-export { OpenAPIHandlerCodec as O, OpenAPIHandlerCodecCore as a, OpenAPIMatcher as b };
+export { OpenAPIHandlerCodec as O, OpenAPIHandlerCodecCore as a, OpenAPIMatcher as b, serializeHeaders as s };

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

@@ -1,7 +1,7 @@
-import { wrapEventIteratorPreservingMeta, 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';
+import { wrapAsyncIteratorPreservingEventMeta, toORPCError, isORPCErrorJson, createORPCErrorFromJson } from '@orpc/client';
+import { isPlainObject, NullProtoObj, copyOnWrite, isAsyncIteratorObject } from '@orpc/shared';
+import { ErrorEvent } from '@standard-server/core';
+import { B as BracketNotationSerializer } from './openapi.B2G-HeFn.mjs';
 
 const DEFAULT_OPENAPI_METHOD = "POST";
 const DEFAULT_OPENAPI_SUCCESS_DESCRIPTION = "OK";
@@ -48,18 +48,18 @@ const DEFAULT_OPEN_API_JSON_SERIALIZER_HANDLERS = {
     },
     isTerminal: true
   },
-  url: {
+  infinity: {
     condition(data) {
-      return data instanceof URL;
+      return data === Number.POSITIVE_INFINITY || data === Number.NEGATIVE_INFINITY;
     },
-    serialize(data) {
-      return data.toString();
+    serialize() {
+      return null;
     },
     isTerminal: true
   },
-  regexp: {
+  url: {
     condition(data) {
-      return data instanceof RegExp;
+      return data instanceof URL;
     },
     serialize(data) {
       return data.toString();
@@ -84,45 +84,114 @@ const DEFAULT_OPEN_API_JSON_SERIALIZER_HANDLERS = {
   }
 };
 class OpenAPIJsonSerializer {
-  handlers;
+  inlineBuiltInHandlers;
+  handlerEntries;
   omitUndefinedProperties;
   constructor(options = {}) {
-    this.handlers = {
-      ...DEFAULT_OPEN_API_JSON_SERIALIZER_HANDLERS,
-      ...options.handlers
-    };
     this.omitUndefinedProperties = options.omitUndefinedProperties !== false;
+    const customHandlers = options.handlers;
+    if (customHandlers === void 0) {
+      this.inlineBuiltInHandlers = true;
+      return;
+    }
+    let inlineBuiltInHandlers = true;
+    let handlerEntries = [];
+    for (const key of Object.keys(customHandlers)) {
+      const handler = customHandlers[key];
+      if (inlineBuiltInHandlers && key in DEFAULT_OPEN_API_JSON_SERIALIZER_HANDLERS) {
+        inlineBuiltInHandlers = false;
+        break;
+      }
+      if (handler !== void 0) {
+        handlerEntries.push(handler);
+      }
+    }
+    if (!inlineBuiltInHandlers) {
+      handlerEntries = [];
+      for (const handler of Object.values({ ...DEFAULT_OPEN_API_JSON_SERIALIZER_HANDLERS, ...customHandlers })) {
+        if (handler !== void 0) {
+          handlerEntries.push(handler);
+        }
+      }
+    }
+    this.inlineBuiltInHandlers = inlineBuiltInHandlers;
+    this.handlerEntries = handlerEntries;
   }
   serialize(data) {
-    const [json, maps, blobs] = this.serializeValue(data, [], [], []);
+    const maps = [];
+    const blobs = [];
+    const json = this.serializeValue(data, [], maps, blobs);
     return { json, maps, blobs };
   }
+  /**
+   * `segments` is a shared mutable stack (push/pop while walking),
+   * so it must be copied before being stored in `maps`.
+   */
   serializeValue(data, segments, maps, blobs) {
-    for (const key in this.handlers) {
-      const handler = this.handlers[key];
-      if (handler && handler.condition(data)) {
-        const serialized = handler.serialize(data);
-        if (handler.isTerminal) {
-          return [serialized, maps, blobs];
+    if (this.inlineBuiltInHandlers) {
+      switch (typeof data) {
+        case "string":
+        case "boolean":
+          return data;
+        case "number":
+          return Number.isFinite(data) ? data : null;
+        case "undefined":
+          return null;
+        case "bigint":
+          return data.toString();
+        case "object": {
+          if (data === null) {
+            return data;
+          }
+          if (data instanceof Date) {
+            return Number.isNaN(data.getTime()) ? null : data.toISOString();
+          }
+          if (data instanceof URL) {
+            return data.toString();
+          }
+          if (data instanceof Set) {
+            return this.serializeValue(Array.from(data), segments, maps, blobs);
+          }
+          if (data instanceof Map) {
+            return this.serializeValue(Array.from(data.entries()), segments, maps, blobs);
+          }
+        }
+      }
+    }
+    const handlerEntries = this.handlerEntries;
+    if (handlerEntries) {
+      for (let i = 0; i < handlerEntries.length; i++) {
+        const handler = handlerEntries[i];
+        if (handler.condition(data)) {
+          const serialized = handler.serialize(data);
+          if (handler.isTerminal) {
+            if (serialized instanceof Blob) {
+              maps.push(segments.slice());
+              blobs.push(serialized);
+            }
+            return serialized;
+          }
+          return this.serializeValue(serialized, segments, maps, blobs);
         }
-        const result = this.serializeValue(serialized, segments, maps, blobs);
-        return result;
       }
     }
     if (data instanceof Blob) {
-      maps.push(segments);
+      maps.push(segments.slice());
       blobs.push(data);
-      return [data, maps, blobs];
+      return data;
     }
     if (Array.isArray(data)) {
-      const json = data.map((v, i) => {
-        return this.serializeValue(v, [...segments, i], maps, blobs)[0];
-      });
-      return [json, maps, blobs];
+      const json = [];
+      for (let i = 0; i < data.length; i++) {
+        segments.push(i);
+        json.push(this.serializeValue(data[i], segments, maps, blobs));
+        segments.pop();
+      }
+      return json;
     }
     if (isPlainObject(data)) {
-      const json = {};
-      for (const k in data) {
+      const json = new NullProtoObj();
+      for (const k of Object.keys(data)) {
         const v = data[k];
         if (k === "toJSON" && typeof v === "function") {
           continue;
@@ -130,29 +199,38 @@ class OpenAPIJsonSerializer {
         if (v === void 0 && this.omitUndefinedProperties) {
           continue;
         }
-        json[k] = this.serializeValue(v, [...segments, k], maps, blobs)[0];
+        segments.push(k);
+        json[k] = this.serializeValue(v, segments, maps, blobs);
+        segments.pop();
       }
-      return [json, maps, blobs];
+      return json;
     }
-    return [data, maps, blobs];
+    return data;
   }
   deserialize(serialized) {
-    const ref = { data: serialized.json };
+    const ref = { json: serialized.json };
     if (serialized.blobs?.length) {
-      serialized.maps.forEach((segments, i) => {
+      for (let i = 0; i < serialized.maps.length; i++) {
+        const blob = serialized.blobs[i];
+        if (!(blob instanceof Blob)) {
+          throw new TypeError(`Invalid OpenAPI serialized data: blob ${i} is not a Blob.`);
+        }
+        const segments = serialized.maps[i];
+        let original = serialized;
         let currentRef = ref;
-        let preSegment = "data";
-        segments.forEach((segment) => {
-          currentRef = currentRef[preSegment];
-          preSegment = segment;
+        let preSegment = "json";
+        for (let j = 0; j < segments.length; j++) {
+          original = original[preSegment];
+          currentRef = copyOnWrite(currentRef, preSegment, original);
+          preSegment = segments[j];
           if (!Object.hasOwn(currentRef, preSegment)) {
-            throw new Error(`Security error: Invalid serialized data. Segment "${preSegment}" does not exist.`);
+            throw new TypeError(`Invalid OpenAPI serialized data: segment "${preSegment}" does not exist.`);
           }
-        });
-        currentRef[preSegment] = serialized.blobs[i];
-      });
+        }
+        currentRef[preSegment] = blob;
+      }
     }
-    return ref.data;
+    return ref.json;
   }
 }
 
@@ -166,34 +244,32 @@ class OpenAPISerializer {
     this.defaultSerializeOptions = serialize;
   }
   serialize(data, options = {}) {
-    const useFormDataForBlobFields = options.useFormDataForBlobFields ?? this.defaultSerializeOptions?.useFormDataForBlobFields ?? true;
-    const asFormData = options.asFormData ?? this.defaultSerializeOptions?.asFormData ?? false;
     if (!options.asFormData) {
       if (data === void 0 || data instanceof ReadableStream || data instanceof Blob) {
         return data;
       }
       if (isAsyncIteratorObject(data)) {
-        return wrapEventIteratorPreservingMeta(data, {
+        return wrapAsyncIteratorPreservingEventMeta(data, {
           mapResult: (result) => {
             if (result.value === void 0) {
               return result;
             }
-            return { done: result.done, value: this.serializeValue(result.value, { asFormData: false, useFormDataForBlobFields: false }) };
+            return { done: result.done, value: this.serializeValue(result.value, false, false) };
           },
-          mapError: (e) => {
-            return new ErrorEvent({
-              data: this.serializeValue(toORPCError(e).toJSON(), { asFormData: false, useFormDataForBlobFields: false }),
-              cause: e
-            });
-          }
+          mapError: (e) => new ErrorEvent(
+            this.serializeValue(toORPCError(e).toJSON(), false, false),
+            { cause: e }
+          )
         });
       }
     }
-    return this.serializeValue(data, { useFormDataForBlobFields, asFormData });
+    const useFormDataForBlobFields = options.useFormDataForBlobFields ?? this.defaultSerializeOptions?.useFormDataForBlobFields ?? true;
+    const asFormData = options.asFormData ?? this.defaultSerializeOptions?.asFormData ?? false;
+    return this.serializeValue(data, useFormDataForBlobFields, asFormData);
   }
-  serializeValue(value, options) {
+  serializeValue(value, useFormDataForBlobFields, asFormData) {
     const { json, blobs } = this.jsonSerializer.serialize(value);
-    if (!options.asFormData && (json instanceof Blob || json === void 0 || !blobs?.length || !options.useFormDataForBlobFields)) {
+    if (!asFormData && (json instanceof Blob || json === void 0 || !blobs?.length || !useFormDataForBlobFields)) {
       return json;
     }
     const form = new FormData();
@@ -211,7 +287,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 +312,9 @@ class OpenAPISerializer {
   }
 }
 
+function isBodylessMethod(method) {
+  return method === "GET" || method === "HEAD";
+}
 const PARAMETER_NAME_REGEX = /^[\w-]+$/;
 function getDynamicPathParams(path) {
   if (!path.includes("{")) {
@@ -272,4 +351,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/dist/shared/{openapi.C7m7NAmH.d.mts → openapi.C2LayTNZ.d.mts}

@@ -1,4 +1,4 @@
-import { StandardBody } from '@standardserver/core';
+import { StandardBody } from '@standard-server/core';
 import { Segment } from '@orpc/shared';
 
 type BracketNotationSerializeResult = [string, unknown][];
@@ -81,10 +81,10 @@ interface OpenAPIJsonSerializerOptions {
      *
      * **Disabling:** Set a key to `undefined` to remove a built-in handler:
      * ```ts
-     * handlers: { regexp: undefined }
+     * handlers: { url: undefined }
      * ```
      *
-     * Built-in type keys: `undefined`, `bigint`, `date`, `nan`, `url`, `regexp`, `set`, `map`.
+     * Built-in type keys: `undefined`, `bigint`, `date`, `nan`, `infinity`, `url`, `set`, `map`.
      */
     handlers?: Record<string, undefined | OpenAPIJsonSerializerHandler> | undefined;
     /**
@@ -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;