@orpc/openapi 1.14.6 → 2.0.0-beta.10

package/dist/shared/openapi.CTlpLuKN.mjs

@@ -0,0 +1,318 @@
+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 { g as getOpenAPIMeta } from './openapi.B9PQzqBn.mjs';
+import { createRouter, addRoute, findRoute, routeToRegExp } from 'rou3';
+
+class OpenAPIMatcher {
+  filter;
+  rootRouter;
+  tree = createRouter();
+  pendingLazyRouters = [];
+  constructor(router, options = {}) {
+    this.filter = options.filter ?? true;
+    this.rootRouter = router;
+    this.index(router);
+  }
+  index(router, path = []) {
+    const lazyResults = walkProcedureContractsSync(router, (contract, path2) => {
+      if (!value(this.filter, contract, path2)) {
+        return;
+      }
+      const meta = getOpenAPIMeta(contract);
+      const method = meta?.method ?? DEFAULT_OPENAPI_METHOD;
+      const postHttpPath = meta?.path ?? pathToHttpPath(path2);
+      const openapiPath = meta?.prefix ? mergeHttpPath(meta.prefix, postHttpPath) : postHttpPath;
+      const rou3Path = toRou3Pattern(openapiPath);
+      addRoute(this.tree, method, rou3Path, {
+        path: path2,
+        contract,
+        procedure: contract instanceof Procedure ? contract : void 0
+      });
+    }, path);
+    this.pendingLazyRouters.push(...lazyResults.map((result) => {
+      const prefix = getOpenAPIMeta(result.router)?.prefix;
+      return {
+        ...result,
+        matcher: prefix ? toRou3PrefixMatcher(prefix) : void 0
+      };
+    }));
+  }
+  async match(method, pathname, prefix) {
+    if (prefix) {
+      if (!pathname.startsWith(prefix)) {
+        return void 0;
+      }
+      const charAfterPrefix = pathname[prefix.length];
+      if (charAfterPrefix === "/") {
+        pathname = pathname.slice(prefix.length);
+      } else if (charAfterPrefix === void 0) {
+        pathname = "/";
+      } else if (prefix[prefix.length - 1] === "/") {
+        pathname = pathname.slice(prefix.length - 1);
+      } else {
+        return void 0;
+      }
+    }
+    const result = await this.matchPathname(method, pathname);
+    if (!result && pathname.includes("%")) {
+      return this.matchPathname(method, normalizeHttpPath(pathname));
+    }
+    return result;
+  }
+  async matchPathname(method, pathname) {
+    await this.resolvePendingLazyRouters(pathname);
+    const match = findRoute(this.tree, method, pathname);
+    if (!match) {
+      return void 0;
+    }
+    const procedure = await this.resolveProcedure(match.data);
+    return {
+      path: match.data.path,
+      procedure,
+      params: match.params ? decodeParams(match.params) : void 0
+    };
+  }
+  async resolvePendingLazyRouters(pathname) {
+    if (!this.pendingLazyRouters.length) {
+      return;
+    }
+    const stillPending = [];
+    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);
+      }
+    }
+    this.pendingLazyRouters = stillPending;
+  }
+  async resolveProcedure(entry) {
+    if (entry.procedure) {
+      return entry.procedure;
+    }
+    const { default: maybeProcedure } = await unlazy(getRouter(this.rootRouter, entry.path));
+    if (!(maybeProcedure instanceof Procedure)) {
+      throw new TypeError(
+        `[Contract-First] Missing or invalid implementation for procedure at path: "${entry.path.join(".")}". Ensure the procedure is correctly implemented and matches its contract.`
+      );
+    }
+    entry.procedure = createContractProcedure(maybeProcedure, entry.contract);
+    return entry.procedure;
+  }
+}
+function toRou3Pattern(path) {
+  const params = getDynamicPathParams(path);
+  if (!params?.length) {
+    return path;
+  }
+  for (let i = params.length - 1; i >= 0; i--) {
+    const param = params[i];
+    const pattern = param.allowsSlash ? `**:${param.parameterName}` : `:${param.parameterName}`;
+    path = path.slice(0, param.startIndex) + pattern + path.slice(param.startIndex + param.segment.length);
+  }
+  return path;
+}
+function toRou3PrefixMatcher(path) {
+  const pattern = toRou3Pattern(path);
+  return routeToRegExp(pattern === "/" ? "/**" : `${pattern}/**`);
+}
+function decodeParams(params) {
+  return Object.fromEntries(Object.entries(params).map(([key, val]) => [key, tryDecodeURIComponent(val)]));
+}
+
+class OpenAPIHandlerCodecCore {
+  serializer;
+  errorStatusMap;
+  customErrorResponseBodySerializer;
+  constructor(options = {}) {
+    this.serializer = options.serializer ?? new OpenAPISerializer();
+    this.errorStatusMap = options.errorStatusMap ?? COMMON_ERROR_STATUS_MAP;
+    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));
+      if (data === void 0) {
+        return params;
+      }
+      if (!params || Object.keys(params).length < 1) {
+        return data;
+      }
+      if (isPlainObject(data)) {
+        return {
+          ...params,
+          ...data
+        };
+      }
+      return data;
+    }
+    return {
+      params,
+      query,
+      headers: request.headers,
+      body: this.serializer.deserialize(await request.resolveBody(meta?.requestBodyHint))
+    };
+  }
+  /**
+   * @throws {TypeError} If `outputStructure` is "detailed" and the output doesn't match the expected structure.
+   */
+  encodeOutput(output, procedure, path) {
+    const meta = getOpenAPIMeta(procedure);
+    const successStatus = meta?.successStatus ?? DEFAULT_SUCCESS_STATUS;
+    const outputStructure = meta?.outputStructure ?? DEFAULT_OPENAPI_OUTPUT_STRUCTURE;
+    if (outputStructure === "compact") {
+      return {
+        status: successStatus,
+        headers: {},
+        body: this.serializer.serialize(output)
+      };
+    }
+    if (!isValidDetailedOutput(output)) {
+      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>)
+          - body (any)
+        \u2022 No extra keys allowed.
+
+        Actual value:
+          ${stringifyJSON(output)}
+      `);
+    }
+    return {
+      status: output.status ?? successStatus,
+      headers: output.headers ?? {},
+      body: this.serializer.serialize(output.body)
+    };
+  }
+  encodeError(error) {
+    const status = this.errorStatusMap[error.code] ?? DEFAULT_ERROR_STATUS;
+    return {
+      status,
+      headers: {},
+      body: this.serializer.serialize(this.customErrorResponseBodySerializer?.(error) ?? error.toJSON())
+    };
+  }
+  deserializeQuery(search, styles) {
+    const searchParams = new URLSearchParams(search);
+    const parsed = this.serializer.deserialize(searchParams);
+    if (!styles || !isPlainObject(parsed)) {
+      return parsed;
+    }
+    Object.entries(styles).forEach(([key, hint]) => {
+      if (hint === void 0) {
+        return;
+      }
+      const values = searchParams.getAll(key);
+      let parsedValue;
+      if (hint === "primitive") {
+        parsedValue = values.at(-1);
+      } else if (hint === "array") {
+        parsedValue = values;
+      } else if (hint === "comma-delimited-array") {
+        parsedValue = decodeDelimitedArray(values.at(-1), ",");
+      } else if (hint === "comma-delimited-object") {
+        parsedValue = decodeDelimitedObject(values.at(-1), ",");
+      } else if (hint === "space-delimited-array") {
+        parsedValue = decodeDelimitedArray(values.at(-1), " ");
+      } else if (hint === "space-delimited-object") {
+        parsedValue = decodeDelimitedObject(values.at(-1), " ");
+      } else if (hint === "pipe-delimited-array") {
+        parsedValue = decodeDelimitedArray(values.at(-1), "|");
+      } else if (hint === "pipe-delimited-object") {
+        parsedValue = decodeDelimitedObject(values.at(-1), "|");
+      } else {
+        const last = values.at(-1);
+        try {
+          parsedValue = parseEmptyableJSON(last);
+        } catch {
+          parsedValue = last;
+        }
+      }
+      parsed[key] = this.serializer.deserialize(parsedValue);
+    });
+    return parsed;
+  }
+  deserializeParams(params, styles) {
+    if (!params || !styles) {
+      return params;
+    }
+    const parsed = { ...params };
+    Object.entries(styles).forEach(([key, hint]) => {
+      if (hint === void 0 || hint === "primitive") {
+        return;
+      }
+      const value = params[key];
+      if (hint === "comma-delimited-array") {
+        parsed[key] = decodeDelimitedArray(value, ",");
+      } else {
+        parsed[key] = decodeDelimitedObject(value, ",");
+      }
+    });
+    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;
+  }
+  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)) {
+    return false;
+  }
+  if (output.headers !== void 0 && !isStandardHeaders(output.headers)) {
+    return false;
+  }
+  return true;
+}
+function decodeDelimitedArray(value, delimiter) {
+  if (value === void 0) {
+    return void 0;
+  }
+  return value.split(delimiter);
+}
+function decodeDelimitedObject(value, delimiter) {
+  if (value === void 0) {
+    return void 0;
+  }
+  const obj = new NullProtoObj();
+  const parts = value.split(delimiter);
+  for (let i = 0; i < parts.length; i += 2) {
+    const key = parts[i];
+    obj[key] = parts[i + 1];
+  }
+  return obj;
+}
+
+export { OpenAPIHandlerCodec as O, OpenAPIHandlerCodecCore as a, OpenAPIMatcher as b };

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

@@ -0,0 +1,82 @@
+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.mjs';
+
+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;
+}
+
+interface OpenAPIHandlerCodecCoreOptions<_T extends Context> {
+    /**
+     * 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 OpenAPIHandlerCodecCore<T extends Context> {
+    private readonly serializer;
+    private readonly errorStatusMap;
+    private readonly customErrorResponseBodySerializer;
+    constructor(options?: OpenAPIHandlerCodecCoreOptions<T>);
+    decodeInput(matched: {
+        procedure: AnyProcedure;
+        params?: undefined | Record<string, string>;
+    }, request: StandardLazyRequest): Promise<unknown>;
+    /**
+     * @throws {TypeError} If `outputStructure` is "detailed" and the output doesn't match the expected structure.
+     */
+    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, OpenAPIHandlerCodecCore as b, OpenAPIMatcher as d };
+export type { OpenAPIHandlerCodecOptions as O, OpenAPIHandlerCodecCoreOptions as c, OpenAPIMatcherOptions as e };

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 };