@skmtc/core 0.0.794 → 0.0.795

package/script/context/StackTrail.js

@@ -15,23 +15,190 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.StackTrail = void 0;
 require("../_dnt.polyfills.js");
 const Components_js_1 = require("../oas/components/Components.js");
+/**
+ * Represents a stack-based trail for tracking document traversal in OpenAPI processing.
+ *
+ * The `StackTrail` class maintains a stack of string frames that represent the current
+ * path through an OpenAPI document structure. It's used throughout the SKMTC pipeline
+ * for tracking context during parsing, generating, and debugging schema processing.
+ *
+ * This class is essential for error reporting, debugging, and maintaining context
+ * when processing nested OpenAPI structures like schemas, operations, and components.
+ *
+ * ## Key Features
+ *
+ * - **Path Tracking**: Maintains a trail of traversed document elements
+ * - **Context Preservation**: Preserves parsing context for error reporting
+ * - **Stack Operations**: Supports push, pop, clone, and manipulation operations
+ * - **Reference Resolution**: Can generate OpenAPI reference strings from trails
+ * - **Serialization**: Supports string serialization and parsing for persistence
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { StackTrail } from '@skmtc/core';
+ *
+ * // Start with empty trail
+ * const trail = new StackTrail();
+ *
+ * // Build a path through document structure
+ * trail.append('components')
+ *      .append('schemas')
+ *      .append('User')
+ *      .append('properties')
+ *      .append('name');
+ *
+ * console.log(trail.toString()); // 'components:schemas:User:properties:name'
+ * ```
+ *
+ * @example Schema reference generation
+ * ```typescript
+ * const schemaTrail = new StackTrail(['components', 'schemas', 'User']);
+ * const ref = schemaTrail.toStackRef();
+ * console.log(ref); // '#/components/schemas/User'
+ * ```
+ *
+ * @example Error context tracking
+ * ```typescript
+ * class SchemaProcessor {
+ *   processSchema(schema: OasSchema, trail: StackTrail) {
+ *     try {
+ *       // Process schema logic
+ *       return this.transformSchema(schema);
+ *     } catch (error) {
+ *       throw new Error(`Error at ${trail.toString()}: ${error.message}`);
+ *       // Error at components:schemas:User:properties:email: Invalid format
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Cloning and manipulation
+ * ```typescript
+ * const baseTrail = new StackTrail(['components', 'schemas']);
+ *
+ * // Clone for processing different schemas
+ * const userTrail = baseTrail.clone().append('User');
+ * const productTrail = baseTrail.clone().append('Product');
+ *
+ * console.log(userTrail.toString());    // 'components:schemas:User'
+ * console.log(productTrail.toString()); // 'components:schemas:Product'
+ * console.log(baseTrail.toString());    // 'components:schemas' (unchanged)
+ * ```
+ */
 class StackTrail {
+    /**
+     * Creates a new StackTrail instance.
+     *
+     * @param stack - Initial stack frames (defaults to empty array)
+     *
+     * @example
+     * ```typescript
+     * // Empty trail
+     * const trail1 = new StackTrail();
+     *
+     * // Pre-populated trail
+     * const trail2 = new StackTrail(['components', 'schemas', 'User']);
+     * ```
+     */
     constructor(stack = []) {
+        /** Internal stack of traversal frames */
         _StackTrail_stack.set(this, void 0);
         __classPrivateFieldSet(this, _StackTrail_stack, stack, "f");
     }
+    /**
+     * Creates a shallow copy of the stack trail.
+     *
+     * @returns A new StackTrail instance with copied frames
+     *
+     * @example
+     * ```typescript
+     * const original = new StackTrail(['components', 'schemas']);
+     * const copy = original.clone();
+     *
+     * copy.append('User');
+     * console.log(original.toString()); // 'components:schemas'
+     * console.log(copy.toString());     // 'components:schemas:User'
+     * ```
+     */
     clone() {
         return new StackTrail([...__classPrivateFieldGet(this, _StackTrail_stack, "f")]);
     }
+    /**
+     * Creates a new trail from a slice of the current trail.
+     *
+     * @param start - Starting index (inclusive)
+     * @param end - Ending index (exclusive, optional)
+     * @returns A new StackTrail with sliced frames
+     *
+     * @example
+     * ```typescript
+     * const trail = new StackTrail(['a', 'b', 'c', 'd', 'e']);
+     *
+     * const slice1 = trail.slice(1, 3);
+     * console.log(slice1.toString()); // 'b:c'
+     *
+     * const slice2 = trail.slice(2);
+     * console.log(slice2.toString()); // 'c:d:e'
+     * ```
+     */
     slice(start, end) {
         return new StackTrail(__classPrivateFieldGet(this, _StackTrail_stack, "f").slice(start, end));
     }
+    /**
+     * Checks if all specified frames exist in the trail.
+     *
+     * @param frames - Array of frames to check for
+     * @returns True if all frames are present in the trail
+     *
+     * @example
+     * ```typescript
+     * const trail = new StackTrail(['components', 'schemas', 'User', 'properties']);
+     *
+     * console.log(trail.includes(['schemas', 'User'])); // true
+     * console.log(trail.includes(['schemas', 'Product'])); // false
+     * console.log(trail.includes(['components'])); // true
+     * ```
+     */
     includes(frames) {
         return frames.every(frame => __classPrivateFieldGet(this, _StackTrail_stack, "f").includes(frame));
     }
+    /**
+     * Gets a copy of the current stack frames.
+     *
+     * @returns Array of stack frames in order
+     *
+     * @example
+     * ```typescript
+     * const trail = new StackTrail(['components', 'schemas', 'User']);
+     * const frames = trail.stackTrail;
+     * console.log(frames); // ['components', 'schemas', 'User']
+     * ```
+     */
     get stackTrail() {
         return __classPrivateFieldGet(this, _StackTrail_stack, "f");
     }
+    /**
+     * Appends frame(s) to the end of the trail.
+     *
+     * @param frame - Single frame string or array of frames to append
+     * @returns This StackTrail instance for chaining
+     *
+     * @throws {Error} When frame is not a string or string array
+     *
+     * @example Single frame
+     * ```typescript
+     * const trail = new StackTrail(['components']);
+     * trail.append('schemas').append('User');
+     * console.log(trail.toString()); // 'components:schemas:User'
+     * ```
+     *
+     * @example Multiple frames
+     * ```typescript
+     * const trail = new StackTrail();
+     * trail.append(['components', 'schemas', 'User']);
+     * console.log(trail.toString()); // 'components:schemas:User'
+     * ```
+     */
     append(frame) {
         if (typeof frame === 'string') {
             __classPrivateFieldGet(this, _StackTrail_stack, "f").push(frame);
@@ -43,6 +210,22 @@ class StackTrail {
         }
         throw new Error(`Unexpected stack frame: ${frame}`);
     }
+    /**
+     * Gets the parent name of a property frame.
+     *
+     * This method is specifically designed to find parent object names
+     * for property trails in schema processing.
+     *
+     * @param frame - The frame name to find the parent of
+     * @returns Parent name if found, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * const trail = new StackTrail(['components', 'schemas', 'User', 'properties', 'email']);
+     * const parent = trail.getParentOf('email');
+     * console.log(parent); // 'User'
+     * ```
+     */
     getParentOf(frame) {
         const lastItemIndex = this.stackTrail.length - 1;
         if (this.stackTrail?.[lastItemIndex] === frame &&
@@ -51,6 +234,28 @@ class StackTrail {
             return typeof parentName === 'string' ? parentName : undefined;
         }
     }
+    /**
+     * Converts the trail to an OpenAPI reference string if applicable.
+     *
+     * Only trails that represent valid OpenAPI component references
+     * (starting with 'components') can be converted to reference strings.
+     *
+     * @returns OpenAPI reference string or undefined if not a valid reference trail
+     *
+     * @example Valid reference trail
+     * ```typescript
+     * const trail = new StackTrail(['components', 'schemas', 'User']);
+     * const ref = trail.toStackRef();
+     * console.log(ref); // '#/components/schemas/User'
+     * ```
+     *
+     * @example Invalid trail
+     * ```typescript
+     * const trail = new StackTrail(['paths', '/users', 'get']);
+     * const ref = trail.toStackRef();
+     * console.log(ref); // undefined
+     * ```
+     */
     toStackRef() {
         const [first, second, third] = this.stackTrail;
         if (first !== 'components') {
@@ -64,6 +269,29 @@ class StackTrail {
         }
         return `#/${first}/${second}/${third}`;
     }
+    /**
+     * Removes frame(s) from the end of the trail.
+     *
+     * @param frame - Single frame string or array of frames to remove
+     * @returns This StackTrail instance for chaining
+     *
+     * @throws {Error} When trying to remove a frame that doesn't match the last frame
+     * @throws {Error} When frame is not a string or string array
+     *
+     * @example Single frame removal
+     * ```typescript
+     * const trail = new StackTrail(['components', 'schemas', 'User', 'properties']);
+     * trail.remove('properties');
+     * console.log(trail.toString()); // 'components:schemas:User'
+     * ```
+     *
+     * @example Multiple frame removal
+     * ```typescript
+     * const trail = new StackTrail(['components', 'schemas', 'User', 'properties', 'name']);
+     * trail.remove(['name', 'properties']);
+     * console.log(trail.toString()); // 'components:schemas:User'
+     * ```
+     */
     remove(frame) {
         if (typeof frame === 'string') {
             const lastItem = __classPrivateFieldGet(this, _StackTrail_stack, "f")[__classPrivateFieldGet(this, _StackTrail_stack, "f").length - 1];
@@ -79,9 +307,42 @@ class StackTrail {
         }
         throw new Error(`Unexpected stack frame: ${frame}`);
     }
+    /**
+     * Joins multiple stacks or strings into a single colon-separated string.
+     *
+     * @param stacks - Array of StackTrail instances or strings to join
+     * @returns Joined string with colon separators
+     *
+     * @example
+     * ```typescript
+     * const trail1 = new StackTrail(['components', 'schemas']);
+     * const trail2 = new StackTrail(['User', 'properties']);
+     *
+     * const joined = StackTrail.join(trail1, 'separator', trail2);
+     * console.log(joined); // 'components:schemas:separator:User:properties'
+     * ```
+     */
     static join(...stacks) {
         return stacks.map(stack => stack.toString()).join(':');
     }
+    /**
+     * Parses a colon-separated string into a StackTrail instance.
+     *
+     * @param value - Colon-separated string to parse
+     * @returns New StackTrail instance
+     *
+     * @throws {Error} When the string contains empty tokens
+     *
+     * @example
+     * ```typescript
+     * const trail = StackTrail.parse('components:schemas:User:properties:name');
+     * console.log(trail.stackTrail); // ['components', 'schemas', 'User', 'properties', 'name']
+     *
+     * // Handles escaped colons
+     * const escapedTrail = StackTrail.parse('components:schemas:User%3AType');
+     * console.log(escapedTrail.stackTrail); // ['components', 'schemas', 'User:Type']
+     * ```
+     */
     static parse(value) {
         const stack = value.split(':').map(item => {
             if (!item) {
@@ -91,9 +352,42 @@ class StackTrail {
         });
         return new StackTrail(stack);
     }
+    /**
+     * Converts the trail to JSON representation.
+     *
+     * Used for serialization in JSON contexts. Returns the same
+     * as toString() method.
+     *
+     * @returns String representation of the trail
+     *
+     * @example
+     * ```typescript
+     * const trail = new StackTrail(['components', 'schemas', 'User']);
+     * const json = JSON.stringify({ path: trail });
+     * console.log(json); // '{"path":"components:schemas:User"}'
+     * ```
+     */
     toJSON() {
         return this.toString();
     }
+    /**
+     * Converts the trail to a colon-separated string representation.
+     *
+     * Colons within frame names are escaped as '%3A' to avoid conflicts
+     * with the separator character.
+     *
+     * @returns String representation of the trail
+     *
+     * @example
+     * ```typescript
+     * const trail = new StackTrail(['components', 'schemas', 'User']);
+     * console.log(trail.toString()); // 'components:schemas:User'
+     *
+     * // With colon in frame name
+     * const trailWithColon = new StackTrail(['components', 'schemas', 'User:Type']);
+     * console.log(trailWithColon.toString()); // 'components:schemas:User%3AType'
+     * ```
+     */
     toString() {
         return __classPrivateFieldGet(this, _StackTrail_stack, "f")
             .map(item => {

package/script/types/Modifiers.d.ts

@@ -1,6 +1,74 @@
+/**
+ * Type modifiers used throughout the SKMTC type system.
+ *
+ * `Modifiers` represent additional metadata and constraints that can be
+ * applied to type system values. These modifiers affect how types are
+ * generated and used in the target language output.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { Modifiers } from '@skmtc/core';
+ *
+ * const stringModifiers: Modifiers = {
+ *   required: true,
+ *   nullable: false,
+ *   description: 'User email address'
+ * };
+ *
+ * const optionalModifiers: Modifiers = {
+ *   required: false,
+ *   nullable: true,
+ *   description: 'Optional user profile image URL'
+ * };
+ * ```
+ *
+ * @example In type system values
+ * ```typescript
+ * const emailField: TypeSystemString = {
+ *   type: 'string',
+ *   format: 'email',
+ *   enums: undefined,
+ *   modifiers: {
+ *     required: true,
+ *     nullable: false,
+ *     description: 'Valid email address for account registration'
+ *   }
+ * };
+ *
+ * const optionalNote: TypeSystemString = {
+ *   type: 'string',
+ *   format: undefined,
+ *   enums: undefined,
+ *   modifiers: {
+ *     required: false,
+ *     nullable: true,
+ *     description: 'Optional user note or comment'
+ *   }
+ * };
+ * ```
+ *
+ * @example TypeScript generation
+ * ```typescript
+ * function generateTypeScript(type: TypeSystemValue): string {
+ *   const baseType = generateBaseType(type);
+ *   const optional = !type.modifiers.required ? '?' : '';
+ *   const nullable = type.modifiers.nullable ? ' | null' : '';
+ *
+ *   return `${baseType}${nullable}${optional}`;
+ * }
+ *
+ * // Required non-null string: 'string'
+ * // Optional non-null string: 'string?'
+ * // Required nullable string: 'string | null'
+ * // Optional nullable string: 'string | null?'
+ * ```
+ */
 export type Modifiers = {
+    /** Whether the field is required (affects optional markers in generated types) */
     required?: boolean;
+    /** Human-readable description of the field (used in documentation) */
     description?: string;
+    /** Whether the field can be null (affects null union types) */
     nullable?: boolean;
 };
 //# sourceMappingURL=Modifiers.d.ts.map

package/script/types/Modifiers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Modifiers.d.ts","sourceRoot":"","sources":["../../src/types/Modifiers.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA"}
+{"version":3,"file":"Modifiers.d.ts","sourceRoot":"","sources":["../../src/types/Modifiers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA"}