voltjs-framework 1.0.0

package/src/ui/template.js

@@ -0,0 +1,448 @@
+/**
+ * VoltJS Template Engine
+ * 
+ * Advanced server-side template engine with layouts, partials, 
+ * conditionals, loops, helpers, and auto-escaping.
+ * 
+ * Syntax:
+ *   {{ variable }}          - Escaped output
+ *   {{{ variable }}}        - Raw output
+ *   {#if condition} ... {/if}
+ *   {#if condition} ... {#else} ... {/if}
+ *   {#each items as item} ... {/each}
+ *   {#each items as item, index} ... {/each}
+ *   {> partialName}
+ *   {#layout "layoutName"} ... {/layout}
+ *   {#slot name} default {/slot}
+ *   {#block name} content {/block}
+ *   {{ helper(arg1, arg2) }}
+ * 
+ * @example
+ * const { TemplateEngine } = require('voltjs');
+ * 
+ * const engine = new TemplateEngine({ views: './views' });
+ * engine.addHelper('upper', (str) => str.toUpperCase());
+ * 
+ * const html = engine.render('index', { title: 'Home', user: 'Jane' });
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+class TemplateEngine {
+  constructor(options = {}) {
+    this.viewsDir = options.views || './views';
+    this.ext = options.ext || '.volt.html';
+    this.cache = new Map();
+    this.cacheEnabled = options.cache !== false;
+    this.helpers = {};
+    this.globals = {};
+    this.layouts = {};
+    this.partials = {};
+
+    // Built-in helpers
+    this.addHelper('upper', s => String(s).toUpperCase());
+    this.addHelper('lower', s => String(s).toLowerCase());
+    this.addHelper('capitalize', s => String(s).charAt(0).toUpperCase() + String(s).slice(1));
+    this.addHelper('json', v => JSON.stringify(v, null, 2));
+    this.addHelper('date', d => new Date(d).toLocaleDateString());
+    this.addHelper('time', d => new Date(d).toLocaleTimeString());
+    this.addHelper('currency', (n, c = 'USD') => new Intl.NumberFormat('en-US', { style: 'currency', currency: c }).format(n));
+    this.addHelper('number', n => new Intl.NumberFormat().format(n));
+    this.addHelper('truncate', (s, l = 50) => String(s).length > l ? String(s).substring(0, l) + '...' : String(s));
+    this.addHelper('default', (v, d) => v ?? d);
+    this.addHelper('length', v => (Array.isArray(v) ? v.length : String(v).length));
+    this.addHelper('keys', v => Object.keys(v || {}));
+    this.addHelper('values', v => Object.values(v || {}));
+    this.addHelper('reverse', v => Array.isArray(v) ? [...v].reverse() : String(v).split('').reverse().join(''));
+    this.addHelper('first', v => Array.isArray(v) ? v[0] : v);
+    this.addHelper('last', v => Array.isArray(v) ? v[v.length - 1] : v);
+    this.addHelper('join', (v, sep = ', ') => Array.isArray(v) ? v.join(sep) : v);
+    this.addHelper('range', (start, end) => Array.from({ length: end - start + 1 }, (_, i) => start + i));
+    this.addHelper('pluralize', (n, s, p) => n === 1 ? s : (p || s + 's'));
+    this.addHelper('ago', d => {
+      const ms = Date.now() - new Date(d).getTime();
+      const s = Math.floor(ms / 1000);
+      if (s < 60) return `${s}s ago`;
+      const m = Math.floor(s / 60);
+      if (m < 60) return `${m}m ago`;
+      const h = Math.floor(m / 60);
+      if (h < 24) return `${h}h ago`;
+      return `${Math.floor(h / 24)}d ago`;
+    });
+  }
+
+  /** Register a custom helper */
+  addHelper(name, fn) {
+    this.helpers[name] = fn;
+    return this;
+  }
+
+  /** Set global variables (available in all templates) */
+  addGlobal(key, value) {
+    this.globals[key] = value;
+    return this;
+  }
+
+  /** Register a partial template */
+  addPartial(name, template) {
+    this.partials[name] = template;
+    return this;
+  }
+
+  /** Render a template file */
+  render(templateName, data = {}) {
+    const template = this._loadTemplate(templateName);
+    return this._compile(template, { ...this.globals, ...data });
+  }
+
+  /** Render a raw template string */
+  renderString(template, data = {}) {
+    return this._compile(template, { ...this.globals, ...data });
+  }
+
+  /** Express/Volt engine integration */
+  engine() {
+    return (filePath, data, callback) => {
+      try {
+        const template = fs.readFileSync(filePath, 'utf-8');
+        const html = this._compile(template, { ...this.globals, ...data });
+        callback(null, html);
+      } catch (err) {
+        callback(err);
+      }
+    };
+  }
+
+  // ===== COMPILATION =====
+
+  _compile(template, data) {
+    let html = template;
+
+    // 1. Process layouts
+    html = this._processLayouts(html, data);
+
+    // 2. Process blocks
+    html = this._processBlocks(html, data);
+
+    // 3. Process partials
+    html = this._processPartials(html, data);
+
+    // 4. Process conditionals
+    html = this._processConditionals(html, data);
+
+    // 5. Process loops
+    html = this._processLoops(html, data);
+
+    // 6. Process raw output {{{ }}}
+    html = html.replace(/\{\{\{(.+?)\}\}\}/g, (_, expr) => {
+      return this._evaluate(expr.trim(), data) ?? '';
+    });
+
+    // 7. Process escaped output {{ }}
+    html = html.replace(/\{\{(.+?)\}\}/g, (_, expr) => {
+      const value = this._evaluate(expr.trim(), data);
+      return this._escape(value ?? '');
+    });
+
+    return html;
+  }
+
+  _processLayouts(html, data) {
+    const layoutRegex = /\{#layout\s+"(.+?)"\s*\}([\s\S]*?)\{\/layout\}/g;
+    let match;
+
+    while ((match = layoutRegex.exec(html)) !== null) {
+      const layoutName = match[1];
+      const content = match[2];
+      const layoutTemplate = this._loadTemplate(layoutName);
+
+      // Extract slots from content
+      const slots = {};
+      const slotRegex = /\{#slot\s+(\w+)\}([\s\S]*?)\{\/slot\}/g;
+      let slotMatch;
+      while ((slotMatch = slotRegex.exec(content)) !== null) {
+        slots[slotMatch[1]] = slotMatch[2];
+      }
+
+      // Replace slots in layout
+      let compiled = layoutTemplate.replace(
+        /\{#slot\s+(\w+)\}([\s\S]*?)\{\/slot\}/g,
+        (_, name, defaultContent) => slots[name] || defaultContent
+      );
+
+      // Replace {#slot content} with the main content
+      compiled = compiled.replace(
+        /\{#slot\s+content\s*\}/g,
+        content.replace(/\{#slot\s+\w+\}[\s\S]*?\{\/slot\}/g, '').trim()
+      );
+
+      html = html.replace(match[0], compiled);
+    }
+
+    return html;
+  }
+
+  _processBlocks(html, data) {
+    return html.replace(
+      /\{#block\s+(\w+)\}([\s\S]*?)\{\/block\}/g,
+      (_, name, content) => this._compile(content.trim(), data)
+    );
+  }
+
+  _processPartials(html, data) {
+    return html.replace(/\{>\s*(\w+)\s*\}/g, (_, name) => {
+      // Check registered partials first
+      if (this.partials[name]) {
+        return this._compile(this.partials[name], data);
+      }
+      // Try loading from file
+      try {
+        const template = this._loadTemplate(`partials/${name}`);
+        return this._compile(template, data);
+      } catch {
+        return `<!-- Partial not found: ${name} -->`;
+      }
+    });
+  }
+
+  _processConditionals(html, data) {
+    // Nested-aware processing
+    let result = html;
+    let changed = true;
+    let maxIter = 50;
+
+    while (changed && maxIter-- > 0) {
+      changed = false;
+
+      // {#if}{#else}{/if}
+      result = result.replace(
+        /\{#if\s+(.+?)\}([\s\S]*?)\{#else\}([\s\S]*?)\{\/if\}/,
+        (match, condition, trueBlock, falseBlock) => {
+          changed = true;
+          const val = this._evaluate(condition, data);
+          return val ? this._compile(trueBlock, data) : this._compile(falseBlock, data);
+        }
+      );
+
+      // {#if}{/if} (without else)
+      result = result.replace(
+        /\{#if\s+(.+?)\}([\s\S]*?)\{\/if\}/,
+        (match, condition, block) => {
+          changed = true;
+          const val = this._evaluate(condition, data);
+          return val ? this._compile(block, data) : '';
+        }
+      );
+
+      // {#unless}{/unless}
+      result = result.replace(
+        /\{#unless\s+(.+?)\}([\s\S]*?)\{\/unless\}/,
+        (match, condition, block) => {
+          changed = true;
+          const val = this._evaluate(condition, data);
+          return !val ? this._compile(block, data) : '';
+        }
+      );
+    }
+
+    return result;
+  }
+
+  _processLoops(html, data) {
+    let result = html;
+    let changed = true;
+    let maxIter = 50;
+
+    while (changed && maxIter-- > 0) {
+      changed = false;
+
+      result = result.replace(
+        /\{#each\s+(\S+)\s+as\s+(\w+)(?:\s*,\s*(\w+))?\}([\s\S]*?)\{\/each\}/,
+        (match, listExpr, itemName, indexName, body) => {
+          changed = true;
+          const list = this._evaluate(listExpr, data);
+          if (!Array.isArray(list)) return '';
+
+          return list.map((item, index) => {
+            const loopData = {
+              ...data,
+              [itemName]: item,
+              ...(indexName ? { [indexName]: index } : {}),
+              $index: index,
+              $first: index === 0,
+              $last: index === list.length - 1,
+              $even: index % 2 === 0,
+              $odd: index % 2 !== 0,
+              $length: list.length,
+            };
+            return this._compile(body, loopData);
+          }).join('');
+        }
+      );
+    }
+
+    return result;
+  }
+
+  _evaluate(expr, data) {
+    // Helper call: helperName(args)
+    const helperMatch = expr.match(/^(\w+)\((.*)?\)$/);
+    if (helperMatch) {
+      const [, name, argsStr] = helperMatch;
+      if (this.helpers[name]) {
+        const args = argsStr ? this._parseArgs(argsStr, data) : [];
+        return this.helpers[name](...args);
+      }
+    }
+
+    // Comparison: a == b, a != b, a > b, etc.
+    const compMatch = expr.match(/^(.+?)\s*(===|!==|==|!=|>=|<=|>|<)\s*(.+)$/);
+    if (compMatch) {
+      const left = this._evaluate(compMatch[1].trim(), data);
+      const right = this._evaluate(compMatch[3].trim(), data);
+      switch (compMatch[2]) {
+        case '===': return left === right;
+        case '!==': return left !== right;
+        case '==': return left == right;
+        case '!=': return left != right;
+        case '>': return left > right;
+        case '<': return left < right;
+        case '>=': return left >= right;
+        case '<=': return left <= right;
+      }
+    }
+
+    // Logical: a && b, a || b
+    if (expr.includes('&&')) {
+      const parts = expr.split('&&').map(p => p.trim());
+      return parts.every(p => this._evaluate(p, data));
+    }
+    if (expr.includes('||')) {
+      const parts = expr.split('||').map(p => p.trim());
+      return parts.some(p => this._evaluate(p, data));
+    }
+
+    // Negation: !value
+    if (expr.startsWith('!')) {
+      return !this._evaluate(expr.slice(1).trim(), data);
+    }
+
+    // String literal
+    if ((expr.startsWith('"') && expr.endsWith('"')) || (expr.startsWith("'") && expr.endsWith("'"))) {
+      return expr.slice(1, -1);
+    }
+
+    // Number literal
+    if (!isNaN(expr)) return Number(expr);
+
+    // Boolean
+    if (expr === 'true') return true;
+    if (expr === 'false') return false;
+    if (expr === 'null' || expr === 'undefined') return null;
+
+    // Ternary: condition ? a : b
+    const ternary = expr.match(/^(.+?)\s*\?\s*(.+?)\s*:\s*(.+)$/);
+    if (ternary) {
+      return this._evaluate(ternary[1].trim(), data)
+        ? this._evaluate(ternary[2].trim(), data)
+        : this._evaluate(ternary[3].trim(), data);
+    }
+
+    // Dot-notation property access: user.name.first
+    return this._resolvePath(expr, data);
+  }
+
+  _resolvePath(path, data) {
+    // Handle array access: items[0].name
+    const parts = path.replace(/\[(\d+)\]/g, '.$1').split('.');
+    let value = data;
+    for (const part of parts) {
+      if (value === null || value === undefined) return undefined;
+      value = value[part];
+    }
+    return value;
+  }
+
+  _parseArgs(argsStr, data) {
+    const args = [];
+    let current = '';
+    let depth = 0;
+    let inString = false;
+    let stringChar = '';
+
+    for (let i = 0; i < argsStr.length; i++) {
+      const ch = argsStr[i];
+      if (inString) {
+        current += ch;
+        if (ch === stringChar) inString = false;
+      } else if (ch === '"' || ch === "'") {
+        inString = true;
+        stringChar = ch;
+        current += ch;
+      } else if (ch === '(') {
+        depth++;
+        current += ch;
+      } else if (ch === ')') {
+        depth--;
+        current += ch;
+      } else if (ch === ',' && depth === 0) {
+        args.push(this._evaluate(current.trim(), data));
+        current = '';
+      } else {
+        current += ch;
+      }
+    }
+    if (current.trim()) {
+      args.push(this._evaluate(current.trim(), data));
+    }
+    return args;
+  }
+
+  _escape(value) {
+    const str = String(value);
+    const map = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#039;' };
+    return str.replace(/[&<>"']/g, c => map[c]);
+  }
+
+  _loadTemplate(name) {
+    const cacheKey = name;
+    if (this.cacheEnabled && this.cache.has(cacheKey)) {
+      return this.cache.get(cacheKey);
+    }
+
+    // Try multiple extensions
+    const extensions = [this.ext, '.html', '.volt', '.hbs', '.ejs'];
+    let template = null;
+
+    for (const ext of extensions) {
+      const filePath = path.join(this.viewsDir, name + ext);
+      if (fs.existsSync(filePath)) {
+        template = fs.readFileSync(filePath, 'utf-8');
+        break;
+      }
+    }
+
+    // Try exact path
+    if (!template) {
+      const exactPath = path.join(this.viewsDir, name);
+      if (fs.existsSync(exactPath)) {
+        template = fs.readFileSync(exactPath, 'utf-8');
+      }
+    }
+
+    if (!template) {
+      throw new Error(`Template not found: ${name} (searched in ${this.viewsDir})`);
+    }
+
+    if (this.cacheEnabled) {
+      this.cache.set(cacheKey, template);
+    }
+
+    return template;
+  }
+}
+
+module.exports = { TemplateEngine };

package/src/utils/cache.js

@@ -0,0 +1,216 @@
+/**
+ * VoltJS Cache
+ * 
+ * High-performance in-memory cache with TTL, LRU eviction, and namespaces.
+ * 
+ * @example
+ * const { Cache } = require('voltjs');
+ * 
+ * const cache = new Cache({ maxSize: 1000, defaultTTL: 300 });
+ * cache.set('user:1', { name: 'John' }, 60); // 60s TTL
+ * const user = cache.get('user:1');
+ * 
+ * // Or use as middleware
+ * app.get('/api/data', Cache.middleware(60), handler);
+ */
+
+'use strict';
+
+class Cache {
+  constructor(options = {}) {
+    this.maxSize = options.maxSize || 10000;
+    this.defaultTTL = options.defaultTTL || 300; // 5 min
+    this.store = new Map();
+    this.hits = 0;
+    this.misses = 0;
+
+    // Auto-cleanup expired entries
+    this._cleanupInterval = setInterval(() => this._cleanup(), 60000);
+    if (this._cleanupInterval.unref) this._cleanupInterval.unref();
+  }
+
+  /** Set a cache entry */
+  set(key, value, ttl) {
+    const expiresAt = Date.now() + ((ttl || this.defaultTTL) * 1000);
+    
+    // LRU: Delete and re-insert to move to end
+    if (this.store.has(key)) {
+      this.store.delete(key);
+    }
+
+    // Evict oldest if at capacity
+    if (this.store.size >= this.maxSize) {
+      const firstKey = this.store.keys().next().value;
+      this.store.delete(firstKey);
+    }
+
+    this.store.set(key, { value, expiresAt, createdAt: Date.now() });
+    return this;
+  }
+
+  /** Get a cache entry */
+  get(key) {
+    const entry = this.store.get(key);
+    
+    if (!entry) {
+      this.misses++;
+      return null;
+    }
+
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      this.misses++;
+      return null;
+    }
+
+    // LRU: Move to end
+    this.store.delete(key);
+    this.store.set(key, entry);
+    this.hits++;
+
+    return entry.value;
+  }
+
+  /** Get or set (fetch from callback if missing) */
+  async getOrSet(key, fetchFn, ttl) {
+    const cached = this.get(key);
+    if (cached !== null) return cached;
+
+    const value = await fetchFn();
+    this.set(key, value, ttl);
+    return value;
+  }
+
+  /** Check if key exists and not expired */
+  has(key) {
+    const entry = this.store.get(key);
+    if (!entry) return false;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return false;
+    }
+    return true;
+  }
+
+  /** Delete a key */
+  delete(key) {
+    return this.store.delete(key);
+  }
+
+  /** Delete keys matching pattern */
+  deletePattern(pattern) {
+    const regex = new RegExp(pattern.replace(/\*/g, '.*'));
+    let count = 0;
+    for (const key of this.store.keys()) {
+      if (regex.test(key)) {
+        this.store.delete(key);
+        count++;
+      }
+    }
+    return count;
+  }
+
+  /** Clear all entries */
+  clear() {
+    this.store.clear();
+    this.hits = 0;
+    this.misses = 0;
+    return this;
+  }
+
+  /** Clear entries by namespace (prefix) */
+  clearNamespace(namespace) {
+    const prefix = namespace + ':';
+    for (const key of this.store.keys()) {
+      if (key.startsWith(prefix)) {
+        this.store.delete(key);
+      }
+    }
+    return this;
+  }
+
+  /** Get cache stats */
+  stats() {
+    const total = this.hits + this.misses;
+    return {
+      size: this.store.size,
+      maxSize: this.maxSize,
+      hits: this.hits,
+      misses: this.misses,
+      hitRate: total > 0 ? (this.hits / total * 100).toFixed(1) + '%' : '0%',
+    };
+  }
+
+  /** Get all keys */
+  keys() {
+    return [...this.store.keys()];
+  }
+
+  /** Increment a numeric value */
+  increment(key, amount = 1) {
+    const val = this.get(key) || 0;
+    this.set(key, val + amount);
+    return val + amount;
+  }
+
+  /** Decrement a numeric value */
+  decrement(key, amount = 1) {
+    return this.increment(key, -amount);
+  }
+
+  /** Get remaining TTL in seconds */
+  ttl(key) {
+    const entry = this.store.get(key);
+    if (!entry) return -1;
+    const remaining = Math.max(0, entry.expiresAt - Date.now());
+    return Math.ceil(remaining / 1000);
+  }
+
+  /** Express/Volt middleware for response caching */
+  static middleware(ttl = 60) {
+    const cache = new Cache({ defaultTTL: ttl });
+    
+    return (req, res) => {
+      if (req.method !== 'GET') return;
+      
+      const key = `resp:${req.url}`;
+      const cached = cache.get(key);
+      
+      if (cached) {
+        res.setHeader('X-Cache', 'HIT');
+        res.setHeader('Content-Type', cached.contentType || 'application/json');
+        res.end(cached.body);
+        return false; // Stops middleware chain
+      }
+
+      // Monkey-patch res.end to cache the response
+      const originalEnd = res.end.bind(res);
+      res.end = (body) => {
+        cache.set(key, {
+          body,
+          contentType: res.getHeader('content-type'),
+        });
+        res.setHeader('X-Cache', 'MISS');
+        originalEnd(body);
+      };
+    };
+  }
+
+  /** Destroy cache (stop cleanup timer) */
+  destroy() {
+    clearInterval(this._cleanupInterval);
+    this.store.clear();
+  }
+
+  /** @private */
+  _cleanup() {
+    const now = Date.now();
+    for (const [key, entry] of this.store) {
+      if (now > entry.expiresAt) {
+        this.store.delete(key);
+      }
+    }
+  }
+}
+
+module.exports = { Cache };