sehawq.db 3.0.0 → 4.0.1

package/src/core/Storage.js

@@ -0,0 +1,322 @@
+/**
+ * Storage Layer - Handles all file I/O with performance optimizations
+ * 
+ * Because reading/writing files should be fast, not frustrating
+ * Added some tricks I learned the hard way 🎯
+ */
+
+const fs = require('fs').promises;
+const path = require('path');
+const { performance } = require('perf_hooks');
+
+class Storage {
+  constructor(filePath, options = {}) {
+    this.filePath = filePath;
+    this.options = {
+      compression: false,
+      backupOnWrite: true,
+      backupRetention: 5, // Keep last 5 backups
+      maxFileSize: 50 * 1024 * 1024, // 50MB limit
+      ...options
+    };
+
+    this.writeQueue = [];
+    this.isWriting = false;
+    this.stats = {
+      reads: 0,
+      writes: 0,
+      backups: 0,
+      errors: 0,
+      totalReadTime: 0,
+      totalWriteTime: 0
+    };
+
+    this._ensureDirectory();
+  }
+
+  /**
+   * Make sure the directory exists
+   * Learned this the hard way - files don't create their own folders! 😅
+   */
+  async _ensureDirectory() {
+    const dir = path.dirname(this.filePath);
+    try {
+      await fs.access(dir);
+    } catch (error) {
+      await fs.mkdir(dir, { recursive: true });
+    }
+  }
+
+  /**
+   * Read data with performance tracking and caching
+   */
+  async read() {
+    const startTime = performance.now();
+    
+    try {
+      // Check if file exists first
+      try {
+        await fs.access(this.filePath);
+      } catch (error) {
+        // File doesn't exist - return empty data
+        return {};
+      }
+
+      const data = await fs.readFile(this.filePath, 'utf8');
+      
+      // Performance tracking
+      const readTime = performance.now() - startTime;
+      this.stats.reads++;
+      this.stats.totalReadTime += readTime;
+
+      if (this.options.debug) {
+        console.log(`📖 Read ${data.length} bytes in ${readTime.toFixed(2)}ms`);
+      }
+
+      return JSON.parse(data);
+    } catch (error) {
+      this.stats.errors++;
+      console.error('🚨 Storage read error:', error);
+      
+      // Try to recover from backup if main file is corrupted
+      return await this._recoverFromBackup();
+    }
+  }
+
+  /**
+   * Write data with queuing and atomic operations
+   * Prevents corruption and handles concurrent writes
+   */
+  async write(data) {
+    return new Promise((resolve, reject) => {
+      // Queue the write operation
+      this.writeQueue.push({ data, resolve, reject });
+      
+      if (!this.isWriting) {
+        this._processWriteQueue();
+      }
+    });
+  }
+
+  /**
+   * Process write queue one by one
+   * Prevents race conditions and file corruption
+   */
+  async _processWriteQueue() {
+    if (this.writeQueue.length === 0 || this.isWriting) {
+      return;
+    }
+
+    this.isWriting = true;
+    const startTime = performance.now();
+
+    try {
+      const { data, resolve, reject } = this.writeQueue.shift();
+
+      // Check file size limit
+      const dataSize = Buffer.byteLength(JSON.stringify(data), 'utf8');
+      if (dataSize > this.options.maxFileSize) {
+        throw new Error(`File size limit exceeded: ${dataSize} > ${this.options.maxFileSize}`);
+      }
+
+      // Create backup before writing
+      if (this.options.backupOnWrite) {
+        await this._createBackup();
+      }
+
+      // Atomic write - write to temp file then rename
+      const tempPath = this.filePath + '.tmp';
+      const serializedData = JSON.stringify(data, null, 2);
+      
+      await fs.writeFile(tempPath, serializedData, 'utf8');
+      await fs.rename(tempPath, this.filePath);
+
+      // Performance tracking
+      const writeTime = performance.now() - startTime;
+      this.stats.writes++;
+      this.stats.totalWriteTime += writeTime;
+
+      if (this.options.debug) {
+        console.log(`💾 Written ${serializedData.length} bytes in ${writeTime.toFixed(2)}ms`);
+      }
+
+      resolve();
+    } catch (error) {
+      this.stats.errors++;
+      console.error('🚨 Storage write error:', error);
+      this.writeQueue[0]?.reject(error);
+    } finally {
+      this.isWriting = false;
+      
+      // Process next item in queue
+      if (this.writeQueue.length > 0) {
+        setImmediate(() => this._processWriteQueue());
+      }
+    }
+  }
+
+  /**
+   * Create backup of current data file
+   * Saved my data more times than I can count! 💾
+   */
+  async _createBackup() {
+    try {
+      // Check if source file exists
+      try {
+        await fs.access(this.filePath);
+      } catch (error) {
+        // No file to backup - that's fine
+        return;
+      }
+
+      const timestamp = new Date().toISOString()
+        .replace(/[:.]/g, '-')
+        .replace('T', '_')
+        .split('.')[0];
+      
+      const backupPath = `${this.filePath}.backup_${timestamp}`;
+      
+      await fs.copyFile(this.filePath, backupPath);
+      this.stats.backups++;
+
+      // Clean up old backups
+      await this._cleanupOldBackups();
+
+      if (this.options.debug) {
+        console.log(`🔐 Backup created: ${backupPath}`);
+      }
+    } catch (error) {
+      console.error('🚨 Backup creation failed:', error);
+      // Don't throw - backup failure shouldn't block main write
+    }
+  }
+
+  /**
+   * Keep only the most recent backups
+   */
+  async _cleanupOldBackups() {
+    try {
+      const dir = path.dirname(this.filePath);
+      const fileName = path.basename(this.filePath);
+      
+      const files = await fs.readdir(dir);
+      const backupFiles = files
+        .filter(file => file.startsWith(fileName + '.backup_'))
+        .sort()
+        .reverse();
+
+      // Remove old backups beyond retention limit
+      for (const file of backupFiles.slice(this.options.backupRetention)) {
+        await fs.unlink(path.join(dir, file));
+        
+        if (this.options.debug) {
+          console.log(`🗑️  Cleaned up old backup: ${file}`);
+        }
+      }
+    } catch (error) {
+      console.error('🚨 Backup cleanup failed:', error);
+    }
+  }
+
+  /**
+   * Try to recover data from backup if main file is corrupted
+   */
+  async _recoverFromBackup() {
+    try {
+      const dir = path.dirname(this.filePath);
+      const fileName = path.basename(this.filePath);
+      
+      const files = await fs.readdir(dir);
+      const backupFiles = files
+        .filter(file => file.startsWith(fileName + '.backup_'))
+        .sort()
+        .reverse();
+
+      for (const backupFile of backupFiles) {
+        try {
+          const backupPath = path.join(dir, backupFile);
+          const data = await fs.readFile(backupPath, 'utf8');
+          const parsed = JSON.parse(data);
+          
+          console.log(`🔧 Recovered data from backup: ${backupFile}`);
+          
+          // Restore the backup to main file
+          await this.write(parsed);
+          
+          return parsed;
+        } catch (error) {
+          // This backup is also corrupted, try next one
+          continue;
+        }
+      }
+      
+      throw new Error('No valid backup found for recovery');
+    } catch (error) {
+      console.error('🚨 Recovery from backup failed:', error);
+      return {}; // Return empty data as last resort
+    }
+  }
+
+  /**
+   * Get storage statistics
+   */
+  getStats() {
+    return {
+      ...this.stats,
+      avgReadTime: this.stats.reads > 0 
+        ? (this.stats.totalReadTime / this.stats.reads).toFixed(2) + 'ms'
+        : '0ms',
+      avgWriteTime: this.stats.writes > 0 
+        ? (this.stats.totalWriteTime / this.stats.writes).toFixed(2) + 'ms'
+        : '0ms',
+      queueLength: this.writeQueue.length,
+      isWriting: this.isWriting
+    };
+  }
+
+  /**
+   * Manual backup creation
+   */
+  async createBackup() {
+    return await this._createBackup();
+  }
+
+  /**
+   * Get list of available backups
+   */
+  async listBackups() {
+    try {
+      const dir = path.dirname(this.filePath);
+      const fileName = path.basename(this.filePath);
+      
+      const files = await fs.readdir(dir);
+      return files
+        .filter(file => file.startsWith(fileName + '.backup_'))
+        .sort()
+        .reverse();
+    } catch (error) {
+      return [];
+    }
+  }
+
+  /**
+   * Restore from specific backup
+   */
+  async restoreBackup(backupName) {
+    const backupPath = path.join(path.dirname(this.filePath), backupName);
+    
+    try {
+      const data = await fs.readFile(backupPath, 'utf8');
+      const parsed = JSON.parse(data);
+      
+      await this.write(parsed);
+      console.log(`✅ Restored from backup: ${backupName}`);
+      
+      return parsed;
+    } catch (error) {
+      throw new Error(`Failed to restore backup ${backupName}: ${error.message}`);
+    }
+  }
+}
+
+module.exports = Storage;

package/src/core/Validator.js

@@ -0,0 +1,325 @@
+/**
+ * Data Validator - Keeps your data clean and proper 🧼
+ * 
+ * Because garbage in, garbage out is a real thing
+ * Validates everything from emails to custom business rules
+ */
+
+class Validator {
+  constructor() {
+    this.rules = new Map();
+    this.customValidators = new Map();
+    
+    this._setupBuiltinRules();
+  }
+
+  /**
+   * Setup built-in validation rules
+   */
+  _setupBuiltinRules() {
+    // Type validators
+    this.rules.set('string', value => typeof value === 'string');
+    this.rules.set('number', value => typeof value === 'number' && !isNaN(value));
+    this.rules.set('boolean', value => typeof value === 'boolean');
+    this.rules.set('array', value => Array.isArray(value));
+    this.rules.set('object', value => value && typeof value === 'object' && !Array.isArray(value));
+    this.rules.set('function', value => typeof value === 'function');
+    this.rules.set('null', value => value === null);
+    this.rules.set('undefined', value => value === undefined);
+
+    // Common format validators
+    this.rules.set('email', value => 
+      typeof value === 'string' && 
+      /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
+    );
+
+    this.rules.set('url', value => {
+      if (typeof value !== 'string') return false;
+      try {
+        new URL(value);
+        return true;
+      } catch {
+        return false;
+      }
+    });
+
+    this.rules.set('uuid', value =>
+      typeof value === 'string' &&
+      /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value)
+    );
+
+    this.rules.set('date', value => 
+      value instanceof Date && !isNaN(value.getTime())
+    );
+
+    this.rules.set('hexColor', value =>
+      typeof value === 'string' &&
+      /^#?([0-9A-F]{3}|[0-9A-F]{6})$/i.test(value)
+    );
+
+    // Comparison validators
+    this.rules.set('min', (value, min) => {
+      if (typeof value === 'number') return value >= min;
+      if (typeof value === 'string' || Array.isArray(value)) return value.length >= min;
+      return false;
+    });
+
+    this.rules.set('max', (value, max) => {
+      if (typeof value === 'number') return value <= max;
+      if (typeof value === 'string' || Array.isArray(value)) return value.length <= max;
+      return false;
+    });
+
+    this.rules.set('range', (value, [min, max]) => {
+      if (typeof value !== 'number') return false;
+      return value >= min && value <= max;
+    });
+
+    this.rules.set('minLength', (value, min) => 
+      (typeof value === 'string' || Array.isArray(value)) && value.length >= min
+    );
+
+    this.rules.set('maxLength', (value, max) => 
+      (typeof value === 'string' || Array.isArray(value)) && value.length <= max
+    );
+
+    this.rules.set('length', (value, length) => 
+      (typeof value === 'string' || Array.isArray(value)) && value.length === length
+    );
+
+    // Pattern validators
+    this.rules.set('pattern', (value, pattern) => 
+      typeof value === 'string' && pattern.test(value)
+    );
+
+    this.rules.set('alphanumeric', value => 
+      typeof value === 'string' && /^[a-zA-Z0-9]+$/.test(value)
+    );
+
+    this.rules.set('numeric', value => 
+      typeof value === 'string' && /^\d+$/.test(value)
+    );
+
+    // Collection validators
+    this.rules.set('in', (value, allowed) => 
+      Array.isArray(allowed) && allowed.includes(value)
+    );
+
+    this.rules.set('notIn', (value, disallowed) => 
+      Array.isArray(disallowed) && !disallowed.includes(value)
+    );
+
+    // Special validators
+    this.rules.set('required', value => 
+      value !== null && value !== undefined && value !== ''
+    );
+
+    this.rules.set('optional', () => true);
+  }
+
+  /**
+   * Add custom validator
+   */
+  addRule(name, validatorFn) {
+    if (this.rules.has(name) || this.customValidators.has(name)) {
+      throw new Error(`Validator '${name}' already exists`);
+    }
+    
+    this.customValidators.set(name, validatorFn);
+    return this;
+  }
+
+  /**
+   * Remove validator
+   */
+  removeRule(name) {
+    this.rules.delete(name);
+    this.customValidators.delete(name);
+    return this;
+  }
+
+  /**
+   * Validate single value against rules
+   */
+  validateValue(value, rules) {
+    const errors = [];
+
+    for (const rule of rules) {
+      const [ruleName, ...ruleArgs] = Array.isArray(rule) ? rule : [rule];
+      
+      let isValid = false;
+      
+      // Check built-in rules first
+      if (this.rules.has(ruleName)) {
+        const validator = this.rules.get(ruleName);
+        isValid = validator(value, ...ruleArgs);
+      }
+      // Check custom rules
+      else if (this.customValidators.has(ruleName)) {
+        const validator = this.customValidators.get(ruleName);
+        isValid = validator(value, ...ruleArgs);
+      }
+      else {
+        errors.push(`Unknown validation rule: ${ruleName}`);
+        continue;
+      }
+
+      if (!isValid) {
+        errors.push(this._formatError(ruleName, ruleArgs, value));
+      }
+    }
+
+    return {
+      isValid: errors.length === 0,
+      errors,
+      value
+    };
+  }
+
+  /**
+   * Validate object against schema
+   */
+  validateObject(obj, schema) {
+    const errors = {};
+    let isValid = true;
+
+    for (const [field, fieldRules] of Object.entries(schema)) {
+      const value = obj[field];
+      const result = this.validateValue(value, fieldRules);
+      
+      if (!result.isValid) {
+        errors[field] = result.errors;
+        isValid = false;
+      }
+    }
+
+    return {
+      isValid,
+      errors,
+      data: obj
+    };
+  }
+
+  /**
+   * Create schema validator
+   */
+  schema(schemaDef) {
+    return (data) => this.validateObject(data, schemaDef);
+  }
+
+  /**
+   * Format validation error
+   */
+  _formatError(rule, args, value) {
+    const valueStr = typeof value === 'string' ? `"${value}"` : JSON.stringify(value);
+    
+    switch (rule) {
+      case 'required':
+        return 'Field is required';
+      case 'min':
+        return `Value must be at least ${args[0]}`;
+      case 'max':
+        return `Value must be at most ${args[0]}`;
+      case 'minLength':
+        return `Length must be at least ${args[0]} characters`;
+      case 'maxLength':
+        return `Length must be at most ${args[0]} characters`;
+      case 'length':
+        return `Length must be exactly ${args[0]} characters`;
+      case 'range':
+        return `Value must be between ${args[0][0]} and ${args[0][1]}`;
+      case 'email':
+        return 'Must be a valid email address';
+      case 'url':
+        return 'Must be a valid URL';
+      case 'uuid':
+        return 'Must be a valid UUID';
+      case 'pattern':
+        return 'Value does not match required pattern';
+      case 'in':
+        return `Value must be one of: ${args[0].join(', ')}`;
+      case 'notIn':
+        return `Value must not be one of: ${args[0].join(', ')}`;
+      default:
+        return `Failed validation: ${rule}`;
+    }
+  }
+
+  /**
+   * Quick validators (static methods)
+   */
+  static isEmail(value) {
+    return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value);
+  }
+
+  static isURL(value) {
+    try {
+      new URL(value);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  static isDate(value) {
+    return value instanceof Date && !isNaN(value.getTime());
+  }
+
+  static isNumber(value) {
+    return typeof value === 'number' && !isNaN(value);
+  }
+
+  static isString(value) {
+    return typeof value === 'string';
+  }
+
+  static isArray(value) {
+    return Array.isArray(value);
+  }
+
+  static isObject(value) {
+    return value && typeof value === 'object' && !Array.isArray(value);
+  }
+
+  static isEmpty(value) {
+    if (value === null || value === undefined) return true;
+    if (typeof value === 'string') return value.trim().length === 0;
+    if (Array.isArray(value)) return value.length === 0;
+    if (typeof value === 'object') return Object.keys(value).length === 0;
+    return false;
+  }
+
+  /**
+   * Sanitize functions
+   */
+  static trim(value) {
+    return typeof value === 'string' ? value.trim() : value;
+  }
+
+  static toLowerCase(value) {
+    return typeof value === 'string' ? value.toLowerCase() : value;
+  }
+
+  static toUpperCase(value) {
+    return typeof value === 'string' ? value.toUpperCase() : value;
+  }
+
+  static toNumber(value) {
+    if (typeof value === 'number') return value;
+    const num = parseFloat(value);
+    return isNaN(num) ? value : num;
+  }
+
+  static toBoolean(value) {
+    if (typeof value === 'boolean') return value;
+    if (typeof value === 'string') {
+      return value.toLowerCase() === 'true' || value === '1';
+    }
+    return !!value;
+  }
+}
+
+// Export singleton instance
+const validator = new Validator();
+module.exports = validator;
+module.exports.Validator = Validator;