@skmtc/core 0.0.792 → 0.0.794

package/esm/dsl/GeneratedValueList.d.ts

@@ -1,9 +1,167 @@
 import type { GeneratedValue } from '../types/GeneratedValue.js';
+/**
+ * A utility class for managing lists of generated values with customizable separators.
+ *
+ * `GeneratedValueList` provides a way to collect multiple generated values and combine
+ * them into a single string with a specified separator. It automatically filters out
+ * empty values to prevent generating unnecessary whitespace or malformed output.
+ *
+ * This class is useful for building lists of code elements like function parameters,
+ * import statements, or any other comma-separated (or otherwise separated) constructs
+ * where individual items might sometimes be empty.
+ *
+ * ## Key Features
+ *
+ * - **Custom Separators**: Support for any string separator (commas, newlines, spaces, etc.)
+ * - **Empty Filtering**: Automatically removes empty values from output
+ * - **Type Safety**: Works with any GeneratedValue type
+ * - **Incremental Building**: Values can be added one at a time
+ *
+ * @example Basic usage with comma separation
+ * ```typescript
+ * import { GeneratedValueList } from '@skmtc/core';
+ *
+ * const parameterList = new GeneratedValueList(', ');
+ * parameterList.add({ toString: () => 'id: string' });
+ * parameterList.add({ toString: () => 'name: string' });
+ * parameterList.add({ toString: () => 'email?: string' });
+ *
+ * console.log(parameterList.toString());
+ * // 'id: string, name: string, email?: string'
+ * ```
+ *
+ * @example With newline separation for code blocks
+ * ```typescript
+ * const codeLines = new GeneratedValueList('\n');
+ * codeLines.add({ toString: () => 'import { User } from "./types";' });
+ * codeLines.add({ toString: () => 'import { validate } from "./utils";' });
+ * codeLines.add({ toString: () => '' }); // Empty line will be filtered
+ * codeLines.add({ toString: () => 'export class UserService {' });
+ * codeLines.add({ toString: () => '  // Implementation' });
+ * codeLines.add({ toString: () => '}' });
+ *
+ * console.log(codeLines.toString());
+ * // import { User } from "./types";
+ * // import { validate } from "./utils";
+ * // export class UserService {
+ * //   // Implementation
+ * // }
+ * ```
+ *
+ * @example Empty value filtering
+ * ```typescript
+ * const mixedList = new GeneratedValueList(' | ');
+ * mixedList.add({ toString: () => "'active'" });
+ * mixedList.add({ toString: () => '' }); // This will be filtered out
+ * mixedList.add({ toString: () => "'inactive'" });
+ * mixedList.add({ toString: () => "'pending'" });
+ *
+ * console.log(mixedList.toString());
+ * // "'active' | 'inactive' | 'pending'"
+ * ```
+ *
+ * @example Using in code generation
+ * ```typescript
+ * class InterfaceGenerator {
+ *   generateInterface(name: string, properties: Array<{name: string, type: string}>) {
+ *     const propertyList = new GeneratedValueList(';\n  ');
+ *
+ *     properties.forEach(prop => {
+ *       if (prop.type) { // Only add properties that have types
+ *         propertyList.add({
+ *           toString: () => `${prop.name}: ${prop.type}`
+ *         });
+ *       }
+ *     });
+ *
+ *     return `interface ${name} {\n  ${propertyList.toString()};\n}`;
+ *   }
+ * }
+ *
+ * const generator = new InterfaceGenerator();
+ * const userInterface = generator.generateInterface('User', [
+ *   { name: 'id', type: 'string' },
+ *   { name: 'name', type: 'string' },
+ *   { name: 'invalid', type: '' }, // Will be filtered out
+ *   { name: 'email', type: 'string | null' }
+ * ]);
+ *
+ * console.log(userInterface);
+ * // interface User {
+ * //   id: string;
+ * //   name: string;
+ * //   email: string | null;
+ * // }
+ * ```
+ */
 export declare class GeneratedValueList {
+    /** The separator string used to join values */
     separator: string;
+    /** Internal array of generated values */
     private items;
+    /**
+     * Creates a new GeneratedValueList with the specified separator.
+     *
+     * @param separator - The string to use when joining values (e.g., ', ', '\n', ' | ')
+     *
+     * @example
+     * ```typescript
+     * // For comma-separated lists
+     * const commaList = new GeneratedValueList(', ');
+     *
+     * // For line-separated content
+     * const lineList = new GeneratedValueList('\n');
+     *
+     * // For union types
+     * const unionList = new GeneratedValueList(' | ');
+     * ```
+     */
     constructor(separator: string);
+    /**
+     * Adds a generated value to the list.
+     *
+     * The value will be included in the output string when `toString()` is called,
+     * unless the value's `toString()` method returns an empty string, in which case
+     * it will be automatically filtered out.
+     *
+     * @param str - The generated value to add to the list
+     *
+     * @example
+     * ```typescript
+     * const list = new GeneratedValueList(', ');
+     *
+     * // Add simple values
+     * list.add({ toString: () => 'value1' });
+     * list.add({ toString: () => 'value2' });
+     *
+     * // Add conditional values
+     * const conditionalValue = shouldInclude ? 'conditional' : '';
+     * list.add({ toString: () => conditionalValue });
+     *
+     * console.log(list.toString()); // 'value1, value2' (conditional filtered if empty)
+     * ```
+     */
     add(str: GeneratedValue): void;
+    /**
+     * Converts the list to a string representation with values joined by the separator.
+     *
+     * This method processes all added values by calling their `toString()` methods,
+     * filters out any empty strings (matching the {@link EMPTY} constant), and joins
+     * the remaining values with the configured separator.
+     *
+     * @returns The joined string representation of all non-empty values
+     *
+     * @example
+     * ```typescript
+     * const list = new GeneratedValueList(' -> ');
+     * list.add({ toString: () => 'start' });
+     * list.add({ toString: () => '' }); // Will be filtered out
+     * list.add({ toString: () => 'middle' });
+     * list.add({ toString: () => 'end' });
+     *
+     * console.log(list.toString()); // 'start -> middle -> end'
+     * ```
+     */
     toString(): string;
 }
 //# sourceMappingURL=GeneratedValueList.d.ts.map

package/esm/dsl/GeneratedValueList.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"GeneratedValueList.d.ts","sourceRoot":"","sources":["../../src/dsl/GeneratedValueList.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAGhE,qBAAa,kBAAkB;IAC7B,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,CAAC,KAAK,CAAuB;gBAExB,SAAS,EAAE,MAAM;IAI7B,GAAG,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IAI9B,QAAQ,IAAI,MAAM;CAMnB"}
+{"version":3,"file":"GeneratedValueList.d.ts","sourceRoot":"","sources":["../../src/dsl/GeneratedValueList.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAGhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8FG;AACH,qBAAa,kBAAkB;IAC7B,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAA;IAEjB,yCAAyC;IACzC,OAAO,CAAC,KAAK,CAAuB;IAEpC;;;;;;;;;;;;;;;;OAgBG;gBACS,SAAS,EAAE,MAAM;IAI7B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,GAAG,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI;IAI9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,QAAQ,IAAI,MAAM;CAMnB"}

package/esm/dsl/GeneratedValueList.js

@@ -1,12 +1,126 @@
 import { EMPTY } from './constants.js';
+/**
+ * A utility class for managing lists of generated values with customizable separators.
+ *
+ * `GeneratedValueList` provides a way to collect multiple generated values and combine
+ * them into a single string with a specified separator. It automatically filters out
+ * empty values to prevent generating unnecessary whitespace or malformed output.
+ *
+ * This class is useful for building lists of code elements like function parameters,
+ * import statements, or any other comma-separated (or otherwise separated) constructs
+ * where individual items might sometimes be empty.
+ *
+ * ## Key Features
+ *
+ * - **Custom Separators**: Support for any string separator (commas, newlines, spaces, etc.)
+ * - **Empty Filtering**: Automatically removes empty values from output
+ * - **Type Safety**: Works with any GeneratedValue type
+ * - **Incremental Building**: Values can be added one at a time
+ *
+ * @example Basic usage with comma separation
+ * ```typescript
+ * import { GeneratedValueList } from '@skmtc/core';
+ *
+ * const parameterList = new GeneratedValueList(', ');
+ * parameterList.add({ toString: () => 'id: string' });
+ * parameterList.add({ toString: () => 'name: string' });
+ * parameterList.add({ toString: () => 'email?: string' });
+ *
+ * console.log(parameterList.toString());
+ * // 'id: string, name: string, email?: string'
+ * ```
+ *
+ * @example With newline separation for code blocks
+ * ```typescript
+ * const codeLines = new GeneratedValueList('\n');
+ * codeLines.add({ toString: () => 'import { User } from "./types";' });
+ * codeLines.add({ toString: () => 'import { validate } from "./utils";' });
+ * codeLines.add({ toString: () => '' }); // Empty line will be filtered
+ * codeLines.add({ toString: () => 'export class UserService {' });
+ * codeLines.add({ toString: () => '  // Implementation' });
+ * codeLines.add({ toString: () => '}' });
+ *
+ * console.log(codeLines.toString());
+ * // import { User } from "./types";
+ * // import { validate } from "./utils";
+ * // export class UserService {
+ * //   // Implementation
+ * // }
+ * ```
+ *
+ * @example Empty value filtering
+ * ```typescript
+ * const mixedList = new GeneratedValueList(' | ');
+ * mixedList.add({ toString: () => "'active'" });
+ * mixedList.add({ toString: () => '' }); // This will be filtered out
+ * mixedList.add({ toString: () => "'inactive'" });
+ * mixedList.add({ toString: () => "'pending'" });
+ *
+ * console.log(mixedList.toString());
+ * // "'active' | 'inactive' | 'pending'"
+ * ```
+ *
+ * @example Using in code generation
+ * ```typescript
+ * class InterfaceGenerator {
+ *   generateInterface(name: string, properties: Array<{name: string, type: string}>) {
+ *     const propertyList = new GeneratedValueList(';\n  ');
+ *
+ *     properties.forEach(prop => {
+ *       if (prop.type) { // Only add properties that have types
+ *         propertyList.add({
+ *           toString: () => `${prop.name}: ${prop.type}`
+ *         });
+ *       }
+ *     });
+ *
+ *     return `interface ${name} {\n  ${propertyList.toString()};\n}`;
+ *   }
+ * }
+ *
+ * const generator = new InterfaceGenerator();
+ * const userInterface = generator.generateInterface('User', [
+ *   { name: 'id', type: 'string' },
+ *   { name: 'name', type: 'string' },
+ *   { name: 'invalid', type: '' }, // Will be filtered out
+ *   { name: 'email', type: 'string | null' }
+ * ]);
+ *
+ * console.log(userInterface);
+ * // interface User {
+ * //   id: string;
+ * //   name: string;
+ * //   email: string | null;
+ * // }
+ * ```
+ */
 export class GeneratedValueList {
+    /**
+     * Creates a new GeneratedValueList with the specified separator.
+     *
+     * @param separator - The string to use when joining values (e.g., ', ', '\n', ' | ')
+     *
+     * @example
+     * ```typescript
+     * // For comma-separated lists
+     * const commaList = new GeneratedValueList(', ');
+     *
+     * // For line-separated content
+     * const lineList = new GeneratedValueList('\n');
+     *
+     * // For union types
+     * const unionList = new GeneratedValueList(' | ');
+     * ```
+     */
     constructor(separator) {
+        /** The separator string used to join values */
         Object.defineProperty(this, "separator", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Internal array of generated values */
         Object.defineProperty(this, "items", {
             enumerable: true,
             configurable: true,
@@ -15,9 +129,53 @@ export class GeneratedValueList {
         });
         this.separator = separator;
     }
+    /**
+     * Adds a generated value to the list.
+     *
+     * The value will be included in the output string when `toString()` is called,
+     * unless the value's `toString()` method returns an empty string, in which case
+     * it will be automatically filtered out.
+     *
+     * @param str - The generated value to add to the list
+     *
+     * @example
+     * ```typescript
+     * const list = new GeneratedValueList(', ');
+     *
+     * // Add simple values
+     * list.add({ toString: () => 'value1' });
+     * list.add({ toString: () => 'value2' });
+     *
+     * // Add conditional values
+     * const conditionalValue = shouldInclude ? 'conditional' : '';
+     * list.add({ toString: () => conditionalValue });
+     *
+     * console.log(list.toString()); // 'value1, value2' (conditional filtered if empty)
+     * ```
+     */
     add(str) {
         this.items.push(str);
     }
+    /**
+     * Converts the list to a string representation with values joined by the separator.
+     *
+     * This method processes all added values by calling their `toString()` methods,
+     * filters out any empty strings (matching the {@link EMPTY} constant), and joins
+     * the remaining values with the configured separator.
+     *
+     * @returns The joined string representation of all non-empty values
+     *
+     * @example
+     * ```typescript
+     * const list = new GeneratedValueList(' -> ');
+     * list.add({ toString: () => 'start' });
+     * list.add({ toString: () => '' }); // Will be filtered out
+     * list.add({ toString: () => 'middle' });
+     * list.add({ toString: () => 'end' });
+     *
+     * console.log(list.toString()); // 'start -> middle -> end'
+     * ```
+     */
     toString() {
         return this.items
             .map(item => item.toString())

package/esm/dsl/Stringable.d.ts

@@ -1,5 +1,81 @@
+/**
+ * Represents any object that can be converted to a string representation.
+ *
+ * The `Stringable` interface is a fundamental type used throughout the SKMTC DSL
+ * system to ensure that objects can be converted to strings for code generation.
+ * This interface matches JavaScript's built-in `toString()` contract and is used
+ * extensively by the {@link List} class and other string-building utilities.
+ *
+ * ## Usage in SKMTC
+ *
+ * This type is used as a constraint in generic classes and functions that need
+ * to output string representations. It allows for type-safe string building
+ * while accommodating both primitive types and custom objects.
+ *
+ * @example Built-in types are stringable
+ * ```typescript
+ * import type { Stringable } from '@skmtc/core';
+ *
+ * // All these types implement Stringable
+ * const str: Stringable = 'hello';        // string
+ * const num: Stringable = 42;             // number
+ * const bool: Stringable = true;          // boolean
+ * const obj: Stringable = { toString: () => 'custom' }; // custom object
+ * ```
+ *
+ * @example Custom classes implementing Stringable
+ * ```typescript
+ * class CodeBlock implements Stringable {
+ *   constructor(private code: string) {}
+ *
+ *   toString(): string {
+ *     return `{\n  ${this.code}\n}`;
+ *   }
+ * }
+ *
+ * const block = new CodeBlock('console.log("hello");');
+ * console.log(block.toString());
+ * // {
+ * //   console.log("hello");
+ * // }
+ * ```
+ *
+ * @example Using with List class
+ * ```typescript
+ * import { List } from '@skmtc/core';
+ *
+ * // List accepts any Stringable items
+ * const stringables: Stringable[] = [
+ *   'string literal',
+ *   42,
+ *   true,
+ *   { toString: () => 'custom object' },
+ *   new CodeBlock('return value;')
+ * ];
+ *
+ * const list = new List(stringables);
+ * console.log(list.toString());
+ * // string literal, 42, true, custom object, {
+ * //   return value;
+ * // }
+ * ```
+ *
+ * @example Type constraints in generics
+ * ```typescript
+ * function joinWithCommas<T extends Stringable>(items: T[]): string {
+ *   return items.map(item => item.toString()).join(', ');
+ * }
+ *
+ * const result = joinWithCommas([1, 2, 3]); // "1, 2, 3"
+ * const identifiers = joinWithCommas([
+ *   Identifier.createVariable('user'),
+ *   Identifier.createType('User')
+ * ]); // "user, User"
+ * ```
+ */
 import "../_dnt.polyfills.js";
 export type Stringable = {
+    /** Converts the object to its string representation */
     toString: () => string;
 };
 //# sourceMappingURL=Stringable.d.ts.map

package/esm/dsl/Stringable.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Stringable.d.ts","sourceRoot":"","sources":["../../src/dsl/Stringable.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,MAAM,MAAM,CAAA;CACvB,CAAA"}
+{"version":3,"file":"Stringable.d.ts","sourceRoot":"","sources":["../../src/dsl/Stringable.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0EG;AACH,OAAO,sBAAsB,CAAC;AAE9B,MAAM,MAAM,UAAU,GAAG;IACvB,uDAAuD;IACvD,QAAQ,EAAE,MAAM,MAAM,CAAA;CACvB,CAAA"}

package/esm/dsl/Stringable.js

@@ -1 +1,76 @@
+/**
+ * Represents any object that can be converted to a string representation.
+ *
+ * The `Stringable` interface is a fundamental type used throughout the SKMTC DSL
+ * system to ensure that objects can be converted to strings for code generation.
+ * This interface matches JavaScript's built-in `toString()` contract and is used
+ * extensively by the {@link List} class and other string-building utilities.
+ *
+ * ## Usage in SKMTC
+ *
+ * This type is used as a constraint in generic classes and functions that need
+ * to output string representations. It allows for type-safe string building
+ * while accommodating both primitive types and custom objects.
+ *
+ * @example Built-in types are stringable
+ * ```typescript
+ * import type { Stringable } from '@skmtc/core';
+ *
+ * // All these types implement Stringable
+ * const str: Stringable = 'hello';        // string
+ * const num: Stringable = 42;             // number
+ * const bool: Stringable = true;          // boolean
+ * const obj: Stringable = { toString: () => 'custom' }; // custom object
+ * ```
+ *
+ * @example Custom classes implementing Stringable
+ * ```typescript
+ * class CodeBlock implements Stringable {
+ *   constructor(private code: string) {}
+ *
+ *   toString(): string {
+ *     return `{\n  ${this.code}\n}`;
+ *   }
+ * }
+ *
+ * const block = new CodeBlock('console.log("hello");');
+ * console.log(block.toString());
+ * // {
+ * //   console.log("hello");
+ * // }
+ * ```
+ *
+ * @example Using with List class
+ * ```typescript
+ * import { List } from '@skmtc/core';
+ *
+ * // List accepts any Stringable items
+ * const stringables: Stringable[] = [
+ *   'string literal',
+ *   42,
+ *   true,
+ *   { toString: () => 'custom object' },
+ *   new CodeBlock('return value;')
+ * ];
+ *
+ * const list = new List(stringables);
+ * console.log(list.toString());
+ * // string literal, 42, true, custom object, {
+ * //   return value;
+ * // }
+ * ```
+ *
+ * @example Type constraints in generics
+ * ```typescript
+ * function joinWithCommas<T extends Stringable>(items: T[]): string {
+ *   return items.map(item => item.toString()).join(', ');
+ * }
+ *
+ * const result = joinWithCommas([1, 2, 3]); // "1, 2, 3"
+ * const identifiers = joinWithCommas([
+ *   Identifier.createVariable('user'),
+ *   Identifier.createType('User')
+ * ]); // "user, User"
+ * ```
+ */
 import "../_dnt.polyfills.js";