@orpc/openapi 1.14.6 → 2.0.0-beta.10

package/dist/shared/openapi.7vgmPxca.d.ts

@@ -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.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;
+}
+
+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.B2SK0ZAr.mjs

@@ -0,0 +1,359 @@
+import { isORPCErrorJson, createORPCErrorFromJson, ORPCError } from '@orpc/client';
+import { getRouterContract, ProcedureContract } from '@orpc/contract';
+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 { g as getOpenAPIMeta } from './openapi.B9PQzqBn.mjs';
+
+class OpenAPILinkCodecError extends TypeError {
+}
+const END_SLASH_REGEX = /\/$/;
+class OpenAPILinkCodec {
+  constructor(router, options = {}) {
+    this.router = router;
+    this.baseUrl = options.url ?? "/";
+    this.headers = options.headers ?? {};
+    this.serializer = options.serializer ?? new OpenAPISerializer();
+    this.customErrorResponseBodyDecoder = options.customErrorResponseBodyDecoder;
+  }
+  baseUrl;
+  headers;
+  serializer;
+  customErrorResponseBodyDecoder;
+  async encodeInput(input, path, options) {
+    let headers = toResolvedStandardHeaders(await value(this.headers, options, path, input));
+    if (options.lastEventId !== void 0) {
+      headers = mergeStandardHeaders(headers, { "last-event-id": options.lastEventId });
+    }
+    const baseUrl = await value(this.baseUrl, options, path, input);
+    const procedure = await this.resolveProcedure(path);
+    const meta = getOpenAPIMeta(procedure);
+    const method = meta?.method ?? DEFAULT_OPENAPI_METHOD;
+    const inputStructure = meta?.inputStructure ?? DEFAULT_OPENAPI_INPUT_STRUCTURE;
+    let pathname = meta?.path ?? pathToHttpPath(path);
+    if (meta?.prefix) {
+      pathname = mergeHttpPath(meta.prefix, pathname);
+    }
+    const [basePathname, baseSearch, baseHash] = parseStandardUrl(baseUrl);
+    const dynamicParams = getDynamicPathParams(pathname);
+    if (inputStructure === "compact") {
+      let data = input;
+      if (dynamicParams?.length) {
+        if (!isTypescriptObject(input)) {
+          throw new OpenAPILinkCodecError(
+            `Input must be an object with "compact" input structure when the path has dynamic params (${dynamicParams.map((p) => p.parameterName).join(", ")}) in call to procedure (${path.join(".")}).`
+          );
+        }
+        const remaining = { ...input };
+        for (let i = dynamicParams.length - 1; i >= 0; i--) {
+          const param = dynamicParams[i];
+          const encoded = this.encodePathParam(input[param.parameterName], param, meta?.paramsStyles?.[param.parameterName], path);
+          pathname = `${pathname.slice(0, param.startIndex)}${encoded}${pathname.slice(param.startIndex + param.segment.length)}`;
+          delete remaining[param.parameterName];
+        }
+        data = Object.keys(remaining).length > 0 ? remaining : void 0;
+      }
+      pathname = `${basePathname.replace(END_SLASH_REGEX, "")}${pathname}`;
+      if (method === "GET") {
+        const queryString2 = this.serializeQueryString(data, meta?.queryStyles);
+        const search2 = combineSearch(baseSearch, queryString2);
+        const url3 = `${pathname}${search2 ?? ""}${baseHash ?? ""}`;
+        return {
+          body: void 0,
+          method,
+          headers,
+          url: url3,
+          signal: options.signal
+        };
+      }
+      const url2 = `${pathname}${baseSearch ?? ""}${baseHash ?? ""}`;
+      return {
+        url: url2,
+        method,
+        headers,
+        body: this.serializer.serialize(data),
+        signal: options.signal
+      };
+    }
+    if (!isValidDetailedInput(input)) {
+      throw new OpenAPILinkCodecError(`
+        Invalid "detailed" input structure in call to procedure (${path.join(".")}):
+        \u2022 Expected an object or undefined with optional properties:
+          - params (object, required when the path has dynamic params)
+          - query (object)
+          - headers (Record<string, string | string[] | undefined>)
+          - body (any)
+
+        Actual value:
+          ${stringifyJSON(input)}
+      `);
+    }
+    if (dynamicParams?.length) {
+      if (!input?.params) {
+        throw new OpenAPILinkCodecError(
+          `The "params" property is required for "detailed" input when the path has dynamic params (${dynamicParams.map((p) => p.parameterName).join(", ")}) in call to procedure (${path.join(".")}).`
+        );
+      }
+      for (let i = dynamicParams.length - 1; i >= 0; i--) {
+        const param = dynamicParams[i];
+        const val = input.params[param.parameterName];
+        const encoded = this.encodePathParam(val, param, meta?.paramsStyles?.[param.parameterName], path);
+        pathname = `${pathname.slice(0, param.startIndex)}${encoded}${pathname.slice(param.startIndex + param.segment.length)}`;
+      }
+    }
+    if (input?.headers) {
+      headers = mergeStandardHeaders(headers, input.headers);
+    }
+    pathname = `${basePathname.replace(END_SLASH_REGEX, "")}${pathname}`;
+    const queryString = this.serializeQueryString(input?.query, meta?.queryStyles);
+    const search = combineSearch(baseSearch, queryString);
+    const url = `${pathname}${search ?? ""}${baseHash ?? ""}`;
+    if (method === "GET") {
+      return {
+        body: void 0,
+        method,
+        headers,
+        url,
+        signal: options.signal
+      };
+    }
+    return {
+      url,
+      method,
+      headers,
+      body: this.serializer.serialize(input?.body),
+      signal: options.signal
+    };
+  }
+  encodePathParam(val, param, style, path) {
+    let encoded;
+    if (style === "comma-delimited-array" && Array.isArray(val)) {
+      encoded = val.map((val2) => this.serializer.serialize(val2)).filter((val2) => val2 !== void 0 && val2 !== null).map((val2) => encodeURIComponent(String(val2))).join(",");
+    } else if (style === "comma-delimited-object" && isTypescriptObject(val)) {
+      encoded = Object.entries(val).map(([key, val2]) => [key, this.serializer.serialize(val2)]).filter(([, val2]) => val2 !== void 0 && val2 !== null).map(([key, val2]) => `${encodeURIComponent(String(key))},${encodeURIComponent(String(val2))}`).join(",");
+    } else {
+      const serialized = this.serializer.serialize(val);
+      if (serialized !== void 0 && serialized !== null) {
+        if (param.allowsSlash) {
+          encoded = String(serialized).split("/").map(encodeURIComponent).join("/");
+        } else {
+          encoded = encodeURIComponent(String(serialized));
+        }
+      }
+    }
+    if (!encoded) {
+      throw new OpenAPILinkCodecError(`Path param "${param.parameterName}" cannot be empty in call to procedure (${path.join(".")}).`);
+    }
+    return encoded;
+  }
+  serializeQueryString(data, queryStyles) {
+    if (!queryStyles || !isTypescriptObject(data)) {
+      return toURLSearchParams(
+        this.serializer.serialize(data, { asFormData: true })
+      ).toString();
+    }
+    const remaining = { ...data };
+    let query = "";
+    Object.entries(queryStyles).forEach(([key, style]) => {
+      if (style === void 0) {
+        return;
+      }
+      const value2 = remaining[key];
+      delete remaining[key];
+      if (style === "primitive") {
+        const serialized = this.serializer.serialize(value2);
+        if (serialized !== void 0 && serialized !== null) {
+          query += `&${encodeURLSearchParamComponent(key)}=${encodeURLSearchParamComponent(String(serialized))}`;
+        }
+      } else if (style === "array" && Array.isArray(value2)) {
+        const encodedKey = encodeURLSearchParamComponent(key);
+        value2.forEach((v) => {
+          const s = this.serializer.serialize(v);
+          if (s !== void 0 && s !== null) {
+            query += `&${encodedKey}=${encodeURLSearchParamComponent(String(s))}`;
+          }
+        });
+      } else if (style === "json") {
+        const serialized = this.serializer.serialize(value2);
+        if (serialized !== void 0) {
+          query += `&${encodeURLSearchParamComponent(key)}=${encodeURLSearchParamComponent(stringifyJSON(serialized))}`;
+        }
+      } else if (style === "comma-delimited-array" && Array.isArray(value2)) {
+        const encodedValue = encodeDelimitedArray(
+          value2.map((v) => this.serializer.serialize(v)),
+          ","
+        );
+        if (encodedValue !== void 0) {
+          query += `&${encodeURLSearchParamComponent(key)}=${encodedValue}`;
+        }
+      } else if (style === "comma-delimited-object" && isTypescriptObject(value2)) {
+        const encodedValue = encodeDelimitedObject(
+          Object.entries(value2).map(([key2, value3]) => [key2, this.serializer.serialize(value3)]),
+          ","
+        );
+        if (encodedValue !== void 0) {
+          query += `&${encodeURLSearchParamComponent(key)}=${encodedValue}`;
+        }
+      } else if (style === "pipe-delimited-array" && Array.isArray(value2)) {
+        const encodedValue = encodeDelimitedArray(
+          value2.map((v) => this.serializer.serialize(v)),
+          "%7C"
+        );
+        if (encodedValue !== void 0) {
+          query += `&${encodeURLSearchParamComponent(key)}=${encodedValue}`;
+        }
+      } else if (style === "pipe-delimited-object" && isTypescriptObject(value2)) {
+        const encodedValue = encodeDelimitedObject(
+          Object.entries(value2).map(([key2, value3]) => [key2, this.serializer.serialize(value3)]),
+          "%7C"
+        );
+        if (encodedValue !== void 0) {
+          query += `&${encodeURLSearchParamComponent(key)}=${encodedValue}`;
+        }
+      } else if (style === "space-delimited-array" && Array.isArray(value2)) {
+        const encodedValue = encodeDelimitedArray(
+          value2.map((v) => this.serializer.serialize(v)),
+          "%20"
+        );
+        if (encodedValue !== void 0) {
+          query += `&${encodeURLSearchParamComponent(key)}=${encodedValue}`;
+        }
+      } else if (style === "space-delimited-object" && isTypescriptObject(value2)) {
+        const encodedValue = encodeDelimitedObject(
+          Object.entries(value2).map(([key2, value3]) => [key2, this.serializer.serialize(value3)]),
+          "%20"
+        );
+        if (encodedValue !== void 0) {
+          query += `&${encodeURLSearchParamComponent(key)}=${encodedValue}`;
+        }
+      } else {
+        const serialized = this.serializer.serialize(value2);
+        if (serialized !== void 0 && serialized !== null) {
+          query += `&${encodeURLSearchParamComponent(key)}=${encodeURLSearchParamComponent(String(serialized))}`;
+        }
+      }
+    });
+    const form = this.serializer.serialize(remaining, { asFormData: true });
+    query = `${toURLSearchParams(form).toString()}${query}`;
+    if (query.startsWith("&")) {
+      query = query.slice(1);
+    }
+    return query || void 0;
+  }
+  async decodeResponse(response, path, _options) {
+    const isOk = response.status >= 200 && response.status < 400;
+    const procedure = await this.resolveProcedure(path);
+    const meta = getOpenAPIMeta(procedure);
+    const deserialized = await (async () => {
+      let isBodyOk = false;
+      try {
+        const body = await response.resolveBody(meta?.responseBodyHint);
+        isBodyOk = true;
+        return this.serializer.deserialize(body);
+      } catch (error) {
+        if (!isBodyOk) {
+          throw new Error("Cannot parse response body, please check the response body and content-type.", {
+            cause: error
+          });
+        }
+        throw new Error("Invalid OpenAPI response format.", {
+          cause: error
+        });
+      }
+    })();
+    if (!isOk) {
+      const customError = this.customErrorResponseBodyDecoder?.(deserialized, response);
+      if (customError !== void 0 && customError !== null) {
+        return { kind: "error", error: customError };
+      }
+      if (isORPCErrorJson(deserialized)) {
+        return { kind: "error", error: createORPCErrorFromJson(deserialized) };
+      }
+      return {
+        kind: "error",
+        error: new ORPCError("MALFORMED_ORPC_ERROR_RESPONSE", {
+          data: { headers: response.headers, status: response.status, body: deserialized }
+        })
+      };
+    }
+    const outputStructure = meta?.outputStructure ?? DEFAULT_OPENAPI_OUTPUT_STRUCTURE;
+    return outputStructure === "compact" ? { kind: "output", output: deserialized } : {
+      kind: "output",
+      output: {
+        status: response.status,
+        headers: response.headers,
+        body: deserialized
+      }
+    };
+  }
+  async resolveProcedure(path) {
+    const { default: maybeProcedure } = await unlazy(getRouterContract(this.router, path));
+    if (!(maybeProcedure instanceof ProcedureContract)) {
+      throw new OpenAPILinkCodecError(`Expected a procedure or contract at path (${path.join(".")})`);
+    }
+    return maybeProcedure;
+  }
+}
+function combineSearch(baseSearch, additionalSearch) {
+  if (!baseSearch && !additionalSearch) {
+    return void 0;
+  }
+  if (!additionalSearch) {
+    return baseSearch;
+  }
+  if (!baseSearch) {
+    return `?${additionalSearch}`;
+  }
+  return `${baseSearch}&${additionalSearch}`;
+}
+function toResolvedStandardHeaders(headers) {
+  if (typeof headers.forEach === "function") {
+    return toStandardHeaders(headers);
+  }
+  return headers;
+}
+function isValidDetailedInput(input) {
+  if (!isTypescriptObject(input)) {
+    return input === void 0;
+  }
+  if (input.params !== void 0 && !isTypescriptObject(input.params)) {
+    return false;
+  }
+  if (input.query !== void 0 && !isTypescriptObject(input.query)) {
+    return false;
+  }
+  if (input.headers !== void 0 && !isStandardHeaders(input.headers)) {
+    return false;
+  }
+  return true;
+}
+function encodeURLSearchParamComponent(value2) {
+  return new URLSearchParams({ "": value2 }).toString().slice(1);
+}
+function toURLSearchParams(form) {
+  const params = new URLSearchParams();
+  for (const [key, value2] of form) {
+    params.append(key, String(value2));
+  }
+  return params;
+}
+function encodeDelimitedArray(serializedValues, encodedDelimiter) {
+  const strings = serializedValues.filter((v) => v !== null && v !== void 0).map(String);
+  if (!strings.length) {
+    return void 0;
+  }
+  return strings.map(encodeURLSearchParamComponent).join(encodedDelimiter);
+}
+function encodeDelimitedObject(entries, encodedDelimiter) {
+  const strings = entries.filter(([v]) => v !== null && v !== void 0).map(([k, v]) => [k, String(v)]);
+  if (!strings.length) {
+    return void 0;
+  }
+  return strings.map(
+    ([key, value2]) => `${encodeURLSearchParamComponent(key)}${encodedDelimiter}${encodeURLSearchParamComponent(value2)}`
+  ).join(encodedDelimiter);
+}
+
+export { OpenAPILinkCodec as O, OpenAPILinkCodecError as a };

package/dist/shared/openapi.B9PQzqBn.mjs

@@ -0,0 +1,49 @@
+import { mergeHttpPath } from '@orpc/shared';
+
+const openapi = (incoming) => ({
+  name: "~openapi",
+  init(meta) {
+    const existing = meta["~openapi"];
+    const tags = existing?.tags && incoming.tags ? [...existing.tags, ...incoming.tags] : "tags" in incoming ? incoming.tags : existing?.tags;
+    const queryStyles = existing?.queryStyles && incoming.queryStyles ? { ...existing.queryStyles, ...incoming.queryStyles } : "queryStyles" in incoming ? incoming.queryStyles : existing?.queryStyles;
+    const paramsStyles = existing?.paramsStyles && incoming.paramsStyles ? { ...existing.paramsStyles, ...incoming.paramsStyles } : "paramsStyles" in incoming ? incoming.paramsStyles : existing?.paramsStyles;
+    const existingSpec = existing?.spec;
+    const incomingSpec = incoming.spec;
+    const spec = typeof existingSpec === "function" && typeof incomingSpec === "function" ? (current) => incomingSpec(existingSpec(current)) : typeof existingSpec === "function" && typeof incomingSpec === "object" ? existingSpec(incomingSpec) : typeof existingSpec === "object" && typeof incomingSpec === "function" ? incomingSpec(existingSpec) : "spec" in incoming ? incomingSpec : existingSpec;
+    const prefix = existing?.prefix && incoming.prefix ? mergeHttpPath(existing.prefix, incoming.prefix) : "prefix" in incoming ? incoming.prefix : existing?.prefix;
+    const merged = {
+      ...existing,
+      ...incoming,
+      tags,
+      queryStyles,
+      paramsStyles,
+      spec,
+      prefix
+    };
+    return {
+      ...meta,
+      "~openapi": merged
+    };
+  }
+});
+openapi.method = (method) => ({
+  ...openapi({ method }),
+  name: "~openapi/method"
+});
+openapi.path = (path) => ({
+  ...openapi({ path }),
+  name: "~openapi/path"
+});
+openapi.spec = (spec) => ({
+  ...openapi({ spec }),
+  name: "~openapi/spec"
+});
+openapi.prefix = (prefix) => ({
+  ...openapi({ prefix }),
+  name: "~openapi/prefix"
+});
+function getOpenAPIMeta(procedureOrLazy) {
+  return procedureOrLazy["~orpc"].meta["~openapi"];
+}
+
+export { getOpenAPIMeta as g, openapi as o };