@aetherframework/template-engine 1.0.0

package/src/utils/ConfigLoader.js

@@ -0,0 +1,279 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/template-engine/src/utils/ConfigLoader
+ */
+
+/**
+ * Configuration Loader - Loads and manages configuration from environment variables and configuration files
+ * Supports loading from .env files, environment variables, and setting defaults
+ */
+import fs from 'fs-extra';
+import path from 'path';
+
+class ConfigLoader {
+  /**
+   * Constructor for ConfigLoader
+   * @param {Object} options - Configuration options
+   * @param {string} options.configFile - Configuration file name (default: '.env')
+   * @param {string} options.configDir - Configuration directory path (default: current working directory)
+   */
+  constructor(options = {}) {
+    // Initialize configuration options with defaults
+    this.options = {
+      configFile: options.configFile || '.env',
+      configDir: options.configDir || process.cwd(),
+      ...options
+    };
+    
+    // Configuration storage object
+    this.config = {};
+    
+    // Flag to track if configuration has been loaded
+    this.loaded = false;
+  }
+  
+  /**
+   * Load configuration from environment variables and configuration files
+   * @returns {Promise<Object>} Configuration object containing all loaded settings
+   */
+  async load() {
+    // Return cached configuration if already loaded
+    if (this.loaded) {
+      return this.config;
+    }
+    
+    // Step 1: Load configuration from environment variables
+    this.loadFromEnv();
+    
+    // Step 2: Load configuration from configuration file
+    await this.loadFromFile();
+    
+    // Step 3: Set default values for any missing configuration options
+    this.setDefaults();
+    
+    // Mark configuration as loaded
+    this.loaded = true;
+    
+    return this.config;
+  }
+  
+  /**
+   * Load configuration from environment variables
+   * Environment variables take precedence over file configuration
+   * @private
+   */
+  loadFromEnv() {
+    // Template Engine Configuration
+    this.config.mode = process.env.TEMPLATE_ENGINE_MODE || 'template';
+    this.config.defaultEngine = process.env.TEMPLATE_ENGINE || 'aether';
+    this.config.templateDir = process.env.TEMPLATE_DIR || './templates';
+    
+    // Cache Configuration
+    this.config.cacheEnabled = process.env.CACHE_ENABLED !== 'false';
+    this.config.cacheTTL = parseInt(process.env.CACHE_TTL) || 300000; // 5 minutes default
+    this.config.cacheMaxSize = parseInt(process.env.CACHE_MAX_SIZE) || 1000;
+    
+    // Debug Configuration
+    this.config.debug = process.env.NODE_ENV === 'development' || process.env.DEBUG === 'true';
+    
+    // Server-Side Rendering (SSR) Configuration
+    this.config.ssrHydrate = process.env.SSR_HYDRATE !== 'false';
+    this.config.ssrStream = process.env.SSR_STREAM === 'true';
+    
+    // Template Configuration
+    this.config.layoutSupport = process.env.LAYOUT_SUPPORT !== 'false';
+    this.config.includeSupport = process.env.INCLUDE_SUPPORT !== 'false';
+    this.config.cacheTemplates = process.env.CACHE_TEMPLATES !== 'false';
+  }
+  
+  /**
+   * Load configuration from configuration file
+   * File configuration is used as fallback when environment variables are not set
+   * @private
+   */
+  async loadFromFile() {
+    // Construct full path to configuration file
+    const configPath = path.join(this.options.configDir, this.options.configFile);
+    
+    try {
+      // Check if configuration file exists
+      if (await fs.pathExists(configPath)) {
+        // Read configuration file content
+        const content = await fs.readFile(configPath, 'utf-8');
+        const lines = content.split('\n');
+        
+        // Parse each line in the configuration file
+        for (const line of lines) {
+          const trimmed = line.trim();
+          
+          // Skip comments (lines starting with #) and empty lines
+          if (!trimmed || trimmed.startsWith('#')) {
+            continue;
+          }
+          
+          // Parse key=value pairs
+          const equalsIndex = trimmed.indexOf('=');
+          if (equalsIndex > 0) {
+            const key = trimmed.substring(0, equalsIndex).trim();
+            const value = trimmed.substring(equalsIndex + 1).trim();
+            
+            // Remove surrounding quotes if present
+            const cleanValue = value.replace(/['"]|['"]$/g, '');
+            
+            // Only set configuration from file if environment variable is not already set
+            if (process.env[key] === undefined) {
+              this.config[key] = this.parseValue(cleanValue);
+            }
+          }
+        }
+        
+        console.log(`📁 Configuration loaded from: ${configPath}`);
+      }
+    } catch (error) {
+      // Log warning but don't fail if configuration file cannot be loaded
+      console.warn(`⚠️ Could not load config file: ${error.message}`);
+    }
+  }
+  
+  /**
+   * Parse configuration value from string to appropriate type
+   * @param {string} value - Raw string value from configuration
+   * @returns {any} Parsed value (boolean, number, or string)
+   * @private
+   */
+  parseValue(value) {
+    // Parse boolean values
+    if (value.toLowerCase() === 'true') return true;
+    if (value.toLowerCase() === 'false') return false;
+    
+    // Parse numeric values
+    if (!isNaN(value) && value.trim() !== '') {
+      const num = Number(value);
+      if (!isNaN(num)) return num;
+    }
+    
+    // Return as string if not boolean or number
+    return value;
+  }
+  
+  /**
+   * Set default configuration values for any missing options
+   * This ensures all required configuration options have values
+   * @private
+   */
+  setDefaults() {
+    // Default configuration values
+    const defaults = {
+      mode: 'template',
+      defaultEngine: 'aether',
+      templateDir: './templates',
+      cacheEnabled: true,
+      cacheTTL: 300000, // 5 minutes in milliseconds
+      cacheMaxSize: 1000,
+      debug: false,
+      ssrHydrate: true,
+      ssrStream: false,
+      layoutSupport: true,
+      includeSupport: true,
+      cacheTemplates: true
+    };
+    
+    // Apply defaults only for configuration options that are not already set
+    for (const [key, defaultValue] of Object.entries(defaults)) {
+      if (this.config[key] === undefined) {
+        this.config[key] = defaultValue;
+      }
+    }
+  }
+  
+  /**
+   * Get a specific configuration value
+   * @param {string} key - Configuration key to retrieve
+   * @param {any} defaultValue - Default value to return if key is not found
+   * @returns {any} Configuration value or default value
+   */
+  get(key, defaultValue = null) {
+    return this.config[key] !== undefined ? this.config[key] : defaultValue;
+  }
+  
+  /**
+   * Set a configuration value
+   * @param {string} key - Configuration key to set
+   * @param {any} value - Value to set for the configuration key
+   * @returns {ConfigLoader} This instance for method chaining
+   */
+  set(key, value) {
+    this.config[key] = value;
+    return this;
+  }
+  
+  /**
+   * Get all configuration as an object
+   * @returns {Object} Complete configuration object
+   */
+  getAll() {
+    // Return a copy to prevent external modification
+    return { ...this.config };
+  }
+  
+  /**
+   * Reload configuration from sources
+   * Useful when configuration files have been updated
+   * @returns {Promise<Object>} Updated configuration object
+   */
+  async reload() {
+    // Reset loaded flag and clear existing configuration
+    this.loaded = false;
+    this.config = {};
+    
+    // Load configuration again
+    return this.load();
+  }
+  
+  /**
+   * Validate the current configuration
+   * Checks for required settings and valid values
+   * @returns {Object} Validation result with errors and warnings
+   */
+  validate() {
+    const errors = [];
+    const warnings = [];
+    
+    // Validate rendering mode
+    if (!['ssr', 'template', 'disabled'].includes(this.config.mode)) {
+      errors.push(`Invalid mode: ${this.config.mode}. Must be 'ssr', 'template', or 'disabled'`);
+    }
+    
+    // Validate template directory configuration
+    if (!this.config.templateDir) {
+      errors.push('Template directory not specified');
+    }
+    
+    // Validate cache TTL (must be positive)
+    if (this.config.cacheTTL < 0) {
+      errors.push(`Invalid cache TTL: ${this.config.cacheTTL}. Must be positive number`);
+    }
+    
+    // Validate cache maximum size (must be at least 1)
+    if (this.config.cacheMaxSize < 1) {
+      errors.push(`Invalid cache max size: ${this.config.cacheMaxSize}. Must be at least 1`);
+    }
+    
+    // Check if template directory exists (warning only, not an error)
+    if (this.config.templateDir && !fs.existsSync(this.config.templateDir)) {
+      warnings.push(`Template directory does not exist: ${this.config.templateDir}`);
+    }
+    
+    // Return validation results
+    return {
+      valid: errors.length === 0,
+      errors,
+      warnings,
+      config: this.config
+    };
+  }
+}
+
+export default ConfigLoader;

package/src/utils/ErrorHandler.js

@@ -0,0 +1,276 @@
+/**
+ * @license MIT
+ * Copyright (c) 2026-present AetherFramework Contributors.
+ * SPDX-License-Identifier: MIT
+ * @module @aetherframework/template-engine/src/utils/ErrorHandler
+ */
+
+/**
+ * Error Handler - Handles and formats template engine errors
+ * This class provides comprehensive error handling for template engine operations,
+ * including error formatting, logging, and user-friendly error messages.
+ */
+class ErrorHandler {
+  /**
+   * Constructor for ErrorHandler class
+   * @param {Object} options - Configuration options for error handling
+   * @param {boolean} options.debug - Enable debug mode for detailed error information
+   * @param {boolean} options.logErrors - Enable error logging to console
+   * @param {boolean} options.formatErrors - Enable error formatting with context
+   */
+  constructor(options = {}) {
+    this.options = {
+      debug: options.debug || false,
+      logErrors: options.logErrors !== false,
+      formatErrors: options.formatErrors !== false,
+      ...options
+    };
+  }
+  
+  /**
+   * Static method to handle template engine errors
+   * @param {Error} error - Original error object
+   * @param {Object} context - Error context information
+   * @returns {Error} Formatted error object
+   */
+  static handle(error, context = {}) {
+    const handler = new ErrorHandler();
+    return handler.formatError(error, context);
+  }
+  
+  /**
+   * Format error with additional context information
+   * @param {Error} error - Original error object
+   * @param {Object} context - Error context information
+   * @returns {Error} Formatted error object
+   */
+  formatError(error, context = {}) {
+    const errorInfo = {
+      message: error.message,
+      stack: error.stack,
+      timestamp: new Date().toISOString(),
+      context: context
+    };
+    
+    // Log error to console if logging is enabled
+    if (this.options.logErrors) {
+      console.error('Template Engine Error:', errorInfo);
+    }
+    
+    // Format error if formatting is enabled
+    if (this.options.formatErrors) {
+      return this.createFormattedError(error, context);
+    }
+    
+    return error;
+  }
+  
+  /**
+   * Create formatted error with helpful message and context
+   * @param {Error} error - Original error object
+   * @param {Object} context - Error context information
+   * @returns {Error} Formatted error object
+   * @private
+   */
+  createFormattedError(error, context) {
+    let message = error.message;
+    
+    // Add template context information to error message
+    if (context.template) {
+      const templatePreview = typeof context.template === 'string' 
+        ? context.template.substring(0, 100) + (context.template.length > 100 ? '...' : '')
+        : 'Function';
+      message += `\nTemplate: ${templatePreview}`;
+    }
+    
+    // Add engine context information
+    if (context.engine) {
+      message += `\nEngine: ${context.engine}`;
+    }
+    
+    // Add mode context information
+    if (context.mode) {
+      message += `\nMode: ${context.mode}`;
+    }
+    
+    // Add data keys context information
+    if (context.data && Object.keys(context.data).length > 0) {
+      message += `\nData Keys: ${Object.keys(context.data).join(', ')}`;
+    }
+    
+    // Create new error with formatted message
+    const formattedError = new Error(message);
+    formattedError.originalError = error;
+    formattedError.context = context;
+    formattedError.stack = error.stack;
+    
+    return formattedError;
+  }
+  
+  /**
+   * Handle template compilation errors
+   * @param {Error} error - Compilation error object
+   * @param {string} template - Template content
+   * @param {string} templateName - Name of the template
+   * @returns {Error} Formatted compilation error
+   */
+  handleCompilationError(error, template, templateName = 'anonymous') {
+    const context = {
+      type: 'compilation',
+      templateName,
+      templateLength: template.length,
+      errorLocation: this.findErrorLocation(error, template)
+    };
+    
+    return this.formatError(error, context);
+  }
+  
+  /**
+   * Handle template rendering errors
+   * @param {Error} error - Rendering error object
+   * @param {string} templateName - Name of the template
+   * @param {Object} data - Template data object
+   * @returns {Error} Formatted rendering error
+   */
+  handleRenderingError(error, templateName, data = {}) {
+    const context = {
+      type: 'rendering',
+      templateName,
+      dataKeys: Object.keys(data),
+      dataSize: JSON.stringify(data).length
+    };
+    
+    return this.formatError(error, context);
+  }
+  
+  /**
+   * Handle file system errors
+   * @param {Error} error - File system error object
+   * @param {string} filePath - Path to the file
+   * @param {string} operation - File operation being performed
+   * @returns {Error} Formatted file system error
+   */
+  handleFileSystemError(error, filePath, operation = 'read') {
+    const context = {
+      type: 'filesystem',
+      filePath,
+      operation,
+      errorCode: error.code
+    };
+    
+    return this.formatError(error, context);
+  }
+  
+  /**
+   * Find error location in template content
+   * @param {Error} error - Error object
+   * @param {string} template - Template content
+   * @returns {Object|null} Error location information or null if not found
+   * @private
+   */
+  findErrorLocation(error, template) {
+    const stack = error.stack || '';
+    const lines = template.split('\n');
+    
+    // Try to find line number from error message
+    const lineMatch = error.message.match(/line (\d+)/i) || stack.match(/line (\d+)/i);
+    if (lineMatch) {
+      const lineNumber = parseInt(lineMatch[1]) - 1;
+      if (lineNumber >= 0 && lineNumber < lines.length) {
+        return {
+          line: lineNumber + 1,
+          column: 0,
+          snippet: lines[lineNumber].substring(0, 100)
+        };
+      }
+    }
+    
+    // Try to find column from error message
+    const columnMatch = error.message.match(/column (\d+)/i) || stack.match(/column (\d+)/i);
+    if (columnMatch) {
+      const column = parseInt(columnMatch[1]);
+      return {
+        line: 1,
+        column,
+        snippet: template.substring(column - 10, column + 10)
+      };
+    }
+    
+    return null;
+  }
+  
+  /**
+   * Create user-friendly error message for end users
+   * @param {Error} error - Error object
+   * @returns {string} User-friendly error message
+   */
+  getUserFriendlyMessage(error) {
+    const errorType = error.originalError ? error.originalError.name : error.name;
+    
+    switch (errorType) {
+      case 'SyntaxError':
+        return 'Template syntax error, please check if the template syntax is correct.';
+      case 'ReferenceError':
+        return 'Template variable reference error, please check if the variable name is correct.';
+      case 'TypeError':
+        return 'Template type error, please check if the data types match.';
+      case 'RangeError':
+        return 'Template range error, please check loops or conditional statements.';
+      case 'EvalError':
+        return 'Template execution error, please check if the expressions are correct.';
+      case 'URIError':
+        return 'Template URL error, please check URL-related functions.';
+      default:
+        return 'An error occurred during template processing, please check the template and data.';
+    }
+  }
+  
+  /**
+   * Get error recovery suggestions based on error type
+   * @param {Error} error - Error object
+   * @returns {Array<string>} Array of recovery suggestions
+   */
+  getRecoverySuggestions(error) {
+    const suggestions = [];
+    const message = error.message.toLowerCase();
+    
+    if (message.includes('not found') || message.includes('cannot find')) {
+      suggestions.push('Check if the template file path is correct');
+      suggestions.push('Confirm that the template file exists');
+      suggestions.push('Check template file permissions');
+    }
+    
+    if (message.includes('syntax') || message.includes('syntax error')) {
+      suggestions.push('Check if the template syntax is correct');
+      suggestions.push('Confirm all directives are properly closed');
+      suggestions.push('Check variable reference format');
+    }
+    
+    if (message.includes('variable') || message.includes('undefined')) {
+      suggestions.push('Check if the variable name is correct');
+      suggestions.push('Confirm the variable is defined in the data');
+      suggestions.push('Check variable scope');
+    }
+    
+    if (message.includes('cache') || message.includes('caching')) {
+      suggestions.push('Try clearing the cache');
+      suggestions.push('Check cache configuration');
+      suggestions.push('Restart the template engine');
+    }
+    
+    if (message.includes('permission') || message.includes('access denied')) {
+      suggestions.push('Check file read/write permissions');
+      suggestions.push('Confirm the running user has sufficient permissions');
+      suggestions.push('Check directory permissions');
+    }
+    
+    // Always add general suggestions
+    suggestions.push('View detailed error logs');
+    suggestions.push('Check template engine configuration');
+    suggestions.push('Simplify the template and debug step by step');
+    
+    return suggestions;
+  }
+}
+
+export default ErrorHandler;