@skmtc/core 0.0.785 → 0.0.787

package/script/oas/document/Document.js

@@ -15,8 +15,85 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OasDocument = void 0;
 require("../../_dnt.polyfills.js");
 const ts_pattern_1 = require("ts-pattern");
-/** Top level document object describing the API */
+/**
+ * Represents a complete OpenAPI v3 document in the SKMTC OAS processing system.
+ *
+ * The `OasDocument` class is the root object in the OAS hierarchy, containing all
+ * the information needed to describe a complete REST API. It provides normalized
+ * access to document properties with built-in validation and error handling.
+ *
+ * ## Key Features
+ *
+ * - **Normalized Structure**: Operations are flattened from nested paths for easier processing
+ * - **Lazy Initialization**: Fields are set after construction during parsing
+ * - **Type Safety**: All properties are typed and validated on access
+ * - **Extensibility**: Supports OpenAPI extension fields (x-* properties)
+ * - **JSON Serialization**: Can be converted back to standard OpenAPI JSON format
+ *
+ * @example Basic document access
+ * ```typescript
+ * import { OasDocument } from '@skmtc/core';
+ *
+ * // Document is typically created during parsing
+ * const document = new OasDocument();
+ * document.fields = {
+ *   openapi: '3.0.0',
+ *   info: { title: 'My API', version: '1.0.0' },
+ *   operations: [
+ *     // ... parsed operations
+ *   ],
+ *   components: {
+ *     schemas: {
+ *       User: { type: 'object', properties: { id: { type: 'string' } } }
+ *     }
+ *   }
+ * };
+ *
+ * console.log(document.info.title); // 'My API'
+ * console.log(document.operations.length); // Number of operations
+ * ```
+ *
+ * @example Iterating over operations
+ * ```typescript
+ * // Process all operations in the document
+ * for (const operation of document.operations) {
+ *   console.log(`${operation.method.toUpperCase()} ${operation.path}`);
+ *
+ *   if (operation.operationId) {
+ *     console.log(`Operation ID: ${operation.operationId}`);
+ *   }
+ * }
+ * ```
+ *
+ * @example Working with components
+ * ```typescript
+ * if (document.components?.schemas) {
+ *   const userSchema = document.components.schemas.get('User');
+ *   if (userSchema) {
+ *     console.log('User schema found:', userSchema);
+ *   }
+ * }
+ * ```
+ */
 class OasDocument {
+    /**
+     * Creates a new OasDocument instance.
+     *
+     * The document is typically created with undefined fields and populated
+     * later during the parsing process. This allows for lazy initialization
+     * and proper error handling during document processing.
+     *
+     * @param fields - Optional document fields (usually set later during parsing)
+     *
+     * @example
+     * ```typescript
+     * // Usually created without fields during parsing
+     * const document = new OasDocument();
+     *
+     * // Fields are set later by the parser
+     * document.fields = parsedDocumentFields;
+     * ```
+     */
     constructor(fields) {
         /** Static identifier property for OasDocument */
         Object.defineProperty(this, "oasType", {
@@ -25,10 +102,31 @@ class OasDocument {
             writable: true,
             value: 'openapi'
         });
-        /** @internal */
+        /** @internal Private fields storage */
         _OasDocument_fields.set(this, void 0);
         __classPrivateFieldSet(this, _OasDocument_fields, fields, "f");
     }
+    /**
+     * Removes an item from the document based on a stack trail path.
+     *
+     * This method is used internally during document processing to remove
+     * specific operations or schema components. The stack trail indicates
+     * the path to the item within the document structure.
+     *
+     * @param stackTrail - Path to the item to remove
+     * @returns The removed item, or undefined if not found
+     *
+     * @internal This method is primarily used by the processing pipeline
+     *
+     * @example
+     * ```typescript
+     * // Remove an operation at /users POST
+     * const removed = document.removeItem(new StackTrail(['paths', '/users', 'post']));
+     *
+     * // Remove a schema component
+     * const removedSchema = document.removeItem(new StackTrail(['components', 'schemas', 'User']));
+     * ```
+     */
     removeItem(stackTrail) {
         const [first, second, third] = stackTrail.stackTrail;
         return (0, ts_pattern_1.match)(first)
@@ -50,6 +148,26 @@ class OasDocument {
             throw new Error(`Unexpected stack trail: ${stackTrail}`);
         });
     }
+    /**
+     * Sets the document fields after parsing.
+     *
+     * This setter is called by the parsing pipeline to populate the document
+     * with parsed OpenAPI data. It enables lazy initialization and proper
+     * error handling during document processing.
+     *
+     * @param fields - The parsed document fields
+     *
+     * @example
+     * ```typescript
+     * const document = new OasDocument();
+     * document.fields = {
+     *   openapi: '3.0.0',
+     *   info: { title: 'API', version: '1.0' },
+     *   operations: [],
+     *   // ... other fields
+     * };
+     * ```
+     */
     set fields(fields) {
         __classPrivateFieldSet(this, _OasDocument_fields, fields, "f");
     }
@@ -108,6 +226,27 @@ class OasDocument {
         }
         return __classPrivateFieldGet(this, _OasDocument_fields, "f").extensionFields;
     }
+    /**
+     * Converts the document back to a JSON-serializable OpenAPI object.
+     *
+     * This method serializes the document to a standard OpenAPI v3 format,
+     * which can be used for output, validation, or further processing. The
+     * resulting object follows the OpenAPI specification structure.
+     *
+     * @returns A JSON-serializable object representing the OpenAPI document
+     *
+     * @example
+     * ```typescript
+     * // Convert document back to standard OpenAPI format
+     * const openApiJson = document.toJSON();
+     *
+     * // Can be stringified for output
+     * const yamlString = JSON.stringify(openApiJson, null, 2);
+     *
+     * // Or used with OpenAPI tools
+     * await validateOpenApiDocument(openApiJson);
+     * ```
+     */
     toJSON() {
         return {
             openapi: this.openapi,

package/script/oas/integer/Integer.d.ts

@@ -2,21 +2,119 @@ import "../../_dnt.polyfills.js";
 import type { OasRef } from '../ref/Ref.js';
 import type { OpenAPIV3 } from 'openapi-types';
 import type { ToJsonSchemaOptions } from '../schema/Schema.js';
+/**
+ * Constructor fields for {@link OasInteger}.
+ *
+ * @template Nullable - Whether the integer value can be null
+ */
 export type IntegerFields<Nullable extends boolean | undefined> = {
+    /** A short summary of the integer schema */
     title?: string;
+    /** A description of the integer schema */
     description?: string;
+    /** Whether the integer value can be null */
     nullable?: Nullable;
+    /** Integer format specification (int32 or int64) */
     format?: 'int32' | 'int64';
+    /** Default value for the integer */
     default?: Nullable extends true ? number | null | undefined : number | undefined;
+    /** Array of allowed enum values */
     enums?: Nullable extends true ? (number | null)[] | undefined : number[] | undefined;
+    /** Custom extension fields (x-* properties) */
     extensionFields?: Record<string, unknown>;
+    /** Example value for the integer */
     example?: Nullable extends true ? number | null | undefined : number | undefined;
+    /** Number must be a multiple of this value */
     multipleOf?: number;
+    /** Maximum value (inclusive) */
     maximum?: number;
+    /** Whether maximum is exclusive */
     exclusiveMaximum?: boolean;
+    /** Minimum value (inclusive) */
     minimum?: number;
+    /** Whether minimum is exclusive */
     exclusiveMinimum?: boolean;
 };
+/**
+ * Represents an integer schema in the OpenAPI Specification.
+ *
+ * `OasInteger` handles integer type definitions with comprehensive validation
+ * constraints including range limits, multiple-of validation, format specifications,
+ * and enum restrictions. It supports both 32-bit and 64-bit integer formats
+ * and provides nullable type support.
+ *
+ * This class is used throughout the OAS processing pipeline to represent
+ * integer fields in API schemas, including IDs, counts, timestamps, and
+ * other numeric values that must be whole numbers.
+ *
+ * ## Key Features
+ *
+ * - **Format Support**: int32 and int64 format specifications
+ * - **Range Validation**: Minimum and maximum value constraints
+ * - **Multiple Validation**: Ensure values are multiples of specified numbers
+ * - **Enum Values**: Restricted sets of allowed integer values
+ * - **Nullable Support**: Type-safe nullable integer handling
+ * - **JSON Schema**: Conversion to standard JSON Schema format
+ *
+ * @template Nullable - Whether the integer value can be null
+ *
+ * @example Basic integer schema
+ * ```typescript
+ * import { OasInteger } from '@skmtc/core';
+ *
+ * const ageInteger = new OasInteger({
+ *   title: 'Age',
+ *   description: 'Person age in years',
+ *   minimum: 0,
+ *   maximum: 150,
+ *   example: 25
+ * });
+ * ```
+ *
+ * @example ID with int64 format
+ * ```typescript
+ * const userIdInteger = new OasInteger({
+ *   title: 'User ID',
+ *   description: 'Unique user identifier',
+ *   format: 'int64',
+ *   minimum: 1,
+ *   example: 1234567890123
+ * });
+ * ```
+ *
+ * @example Count with multiple-of validation
+ * ```typescript
+ * const batchSizeInteger = new OasInteger({
+ *   title: 'Batch Size',
+ *   description: 'Number of items to process',
+ *   minimum: 10,
+ *   maximum: 1000,
+ *   multipleOf: 10, // Must be multiple of 10
+ *   default: 50
+ * });
+ * ```
+ *
+ * @example Status code enum
+ * ```typescript
+ * const statusCodeInteger = new OasInteger({
+ *   title: 'HTTP Status Code',
+ *   description: 'Valid HTTP response status codes',
+ *   enums: [200, 201, 400, 401, 404, 500],
+ *   example: 200
+ * });
+ * ```
+ *
+ * @example Nullable integer
+ * ```typescript
+ * const optionalCountInteger = new OasInteger<true>({
+ *   title: 'Optional Count',
+ *   description: 'Count value that can be null',
+ *   nullable: true,
+ *   minimum: 0,
+ *   default: null
+ * });
+ * ```
+ */
 export declare class OasInteger<Nullable extends boolean | undefined = boolean | undefined> {
     /**
      * Object is part the 'schema' set which is used

package/script/oas/integer/Integer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Integer.d.ts","sourceRoot":"","sources":["../../../src/oas/integer/Integer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Integer.d.ts","sourceRoot":"","sources":["../../../src/oas/integer/Integer.ts"],"names":[],"mappings":"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"}

package/script/oas/integer/Integer.js

@@ -2,6 +2,86 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OasInteger = void 0;
 require("../../_dnt.polyfills.js");
+/**
+ * Represents an integer schema in the OpenAPI Specification.
+ *
+ * `OasInteger` handles integer type definitions with comprehensive validation
+ * constraints including range limits, multiple-of validation, format specifications,
+ * and enum restrictions. It supports both 32-bit and 64-bit integer formats
+ * and provides nullable type support.
+ *
+ * This class is used throughout the OAS processing pipeline to represent
+ * integer fields in API schemas, including IDs, counts, timestamps, and
+ * other numeric values that must be whole numbers.
+ *
+ * ## Key Features
+ *
+ * - **Format Support**: int32 and int64 format specifications
+ * - **Range Validation**: Minimum and maximum value constraints
+ * - **Multiple Validation**: Ensure values are multiples of specified numbers
+ * - **Enum Values**: Restricted sets of allowed integer values
+ * - **Nullable Support**: Type-safe nullable integer handling
+ * - **JSON Schema**: Conversion to standard JSON Schema format
+ *
+ * @template Nullable - Whether the integer value can be null
+ *
+ * @example Basic integer schema
+ * ```typescript
+ * import { OasInteger } from '@skmtc/core';
+ *
+ * const ageInteger = new OasInteger({
+ *   title: 'Age',
+ *   description: 'Person age in years',
+ *   minimum: 0,
+ *   maximum: 150,
+ *   example: 25
+ * });
+ * ```
+ *
+ * @example ID with int64 format
+ * ```typescript
+ * const userIdInteger = new OasInteger({
+ *   title: 'User ID',
+ *   description: 'Unique user identifier',
+ *   format: 'int64',
+ *   minimum: 1,
+ *   example: 1234567890123
+ * });
+ * ```
+ *
+ * @example Count with multiple-of validation
+ * ```typescript
+ * const batchSizeInteger = new OasInteger({
+ *   title: 'Batch Size',
+ *   description: 'Number of items to process',
+ *   minimum: 10,
+ *   maximum: 1000,
+ *   multipleOf: 10, // Must be multiple of 10
+ *   default: 50
+ * });
+ * ```
+ *
+ * @example Status code enum
+ * ```typescript
+ * const statusCodeInteger = new OasInteger({
+ *   title: 'HTTP Status Code',
+ *   description: 'Valid HTTP response status codes',
+ *   enums: [200, 201, 400, 401, 404, 500],
+ *   example: 200
+ * });
+ * ```
+ *
+ * @example Nullable integer
+ * ```typescript
+ * const optionalCountInteger = new OasInteger<true>({
+ *   title: 'Optional Count',
+ *   description: 'Count value that can be null',
+ *   nullable: true,
+ *   minimum: 0,
+ *   default: null
+ * });
+ * ```
+ */
 class OasInteger {
     constructor(fields = {}) {
         /**