@orpc/openapi 0.0.0-next.d888fab → 0.0.0-next.d8deda3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (34) hide show
  1. package/README.md +11 -8
  2. package/dist/adapters/aws-lambda/index.d.mts +20 -0
  3. package/dist/adapters/aws-lambda/index.d.ts +20 -0
  4. package/dist/adapters/aws-lambda/index.mjs +18 -0
  5. package/dist/adapters/fastify/index.d.mts +23 -0
  6. package/dist/adapters/fastify/index.d.ts +23 -0
  7. package/dist/adapters/fastify/index.mjs +18 -0
  8. package/dist/adapters/fetch/index.d.mts +9 -3
  9. package/dist/adapters/fetch/index.d.ts +9 -3
  10. package/dist/adapters/fetch/index.mjs +2 -1
  11. package/dist/adapters/node/index.d.mts +9 -3
  12. package/dist/adapters/node/index.d.ts +9 -3
  13. package/dist/adapters/node/index.mjs +2 -1
  14. package/dist/adapters/standard/index.d.mts +8 -22
  15. package/dist/adapters/standard/index.d.ts +8 -22
  16. package/dist/adapters/standard/index.mjs +2 -1
  17. package/dist/index.d.mts +29 -12
  18. package/dist/index.d.ts +29 -12
  19. package/dist/index.mjs +3 -3
  20. package/dist/plugins/index.d.mts +25 -11
  21. package/dist/plugins/index.d.ts +25 -11
  22. package/dist/plugins/index.mjs +58 -18
  23. package/dist/shared/{openapi.p5tsmBXx.mjs → openapi.DIt-Z9W1.mjs} +45 -13
  24. package/dist/shared/openapi.DNv9yFfn.mjs +853 -0
  25. package/dist/shared/openapi.DwaweYRb.d.mts +54 -0
  26. package/dist/shared/openapi.DwaweYRb.d.ts +54 -0
  27. package/dist/shared/openapi.dbQeFCUJ.d.mts +120 -0
  28. package/dist/shared/openapi.dbQeFCUJ.d.ts +120 -0
  29. package/package.json +22 -11
  30. package/dist/shared/openapi.D3j94c9n.d.mts +0 -12
  31. package/dist/shared/openapi.D3j94c9n.d.ts +0 -12
  32. package/dist/shared/openapi.DP97kr00.d.mts +0 -47
  33. package/dist/shared/openapi.DP97kr00.d.ts +0 -47
  34. package/dist/shared/openapi.fMEQd3Yd.mjs +0 -544
package/dist/plugins/index.d.mts CHANGED
@@ -1,9 +1,8 @@
1
+ import { OpenAPI } from '@orpc/contract';
1
2
  import { Context, HTTPPath, Router } from '@orpc/server';
2
3
  import { StandardHandlerInterceptorOptions, StandardHandlerPlugin, StandardHandlerOptions } from '@orpc/server/standard';
3
- import { Value } from '@orpc/shared';
4
- import { OpenAPIV3_1 } from 'openapi-types';
5
- import { O as OpenAPIGeneratorOptions, a as OpenAPIGeneratorGenerateOptions } from '../shared/openapi.DP97kr00.mjs';
6
- import '@orpc/contract';
4
+ import { Value, Promisable } from '@orpc/shared';
5
+ import { O as OpenAPIGeneratorOptions, a as OpenAPIGeneratorGenerateOptions } from '../shared/openapi.dbQeFCUJ.mjs';
7
6
  import '@orpc/openapi-client/standard';
8
7
  import 'json-schema-typed/draft-2020-12';
9
8
 
@@ -12,7 +11,7 @@ interface OpenAPIReferencePluginOptions<T extends Context> extends OpenAPIGenera
12
11
  * Options to pass to the OpenAPI generate.
13
12
  *
14
13
  */
15
- specGenerateOptions?: Value<OpenAPIGeneratorGenerateOptions, [StandardHandlerInterceptorOptions<T>]>;
14
+ specGenerateOptions?: Value<Promisable<OpenAPIGeneratorGenerateOptions>, [StandardHandlerInterceptorOptions<T>]>;
16
15
  /**
17
16
  * The URL path at which to serve the OpenAPI JSON.
18
17
  *
@@ -30,27 +29,40 @@ interface OpenAPIReferencePluginOptions<T extends Context> extends OpenAPIGenera
30
29
  *
31
30
  * @default 'API Reference'
32
31
  */
33
- docsTitle?: Value<string, [StandardHandlerInterceptorOptions<T>]>;
32
+ docsTitle?: Value<Promisable<string>, [StandardHandlerInterceptorOptions<T>]>;
33
+ /**
34
+ * The UI library to use for rendering the API reference.
35
+ *
36
+ * @default 'scalar'
37
+ */
38
+ docsProvider?: 'scalar' | 'swagger';
34
39
  /**
35
40
  * Arbitrary configuration object for the UI.
36
41
  */
37
- docsConfig?: Value<Record<string, unknown>, [StandardHandlerInterceptorOptions<T>]>;
42
+ docsConfig?: Value<Promisable<Record<string, unknown>>, [StandardHandlerInterceptorOptions<T>]>;
38
43
  /**
39
44
  * HTML to inject into the <head> of the docs page.
40
45
  *
41
46
  * @default ''
42
47
  */
43
- docsHead?: Value<string, [StandardHandlerInterceptorOptions<T>]>;
48
+ docsHead?: Value<Promisable<string>, [StandardHandlerInterceptorOptions<T>]>;
44
49
  /**
45
50
  * URL of the external script bundle for the reference UI.
46
51
  *
47
- * @default 'https://cdn.jsdelivr.net/npm/@scalar/api-reference'
52
+ * - For Scalar: defaults to 'https://cdn.jsdelivr.net/npm/@scalar/api-reference'
53
+ * - For Swagger UI: defaults to 'https://unpkg.com/swagger-ui-dist@5.17.14/swagger-ui-bundle.js'
54
+ */
55
+ docsScriptUrl?: Value<Promisable<string>, [StandardHandlerInterceptorOptions<T>]>;
56
+ /**
57
+ * URL of the external CSS bundle for the reference UI (used by Swagger UI).
58
+ *
59
+ * @default 'https://unpkg.com/swagger-ui-dist@5.17.14/swagger-ui.css' (if swagger)
48
60
  */
49
- docsScriptUrl?: Value<string, [StandardHandlerInterceptorOptions<T>]>;
61
+ docsCssUrl?: Value<Promisable<string>, [StandardHandlerInterceptorOptions<T>]>;
50
62
  /**
51
63
  * Override function to generate the full HTML for the docs page.
52
64
  */
53
- renderDocsHtml?: (specUrl: string, title: string, head: string, scriptUrl: string, config: Record<string, unknown> | undefined, spec: OpenAPIV3_1.Document) => string;
65
+ renderDocsHtml?: (specUrl: string, title: string, head: string, scriptUrl: string, config: Record<string, unknown> | undefined, spec: OpenAPI.Document, docsProvider: 'scalar' | 'swagger', cssUrl: string | undefined) => string;
54
66
  }
55
67
  declare class OpenAPIReferencePlugin<T extends Context> implements StandardHandlerPlugin<T> {
56
68
  private readonly generator;
@@ -59,7 +71,9 @@ declare class OpenAPIReferencePlugin<T extends Context> implements StandardHandl
59
71
  private readonly docsPath;
60
72
  private readonly docsTitle;
61
73
  private readonly docsHead;
74
+ private readonly docsProvider;
62
75
  private readonly docsScriptUrl;
76
+ private readonly docsCssUrl;
63
77
  private readonly docsConfig;
64
78
  private readonly renderDocsHtml;
65
79
  constructor(options?: OpenAPIReferencePluginOptions<T>);
package/dist/plugins/index.d.ts CHANGED
@@ -1,9 +1,8 @@
1
+ import { OpenAPI } from '@orpc/contract';
1
2
  import { Context, HTTPPath, Router } from '@orpc/server';
2
3
  import { StandardHandlerInterceptorOptions, StandardHandlerPlugin, StandardHandlerOptions } from '@orpc/server/standard';
3
- import { Value } from '@orpc/shared';
4
- import { OpenAPIV3_1 } from 'openapi-types';
5
- import { O as OpenAPIGeneratorOptions, a as OpenAPIGeneratorGenerateOptions } from '../shared/openapi.DP97kr00.js';
6
- import '@orpc/contract';
4
+ import { Value, Promisable } from '@orpc/shared';
5
+ import { O as OpenAPIGeneratorOptions, a as OpenAPIGeneratorGenerateOptions } from '../shared/openapi.dbQeFCUJ.js';
7
6
  import '@orpc/openapi-client/standard';
8
7
  import 'json-schema-typed/draft-2020-12';
9
8
 
@@ -12,7 +11,7 @@ interface OpenAPIReferencePluginOptions<T extends Context> extends OpenAPIGenera
12
11
  * Options to pass to the OpenAPI generate.
13
12
  *
14
13
  */
15
- specGenerateOptions?: Value<OpenAPIGeneratorGenerateOptions, [StandardHandlerInterceptorOptions<T>]>;
14
+ specGenerateOptions?: Value<Promisable<OpenAPIGeneratorGenerateOptions>, [StandardHandlerInterceptorOptions<T>]>;
16
15
  /**
17
16
  * The URL path at which to serve the OpenAPI JSON.
18
17
  *
@@ -30,27 +29,40 @@ interface OpenAPIReferencePluginOptions<T extends Context> extends OpenAPIGenera
30
29
  *
31
30
  * @default 'API Reference'
32
31
  */
33
- docsTitle?: Value<string, [StandardHandlerInterceptorOptions<T>]>;
32
+ docsTitle?: Value<Promisable<string>, [StandardHandlerInterceptorOptions<T>]>;
33
+ /**
34
+ * The UI library to use for rendering the API reference.
35
+ *
36
+ * @default 'scalar'
37
+ */
38
+ docsProvider?: 'scalar' | 'swagger';
34
39
  /**
35
40
  * Arbitrary configuration object for the UI.
36
41
  */
37
- docsConfig?: Value<Record<string, unknown>, [StandardHandlerInterceptorOptions<T>]>;
42
+ docsConfig?: Value<Promisable<Record<string, unknown>>, [StandardHandlerInterceptorOptions<T>]>;
38
43
  /**
39
44
  * HTML to inject into the <head> of the docs page.
40
45
  *
41
46
  * @default ''
42
47
  */
43
- docsHead?: Value<string, [StandardHandlerInterceptorOptions<T>]>;
48
+ docsHead?: Value<Promisable<string>, [StandardHandlerInterceptorOptions<T>]>;
44
49
  /**
45
50
  * URL of the external script bundle for the reference UI.
46
51
  *
47
- * @default 'https://cdn.jsdelivr.net/npm/@scalar/api-reference'
52
+ * - For Scalar: defaults to 'https://cdn.jsdelivr.net/npm/@scalar/api-reference'
53
+ * - For Swagger UI: defaults to 'https://unpkg.com/swagger-ui-dist@5.17.14/swagger-ui-bundle.js'
54
+ */
55
+ docsScriptUrl?: Value<Promisable<string>, [StandardHandlerInterceptorOptions<T>]>;
56
+ /**
57
+ * URL of the external CSS bundle for the reference UI (used by Swagger UI).
58
+ *
59
+ * @default 'https://unpkg.com/swagger-ui-dist@5.17.14/swagger-ui.css' (if swagger)
48
60
  */
49
- docsScriptUrl?: Value<string, [StandardHandlerInterceptorOptions<T>]>;
61
+ docsCssUrl?: Value<Promisable<string>, [StandardHandlerInterceptorOptions<T>]>;
50
62
  /**
51
63
  * Override function to generate the full HTML for the docs page.
52
64
  */
53
- renderDocsHtml?: (specUrl: string, title: string, head: string, scriptUrl: string, config: Record<string, unknown> | undefined, spec: OpenAPIV3_1.Document) => string;
65
+ renderDocsHtml?: (specUrl: string, title: string, head: string, scriptUrl: string, config: Record<string, unknown> | undefined, spec: OpenAPI.Document, docsProvider: 'scalar' | 'swagger', cssUrl: string | undefined) => string;
54
66
  }
55
67
  declare class OpenAPIReferencePlugin<T extends Context> implements StandardHandlerPlugin<T> {
56
68
  private readonly generator;
@@ -59,7 +71,9 @@ declare class OpenAPIReferencePlugin<T extends Context> implements StandardHandl
59
71
  private readonly docsPath;
60
72
  private readonly docsTitle;
61
73
  private readonly docsHead;
74
+ private readonly docsProvider;
62
75
  private readonly docsScriptUrl;
76
+ private readonly docsCssUrl;
63
77
  private readonly docsConfig;
64
78
  private readonly renderDocsHtml;
65
79
  constructor(options?: OpenAPIReferencePluginOptions<T>);
package/dist/plugins/index.mjs CHANGED
@@ -1,5 +1,5 @@
1
1
  import { stringifyJSON, once, value } from '@orpc/shared';
2
- import { O as OpenAPIGenerator } from '../shared/openapi.fMEQd3Yd.mjs';
2
+ import { O as OpenAPIGenerator } from '../shared/openapi.DNv9yFfn.mjs';
3
3
  import '@orpc/client';
4
4
  import '@orpc/client/standard';
5
5
  import '@orpc/contract';
@@ -14,7 +14,9 @@ class OpenAPIReferencePlugin {
14
14
  docsPath;
15
15
  docsTitle;
16
16
  docsHead;
17
+ docsProvider;
17
18
  docsScriptUrl;
19
+ docsCssUrl;
18
20
  docsConfig;
19
21
  renderDocsHtml;
20
22
  constructor(options = {}) {
@@ -22,16 +24,59 @@ class OpenAPIReferencePlugin {
22
24
  this.docsPath = options.docsPath ?? "/";
23
25
  this.docsTitle = options.docsTitle ?? "API Reference";
24
26
  this.docsConfig = options.docsConfig ?? void 0;
25
- this.docsScriptUrl = options.docsScriptUrl ?? "https://cdn.jsdelivr.net/npm/@scalar/api-reference";
27
+ this.docsProvider = options.docsProvider ?? "scalar";
28
+ this.docsScriptUrl = options.docsScriptUrl ?? (this.docsProvider === "swagger" ? "https://unpkg.com/swagger-ui-dist/swagger-ui-bundle.js" : "https://cdn.jsdelivr.net/npm/@scalar/api-reference");
29
+ this.docsCssUrl = options.docsCssUrl ?? (this.docsProvider === "swagger" ? "https://unpkg.com/swagger-ui-dist/swagger-ui.css" : void 0);
26
30
  this.docsHead = options.docsHead ?? "";
27
31
  this.specPath = options.specPath ?? "/spec.json";
28
32
  this.generator = new OpenAPIGenerator(options);
29
33
  const esc = (s) => s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
30
- this.renderDocsHtml = options.renderDocsHtml ?? ((specUrl, title, head, scriptUrl, config, spec) => {
31
- const finalConfig = {
32
- content: stringifyJSON(spec),
33
- ...config
34
- };
34
+ this.renderDocsHtml = options.renderDocsHtml ?? ((specUrl, title, head, scriptUrl, config, spec, docsProvider, cssUrl) => {
35
+ let body;
36
+ if (docsProvider === "swagger") {
37
+ const swaggerConfig = {
38
+ dom_id: "#app",
39
+ spec,
40
+ deepLinking: true,
41
+ presets: [
42
+ "SwaggerUIBundle.presets.apis",
43
+ "SwaggerUIBundle.presets.standalone"
44
+ ],
45
+ plugins: [
46
+ "SwaggerUIBundle.plugins.DownloadUrl"
47
+ ],
48
+ ...config
49
+ };
50
+ body = `
51
+ <body>
52
+ <div id="app"></div>
53
+
54
+ <script src="${esc(scriptUrl)}"><\/script>
55
+
56
+ <script>
57
+ window.onload = () => {
58
+ window.ui = SwaggerUIBundle(${stringifyJSON(swaggerConfig).replace(/"(SwaggerUIBundle\.[^"]+)"/g, "$1")})
59
+ }
60
+ <\/script>
61
+ </body>
62
+ `;
63
+ } else {
64
+ const scalarConfig = {
65
+ content: stringifyJSON(spec),
66
+ ...config
67
+ };
68
+ body = `
69
+ <body>
70
+ <div id="app" data-config="${esc(stringifyJSON(scalarConfig))}"></div>
71
+
72
+ <script src="${esc(scriptUrl)}"><\/script>
73
+
74
+ <script>
75
+ Scalar.createApiReference('#app', JSON.parse(document.getElementById('app').dataset.config))
76
+ <\/script>
77
+ </body>
78
+ `;
79
+ }
35
80
  return `
36
81
  <!doctype html>
37
82
  <html>
@@ -39,19 +84,12 @@ class OpenAPIReferencePlugin {
39
84
  <meta charset="utf-8" />
40
85
  <meta name="viewport" content="width=device-width, initial-scale=1" />
41
86
  <title>${esc(title)}</title>
87
+ ${cssUrl ? `<link rel="stylesheet" type="text/css" href="${esc(cssUrl)}" />` : ""}
42
88
  ${head}
43
89
  </head>
44
- <body>
45
- <div id="app" data-config="${esc(stringifyJSON(finalConfig))}"></div>
46
-
47
- <script src="${esc(scriptUrl)}"><\/script>
48
-
49
- <script>
50
- Scalar.createApiReference('#app', JSON.parse(document.getElementById('app').dataset.config))
51
- <\/script>
52
- </body>
90
+ ${body}
53
91
  </html>
54
- `;
92
+ `;
55
93
  });
56
94
  }
57
95
  init(options, router) {
@@ -89,7 +127,9 @@ class OpenAPIReferencePlugin {
89
127
  await value(this.docsHead, options2),
90
128
  await value(this.docsScriptUrl, options2),
91
129
  await value(this.docsConfig, options2),
92
- await generateSpec()
130
+ await generateSpec(),
131
+ this.docsProvider,
132
+ await value(this.docsCssUrl, options2)
93
133
  );
94
134
  return {
95
135
  matched: true,
package/dist/shared/{openapi.p5tsmBXx.mjs → openapi.DIt-Z9W1.mjs} RENAMED
@@ -1,15 +1,18 @@
1
1
  import { standardizeHTTPPath, StandardOpenAPIJsonSerializer, StandardBracketNotationSerializer, StandardOpenAPISerializer } from '@orpc/openapi-client/standard';
2
2
  import { StandardHandler } from '@orpc/server/standard';
3
+ import { isORPCErrorStatus } from '@orpc/client';
3
4
  import { fallbackContractConfig } from '@orpc/contract';
4
- import { isObject } from '@orpc/shared';
5
+ import { isObject, stringifyJSON, tryDecodeURIComponent, value } from '@orpc/shared';
5
6
  import { toHttpPath } from '@orpc/client/standard';
6
7
  import { traverseContractProcedures, isProcedure, getLazyMeta, unlazy, getRouter, createContractedProcedure } from '@orpc/server';
7
8
  import { createRouter, addRoute, findRoute } from 'rou3';
8
9
 
9
10
  class StandardOpenAPICodec {
10
- constructor(serializer) {
11
+ constructor(serializer, options = {}) {
11
12
  this.serializer = serializer;
13
+ this.customErrorResponseBodyEncoder = options.customErrorResponseBodyEncoder;
12
14
  }
15
+ customErrorResponseBodyEncoder;
13
16
  async decode(request, params, procedure) {
14
17
  const inputStructure = fallbackContractConfig("defaultInputStructure", procedure["~orpc"].route.inputStructure);
15
18
  if (inputStructure === "compact") {
@@ -52,38 +55,67 @@ class StandardOpenAPICodec {
52
55
  body: this.serializer.serialize(output)
53
56
  };
54
57
  }
55
- if (!isObject(output)) {
56
- throw new Error(
57
- 'Invalid output structure for "detailed" output. Expected format: { body: any, headers?: Record<string, string | string[] | undefined> }'
58
- );
58
+ if (!this.#isDetailedOutput(output)) {
59
+ throw new Error(`
60
+ Invalid "detailed" output structure:
61
+ \u2022 Expected an object with optional properties:
62
+ - status (number 200-399)
63
+ - headers (Record<string, string | string[]>)
64
+ - body (any)
65
+ \u2022 No extra keys allowed.
66
+
67
+ Actual value:
68
+ ${stringifyJSON(output)}
69
+ `);
59
70
  }
60
71
  return {
61
- status: successStatus,
72
+ status: output.status ?? successStatus,
62
73
  headers: output.headers ?? {},
63
74
  body: this.serializer.serialize(output.body)
64
75
  };
65
76
  }
66
77
  encodeError(error) {
78
+ const body = this.customErrorResponseBodyEncoder?.(error) ?? error.toJSON();
67
79
  return {
68
80
  status: error.status,
69
81
  headers: {},
70
- body: this.serializer.serialize(error.toJSON(), { outputFormat: "plain" })
82
+ body: this.serializer.serialize(body, { outputFormat: "plain" })
71
83
  };
72
84
  }
85
+ #isDetailedOutput(output) {
86
+ if (!isObject(output)) {
87
+ return false;
88
+ }
89
+ if (output.headers && !isObject(output.headers)) {
90
+ return false;
91
+ }
92
+ if (output.status !== void 0 && (typeof output.status !== "number" || !Number.isInteger(output.status) || isORPCErrorStatus(output.status))) {
93
+ return false;
94
+ }
95
+ return true;
96
+ }
73
97
  }
74
98
 
75
99
  function toRou3Pattern(path) {
76
100
  return standardizeHTTPPath(path).replace(/\/\{\+([^}]+)\}/g, "/**:$1").replace(/\/\{([^}]+)\}/g, "/:$1");
77
101
  }
78
102
  function decodeParams(params) {
79
- return Object.fromEntries(Object.entries(params).map(([key, value]) => [key, decodeURIComponent(value)]));
103
+ return Object.fromEntries(Object.entries(params).map(([key, value]) => [key, tryDecodeURIComponent(value)]));
80
104
  }
81
105
 
82
106
  class StandardOpenAPIMatcher {
107
+ filter;
83
108
  tree = createRouter();
84
109
  pendingRouters = [];
110
+ constructor(options = {}) {
111
+ this.filter = options.filter ?? true;
112
+ }
85
113
  init(router, path = []) {
86
- const laziedOptions = traverseContractProcedures({ router, path }, ({ path: path2, contract }) => {
114
+ const laziedOptions = traverseContractProcedures({ router, path }, (traverseOptions) => {
115
+ if (!value(this.filter, traverseOptions)) {
116
+ return;
117
+ }
118
+ const { path: path2, contract } = traverseOptions;
87
119
  const method = fallbackContractConfig("defaultMethod", contract["~orpc"].route.method);
88
120
  const httpPath = toRou3Pattern(contract["~orpc"].route.path ?? toHttpPath(path2));
89
121
  if (isProcedure(contract)) {
@@ -147,10 +179,10 @@ class StandardOpenAPIMatcher {
147
179
  class StandardOpenAPIHandler extends StandardHandler {
148
180
  constructor(router, options) {
149
181
  const jsonSerializer = new StandardOpenAPIJsonSerializer(options);
150
- const bracketNotationSerializer = new StandardBracketNotationSerializer();
182
+ const bracketNotationSerializer = new StandardBracketNotationSerializer(options);
151
183
  const serializer = new StandardOpenAPISerializer(jsonSerializer, bracketNotationSerializer);
152
- const matcher = new StandardOpenAPIMatcher();
153
- const codec = new StandardOpenAPICodec(serializer);
184
+ const matcher = new StandardOpenAPIMatcher(options);
185
+ const codec = new StandardOpenAPICodec(serializer, options);
154
186
  super(router, matcher, codec, options);
155
187
  }
156
188
  }