@skmtc/core 0.0.793 → 0.0.795

package/esm/helpers/tracer.js

@@ -1,3 +1,127 @@
+/**
+ * Executes a function with distributed tracing support and stack trail management.
+ *
+ * This utility function provides distributed tracing capabilities for the SKMTC
+ * generation pipeline. It manages stack trail tokens that help track execution
+ * context across complex nested operations, making debugging and performance
+ * analysis much easier.
+ *
+ * The tracer ensures proper cleanup of stack trail tokens even if the wrapped
+ * function throws an error, maintaining the integrity of the tracing system.
+ * This is essential for accurate debugging and performance monitoring in
+ * complex code generation scenarios.
+ *
+ * @template T - The return type of the traced function
+ * @param stackTrail - The stack trail instance for tracking execution context
+ * @param token - Token(s) to identify this execution step in traces
+ * @param fn - The function to execute with tracing
+ * @param log - Logger instance for error reporting
+ * @returns The result of the wrapped function execution
+ *
+ * @throws Re-throws any error from the wrapped function after cleanup
+ *
+ * @example Basic tracing usage
+ * ```typescript
+ * import { tracer } from '@skmtc/core';
+ *
+ * class ModelGenerator {
+ *   generateModel(stackTrail: StackTrail, logger: Logger) {
+ *     return tracer(stackTrail, 'generate-model', () => {
+ *       // Complex model generation logic here
+ *       return this.createModelDefinition();
+ *     }, logger);
+ *   }
+ * }
+ * ```
+ *
+ * @example Nested tracing
+ * ```typescript
+ * class ComplexProcessor {
+ *   processSchema(stackTrail: StackTrail, logger: Logger) {
+ *     return tracer(stackTrail, 'process-schema', () => {
+ *       const parsed = tracer(stackTrail, 'parse', () => {
+ *         return this.parseSchema();
+ *       }, logger);
+ *
+ *       const validated = tracer(stackTrail, 'validate', () => {
+ *         return this.validateSchema(parsed);
+ *       }, logger);
+ *
+ *       return tracer(stackTrail, 'transform', () => {
+ *         return this.transformSchema(validated);
+ *       }, logger);
+ *     }, logger);
+ *   }
+ * }
+ *
+ * // Stack trail will show: ['process-schema', 'parse'] -> ['process-schema', 'validate'] -> ['process-schema', 'transform']
+ * ```
+ *
+ * @example Multiple token tracing
+ * ```typescript
+ * const result = tracer(
+ *   stackTrail,
+ *   ['file-generation', 'models.ts'], // Multiple tokens for detailed context
+ *   () => {
+ *     return generateModelsFile();
+ *   },
+ *   logger
+ * );
+ * ```
+ *
+ * @example Error handling with tracing
+ * ```typescript
+ * class SafeGenerator {
+ *   generateWithTracing(stackTrail: StackTrail, logger: Logger) {
+ *     try {
+ *       return tracer(stackTrail, 'risky-operation', () => {
+ *         // This might throw an error
+ *         return this.complexGeneration();
+ *       }, logger);
+ *     } catch (error) {
+ *       // Stack trail is automatically cleaned up
+ *       logger.error(`Generation failed: ${error.message}`);
+ *       return this.fallbackGeneration();
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * @example Performance monitoring
+ * ```typescript
+ * class PerformanceAwareGenerator {
+ *   timedGeneration(stackTrail: StackTrail, logger: Logger) {
+ *     const startTime = Date.now();
+ *
+ *     const result = tracer(stackTrail, 'timed-generation', () => {
+ *       return this.heavyComputation();
+ *     }, logger);
+ *
+ *     const duration = Date.now() - startTime;
+ *     logger.info(`Generation completed in ${duration}ms`);
+ *
+ *     return result;
+ *   }
+ * }
+ * ```
+ *
+ * @example Integration with context classes
+ * ```typescript
+ * // Typically used within context classes like this:
+ * class GenerateContext {
+ *   trace<T>(token: string | string[], fn: () => T): T {
+ *     return tracer(this.stackTrail, token, fn, this.logger);
+ *   }
+ *
+ *   processModel(schema: OasSchema) {
+ *     return this.trace(['model', schema.type], () => {
+ *       // Model processing logic
+ *       return this.createModel(schema);
+ *     });
+ *   }
+ * }
+ * ```
+ */
 export const tracer = (stackTrail, token, fn, log) => {
     stackTrail.append(token);
     try {

package/esm/types/Modifiers.d.ts

@@ -1,6 +1,74 @@
+/**
+ * Type modifiers used throughout the SKMTC type system.
+ *
+ * `Modifiers` represent additional metadata and constraints that can be
+ * applied to type system values. These modifiers affect how types are
+ * generated and used in the target language output.
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { Modifiers } from '@skmtc/core';
+ *
+ * const stringModifiers: Modifiers = {
+ *   required: true,
+ *   nullable: false,
+ *   description: 'User email address'
+ * };
+ *
+ * const optionalModifiers: Modifiers = {
+ *   required: false,
+ *   nullable: true,
+ *   description: 'Optional user profile image URL'
+ * };
+ * ```
+ *
+ * @example In type system values
+ * ```typescript
+ * const emailField: TypeSystemString = {
+ *   type: 'string',
+ *   format: 'email',
+ *   enums: undefined,
+ *   modifiers: {
+ *     required: true,
+ *     nullable: false,
+ *     description: 'Valid email address for account registration'
+ *   }
+ * };
+ *
+ * const optionalNote: TypeSystemString = {
+ *   type: 'string',
+ *   format: undefined,
+ *   enums: undefined,
+ *   modifiers: {
+ *     required: false,
+ *     nullable: true,
+ *     description: 'Optional user note or comment'
+ *   }
+ * };
+ * ```
+ *
+ * @example TypeScript generation
+ * ```typescript
+ * function generateTypeScript(type: TypeSystemValue): string {
+ *   const baseType = generateBaseType(type);
+ *   const optional = !type.modifiers.required ? '?' : '';
+ *   const nullable = type.modifiers.nullable ? ' | null' : '';
+ *
+ *   return `${baseType}${nullable}${optional}`;
+ * }
+ *
+ * // Required non-null string: 'string'
+ * // Optional non-null string: 'string?'
+ * // Required nullable string: 'string | null'
+ * // Optional nullable string: 'string | null?'
+ * ```
+ */
 export type Modifiers = {
+    /** Whether the field is required (affects optional markers in generated types) */
     required?: boolean;
+    /** Human-readable description of the field (used in documentation) */
     description?: string;
+    /** Whether the field can be null (affects null union types) */
     nullable?: boolean;
 };
 //# sourceMappingURL=Modifiers.d.ts.map

package/esm/types/Modifiers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Modifiers.d.ts","sourceRoot":"","sources":["../../src/types/Modifiers.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA"}
+{"version":3,"file":"Modifiers.d.ts","sourceRoot":"","sources":["../../src/types/Modifiers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,kFAAkF;IAClF,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA"}