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

package/dist/plugins/index.d.mts

@@ -2,10 +2,10 @@ import { Context } from '@orpc/server';
 import { StandardHandlerPlugin, StandardHandlerRoutingInterceptorOptions, StandardHandlerOptions } from '@orpc/server/standard';
 import { Value, Promisable } from '@orpc/shared';
 import { ApiReferenceConfiguration } from '@scalar/api-reference';
-import { StandardUrl } from '@standardserver/core';
+import { StandardUrl } from '@standard-server/core';
 import { SwaggerUIOptions } from 'swagger-ui';
-import { a as OpenAPIDocument } from '../shared/openapi.CYgMBSUF.mjs';
-import '@hey-api/spec-types';
+import { OpenAPIDocument, OpenAPIVersion } from '../index.mjs';
+import '@openapi-spec/types';
 import '@orpc/client';
 
 type OpenAPIReferenceHandlerPluginProvider = 'scalar' | 'swagger';
@@ -21,7 +21,14 @@ interface OpenAPIReferenceHandlerPluginOptions<T extends Context, TProvider exte
      * A static or dynamic OpenAPI document to serve.
      * Receives routing interceptor options when provided as a function.
      */
-    spec: Value<Promisable<OpenAPIDocument>, [StandardHandlerRoutingInterceptorOptions<T>]>;
+    spec: Value<Promisable<OpenAPIDocument<OpenAPIVersion>>, [StandardHandlerRoutingInterceptorOptions<T>]>;
+    /**
+     * Determines whether the docs UI and OpenAPI JSON are allowed to be served for a request.
+     * When it resolves to `false`, the request falls through as unmatched,
+     * as if the plugin were not installed. Useful for restricting access
+     * to authenticated users.
+     */
+    allow?: Value<Promisable<boolean>, [StandardHandlerRoutingInterceptorOptions<T>]>;
     /**
      * The URL path at which to serve the OpenAPI JSON.
      *
@@ -71,9 +78,19 @@ interface OpenAPIReferenceHandlerPluginOptions<T extends Context, TProvider exte
      */
     docsHead?: Value<Promisable<string>, [StandardHandlerRoutingInterceptorOptions<T>]>;
 }
+/**
+ * Serves API reference documentation powered by Scalar or Swagger UI,
+ * and exposes the OpenAPI specification as JSON.
+ *
+ * @remarks
+ * **Note**: By default, the API reference UI is served from `/` and the OpenAPI specification from `/spec.json`.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/openapi-reference | OpenAPI Reference Plugin (Swagger/Scalar)}
+ */
 declare class OpenAPIReferenceHandlerPlugin<T extends Context, TProvider extends OpenAPIReferenceHandlerPluginProvider> implements StandardHandlerPlugin<T> {
     name: string;
     private readonly spec;
+    private readonly allow;
     private readonly specPath;
     private readonly provider;
     private readonly providerConfig;

package/dist/plugins/index.d.ts

@@ -2,10 +2,10 @@ import { Context } from '@orpc/server';
 import { StandardHandlerPlugin, StandardHandlerRoutingInterceptorOptions, StandardHandlerOptions } from '@orpc/server/standard';
 import { Value, Promisable } from '@orpc/shared';
 import { ApiReferenceConfiguration } from '@scalar/api-reference';
-import { StandardUrl } from '@standardserver/core';
+import { StandardUrl } from '@standard-server/core';
 import { SwaggerUIOptions } from 'swagger-ui';
-import { a as OpenAPIDocument } from '../shared/openapi.CYgMBSUF.js';
-import '@hey-api/spec-types';
+import { OpenAPIDocument, OpenAPIVersion } from '../index.js';
+import '@openapi-spec/types';
 import '@orpc/client';
 
 type OpenAPIReferenceHandlerPluginProvider = 'scalar' | 'swagger';
@@ -21,7 +21,14 @@ interface OpenAPIReferenceHandlerPluginOptions<T extends Context, TProvider exte
      * A static or dynamic OpenAPI document to serve.
      * Receives routing interceptor options when provided as a function.
      */
-    spec: Value<Promisable<OpenAPIDocument>, [StandardHandlerRoutingInterceptorOptions<T>]>;
+    spec: Value<Promisable<OpenAPIDocument<OpenAPIVersion>>, [StandardHandlerRoutingInterceptorOptions<T>]>;
+    /**
+     * Determines whether the docs UI and OpenAPI JSON are allowed to be served for a request.
+     * When it resolves to `false`, the request falls through as unmatched,
+     * as if the plugin were not installed. Useful for restricting access
+     * to authenticated users.
+     */
+    allow?: Value<Promisable<boolean>, [StandardHandlerRoutingInterceptorOptions<T>]>;
     /**
      * The URL path at which to serve the OpenAPI JSON.
      *
@@ -71,9 +78,19 @@ interface OpenAPIReferenceHandlerPluginOptions<T extends Context, TProvider exte
      */
     docsHead?: Value<Promisable<string>, [StandardHandlerRoutingInterceptorOptions<T>]>;
 }
+/**
+ * Serves API reference documentation powered by Scalar or Swagger UI,
+ * and exposes the OpenAPI specification as JSON.
+ *
+ * @remarks
+ * **Note**: By default, the API reference UI is served from `/` and the OpenAPI specification from `/spec.json`.
+ *
+ * @see {@link https://orpc.dev/docs/plugins/openapi-reference | OpenAPI Reference Plugin (Swagger/Scalar)}
+ */
 declare class OpenAPIReferenceHandlerPlugin<T extends Context, TProvider extends OpenAPIReferenceHandlerPluginProvider> implements StandardHandlerPlugin<T> {
     name: string;
     private readonly spec;
+    private readonly allow;
     private readonly specPath;
     private readonly provider;
     private readonly providerConfig;

package/dist/plugins/index.mjs

@@ -1,8 +1,9 @@
-import { toArray, matchesHttpPath, mergeHttpPath, getOpenTelemetryConfig, value, stringifyJSON } from '@orpc/shared';
+import { toArray, matchesHttpPath, mergeHttpPath, value, getTracer, stringifyJSON } from '@orpc/shared';
 
 class OpenAPIReferenceHandlerPlugin {
   name = "~openapi-reference";
   spec;
+  allow;
   specPath;
   provider;
   providerConfig;
@@ -13,6 +14,7 @@ class OpenAPIReferenceHandlerPlugin {
   docsHead;
   constructor(options) {
     this.spec = options.spec;
+    this.allow = options.allow;
     this.specPath = options.specPath ?? "/spec.json";
     this.provider = options.provider ?? "scalar";
     this.providerConfig = options.providerConfig;
@@ -44,7 +46,10 @@ class OpenAPIReferenceHandlerPlugin {
           if (!isSpecPath && !isDocsPath) {
             return result;
           }
-          const span = getOpenTelemetryConfig()?.trace.getActiveSpan();
+          if (await value(this.allow, routingInterceptorOptions) === false) {
+            return result;
+          }
+          const span = getTracer()?.getActiveSpan();
           const spec = await value(this.spec, routingInterceptorOptions);
           if (isSpecPath) {
             span?.updateName(`${routingInterceptorOptions.request.method} ${routingInterceptorOptions.request.url} (openapi spec)`);

package/dist/shared/{openapi.DmAa7YPO.mjs → openapi.B1LWf28E.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";
@@ -57,15 +57,6 @@ const DEFAULT_OPEN_API_JSON_SERIALIZER_HANDLERS = {
     },
     isTerminal: true
   },
-  regexp: {
-    condition(data) {
-      return data instanceof RegExp;
-    },
-    serialize(data) {
-      return data.toString();
-    },
-    isTerminal: true
-  },
   set: {
     condition(data) {
       return data instanceof Set;
@@ -84,45 +75,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.isNaN(data) ? null : data;
+        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 +190,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 +235,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 +278,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 +303,9 @@ class OpenAPISerializer {
   }
 }
 
+function isBodylessMethod(method) {
+  return method === "GET" || method === "HEAD";
+}
 const PARAMETER_NAME_REGEX = /^[\w-]+$/;
 function getDynamicPathParams(path) {
   if (!path.includes("{")) {
@@ -272,4 +342,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.B2G-HeFn.mjs

@@ -0,0 +1,123 @@
+import { isPlainObject, NullProtoObj, getOwn, setOwn } from '@orpc/shared';
+
+class BracketNotationSerializer {
+  maxExplicitDeserializingArrayIndex;
+  constructor(options = {}) {
+    this.maxExplicitDeserializingArrayIndex = options.maxExplicitDeserializingArrayIndex ?? 999;
+  }
+  serialize(data) {
+    const result = [];
+    this.internalSerialize(data, "", true, result);
+    return result;
+  }
+  internalSerialize(data, path, isRoot, result) {
+    if (Array.isArray(data)) {
+      data.forEach((item, i) => {
+        this.internalSerialize(item, isRoot ? i.toString() : `${path}[${i}]`, false, result);
+      });
+    } else if (isPlainObject(data)) {
+      for (const key of Object.keys(data)) {
+        this.internalSerialize(data[key], isRoot ? key : `${path}[${key}]`, false, result);
+      }
+    } else {
+      result.push([path, data]);
+    }
+  }
+  deserialize(serialized) {
+    const arrayPushStyles = /* @__PURE__ */ new WeakSet();
+    const root = new NullProtoObj();
+    for (const [path, value] of serialized) {
+      const segments = this.parsePath(path);
+      let currentRef = root;
+      let nextSegment = segments[0];
+      for (let i = 1; i < segments.length; i++) {
+        const segment = segments[i];
+        const isLast = i === segments.length - 1;
+        const existing = getOwn(currentRef, nextSegment);
+        let child = existing;
+        if (!Array.isArray(child) && !isPlainObject(child)) {
+          child = [];
+        }
+        if (Array.isArray(child)) {
+          const isPushStyle = arrayPushStyles.has(child);
+          const canStayArray = segment === "" ? isLast && (isPushStyle || child.length === 0) : internalIsValidArrayIndex(segment, this.maxExplicitDeserializingArrayIndex) && !(isLast && isPushStyle);
+          if (!canStayArray) {
+            arrayPushStyles.delete(child);
+            child = isPushStyle ? internalPushStyleArrayToObject(child) : internalArrayToObject(child);
+          }
+        }
+        if (child !== existing) {
+          setOwn(currentRef, nextSegment, child);
+        }
+        currentRef = child;
+        nextSegment = segment;
+      }
+      if (Array.isArray(currentRef) && nextSegment === "") {
+        arrayPushStyles.add(currentRef);
+        currentRef.push(value);
+      } else if (Object.hasOwn(currentRef, nextSegment)) {
+        const current = currentRef[nextSegment];
+        if (Array.isArray(current)) {
+          current.push(value);
+        } else {
+          setOwn(currentRef, nextSegment, [current, value]);
+        }
+      } else {
+        setOwn(currentRef, nextSegment, value);
+      }
+    }
+    return root;
+  }
+  stringifyPath(segments) {
+    if (segments.length === 0) {
+      return "";
+    }
+    let result = segments[0].toString();
+    for (let i = 1; i < segments.length; i++) {
+      result += `[${segments[i]}]`;
+    }
+    return result;
+  }
+  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;
+  }
+}
+const INTEGER_PATTERN = /^0$|^[1-9]\d*$/;
+function internalIsValidArrayIndex(value, maxIndex) {
+  return INTEGER_PATTERN.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 };