@celljs/openapi 0.0.0-stage → 4.4.0

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 (116) hide show
  1. package/README.md +85 -2
  2. package/cell.schema.json +41 -0
  3. package/cell.yml +12 -0
  4. package/esm/common/annotation.d.ts +60 -0
  5. package/esm/common/annotation.js +73 -0
  6. package/esm/common/annotation.js.map +1 -0
  7. package/esm/common/constants.d.ts +11 -0
  8. package/esm/common/constants.js +12 -0
  9. package/esm/common/constants.js.map +1 -0
  10. package/esm/common/index.d.ts +3 -0
  11. package/esm/common/index.js +4 -0
  12. package/esm/common/index.js.map +1 -0
  13. package/esm/common/openapi-protocol.d.ts +143 -0
  14. package/esm/common/openapi-protocol.js +2 -0
  15. package/esm/common/openapi-protocol.js.map +1 -0
  16. package/esm/node/index.d.ts +6 -0
  17. package/esm/node/index.js +7 -0
  18. package/esm/node/index.js.map +1 -0
  19. package/esm/node/module.d.ts +3 -0
  20. package/esm/node/module.js +4 -0
  21. package/esm/node/module.js.map +1 -0
  22. package/esm/node/openapi-document-provider.d.ts +39 -0
  23. package/esm/node/openapi-document-provider.js +310 -0
  24. package/esm/node/openapi-document-provider.js.map +1 -0
  25. package/esm/node/openapi-middleware.d.ts +17 -0
  26. package/esm/node/openapi-middleware.js +76 -0
  27. package/esm/node/openapi-middleware.js.map +1 -0
  28. package/esm/node/openapi-node-protocol.d.ts +7 -0
  29. package/esm/node/openapi-node-protocol.js +4 -0
  30. package/esm/node/openapi-node-protocol.js.map +1 -0
  31. package/esm/node/openapi-path-util.d.ts +10 -0
  32. package/esm/node/openapi-path-util.js +84 -0
  33. package/esm/node/openapi-path-util.js.map +1 -0
  34. package/esm/node/schema-builder.d.ts +39 -0
  35. package/esm/node/schema-builder.js +271 -0
  36. package/esm/node/schema-builder.js.map +1 -0
  37. package/esm/node/swagger-ui.d.ts +10 -0
  38. package/esm/node/swagger-ui.js +31 -0
  39. package/esm/node/swagger-ui.js.map +1 -0
  40. package/esm/package.json +3 -0
  41. package/lib/common/annotation.d.ts +61 -0
  42. package/lib/common/annotation.d.ts.map +1 -0
  43. package/lib/common/annotation.js +86 -0
  44. package/lib/common/annotation.js.map +1 -0
  45. package/lib/common/constants.d.ts +12 -0
  46. package/lib/common/constants.d.ts.map +1 -0
  47. package/lib/common/constants.js +15 -0
  48. package/lib/common/constants.js.map +1 -0
  49. package/lib/common/index.d.ts +4 -0
  50. package/lib/common/index.d.ts.map +1 -0
  51. package/lib/common/index.js +20 -0
  52. package/lib/common/index.js.map +1 -0
  53. package/lib/common/openapi-protocol.d.ts +144 -0
  54. package/lib/common/openapi-protocol.d.ts.map +1 -0
  55. package/lib/common/openapi-protocol.js +3 -0
  56. package/lib/common/openapi-protocol.js.map +1 -0
  57. package/lib/node/index.d.ts +7 -0
  58. package/lib/node/index.d.ts.map +1 -0
  59. package/lib/node/index.js +23 -0
  60. package/lib/node/index.js.map +1 -0
  61. package/lib/node/module.d.ts +4 -0
  62. package/lib/node/module.d.ts.map +1 -0
  63. package/lib/node/module.js +6 -0
  64. package/lib/node/module.js.map +1 -0
  65. package/lib/node/openapi-document-provider.d.ts +40 -0
  66. package/lib/node/openapi-document-provider.d.ts.map +1 -0
  67. package/lib/node/openapi-document-provider.js +313 -0
  68. package/lib/node/openapi-document-provider.js.map +1 -0
  69. package/lib/node/openapi-middleware.d.ts +18 -0
  70. package/lib/node/openapi-middleware.d.ts.map +1 -0
  71. package/lib/node/openapi-middleware.js +79 -0
  72. package/lib/node/openapi-middleware.js.map +1 -0
  73. package/lib/node/openapi-node-protocol.d.ts +8 -0
  74. package/lib/node/openapi-node-protocol.d.ts.map +1 -0
  75. package/lib/node/openapi-node-protocol.js +7 -0
  76. package/lib/node/openapi-node-protocol.js.map +1 -0
  77. package/lib/node/openapi-path-util.d.ts +11 -0
  78. package/lib/node/openapi-path-util.d.ts.map +1 -0
  79. package/lib/node/openapi-path-util.js +87 -0
  80. package/lib/node/openapi-path-util.js.map +1 -0
  81. package/lib/node/openapi.spec.d.ts +30 -0
  82. package/lib/node/openapi.spec.d.ts.map +1 -0
  83. package/lib/node/openapi.spec.js +268 -0
  84. package/lib/node/openapi.spec.js.map +1 -0
  85. package/lib/node/schema-builder.d.ts +40 -0
  86. package/lib/node/schema-builder.d.ts.map +1 -0
  87. package/lib/node/schema-builder.js +275 -0
  88. package/lib/node/schema-builder.js.map +1 -0
  89. package/lib/node/schema-builder.spec.d.ts +2 -0
  90. package/lib/node/schema-builder.spec.d.ts.map +1 -0
  91. package/lib/node/schema-builder.spec.js +143 -0
  92. package/lib/node/schema-builder.spec.js.map +1 -0
  93. package/lib/node/swagger-ui.d.ts +11 -0
  94. package/lib/node/swagger-ui.d.ts.map +1 -0
  95. package/lib/node/swagger-ui.js +34 -0
  96. package/lib/node/swagger-ui.js.map +1 -0
  97. package/lib/package.spec.d.ts +2 -0
  98. package/lib/package.spec.d.ts.map +1 -0
  99. package/lib/package.spec.js +7 -0
  100. package/lib/package.spec.js.map +1 -0
  101. package/package.json +78 -4
  102. package/src/common/annotation.ts +130 -0
  103. package/src/common/constants.ts +12 -0
  104. package/src/common/index.ts +3 -0
  105. package/src/common/openapi-protocol.ts +154 -0
  106. package/src/node/index.ts +6 -0
  107. package/src/node/module.ts +4 -0
  108. package/src/node/openapi-document-provider.ts +334 -0
  109. package/src/node/openapi-middleware.ts +59 -0
  110. package/src/node/openapi-node-protocol.ts +11 -0
  111. package/src/node/openapi-path-util.ts +75 -0
  112. package/src/node/openapi.spec.ts +219 -0
  113. package/src/node/schema-builder.spec.ts +124 -0
  114. package/src/node/schema-builder.ts +282 -0
  115. package/src/node/swagger-ui.ts +38 -0
  116. package/src/package.spec.ts +5 -0
@@ -0,0 +1,282 @@
1
+ import { type ApiPropertyMetadata, type ApiPropertyOptions, type Constructor, OPENAPI_METADATA_KEY, type SchemaObject, type TypeRef } from '../common';
2
+
3
+ const PRIMITIVES = new Map<unknown, SchemaObject>([
4
+ [String, { type: 'string' }],
5
+ [Number, { type: 'number' }],
6
+ [Boolean, { type: 'boolean' }],
7
+ [Date, { type: 'string', format: 'date-time' }],
8
+ [Object, { type: 'object' }],
9
+ [Array, { type: 'array', items: {} }],
10
+ ]);
11
+
12
+ /** Types that say nothing about the data: `Promise` of an async method, `any` / interfaces (`Object`) are handled by the caller. */
13
+ const OPAQUE = new Set<unknown>([Promise, Function, Symbol]);
14
+
15
+ /** class-validator constraints (by name) that describe a schema. */
16
+ const CONSTRAINTS: Record<string, (schema: SchemaObject, constraints: any[]) => void> = {
17
+ isString: s => setType(s, 'string'),
18
+ isInt: s => setType(s, 'integer'),
19
+ isNumber: s => setType(s, 'number'),
20
+ isBoolean: s => setType(s, 'boolean'),
21
+ isObject: s => setType(s, 'object'),
22
+ isDate: s => setType(s, 'string', 'date-time'),
23
+ isDateString: s => setType(s, 'string', 'date-time'),
24
+ isIso8601: s => setType(s, 'string', 'date-time'),
25
+ isEmail: s => setType(s, 'string', 'email'),
26
+ isUrl: s => setType(s, 'string', 'uri'),
27
+ isUuid: s => setType(s, 'string', 'uuid'),
28
+ isNumberString: s => setType(s, 'string'),
29
+ isBooleanString: s => setType(s, 'string'),
30
+ isArray: s => {
31
+ setType(s, 'array');
32
+ s.items = s.items || {};
33
+ },
34
+ isEnum: (s, c) => setEnum(s, EnumUtil.values(c[0])),
35
+ isIn: (s, c) => setEnum(s, [...c[0]]),
36
+ min: (s, c) => {
37
+ s.minimum = c[0];
38
+ },
39
+ max: (s, c) => {
40
+ s.maximum = c[0];
41
+ },
42
+ isPositive: s => {
43
+ s.minimum = 0;
44
+ s.exclusiveMinimum = true;
45
+ },
46
+ isNegative: s => {
47
+ s.maximum = 0;
48
+ s.exclusiveMaximum = true;
49
+ },
50
+ minLength: (s, c) => {
51
+ s.minLength = c[0];
52
+ },
53
+ maxLength: (s, c) => {
54
+ s.maxLength = c[0];
55
+ },
56
+ isLength: (s, c) => {
57
+ s.minLength = c[0];
58
+ if (c[1] !== undefined) {
59
+ s.maxLength = c[1];
60
+ }
61
+ },
62
+ matches: (s, c) => {
63
+ s.pattern = c[0] instanceof RegExp ? c[0].source : String(c[0]);
64
+ },
65
+ arrayMinSize: (s, c) => {
66
+ s.minItems = c[0];
67
+ },
68
+ arrayMaxSize: (s, c) => {
69
+ s.maxItems = c[0];
70
+ },
71
+ };
72
+
73
+ function setType(schema: SchemaObject, type: SchemaObject['type'], format?: string): void {
74
+ delete schema.$ref;
75
+ delete schema.allOf;
76
+ schema.type = type;
77
+ if (format) {
78
+ schema.format = format;
79
+ } else {
80
+ delete schema.format;
81
+ }
82
+ if (type !== 'array') {
83
+ delete schema.items;
84
+ }
85
+ }
86
+
87
+ /** The type of an enum follows its values: the TypeScript type of an enum property may be missing or `Object`. */
88
+ function setEnum(schema: SchemaObject, values: any[]): void {
89
+ schema.enum = values;
90
+ if (schema.$ref || schema.allOf || (schema.type && schema.type !== 'object') || !values.length) {
91
+ return;
92
+ }
93
+ if (values.every(v => typeof v === 'string')) {
94
+ setType(schema, 'string');
95
+ } else if (values.every(v => typeof v === 'number')) {
96
+ setType(schema, values.every(v => Number.isInteger(v)) ? 'integer' : 'number');
97
+ }
98
+ }
99
+
100
+ export namespace EnumUtil {
101
+ /** The values of a list or a TypeScript enum (without the reverse entries of numeric enums). */
102
+ export function values(enumOrValues: any[] | Record<string, any>): any[] {
103
+ if (Array.isArray(enumOrValues)) {
104
+ return [...enumOrValues];
105
+ }
106
+ return Object.keys(enumOrValues)
107
+ .filter(key => typeof enumOrValues[enumOrValues[key]] !== 'number')
108
+ .map(key => enumOrValues[key]);
109
+ }
110
+ }
111
+
112
+ /** The part of class-validator's metadata Cell reads; found on `globalThis`, so class-validator is not a dependency. */
113
+ interface ValidationMetadata {
114
+ type: string;
115
+ name?: string;
116
+ propertyName: string;
117
+ constraints?: any[];
118
+ each?: boolean;
119
+ }
120
+
121
+ export namespace ClassValidatorUtil {
122
+ export function metadatas(target: Constructor): ValidationMetadata[] {
123
+ const storage = (globalThis as any).classValidatorMetadataStorage;
124
+ if (!storage || typeof storage.getTargetValidationMetadatas !== 'function') {
125
+ return [];
126
+ }
127
+ try {
128
+ return storage.getTargetValidationMetadatas(target, '', true, false) || [];
129
+ } catch {
130
+ return [];
131
+ }
132
+ }
133
+ }
134
+
135
+ /**
136
+ * Turns types into schemas; classes become `components.schemas` entries referred to by `$ref`.
137
+ * One instance builds one document.
138
+ */
139
+ export class SchemaBuilder {
140
+ readonly schemas: Record<string, SchemaObject> = {};
141
+
142
+ protected readonly names = new Map<Constructor, string>();
143
+
144
+ /** The schema of a type, or undefined when the type says nothing (`Promise`, `void`). */
145
+ resolve(type: TypeRef | undefined): SchemaObject | undefined {
146
+ if (type === undefined || type === null) {
147
+ return undefined;
148
+ }
149
+ if (Array.isArray(type)) {
150
+ return { type: 'array', items: this.resolve(type[0] as TypeRef) || {} };
151
+ }
152
+ if (typeof type === 'string') {
153
+ return { type };
154
+ }
155
+ const primitive = PRIMITIVES.get(type);
156
+ if (primitive) {
157
+ return structuredClone(primitive);
158
+ }
159
+ if (OPAQUE.has(type) || typeof type !== 'function') {
160
+ return undefined;
161
+ }
162
+ return { $ref: `#/components/schemas/${this.define(type)}` };
163
+ }
164
+
165
+ /** The schema of a class, inline: its properties from @ApiProperty and class-validator decorators. */
166
+ build(target: Constructor): SchemaObject {
167
+ const properties: Record<string, SchemaObject> = {};
168
+ const optional = new Set<string>();
169
+ const required = new Set<string>();
170
+ for (const metadata of ClassValidatorUtil.metadatas(target)) {
171
+ const key = metadata.propertyName;
172
+ properties[key] = properties[key] || this.designType(target, key);
173
+ const schema = properties[key];
174
+ if (metadata.type === 'conditionalValidation') {
175
+ optional.add(key);
176
+ continue;
177
+ }
178
+ const apply = metadata.name && CONSTRAINTS[metadata.name];
179
+ if (!apply) {
180
+ continue;
181
+ }
182
+ if (metadata.each) {
183
+ setType(schema, 'array');
184
+ schema.items = schema.items || {};
185
+ apply(schema.items, metadata.constraints || []);
186
+ } else {
187
+ apply(schema, metadata.constraints || []);
188
+ }
189
+ }
190
+ for (const { key, options } of this.apiProperties(target)) {
191
+ properties[key] = this.fromOptions(options, properties[key] || this.designType(target, key));
192
+ if (options.required === false) {
193
+ optional.add(key);
194
+ } else if (options.required === true) {
195
+ required.add(key);
196
+ }
197
+ }
198
+ const schema: SchemaObject = { type: 'object', properties: {} };
199
+ const requiredList: string[] = [];
200
+ for (const [key, property] of Object.entries(properties)) {
201
+ (schema.properties as Record<string, SchemaObject>)[key] = SchemaUtil.normalize(property);
202
+ if (required.has(key) || !optional.has(key)) {
203
+ requiredList.push(key);
204
+ }
205
+ }
206
+ if (requiredList.length) {
207
+ schema.required = requiredList;
208
+ }
209
+ return schema;
210
+ }
211
+
212
+ /** Applies @ApiProperty-like options to the schema found from the TypeScript type. */
213
+ fromOptions(options: ApiPropertyOptions, found: SchemaObject = {}): SchemaObject {
214
+ const { type, required, enum: values, items, ...rest } = options;
215
+ let schema: SchemaObject = { ...found };
216
+ if (type !== undefined) {
217
+ const resolved = this.resolve(type) || {};
218
+ if (resolved.$ref || resolved.type !== found.type) {
219
+ schema = {};
220
+ for (const key of ['description', 'example', 'enum', 'nullable']) {
221
+ if (found[key] !== undefined) {
222
+ schema[key] = found[key];
223
+ }
224
+ }
225
+ }
226
+ Object.assign(schema, resolved);
227
+ }
228
+ if (values !== undefined) {
229
+ setEnum(schema, EnumUtil.values(values));
230
+ }
231
+ if (items !== undefined) {
232
+ schema.items = items;
233
+ }
234
+ return Object.assign(schema, rest);
235
+ }
236
+
237
+ protected designType(target: Constructor, key: string): SchemaObject {
238
+ return this.resolve(Reflect.getMetadata('design:type', target.prototype, key)) || {};
239
+ }
240
+
241
+ /** @ApiProperty metadata of the class and its parents, parents first; a subclass entry replaces the parent's. */
242
+ protected apiProperties(target: Constructor): ApiPropertyMetadata[] {
243
+ const chain: Constructor[] = [];
244
+ for (let current = target; current && current !== Function.prototype; current = Object.getPrototypeOf(current)) {
245
+ chain.unshift(current);
246
+ }
247
+ const merged = new Map<string, ApiPropertyMetadata>();
248
+ for (const current of chain) {
249
+ for (const metadata of (Reflect.getOwnMetadata(OPENAPI_METADATA_KEY.properties, current) || []) as ApiPropertyMetadata[]) {
250
+ merged.set(metadata.key, metadata);
251
+ }
252
+ }
253
+ return [...merged.values()];
254
+ }
255
+
256
+ protected define(target: Constructor): string {
257
+ const existing = this.names.get(target);
258
+ if (existing) {
259
+ return existing;
260
+ }
261
+ const base = target.name || 'Anonymous';
262
+ let name = base;
263
+ for (let i = 2; this.schemas[name]; i++) {
264
+ name = `${base}${i}`;
265
+ }
266
+ this.names.set(target, name);
267
+ this.schemas[name] = {};
268
+ this.schemas[name] = this.build(target);
269
+ return name;
270
+ }
271
+ }
272
+
273
+ export namespace SchemaUtil {
274
+ /** OpenAPI 3.0 ignores the siblings of `$ref`: keep them by wrapping the reference in `allOf`. */
275
+ export function normalize(schema: SchemaObject): SchemaObject {
276
+ if (schema.$ref && Object.keys(schema).length > 1) {
277
+ const { $ref, ...rest } = schema;
278
+ return { allOf: [{ $ref }], ...rest };
279
+ }
280
+ return schema;
281
+ }
282
+ }
@@ -0,0 +1,38 @@
1
+ export interface SwaggerUiPageOptions {
2
+ title: string;
3
+ /** URL of the OpenAPI document. */
4
+ url: string;
5
+ /** Base URL of swagger-ui-dist. */
6
+ cdn: string;
7
+ }
8
+
9
+ export namespace SwaggerUiUtil {
10
+ export function render({ title, url, cdn }: SwaggerUiPageOptions): string {
11
+ const base = cdn.replace(/\/+$/, '');
12
+ return `<!doctype html>
13
+ <html lang="en">
14
+ <head>
15
+ <meta charset="utf-8">
16
+ <meta name="viewport" content="width=device-width, initial-scale=1">
17
+ <title>${escapeHtml(title)}</title>
18
+ <link rel="stylesheet" href="${escapeHtml(base)}/swagger-ui.css">
19
+ </head>
20
+ <body>
21
+ <div id="swagger-ui"></div>
22
+ <script src="${escapeHtml(base)}/swagger-ui-bundle.js" crossorigin></script>
23
+ <script>
24
+ window.ui = SwaggerUIBundle({ url: ${scriptValue(url)}, dom_id: '#swagger-ui', deepLinking: true });
25
+ </script>
26
+ </body>
27
+ </html>
28
+ `;
29
+ }
30
+
31
+ function escapeHtml(text: string): string {
32
+ return text.replace(/[&<>"']/g, c => `&#${c.charCodeAt(0)};`);
33
+ }
34
+
35
+ function scriptValue(value: string): string {
36
+ return JSON.stringify(value).replace(/</g, '\\u003c');
37
+ }
38
+ }
@@ -0,0 +1,5 @@
1
+ import { describe, it } from 'bun:test';
2
+
3
+ describe('openapi package', () => {
4
+ it('support code coverage statistics', () => {});
5
+ });