@skmtc/core 0.0.783 → 0.0.786
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.
- package/esm/dsl/File.d.ts +208 -0
- package/esm/dsl/File.d.ts.map +1 -1
- package/esm/dsl/File.js +197 -0
- package/esm/dsl/Identifier.d.ts +152 -0
- package/esm/dsl/Identifier.d.ts.map +1 -1
- package/esm/dsl/Identifier.js +152 -0
- package/esm/dsl/Import.d.ts +221 -0
- package/esm/dsl/Import.d.ts.map +1 -1
- package/esm/dsl/Import.js +202 -0
- package/esm/dsl/model/ModelBase.d.ts +257 -0
- package/esm/dsl/model/ModelBase.d.ts.map +1 -1
- package/esm/dsl/model/ModelBase.js +248 -0
- package/esm/dsl/operation/OperationBase.d.ts +356 -1
- package/esm/dsl/operation/OperationBase.d.ts.map +1 -1
- package/esm/dsl/operation/OperationBase.js +347 -1
- package/esm/oas/document/Document.d.ts +155 -1
- package/esm/oas/document/Document.d.ts.map +1 -1
- package/esm/oas/document/Document.js +141 -2
- package/esm/oas/object/Object.d.ts +255 -10
- package/esm/oas/object/Object.d.ts.map +1 -1
- package/esm/oas/object/Object.js +229 -10
- package/esm/types/GeneratorKeys.d.ts +336 -0
- package/esm/types/GeneratorKeys.d.ts.map +1 -1
- package/esm/types/GeneratorKeys.js +243 -0
- package/esm/types/GeneratorType.d.ts +119 -0
- package/esm/types/GeneratorType.d.ts.map +1 -1
- package/esm/types/Method.d.ts +109 -0
- package/esm/types/Method.d.ts.map +1 -1
- package/esm/types/Method.js +84 -0
- package/package.json +5 -1
- package/script/dsl/File.d.ts +208 -0
- package/script/dsl/File.d.ts.map +1 -1
- package/script/dsl/File.js +197 -0
- package/script/dsl/Identifier.d.ts +152 -0
- package/script/dsl/Identifier.d.ts.map +1 -1
- package/script/dsl/Identifier.js +152 -0
- package/script/dsl/Import.d.ts +221 -0
- package/script/dsl/Import.d.ts.map +1 -1
- package/script/dsl/Import.js +202 -0
- package/script/dsl/model/ModelBase.d.ts +257 -0
- package/script/dsl/model/ModelBase.d.ts.map +1 -1
- package/script/dsl/model/ModelBase.js +248 -0
- package/script/dsl/operation/OperationBase.d.ts +356 -1
- package/script/dsl/operation/OperationBase.d.ts.map +1 -1
- package/script/dsl/operation/OperationBase.js +347 -1
- package/script/oas/document/Document.d.ts +155 -1
- package/script/oas/document/Document.d.ts.map +1 -1
- package/script/oas/document/Document.js +141 -2
- package/script/oas/object/Object.d.ts +255 -10
- package/script/oas/object/Object.d.ts.map +1 -1
- package/script/oas/object/Object.js +229 -10
- package/script/types/GeneratorKeys.d.ts +336 -0
- package/script/types/GeneratorKeys.d.ts.map +1 -1
- package/script/types/GeneratorKeys.js +243 -0
- package/script/types/GeneratorType.d.ts +119 -0
- package/script/types/GeneratorType.d.ts.map +1 -1
- package/script/types/Method.d.ts +109 -0
- package/script/types/Method.d.ts.map +1 -1
- package/script/types/Method.js +84 -0
|
@@ -1,19 +1,148 @@
|
|
|
1
1
|
import { ContentBase } from '../ContentBase.js';
|
|
2
|
+
/**
|
|
3
|
+
* Base class for operation generators in the SKMTC DSL system.
|
|
4
|
+
*
|
|
5
|
+
* `OperationBase` extends {@link ContentBase} to provide specialized functionality for
|
|
6
|
+
* generating code from OpenAPI operations. It offers type-safe methods for inserting
|
|
7
|
+
* related operations and models, managing complex operation dependencies, and handling
|
|
8
|
+
* enrichments specific to API operations.
|
|
9
|
+
*
|
|
10
|
+
* This class serves as the foundation for creating custom operation generators that
|
|
11
|
+
* transform OpenAPI operations into various code artifacts like API clients, server
|
|
12
|
+
* handlers, validation middleware, or documentation.
|
|
13
|
+
*
|
|
14
|
+
* ## Key Features
|
|
15
|
+
*
|
|
16
|
+
* - **Operation Insertion**: Insert related operations with automatic dependency tracking
|
|
17
|
+
* - **Model Integration**: Seamlessly insert related models from operation schemas
|
|
18
|
+
* - **Schema Normalization**: Handle complex request/response schema references
|
|
19
|
+
* - **Export Management**: Control which operations are exported from generated files
|
|
20
|
+
* - **Enrichment Support**: Extend functionality with operation-specific enrichment data
|
|
21
|
+
* - **Type Safety**: Full TypeScript support with generic enrichment types
|
|
22
|
+
*
|
|
23
|
+
* @template EnrichmentType - Optional type for custom enrichment data
|
|
24
|
+
*
|
|
25
|
+
* @example Basic API client generator
|
|
26
|
+
* ```typescript
|
|
27
|
+
* import { OperationBase, Definition } from '@skmtc/core';
|
|
28
|
+
*
|
|
29
|
+
* class ApiClientMethod extends OperationBase {
|
|
30
|
+
* toDefinition(): Definition {
|
|
31
|
+
* const { method, path, operationId } = this.operation;
|
|
32
|
+
*
|
|
33
|
+
* return new Definition({
|
|
34
|
+
* name: operationId || `${method}${this.pascalCasePath()}`,
|
|
35
|
+
* content: `async ${operationId}(${this.generateParameters()}) {
|
|
36
|
+
* return this.request('${method}', '${path}', ${this.generateRequestBody()});
|
|
37
|
+
* }`
|
|
38
|
+
* });
|
|
39
|
+
* }
|
|
40
|
+
* }
|
|
41
|
+
* ```
|
|
42
|
+
*
|
|
43
|
+
* @example With request/response models
|
|
44
|
+
* ```typescript
|
|
45
|
+
* class TypedApiMethod extends OperationBase {
|
|
46
|
+
* toDefinition(): Definition {
|
|
47
|
+
* const operation = this.operation;
|
|
48
|
+
*
|
|
49
|
+
* // Generate request model if needed
|
|
50
|
+
* let requestType = 'void';
|
|
51
|
+
* if (operation.requestBody?.content?.['application/json']?.schema) {
|
|
52
|
+
* const requestModel = this.insertNormalizedModel(
|
|
53
|
+
* new RequestModel({ ... }),
|
|
54
|
+
* {
|
|
55
|
+
* schema: operation.requestBody.content['application/json'].schema,
|
|
56
|
+
* fallbackName: `${operation.operationId}Request`
|
|
57
|
+
* }
|
|
58
|
+
* );
|
|
59
|
+
* requestType = requestModel.value;
|
|
60
|
+
* }
|
|
61
|
+
*
|
|
62
|
+
* // Generate response model
|
|
63
|
+
* const responseSchema = operation.responses?.['200']?.content?.['application/json']?.schema;
|
|
64
|
+
* const responseModel = this.insertNormalizedModel(
|
|
65
|
+
* new ResponseModel({ ... }),
|
|
66
|
+
* { schema: responseSchema, fallbackName: `${operation.operationId}Response` }
|
|
67
|
+
* );
|
|
68
|
+
*
|
|
69
|
+
* return new Definition({
|
|
70
|
+
* name: operation.operationId,
|
|
71
|
+
* content: `async ${operation.operationId}(data: ${requestType}): Promise<${responseModel.value}> {
|
|
72
|
+
* return this.request('${operation.method}', '${operation.path}', data);
|
|
73
|
+
* }`
|
|
74
|
+
* });
|
|
75
|
+
* }
|
|
76
|
+
* }
|
|
77
|
+
* ```
|
|
78
|
+
*
|
|
79
|
+
* @example With enrichments
|
|
80
|
+
* ```typescript
|
|
81
|
+
* type AuthEnrichment = {
|
|
82
|
+
* requiresAuth: boolean;
|
|
83
|
+
* permissions: string[];
|
|
84
|
+
* };
|
|
85
|
+
*
|
|
86
|
+
* class SecuredApiMethod extends OperationBase<AuthEnrichment> {
|
|
87
|
+
* toDefinition(): Definition {
|
|
88
|
+
* const enrichment = this.settings.enrichment;
|
|
89
|
+
* const requiresAuth = enrichment?.requiresAuth ?? false;
|
|
90
|
+
*
|
|
91
|
+
* const authCheck = requiresAuth
|
|
92
|
+
* ? 'this.checkAuth();'
|
|
93
|
+
* : '';
|
|
94
|
+
*
|
|
95
|
+
* return new Definition({
|
|
96
|
+
* name: this.operation.operationId,
|
|
97
|
+
* content: `async ${this.operation.operationId}() {
|
|
98
|
+
* ${authCheck}
|
|
99
|
+
* return this.request('${this.operation.method}', '${this.operation.path}');
|
|
100
|
+
* }`
|
|
101
|
+
* });
|
|
102
|
+
* }
|
|
103
|
+
* }
|
|
104
|
+
* ```
|
|
105
|
+
*/
|
|
2
106
|
export class OperationBase extends ContentBase {
|
|
107
|
+
/**
|
|
108
|
+
* Creates a new OperationBase instance.
|
|
109
|
+
*
|
|
110
|
+
* @param args - Operation generator configuration
|
|
111
|
+
* @param args.context - The generation context providing pipeline access
|
|
112
|
+
* @param args.settings - Content settings with export path and enrichments
|
|
113
|
+
* @param args.generatorKey - Unique identifier for this generator type
|
|
114
|
+
* @param args.operation - The OpenAPI operation being processed
|
|
115
|
+
*
|
|
116
|
+
* @example
|
|
117
|
+
* ```typescript
|
|
118
|
+
* const operation = new OperationBase({
|
|
119
|
+
* context: generateContext,
|
|
120
|
+
* settings: {
|
|
121
|
+
* exportPath: './src/api.ts',
|
|
122
|
+
* enrichment: customEnrichments
|
|
123
|
+
* },
|
|
124
|
+
* generatorKey: 'api-client',
|
|
125
|
+
* operation: oasOperation
|
|
126
|
+
* });
|
|
127
|
+
* ```
|
|
128
|
+
*/
|
|
3
129
|
constructor({ context, generatorKey, settings, operation }) {
|
|
4
130
|
super({ context });
|
|
131
|
+
/** Content settings including export path and enrichment configuration */
|
|
5
132
|
Object.defineProperty(this, "settings", {
|
|
6
133
|
enumerable: true,
|
|
7
134
|
configurable: true,
|
|
8
135
|
writable: true,
|
|
9
136
|
value: void 0
|
|
10
137
|
});
|
|
138
|
+
/** The OpenAPI operation being processed */
|
|
11
139
|
Object.defineProperty(this, "operation", {
|
|
12
140
|
enumerable: true,
|
|
13
141
|
configurable: true,
|
|
14
142
|
writable: true,
|
|
15
143
|
value: void 0
|
|
16
144
|
});
|
|
145
|
+
/** Generator key identifying this generator type */
|
|
17
146
|
Object.defineProperty(this, "generatorKey", {
|
|
18
147
|
enumerable: true,
|
|
19
148
|
configurable: true,
|
|
@@ -24,6 +153,43 @@ export class OperationBase extends ContentBase {
|
|
|
24
153
|
this.operation = operation;
|
|
25
154
|
this.settings = settings;
|
|
26
155
|
}
|
|
156
|
+
/**
|
|
157
|
+
* Inserts a related operation with forced generation.
|
|
158
|
+
*
|
|
159
|
+
* This method adds a related operation to the current generation context, ensuring
|
|
160
|
+
* it will be generated regardless of whether it already exists. This is useful for
|
|
161
|
+
* operations that depend on other operations or need to generate helper operations.
|
|
162
|
+
*
|
|
163
|
+
* @template V - Type of generated value returned by the insertable
|
|
164
|
+
* @template EnrichmentType - Type of enrichment data for the insertable
|
|
165
|
+
* @param insertable - The operation generator to insert
|
|
166
|
+
* @param operation - The OpenAPI operation to process
|
|
167
|
+
* @param options - Insertion options
|
|
168
|
+
* @param options.noExport - Whether to skip exporting the inserted operation
|
|
169
|
+
* @returns Inserted operation reference with generated value
|
|
170
|
+
*
|
|
171
|
+
* @example Inserting helper operations
|
|
172
|
+
* ```typescript
|
|
173
|
+
* class CrudApiClient extends OperationBase {
|
|
174
|
+
* toDefinition(): Definition {
|
|
175
|
+
* // Insert a related validation operation
|
|
176
|
+
* const validator = this.insertOperation(
|
|
177
|
+
* new ValidationOperation({ ... }),
|
|
178
|
+
* this.operation,
|
|
179
|
+
* { noExport: true }
|
|
180
|
+
* );
|
|
181
|
+
*
|
|
182
|
+
* return new Definition({
|
|
183
|
+
* name: this.operation.operationId,
|
|
184
|
+
* content: `async ${this.operation.operationId}(data: any) {
|
|
185
|
+
* ${validator.value}(data);
|
|
186
|
+
* return this.request('${this.operation.method}', '${this.operation.path}', data);
|
|
187
|
+
* }`
|
|
188
|
+
* });
|
|
189
|
+
* }
|
|
190
|
+
* }
|
|
191
|
+
* ```
|
|
192
|
+
*/
|
|
27
193
|
insertOperation(insertable, operation, options = {}) {
|
|
28
194
|
return this.context.insertOperation(insertable, operation, {
|
|
29
195
|
generation: 'force',
|
|
@@ -31,6 +197,47 @@ export class OperationBase extends ContentBase {
|
|
|
31
197
|
noExport: options.noExport
|
|
32
198
|
});
|
|
33
199
|
}
|
|
200
|
+
/**
|
|
201
|
+
* Inserts a related model with forced generation.
|
|
202
|
+
*
|
|
203
|
+
* This method adds a model to the current generation context, typically used
|
|
204
|
+
* for request/response models or other types related to the operation. The model
|
|
205
|
+
* will be generated and can be referenced in the operation code.
|
|
206
|
+
*
|
|
207
|
+
* @template V - Type of generated value returned by the insertable
|
|
208
|
+
* @template EnrichmentType - Type of enrichment data for the insertable
|
|
209
|
+
* @param insertable - The model generator to insert
|
|
210
|
+
* @param refName - Reference name for the inserted model
|
|
211
|
+
* @param options - Insertion options
|
|
212
|
+
* @param options.noExport - Whether to skip exporting the inserted model
|
|
213
|
+
* @returns Inserted model reference with generated value
|
|
214
|
+
*
|
|
215
|
+
* @example Inserting request/response models
|
|
216
|
+
* ```typescript
|
|
217
|
+
* class ApiOperation extends OperationBase {
|
|
218
|
+
* toDefinition(): Definition {
|
|
219
|
+
* // Insert request model
|
|
220
|
+
* const requestModel = this.insertModel(
|
|
221
|
+
* new RequestModel({ ... }),
|
|
222
|
+
* 'CreateUserRequest'
|
|
223
|
+
* );
|
|
224
|
+
*
|
|
225
|
+
* // Insert response model
|
|
226
|
+
* const responseModel = this.insertModel(
|
|
227
|
+
* new ResponseModel({ ... }),
|
|
228
|
+
* 'CreateUserResponse'
|
|
229
|
+
* );
|
|
230
|
+
*
|
|
231
|
+
* return new Definition({
|
|
232
|
+
* name: this.operation.operationId,
|
|
233
|
+
* content: `async ${this.operation.operationId}(data: ${requestModel.value}): Promise<${responseModel.value}> {
|
|
234
|
+
* return this.request('${this.operation.method}', '${this.operation.path}', data);
|
|
235
|
+
* }`
|
|
236
|
+
* });
|
|
237
|
+
* }
|
|
238
|
+
* }
|
|
239
|
+
* ```
|
|
240
|
+
*/
|
|
34
241
|
insertModel(insertable, refName, options = {}) {
|
|
35
242
|
return this.context.insertModel(insertable, refName, {
|
|
36
243
|
generation: 'force',
|
|
@@ -38,6 +245,62 @@ export class OperationBase extends ContentBase {
|
|
|
38
245
|
noExport: options.noExport
|
|
39
246
|
});
|
|
40
247
|
}
|
|
248
|
+
/**
|
|
249
|
+
* Inserts a related model with automatic schema normalization and reference resolution.
|
|
250
|
+
*
|
|
251
|
+
* This method intelligently handles schema references from operation request/response
|
|
252
|
+
* bodies, automatically resolving schema references to appropriate model names.
|
|
253
|
+
* This is particularly useful for operations with complex request/response schemas.
|
|
254
|
+
*
|
|
255
|
+
* @template V - Type of generated value returned by the insertable
|
|
256
|
+
* @template Schema - Type of OpenAPI schema (schema object, reference, or void)
|
|
257
|
+
* @template EnrichmentType - Type of enrichment data for the insertable
|
|
258
|
+
* @param insertable - The model generator to insert
|
|
259
|
+
* @param args - Schema normalization arguments
|
|
260
|
+
* @param args.schema - The OpenAPI schema to normalize (from request/response)
|
|
261
|
+
* @param args.fallbackName - Name to use if schema is not a reference
|
|
262
|
+
* @param options - Insertion options
|
|
263
|
+
* @param options.noExport - Whether to skip exporting the inserted model
|
|
264
|
+
* @returns Inserted model reference with normalized name and generated value
|
|
265
|
+
*
|
|
266
|
+
* @example Handling operation request/response schemas
|
|
267
|
+
* ```typescript
|
|
268
|
+
* class RestApiOperation extends OperationBase {
|
|
269
|
+
* toDefinition(): Definition {
|
|
270
|
+
* const operation = this.operation;
|
|
271
|
+
*
|
|
272
|
+
* // Handle request body schema
|
|
273
|
+
* let requestType = 'void';
|
|
274
|
+
* const requestSchema = operation.requestBody?.content?.['application/json']?.schema;
|
|
275
|
+
* if (requestSchema) {
|
|
276
|
+
* const requestModel = this.insertNormalizedModel(
|
|
277
|
+
* new TypeScriptInterface({ ... }),
|
|
278
|
+
* {
|
|
279
|
+
* schema: requestSchema,
|
|
280
|
+
* fallbackName: `${operation.operationId}Request`
|
|
281
|
+
* }
|
|
282
|
+
* );
|
|
283
|
+
* requestType = requestModel.value;
|
|
284
|
+
* }
|
|
285
|
+
*
|
|
286
|
+
* // Handle response schema
|
|
287
|
+
* const responseSchema = operation.responses?.['200']?.content?.['application/json']?.schema;
|
|
288
|
+
* const responseModel = this.insertNormalizedModel(
|
|
289
|
+
* new TypeScriptInterface({ ... }),
|
|
290
|
+
* {
|
|
291
|
+
* schema: responseSchema,
|
|
292
|
+
* fallbackName: `${operation.operationId}Response`
|
|
293
|
+
* }
|
|
294
|
+
* );
|
|
295
|
+
*
|
|
296
|
+
* return new Definition({
|
|
297
|
+
* name: operation.operationId,
|
|
298
|
+
* content: `async ${operation.operationId}(data: ${requestType}): Promise<${responseModel.value}>`
|
|
299
|
+
* });
|
|
300
|
+
* }
|
|
301
|
+
* }
|
|
302
|
+
* ```
|
|
303
|
+
*/
|
|
41
304
|
insertNormalizedModel(insertable, { schema, fallbackName }, options = {}) {
|
|
42
305
|
return this.context.insertNormalisedModel(insertable, {
|
|
43
306
|
schema,
|
|
@@ -45,7 +308,43 @@ export class OperationBase extends ContentBase {
|
|
|
45
308
|
destinationPath: this.settings.exportPath
|
|
46
309
|
}, options);
|
|
47
310
|
}
|
|
48
|
-
/**
|
|
311
|
+
/**
|
|
312
|
+
* Defines and registers a new definition in the generation context.
|
|
313
|
+
*
|
|
314
|
+
* This is an experimental method that allows creating and registering
|
|
315
|
+
* definitions directly without going through the standard insertion flow.
|
|
316
|
+
* Use with caution as the API may change in future versions.
|
|
317
|
+
*
|
|
318
|
+
* @experimental This method's API may change in future versions
|
|
319
|
+
* @template V - Type of generated value
|
|
320
|
+
* @param args - Definition arguments
|
|
321
|
+
* @param args.identifier - Unique identifier for the definition
|
|
322
|
+
* @param args.value - The generated value to associate with the definition
|
|
323
|
+
* @param args.noExport - Whether to skip exporting the definition
|
|
324
|
+
* @returns The created and registered definition
|
|
325
|
+
*
|
|
326
|
+
* @example Creating inline definitions
|
|
327
|
+
* ```typescript
|
|
328
|
+
* class InlineHelperOperation extends OperationBase {
|
|
329
|
+
* toDefinition(): Definition {
|
|
330
|
+
* // Create an inline helper function
|
|
331
|
+
* const helper = this.defineAndRegister({
|
|
332
|
+
* identifier: 'validateRequest',
|
|
333
|
+
* value: 'function validateRequest(data: any) { ... }',
|
|
334
|
+
* noExport: true
|
|
335
|
+
* });
|
|
336
|
+
*
|
|
337
|
+
* return new Definition({
|
|
338
|
+
* name: this.operation.operationId,
|
|
339
|
+
* content: `async ${this.operation.operationId}(data: any) {
|
|
340
|
+
* ${helper.value}(data);
|
|
341
|
+
* return this.request('${this.operation.method}', '${this.operation.path}', data);
|
|
342
|
+
* }`
|
|
343
|
+
* });
|
|
344
|
+
* }
|
|
345
|
+
* }
|
|
346
|
+
* ```
|
|
347
|
+
*/
|
|
49
348
|
defineAndRegister({ identifier, value, noExport }) {
|
|
50
349
|
return this.context.defineAndRegister({
|
|
51
350
|
identifier,
|
|
@@ -54,6 +353,53 @@ export class OperationBase extends ContentBase {
|
|
|
54
353
|
noExport
|
|
55
354
|
});
|
|
56
355
|
}
|
|
356
|
+
/**
|
|
357
|
+
* Registers a file-level artifact with the generation context.
|
|
358
|
+
*
|
|
359
|
+
* This method allows the operation generator to register additional content
|
|
360
|
+
* (like imports, exports, or file-level definitions) that should be included
|
|
361
|
+
* in the generated file. The registration is automatically scoped to this
|
|
362
|
+
* operation's export path.
|
|
363
|
+
*
|
|
364
|
+
* @param args - Registration arguments
|
|
365
|
+
* @param args.content - The content to register (import, export, etc.)
|
|
366
|
+
* @param args.phase - When to register the content ('pre' or 'post')
|
|
367
|
+
*
|
|
368
|
+
* @example Registering API client imports
|
|
369
|
+
* ```typescript
|
|
370
|
+
* class HttpOperation extends OperationBase {
|
|
371
|
+
* toDefinition(): Definition {
|
|
372
|
+
* // Register imports needed for HTTP operations
|
|
373
|
+
* this.register({
|
|
374
|
+
* content: "import { ApiClient } from './client';",
|
|
375
|
+
* phase: 'pre'
|
|
376
|
+
* });
|
|
377
|
+
*
|
|
378
|
+
* this.register({
|
|
379
|
+
* content: "import { RequestOptions } from './types';",
|
|
380
|
+
* phase: 'pre'
|
|
381
|
+
* });
|
|
382
|
+
*
|
|
383
|
+
* return new Definition({ ... });
|
|
384
|
+
* }
|
|
385
|
+
* }
|
|
386
|
+
* ```
|
|
387
|
+
*
|
|
388
|
+
* @example Registering utility exports
|
|
389
|
+
* ```typescript
|
|
390
|
+
* class ApiOperationGroup extends OperationBase {
|
|
391
|
+
* toDefinition(): Definition {
|
|
392
|
+
* // Register a utility export after all operations
|
|
393
|
+
* this.register({
|
|
394
|
+
* content: "export const API_VERSION = '1.0';",
|
|
395
|
+
* phase: 'post'
|
|
396
|
+
* });
|
|
397
|
+
*
|
|
398
|
+
* return new Definition({ ... });
|
|
399
|
+
* }
|
|
400
|
+
* }
|
|
401
|
+
* ```
|
|
402
|
+
*/
|
|
57
403
|
register(args) {
|
|
58
404
|
this.context.register({
|
|
59
405
|
...args,
|
|
@@ -8,23 +8,156 @@ import type { OasSecurityRequirement } from '../securityRequirement/SecurityRequ
|
|
|
8
8
|
import type { StackTrail } from '../../context/StackTrail.js';
|
|
9
9
|
import type { OasSchema } from '../schema/Schema.js';
|
|
10
10
|
import type { OasRef } from '../ref/Ref.js';
|
|
11
|
+
/**
|
|
12
|
+
* Fields that define the structure of an OpenAPI v3 document.
|
|
13
|
+
*
|
|
14
|
+
* This type represents the normalized structure of an OpenAPI document after
|
|
15
|
+
* parsing, with operations flattened from the nested paths structure into
|
|
16
|
+
* a simple array for easier processing.
|
|
17
|
+
*/
|
|
11
18
|
export type DocumentFields = {
|
|
19
|
+
/** OpenAPI specification version (e.g., '3.0.0', '3.1.0') */
|
|
12
20
|
openapi: string;
|
|
21
|
+
/** API metadata including title, version, description */
|
|
13
22
|
info: OasInfo;
|
|
23
|
+
/** Array of server objects providing connectivity information */
|
|
14
24
|
servers?: OasServer[] | undefined;
|
|
25
|
+
/** Flattened array of all operations from all paths */
|
|
15
26
|
operations: OasOperation[];
|
|
27
|
+
/** Container for reusable components (schemas, responses, etc.) */
|
|
16
28
|
components?: OasComponents | undefined;
|
|
29
|
+
/** List of tags used by operations with additional metadata */
|
|
17
30
|
tags?: OasTag[] | undefined;
|
|
31
|
+
/** Default security requirements that apply to all operations */
|
|
18
32
|
security?: OasSecurityRequirement[] | undefined;
|
|
33
|
+
/** Custom extension fields (x-* properties) */
|
|
19
34
|
extensionFields?: Record<string, unknown>;
|
|
20
35
|
};
|
|
21
|
-
/**
|
|
36
|
+
/**
|
|
37
|
+
* Represents a complete OpenAPI v3 document in the SKMTC OAS processing system.
|
|
38
|
+
*
|
|
39
|
+
* The `OasDocument` class is the root object in the OAS hierarchy, containing all
|
|
40
|
+
* the information needed to describe a complete REST API. It provides normalized
|
|
41
|
+
* access to document properties with built-in validation and error handling.
|
|
42
|
+
*
|
|
43
|
+
* ## Key Features
|
|
44
|
+
*
|
|
45
|
+
* - **Normalized Structure**: Operations are flattened from nested paths for easier processing
|
|
46
|
+
* - **Lazy Initialization**: Fields are set after construction during parsing
|
|
47
|
+
* - **Type Safety**: All properties are typed and validated on access
|
|
48
|
+
* - **Extensibility**: Supports OpenAPI extension fields (x-* properties)
|
|
49
|
+
* - **JSON Serialization**: Can be converted back to standard OpenAPI JSON format
|
|
50
|
+
*
|
|
51
|
+
* @example Basic document access
|
|
52
|
+
* ```typescript
|
|
53
|
+
* import { OasDocument } from '@skmtc/core';
|
|
54
|
+
*
|
|
55
|
+
* // Document is typically created during parsing
|
|
56
|
+
* const document = new OasDocument();
|
|
57
|
+
* document.fields = {
|
|
58
|
+
* openapi: '3.0.0',
|
|
59
|
+
* info: { title: 'My API', version: '1.0.0' },
|
|
60
|
+
* operations: [
|
|
61
|
+
* // ... parsed operations
|
|
62
|
+
* ],
|
|
63
|
+
* components: {
|
|
64
|
+
* schemas: {
|
|
65
|
+
* User: { type: 'object', properties: { id: { type: 'string' } } }
|
|
66
|
+
* }
|
|
67
|
+
* }
|
|
68
|
+
* };
|
|
69
|
+
*
|
|
70
|
+
* console.log(document.info.title); // 'My API'
|
|
71
|
+
* console.log(document.operations.length); // Number of operations
|
|
72
|
+
* ```
|
|
73
|
+
*
|
|
74
|
+
* @example Iterating over operations
|
|
75
|
+
* ```typescript
|
|
76
|
+
* // Process all operations in the document
|
|
77
|
+
* for (const operation of document.operations) {
|
|
78
|
+
* console.log(`${operation.method.toUpperCase()} ${operation.path}`);
|
|
79
|
+
*
|
|
80
|
+
* if (operation.operationId) {
|
|
81
|
+
* console.log(`Operation ID: ${operation.operationId}`);
|
|
82
|
+
* }
|
|
83
|
+
* }
|
|
84
|
+
* ```
|
|
85
|
+
*
|
|
86
|
+
* @example Working with components
|
|
87
|
+
* ```typescript
|
|
88
|
+
* if (document.components?.schemas) {
|
|
89
|
+
* const userSchema = document.components.schemas.get('User');
|
|
90
|
+
* if (userSchema) {
|
|
91
|
+
* console.log('User schema found:', userSchema);
|
|
92
|
+
* }
|
|
93
|
+
* }
|
|
94
|
+
* ```
|
|
95
|
+
*/
|
|
22
96
|
export declare class OasDocument {
|
|
23
97
|
#private;
|
|
24
98
|
/** Static identifier property for OasDocument */
|
|
25
99
|
oasType: 'openapi';
|
|
100
|
+
/**
|
|
101
|
+
* Creates a new OasDocument instance.
|
|
102
|
+
*
|
|
103
|
+
* The document is typically created with undefined fields and populated
|
|
104
|
+
* later during the parsing process. This allows for lazy initialization
|
|
105
|
+
* and proper error handling during document processing.
|
|
106
|
+
*
|
|
107
|
+
* @param fields - Optional document fields (usually set later during parsing)
|
|
108
|
+
*
|
|
109
|
+
* @example
|
|
110
|
+
* ```typescript
|
|
111
|
+
* // Usually created without fields during parsing
|
|
112
|
+
* const document = new OasDocument();
|
|
113
|
+
*
|
|
114
|
+
* // Fields are set later by the parser
|
|
115
|
+
* document.fields = parsedDocumentFields;
|
|
116
|
+
* ```
|
|
117
|
+
*/
|
|
26
118
|
constructor(fields?: DocumentFields);
|
|
119
|
+
/**
|
|
120
|
+
* Removes an item from the document based on a stack trail path.
|
|
121
|
+
*
|
|
122
|
+
* This method is used internally during document processing to remove
|
|
123
|
+
* specific operations or schema components. The stack trail indicates
|
|
124
|
+
* the path to the item within the document structure.
|
|
125
|
+
*
|
|
126
|
+
* @param stackTrail - Path to the item to remove
|
|
127
|
+
* @returns The removed item, or undefined if not found
|
|
128
|
+
*
|
|
129
|
+
* @internal This method is primarily used by the processing pipeline
|
|
130
|
+
*
|
|
131
|
+
* @example
|
|
132
|
+
* ```typescript
|
|
133
|
+
* // Remove an operation at /users POST
|
|
134
|
+
* const removed = document.removeItem(new StackTrail(['paths', '/users', 'post']));
|
|
135
|
+
*
|
|
136
|
+
* // Remove a schema component
|
|
137
|
+
* const removedSchema = document.removeItem(new StackTrail(['components', 'schemas', 'User']));
|
|
138
|
+
* ```
|
|
139
|
+
*/
|
|
27
140
|
removeItem(stackTrail: StackTrail): OasOperation | OasSchema | OasRef<'schema'> | undefined;
|
|
141
|
+
/**
|
|
142
|
+
* Sets the document fields after parsing.
|
|
143
|
+
*
|
|
144
|
+
* This setter is called by the parsing pipeline to populate the document
|
|
145
|
+
* with parsed OpenAPI data. It enables lazy initialization and proper
|
|
146
|
+
* error handling during document processing.
|
|
147
|
+
*
|
|
148
|
+
* @param fields - The parsed document fields
|
|
149
|
+
*
|
|
150
|
+
* @example
|
|
151
|
+
* ```typescript
|
|
152
|
+
* const document = new OasDocument();
|
|
153
|
+
* document.fields = {
|
|
154
|
+
* openapi: '3.0.0',
|
|
155
|
+
* info: { title: 'API', version: '1.0' },
|
|
156
|
+
* operations: [],
|
|
157
|
+
* // ... other fields
|
|
158
|
+
* };
|
|
159
|
+
* ```
|
|
160
|
+
*/
|
|
28
161
|
set fields(fields: DocumentFields);
|
|
29
162
|
/** OpenAPI specification version */
|
|
30
163
|
get openapi(): string;
|
|
@@ -41,6 +174,27 @@ export declare class OasDocument {
|
|
|
41
174
|
get security(): OasSecurityRequirement[] | undefined;
|
|
42
175
|
/** Specification Extension fields */
|
|
43
176
|
get extensionFields(): Record<string, unknown> | undefined;
|
|
177
|
+
/**
|
|
178
|
+
* Converts the document back to a JSON-serializable OpenAPI object.
|
|
179
|
+
*
|
|
180
|
+
* This method serializes the document to a standard OpenAPI v3 format,
|
|
181
|
+
* which can be used for output, validation, or further processing. The
|
|
182
|
+
* resulting object follows the OpenAPI specification structure.
|
|
183
|
+
*
|
|
184
|
+
* @returns A JSON-serializable object representing the OpenAPI document
|
|
185
|
+
*
|
|
186
|
+
* @example
|
|
187
|
+
* ```typescript
|
|
188
|
+
* // Convert document back to standard OpenAPI format
|
|
189
|
+
* const openApiJson = document.toJSON();
|
|
190
|
+
*
|
|
191
|
+
* // Can be stringified for output
|
|
192
|
+
* const yamlString = JSON.stringify(openApiJson, null, 2);
|
|
193
|
+
*
|
|
194
|
+
* // Or used with OpenAPI tools
|
|
195
|
+
* await validateOpenApiDocument(openApiJson);
|
|
196
|
+
* ```
|
|
197
|
+
*/
|
|
44
198
|
toJSON(): object;
|
|
45
199
|
}
|
|
46
200
|
//# sourceMappingURL=Document.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"Document.d.ts","sourceRoot":"","sources":["../../../src/oas/document/Document.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAA;AAC3F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAG7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAE3C,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,OAAO,CAAA;IACb,OAAO,CAAC,EAAE,SAAS,EAAE,GAAG,SAAS,CAAA;IACjC,UAAU,EAAE,YAAY,EAAE,CAAA;IAC1B,UAAU,CAAC,EAAE,aAAa,GAAG,SAAS,CAAA;IACtC,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC3B,QAAQ,CAAC,EAAE,sBAAsB,EAAE,GAAG,SAAS,CAAA;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED
|
|
1
|
+
{"version":3,"file":"Document.d.ts","sourceRoot":"","sources":["../../../src/oas/document/Document.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAA;AAC9C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAA;AAC3F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,6BAA6B,CAAA;AAG7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAE3C;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAA;IACf,yDAAyD;IACzD,IAAI,EAAE,OAAO,CAAA;IACb,iEAAiE;IACjE,OAAO,CAAC,EAAE,SAAS,EAAE,GAAG,SAAS,CAAA;IACjC,uDAAuD;IACvD,UAAU,EAAE,YAAY,EAAE,CAAA;IAC1B,mEAAmE;IACnE,UAAU,CAAC,EAAE,aAAa,GAAG,SAAS,CAAA;IACtC,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAA;IAC3B,iEAAiE;IACjE,QAAQ,CAAC,EAAE,sBAAsB,EAAE,GAAG,SAAS,CAAA;IAC/C,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,qBAAa,WAAW;;IACtB,iDAAiD;IACjD,OAAO,EAAE,SAAS,CAAY;IAK9B;;;;;;;;;;;;;;;;;OAiBG;gBACS,MAAM,CAAC,EAAE,cAAc;IAInC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,UAAU,CAAC,UAAU,EAAE,UAAU,GAAG,YAAY,GAAG,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS;IA6B3F;;;;;;;;;;;;;;;;;;;OAmBG;IACH,IAAI,MAAM,CAAC,MAAM,EAAE,cAAc,EAEhC;IAED,oCAAoC;IACpC,IAAI,OAAO,IAAI,MAAM,CAMpB;IAED,mBAAmB;IACnB,IAAI,IAAI,IAAI,OAAO,CAMlB;IAED,IAAI,OAAO,IAAI,SAAS,EAAE,GAAG,SAAS,CAMrC;IAED,yCAAyC;IACzC,IAAI,UAAU,IAAI,YAAY,EAAE,CAM/B;IAED,iEAAiE;IACjE,IAAI,UAAU,IAAI,aAAa,GAAG,SAAS,CAM1C;IAED,wDAAwD;IACxD,IAAI,IAAI,IAAI,MAAM,EAAE,GAAG,SAAS,CAM/B;IAED,gDAAgD;IAChD,IAAI,QAAQ,IAAI,sBAAsB,EAAE,GAAG,SAAS,CAMnD;IAED,qCAAqC;IACrC,IAAI,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAMzD;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,MAAM,IAAI,MAAM;CAYjB"}
|