@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.
@@ -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,6 +1,6 @@
1
1
  {
2
2
  "name": "@skmtc/core",
3
- "version": "0.0.794",
3
+ "version": "0.0.795",
4
4
  "repository": {
5
5
  "type": "git",
6
6
  "url": "https://github.com/skmtc/skmtc.git"
@@ -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;;gBAGT,KAAK,GAAE,MAAM,EAAO;IAIhC,KAAK,IAAI,UAAU;IAInB,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,UAAU;IAI9C,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO;IAInC,IAAI,UAAU,IAAI,MAAM,EAAE,CAEzB;IAED,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,UAAU;IAgB5C,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAW9C,UAAU,IAAI,MAAM,GAAG,SAAS;IAkBhC,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,UAAU;IAsB5C,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,EAAE,CAAC,UAAU,GAAG,MAAM,CAAC,EAAE,GAAG,MAAM;IAIvD,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU;IAYvC,MAAM,IAAI,MAAM;IAIhB,QAAQ,IAAI,MAAM;CAOnB"}
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"}