@skmtc/core 0.0.792 → 0.0.793

package/esm/typescript/withDescription.js

@@ -1,3 +1,122 @@
+/**
+ * Wraps a value with a JSDoc comment if a description is provided.
+ *
+ * This utility function is used throughout the SKMTC code generation system to
+ * add JSDoc documentation comments to generated TypeScript code. If a description
+ * is provided, it formats it as a single-line JSDoc comment above the value.
+ * If no description is provided, the value is returned unchanged.
+ *
+ * @param value - The code value to potentially wrap with documentation
+ * @param modifiers - Modifiers object containing optional description
+ * @param modifiers.description - Optional description text for the JSDoc comment
+ * @returns The value with JSDoc comment prepended if description exists, otherwise just the value
+ *
+ * @example With description
+ * ```typescript
+ * import { withDescription } from '@skmtc/core';
+ *
+ * const result = withDescription(
+ *   'export const API_URL = "https://api.example.com";',
+ *   { description: 'Base URL for all API requests' }
+ * );
+ *
+ * console.log(result);
+ * // /** Base URL for all API requests *\/
+ * // export const API_URL = "https://api.example.com";
+ * ```
+ *
+ * @example Without description
+ * ```typescript
+ * const result = withDescription(
+ *   'export const API_URL = "https://api.example.com";',
+ *   { description: undefined }
+ * );
+ *
+ * console.log(result);
+ * // export const API_URL = "https://api.example.com";
+ * ```
+ *
+ * @example Using with Definition class
+ * ```typescript
+ * class ModelGenerator {
+ *   generateInterface(name: string, description?: string) {
+ *     const interfaceCode = `interface ${name} {
+ *   id: string;
+ *   name: string;
+ * }`;
+ *
+ *     return withDescription(interfaceCode, { description });
+ *   }
+ * }
+ *
+ * const generator = new ModelGenerator();
+ * const documented = generator.generateInterface('User', 'Represents a user in the system');
+ *
+ * console.log(documented);
+ * // /** Represents a user in the system *\/
+ * // interface User {
+ * //   id: string;
+ * //   name: string;
+ * // }
+ * ```
+ *
+ * @example Integration with generated definitions
+ * ```typescript
+ * import { Definition, Identifier, withDescription } from '@skmtc/core';
+ *
+ * class DocumentedGenerator {
+ *   createDefinition(name: string, value: string, docs?: string) {
+ *     return new Definition({
+ *       context: this.context,
+ *       identifier: Identifier.createVariable(name),
+ *       description: docs, // This gets processed by withDescription internally
+ *       value: {
+ *         generatorKey: 'documented',
+ *         content: value
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * @example Complex documentation
+ * ```typescript
+ * const complexDoc = withDescription(
+ *   `export type Status = 'active' | 'inactive' | 'pending';`,
+ *   {
+ *     description: 'User account status - active users can access all features'
+ *   }
+ * );
+ *
+ * console.log(complexDoc);
+ * // /** User account status - active users can access all features *\/
+ * // export type Status = 'active' | 'inactive' | 'pending';
+ * ```
+ *
+ * @example Conditional documentation
+ * ```typescript
+ * function generateWithOptionalDocs(
+ *   code: string,
+ *   includeDescription: boolean
+ * ) {
+ *   return withDescription(code, {
+ *     description: includeDescription
+ *       ? 'This is an auto-generated definition'
+ *       : undefined
+ *   });
+ * }
+ *
+ * const withDocs = generateWithOptionalDocs('export const VALUE = 42;', true);
+ * const withoutDocs = generateWithOptionalDocs('export const VALUE = 42;', false);
+ *
+ * console.log(withDocs);
+ * // /** This is an auto-generated definition *\/
+ * // export const VALUE = 42;
+ *
+ * console.log(withoutDocs);
+ * // export const VALUE = 42;
+ * ```
+ */
 export const withDescription = (value, { description }) => {
     return description ? `/** ${description} */\n${value}` : `${value}`;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skmtc/core",
-  "version": "0.0.792",
+  "version": "0.0.793",
   "repository": {
     "type": "git",
     "url": "https://github.com/skmtc/skmtc.git"

package/script/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/script/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/script/dsl/GeneratedValueList.js

@@ -2,14 +2,128 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GeneratedValueList = void 0;
 const constants_js_1 = require("./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;
+ * // }
+ * ```
+ */
 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,
@@ -18,9 +132,53 @@ 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/script/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/script/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/script/dsl/Stringable.js

@@ -1,3 +1,78 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * 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"
+ * ```
+ */
 require("../_dnt.polyfills.js");