@skmtc/core 0.0.787 → 0.0.789

package/esm/oas/operation/Operation.js

@@ -1,6 +1,112 @@
 import "../../_dnt.polyfills.js";
 import { OasObject } from '../object/Object.js';
-/** 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 class OasOperation {
     constructor(fields) {
         Object.defineProperty(this, "oasType", {

package/esm/oas/ref/Ref.d.ts

@@ -14,6 +14,92 @@ export type RefFields<T extends OasRefData['refType']> = {
     refType: T;
     $ref: string;
 };
+/**
+ * Represents an OpenAPI reference ($ref) in the SKMTC OAS processing system.
+ *
+ * The `OasRef` class handles OpenAPI JSON Reference Objects that point to reusable
+ * components within the same document. It provides type-safe reference resolution
+ * with support for chained references and circular reference detection.
+ *
+ * ## Key Features
+ *
+ * - **Type Safety**: Generic parameter ensures resolved types match the reference type
+ * - **Lazy Resolution**: References are resolved on-demand, not during construction
+ * - **Chain Resolution**: Handles references that point to other references
+ * - **Circular Detection**: Prevents infinite loops with maximum lookup limits
+ * - **Type Validation**: Ensures resolved objects match expected reference types
+ *
+ * @template T - The type of component this reference points to
+ *
+ * @example Basic reference resolution
+ * ```typescript
+ * import { OasRef } from '@skmtc/core';
+ *
+ * // Reference to a schema component
+ * const userRef = new OasRef<'schema'>({
+ *   refType: 'schema',
+ *   $ref: '#/components/schemas/User'
+ * }, document);
+ *
+ * // Resolve the reference
+ * const userSchema = userRef.resolve();
+ * console.log(userSchema.properties); // Access resolved schema properties
+ * ```
+ *
+ * @example Working with different reference types
+ * ```typescript
+ * // Schema reference
+ * const schemaRef = new OasRef<'schema'>({
+ *   refType: 'schema',
+ *   $ref: '#/components/schemas/Product'
+ * }, document);
+ *
+ * // Response reference
+ * const responseRef = new OasRef<'response'>({
+ *   refType: 'response',
+ *   $ref: '#/components/responses/ErrorResponse'
+ * }, document);
+ *
+ * // Parameter reference
+ * const paramRef = new OasRef<'parameter'>({
+ *   refType: 'parameter',
+ *   $ref: '#/components/parameters/PageSize'
+ * }, document);
+ * ```
+ *
+ * @example Reference checking and conditional resolution
+ * ```typescript
+ * function processSchemaOrRef(schema: OasSchema | OasRef<'schema'>) {
+ *   if (schema.isRef()) {
+ *     // Handle reference
+ *     const refName = schema.toRefName();
+ *     console.log(`Processing reference: ${refName}`);
+ *
+ *     // Resolve only when needed
+ *     const resolved = schema.resolve();
+ *     return processed(resolved);
+ *   } else {
+ *     // Handle direct schema
+ *     return process(schema);
+ *   }
+ * }
+ * ```
+ *
+ * @example Chained reference handling
+ * ```typescript
+ * // References can point to other references
+ * const chainedRef = new OasRef<'schema'>({
+ *   refType: 'schema',
+ *   $ref: '#/components/schemas/AliasToUser'
+ * }, document);
+ *
+ * // resolve() automatically follows the chain
+ * const finalSchema = chainedRef.resolve(); // Follows chain to final schema
+ *
+ * // resolveOnce() resolves only one step
+ * const oneStep = chainedRef.resolveOnce(); // May still be a reference
+ * ```
+ */
 export declare class OasRef<T extends OasRefData['refType']> {
     #private;
     oasType: 'ref';

package/esm/oas/ref/Ref.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Ref.d.ts","sourceRoot":"","sources":["../../../src/oas/ref/Ref.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAGhD,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAA;AAI7E,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,UAAU,CAAC,SAAS,CAAC,IAAI;IACvD,OAAO,EAAE,CAAC,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED,qBAAa,MAAM,CAAC,CAAC,SAAS,UAAU,CAAC,SAAS,CAAC;;IACjD,OAAO,EAAE,KAAK,CAAQ;IACtB,IAAI,EAAE,KAAK,CAAQ;gBAIP,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW;IAK1D,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC;IAI1B,OAAO,CAAC,gBAAgB,GAAE,MAAU,GAAG,WAAW,CAAC,CAAC,CAAC;IAUrD,WAAW,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC;IAsCzC,SAAS,IAAI,OAAO;IAIpB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,OAAO,IAAI,UAAU,CAAC,SAAS,CAAC,CAEnC;IAED,IAAI,WAAW,IAAI,WAAW,CAE7B;IAED,YAAY,CAAC,EACX,OAAO,EACR,EAAE,mBAAmB,GAAG,SAAS,CAAC,eAAe,GAAG,mBAAmB,CAAC,CAAC,CAAC;IAsB3E,MAAM,IAAI,MAAM;CAajB;AAED,KAAK,mBAAmB,CAAC,CAAC,SAAS,UAAU,CAAC,SAAS,CAAC,IAAI,UAAU,CACpE,WAAW,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAC/B,CAAA;AAED,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,WAAW,GACX,YAAY,GACZ,UAAU,GACV,cAAc,GACd,SAAS,GACT,iBAAiB,CAAA;AAErB,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,UAAU,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,gBAAgB,EAAE;IAAE,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC,CAAA"}
+{"version":3,"file":"Ref.d.ts","sourceRoot":"","sources":["../../../src/oas/ref/Ref.ts"],"names":[],"mappings":"AAAA,OAAO,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAGhD,OAAO,KAAK,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AACzE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAA;AAC7D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAA;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAA;AACnE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAA;AAC1D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAA;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAA;AAI7E,MAAM,MAAM,SAAS,CAAC,CAAC,SAAS,UAAU,CAAC,SAAS,CAAC,IAAI;IACvD,OAAO,EAAE,CAAC,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;CACb,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqFG;AACH,qBAAa,MAAM,CAAC,CAAC,SAAS,UAAU,CAAC,SAAS,CAAC;;IACjD,OAAO,EAAE,KAAK,CAAQ;IACtB,IAAI,EAAE,KAAK,CAAQ;gBAIP,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,WAAW;IAK1D,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,CAAC,CAAC;IAI1B,OAAO,CAAC,gBAAgB,GAAE,MAAU,GAAG,WAAW,CAAC,CAAC,CAAC;IAUrD,WAAW,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC;IAsCzC,SAAS,IAAI,OAAO;IAIpB,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,OAAO,IAAI,UAAU,CAAC,SAAS,CAAC,CAEnC;IAED,IAAI,WAAW,IAAI,WAAW,CAE7B;IAED,YAAY,CAAC,EACX,OAAO,EACR,EAAE,mBAAmB,GAAG,SAAS,CAAC,eAAe,GAAG,mBAAmB,CAAC,CAAC,CAAC;IAsB3E,MAAM,IAAI,MAAM;CAajB;AAED,KAAK,mBAAmB,CAAC,CAAC,SAAS,UAAU,CAAC,SAAS,CAAC,IAAI,UAAU,CACpE,WAAW,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,CAC/B,CAAA;AAED,MAAM,MAAM,gBAAgB,GACxB,SAAS,GACT,WAAW,GACX,YAAY,GACZ,UAAU,GACV,cAAc,GACd,SAAS,GACT,iBAAiB,CAAA;AAErB,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,UAAU,CAAC,SAAS,CAAC,IAAI,OAAO,CAAC,gBAAgB,EAAE;IAAE,OAAO,EAAE,CAAC,CAAA;CAAE,CAAC,CAAA"}

package/esm/oas/ref/Ref.js

@@ -14,6 +14,92 @@ import "../../_dnt.polyfills.js";
 import { toRefName } from '../../helpers/refFns.js';
 import { match } from 'ts-pattern';
 const MAX_LOOKUPS = 10;
+/**
+ * Represents an OpenAPI reference ($ref) in the SKMTC OAS processing system.
+ *
+ * The `OasRef` class handles OpenAPI JSON Reference Objects that point to reusable
+ * components within the same document. It provides type-safe reference resolution
+ * with support for chained references and circular reference detection.
+ *
+ * ## Key Features
+ *
+ * - **Type Safety**: Generic parameter ensures resolved types match the reference type
+ * - **Lazy Resolution**: References are resolved on-demand, not during construction
+ * - **Chain Resolution**: Handles references that point to other references
+ * - **Circular Detection**: Prevents infinite loops with maximum lookup limits
+ * - **Type Validation**: Ensures resolved objects match expected reference types
+ *
+ * @template T - The type of component this reference points to
+ *
+ * @example Basic reference resolution
+ * ```typescript
+ * import { OasRef } from '@skmtc/core';
+ *
+ * // Reference to a schema component
+ * const userRef = new OasRef<'schema'>({
+ *   refType: 'schema',
+ *   $ref: '#/components/schemas/User'
+ * }, document);
+ *
+ * // Resolve the reference
+ * const userSchema = userRef.resolve();
+ * console.log(userSchema.properties); // Access resolved schema properties
+ * ```
+ *
+ * @example Working with different reference types
+ * ```typescript
+ * // Schema reference
+ * const schemaRef = new OasRef<'schema'>({
+ *   refType: 'schema',
+ *   $ref: '#/components/schemas/Product'
+ * }, document);
+ *
+ * // Response reference
+ * const responseRef = new OasRef<'response'>({
+ *   refType: 'response',
+ *   $ref: '#/components/responses/ErrorResponse'
+ * }, document);
+ *
+ * // Parameter reference
+ * const paramRef = new OasRef<'parameter'>({
+ *   refType: 'parameter',
+ *   $ref: '#/components/parameters/PageSize'
+ * }, document);
+ * ```
+ *
+ * @example Reference checking and conditional resolution
+ * ```typescript
+ * function processSchemaOrRef(schema: OasSchema | OasRef<'schema'>) {
+ *   if (schema.isRef()) {
+ *     // Handle reference
+ *     const refName = schema.toRefName();
+ *     console.log(`Processing reference: ${refName}`);
+ *
+ *     // Resolve only when needed
+ *     const resolved = schema.resolve();
+ *     return processed(resolved);
+ *   } else {
+ *     // Handle direct schema
+ *     return process(schema);
+ *   }
+ * }
+ * ```
+ *
+ * @example Chained reference handling
+ * ```typescript
+ * // References can point to other references
+ * const chainedRef = new OasRef<'schema'>({
+ *   refType: 'schema',
+ *   $ref: '#/components/schemas/AliasToUser'
+ * }, document);
+ *
+ * // resolve() automatically follows the chain
+ * const finalSchema = chainedRef.resolve(); // Follows chain to final schema
+ *
+ * // resolveOnce() resolves only one step
+ * const oneStep = chainedRef.resolveOnce(); // May still be a reference
+ * ```
+ */
 export class OasRef {
     constructor(fields, oasDocument) {
         Object.defineProperty(this, "oasType", {

package/esm/oas/union/Union.d.ts

@@ -3,24 +3,138 @@ import type { OasSchema } from '../schema/Schema.js';
 import type { OasRef } from '../ref/Ref.js';
 import type { ToJsonSchemaOptions } from '../schema/Schema.js';
 import type { OpenAPIV3 } from 'openapi-types';
+/**
+ * Constructor fields for {@link OasUnion}.
+ */
 export type UnionFields = {
+    /** A short summary of the union type */
     title?: string;
+    /** A description of the union type */
     description?: string;
+    /** Whether the union value can be null */
     nullable?: boolean;
+    /** Discriminator object for creating tagged unions */
     discriminator?: OasDiscriminator;
+    /** Example value for the union */
     example?: unknown;
+    /** Default value for the union */
     default?: unknown;
+    /** Array of schemas that make up the union members */
     members: (OasSchema | OasRef<'schema'>)[];
+    /** Custom extension fields (x-* properties) */
     extensionFields?: Record<string, unknown>;
 };
 /**
- * Object representing a 'oneOf' or 'anyOf' in the OpenAPI Specification.
+ * Represents a union type schema in the OpenAPI Specification.
+ *
+ * `OasUnion` handles both OpenAPI `oneOf` and `anyOf` constructs by mapping them
+ * to TypeScript union types. While OpenAPI distinguishes between these concepts,
+ * in TypeScript they both represent union types (A | B | C), making the distinction
+ * less meaningful for code generation.
+ *
+ * This class supports both simple unions and discriminated (tagged) unions through
+ * the discriminator property, which enables more precise type narrowing in generated code.
+ *
+ * ## Key Features
+ *
+ * - **Union Types**: Represents multiple possible schema types as a single union
+ * - **Tagged Unions**: Supports discriminator properties for type narrowing
+ * - **Reference Resolution**: Handles references to other schemas within union members
+ * - **Nullable Support**: Can represent nullable union types (A | B | null)
+ * - **JSON Schema**: Converts to standard JSON Schema format for validation
+ *
+ * @example Basic union type
+ * ```typescript
+ * import { OasUnion, OasString, OasInteger } from '@skmtc/core';
+ *
+ * const stringOrNumber = new OasUnion({
+ *   title: 'StringOrNumber',
+ *   description: 'A value that can be either a string or number',
+ *   members: [
+ *     new OasString({ title: 'String Value' }),
+ *     new OasInteger({ title: 'Integer Value' })
+ *   ]
+ * });
+ *
+ * // This represents: string | number
+ * ```
+ *
+ * @example Discriminated union (tagged union)
+ * ```typescript
+ * const shape = new OasUnion({
+ *   title: 'Shape',
+ *   description: 'Different types of geometric shapes',
+ *   discriminator: new OasDiscriminator({
+ *     propertyName: 'type',
+ *     mapping: {
+ *       'circle': '#/components/schemas/Circle',
+ *       'square': '#/components/schemas/Square'
+ *     }
+ *   }),
+ *   members: [
+ *     new OasRef({ $ref: '#/components/schemas/Circle' }),
+ *     new OasRef({ $ref: '#/components/schemas/Square' })
+ *   ]
+ * });
+ *
+ * // This creates a tagged union that can be narrowed by the 'type' property
+ * ```
+ *
+ * @example Nullable union
+ * ```typescript
+ * const nullableStatus = new OasUnion({
+ *   title: 'NullableStatus',
+ *   nullable: true,
+ *   members: [
+ *     new OasString({ enum: ['active', 'inactive'] }),
+ *     new OasString({ enum: ['pending', 'suspended'] })
+ *   ],
+ *   default: null
+ * });
+ *
+ * // This represents: ('active' | 'inactive' | 'pending' | 'suspended') | null
+ * ```
+ *
+ * @example Complex nested union
+ * ```typescript
+ * const apiResponse = new OasUnion({
+ *   title: 'ApiResponse',
+ *   description: 'Response from API endpoint',
+ *   members: [
+ *     new OasObject({
+ *       title: 'SuccessResponse',
+ *       properties: {
+ *         success: new OasBoolean({ default: true }),
+ *         data: new OasObject({ additionalProperties: true })
+ *       }
+ *     }),
+ *     new OasObject({
+ *       title: 'ErrorResponse',
+ *       properties: {
+ *         error: new OasString(),
+ *         code: new OasInteger()
+ *       }
+ *     })
+ *   ]
+ * });
+ *
+ * // This represents: { success: boolean; data: Record<string, any> } | { error: string; code: number }
+ * ```
  *
- * In the context of TypeScript 'anyOf' is not helpful since it implies
- * a union that consists of all possible combinations of member types.
+ * @example Using with references
+ * ```typescript
+ * const userOrAdmin = new OasUnion({
+ *   title: 'UserOrAdmin',
+ *   description: 'Either a regular user or an admin user',
+ *   members: [
+ *     new OasRef({ $ref: '#/components/schemas/User' }),
+ *     new OasRef({ $ref: '#/components/schemas/Admin' })
+ *   ]
+ * });
  *
- * Generating such combination types would not be useful and we map both
- * 'oneOf' and 'anyOf' to a TypeScript union type.
+ * // References will be resolved during processing
+ * // This represents: User | Admin
+ * ```
  */
 export declare class OasUnion {
     /**

package/esm/oas/union/Union.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Union.d.ts","sourceRoot":"","sources":["../../../src/oas/union/Union.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAA;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C,MAAM,MAAM,WAAW,GAAG;IACxB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,aAAa,CAAC,EAAE,gBAAgB,CAAA;IAChC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,OAAO,EAAE,CAAC,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAA;IACzC,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED;;;;;;;;GAQG;AACH,qBAAa,QAAQ;IACnB;;;OAGG;IACH,OAAO,EAAG,QAAQ,CAAS;IAC3B;;OAEG;IACH,IAAI,EAAG,OAAO,CAAS;IACvB;;OAEG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB;;OAEG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B;;OAEG;IACH,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B;;OAEG;IACH,aAAa,EAAE,gBAAgB,GAAG,SAAS,CAAA;IAC3C;;OAEG;IACH,OAAO,EAAE,CAAC,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAA;IAEzC,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACpD;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;gBAEL,MAAM,EAAE,WAAW;IAW/B,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC;IAIjC,OAAO,IAAI,QAAQ;IAInB,WAAW,IAAI,QAAQ;IAIvB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAAC,oBAAoB;CAU3E"}
+{"version":3,"file":"Union.d.ts","sourceRoot":"","sources":["../../../src/oas/union/Union.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mCAAmC,CAAA;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAA;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAC9D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAE9C;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,sDAAsD;IACtD,aAAa,CAAC,EAAE,gBAAgB,CAAA;IAChC,kCAAkC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,kCAAkC;IAClC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,sDAAsD;IACtD,OAAO,EAAE,CAAC,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAA;IACzC,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+GG;AACH,qBAAa,QAAQ;IACnB;;;OAGG;IACH,OAAO,EAAG,QAAQ,CAAS;IAC3B;;OAEG;IACH,IAAI,EAAG,OAAO,CAAS;IACvB;;OAEG;IACH,KAAK,EAAE,MAAM,GAAG,SAAS,CAAA;IACzB;;OAEG;IACH,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B;;OAEG;IACH,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAA;IAC7B;;OAEG;IACH,aAAa,EAAE,gBAAgB,GAAG,SAAS,CAAA;IAC3C;;OAEG;IACH,OAAO,EAAE,CAAC,SAAS,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAA;IAEzC,qCAAqC;IACrC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACpD;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;OAEG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;gBAEL,MAAM,EAAE,WAAW;IAW/B,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,QAAQ,CAAC;IAIjC,OAAO,IAAI,QAAQ;IAInB,WAAW,IAAI,QAAQ;IAIvB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,SAAS,CAAC,oBAAoB;CAU3E"}

package/esm/oas/union/Union.js

@@ -1,11 +1,114 @@
 /**
- * Object representing a 'oneOf' or 'anyOf' in the OpenAPI Specification.
+ * Represents a union type schema in the OpenAPI Specification.
  *
- * In the context of TypeScript 'anyOf' is not helpful since it implies
- * a union that consists of all possible combinations of member types.
+ * `OasUnion` handles both OpenAPI `oneOf` and `anyOf` constructs by mapping them
+ * to TypeScript union types. While OpenAPI distinguishes between these concepts,
+ * in TypeScript they both represent union types (A | B | C), making the distinction
+ * less meaningful for code generation.
  *
- * Generating such combination types would not be useful and we map both
- * 'oneOf' and 'anyOf' to a TypeScript union type.
+ * This class supports both simple unions and discriminated (tagged) unions through
+ * the discriminator property, which enables more precise type narrowing in generated code.
+ *
+ * ## Key Features
+ *
+ * - **Union Types**: Represents multiple possible schema types as a single union
+ * - **Tagged Unions**: Supports discriminator properties for type narrowing
+ * - **Reference Resolution**: Handles references to other schemas within union members
+ * - **Nullable Support**: Can represent nullable union types (A | B | null)
+ * - **JSON Schema**: Converts to standard JSON Schema format for validation
+ *
+ * @example Basic union type
+ * ```typescript
+ * import { OasUnion, OasString, OasInteger } from '@skmtc/core';
+ *
+ * const stringOrNumber = new OasUnion({
+ *   title: 'StringOrNumber',
+ *   description: 'A value that can be either a string or number',
+ *   members: [
+ *     new OasString({ title: 'String Value' }),
+ *     new OasInteger({ title: 'Integer Value' })
+ *   ]
+ * });
+ *
+ * // This represents: string | number
+ * ```
+ *
+ * @example Discriminated union (tagged union)
+ * ```typescript
+ * const shape = new OasUnion({
+ *   title: 'Shape',
+ *   description: 'Different types of geometric shapes',
+ *   discriminator: new OasDiscriminator({
+ *     propertyName: 'type',
+ *     mapping: {
+ *       'circle': '#/components/schemas/Circle',
+ *       'square': '#/components/schemas/Square'
+ *     }
+ *   }),
+ *   members: [
+ *     new OasRef({ $ref: '#/components/schemas/Circle' }),
+ *     new OasRef({ $ref: '#/components/schemas/Square' })
+ *   ]
+ * });
+ *
+ * // This creates a tagged union that can be narrowed by the 'type' property
+ * ```
+ *
+ * @example Nullable union
+ * ```typescript
+ * const nullableStatus = new OasUnion({
+ *   title: 'NullableStatus',
+ *   nullable: true,
+ *   members: [
+ *     new OasString({ enum: ['active', 'inactive'] }),
+ *     new OasString({ enum: ['pending', 'suspended'] })
+ *   ],
+ *   default: null
+ * });
+ *
+ * // This represents: ('active' | 'inactive' | 'pending' | 'suspended') | null
+ * ```
+ *
+ * @example Complex nested union
+ * ```typescript
+ * const apiResponse = new OasUnion({
+ *   title: 'ApiResponse',
+ *   description: 'Response from API endpoint',
+ *   members: [
+ *     new OasObject({
+ *       title: 'SuccessResponse',
+ *       properties: {
+ *         success: new OasBoolean({ default: true }),
+ *         data: new OasObject({ additionalProperties: true })
+ *       }
+ *     }),
+ *     new OasObject({
+ *       title: 'ErrorResponse',
+ *       properties: {
+ *         error: new OasString(),
+ *         code: new OasInteger()
+ *       }
+ *     })
+ *   ]
+ * });
+ *
+ * // This represents: { success: boolean; data: Record<string, any> } | { error: string; code: number }
+ * ```
+ *
+ * @example Using with references
+ * ```typescript
+ * const userOrAdmin = new OasUnion({
+ *   title: 'UserOrAdmin',
+ *   description: 'Either a regular user or an admin user',
+ *   members: [
+ *     new OasRef({ $ref: '#/components/schemas/User' }),
+ *     new OasRef({ $ref: '#/components/schemas/Admin' })
+ *   ]
+ * });
+ *
+ * // References will be resolved during processing
+ * // This represents: User | Admin
+ * ```
  */
 export class OasUnion {
     constructor(fields) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skmtc/core",
-  "version": "0.0.787",
+  "version": "0.0.789",
   "repository": {
     "type": "git",
     "url": "https://github.com/skmtc/skmtc.git"