@skmtc/core 0.0.794 → 0.0.795
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/context/StackTrail.d.ts +293 -0
- package/esm/context/StackTrail.d.ts.map +1 -1
- package/esm/context/StackTrail.js +294 -0
- package/esm/types/Modifiers.d.ts +68 -0
- package/esm/types/Modifiers.d.ts.map +1 -1
- package/esm/types/TypeSystem.d.ts +419 -0
- package/esm/types/TypeSystem.d.ts.map +1 -1
- package/esm/typescript/FunctionParameter.d.ts +313 -0
- package/esm/typescript/FunctionParameter.d.ts.map +1 -1
- package/esm/typescript/FunctionParameter.js +328 -0
- package/package.json +1 -1
- package/script/context/StackTrail.d.ts +293 -0
- package/script/context/StackTrail.d.ts.map +1 -1
- package/script/context/StackTrail.js +294 -0
- package/script/types/Modifiers.d.ts +68 -0
- package/script/types/Modifiers.d.ts.map +1 -1
- package/script/types/TypeSystem.d.ts +419 -0
- package/script/types/TypeSystem.d.ts.map +1 -1
- package/script/typescript/FunctionParameter.d.ts +313 -0
- package/script/typescript/FunctionParameter.d.ts.map +1 -1
- package/script/typescript/FunctionParameter.js +328 -0
|
@@ -3,14 +3,183 @@ import { camelCase } from 'lodash-es';
|
|
|
3
3
|
import { match, P } from 'ts-pattern';
|
|
4
4
|
import { List } from './List.js';
|
|
5
5
|
import { isEmpty } from '../helpers/isEmpty.js';
|
|
6
|
+
/**
|
|
7
|
+
* Generates TypeScript function parameters with advanced handling for different parameter patterns.
|
|
8
|
+
*
|
|
9
|
+
* `FunctionParameter` is a sophisticated utility for generating TypeScript function parameter
|
|
10
|
+
* syntax that handles multiple parameter patterns including named parameters, destructured
|
|
11
|
+
* object parameters, and void parameters. It provides intelligent type handling and can
|
|
12
|
+
* generate both the parameter declaration and the parameter usage patterns.
|
|
13
|
+
*
|
|
14
|
+
* This class is essential for generating type-safe function signatures in API clients,
|
|
15
|
+
* utility functions, and other generated code where parameters need to be handled
|
|
16
|
+
* consistently and safely.
|
|
17
|
+
*
|
|
18
|
+
* ## Supported Parameter Patterns
|
|
19
|
+
*
|
|
20
|
+
* - **Named Parameters**: Traditional `paramName: Type` syntax
|
|
21
|
+
* - **Destructured Parameters**: `{ prop1, prop2 }: ObjectType` syntax
|
|
22
|
+
* - **Void Parameters**: No parameters when dealing with void types
|
|
23
|
+
* - **Optional Parameters**: Automatic handling of optional parameter markers
|
|
24
|
+
* - **Empty Filtering**: Option to skip empty properties in destructured objects
|
|
25
|
+
*
|
|
26
|
+
* @example Named parameter generation
|
|
27
|
+
* ```typescript
|
|
28
|
+
* import { FunctionParameter, Definition, Identifier } from '@skmtc/core';
|
|
29
|
+
*
|
|
30
|
+
* const userIdParam = new FunctionParameter({
|
|
31
|
+
* name: 'userId',
|
|
32
|
+
* typeDefinition: new Definition({
|
|
33
|
+
* context: generateContext,
|
|
34
|
+
* identifier: Identifier.createType('string'),
|
|
35
|
+
* value: { type: 'string' }
|
|
36
|
+
* }),
|
|
37
|
+
* required: true
|
|
38
|
+
* });
|
|
39
|
+
*
|
|
40
|
+
* console.log(userIdParam.toString()); // 'userId: string'
|
|
41
|
+
* console.log(userIdParam.toInbound()); // 'userId'
|
|
42
|
+
* ```
|
|
43
|
+
*
|
|
44
|
+
* @example Destructured parameter generation
|
|
45
|
+
* ```typescript
|
|
46
|
+
* const destructuredParam = new FunctionParameter({
|
|
47
|
+
* typeDefinition: new Definition({
|
|
48
|
+
* context: generateContext,
|
|
49
|
+
* identifier: Identifier.createType('UserParams'),
|
|
50
|
+
* value: {
|
|
51
|
+
* type: 'object',
|
|
52
|
+
* objectProperties: {
|
|
53
|
+
* properties: {
|
|
54
|
+
* name: { type: 'string' },
|
|
55
|
+
* email: { type: 'string' },
|
|
56
|
+
* age: { type: 'number' }
|
|
57
|
+
* }
|
|
58
|
+
* }
|
|
59
|
+
* }
|
|
60
|
+
* }),
|
|
61
|
+
* destructure: true,
|
|
62
|
+
* required: true
|
|
63
|
+
* });
|
|
64
|
+
*
|
|
65
|
+
* console.log(destructuredParam.toString());
|
|
66
|
+
* // '{ name, email, age }: UserParams'
|
|
67
|
+
*
|
|
68
|
+
* console.log(destructuredParam.toInbound());
|
|
69
|
+
* // '{ name, email, age }'
|
|
70
|
+
* ```
|
|
71
|
+
*
|
|
72
|
+
* @example Optional parameter handling
|
|
73
|
+
* ```typescript
|
|
74
|
+
* const optionalParam = new FunctionParameter({
|
|
75
|
+
* name: 'options',
|
|
76
|
+
* typeDefinition: optionsTypeDefinition,
|
|
77
|
+
* required: false
|
|
78
|
+
* });
|
|
79
|
+
*
|
|
80
|
+
* console.log(optionalParam.toString()); // 'options?: OptionsType'
|
|
81
|
+
* ```
|
|
82
|
+
*
|
|
83
|
+
* @example Void parameter handling
|
|
84
|
+
* ```typescript
|
|
85
|
+
* const voidParam = new FunctionParameter({
|
|
86
|
+
* typeDefinition: new Definition({
|
|
87
|
+
* context: generateContext,
|
|
88
|
+
* identifier: Identifier.createType('void'),
|
|
89
|
+
* value: { type: 'void' }
|
|
90
|
+
* })
|
|
91
|
+
* });
|
|
92
|
+
*
|
|
93
|
+
* console.log(voidParam.toString()); // ''
|
|
94
|
+
* console.log(voidParam.toInbound()); // ''
|
|
95
|
+
* ```
|
|
96
|
+
*
|
|
97
|
+
* @example Property checking
|
|
98
|
+
* ```typescript
|
|
99
|
+
* const objectParam = new FunctionParameter({
|
|
100
|
+
* typeDefinition: userTypeDefinition,
|
|
101
|
+
* destructure: true,
|
|
102
|
+
* required: true
|
|
103
|
+
* });
|
|
104
|
+
*
|
|
105
|
+
* if (objectParam.hasProperty('email')) {
|
|
106
|
+
* // Handle email property access
|
|
107
|
+
* console.log('Parameter includes email property');
|
|
108
|
+
* }
|
|
109
|
+
*
|
|
110
|
+
* const propertyList = objectParam.toPropertyList();
|
|
111
|
+
* console.log(propertyList.toString()); // 'name, email, age'
|
|
112
|
+
* ```
|
|
113
|
+
*
|
|
114
|
+
* @example API method generation with parameters
|
|
115
|
+
* ```typescript
|
|
116
|
+
* class ApiMethodGenerator {
|
|
117
|
+
* generateMethod(
|
|
118
|
+
* methodName: string,
|
|
119
|
+
* pathParams?: FunctionParameter,
|
|
120
|
+
* bodyParam?: FunctionParameter
|
|
121
|
+
* ) {
|
|
122
|
+
* const parameters = [pathParams, bodyParam]
|
|
123
|
+
* .filter(p => p && p.toString())
|
|
124
|
+
* .map(p => p!.toString())
|
|
125
|
+
* .join(', ');
|
|
126
|
+
*
|
|
127
|
+
* const pathInbound = pathParams?.toInbound() || '';
|
|
128
|
+
* const bodyInbound = bodyParam?.toInbound() || '';
|
|
129
|
+
*
|
|
130
|
+
* return `
|
|
131
|
+
* async ${methodName}(${parameters}) {
|
|
132
|
+
* const path = this.buildPath(${pathInbound});
|
|
133
|
+
* return this.request('POST', path, ${bodyInbound});
|
|
134
|
+
* }`;
|
|
135
|
+
* }
|
|
136
|
+
* }
|
|
137
|
+
* ```
|
|
138
|
+
*
|
|
139
|
+
* @example Empty property filtering
|
|
140
|
+
* ```typescript
|
|
141
|
+
* const filteredParam = new FunctionParameter({
|
|
142
|
+
* typeDefinition: sparseObjectDefinition,
|
|
143
|
+
* destructure: true,
|
|
144
|
+
* required: true,
|
|
145
|
+
* skipEmpty: true // Skip properties with empty types
|
|
146
|
+
* });
|
|
147
|
+
*
|
|
148
|
+
* // Only non-empty properties will be included in destructuring
|
|
149
|
+
* console.log(filteredParam.toString());
|
|
150
|
+
* // '{ validProp1, validProp2 }: FilteredType' (empty props omitted)
|
|
151
|
+
* ```
|
|
152
|
+
*/
|
|
6
153
|
export class FunctionParameter {
|
|
154
|
+
/**
|
|
155
|
+
* Creates a new FunctionParameter instance with the specified configuration.
|
|
156
|
+
*
|
|
157
|
+
* The constructor analyzes the provided type definition and configuration options
|
|
158
|
+
* to determine the appropriate parameter pattern (void, regular, or destructured).
|
|
159
|
+
* It handles the complex logic of parameter type determination and validation.
|
|
160
|
+
*
|
|
161
|
+
* @param args - Configuration options for the function parameter
|
|
162
|
+
*
|
|
163
|
+
* @throws {Error} When the parameter configuration is invalid
|
|
164
|
+
*
|
|
165
|
+
* @example
|
|
166
|
+
* ```typescript
|
|
167
|
+
* const param = new FunctionParameter({
|
|
168
|
+
* name: 'userData',
|
|
169
|
+
* typeDefinition: userTypeDefinition,
|
|
170
|
+
* required: true
|
|
171
|
+
* });
|
|
172
|
+
* ```
|
|
173
|
+
*/
|
|
7
174
|
constructor(args) {
|
|
175
|
+
/** The internal parameter configuration determining how the parameter is generated */
|
|
8
176
|
Object.defineProperty(this, "properties", {
|
|
9
177
|
enumerable: true,
|
|
10
178
|
configurable: true,
|
|
11
179
|
writable: true,
|
|
12
180
|
value: void 0
|
|
13
181
|
});
|
|
182
|
+
/** Whether to skip empty properties in destructured parameters */
|
|
14
183
|
Object.defineProperty(this, "skipEmpty", {
|
|
15
184
|
enumerable: true,
|
|
16
185
|
configurable: true,
|
|
@@ -39,6 +208,34 @@ export class FunctionParameter {
|
|
|
39
208
|
this.properties = { type: 'void' };
|
|
40
209
|
}
|
|
41
210
|
}
|
|
211
|
+
/**
|
|
212
|
+
* Checks if the parameter has a specific property (for object-based parameters).
|
|
213
|
+
*
|
|
214
|
+
* This method determines whether a given property name exists within the parameter's
|
|
215
|
+
* type structure. It's useful for conditional code generation based on available
|
|
216
|
+
* properties and only returns true for object-based parameters (regular object
|
|
217
|
+
* parameters or destructured parameters).
|
|
218
|
+
*
|
|
219
|
+
* @param name - The property name to check for
|
|
220
|
+
* @returns True if the property exists in the parameter's type structure
|
|
221
|
+
*
|
|
222
|
+
* @example
|
|
223
|
+
* ```typescript
|
|
224
|
+
* const userParam = new FunctionParameter({
|
|
225
|
+
* typeDefinition: userTypeDefinition, // has properties: name, email, age
|
|
226
|
+
* destructure: true,
|
|
227
|
+
* required: true
|
|
228
|
+
* });
|
|
229
|
+
*
|
|
230
|
+
* if (userParam.hasProperty('email')) {
|
|
231
|
+
* console.log('Parameter includes email property');
|
|
232
|
+
* }
|
|
233
|
+
*
|
|
234
|
+
* if (userParam.hasProperty('nonexistent')) {
|
|
235
|
+
* // This won't execute
|
|
236
|
+
* }
|
|
237
|
+
* ```
|
|
238
|
+
*/
|
|
42
239
|
hasProperty(name) {
|
|
43
240
|
return match(this.properties)
|
|
44
241
|
.with({ type: 'void' }, () => false)
|
|
@@ -51,6 +248,37 @@ export class FunctionParameter {
|
|
|
51
248
|
})
|
|
52
249
|
.exhaustive();
|
|
53
250
|
}
|
|
251
|
+
/**
|
|
252
|
+
* Generates a List of property names from the parameter.
|
|
253
|
+
*
|
|
254
|
+
* This method extracts property names from object-based parameters and returns
|
|
255
|
+
* them as a List instance. For regular parameters, it returns the parameter name,
|
|
256
|
+
* for destructured parameters it returns all object properties, and for void
|
|
257
|
+
* parameters it returns an empty list.
|
|
258
|
+
*
|
|
259
|
+
* @returns List containing the relevant property or parameter names
|
|
260
|
+
*
|
|
261
|
+
* @example
|
|
262
|
+
* ```typescript
|
|
263
|
+
* const destructuredParam = new FunctionParameter({
|
|
264
|
+
* typeDefinition: userTypeDefinition, // has properties: name, email, age
|
|
265
|
+
* destructure: true,
|
|
266
|
+
* required: true
|
|
267
|
+
* });
|
|
268
|
+
*
|
|
269
|
+
* const propertyList = destructuredParam.toPropertyList();
|
|
270
|
+
* console.log(propertyList.toString()); // 'name, email, age'
|
|
271
|
+
*
|
|
272
|
+
* const regularParam = new FunctionParameter({
|
|
273
|
+
* name: 'userData',
|
|
274
|
+
* typeDefinition: userTypeDefinition,
|
|
275
|
+
* required: true
|
|
276
|
+
* });
|
|
277
|
+
*
|
|
278
|
+
* const regularList = regularParam.toPropertyList();
|
|
279
|
+
* console.log(regularList.toString()); // 'userData'
|
|
280
|
+
* ```
|
|
281
|
+
*/
|
|
54
282
|
toPropertyList() {
|
|
55
283
|
return match(this.properties)
|
|
56
284
|
.with({ type: 'void' }, () => List.toEmpty())
|
|
@@ -60,6 +288,35 @@ export class FunctionParameter {
|
|
|
60
288
|
})
|
|
61
289
|
.exhaustive();
|
|
62
290
|
}
|
|
291
|
+
/**
|
|
292
|
+
* Generates the inbound parameter syntax for function calls.
|
|
293
|
+
*
|
|
294
|
+
* This method produces the syntax used when calling a function with this parameter.
|
|
295
|
+
* For regular parameters, it returns the parameter name. For destructured parameters,
|
|
296
|
+
* it returns the destructured object syntax. For void parameters, it returns an
|
|
297
|
+
* empty string.
|
|
298
|
+
*
|
|
299
|
+
* @returns The inbound parameter syntax string
|
|
300
|
+
*
|
|
301
|
+
* @example
|
|
302
|
+
* ```typescript
|
|
303
|
+
* const regularParam = new FunctionParameter({
|
|
304
|
+
* name: 'userId',
|
|
305
|
+
* typeDefinition: stringTypeDefinition,
|
|
306
|
+
* required: true
|
|
307
|
+
* });
|
|
308
|
+
*
|
|
309
|
+
* console.log(regularParam.toInbound()); // 'userId'
|
|
310
|
+
*
|
|
311
|
+
* const destructuredParam = new FunctionParameter({
|
|
312
|
+
* typeDefinition: userTypeDefinition,
|
|
313
|
+
* destructure: true,
|
|
314
|
+
* required: true
|
|
315
|
+
* });
|
|
316
|
+
*
|
|
317
|
+
* console.log(destructuredParam.toInbound()); // '{ name, email, age }'
|
|
318
|
+
* ```
|
|
319
|
+
*/
|
|
63
320
|
toInbound() {
|
|
64
321
|
return match(this.properties)
|
|
65
322
|
.with({ type: 'void' }, () => '')
|
|
@@ -69,6 +326,42 @@ export class FunctionParameter {
|
|
|
69
326
|
})
|
|
70
327
|
.exhaustive();
|
|
71
328
|
}
|
|
329
|
+
/**
|
|
330
|
+
* Generates the complete function parameter declaration syntax.
|
|
331
|
+
*
|
|
332
|
+
* This method produces the full parameter declaration that appears in a function
|
|
333
|
+
* signature, including the parameter name, type annotation, and optional markers.
|
|
334
|
+
* It handles all parameter patterns supported by the class.
|
|
335
|
+
*
|
|
336
|
+
* @returns The complete parameter declaration string
|
|
337
|
+
*
|
|
338
|
+
* @example
|
|
339
|
+
* ```typescript
|
|
340
|
+
* const requiredParam = new FunctionParameter({
|
|
341
|
+
* name: 'userId',
|
|
342
|
+
* typeDefinition: stringTypeDefinition,
|
|
343
|
+
* required: true
|
|
344
|
+
* });
|
|
345
|
+
*
|
|
346
|
+
* console.log(requiredParam.toString()); // 'userId: string'
|
|
347
|
+
*
|
|
348
|
+
* const optionalParam = new FunctionParameter({
|
|
349
|
+
* name: 'options',
|
|
350
|
+
* typeDefinition: optionsTypeDefinition,
|
|
351
|
+
* required: false
|
|
352
|
+
* });
|
|
353
|
+
*
|
|
354
|
+
* console.log(optionalParam.toString()); // 'options?: OptionsType'
|
|
355
|
+
*
|
|
356
|
+
* const destructuredParam = new FunctionParameter({
|
|
357
|
+
* typeDefinition: userTypeDefinition,
|
|
358
|
+
* destructure: true,
|
|
359
|
+
* required: true
|
|
360
|
+
* });
|
|
361
|
+
*
|
|
362
|
+
* console.log(destructuredParam.toString()); // '{ name, email, age }: UserType'
|
|
363
|
+
* ```
|
|
364
|
+
*/
|
|
72
365
|
toString() {
|
|
73
366
|
return match(this.properties)
|
|
74
367
|
.with({ type: 'void' }, () => '')
|
|
@@ -86,6 +379,41 @@ export class FunctionParameter {
|
|
|
86
379
|
.exhaustive();
|
|
87
380
|
}
|
|
88
381
|
}
|
|
382
|
+
/**
|
|
383
|
+
* Generates destructured object parameter syntax from a type definition.
|
|
384
|
+
*
|
|
385
|
+
* This helper function creates the destructured parameter syntax for object types,
|
|
386
|
+
* handling property name validation and optional camelCase conversion for invalid
|
|
387
|
+
* JavaScript identifiers. It integrates with the List system to produce properly
|
|
388
|
+
* formatted destructured parameter lists.
|
|
389
|
+
*
|
|
390
|
+
* @param typeDefinition - The object type definition to destructure
|
|
391
|
+
* @param options - Options for controlling the destructuring behavior
|
|
392
|
+
* @param options.skipEmpty - Whether to skip empty properties
|
|
393
|
+
* @returns List instance representing the destructured parameter structure
|
|
394
|
+
*
|
|
395
|
+
* @example
|
|
396
|
+
* ```typescript
|
|
397
|
+
* const objectDef = new Definition({
|
|
398
|
+
* context: generateContext,
|
|
399
|
+
* identifier: Identifier.createType('ApiParams'),
|
|
400
|
+
* value: {
|
|
401
|
+
* type: 'object',
|
|
402
|
+
* objectProperties: {
|
|
403
|
+
* properties: {
|
|
404
|
+
* 'user-id': { type: 'string' },
|
|
405
|
+
* 'valid_name': { type: 'string' },
|
|
406
|
+
* 'api-key': { type: 'string' }
|
|
407
|
+
* }
|
|
408
|
+
* }
|
|
409
|
+
* }
|
|
410
|
+
* });
|
|
411
|
+
*
|
|
412
|
+
* const result = toDestructured(objectDef);
|
|
413
|
+
* console.log(result.toString());
|
|
414
|
+
* // "{ 'user-id': userId, valid_name, 'api-key': apiKey }"
|
|
415
|
+
* ```
|
|
416
|
+
*/
|
|
89
417
|
const toDestructured = (typeDefinition, { skipEmpty } = {}) => {
|
|
90
418
|
return List.fromKeys(typeDefinition.value.objectProperties?.properties).toObject(key => {
|
|
91
419
|
return isIdentifierName(key) ? key : List.toKeyValue(key, camelCase(key));
|
package/package.json
CHANGED
|
@@ -1,18 +1,311 @@
|
|
|
1
1
|
import "../_dnt.polyfills.js";
|
|
2
|
+
/**
|
|
3
|
+
* Represents a stack-based trail for tracking document traversal in OpenAPI processing.
|
|
4
|
+
*
|
|
5
|
+
* The `StackTrail` class maintains a stack of string frames that represent the current
|
|
6
|
+
* path through an OpenAPI document structure. It's used throughout the SKMTC pipeline
|
|
7
|
+
* for tracking context during parsing, generating, and debugging schema processing.
|
|
8
|
+
*
|
|
9
|
+
* This class is essential for error reporting, debugging, and maintaining context
|
|
10
|
+
* when processing nested OpenAPI structures like schemas, operations, and components.
|
|
11
|
+
*
|
|
12
|
+
* ## Key Features
|
|
13
|
+
*
|
|
14
|
+
* - **Path Tracking**: Maintains a trail of traversed document elements
|
|
15
|
+
* - **Context Preservation**: Preserves parsing context for error reporting
|
|
16
|
+
* - **Stack Operations**: Supports push, pop, clone, and manipulation operations
|
|
17
|
+
* - **Reference Resolution**: Can generate OpenAPI reference strings from trails
|
|
18
|
+
* - **Serialization**: Supports string serialization and parsing for persistence
|
|
19
|
+
*
|
|
20
|
+
* @example Basic usage
|
|
21
|
+
* ```typescript
|
|
22
|
+
* import { StackTrail } from '@skmtc/core';
|
|
23
|
+
*
|
|
24
|
+
* // Start with empty trail
|
|
25
|
+
* const trail = new StackTrail();
|
|
26
|
+
*
|
|
27
|
+
* // Build a path through document structure
|
|
28
|
+
* trail.append('components')
|
|
29
|
+
* .append('schemas')
|
|
30
|
+
* .append('User')
|
|
31
|
+
* .append('properties')
|
|
32
|
+
* .append('name');
|
|
33
|
+
*
|
|
34
|
+
* console.log(trail.toString()); // 'components:schemas:User:properties:name'
|
|
35
|
+
* ```
|
|
36
|
+
*
|
|
37
|
+
* @example Schema reference generation
|
|
38
|
+
* ```typescript
|
|
39
|
+
* const schemaTrail = new StackTrail(['components', 'schemas', 'User']);
|
|
40
|
+
* const ref = schemaTrail.toStackRef();
|
|
41
|
+
* console.log(ref); // '#/components/schemas/User'
|
|
42
|
+
* ```
|
|
43
|
+
*
|
|
44
|
+
* @example Error context tracking
|
|
45
|
+
* ```typescript
|
|
46
|
+
* class SchemaProcessor {
|
|
47
|
+
* processSchema(schema: OasSchema, trail: StackTrail) {
|
|
48
|
+
* try {
|
|
49
|
+
* // Process schema logic
|
|
50
|
+
* return this.transformSchema(schema);
|
|
51
|
+
* } catch (error) {
|
|
52
|
+
* throw new Error(`Error at ${trail.toString()}: ${error.message}`);
|
|
53
|
+
* // Error at components:schemas:User:properties:email: Invalid format
|
|
54
|
+
* }
|
|
55
|
+
* }
|
|
56
|
+
* }
|
|
57
|
+
* ```
|
|
58
|
+
*
|
|
59
|
+
* @example Cloning and manipulation
|
|
60
|
+
* ```typescript
|
|
61
|
+
* const baseTrail = new StackTrail(['components', 'schemas']);
|
|
62
|
+
*
|
|
63
|
+
* // Clone for processing different schemas
|
|
64
|
+
* const userTrail = baseTrail.clone().append('User');
|
|
65
|
+
* const productTrail = baseTrail.clone().append('Product');
|
|
66
|
+
*
|
|
67
|
+
* console.log(userTrail.toString()); // 'components:schemas:User'
|
|
68
|
+
* console.log(productTrail.toString()); // 'components:schemas:Product'
|
|
69
|
+
* console.log(baseTrail.toString()); // 'components:schemas' (unchanged)
|
|
70
|
+
* ```
|
|
71
|
+
*/
|
|
2
72
|
export declare class StackTrail {
|
|
3
73
|
#private;
|
|
74
|
+
/**
|
|
75
|
+
* Creates a new StackTrail instance.
|
|
76
|
+
*
|
|
77
|
+
* @param stack - Initial stack frames (defaults to empty array)
|
|
78
|
+
*
|
|
79
|
+
* @example
|
|
80
|
+
* ```typescript
|
|
81
|
+
* // Empty trail
|
|
82
|
+
* const trail1 = new StackTrail();
|
|
83
|
+
*
|
|
84
|
+
* // Pre-populated trail
|
|
85
|
+
* const trail2 = new StackTrail(['components', 'schemas', 'User']);
|
|
86
|
+
* ```
|
|
87
|
+
*/
|
|
4
88
|
constructor(stack?: string[]);
|
|
89
|
+
/**
|
|
90
|
+
* Creates a shallow copy of the stack trail.
|
|
91
|
+
*
|
|
92
|
+
* @returns A new StackTrail instance with copied frames
|
|
93
|
+
*
|
|
94
|
+
* @example
|
|
95
|
+
* ```typescript
|
|
96
|
+
* const original = new StackTrail(['components', 'schemas']);
|
|
97
|
+
* const copy = original.clone();
|
|
98
|
+
*
|
|
99
|
+
* copy.append('User');
|
|
100
|
+
* console.log(original.toString()); // 'components:schemas'
|
|
101
|
+
* console.log(copy.toString()); // 'components:schemas:User'
|
|
102
|
+
* ```
|
|
103
|
+
*/
|
|
5
104
|
clone(): StackTrail;
|
|
105
|
+
/**
|
|
106
|
+
* Creates a new trail from a slice of the current trail.
|
|
107
|
+
*
|
|
108
|
+
* @param start - Starting index (inclusive)
|
|
109
|
+
* @param end - Ending index (exclusive, optional)
|
|
110
|
+
* @returns A new StackTrail with sliced frames
|
|
111
|
+
*
|
|
112
|
+
* @example
|
|
113
|
+
* ```typescript
|
|
114
|
+
* const trail = new StackTrail(['a', 'b', 'c', 'd', 'e']);
|
|
115
|
+
*
|
|
116
|
+
* const slice1 = trail.slice(1, 3);
|
|
117
|
+
* console.log(slice1.toString()); // 'b:c'
|
|
118
|
+
*
|
|
119
|
+
* const slice2 = trail.slice(2);
|
|
120
|
+
* console.log(slice2.toString()); // 'c:d:e'
|
|
121
|
+
* ```
|
|
122
|
+
*/
|
|
6
123
|
slice(start: number, end?: number): StackTrail;
|
|
124
|
+
/**
|
|
125
|
+
* Checks if all specified frames exist in the trail.
|
|
126
|
+
*
|
|
127
|
+
* @param frames - Array of frames to check for
|
|
128
|
+
* @returns True if all frames are present in the trail
|
|
129
|
+
*
|
|
130
|
+
* @example
|
|
131
|
+
* ```typescript
|
|
132
|
+
* const trail = new StackTrail(['components', 'schemas', 'User', 'properties']);
|
|
133
|
+
*
|
|
134
|
+
* console.log(trail.includes(['schemas', 'User'])); // true
|
|
135
|
+
* console.log(trail.includes(['schemas', 'Product'])); // false
|
|
136
|
+
* console.log(trail.includes(['components'])); // true
|
|
137
|
+
* ```
|
|
138
|
+
*/
|
|
7
139
|
includes(frames: string[]): boolean;
|
|
140
|
+
/**
|
|
141
|
+
* Gets a copy of the current stack frames.
|
|
142
|
+
*
|
|
143
|
+
* @returns Array of stack frames in order
|
|
144
|
+
*
|
|
145
|
+
* @example
|
|
146
|
+
* ```typescript
|
|
147
|
+
* const trail = new StackTrail(['components', 'schemas', 'User']);
|
|
148
|
+
* const frames = trail.stackTrail;
|
|
149
|
+
* console.log(frames); // ['components', 'schemas', 'User']
|
|
150
|
+
* ```
|
|
151
|
+
*/
|
|
8
152
|
get stackTrail(): string[];
|
|
153
|
+
/**
|
|
154
|
+
* Appends frame(s) to the end of the trail.
|
|
155
|
+
*
|
|
156
|
+
* @param frame - Single frame string or array of frames to append
|
|
157
|
+
* @returns This StackTrail instance for chaining
|
|
158
|
+
*
|
|
159
|
+
* @throws {Error} When frame is not a string or string array
|
|
160
|
+
*
|
|
161
|
+
* @example Single frame
|
|
162
|
+
* ```typescript
|
|
163
|
+
* const trail = new StackTrail(['components']);
|
|
164
|
+
* trail.append('schemas').append('User');
|
|
165
|
+
* console.log(trail.toString()); // 'components:schemas:User'
|
|
166
|
+
* ```
|
|
167
|
+
*
|
|
168
|
+
* @example Multiple frames
|
|
169
|
+
* ```typescript
|
|
170
|
+
* const trail = new StackTrail();
|
|
171
|
+
* trail.append(['components', 'schemas', 'User']);
|
|
172
|
+
* console.log(trail.toString()); // 'components:schemas:User'
|
|
173
|
+
* ```
|
|
174
|
+
*/
|
|
9
175
|
append(frame: string | string[]): StackTrail;
|
|
176
|
+
/**
|
|
177
|
+
* Gets the parent name of a property frame.
|
|
178
|
+
*
|
|
179
|
+
* This method is specifically designed to find parent object names
|
|
180
|
+
* for property trails in schema processing.
|
|
181
|
+
*
|
|
182
|
+
* @param frame - The frame name to find the parent of
|
|
183
|
+
* @returns Parent name if found, undefined otherwise
|
|
184
|
+
*
|
|
185
|
+
* @example
|
|
186
|
+
* ```typescript
|
|
187
|
+
* const trail = new StackTrail(['components', 'schemas', 'User', 'properties', 'email']);
|
|
188
|
+
* const parent = trail.getParentOf('email');
|
|
189
|
+
* console.log(parent); // 'User'
|
|
190
|
+
* ```
|
|
191
|
+
*/
|
|
10
192
|
getParentOf(frame: string): string | undefined;
|
|
193
|
+
/**
|
|
194
|
+
* Converts the trail to an OpenAPI reference string if applicable.
|
|
195
|
+
*
|
|
196
|
+
* Only trails that represent valid OpenAPI component references
|
|
197
|
+
* (starting with 'components') can be converted to reference strings.
|
|
198
|
+
*
|
|
199
|
+
* @returns OpenAPI reference string or undefined if not a valid reference trail
|
|
200
|
+
*
|
|
201
|
+
* @example Valid reference trail
|
|
202
|
+
* ```typescript
|
|
203
|
+
* const trail = new StackTrail(['components', 'schemas', 'User']);
|
|
204
|
+
* const ref = trail.toStackRef();
|
|
205
|
+
* console.log(ref); // '#/components/schemas/User'
|
|
206
|
+
* ```
|
|
207
|
+
*
|
|
208
|
+
* @example Invalid trail
|
|
209
|
+
* ```typescript
|
|
210
|
+
* const trail = new StackTrail(['paths', '/users', 'get']);
|
|
211
|
+
* const ref = trail.toStackRef();
|
|
212
|
+
* console.log(ref); // undefined
|
|
213
|
+
* ```
|
|
214
|
+
*/
|
|
11
215
|
toStackRef(): string | undefined;
|
|
216
|
+
/**
|
|
217
|
+
* Removes frame(s) from the end of the trail.
|
|
218
|
+
*
|
|
219
|
+
* @param frame - Single frame string or array of frames to remove
|
|
220
|
+
* @returns This StackTrail instance for chaining
|
|
221
|
+
*
|
|
222
|
+
* @throws {Error} When trying to remove a frame that doesn't match the last frame
|
|
223
|
+
* @throws {Error} When frame is not a string or string array
|
|
224
|
+
*
|
|
225
|
+
* @example Single frame removal
|
|
226
|
+
* ```typescript
|
|
227
|
+
* const trail = new StackTrail(['components', 'schemas', 'User', 'properties']);
|
|
228
|
+
* trail.remove('properties');
|
|
229
|
+
* console.log(trail.toString()); // 'components:schemas:User'
|
|
230
|
+
* ```
|
|
231
|
+
*
|
|
232
|
+
* @example Multiple frame removal
|
|
233
|
+
* ```typescript
|
|
234
|
+
* const trail = new StackTrail(['components', 'schemas', 'User', 'properties', 'name']);
|
|
235
|
+
* trail.remove(['name', 'properties']);
|
|
236
|
+
* console.log(trail.toString()); // 'components:schemas:User'
|
|
237
|
+
* ```
|
|
238
|
+
*/
|
|
12
239
|
remove(frame: string | string[]): StackTrail;
|
|
240
|
+
/**
|
|
241
|
+
* Joins multiple stacks or strings into a single colon-separated string.
|
|
242
|
+
*
|
|
243
|
+
* @param stacks - Array of StackTrail instances or strings to join
|
|
244
|
+
* @returns Joined string with colon separators
|
|
245
|
+
*
|
|
246
|
+
* @example
|
|
247
|
+
* ```typescript
|
|
248
|
+
* const trail1 = new StackTrail(['components', 'schemas']);
|
|
249
|
+
* const trail2 = new StackTrail(['User', 'properties']);
|
|
250
|
+
*
|
|
251
|
+
* const joined = StackTrail.join(trail1, 'separator', trail2);
|
|
252
|
+
* console.log(joined); // 'components:schemas:separator:User:properties'
|
|
253
|
+
* ```
|
|
254
|
+
*/
|
|
13
255
|
static join(...stacks: (StackTrail | string)[]): string;
|
|
256
|
+
/**
|
|
257
|
+
* Parses a colon-separated string into a StackTrail instance.
|
|
258
|
+
*
|
|
259
|
+
* @param value - Colon-separated string to parse
|
|
260
|
+
* @returns New StackTrail instance
|
|
261
|
+
*
|
|
262
|
+
* @throws {Error} When the string contains empty tokens
|
|
263
|
+
*
|
|
264
|
+
* @example
|
|
265
|
+
* ```typescript
|
|
266
|
+
* const trail = StackTrail.parse('components:schemas:User:properties:name');
|
|
267
|
+
* console.log(trail.stackTrail); // ['components', 'schemas', 'User', 'properties', 'name']
|
|
268
|
+
*
|
|
269
|
+
* // Handles escaped colons
|
|
270
|
+
* const escapedTrail = StackTrail.parse('components:schemas:User%3AType');
|
|
271
|
+
* console.log(escapedTrail.stackTrail); // ['components', 'schemas', 'User:Type']
|
|
272
|
+
* ```
|
|
273
|
+
*/
|
|
14
274
|
static parse(value: string): StackTrail;
|
|
275
|
+
/**
|
|
276
|
+
* Converts the trail to JSON representation.
|
|
277
|
+
*
|
|
278
|
+
* Used for serialization in JSON contexts. Returns the same
|
|
279
|
+
* as toString() method.
|
|
280
|
+
*
|
|
281
|
+
* @returns String representation of the trail
|
|
282
|
+
*
|
|
283
|
+
* @example
|
|
284
|
+
* ```typescript
|
|
285
|
+
* const trail = new StackTrail(['components', 'schemas', 'User']);
|
|
286
|
+
* const json = JSON.stringify({ path: trail });
|
|
287
|
+
* console.log(json); // '{"path":"components:schemas:User"}'
|
|
288
|
+
* ```
|
|
289
|
+
*/
|
|
15
290
|
toJSON(): string;
|
|
291
|
+
/**
|
|
292
|
+
* Converts the trail to a colon-separated string representation.
|
|
293
|
+
*
|
|
294
|
+
* Colons within frame names are escaped as '%3A' to avoid conflicts
|
|
295
|
+
* with the separator character.
|
|
296
|
+
*
|
|
297
|
+
* @returns String representation of the trail
|
|
298
|
+
*
|
|
299
|
+
* @example
|
|
300
|
+
* ```typescript
|
|
301
|
+
* const trail = new StackTrail(['components', 'schemas', 'User']);
|
|
302
|
+
* console.log(trail.toString()); // 'components:schemas:User'
|
|
303
|
+
*
|
|
304
|
+
* // With colon in frame name
|
|
305
|
+
* const trailWithColon = new StackTrail(['components', 'schemas', 'User:Type']);
|
|
306
|
+
* console.log(trailWithColon.toString()); // 'components:schemas:User%3AType'
|
|
307
|
+
* ```
|
|
308
|
+
*/
|
|
16
309
|
toString(): string;
|
|
17
310
|
}
|
|
18
311
|
//# sourceMappingURL=StackTrail.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"StackTrail.d.ts","sourceRoot":"","sources":["../../src/context/StackTrail.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAG9B,qBAAa,UAAU;;
|
|
1
|
+
{"version":3,"file":"StackTrail.d.ts","sourceRoot":"","sources":["../../src/context/StackTrail.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAG9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,qBAAa,UAAU;;IAIrB;;;;;;;;;;;;;OAaG;gBACS,KAAK,GAAE,MAAM,EAAO;IAIhC;;;;;;;;;;;;;;OAcG;IACH,KAAK,IAAI,UAAU;IAInB;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,UAAU;IAI9C;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO;IAInC;;;;;;;;;;;OAWG;IACH,IAAI,UAAU,IAAI,MAAM,EAAE,CAEzB;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,UAAU;IAgB5C;;;;;;;;;;;;;;;OAeG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAW9C;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,UAAU,IAAI,MAAM,GAAG,SAAS;IAkBhC;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,UAAU;IAsB5C;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,EAAE,CAAC,UAAU,GAAG,MAAM,CAAC,EAAE,GAAG,MAAM;IAIvD;;;;;;;;;;;;;;;;;OAiBG;IACH,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU;IAYvC;;;;;;;;;;;;;;OAcG;IACH,MAAM,IAAI,MAAM;IAIhB;;;;;;;;;;;;;;;;;OAiBG;IACH,QAAQ,IAAI,MAAM;CAOnB"}
|