@skmtc/core 0.0.786 → 0.0.788

package/esm/dsl/Definition.d.ts

@@ -2,19 +2,218 @@ import type { GenerateContext } from '../context/GenerateContext.js';
 import type { Identifier } from './Identifier.js';
 import { ContentBase } from './ContentBase.js';
 import type { GeneratedValue } from '../types/GeneratedValue.js';
+/**
+ * Constructor arguments for {@link Definition}.
+ *
+ * @template V - The type of generated value this definition contains
+ */
 type ConstructorArgs<V extends GeneratedValue> = {
+    /** The generation context providing pipeline access */
     context: GenerateContext;
+    /** Optional description for JSDoc comments */
     description?: string;
+    /** The identifier for this definition */
     identifier: Identifier;
+    /** The generated value content */
     value: V;
+    /** Whether to skip the export keyword */
     noExport?: boolean;
 };
+/**
+ * Represents a complete code definition in the SKMTC DSL system.
+ *
+ * The `Definition` class is the primary output unit of generators, representing
+ * a complete piece of generated code (like an interface, function, or constant).
+ * It combines an identifier, generated content, and optional metadata into a
+ * formatted code definition with proper TypeScript syntax.
+ *
+ * This class automatically handles export statements, type annotations, and
+ * JSDoc comment generation, making it the building block for all generated
+ * code artifacts.
+ *
+ * ## Key Features
+ *
+ * - **Automatic Exports**: Handles export keyword based on configuration
+ * - **Type Safety**: Preserves type information through generic parameters
+ * - **JSDoc Integration**: Automatic comment generation from descriptions
+ * - **Entity Type Support**: Handles different definition types (const, type, etc.)
+ * - **Identifier Management**: Integrates with the Identifier system for naming
+ *
+ * @template V - The type of generated value (preserves generator-specific types)
+ *
+ * @example Basic interface definition
+ * ```typescript
+ * import { Definition, Identifier } from '@skmtc/core';
+ *
+ * const userInterface = new Definition({
+ *   context: generateContext,
+ *   identifier: Identifier.createType('User'),
+ *   description: 'Represents a user in the system',
+ *   value: {
+ *     generatorKey: 'typescript-interfaces',
+ *     content: `{
+ *       id: string;
+ *       name: string;
+ *       email: string;
+ *     }`
+ *   }
+ * });
+ *
+ * console.log(userInterface.toString());
+ * //
+ * // Represents a user in the system
+ * //
+ * // export type User = {
+ * //   id: string;
+ * //   name: string;
+ * //   email: string;
+ * // };
+ * ```
+ *
+ * @example Function definition with parameters
+ * ```typescript
+ * const apiFunction = new Definition({
+ *   context: generateContext,
+ *   identifier: Identifier.createVariable('fetchUser', 'Promise<User>'),
+ *   description: 'Fetches a user by ID from the API',
+ *   value: {
+ *     generatorKey: 'api-client',
+ *     content: `async (id: string) => {
+ *       const response = await fetch(\`/api/users/\${id}\`);
+ *       return response.json();
+ *     }`
+ *   }
+ * });
+ *
+ * console.log(apiFunction.toString());
+ * //
+ * //  Fetches a user by ID from the API
+ * //
+ * // export const fetchUser: Promise<User> = async (id: string) => {
+ * //   const response = await fetch(`/api/users/${id}`);
+ * //   return response.json();
+ * // };
+ * ```
+ *
+ * @example Non-exported definition
+ * ```typescript
+ * const helperFunction = new Definition({
+ *   context: generateContext,
+ *   identifier: Identifier.createVariable('validateEmail'),
+ *   value: {
+ *     generatorKey: 'utilities',
+ *     content: `(email: string): boolean => {
+ *       return /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(email);
+ *     }`
+ *   },
+ *   noExport: true // Internal helper, not exported
+ * });
+ *
+ * console.log(helperFunction.toString());
+ * // const validateEmail = (email: string): boolean => {
+ * //   return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+ * // };
+ * ```
+ *
+ * @example Using in generator classes
+ * ```typescript
+ * import { ModelBase, Definition, Identifier } from '@skmtc/core';
+ *
+ * class TypeScriptInterface extends ModelBase {
+ *   toDefinition(): Definition {
+ *     const schema = this.context.getSchema(this.refName);
+ *
+ *     return new Definition({
+ *       context: this.context,
+ *       identifier: Identifier.createType(this.refName),
+ *       description: schema.description,
+ *       value: {
+ *         generatorKey: this.generatorKey,
+ *         content: this.generateInterfaceBody(schema)
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ */
 export declare class Definition<V extends GeneratedValue = GeneratedValue> extends ContentBase {
+    /** The identifier for this definition */
     identifier: Identifier;
+    /** Optional description for JSDoc comments */
     description: string | undefined;
+    /** The generated value content */
     value: V;
+    /** Whether to skip the export keyword */
     noExport?: boolean;
+    /**
+     * Creates a new Definition instance.
+     *
+     * @param args - Definition configuration
+     * @param args.context - Generation context for pipeline access
+     * @param args.identifier - The identifier (name and type info) for this definition
+     * @param args.value - The generated content value
+     * @param args.description - Optional description for JSDoc comments
+     * @param args.noExport - Whether to omit the export keyword (default: false)
+     *
+     * @example
+     * ```typescript
+     * const constant = new Definition({
+     *   context: generateContext,
+     *   identifier: Identifier.createVariable('API_BASE_URL', 'string'),
+     *   description: 'Base URL for all API requests',
+     *   value: {
+     *     generatorKey: 'constants',
+     *     content: "'https://api.example.com'"
+     *   }
+     * });
+     * ```
+     */
     constructor({ context, identifier, value, description, noExport }: ConstructorArgs<V>);
+    /**
+     * Generates the complete TypeScript definition code.
+     *
+     * This method produces a properly formatted TypeScript definition with:
+     * - Optional JSDoc comments from the description
+     * - Export keyword (unless noExport is true)
+     * - Entity type (const, type, function, etc.)
+     * - Identifier with optional type annotation
+     * - Generated value content
+     *
+     * The output follows TypeScript syntax conventions and can be written
+     * directly to a .ts file.
+     *
+     * @returns The complete TypeScript definition as a string
+     *
+     * @example Type definition
+     * ```typescript
+     * const typeDef = new Definition({
+     *   context,
+     *   identifier: Identifier.createType('Status'),
+     *   description: 'Possible status values',
+     *   value: { generatorKey: 'types', content: "'pending' | 'complete' | 'failed'" }
+     * });
+     *
+     * console.log(typeDef.toString());
+     * //
+     * // Possible status values
+     * //
+     * // export type Status = 'pending' | 'complete' | 'failed';
+     * ```
+     *
+     * @example Constant definition
+     * ```typescript
+     * const constDef = new Definition({
+     *   context,
+     *   identifier: Identifier.createVariable('DEFAULT_TIMEOUT', 'number'),
+     *   value: { generatorKey: 'config', content: '5000' }
+     * });
+     *
+     * console.log(constDef.toString());
+     * // export const DEFAULT_TIMEOUT: number = 5000;
+     * ```
+     *
+     * @todo Move syntax to typescript package to enable language-agnostic use
+     */
     toString(): string;
 }
 export {};

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

@@ -1 +1 @@
-{"version":3,"file":"Definition.d.ts","sourceRoot":"","sources":["../../src/dsl/Definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAEhE,KAAK,eAAe,CAAC,CAAC,SAAS,cAAc,IAAI;IAC/C,OAAO,EAAE,eAAe,CAAA;IACxB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,UAAU,CAAA;IACtB,KAAK,EAAE,CAAC,CAAA;IACR,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED,qBAAa,UAAU,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,CAAE,SAAQ,WAAW;IACpF,UAAU,EAAE,UAAU,CAAA;IACtB,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,KAAK,EAAE,CAAC,CAAA;IACR,QAAQ,CAAC,EAAE,OAAO,CAAA;gBAEN,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,eAAe,CAAC,CAAC,CAAC;IAS5E,QAAQ,IAAI,MAAM;CAa5B"}
+{"version":3,"file":"Definition.d.ts","sourceRoot":"","sources":["../../src/dsl/Definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAA;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAE9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAEhE;;;;GAIG;AACH,KAAK,eAAe,CAAC,CAAC,SAAS,cAAc,IAAI;IAC/C,uDAAuD;IACvD,OAAO,EAAE,eAAe,CAAA;IACxB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,yCAAyC;IACzC,UAAU,EAAE,UAAU,CAAA;IACtB,kCAAkC;IAClC,KAAK,EAAE,CAAC,CAAA;IACR,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoHG;AACH,qBAAa,UAAU,CAAC,CAAC,SAAS,cAAc,GAAG,cAAc,CAAE,SAAQ,WAAW;IACpF,yCAAyC;IACzC,UAAU,EAAE,UAAU,CAAA;IAEtB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAE/B,kCAAkC;IAClC,KAAK,EAAE,CAAC,CAAA;IAER,yCAAyC;IACzC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB;;;;;;;;;;;;;;;;;;;;;;OAsBG;gBACS,EAAE,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,eAAe,CAAC,CAAC,CAAC;IASrF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4CG;IACM,QAAQ,IAAI,MAAM;CAa5B"}

package/esm/dsl/Definition.js

@@ -1,26 +1,170 @@
 import { ContentBase } from './ContentBase.js';
 import { withDescription } from '../typescript/withDescription.js';
+/**
+ * Represents a complete code definition in the SKMTC DSL system.
+ *
+ * The `Definition` class is the primary output unit of generators, representing
+ * a complete piece of generated code (like an interface, function, or constant).
+ * It combines an identifier, generated content, and optional metadata into a
+ * formatted code definition with proper TypeScript syntax.
+ *
+ * This class automatically handles export statements, type annotations, and
+ * JSDoc comment generation, making it the building block for all generated
+ * code artifacts.
+ *
+ * ## Key Features
+ *
+ * - **Automatic Exports**: Handles export keyword based on configuration
+ * - **Type Safety**: Preserves type information through generic parameters
+ * - **JSDoc Integration**: Automatic comment generation from descriptions
+ * - **Entity Type Support**: Handles different definition types (const, type, etc.)
+ * - **Identifier Management**: Integrates with the Identifier system for naming
+ *
+ * @template V - The type of generated value (preserves generator-specific types)
+ *
+ * @example Basic interface definition
+ * ```typescript
+ * import { Definition, Identifier } from '@skmtc/core';
+ *
+ * const userInterface = new Definition({
+ *   context: generateContext,
+ *   identifier: Identifier.createType('User'),
+ *   description: 'Represents a user in the system',
+ *   value: {
+ *     generatorKey: 'typescript-interfaces',
+ *     content: `{
+ *       id: string;
+ *       name: string;
+ *       email: string;
+ *     }`
+ *   }
+ * });
+ *
+ * console.log(userInterface.toString());
+ * //
+ * // Represents a user in the system
+ * //
+ * // export type User = {
+ * //   id: string;
+ * //   name: string;
+ * //   email: string;
+ * // };
+ * ```
+ *
+ * @example Function definition with parameters
+ * ```typescript
+ * const apiFunction = new Definition({
+ *   context: generateContext,
+ *   identifier: Identifier.createVariable('fetchUser', 'Promise<User>'),
+ *   description: 'Fetches a user by ID from the API',
+ *   value: {
+ *     generatorKey: 'api-client',
+ *     content: `async (id: string) => {
+ *       const response = await fetch(\`/api/users/\${id}\`);
+ *       return response.json();
+ *     }`
+ *   }
+ * });
+ *
+ * console.log(apiFunction.toString());
+ * //
+ * //  Fetches a user by ID from the API
+ * //
+ * // export const fetchUser: Promise<User> = async (id: string) => {
+ * //   const response = await fetch(`/api/users/${id}`);
+ * //   return response.json();
+ * // };
+ * ```
+ *
+ * @example Non-exported definition
+ * ```typescript
+ * const helperFunction = new Definition({
+ *   context: generateContext,
+ *   identifier: Identifier.createVariable('validateEmail'),
+ *   value: {
+ *     generatorKey: 'utilities',
+ *     content: `(email: string): boolean => {
+ *       return /^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$/.test(email);
+ *     }`
+ *   },
+ *   noExport: true // Internal helper, not exported
+ * });
+ *
+ * console.log(helperFunction.toString());
+ * // const validateEmail = (email: string): boolean => {
+ * //   return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);
+ * // };
+ * ```
+ *
+ * @example Using in generator classes
+ * ```typescript
+ * import { ModelBase, Definition, Identifier } from '@skmtc/core';
+ *
+ * class TypeScriptInterface extends ModelBase {
+ *   toDefinition(): Definition {
+ *     const schema = this.context.getSchema(this.refName);
+ *
+ *     return new Definition({
+ *       context: this.context,
+ *       identifier: Identifier.createType(this.refName),
+ *       description: schema.description,
+ *       value: {
+ *         generatorKey: this.generatorKey,
+ *         content: this.generateInterfaceBody(schema)
+ *       }
+ *     });
+ *   }
+ * }
+ * ```
+ */
 export class Definition extends ContentBase {
+    /**
+     * Creates a new Definition instance.
+     *
+     * @param args - Definition configuration
+     * @param args.context - Generation context for pipeline access
+     * @param args.identifier - The identifier (name and type info) for this definition
+     * @param args.value - The generated content value
+     * @param args.description - Optional description for JSDoc comments
+     * @param args.noExport - Whether to omit the export keyword (default: false)
+     *
+     * @example
+     * ```typescript
+     * const constant = new Definition({
+     *   context: generateContext,
+     *   identifier: Identifier.createVariable('API_BASE_URL', 'string'),
+     *   description: 'Base URL for all API requests',
+     *   value: {
+     *     generatorKey: 'constants',
+     *     content: "'https://api.example.com'"
+     *   }
+     * });
+     * ```
+     */
     constructor({ context, identifier, value, description, noExport }) {
         super({ context, generatorKey: value.generatorKey });
+        /** The identifier for this definition */
         Object.defineProperty(this, "identifier", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Optional description for JSDoc comments */
         Object.defineProperty(this, "description", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** The generated value content */
         Object.defineProperty(this, "value", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /** Whether to skip the export keyword */
         Object.defineProperty(this, "noExport", {
             enumerable: true,
             configurable: true,
@@ -32,6 +176,51 @@ export class Definition extends ContentBase {
         this.description = description;
         this.noExport = noExport;
     }
+    /**
+     * Generates the complete TypeScript definition code.
+     *
+     * This method produces a properly formatted TypeScript definition with:
+     * - Optional JSDoc comments from the description
+     * - Export keyword (unless noExport is true)
+     * - Entity type (const, type, function, etc.)
+     * - Identifier with optional type annotation
+     * - Generated value content
+     *
+     * The output follows TypeScript syntax conventions and can be written
+     * directly to a .ts file.
+     *
+     * @returns The complete TypeScript definition as a string
+     *
+     * @example Type definition
+     * ```typescript
+     * const typeDef = new Definition({
+     *   context,
+     *   identifier: Identifier.createType('Status'),
+     *   description: 'Possible status values',
+     *   value: { generatorKey: 'types', content: "'pending' | 'complete' | 'failed'" }
+     * });
+     *
+     * console.log(typeDef.toString());
+     * //
+     * // Possible status values
+     * //
+     * // export type Status = 'pending' | 'complete' | 'failed';
+     * ```
+     *
+     * @example Constant definition
+     * ```typescript
+     * const constDef = new Definition({
+     *   context,
+     *   identifier: Identifier.createVariable('DEFAULT_TIMEOUT', 'number'),
+     *   value: { generatorKey: 'config', content: '5000' }
+     * });
+     *
+     * console.log(constDef.toString());
+     * // export const DEFAULT_TIMEOUT: number = 5000;
+     * ```
+     *
+     * @todo Move syntax to typescript package to enable language-agnostic use
+     */
     toString() {
         const identifier = this.identifier.typeName
             ? `${this.identifier.name}: ${this.identifier.typeName}`

package/esm/dsl/EntityType.d.ts

@@ -1,6 +1,89 @@
+/**
+ * Represents the type of a TypeScript entity for code generation.
+ *
+ * `EntityType` encapsulates the distinction between different kinds of
+ * TypeScript entities, specifically variables (which become `const` declarations)
+ * and types (which become `type` or `interface` declarations).
+ *
+ * This class is used by the {@link Identifier} system to ensure that
+ * generated code uses the correct TypeScript keywords and syntax patterns.
+ *
+ * @example Variable entity type
+ * ```typescript
+ * import { EntityType } from '@skmtc/core';
+ *
+ * const variableEntity = new EntityType('variable');
+ * console.log(variableEntity.toString()); // 'const'
+ *
+ * // Used in code generation:
+ * // const API_URL = 'https://api.example.com';
+ * ```
+ *
+ * @example Type entity type
+ * ```typescript
+ * const typeEntity = new EntityType('type');
+ * console.log(typeEntity.toString()); // 'type'
+ *
+ * // Used in code generation:
+ * // type User = { id: string; name: string; };
+ * ```
+ *
+ * @example Integration with Identifier
+ * ```typescript
+ * import { Identifier, EntityType } from '@skmtc/core';
+ *
+ * // Create a variable identifier (uses 'const' keyword)
+ * const varId = Identifier.createVariable('API_KEY', 'string');
+ * console.log(varId.entityType.toString()); // 'const'
+ *
+ * // Create a type identifier (uses 'type' keyword)
+ * const typeId = Identifier.createType('UserStatus');
+ * console.log(typeId.entityType.toString()); // 'type'
+ * ```
+ */
 export declare class EntityType {
+    /** The entity type discriminator */
     type: 'variable' | 'type';
+    /**
+     * Creates a new EntityType instance.
+     *
+     * @param type - The type of entity ('variable' for const declarations, 'type' for type declarations)
+     *
+     * @example
+     * ```typescript
+     * // For generating const declarations
+     * const constEntity = new EntityType('variable');
+     *
+     * // For generating type declarations
+     * const typeEntity = new EntityType('type');
+     * ```
+     */
     constructor(type: 'variable' | 'type');
+    /**
+     * Returns the appropriate TypeScript keyword for this entity type.
+     *
+     * This method maps the entity type to the correct TypeScript declaration
+     * keyword that should be used in generated code:
+     * - 'variable' entities become 'const' declarations
+     * - 'type' entities become 'type' declarations
+     *
+     * @returns The TypeScript keyword string ('const' or 'type')
+     *
+     * @example
+     * ```typescript
+     * const varEntity = new EntityType('variable');
+     * console.log(varEntity.toString()); // 'const'
+     *
+     * const typeEntity = new EntityType('type');
+     * console.log(typeEntity.toString()); // 'type'
+     *
+     * // Used in code generation:
+     * const keyword = entityType.toString();
+     * const declaration = `${keyword} ${identifier} = ${value};`;
+     * // Results in: "const API_URL = 'https://example.com';" or
+     * // Results in: "type Status = 'active' | 'inactive';"
+     * ```
+     */
     toString(): string;
 }
 //# sourceMappingURL=EntityType.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"EntityType.d.ts","sourceRoot":"","sources":["../../src/dsl/EntityType.ts"],"names":[],"mappings":"AAEA,qBAAa,UAAU;IACrB,IAAI,EAAE,UAAU,GAAG,MAAM,CAAA;gBACb,IAAI,EAAE,UAAU,GAAG,MAAM;IAIrC,QAAQ,IAAI,MAAM;CAMnB"}
+{"version":3,"file":"EntityType.d.ts","sourceRoot":"","sources":["../../src/dsl/EntityType.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,qBAAa,UAAU;IACrB,oCAAoC;IACpC,IAAI,EAAE,UAAU,GAAG,MAAM,CAAA;IAEzB;;;;;;;;;;;;;OAaG;gBACS,IAAI,EAAE,UAAU,GAAG,MAAM;IAIrC;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,QAAQ,IAAI,MAAM;CAMnB"}

package/esm/dsl/EntityType.js

@@ -1,6 +1,64 @@
 import { match } from 'ts-pattern';
+/**
+ * Represents the type of a TypeScript entity for code generation.
+ *
+ * `EntityType` encapsulates the distinction between different kinds of
+ * TypeScript entities, specifically variables (which become `const` declarations)
+ * and types (which become `type` or `interface` declarations).
+ *
+ * This class is used by the {@link Identifier} system to ensure that
+ * generated code uses the correct TypeScript keywords and syntax patterns.
+ *
+ * @example Variable entity type
+ * ```typescript
+ * import { EntityType } from '@skmtc/core';
+ *
+ * const variableEntity = new EntityType('variable');
+ * console.log(variableEntity.toString()); // 'const'
+ *
+ * // Used in code generation:
+ * // const API_URL = 'https://api.example.com';
+ * ```
+ *
+ * @example Type entity type
+ * ```typescript
+ * const typeEntity = new EntityType('type');
+ * console.log(typeEntity.toString()); // 'type'
+ *
+ * // Used in code generation:
+ * // type User = { id: string; name: string; };
+ * ```
+ *
+ * @example Integration with Identifier
+ * ```typescript
+ * import { Identifier, EntityType } from '@skmtc/core';
+ *
+ * // Create a variable identifier (uses 'const' keyword)
+ * const varId = Identifier.createVariable('API_KEY', 'string');
+ * console.log(varId.entityType.toString()); // 'const'
+ *
+ * // Create a type identifier (uses 'type' keyword)
+ * const typeId = Identifier.createType('UserStatus');
+ * console.log(typeId.entityType.toString()); // 'type'
+ * ```
+ */
 export class EntityType {
+    /**
+     * Creates a new EntityType instance.
+     *
+     * @param type - The type of entity ('variable' for const declarations, 'type' for type declarations)
+     *
+     * @example
+     * ```typescript
+     * // For generating const declarations
+     * const constEntity = new EntityType('variable');
+     *
+     * // For generating type declarations
+     * const typeEntity = new EntityType('type');
+     * ```
+     */
     constructor(type) {
+        /** The entity type discriminator */
         Object.defineProperty(this, "type", {
             enumerable: true,
             configurable: true,
@@ -9,6 +67,31 @@ export class EntityType {
         });
         this.type = type;
     }
+    /**
+     * Returns the appropriate TypeScript keyword for this entity type.
+     *
+     * This method maps the entity type to the correct TypeScript declaration
+     * keyword that should be used in generated code:
+     * - 'variable' entities become 'const' declarations
+     * - 'type' entities become 'type' declarations
+     *
+     * @returns The TypeScript keyword string ('const' or 'type')
+     *
+     * @example
+     * ```typescript
+     * const varEntity = new EntityType('variable');
+     * console.log(varEntity.toString()); // 'const'
+     *
+     * const typeEntity = new EntityType('type');
+     * console.log(typeEntity.toString()); // 'type'
+     *
+     * // Used in code generation:
+     * const keyword = entityType.toString();
+     * const declaration = `${keyword} ${identifier} = ${value};`;
+     * // Results in: "const API_URL = 'https://example.com';" or
+     * // Results in: "type Status = 'active' | 'inactive';"
+     * ```
+     */
     toString() {
         return match(this.type)
             .with('variable', () => 'const')