@skmtc/core 0.0.791 → 0.0.793

package/script/helpers/parseModuleName.js

@@ -1,6 +1,159 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseModuleName = void 0;
+/**
+ * Parses a module name string into its component parts.
+ *
+ * This utility function decomposes module names from various formats into
+ * structured components, handling schemes, scopes, versions, and package names.
+ * It supports formats used by npm, JSR, Deno, and other package managers.
+ *
+ * The parser handles complex module name patterns including:
+ * - Scheme prefixes (jsr:, npm:, https:)
+ * - Scoped packages (@scope/package)
+ * - Version specifiers (@version)
+ * - Combinations of the above
+ *
+ * @param moduleName - The module name string to parse
+ * @returns Parsed components of the module name
+ *
+ * @example Basic package names
+ * ```typescript
+ * import { parseModuleName } from '@skmtc/core';
+ *
+ * // Simple package name
+ * const simple = parseModuleName('lodash');
+ * // {
+ * //   scheme: null,
+ * //   scopeName: null,
+ * //   packageName: 'lodash',
+ * //   version: null
+ * // }
+ *
+ * // Package with version
+ * const versioned = parseModuleName('lodash@4.17.21');
+ * // {
+ * //   scheme: null,
+ * //   scopeName: null,
+ * //   packageName: 'lodash',
+ * //   version: '4.17.21'
+ * // }
+ * ```
+ *
+ * @example Scoped packages
+ * ```typescript
+ * // Scoped package
+ * const scoped = parseModuleName('@company/utils');
+ * // {
+ * //   scheme: null,
+ * //   scopeName: '@company',
+ * //   packageName: 'utils',
+ * //   version: null
+ * // }
+ *
+ * // Scoped package with version
+ * const scopedVersioned = parseModuleName('@company/utils@2.0.0');
+ * // {
+ * //   scheme: null,
+ * //   scopeName: '@company',
+ * //   packageName: 'utils',
+ * //   version: '2.0.0'
+ * // }
+ * ```
+ *
+ * @example Scheme-prefixed modules
+ * ```typescript
+ * // JSR module
+ * const jsrModule = parseModuleName('jsr:@std/path@1.0.0');
+ * // {
+ * //   scheme: 'jsr',
+ * //   scopeName: '@std',
+ * //   packageName: 'path',
+ * //   version: '1.0.0'
+ * // }
+ *
+ * // npm module with scheme
+ * const npmModule = parseModuleName('npm:lodash@^4.17.0');
+ * // {
+ * //   scheme: 'npm',
+ * //   scopeName: null,
+ * //   packageName: 'lodash',
+ * //   version: '^4.17.0'
+ * // }
+ *
+ * // HTTPS module
+ * const httpsModule = parseModuleName('https:example.com/package@v1.2.3');
+ * // {
+ * //   scheme: 'https',
+ * //   scopeName: null,
+ * //   packageName: 'example.com/package',
+ * //   version: 'v1.2.3'
+ * // }
+ * ```
+ *
+ * @example Complex parsing scenarios
+ * ```typescript
+ * // Multiple levels in package name
+ * const nested = parseModuleName('npm:@babel/plugin-transform-runtime@^7.0.0');
+ * // {
+ * //   scheme: 'npm',
+ * //   scopeName: '@babel',
+ * //   packageName: 'plugin-transform-runtime',
+ * //   version: '^7.0.0'
+ * // }
+ *
+ * // Version ranges and pre-release versions
+ * const prerelease = parseModuleName('jsr:@deno/std@1.0.0-rc.1');
+ * // {
+ * //   scheme: 'jsr',
+ * //   scopeName: '@deno',
+ * //   packageName: 'std',
+ * //   version: '1.0.0-rc.1'
+ * // }
+ * ```
+ *
+ * @example Usage in dependency management
+ * ```typescript
+ * class DependencyManager {
+ *   processDependency(moduleSpec: string) {
+ *     const parsed = parseModuleName(moduleSpec);
+ *
+ *     console.log(`Processing ${parsed.packageName}`);
+ *
+ *     if (parsed.scheme) {
+ *       console.log(`Using ${parsed.scheme} registry`);
+ *     }
+ *
+ *     if (parsed.scopeName) {
+ *       console.log(`Scoped package: ${parsed.scopeName}/${parsed.packageName}`);
+ *     }
+ *
+ *     if (parsed.version) {
+ *       console.log(`Version constraint: ${parsed.version}`);
+ *     }
+ *
+ *     return this.resolvePackage(parsed);
+ *   }
+ * }
+ * ```
+ *
+ * @example Building module URLs
+ * ```typescript
+ * function buildModuleUrl(moduleSpec: string): string {
+ *   const parsed = parseModuleName(moduleSpec);
+ *
+ *   switch (parsed.scheme) {
+ *     case 'jsr':
+ *       return `https://jsr.io/${parsed.scopeName}/${parsed.packageName}`;
+ *     case 'npm':
+ *       const scope = parsed.scopeName ? `${parsed.scopeName}/` : '';
+ *       return `https://npmjs.com/package/${scope}${parsed.packageName}`;
+ *     default:
+ *       return `https://deno.land/x/${parsed.packageName}`;
+ *   }
+ * }
+ * ```
+ */
 const parseModuleName = (moduleName) => {
     const result = {
         scheme: null,

package/script/helpers/toResolvedArtifactPath.d.ts

@@ -1,8 +1,153 @@
 import "../_dnt.polyfills.js";
+/**
+ * Arguments for resolving artifact file paths.
+ */
 type ToResolvedArtifactPathArgs = {
+    /** The base directory path for resolving relative paths */
     basePath: string | undefined;
+    /** The destination path for the artifact file */
     destinationPath: string;
 };
+/**
+ * Resolves artifact destination paths relative to a base directory.
+ *
+ * This utility function combines a base path with a destination path to create
+ * the final resolved file path for generated artifacts. It handles special path
+ * prefixes (like '@/') and provides sensible defaults when no base path is specified.
+ *
+ * The function is used throughout the rendering pipeline to determine the final
+ * file system locations for generated code artifacts, ensuring consistent path
+ * resolution across different operating systems and deployment scenarios.
+ *
+ * @param args - Path resolution configuration
+ * @param args.basePath - Base directory path (defaults to './' if undefined)
+ * @param args.destinationPath - Destination path for the artifact
+ * @returns The resolved absolute or relative path for the artifact
+ *
+ * @example Basic path resolution
+ * ```typescript
+ * import { toResolvedArtifactPath } from '@skmtc/core';
+ *
+ * // With explicit base path
+ * const resolved1 = toResolvedArtifactPath({
+ *   basePath: './src/generated',
+ *   destinationPath: 'models/User.ts'
+ * });
+ * console.log(resolved1); // './src/generated/models/User.ts'
+ *
+ * // With undefined base path (uses default)
+ * const resolved2 = toResolvedArtifactPath({
+ *   basePath: undefined,
+ *   destinationPath: 'types.ts'
+ * });
+ * console.log(resolved2); // './types.ts'
+ * ```
+ *
+ * @example Special path prefix handling
+ * ```typescript
+ * // '@/' prefix gets stripped and resolved relative to base
+ * const resolved = toResolvedArtifactPath({
+ *   basePath: './output',
+ *   destinationPath: '@/api/models.ts'
+ * });
+ * console.log(resolved); // './output/api/models.ts'
+ *
+ * // Regular paths work normally
+ * const normal = toResolvedArtifactPath({
+ *   basePath: './build',
+ *   destinationPath: 'components/Button.tsx'
+ * });
+ * console.log(normal); // './build/components/Button.tsx'
+ * ```
+ *
+ * @example Cross-platform path resolution
+ * ```typescript
+ * // Works consistently across platforms
+ * const windowsPath = toResolvedArtifactPath({
+ *   basePath: 'C:\\projects\\app\\dist',
+ *   destinationPath: 'utils/helpers.js'
+ * });
+ *
+ * const unixPath = toResolvedArtifactPath({
+ *   basePath: '/home/user/projects/app/dist',
+ *   destinationPath: 'utils/helpers.js'
+ * });
+ * ```
+ *
+ * @example Usage in file generation
+ * ```typescript
+ * class ArtifactWriter {
+ *   writeArtifact(
+ *     content: string,
+ *     destination: string,
+ *     baseDir?: string
+ *   ) {
+ *     const resolvedPath = toResolvedArtifactPath({
+ *       basePath: baseDir,
+ *       destinationPath: destination
+ *     });
+ *
+ *     console.log(`Writing to: ${resolvedPath}`);
+ *     return Deno.writeTextFile(resolvedPath, content);
+ *   }
+ * }
+ *
+ * const writer = new ArtifactWriter();
+ * await writer.writeArtifact(
+ *   'export const greeting = "Hello";',
+ *   '@/constants.ts',
+ *   './src/generated'
+ * );
+ * // Writes to: ./src/generated/constants.ts
+ * ```
+ *
+ * @example Integration with rendering pipeline
+ * ```typescript
+ * class FileRenderer {
+ *   renderFiles(
+ *     files: Map<string, File>,
+ *     outputDir: string
+ *   ): Record<string, string> {
+ *     const artifacts: Record<string, string> = {};
+ *
+ *     for (const [destPath, file] of files) {
+ *       const resolvedPath = toResolvedArtifactPath({
+ *         basePath: outputDir,
+ *         destinationPath: destPath
+ *       });
+ *
+ *       artifacts[resolvedPath] = file.toString();
+ *     }
+ *
+ *     return artifacts;
+ *   }
+ * }
+ * ```
+ *
+ * @example Dynamic base path resolution
+ * ```typescript
+ * function resolveForEnvironment(
+ *   destination: string,
+ *   env: 'development' | 'production'
+ * ): string {
+ *   const basePaths = {
+ *     development: './dev-output',
+ *     production: './dist'
+ *   };
+ *
+ *   return toResolvedArtifactPath({
+ *     basePath: basePaths[env],
+ *     destinationPath: destination
+ *   });
+ * }
+ *
+ * const devPath = resolveForEnvironment('api.ts', 'development');
+ * const prodPath = resolveForEnvironment('api.ts', 'production');
+ *
+ * console.log(devPath);  // './dev-output/api.ts'
+ * console.log(prodPath); // './dist/api.ts'
+ * ```
+ */
 export declare const toResolvedArtifactPath: ({ basePath, destinationPath }: ToResolvedArtifactPathArgs) => string;
 export {};
 //# sourceMappingURL=toResolvedArtifactPath.d.ts.map

package/script/helpers/toResolvedArtifactPath.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"toResolvedArtifactPath.d.ts","sourceRoot":"","sources":["../../src/helpers/toResolvedArtifactPath.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAE9B,KAAK,0BAA0B,GAAG;IAChC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,eAAe,EAAE,MAAM,CAAA;CACxB,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,+BAGpC,0BAA0B,KAAG,MAE/B,CAAA"}
+{"version":3,"file":"toResolvedArtifactPath.d.ts","sourceRoot":"","sources":["../../src/helpers/toResolvedArtifactPath.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAG9B;;GAEG;AACH,KAAK,0BAA0B,GAAG;IAChC,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,iDAAiD;IACjD,eAAe,EAAE,MAAM,CAAA;CACxB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2IG;AACH,eAAO,MAAM,sBAAsB,GAAI,+BAGpC,0BAA0B,KAAG,MAE/B,CAAA"}

package/script/helpers/toResolvedArtifactPath.js

@@ -3,6 +3,146 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.toResolvedArtifactPath = void 0;
 require("../_dnt.polyfills.js");
 const join_js_1 = require("../deps/jsr.io/@std/path/1.1.2/join.js");
+/**
+ * Resolves artifact destination paths relative to a base directory.
+ *
+ * This utility function combines a base path with a destination path to create
+ * the final resolved file path for generated artifacts. It handles special path
+ * prefixes (like '@/') and provides sensible defaults when no base path is specified.
+ *
+ * The function is used throughout the rendering pipeline to determine the final
+ * file system locations for generated code artifacts, ensuring consistent path
+ * resolution across different operating systems and deployment scenarios.
+ *
+ * @param args - Path resolution configuration
+ * @param args.basePath - Base directory path (defaults to './' if undefined)
+ * @param args.destinationPath - Destination path for the artifact
+ * @returns The resolved absolute or relative path for the artifact
+ *
+ * @example Basic path resolution
+ * ```typescript
+ * import { toResolvedArtifactPath } from '@skmtc/core';
+ *
+ * // With explicit base path
+ * const resolved1 = toResolvedArtifactPath({
+ *   basePath: './src/generated',
+ *   destinationPath: 'models/User.ts'
+ * });
+ * console.log(resolved1); // './src/generated/models/User.ts'
+ *
+ * // With undefined base path (uses default)
+ * const resolved2 = toResolvedArtifactPath({
+ *   basePath: undefined,
+ *   destinationPath: 'types.ts'
+ * });
+ * console.log(resolved2); // './types.ts'
+ * ```
+ *
+ * @example Special path prefix handling
+ * ```typescript
+ * // '@/' prefix gets stripped and resolved relative to base
+ * const resolved = toResolvedArtifactPath({
+ *   basePath: './output',
+ *   destinationPath: '@/api/models.ts'
+ * });
+ * console.log(resolved); // './output/api/models.ts'
+ *
+ * // Regular paths work normally
+ * const normal = toResolvedArtifactPath({
+ *   basePath: './build',
+ *   destinationPath: 'components/Button.tsx'
+ * });
+ * console.log(normal); // './build/components/Button.tsx'
+ * ```
+ *
+ * @example Cross-platform path resolution
+ * ```typescript
+ * // Works consistently across platforms
+ * const windowsPath = toResolvedArtifactPath({
+ *   basePath: 'C:\\projects\\app\\dist',
+ *   destinationPath: 'utils/helpers.js'
+ * });
+ *
+ * const unixPath = toResolvedArtifactPath({
+ *   basePath: '/home/user/projects/app/dist',
+ *   destinationPath: 'utils/helpers.js'
+ * });
+ * ```
+ *
+ * @example Usage in file generation
+ * ```typescript
+ * class ArtifactWriter {
+ *   writeArtifact(
+ *     content: string,
+ *     destination: string,
+ *     baseDir?: string
+ *   ) {
+ *     const resolvedPath = toResolvedArtifactPath({
+ *       basePath: baseDir,
+ *       destinationPath: destination
+ *     });
+ *
+ *     console.log(`Writing to: ${resolvedPath}`);
+ *     return Deno.writeTextFile(resolvedPath, content);
+ *   }
+ * }
+ *
+ * const writer = new ArtifactWriter();
+ * await writer.writeArtifact(
+ *   'export const greeting = "Hello";',
+ *   '@/constants.ts',
+ *   './src/generated'
+ * );
+ * // Writes to: ./src/generated/constants.ts
+ * ```
+ *
+ * @example Integration with rendering pipeline
+ * ```typescript
+ * class FileRenderer {
+ *   renderFiles(
+ *     files: Map<string, File>,
+ *     outputDir: string
+ *   ): Record<string, string> {
+ *     const artifacts: Record<string, string> = {};
+ *
+ *     for (const [destPath, file] of files) {
+ *       const resolvedPath = toResolvedArtifactPath({
+ *         basePath: outputDir,
+ *         destinationPath: destPath
+ *       });
+ *
+ *       artifacts[resolvedPath] = file.toString();
+ *     }
+ *
+ *     return artifacts;
+ *   }
+ * }
+ * ```
+ *
+ * @example Dynamic base path resolution
+ * ```typescript
+ * function resolveForEnvironment(
+ *   destination: string,
+ *   env: 'development' | 'production'
+ * ): string {
+ *   const basePaths = {
+ *     development: './dev-output',
+ *     production: './dist'
+ *   };
+ *
+ *   return toResolvedArtifactPath({
+ *     basePath: basePaths[env],
+ *     destinationPath: destination
+ *   });
+ * }
+ *
+ * const devPath = resolveForEnvironment('api.ts', 'development');
+ * const prodPath = resolveForEnvironment('api.ts', 'production');
+ *
+ * console.log(devPath);  // './dev-output/api.ts'
+ * console.log(prodPath); // './dist/api.ts'
+ * ```
+ */
 const toResolvedArtifactPath = ({ basePath, destinationPath }) => {
     return (0, join_js_1.join)(basePath ?? './', destinationPath.replace(/^@\//, ''));
 };

package/script/oas/example/Example.d.ts

@@ -1,13 +1,93 @@
 import type { OasRef } from '../ref/Ref.js';
 import type { ToJsonSchemaOptions } from '../schema/Schema.js';
 import type { OpenAPIV3 } from 'openapi-types';
+/**
+ * Constructor fields for {@link OasExample}.
+ */
 export type ExampleFields = {
+    /** Short summary of the example */
     summary: string | undefined;
+    /** Longer description of the example */
     description: string | undefined;
+    /** The example value */
     value: unknown;
+    /** Custom extension fields (x-* properties) */
     extensionFields?: Record<string, unknown>;
 };
-/** Provides example data represented by schema */
+/**
+ * Represents an Example Object in the OpenAPI Specification.
+ *
+ * The `OasExample` class provides sample data for parameters, request bodies,
+ * responses, and other components in an OpenAPI document. Examples are crucial
+ * for API documentation, testing, and helping developers understand expected
+ * data formats and structures.
+ *
+ * This class supports rich example definitions with metadata, making API
+ * documentation more informative and interactive for developers.
+ *
+ * ## Key Features
+ *
+ * - **Sample Data**: Concrete examples of API inputs and outputs
+ * - **Documentation**: Summary and description for context
+ * - **Type Flexibility**: Supports any data type as example values
+ * - **Reference Support**: Can be referenced from multiple locations
+ * - **Markdown Support**: Rich text descriptions with CommonMark
+ *
+ * @example Simple string example
+ * ```typescript
+ * import { OasExample } from '@skmtc/core';
+ *
+ * const nameExample = new OasExample({
+ *   summary: 'Typical user name',
+ *   description: 'A common first and last name combination',
+ *   value: 'John Doe'
+ * });
+ * ```
+ *
+ * @example JSON object example
+ * ```typescript
+ * const userExample = new OasExample({
+ *   summary: 'Complete user profile',
+ *   description: 'Example user with all profile fields populated',
+ *   value: {
+ *     id: 12345,
+ *     name: 'Jane Smith',
+ *     email: 'jane.smith@example.com',
+ *     active: true,
+ *     createdAt: '2023-01-15T10:30:00Z'
+ *   }
+ * });
+ * ```
+ *
+ * @example Array example with multiple items
+ * ```typescript
+ * const productsExample = new OasExample({
+ *   summary: 'Product list sample',
+ *   description: 'Typical response for product catalog endpoint',
+ *   value: [
+ *     { id: 1, name: 'Laptop', price: 999.99, category: 'Electronics' },
+ *     { id: 2, name: 'Book', price: 19.99, category: 'Education' },
+ *     { id: 3, name: 'Coffee Mug', price: 12.50, category: 'Home' }
+ *   ]
+ * });
+ * ```
+ *
+ * @example Error response example
+ * ```typescript
+ * const errorExample = new OasExample({
+ *   summary: 'Validation error',
+ *   description: 'Response when request validation fails',
+ *   value: {
+ *     error: 'Validation failed',
+ *     code: 'INVALID_INPUT',
+ *     details: [
+ *       { field: 'email', message: 'Invalid email format' },
+ *       { field: 'age', message: 'Must be between 18 and 120' }
+ *     ]
+ *   }
+ * });
+ * ```
+ */
 export declare class OasExample {
     #private;
     /** Static identifier property for OasExample */

package/script/oas/example/Example.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Example.d.ts","sourceRoot":"","sources":["../../../src/oas/example/Example.ts"],"names":[],"mappings":"AAAA,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,aAAa,GAAG;IAC1B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,KAAK,EAAE,OAAO,CAAA;IACd,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED,kDAAkD;AAClD,qBAAa,UAAU;;IACrB,gDAAgD;IAChD,OAAO,EAAE,SAAS,CAAY;gBAIlB,MAAM,EAAE,aAAa;IAIjC,+BAA+B;IAC/B,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;IAED,2EAA2E;IAC3E,IAAI,WAAW,IAAI,MAAM,GAAG,SAAS,CAEpC;IAED,6BAA6B;IAC7B,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,qCAAqC;IACrC,IAAI,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEzD;IAED,4CAA4C;IAC5C,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,SAAS,CAAC;IAIlC,qBAAqB;IACrB,OAAO,IAAI,UAAU;IAIrB,WAAW,IAAI,UAAU;IAIzB,YAAY,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,CAAC,aAAa;CAOrE"}
+{"version":3,"file":"Example.d.ts","sourceRoot":"","sources":["../../../src/oas/example/Example.ts"],"names":[],"mappings":"AAAA,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,aAAa,GAAG;IAC1B,mCAAmC;IACnC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,wCAAwC;IACxC,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,wBAAwB;IACxB,KAAK,EAAE,OAAO,CAAA;IACd,+CAA+C;IAC/C,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC1C,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyEG;AACH,qBAAa,UAAU;;IACrB,gDAAgD;IAChD,OAAO,EAAE,SAAS,CAAY;gBAIlB,MAAM,EAAE,aAAa;IAIjC,+BAA+B;IAC/B,IAAI,OAAO,IAAI,MAAM,GAAG,SAAS,CAEhC;IAED,2EAA2E;IAC3E,IAAI,WAAW,IAAI,MAAM,GAAG,SAAS,CAEpC;IAED,6BAA6B;IAC7B,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,qCAAqC;IACrC,IAAI,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAEzD;IAED,4CAA4C;IAC5C,KAAK,IAAI,IAAI,IAAI,MAAM,CAAC,SAAS,CAAC;IAIlC,qBAAqB;IACrB,OAAO,IAAI,UAAU;IAIrB,WAAW,IAAI,UAAU;IAIzB,YAAY,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,CAAC,aAAa;CAOrE"}

package/script/oas/example/Example.js

@@ -13,7 +13,80 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 var _OasExample_fields;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OasExample = void 0;
-/** Provides example data represented by schema */
+/**
+ * Represents an Example Object in the OpenAPI Specification.
+ *
+ * The `OasExample` class provides sample data for parameters, request bodies,
+ * responses, and other components in an OpenAPI document. Examples are crucial
+ * for API documentation, testing, and helping developers understand expected
+ * data formats and structures.
+ *
+ * This class supports rich example definitions with metadata, making API
+ * documentation more informative and interactive for developers.
+ *
+ * ## Key Features
+ *
+ * - **Sample Data**: Concrete examples of API inputs and outputs
+ * - **Documentation**: Summary and description for context
+ * - **Type Flexibility**: Supports any data type as example values
+ * - **Reference Support**: Can be referenced from multiple locations
+ * - **Markdown Support**: Rich text descriptions with CommonMark
+ *
+ * @example Simple string example
+ * ```typescript
+ * import { OasExample } from '@skmtc/core';
+ *
+ * const nameExample = new OasExample({
+ *   summary: 'Typical user name',
+ *   description: 'A common first and last name combination',
+ *   value: 'John Doe'
+ * });
+ * ```
+ *
+ * @example JSON object example
+ * ```typescript
+ * const userExample = new OasExample({
+ *   summary: 'Complete user profile',
+ *   description: 'Example user with all profile fields populated',
+ *   value: {
+ *     id: 12345,
+ *     name: 'Jane Smith',
+ *     email: 'jane.smith@example.com',
+ *     active: true,
+ *     createdAt: '2023-01-15T10:30:00Z'
+ *   }
+ * });
+ * ```
+ *
+ * @example Array example with multiple items
+ * ```typescript
+ * const productsExample = new OasExample({
+ *   summary: 'Product list sample',
+ *   description: 'Typical response for product catalog endpoint',
+ *   value: [
+ *     { id: 1, name: 'Laptop', price: 999.99, category: 'Electronics' },
+ *     { id: 2, name: 'Book', price: 19.99, category: 'Education' },
+ *     { id: 3, name: 'Coffee Mug', price: 12.50, category: 'Home' }
+ *   ]
+ * });
+ * ```
+ *
+ * @example Error response example
+ * ```typescript
+ * const errorExample = new OasExample({
+ *   summary: 'Validation error',
+ *   description: 'Response when request validation fails',
+ *   value: {
+ *     error: 'Validation failed',
+ *     code: 'INVALID_INPUT',
+ *     details: [
+ *       { field: 'email', message: 'Invalid email format' },
+ *       { field: 'age', message: 'Must be between 18 and 120' }
+ *     ]
+ *   }
+ * });
+ * ```
+ */
 class OasExample {
     constructor(fields) {
         /** Static identifier property for OasExample */