@skmtc/core 0.0.786 → 0.0.787

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')

package/esm/oas/array/Array.d.ts

@@ -2,21 +2,129 @@ import "../../_dnt.polyfills.js";
 import type { OasSchema, ToJsonSchemaOptions } from '../schema/Schema.js';
 import type { OasRef } from '../ref/Ref.js';
 import type { OpenAPIV3 } from 'openapi-types';
+/**
+ * Constructor fields for {@link OasArray}.
+ *
+ * @template Nullable - Whether the array value can be null
+ */
 export type ArrayFields<Nullable extends boolean | undefined> = {
+    /** Schema definition for array items */
     items: OasSchema | OasRef<'schema'>;
+    /** A short summary of the array schema */
     title?: string;
+    /** A description of the array schema */
     description?: string;
+    /** Whether the array value can be null */
     nullable?: Nullable;
+    /** Whether array items must be unique */
     uniqueItems?: boolean;
+    /** Custom extension fields (x-* properties) */
     extensionFields?: Record<string, unknown>;
+    /** Example array value */
     example?: Nullable extends true ? unknown[] | null | undefined : unknown[] | undefined;
+    /** Maximum number of items allowed */
     maxItems?: number;
+    /** Minimum number of items required */
     minItems?: number;
+    /** Array of allowed enum values for the entire array */
     enums?: Nullable extends true ? (unknown | null)[] | undefined : unknown[] | undefined;
+    /** Default value for the array */
     defaultValue?: Nullable extends true ? unknown[] | null | undefined : unknown[] | undefined;
 };
 /**
- * Object representing an array in the OpenAPI Specification.
+ * Represents an array schema in the OpenAPI Specification.
+ *
+ * `OasArray` handles array type definitions with comprehensive validation
+ * constraints including item count limits, uniqueness requirements, and
+ * item type specifications. It supports nested schemas and references
+ * for complex array structures.
+ *
+ * This class is used throughout the OAS processing pipeline to represent
+ * array fields in API schemas, including lists of objects, primitive arrays,
+ * and complex nested array structures.
+ *
+ * ## Key Features
+ *
+ * - **Item Type Definition**: Support for any schema type as array items
+ * - **Size Constraints**: Minimum and maximum item count validation
+ * - **Uniqueness Validation**: Ensure array items are unique (like Set behavior)
+ * - **Nested Schemas**: Support for complex nested array structures
+ * - **Reference Handling**: Seamless integration with schema references
+ * - **Nullable Support**: Type-safe nullable array handling
+ * - **JSON Schema**: Conversion to standard JSON Schema format
+ *
+ * @template Nullable - Whether the array value can be null
+ *
+ * @example String array
+ * ```typescript
+ * import { OasArray, OasString } from '@skmtc/core';
+ *
+ * const tagsArray = new OasArray({
+ *   title: 'Tags',
+ *   description: 'List of tags associated with the item',
+ *   items: new OasString({ minLength: 1 }),
+ *   minItems: 1,
+ *   uniqueItems: true,
+ *   example: ['javascript', 'typescript', 'react']
+ * });
+ * ```
+ *
+ * @example Object array with references
+ * ```typescript
+ * import { OasArray, OasRef } from '@skmtc/core';
+ *
+ * const usersArray = new OasArray({
+ *   title: 'Users',
+ *   description: 'List of user objects',
+ *   items: new OasRef({ refName: 'User' }),
+ *   maxItems: 100,
+ *   example: [
+ *     { id: 1, name: 'John' },
+ *     { id: 2, name: 'Jane' }
+ *   ]
+ * });
+ * ```
+ *
+ * @example Nested array (array of arrays)
+ * ```typescript
+ * const matrixArray = new OasArray({
+ *   title: 'Matrix',
+ *   description: '2D array of numbers',
+ *   items: new OasArray({
+ *     items: new OasInteger({ minimum: 0 })
+ *   }),
+ *   example: [
+ *     [1, 2, 3],
+ *     [4, 5, 6],
+ *     [7, 8, 9]
+ *   ]
+ * });
+ * ```
+ *
+ * @example Nullable array with constraints
+ * ```typescript
+ * const optionalIdsArray = new OasArray<true>({
+ *   title: 'Optional IDs',
+ *   description: 'Optional list of IDs',
+ *   items: new OasInteger({ format: 'int64', minimum: 1 }),
+ *   nullable: true,
+ *   minItems: 0,
+ *   maxItems: 10,
+ *   defaultValue: null
+ * });
+ * ```
+ *
+ * @example Unique items validation
+ * ```typescript
+ * const uniqueEmailsArray = new OasArray({
+ *   title: 'Email Recipients',
+ *   description: 'List of unique email addresses',
+ *   items: new OasString({ format: 'email' }),
+ *   uniqueItems: true, // Ensures no duplicate emails
+ *   minItems: 1,
+ *   example: ['user1@example.com', 'user2@example.com']
+ * });
+ * ```
  */
 export declare class OasArray<Nullable extends boolean | undefined = boolean | undefined> {
     /**

package/esm/oas/array/Array.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Array.d.ts","sourceRoot":"","sources":["../../../src/oas/array/Array.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,MAAM,MAAM,WAAW,CAAC,QAAQ,SAAS,OAAO,GAAG,SAAS,IAAI;IAC9D,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAA;IACnC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACzC,OAAO,CAAC,EAAE,QAAQ,SAAS,IAAI,GAAG,OAAO,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,EAAE,GAAG,SAAS,CAAA;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,QAAQ,SAAS,IAAI,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,GAAG,SAAS,GAAG,OAAO,EAAE,GAAG,SAAS,CAAA;IACtF,YAAY,CAAC,EAAE,QAAQ,SAAS,IAAI,GAAG,OAAO,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,EAAE,GAAG,SAAS,CAAA;CAC5F,CAAA;AAED;;GAEG;AACH,qBAAa,QAAQ,CAAC,QAAQ,SAAS,OAAO,GAAG,SAAS,GAAG,OAAO,GAAG,SAAS;IAC9E;;;OAGG;IACH,OAAO,EAAG,QAAQ,CAAS;IAC3B;;OAEG;IACH,IAAI,EAAG,OAAO,CAAS;IACvB;;OAEG;IACH,KAAK,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAA;IACnC;;OAEG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB;;OAEG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B;;OAEG;IACH,QAAQ,EAAE,QAAQ,GAAG,SAAS,CAAA;IAC9B;;OAEG;IACH,WAAW,EAAE,OAAO,GAAG,SAAS,CAAA;IAEhC,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IAEpD;;OAEG;IACH,OAAO,EAAE,QAAQ,SAAS,IAAI,GAAG,OAAO,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,EAAE,GAAG,SAAS,CAAA;IACrF;;OAEG;IACH,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B;;OAEG;IACH,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAE5B;;OAEG;IACH,KAAK,EAAE,QAAQ,SAAS,IAAI,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC,EAAE,GAAG,SAAS,GAAG,OAAO,EAAE,GAAG,SAAS,CAAA;IAErF;;OAEG;IACH,YAAY,EAAE,QAAQ,SAAS,IAAI,GAAG,OAAO,EAAE,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,EAAE,GAAG,SAAS,CAAA;gBAE9E,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC;IAczC,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC;IAIjC,OAAO,IAAI,QAAQ,CAAC,QAAQ,CAAC;IAI7B,WAAW,IAAI,QAAQ,CAAC,QAAQ,CAAC;IAIjC,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAAC,iBAAiB;CAexE"}
+{"version":3,"file":"Array.d.ts","sourceRoot":"","sources":["../../../src/oas/array/Array.ts"],"names":[],"mappings":"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"}

package/esm/oas/array/Array.js

@@ -1,6 +1,98 @@
 import "../../_dnt.polyfills.js";
 /**
- * Object representing an array in the OpenAPI Specification.
+ * Represents an array schema in the OpenAPI Specification.
+ *
+ * `OasArray` handles array type definitions with comprehensive validation
+ * constraints including item count limits, uniqueness requirements, and
+ * item type specifications. It supports nested schemas and references
+ * for complex array structures.
+ *
+ * This class is used throughout the OAS processing pipeline to represent
+ * array fields in API schemas, including lists of objects, primitive arrays,
+ * and complex nested array structures.
+ *
+ * ## Key Features
+ *
+ * - **Item Type Definition**: Support for any schema type as array items
+ * - **Size Constraints**: Minimum and maximum item count validation
+ * - **Uniqueness Validation**: Ensure array items are unique (like Set behavior)
+ * - **Nested Schemas**: Support for complex nested array structures
+ * - **Reference Handling**: Seamless integration with schema references
+ * - **Nullable Support**: Type-safe nullable array handling
+ * - **JSON Schema**: Conversion to standard JSON Schema format
+ *
+ * @template Nullable - Whether the array value can be null
+ *
+ * @example String array
+ * ```typescript
+ * import { OasArray, OasString } from '@skmtc/core';
+ *
+ * const tagsArray = new OasArray({
+ *   title: 'Tags',
+ *   description: 'List of tags associated with the item',
+ *   items: new OasString({ minLength: 1 }),
+ *   minItems: 1,
+ *   uniqueItems: true,
+ *   example: ['javascript', 'typescript', 'react']
+ * });
+ * ```
+ *
+ * @example Object array with references
+ * ```typescript
+ * import { OasArray, OasRef } from '@skmtc/core';
+ *
+ * const usersArray = new OasArray({
+ *   title: 'Users',
+ *   description: 'List of user objects',
+ *   items: new OasRef({ refName: 'User' }),
+ *   maxItems: 100,
+ *   example: [
+ *     { id: 1, name: 'John' },
+ *     { id: 2, name: 'Jane' }
+ *   ]
+ * });
+ * ```
+ *
+ * @example Nested array (array of arrays)
+ * ```typescript
+ * const matrixArray = new OasArray({
+ *   title: 'Matrix',
+ *   description: '2D array of numbers',
+ *   items: new OasArray({
+ *     items: new OasInteger({ minimum: 0 })
+ *   }),
+ *   example: [
+ *     [1, 2, 3],
+ *     [4, 5, 6],
+ *     [7, 8, 9]
+ *   ]
+ * });
+ * ```
+ *
+ * @example Nullable array with constraints
+ * ```typescript
+ * const optionalIdsArray = new OasArray<true>({
+ *   title: 'Optional IDs',
+ *   description: 'Optional list of IDs',
+ *   items: new OasInteger({ format: 'int64', minimum: 1 }),
+ *   nullable: true,
+ *   minItems: 0,
+ *   maxItems: 10,
+ *   defaultValue: null
+ * });
+ * ```
+ *
+ * @example Unique items validation
+ * ```typescript
+ * const uniqueEmailsArray = new OasArray({
+ *   title: 'Email Recipients',
+ *   description: 'List of unique email addresses',
+ *   items: new OasString({ format: 'email' }),
+ *   uniqueItems: true, // Ensures no duplicate emails
+ *   minItems: 1,
+ *   example: ['user1@example.com', 'user2@example.com']
+ * });
+ * ```
  */
 export class OasArray {
     constructor(fields) {