@orpc/openapi 1.14.5 → 2.0.0-beta.1

package/dist/shared/openapi.Bt87OzTt.mjs

@@ -0,0 +1,131 @@
+import { isPlainObject, NullProtoObj } from '@orpc/shared';
+
+class BracketNotationSerializer {
+  maxExplicitDeserializingArrayIndex;
+  constructor(options = {}) {
+    this.maxExplicitDeserializingArrayIndex = options.maxExplicitDeserializingArrayIndex ?? 999;
+  }
+  serialize(data) {
+    return this.internalSerialize(data, [], []);
+  }
+  internalSerialize(data, segments, result) {
+    if (Array.isArray(data)) {
+      data.forEach((item, i) => {
+        this.internalSerialize(item, [...segments, i], result);
+      });
+    } else if (isPlainObject(data)) {
+      for (const key in data) {
+        this.internalSerialize(data[key], [...segments, key], result);
+      }
+    } else {
+      result.push([this.stringifyPath(segments), data]);
+    }
+    return result;
+  }
+  deserialize(serialized) {
+    if (serialized.length === 0) {
+      return new NullProtoObj();
+    }
+    const arrayPushStyles = /* @__PURE__ */ new WeakSet();
+    const ref = { value: new NullProtoObj() };
+    for (const [path, value] of serialized) {
+      const segments = this.parsePath(path);
+      let currentRef = ref;
+      let nextSegment = "value";
+      segments.forEach((segment, i) => {
+        if (!Array.isArray(currentRef[nextSegment]) && !isPlainObject(currentRef[nextSegment])) {
+          currentRef[nextSegment] = [];
+        }
+        if (i !== segments.length - 1) {
+          if (Array.isArray(currentRef[nextSegment]) && !internalIsValidArrayIndex(segment, this.maxExplicitDeserializingArrayIndex)) {
+            if (arrayPushStyles.has(currentRef[nextSegment])) {
+              arrayPushStyles.delete(currentRef[nextSegment]);
+              currentRef[nextSegment] = internalPushStyleArrayToObject(currentRef[nextSegment]);
+            } else {
+              currentRef[nextSegment] = internalArrayToObject(currentRef[nextSegment]);
+            }
+          }
+        } else {
+          if (Array.isArray(currentRef[nextSegment])) {
+            if (segment === "") {
+              if (currentRef[nextSegment].length && !arrayPushStyles.has(currentRef[nextSegment])) {
+                currentRef[nextSegment] = internalArrayToObject(currentRef[nextSegment]);
+              }
+            } else {
+              if (arrayPushStyles.has(currentRef[nextSegment])) {
+                arrayPushStyles.delete(currentRef[nextSegment]);
+                currentRef[nextSegment] = internalPushStyleArrayToObject(currentRef[nextSegment]);
+              } else if (!internalIsValidArrayIndex(segment, this.maxExplicitDeserializingArrayIndex)) {
+                currentRef[nextSegment] = internalArrayToObject(currentRef[nextSegment]);
+              }
+            }
+          }
+        }
+        currentRef = currentRef[nextSegment];
+        nextSegment = segment;
+      });
+      if (Array.isArray(currentRef) && nextSegment === "") {
+        arrayPushStyles.add(currentRef);
+        currentRef.push(value);
+      } else if (nextSegment in currentRef) {
+        if (Array.isArray(currentRef[nextSegment])) {
+          currentRef[nextSegment].push(value);
+        } else {
+          currentRef[nextSegment] = [currentRef[nextSegment], value];
+        }
+      } else {
+        currentRef[nextSegment] = value;
+      }
+    }
+    return ref.value;
+  }
+  stringifyPath(segments) {
+    return segments.reduce((result, segment, i) => {
+      if (i === 0) {
+        return segment.toString();
+      }
+      return `${result}[${segment}]`;
+    }, "");
+  }
+  parsePath(path) {
+    const segments = [];
+    let inBrackets = false;
+    let currentSegment = "";
+    for (let i = 0; i < path.length; i++) {
+      const char = path[i];
+      const nextChar = path[i + 1];
+      if (inBrackets && char === "]" && (nextChar === void 0 || nextChar === "[")) {
+        if (nextChar === void 0) {
+          inBrackets = false;
+        }
+        segments.push(currentSegment);
+        currentSegment = "";
+        i++;
+      } else if (segments.length === 0 && char === "[") {
+        inBrackets = true;
+        segments.push(currentSegment);
+        currentSegment = "";
+      } else {
+        currentSegment += char;
+      }
+    }
+    return inBrackets || segments.length === 0 ? [path] : segments;
+  }
+}
+function internalIsValidArrayIndex(value, maxIndex) {
+  return /^0$|^[1-9]\d*$/.test(value) && Number(value) <= maxIndex;
+}
+function internalArrayToObject(array) {
+  const obj = new NullProtoObj();
+  array.forEach((item, i) => {
+    obj[i] = item;
+  });
+  return obj;
+}
+function internalPushStyleArrayToObject(array) {
+  const obj = new NullProtoObj();
+  obj[""] = array.length === 1 ? array[0] : array;
+  return obj;
+}
+
+export { BracketNotationSerializer as B };

package/dist/shared/openapi.C7m7NAmH.d.mts

@@ -0,0 +1,142 @@
+import { StandardBody } from '@standardserver/core';
+import { Segment } from '@orpc/shared';
+
+type BracketNotationSerializeResult = [string, unknown][];
+interface BracketNotationSerializerOptions {
+    /**
+     * Maximum explicit array index allowed during deserialization (e.g., `arr[0]`, `arr[999]`).
+     * If the index exceeds this limit, the array is deserialized as an object instead.
+     *
+     * This guards against memory exhaustion attacks where malicious input uses extremely large
+     * indices (e.g., `?arr[4294967296]=value`). Although orpc uses sparse arrays handle large indices
+     * efficiently, downstream code may inadvertently densify them - creating millions of
+     * undefined slots and exhausting memory.
+     *
+     * NOTE: Does not apply to append-style notation (e.g., `arr[]`).
+     *
+     * @default 999 (array with 1,000 elements)
+     */
+    maxExplicitDeserializingArrayIndex?: number;
+}
+declare class BracketNotationSerializer {
+    private readonly maxExplicitDeserializingArrayIndex;
+    constructor(options?: BracketNotationSerializerOptions);
+    serialize(data: unknown): BracketNotationSerializeResult;
+    private internalSerialize;
+    deserialize(serialized: BracketNotationSerializeResult): Record<string, unknown>;
+    stringifyPath(segments: readonly Segment[]): string;
+    parsePath(path: string): string[];
+}
+
+type OpenAPIJsonSerialization = {
+    json: unknown;
+    maps?: undefined;
+    blobs?: undefined;
+} | {
+    json: unknown;
+    maps: Segment[][];
+    blobs: Blob[];
+};
+interface OpenAPIJsonSerializerHandler {
+    condition(value: unknown): boolean;
+    serialize(value: any): unknown;
+    /**
+     * If false, the result of this serializer will not be further processed by other serializers,
+     * even if it matches their conditions and treat it as final serialized value.
+     * This can be useful for serializers that return primitive values, which should not be further processed.
+     * to improve performance and avoid potential issues with other serializers.
+     *
+     * @default false
+     */
+    isTerminal?: boolean;
+}
+interface OpenAPIJsonSerializerOptions {
+    /**
+     * Extend or override the built-in type handlers used during serialization.
+     *
+     * Each key is a unique type identifier (e.g. `"date"`, `"bigint"`) and maps to a handler
+     * that defines how to detect and serialize values of that type.
+     *
+     * **Extending:** Add new keys to support custom types:
+     * ```ts
+     * handlers: {
+     *   buffer: {
+     *     condition: (v) => v instanceof Buffer,
+     *     serialize: (v: Buffer) => v.toString('base64'),
+     *     isTerminal: true,
+     *   }
+     * }
+     * ```
+     *
+     * **Overriding:** Use an existing key to replace a built-in handler:
+     * ```ts
+     * handlers: {
+     *   date: {
+     *     condition: (v) => v instanceof Date,
+     *     serialize: (v: Date) => v.getTime(),
+     *     isTerminal: true,
+     *   }
+     * }
+     * ```
+     *
+     * **Disabling:** Set a key to `undefined` to remove a built-in handler:
+     * ```ts
+     * handlers: { regexp: undefined }
+     * ```
+     *
+     * Built-in type keys: `undefined`, `bigint`, `date`, `nan`, `url`, `regexp`, `set`, `map`.
+     */
+    handlers?: Record<string, undefined | OpenAPIJsonSerializerHandler> | undefined;
+    /**
+     * If true, properties with undefined values will be omitted during serialization.
+     *
+     * @default true
+     */
+    omitUndefinedProperties?: boolean | undefined;
+}
+declare class OpenAPIJsonSerializer {
+    private readonly handlers;
+    private readonly omitUndefinedProperties;
+    constructor(options?: OpenAPIJsonSerializerOptions);
+    serialize(data: unknown): OpenAPIJsonSerialization;
+    private serializeValue;
+    deserialize(serialized: OpenAPIJsonSerialization): unknown;
+}
+
+interface OpenAPISerializerSerializeOptions {
+    /**
+     * Use FormData for serialization when nested blobs are present.
+     * Does not apply to root-level Blob values.
+     *
+     * @default true
+     */
+    useFormDataForBlobFields?: boolean;
+    /**
+     * When enabled, the serialized output is always returned as a FormData instance using bracket notation.
+     *
+     * @default false
+     */
+    asFormData?: boolean | undefined;
+}
+interface OpenAPISerializerOptions extends OpenAPIJsonSerializerOptions, OpenAPISerializerSerializeOptions {
+    /**
+     * Options for bracket notation serializer, like maxExplicitDeserializingArrayIndex
+     */
+    bracketNotation?: BracketNotationSerializerOptions | undefined;
+    /**
+     * Default options for serialize method
+     */
+    serialize?: OpenAPISerializerSerializeOptions | undefined;
+}
+declare class OpenAPISerializer {
+    private readonly jsonSerializer;
+    private readonly bracketNotation;
+    private readonly defaultSerializeOptions;
+    constructor({ bracketNotation, serialize, ...options }?: OpenAPISerializerOptions);
+    serialize(data: unknown, options?: OpenAPISerializerSerializeOptions): StandardBody;
+    private serializeValue;
+    deserialize(data: StandardBody): unknown;
+}
+
+export { OpenAPISerializer as O, BracketNotationSerializer as a, OpenAPIJsonSerializer as d };
+export type { BracketNotationSerializeResult as B, BracketNotationSerializerOptions as b, OpenAPIJsonSerialization as c, OpenAPIJsonSerializerHandler as e, OpenAPIJsonSerializerOptions as f, OpenAPISerializerOptions as g, OpenAPISerializerSerializeOptions as h };

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

@@ -0,0 +1,142 @@
+import { StandardBody } from '@standardserver/core';
+import { Segment } from '@orpc/shared';
+
+type BracketNotationSerializeResult = [string, unknown][];
+interface BracketNotationSerializerOptions {
+    /**
+     * Maximum explicit array index allowed during deserialization (e.g., `arr[0]`, `arr[999]`).
+     * If the index exceeds this limit, the array is deserialized as an object instead.
+     *
+     * This guards against memory exhaustion attacks where malicious input uses extremely large
+     * indices (e.g., `?arr[4294967296]=value`). Although orpc uses sparse arrays handle large indices
+     * efficiently, downstream code may inadvertently densify them - creating millions of
+     * undefined slots and exhausting memory.
+     *
+     * NOTE: Does not apply to append-style notation (e.g., `arr[]`).
+     *
+     * @default 999 (array with 1,000 elements)
+     */
+    maxExplicitDeserializingArrayIndex?: number;
+}
+declare class BracketNotationSerializer {
+    private readonly maxExplicitDeserializingArrayIndex;
+    constructor(options?: BracketNotationSerializerOptions);
+    serialize(data: unknown): BracketNotationSerializeResult;
+    private internalSerialize;
+    deserialize(serialized: BracketNotationSerializeResult): Record<string, unknown>;
+    stringifyPath(segments: readonly Segment[]): string;
+    parsePath(path: string): string[];
+}
+
+type OpenAPIJsonSerialization = {
+    json: unknown;
+    maps?: undefined;
+    blobs?: undefined;
+} | {
+    json: unknown;
+    maps: Segment[][];
+    blobs: Blob[];
+};
+interface OpenAPIJsonSerializerHandler {
+    condition(value: unknown): boolean;
+    serialize(value: any): unknown;
+    /**
+     * If false, the result of this serializer will not be further processed by other serializers,
+     * even if it matches their conditions and treat it as final serialized value.
+     * This can be useful for serializers that return primitive values, which should not be further processed.
+     * to improve performance and avoid potential issues with other serializers.
+     *
+     * @default false
+     */
+    isTerminal?: boolean;
+}
+interface OpenAPIJsonSerializerOptions {
+    /**
+     * Extend or override the built-in type handlers used during serialization.
+     *
+     * Each key is a unique type identifier (e.g. `"date"`, `"bigint"`) and maps to a handler
+     * that defines how to detect and serialize values of that type.
+     *
+     * **Extending:** Add new keys to support custom types:
+     * ```ts
+     * handlers: {
+     *   buffer: {
+     *     condition: (v) => v instanceof Buffer,
+     *     serialize: (v: Buffer) => v.toString('base64'),
+     *     isTerminal: true,
+     *   }
+     * }
+     * ```
+     *
+     * **Overriding:** Use an existing key to replace a built-in handler:
+     * ```ts
+     * handlers: {
+     *   date: {
+     *     condition: (v) => v instanceof Date,
+     *     serialize: (v: Date) => v.getTime(),
+     *     isTerminal: true,
+     *   }
+     * }
+     * ```
+     *
+     * **Disabling:** Set a key to `undefined` to remove a built-in handler:
+     * ```ts
+     * handlers: { regexp: undefined }
+     * ```
+     *
+     * Built-in type keys: `undefined`, `bigint`, `date`, `nan`, `url`, `regexp`, `set`, `map`.
+     */
+    handlers?: Record<string, undefined | OpenAPIJsonSerializerHandler> | undefined;
+    /**
+     * If true, properties with undefined values will be omitted during serialization.
+     *
+     * @default true
+     */
+    omitUndefinedProperties?: boolean | undefined;
+}
+declare class OpenAPIJsonSerializer {
+    private readonly handlers;
+    private readonly omitUndefinedProperties;
+    constructor(options?: OpenAPIJsonSerializerOptions);
+    serialize(data: unknown): OpenAPIJsonSerialization;
+    private serializeValue;
+    deserialize(serialized: OpenAPIJsonSerialization): unknown;
+}
+
+interface OpenAPISerializerSerializeOptions {
+    /**
+     * Use FormData for serialization when nested blobs are present.
+     * Does not apply to root-level Blob values.
+     *
+     * @default true
+     */
+    useFormDataForBlobFields?: boolean;
+    /**
+     * When enabled, the serialized output is always returned as a FormData instance using bracket notation.
+     *
+     * @default false
+     */
+    asFormData?: boolean | undefined;
+}
+interface OpenAPISerializerOptions extends OpenAPIJsonSerializerOptions, OpenAPISerializerSerializeOptions {
+    /**
+     * Options for bracket notation serializer, like maxExplicitDeserializingArrayIndex
+     */
+    bracketNotation?: BracketNotationSerializerOptions | undefined;
+    /**
+     * Default options for serialize method
+     */
+    serialize?: OpenAPISerializerSerializeOptions | undefined;
+}
+declare class OpenAPISerializer {
+    private readonly jsonSerializer;
+    private readonly bracketNotation;
+    private readonly defaultSerializeOptions;
+    constructor({ bracketNotation, serialize, ...options }?: OpenAPISerializerOptions);
+    serialize(data: unknown, options?: OpenAPISerializerSerializeOptions): StandardBody;
+    private serializeValue;
+    deserialize(data: StandardBody): unknown;
+}
+
+export { OpenAPISerializer as O, BracketNotationSerializer as a, OpenAPIJsonSerializer as d };
+export type { BracketNotationSerializeResult as B, BracketNotationSerializerOptions as b, OpenAPIJsonSerialization as c, OpenAPIJsonSerializerHandler as e, OpenAPIJsonSerializerOptions as f, OpenAPISerializerOptions as g, OpenAPISerializerSerializeOptions as h };

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

@@ -0,0 +1,75 @@
+import { AnyORPCError } from '@orpc/client';
+import { AnyProcedure, AnyRouter, Context } from '@orpc/server';
+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';
+
+interface OpenAPIMatcherOptions {
+    /**
+     * Filter which procedures are exposed for matching. Return `false` to exclude.
+     *
+     * @default true
+     */
+    filter?: Value<boolean, [contract: AnyProcedureContract | AnyProcedure, path: string[]]>;
+}
+declare class OpenAPIMatcher {
+    private readonly filter;
+    private readonly rootRouter;
+    private readonly tree;
+    private pendingLazyRouters;
+    constructor(router: AnyRouter, options?: OpenAPIMatcherOptions);
+    private index;
+    match(method: string, pathname: `/${string}`, prefix: `/${string}` | undefined): Promise<{
+        path: string[];
+        procedure: AnyProcedure;
+        params?: Record<string, string> | undefined;
+    } | undefined>;
+    private matchPathname;
+    private resolvePendingLazyRouters;
+    private resolveProcedure;
+}
+
+declare class OpenAPIHandlerCodecError extends TypeError {
+}
+interface OpenAPIHandlerCodecOptions<_T extends Context> extends OpenAPIMatcherOptions {
+    /**
+     * Override the default OpenAPI serializer.
+     */
+    serializer?: Pick<OpenAPISerializer, keyof OpenAPISerializer>;
+    /**
+     * Mapping ORPCError Code -> HTTP Status Code
+     *
+     * @default COMMON_ERROR_STATUS_MAP, DEFAULT_ERROR_STATUS
+     */
+    errorStatusMap?: Record<string, number> | undefined;
+    /**
+     * Customize how an ORPC error is serialized into a response body.
+     * Use this if your API needs a different error output structure.
+     *
+     * @remarks
+     * - Return `null | undefined` to fallback to default behavior
+     *
+     * @default ((e) => e.toJSON())
+     */
+    customErrorResponseBodyEncoder?: (error: AnyORPCError) => unknown;
+}
+declare class OpenAPIHandlerCodec<T extends Context> implements StandardHandlerCodec<T> {
+    private readonly matcher;
+    private readonly serializer;
+    private readonly errorStatusMap;
+    private readonly customErrorResponseBodySerializer;
+    constructor(router: AnyRouter, options?: OpenAPIHandlerCodecOptions<T>);
+    resolveProcedure(request: StandardLazyRequest, options: StandardHandlerHandleOptions<T>): Promise<StandardHandlerCodecResolvedProcedure | undefined>;
+    /**
+     * @throws {Error} 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>;
+    private deserializeQuery;
+    private deserializeParams;
+}
+
+export { OpenAPIHandlerCodec as a, OpenAPIHandlerCodecError as b, OpenAPIMatcher as c };
+export type { OpenAPIHandlerCodecOptions as O, OpenAPIMatcherOptions as d };

package/dist/shared/openapi.CYgMBSUF.d.mts

@@ -0,0 +1,18 @@
+import { OpenAPIV3_1 } from '@hey-api/spec-types';
+import { ORPCError, AnyNestedClient, Client } from '@orpc/client';
+
+type OpenAPIDocument = OpenAPIV3_1.Document;
+type OpenAPIOperationObject = OpenAPIV3_1.OperationObject;
+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;
+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
+ */
+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 };

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

@@ -0,0 +1,18 @@
+import { OpenAPIV3_1 } from '@hey-api/spec-types';
+import { ORPCError, AnyNestedClient, Client } from '@orpc/client';
+
+type OpenAPIDocument = OpenAPIV3_1.Document;
+type OpenAPIOperationObject = OpenAPIV3_1.OperationObject;
+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;
+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
+ */
+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 };