@skmtc/core 0.0.787 → 0.0.789

package/script/oas/components/Components.d.ts

@@ -9,29 +9,279 @@ import type { OasRef } from '../ref/Ref.js';
 import type { OasSchema } from '../schema/Schema.js';
 import type { RefName } from '../../types/RefName.js';
 import type { OasSecurityScheme } from '../securitySchemes/SecurityScheme.js';
+/**
+ * Available component types in an OpenAPI document.
+ */
 export declare const componentsKeys: string[];
+/**
+ * Constructor fields for {@link OasComponents}.
+ */
 export type ComponentsFields = {
+    /** Reusable schema components */
     schemas?: Record<RefName, OasSchema | OasRef<'schema'>>;
+    /** Reusable response components */
     responses?: Record<RefName, OasResponse | OasRef<'response'>>;
+    /** Reusable parameter components */
     parameters?: Record<RefName, OasParameter | OasRef<'parameter'>>;
+    /** Reusable example components */
     examples?: Record<RefName, OasExample | OasRef<'example'>>;
+    /** Reusable request body components */
     requestBodies?: Record<RefName, OasRequestBody | OasRef<'requestBody'>>;
+    /** Reusable header components */
     headers?: Record<RefName, OasHeader | OasRef<'header'>>;
+    /** Reusable security scheme components */
     securitySchemes?: Record<string, OasSecurityScheme | OasRef<'securityScheme'>>;
+    /** Custom extension fields (x-* properties) */
     extensionFields?: Record<string, unknown>;
 };
-/** 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}`);
+ *       });
+ *     }
+ *   }
+ * }
+ * ```
  */
 export declare class OasComponents {
     #private;
     /** Static identifier property for OasComponents */
     oasType: "components";
+    /**
+     * 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?: ComponentsFields);
+    /**
+     * 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(): RefName[];
     /** Record holding re-usable {@link OasSchema} objects or Refs  */
     get schemas(): Record<RefName, OasSchema | OasRef<'schema'>> | undefined;
+    /**
+     * 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: RefName): OasSchema | OasRef<'schema'>;
     /** Record holding re-usable {@link OasResponse} objects or Refs  */
     get responses(): Record<RefName, OasResponse | OasRef<'response'>> | undefined;

package/script/oas/components/Components.d.ts.map

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

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/operation/Operation.d.ts

@@ -30,7 +30,113 @@ type ToRequestBodyMapArgs = {
     schema: OasSchema | OasRef<'schema'>;
     requestBody: OasRequestBody;
 };
-/** Operation represents a resource path and a method that can be enacted against it */
+/**
+ * Represents an OpenAPI Operation Object in the SKMTC OAS processing system.
+ *
+ * The `OasOperation` class encapsulates a single API operation (path + method combination)
+ * with all its associated metadata, parameters, request/response specifications, and
+ * security requirements. It provides utilities for extracting common operation data
+ * like success responses and request bodies.
+ *
+ * ## Key Features
+ *
+ * - **Path and Method**: Unique combination identifying the operation
+ * - **Metadata Access**: Operation ID, summary, description, tags, and deprecation status
+ * - **Parameter Handling**: Query, path, header, and cookie parameters
+ * - **Request/Response Specs**: Type-safe access to request body and response definitions
+ * - **Security Context**: Operation-specific security requirements
+ * - **Success Response Utils**: Helper methods to identify and extract successful responses
+ *
+ * @example Basic operation properties
+ * ```typescript
+ * import { OasOperation } from '@skmtc/core';
+ *
+ * // Typically created during document parsing
+ * const getUserOp = new OasOperation({
+ *   path: '/users/{id}',
+ *   method: 'get',
+ *   operationId: 'getUserById',
+ *   summary: 'Get user by ID',
+ *   description: 'Retrieves a single user by their unique identifier',
+ *   parameters: [
+ *     // Path parameter for user ID
+ *     { name: 'id', in: 'path', required: true, schema: { type: 'string' } }
+ *   ],
+ *   responses: {
+ *     '200': { description: 'User found', content: { ... } },
+ *     '404': { description: 'User not found' }
+ *   }
+ * });
+ *
+ * console.log(getUserOp.path);        // '/users/{id}'
+ * console.log(getUserOp.method);      // 'get'
+ * console.log(getUserOp.operationId); // 'getUserById'
+ * ```
+ *
+ * @example Working with success responses
+ * ```typescript
+ * // Find the primary success response
+ * const successResponse = operation.toSuccessResponse();
+ * if (successResponse) {
+ *   const resolved = successResponse.resolve();
+ *   console.log('Success response:', resolved.description);
+ * }
+ *
+ * // Get the HTTP status code for success
+ * const successCode = operation.toSuccessResponseCode();
+ * console.log('Success status:', successCode); // '200', '201', 'default', etc.
+ * ```
+ *
+ * @example Extracting request body data
+ * ```typescript
+ * // Extract request body with custom transformation
+ * const requestData = operation.toRequestBody(({ schema, requestBody }) => {
+ *   return {
+ *     schema: schema,
+ *     contentType: 'application/json',
+ *     required: requestBody.required ?? false,
+ *     description: requestBody.description
+ *   };
+ * });
+ *
+ * if (requestData) {
+ *   console.log('Request schema:', requestData.schema);
+ *   console.log('Required:', requestData.required);
+ * }
+ * ```
+ *
+ * @example Parameter processing
+ * ```typescript
+ * // Process operation parameters by location
+ * const pathParams = operation.parameters?.filter(param => {
+ *   const resolved = param.resolve();
+ *   return resolved.in === 'path';
+ * });
+ *
+ * const queryParams = operation.parameters?.filter(param => {
+ *   const resolved = param.resolve();
+ *   return resolved.in === 'query';
+ * });
+ *
+ * console.log('Path parameters:', pathParams?.length);
+ * console.log('Query parameters:', queryParams?.length);
+ * ```
+ *
+ * @example Security requirements
+ * ```typescript
+ * if (operation.security) {
+ *   console.log('Operation has specific security requirements');
+ *   for (const requirement of operation.security) {
+ *     // Process security schemes for this operation
+ *     Object.keys(requirement.schemes).forEach(scheme => {
+ *       console.log(`Security scheme: ${scheme}`);
+ *     });
+ *   }
+ * } else {
+ *   console.log('Operation uses default document security');
+ * }
+ * ```
+ */
 export declare class OasOperation {
     oasType: 'operation';
     path: string;

package/script/oas/operation/Operation.d.ts.map

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