@skmtc/core 0.0.788 → 0.0.790

package/script/oas/components/Components.js

@@ -15,6 +15,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.OasComponents = exports.componentsKeys = void 0;
 require("../../_dnt.polyfills.js");
 require("../../_dnt.polyfills.js");
+/**
+ * Available component types in an OpenAPI document.
+ */
 exports.componentsKeys = [
     'schemas',
     'responses',
@@ -24,11 +27,182 @@ exports.componentsKeys = [
     'headers',
     'securitySchemes'
 ];
-/** Container object for re-usable schema items within the API
+/**
+ * Represents the OpenAPI Components Object in the SKMTC OAS processing system.
+ *
+ * The `OasComponents` class manages the reusable components section of an OpenAPI
+ * document, providing centralized access to shared schemas, responses, parameters,
+ * and other reusable elements that can be referenced throughout the API specification.
+ *
+ * This class serves as the central registry for all reusable components, enabling
+ * efficient reference resolution and reducing duplication in OpenAPI documents.
+ *
+ * ## Key Features
+ *
+ * - **Schema Management**: Central repository for reusable data schemas
+ * - **Response Reuse**: Common response definitions for consistent API responses
+ * - **Parameter Standardization**: Shared parameter definitions across operations
+ * - **Reference Resolution**: Support for internal references ($ref) to components
+ * - **Type Safety**: Strongly typed access to different component categories
+ * - **Extension Support**: Custom OpenAPI extension field handling
+ *
+ * @example Basic component access
+ * ```typescript
+ * import { OasComponents } from '@skmtc/core';
+ *
+ * // Typically created during document parsing
+ * const components = new OasComponents({
+ *   schemas: {
+ *     User: new OasObject({
+ *       properties: {
+ *         id: new OasString(),
+ *         name: new OasString()
+ *       }
+ *     }),
+ *     Product: new OasObject({
+ *       properties: {
+ *         id: new OasString(),
+ *         price: new OasNumber()
+ *       }
+ *     })
+ *   },
+ *   responses: {
+ *     NotFound: new OasResponse({
+ *       description: '404 - Resource not found'
+ *     })
+ *   }
+ * });
+ *
+ * // Access schemas
+ * const userSchema = components.schemas?.['User'];
+ * const productSchema = components.schemas?.['Product'];
+ *
+ * // Access responses
+ * const notFoundResponse = components.responses?.['NotFound'];
+ * ```
+ *
+ * @example Schema management
+ * ```typescript
+ * // Get all schema reference names
+ * const schemaNames = components.toSchemasRefNames();
+ * console.log(schemaNames); // ['User', 'Product', 'Order']
+ *
+ * // Remove a schema (useful for processing)
+ * const removedSchema = components.removeSchema('ObsoleteSchema');
+ * console.log('Removed:', removedSchema);
+ *
+ * // Check remaining schemas
+ * const remainingSchemas = components.toSchemasRefNames();
+ * console.log('Remaining:', remainingSchemas);
+ * ```
+ *
+ * @example Parameter reuse
+ * ```typescript
+ * const components = new OasComponents({
+ *   parameters: {
+ *     PageSize: new OasParameter({
+ *       name: 'pageSize',
+ *       in: 'query',
+ *       schema: new OasInteger({ minimum: 1, maximum: 100, default: 20 })
+ *     }),
+ *     PageNumber: new OasParameter({
+ *       name: 'page',
+ *       in: 'query',
+ *       schema: new OasInteger({ minimum: 1, default: 1 })
+ *     })
+ *   }
+ * });
+ *
+ * // These parameters can be referenced in operations:
+ * // $ref: '#/components/parameters/PageSize'
+ * // $ref: '#/components/parameters/PageNumber'
+ * ```
+ *
+ * @example Response standardization
+ * ```typescript
+ * const components = new OasComponents({
+ *   responses: {
+ *     Success: new OasResponse({
+ *       description: 'Successful operation',
+ *       content: {
+ *         'application/json': {
+ *           schema: new OasObject({
+ *             properties: {
+ *               success: new OasBoolean({ default: true }),
+ *               data: new OasObject({ additionalProperties: true })
+ *             }
+ *           })
+ *         }
+ *       }
+ *     }),
+ *     ValidationError: new OasResponse({
+ *       description: 'Validation failed',
+ *       content: {
+ *         'application/json': {
+ *           schema: new OasObject({
+ *             properties: {
+ *               error: new OasString(),
+ *               details: new OasArray({
+ *                 items: new OasString()
+ *               })
+ *             }
+ *           })
+ *         }
+ *       }
+ *     })
+ *   }
+ * });
+ *
+ * // Standardized responses across all operations
+ * ```
+ *
+ * @example Processing components in generators
+ * ```typescript
+ * class ComponentProcessor {
+ *   processDocument(document: OasDocument) {
+ *     const components = document.components;
+ *     if (!components) return;
+ *
+ *     // Process all schemas
+ *     if (components.schemas) {
+ *       Object.entries(components.schemas).forEach(([name, schema]) => {
+ *         if (schema.isRef()) {
+ *           console.log(`Schema ${name} is a reference to ${schema.$ref}`);
+ *         } else {
+ *           console.log(`Schema ${name} is a direct definition`);
+ *         }
+ *       });
+ *     }
  *
- * Fields not yet implemented: **securitySchemes**, **links**, **callbacks**
+ *     // Process parameters
+ *     if (components.parameters) {
+ *       Object.keys(components.parameters).forEach(paramName => {
+ *         console.log(`Reusable parameter: ${paramName}`);
+ *       });
+ *     }
+ *   }
+ * }
+ * ```
  */
 class OasComponents {
+    /**
+     * Creates a new OasComponents instance.
+     *
+     * @param fields - Component definitions (defaults to empty object)
+     *
+     * @example
+     * ```typescript
+     * const components = new OasComponents({
+     *   schemas: {
+     *     User: userSchema,
+     *     Product: productSchema
+     *   },
+     *   responses: {
+     *     NotFound: notFoundResponse
+     *   }
+     * });
+     * ```
+     */
     constructor(fields = {}) {
         /** Static identifier property for OasComponents */
         Object.defineProperty(this, "oasType", {
@@ -41,6 +215,35 @@ class OasComponents {
         _OasComponents_fields.set(this, void 0);
         __classPrivateFieldSet(this, _OasComponents_fields, fields, "f");
     }
+    /**
+     * Gets all schema reference names.
+     *
+     * This method extracts the keys from the schemas object and returns them
+     * as an array of RefName types. Useful for iterating over all available
+     * schemas or checking schema availability.
+     *
+     * @returns Array of reference names for all schemas
+     *
+     * @example
+     * ```typescript
+     * const components = new OasComponents({
+     *   schemas: {
+     *     User: userSchema,
+     *     Product: productSchema,
+     *     Order: orderSchema
+     *   }
+     * });
+     *
+     * const schemaNames = components.toSchemasRefNames();
+     * console.log(schemaNames); // ['User', 'Product', 'Order']
+     *
+     * // Use for processing
+     * schemaNames.forEach(name => {
+     *   const schema = components.schemas?.[name];
+     *   console.log(`Processing schema: ${name}`);
+     * });
+     * ```
+     */
     toSchemasRefNames() {
         return Object.keys(__classPrivateFieldGet(this, _OasComponents_fields, "f").schemas ?? {});
     }
@@ -48,6 +251,42 @@ class OasComponents {
     get schemas() {
         return __classPrivateFieldGet(this, _OasComponents_fields, "f").schemas;
     }
+    /**
+     * Removes a schema from the components and returns it.
+     *
+     * This method permanently removes a schema from the components object
+     * and returns the removed schema. This is useful during processing when
+     * you need to extract and handle specific schemas separately.
+     *
+     * @param refName - The reference name of the schema to remove
+     * @returns The removed schema object or reference
+     *
+     * @throws {Error} When the schema doesn't exist or schemas object is undefined
+     *
+     * @example
+     * ```typescript
+     * const components = new OasComponents({
+     *   schemas: {
+     *     User: userSchema,
+     *     Product: productSchema,
+     *     Internal: internalSchema
+     *   }
+     * });
+     *
+     * // Remove internal schema that shouldn't be exposed
+     * const internalSchema = components.removeSchema('Internal');
+     * console.log('Removed internal schema');
+     *
+     * // Check remaining schemas
+     * const remainingSchemas = components.toSchemasRefNames();
+     * console.log(remainingSchemas); // ['User', 'Product']
+     *
+     * // Process removed schema separately
+     * if (!internalSchema.isRef()) {
+     *   console.log('Processing internal schema privately');
+     * }
+     * ```
+     */
     removeSchema(refName) {
         const { [refName]: removed, ...rest } = __classPrivateFieldGet(this, _OasComponents_fields, "f").schemas;
         __classPrivateFieldGet(this, _OasComponents_fields, "f").schemas = rest;

package/script/oas/parameter/Parameter.d.ts

@@ -6,21 +6,181 @@ import type { OasExample } from '../example/Example.js';
 import type { OasSchema } from '../schema/Schema.js';
 import type { ToJsonSchemaOptions } from '../schema/Schema.js';
 import type { OpenAPIV3 } from 'openapi-types';
+/**
+ * Constructor fields for {@link OasParameter}.
+ */
 export type ParameterFields = {
+    /** The name of the parameter */
     name: string;
+    /** The location of the parameter (path, query, header, cookie) */
     location: OasParameterLocation;
+    /** A brief description of the parameter */
     description?: string | undefined;
+    /** Determines whether this parameter is mandatory */
     required?: boolean | undefined;
+    /** Specifies that the parameter is deprecated */
     deprecated?: boolean | undefined;
+    /** Whether to allow empty values for the parameter */
     allowEmptyValue?: boolean | undefined;
+    /** Whether reserved characters are allowed in the parameter value */
     allowReserved?: boolean | undefined;
+    /** The schema defining the parameter's data type */
     schema?: OasSchema | OasRef<'schema'> | undefined;
+    /** Example values for the parameter */
     examples?: Record<string, OasExample | OasRef<'example'>> | undefined;
+    /** Media type definitions for the parameter content */
     content?: Record<string, OasMediaType> | undefined;
+    /** The serialization style for the parameter */
     style: OasParameterStyle;
+    /** Whether to explode parameter values */
     explode: boolean;
+    /** Custom extension fields (x-* properties) */
     extensionFields?: Record<string, unknown>;
 };
+/**
+ * Represents a Parameter Object in the OpenAPI Specification.
+ *
+ * The `OasParameter` class encapsulates the definition of a single operation parameter,
+ * including its location, data type, validation rules, and serialization behavior.
+ * Parameters can be located in the path, query string, headers, or cookies.
+ *
+ * This class provides comprehensive support for parameter validation, serialization
+ * styles, and complex data types through schema definitions or content specifications.
+ *
+ * ## Key Features
+ *
+ * - **Location Support**: Path, query, header, and cookie parameters
+ * - **Schema Validation**: Comprehensive data type validation through schemas
+ * - **Serialization Styles**: Various parameter serialization formats
+ * - **Content Types**: Support for complex parameter content with media types
+ * - **Examples & Documentation**: Parameter examples and descriptive documentation
+ * - **Advanced Options**: Empty values, reserved characters, and explode behavior
+ *
+ * @example Basic path parameter
+ * ```typescript
+ * import { OasParameter, OasString } from '@skmtc/core';
+ *
+ * const userIdParam = new OasParameter({
+ *   name: 'userId',
+ *   location: 'path',
+ *   description: 'Unique identifier for the user',
+ *   required: true,
+ *   schema: new OasString({
+ *     pattern: '^[0-9a-f]{24}$',
+ *     example: '507f1f77bcf86cd799439011'
+ *   }),
+ *   style: 'simple',
+ *   explode: false
+ * });
+ *
+ * // Used in path: /users/{userId}
+ * ```
+ *
+ * @example Query parameter with validation
+ * ```typescript
+ * const pageSizeParam = new OasParameter({
+ *   name: 'pageSize',
+ *   location: 'query',
+ *   description: 'Number of items to return per page',
+ *   required: false,
+ *   schema: new OasInteger({
+ *     minimum: 1,
+ *     maximum: 100,
+ *     default: 20
+ *   }),
+ *   style: 'form',
+ *   explode: true,
+ *   examples: {
+ *     small: new OasExample({ value: 10 }),
+ *     medium: new OasExample({ value: 25 }),
+ *     large: new OasExample({ value: 50 })
+ *   }
+ * });
+ *
+ * // Used in query: ?pageSize=20
+ * ```
+ *
+ * @example Header parameter
+ * ```typescript
+ * const authHeaderParam = new OasParameter({
+ *   name: 'Authorization',
+ *   location: 'header',
+ *   description: 'Bearer token for authentication',
+ *   required: true,
+ *   schema: new OasString({
+ *     pattern: '^Bearer [A-Za-z0-9+/=]+$',
+ *     example: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
+ *   }),
+ *   style: 'simple',
+ *   explode: false
+ * });
+ * ```
+ *
+ * @example Complex parameter with content
+ * ```typescript
+ * const filterParam = new OasParameter({
+ *   name: 'filter',
+ *   location: 'query',
+ *   description: 'Complex filter object',
+ *   required: false,
+ *   content: {
+ *     'application/json': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           category: new OasString(),
+ *           priceRange: new OasObject({
+ *             properties: {
+ *               min: new OasNumber(),
+ *               max: new OasNumber()
+ *             }
+ *           })
+ *         }
+ *       })
+ *     })
+ *   },
+ *   style: 'deepObject',
+ *   explode: true
+ * });
+ *
+ * // Used as: ?filter[category]=electronics&filter[priceRange][min]=100
+ * ```
+ *
+ * @example Array parameter with explode
+ * ```typescript
+ * const tagsParam = new OasParameter({
+ *   name: 'tags',
+ *   location: 'query',
+ *   description: 'Filter by multiple tags',
+ *   required: false,
+ *   schema: new OasArray({
+ *     items: new OasString(),
+ *     minItems: 1,
+ *     maxItems: 10
+ *   }),
+ *   style: 'form',
+ *   explode: true // Results in: ?tags=tech&tags=api&tags=rest
+ * });
+ *
+ * // Without explode: ?tags=tech,api,rest
+ * // With explode: ?tags=tech&tags=api&tags=rest
+ * ```
+ *
+ * @example Cookie parameter
+ * ```typescript
+ * const sessionParam = new OasParameter({
+ *   name: 'sessionId',
+ *   location: 'cookie',
+ *   description: 'Session identifier cookie',
+ *   required: false,
+ *   schema: new OasString({
+ *     minLength: 32,
+ *     maxLength: 128
+ *   }),
+ *   style: 'form',
+ *   explode: false
+ * });
+ * ```
+ */
 export declare class OasParameter {
     oasType: 'parameter';
     name: string;

package/script/oas/parameter/Parameter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Parameter.d.ts","sourceRoot":"","sources":["../../../src/oas/parameter/Parameter.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AACnF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAK9C,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,oBAAoB,CAAA;IAC9B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC9B,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAChC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACrC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACnC,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,SAAS,CAAA;IAClD,KAAK,EAAE,iBAAiB,CAAA;IACxB,OAAO,EAAE,OAAO,CAAA;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED,qBAAa,YAAY;IACvB,OAAO,EAAE,WAAW,CAAc;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,oBAAoB,CAAA;IAC9B,WAAW,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAC9B,UAAU,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IAChC,eAAe,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACrC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACnC,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAA;IACjD,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,GAAG,SAAS,CAAA;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,GAAG,SAAS,CAAA;IAClD,KAAK,EAAE,iBAAiB,CAAA;IACxB,OAAO,EAAE,OAAO,CAAA;IAChB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;gBACxC,MAAM,EAAE,eAAe;IAkBnC,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,WAAW,CAAC;IAIpC,OAAO,IAAI,YAAY;IAIvB,WAAW,IAAI,YAAY;IAI3B,QAAQ,CAAC,SAAS,GAAE,MAA2B,GAAG,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC;IAc9E,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAAC,eAAe;CAuBtE"}
+{"version":3,"file":"Parameter.d.ts","sourceRoot":"","sources":["../../../src/oas/parameter/Parameter.ts"],"names":[],"mappings":"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"}

package/script/oas/parameter/Parameter.js

@@ -2,6 +2,150 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OasParameter = void 0;
 require("../../_dnt.polyfills.js");
+/**
+ * Represents a Parameter Object in the OpenAPI Specification.
+ *
+ * The `OasParameter` class encapsulates the definition of a single operation parameter,
+ * including its location, data type, validation rules, and serialization behavior.
+ * Parameters can be located in the path, query string, headers, or cookies.
+ *
+ * This class provides comprehensive support for parameter validation, serialization
+ * styles, and complex data types through schema definitions or content specifications.
+ *
+ * ## Key Features
+ *
+ * - **Location Support**: Path, query, header, and cookie parameters
+ * - **Schema Validation**: Comprehensive data type validation through schemas
+ * - **Serialization Styles**: Various parameter serialization formats
+ * - **Content Types**: Support for complex parameter content with media types
+ * - **Examples & Documentation**: Parameter examples and descriptive documentation
+ * - **Advanced Options**: Empty values, reserved characters, and explode behavior
+ *
+ * @example Basic path parameter
+ * ```typescript
+ * import { OasParameter, OasString } from '@skmtc/core';
+ *
+ * const userIdParam = new OasParameter({
+ *   name: 'userId',
+ *   location: 'path',
+ *   description: 'Unique identifier for the user',
+ *   required: true,
+ *   schema: new OasString({
+ *     pattern: '^[0-9a-f]{24}$',
+ *     example: '507f1f77bcf86cd799439011'
+ *   }),
+ *   style: 'simple',
+ *   explode: false
+ * });
+ *
+ * // Used in path: /users/{userId}
+ * ```
+ *
+ * @example Query parameter with validation
+ * ```typescript
+ * const pageSizeParam = new OasParameter({
+ *   name: 'pageSize',
+ *   location: 'query',
+ *   description: 'Number of items to return per page',
+ *   required: false,
+ *   schema: new OasInteger({
+ *     minimum: 1,
+ *     maximum: 100,
+ *     default: 20
+ *   }),
+ *   style: 'form',
+ *   explode: true,
+ *   examples: {
+ *     small: new OasExample({ value: 10 }),
+ *     medium: new OasExample({ value: 25 }),
+ *     large: new OasExample({ value: 50 })
+ *   }
+ * });
+ *
+ * // Used in query: ?pageSize=20
+ * ```
+ *
+ * @example Header parameter
+ * ```typescript
+ * const authHeaderParam = new OasParameter({
+ *   name: 'Authorization',
+ *   location: 'header',
+ *   description: 'Bearer token for authentication',
+ *   required: true,
+ *   schema: new OasString({
+ *     pattern: '^Bearer [A-Za-z0-9+/=]+$',
+ *     example: 'Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
+ *   }),
+ *   style: 'simple',
+ *   explode: false
+ * });
+ * ```
+ *
+ * @example Complex parameter with content
+ * ```typescript
+ * const filterParam = new OasParameter({
+ *   name: 'filter',
+ *   location: 'query',
+ *   description: 'Complex filter object',
+ *   required: false,
+ *   content: {
+ *     'application/json': new OasMediaType({
+ *       schema: new OasObject({
+ *         properties: {
+ *           category: new OasString(),
+ *           priceRange: new OasObject({
+ *             properties: {
+ *               min: new OasNumber(),
+ *               max: new OasNumber()
+ *             }
+ *           })
+ *         }
+ *       })
+ *     })
+ *   },
+ *   style: 'deepObject',
+ *   explode: true
+ * });
+ *
+ * // Used as: ?filter[category]=electronics&filter[priceRange][min]=100
+ * ```
+ *
+ * @example Array parameter with explode
+ * ```typescript
+ * const tagsParam = new OasParameter({
+ *   name: 'tags',
+ *   location: 'query',
+ *   description: 'Filter by multiple tags',
+ *   required: false,
+ *   schema: new OasArray({
+ *     items: new OasString(),
+ *     minItems: 1,
+ *     maxItems: 10
+ *   }),
+ *   style: 'form',
+ *   explode: true // Results in: ?tags=tech&tags=api&tags=rest
+ * });
+ *
+ * // Without explode: ?tags=tech,api,rest
+ * // With explode: ?tags=tech&tags=api&tags=rest
+ * ```
+ *
+ * @example Cookie parameter
+ * ```typescript
+ * const sessionParam = new OasParameter({
+ *   name: 'sessionId',
+ *   location: 'cookie',
+ *   description: 'Session identifier cookie',
+ *   required: false,
+ *   schema: new OasString({
+ *     minLength: 32,
+ *     maxLength: 128
+ *   }),
+ *   style: 'form',
+ *   explode: false
+ * });
+ * ```
+ */
 class OasParameter {
     constructor(fields) {
         Object.defineProperty(this, "oasType", {