@skmtc/core 0.0.806 → 0.0.807

package/script/types/Preview.js

@@ -34,6 +34,81 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mapping = exports.preview = exports.mappingModule = exports.previewModule = exports.previewGroup = exports.modelSource = exports.operationSource = void 0;
+/**
+ * @fileoverview Preview and Mapping System for SKMTC Core
+ *
+ * This module provides comprehensive types and utilities for creating preview
+ * interfaces and mapping configurations for generated code. The preview system
+ * enables interactive demonstrations of generated APIs, forms, tables, and
+ * other UI components within development tools and documentation.
+ *
+ * The mapping system provides metadata about how OpenAPI operations and models
+ * translate to generated code, enabling rich tooling experiences and
+ * reverse-engineering capabilities.
+ *
+ * ## Key Features
+ *
+ * - **Interactive Previews**: Rich preview interfaces for generated components
+ * - **Source Mapping**: Traceability from generated code back to OpenAPI sources
+ * - **UI Grouping**: Organized grouping of related UI components (forms, tables, inputs)
+ * - **Generator Integration**: Deep integration with the generator pipeline
+ * - **Type Safety**: Comprehensive validation and type safety throughout
+ *
+ * @example Creating operation previews
+ * ```typescript
+ * import type { PreviewModule, OperationSource } from '@skmtc/core/Preview';
+ *
+ * const operationSource: OperationSource = {
+ *   type: 'operation',
+ *   generatorId: 'react-forms',
+ *   operationPath: '/users',
+ *   operationMethod: 'POST'
+ * };
+ *
+ * const preview: PreviewModule = {
+ *   title: 'Create User Form',
+ *   description: 'Interactive form for creating new users',
+ *   group: 'forms',
+ *   source: operationSource,
+ *   moduleName: 'CreateUserForm',
+ *   exportName: 'default'
+ * };
+ * ```
+ *
+ * @example Creating model previews
+ * ```typescript
+ * import type { PreviewModule, ModelSource } from '@skmtc/core/Preview';
+ *
+ * const modelSource: ModelSource = {
+ *   type: 'model',
+ *   generatorId: 'typescript-types',
+ *   refName: 'User'
+ * };
+ *
+ * const preview: PreviewModule = {
+ *   title: 'User Type Definition',
+ *   description: 'TypeScript interface for User model',
+ *   group: 'tables',
+ *   source: modelSource,
+ *   moduleName: 'UserTypes',
+ *   exportName: 'User'
+ * };
+ * ```
+ *
+ * @example Working with mappings
+ * ```typescript
+ * import type { MappingModule } from '@skmtc/core/Preview';
+ *
+ * const mapping: MappingModule = {
+ *   source: operationSource,
+ *   moduleName: 'UserApi',
+ *   exportName: 'createUser',
+ *   generatedPath: './src/generated/UserApi.ts'
+ * };
+ * ```
+ *
+ * @module Preview
+ */
 require("../_dnt.polyfills.js");
 const Method_js_1 = require("./Method.js");
 const v = __importStar(require("valibot"));

package/script/types/RefName.d.ts

@@ -1,3 +1,73 @@
+/**
+ * @fileoverview Reference Name System for SKMTC Core
+ *
+ * This module provides a type-safe reference name system for identifying
+ * OpenAPI schema components throughout the SKMTC pipeline. Reference names
+ * are branded types that ensure schema identifiers are handled safely and
+ * prevent accidental mixing with regular strings.
+ *
+ * The reference name system is crucial for maintaining type safety when
+ * working with OpenAPI component references, schema lookups, and cross-references
+ * between different parts of the generated code.
+ *
+ * ## Key Features
+ *
+ * - **Type Safety**: Branded types prevent string confusion and improve code reliability
+ * - **Schema Integration**: Direct mapping to OpenAPI components.schemas keys
+ * - **Reference Tracking**: Safe handling of schema references throughout generation
+ * - **IDE Support**: Enhanced IntelliSense and error detection in development
+ * - **Validation**: Compile-time validation of schema reference usage
+ *
+ * @example Basic reference name usage
+ * ```typescript
+ * import type { RefName } from '@skmtc/core/RefName';
+ *
+ * // Create a reference name (typically done by the parser)
+ * const userRef: RefName = 'User' as RefName;
+ * const productRef: RefName = 'Product' as RefName;
+ *
+ * // TypeScript prevents mixing with regular strings
+ * const regularString = 'User';
+ * // const invalid: RefName = regularString; // Type error!
+ * ```
+ *
+ * @example Using reference names in generators
+ * ```typescript
+ * import type { RefName } from '@skmtc/core/RefName';
+ *
+ * function generateModelImport(refName: RefName): string {
+ *   return `import type { ${refName} } from './models/${refName}';`;
+ * }
+ *
+ * function generateModelReference(refName: RefName): string {
+ *   return `#/components/schemas/${refName}`;
+ * }
+ *
+ * // Usage with type safety
+ * const userRef: RefName = 'User' as RefName;
+ * const importStatement = generateModelImport(userRef);
+ * const schemaRef = generateModelReference(userRef);
+ * ```
+ *
+ * @example Reference name validation
+ * ```typescript
+ * import type { RefName } from '@skmtc/core/RefName';
+ *
+ * function isValidRefName(value: string): value is RefName {
+ *   // Validate that the string is a valid schema reference name
+ *   return /^[A-Za-z][A-Za-z0-9_]*$/.test(value) && value.length > 0;
+ * }
+ *
+ * function safeCreateRefName(value: string): RefName | null {
+ *   if (isValidRefName(value)) {
+ *     return value as RefName;
+ *   }
+ *   return null;
+ * }
+ * ```
+ *
+ * @module RefName
+ */
 import "../_dnt.polyfills.js";
 import type { Brand } from './Brand.js';
 /**

package/script/types/RefName.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"RefName.d.ts","sourceRoot":"","sources":["../../src/types/RefName.ts"],"names":[],"mappings":"AAAA,OAAO,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA"}
+{"version":3,"file":"RefName.d.ts","sourceRoot":"","sources":["../../src/types/RefName.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqEG;AACH,OAAO,sBAAsB,CAAC;AAG9B,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AACH,MAAM,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA"}

package/script/types/RefName.js

@@ -1,3 +1,73 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * @fileoverview Reference Name System for SKMTC Core
+ *
+ * This module provides a type-safe reference name system for identifying
+ * OpenAPI schema components throughout the SKMTC pipeline. Reference names
+ * are branded types that ensure schema identifiers are handled safely and
+ * prevent accidental mixing with regular strings.
+ *
+ * The reference name system is crucial for maintaining type safety when
+ * working with OpenAPI component references, schema lookups, and cross-references
+ * between different parts of the generated code.
+ *
+ * ## Key Features
+ *
+ * - **Type Safety**: Branded types prevent string confusion and improve code reliability
+ * - **Schema Integration**: Direct mapping to OpenAPI components.schemas keys
+ * - **Reference Tracking**: Safe handling of schema references throughout generation
+ * - **IDE Support**: Enhanced IntelliSense and error detection in development
+ * - **Validation**: Compile-time validation of schema reference usage
+ *
+ * @example Basic reference name usage
+ * ```typescript
+ * import type { RefName } from '@skmtc/core/RefName';
+ *
+ * // Create a reference name (typically done by the parser)
+ * const userRef: RefName = 'User' as RefName;
+ * const productRef: RefName = 'Product' as RefName;
+ *
+ * // TypeScript prevents mixing with regular strings
+ * const regularString = 'User';
+ * // const invalid: RefName = regularString; // Type error!
+ * ```
+ *
+ * @example Using reference names in generators
+ * ```typescript
+ * import type { RefName } from '@skmtc/core/RefName';
+ *
+ * function generateModelImport(refName: RefName): string {
+ *   return `import type { ${refName} } from './models/${refName}';`;
+ * }
+ *
+ * function generateModelReference(refName: RefName): string {
+ *   return `#/components/schemas/${refName}`;
+ * }
+ *
+ * // Usage with type safety
+ * const userRef: RefName = 'User' as RefName;
+ * const importStatement = generateModelImport(userRef);
+ * const schemaRef = generateModelReference(userRef);
+ * ```
+ *
+ * @example Reference name validation
+ * ```typescript
+ * import type { RefName } from '@skmtc/core/RefName';
+ *
+ * function isValidRefName(value: string): value is RefName {
+ *   // Validate that the string is a valid schema reference name
+ *   return /^[A-Za-z][A-Za-z0-9_]*$/.test(value) && value.length > 0;
+ * }
+ *
+ * function safeCreateRefName(value: string): RefName | null {
+ *   if (isValidRefName(value)) {
+ *     return value as RefName;
+ *   }
+ *   return null;
+ * }
+ * ```
+ *
+ * @module RefName
+ */
 require("../_dnt.polyfills.js");