voltjs-framework 1.0.0

package/src/core/config.js

@@ -0,0 +1,232 @@
+/**
+ * VoltJS Configuration Manager
+ * 
+ * Handles configuration with:
+ * - Default values
+ * - Environment variable overrides
+ * - Config file loading (volt.config.js)
+ * - Nested key access with dot notation
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+const DEFAULTS = {
+  env: process.env.NODE_ENV || 'development',
+  port: parseInt(process.env.PORT, 10) || 3000,
+  host: process.env.HOST || '0.0.0.0',
+
+  // Security defaults - ON by default
+  security: {
+    csrf: true,
+    xss: true,
+    cors: {
+      origin: '*',
+      methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'],
+      allowedHeaders: ['Content-Type', 'Authorization', 'X-Requested-With'],
+      credentials: true,
+      maxAge: 86400,
+    },
+    rateLimit: {
+      windowMs: 15 * 60 * 1000, // 15 minutes
+      max: 100,                  // 100 requests per window
+    },
+    headers: true,
+    hsts: true,
+    sanitize: true,
+  },
+
+  // Server defaults
+  server: {
+    maxBodySize: 10 * 1024 * 1024, // 10MB
+    timeout: 30000,                 // 30s
+    keepAlive: true,
+    compression: true,
+  },
+
+  // Logging
+  logging: {
+    requests: true,
+    level: 'info',
+    format: 'pretty',
+    file: null,
+  },
+
+  // Views
+  views: {
+    engine: 'volt',
+    dir: 'views',
+    cache: process.env.NODE_ENV === 'production',
+  },
+
+  // Database
+  database: {
+    driver: null,
+    host: 'localhost',
+    port: null,
+    name: null,
+    user: null,
+    password: null,
+    filename: null,
+    pool: { min: 2, max: 10 },
+  },
+
+  // Cache
+  cache: {
+    driver: 'memory',
+    ttl: 3600,
+    prefix: 'volt:',
+  },
+
+  // Mail
+  mail: {
+    driver: 'smtp',
+    host: null,
+    port: 587,
+    secure: false,
+    user: null,
+    password: null,
+    from: null,
+  },
+
+  // Session
+  session: {
+    secret: null,
+    name: 'volt.sid',
+    maxAge: 24 * 60 * 60 * 1000, // 24 hours
+    secure: false,
+    httpOnly: true,
+    sameSite: 'Lax',
+  },
+};
+
+class Config {
+  constructor(userConfig = {}) {
+    // Deep merge: defaults → config file → user config → env vars
+    this._config = this._deepMerge(DEFAULTS, this._loadConfigFile(), userConfig);
+    this._applyEnvOverrides();
+  }
+
+  /** Get config value using dot notation */
+  get(key, defaultValue = undefined) {
+    const keys = key.split('.');
+    let value = this._config;
+
+    for (const k of keys) {
+      if (value === undefined || value === null) return defaultValue;
+      value = value[k];
+    }
+
+    return value !== undefined ? value : defaultValue;
+  }
+
+  /** Set config value using dot notation */
+  set(key, value) {
+    const keys = key.split('.');
+    let target = this._config;
+
+    for (let i = 0; i < keys.length - 1; i++) {
+      if (!(keys[i] in target)) target[keys[i]] = {};
+      target = target[keys[i]];
+    }
+
+    target[keys[keys.length - 1]] = value;
+    return this;
+  }
+
+  /** Check if key exists */
+  has(key) {
+    return this.get(key) !== undefined;
+  }
+
+  /** Get all config */
+  all() {
+    return { ...this._config };
+  }
+
+  // ===== INTERNAL =====
+
+  _loadConfigFile() {
+    const configPaths = [
+      path.join(process.cwd(), 'volt.config.js'),
+      path.join(process.cwd(), 'volt.config.json'),
+      path.join(process.cwd(), '.voltrc'),
+      path.join(process.cwd(), '.voltrc.js'),
+    ];
+
+    for (const configPath of configPaths) {
+      try {
+        if (fs.existsSync(configPath)) {
+          return require(configPath);
+        }
+      } catch {
+        // Skip invalid config files
+      }
+    }
+
+    return {};
+  }
+
+  _applyEnvOverrides() {
+    // Map common ENV vars to config keys
+    const envMap = {
+      VOLT_PORT: 'port',
+      VOLT_HOST: 'host',
+      VOLT_ENV: 'env',
+      NODE_ENV: 'env',
+      DATABASE_URL: 'database.url',
+      DB_HOST: 'database.host',
+      DB_PORT: 'database.port',
+      DB_NAME: 'database.name',
+      DB_USER: 'database.user',
+      DB_PASSWORD: 'database.password',
+      MAIL_HOST: 'mail.host',
+      MAIL_PORT: 'mail.port',
+      MAIL_USER: 'mail.user',
+      MAIL_PASSWORD: 'mail.password',
+      MAIL_FROM: 'mail.from',
+      SESSION_SECRET: 'session.secret',
+      CACHE_DRIVER: 'cache.driver',
+    };
+
+    for (const [envKey, configKey] of Object.entries(envMap)) {
+      if (process.env[envKey] !== undefined) {
+        let value = process.env[envKey];
+        // Auto-convert numbers and booleans
+        if (value === 'true') value = true;
+        else if (value === 'false') value = false;
+        else if (/^\d+$/.test(value)) value = parseInt(value, 10);
+        this.set(configKey, value);
+      }
+    }
+  }
+
+  _deepMerge(target, ...sources) {
+    const result = { ...target };
+
+    for (const source of sources) {
+      if (!source || typeof source !== 'object') continue;
+
+      for (const key of Object.keys(source)) {
+        if (
+          source[key] &&
+          typeof source[key] === 'object' &&
+          !Array.isArray(source[key]) &&
+          result[key] &&
+          typeof result[key] === 'object' &&
+          !Array.isArray(result[key])
+        ) {
+          result[key] = this._deepMerge(result[key], source[key]);
+        } else {
+          result[key] = source[key];
+        }
+      }
+    }
+
+    return result;
+  }
+}
+
+module.exports = { Config };

package/src/core/middleware.js

@@ -0,0 +1,133 @@
+/**
+ * VoltJS Middleware Engine
+ * 
+ * Supports global middleware, path-specific middleware, and named middleware.
+ * All middleware follows (req, res, next?) pattern.
+ */
+
+'use strict';
+
+class Middleware {
+  constructor() {
+    this._global = [];
+    this._paths = new Map();
+    this._named = new Map();
+  }
+
+  /** Add global middleware */
+  addGlobal(fn) {
+    if (typeof fn !== 'function') {
+      throw new Error('Middleware must be a function');
+    }
+    this._global.push(fn);
+    return this;
+  }
+
+  /** Add path-specific middleware */
+  addPath(pathPattern, fns) {
+    const handlers = Array.isArray(fns) ? fns : [fns];
+    if (!this._paths.has(pathPattern)) {
+      this._paths.set(pathPattern, []);
+    }
+    this._paths.get(pathPattern).push(...handlers);
+    return this;
+  }
+
+  /** Register named middleware for reuse */
+  register(name, fn) {
+    this._named.set(name, fn);
+    return this;
+  }
+
+  /** Get named middleware */
+  get(name) {
+    return this._named.get(name);
+  }
+
+  /** Run global middleware chain */
+  async runGlobal(req, res) {
+    return this._runChain(this._global, req, res);
+  }
+
+  /** Run path-specific middleware */
+  async runPath(requestPath, req, res) {
+    const matchingMiddleware = [];
+
+    for (const [pathPattern, handlers] of this._paths) {
+      if (this._pathMatches(requestPath, pathPattern)) {
+        matchingMiddleware.push(...handlers);
+      }
+    }
+
+    if (matchingMiddleware.length === 0) return true;
+    return this._runChain(matchingMiddleware, req, res);
+  }
+
+  /** Execute middleware chain */
+  async _runChain(middlewares, req, res) {
+    for (const mw of middlewares) {
+      if (res.writableEnded) return false;
+
+      const result = await new Promise((resolve, reject) => {
+        try {
+          // Support both (req, res, next) and (req, res) patterns
+          if (mw.length >= 3) {
+            const ret = mw(req, res, (err) => {
+              if (err) reject(err);
+              else resolve(true);
+            });
+            // Handle async middleware
+            if (ret && typeof ret.then === 'function') {
+              ret.catch(reject);
+            }
+          } else {
+            const ret = mw(req, res);
+            if (ret && typeof ret.then === 'function') {
+              ret.then(r => resolve(r !== false)).catch(reject);
+            } else {
+              resolve(ret !== false);
+            }
+          }
+        } catch (err) {
+          reject(err);
+        }
+      });
+
+      if (result === false) return false;
+    }
+    return true;
+  }
+
+  /** Check if a request path matches a middleware path pattern */
+  _pathMatches(requestPath, pattern) {
+    if (pattern === '*' || pattern === '/') return true;
+
+    // Exact match
+    if (requestPath === pattern) return true;
+
+    // Prefix match (e.g., '/admin' matches '/admin/users')
+    if (requestPath.startsWith(pattern + '/')) return true;
+
+    // Wildcard pattern
+    if (pattern.includes('*')) {
+      const regex = new RegExp('^' + pattern.replace(/\*/g, '.*') + '$');
+      return regex.test(requestPath);
+    }
+
+    return false;
+  }
+
+  /** Create composed middleware from multiple middleware functions */
+  static compose(...middlewares) {
+    return async (req, res) => {
+      for (const mw of middlewares.flat()) {
+        if (res.writableEnded) return false;
+        const result = typeof mw === 'function' ? await mw(req, res) : undefined;
+        if (result === false) return false;
+      }
+      return true;
+    };
+  }
+}
+
+module.exports = { Middleware };

package/src/core/plugins.js

@@ -0,0 +1,88 @@
+/**
+ * VoltJS Plugin Manager
+ * 
+ * Extensible plugin system for adding functionality.
+ * 
+ * @example
+ * // Creating a plugin
+ * const myPlugin = {
+ *   name: 'my-plugin',
+ *   version: '1.0.0',
+ *   install(app, options) {
+ *     app.get('/my-route', (req, res) => res.json({ plugin: true }));
+ *     app.use((req, res) => { req.myPlugin = true; });
+ *   }
+ * };
+ * 
+ * app.use(myPlugin);
+ */
+
+'use strict';
+
+class PluginManager {
+  constructor(app) {
+    this._app = app;
+    this._plugins = new Map();
+    this._hooks = new Map();
+  }
+
+  /** Register a plugin */
+  register(plugin, options = {}) {
+    if (!plugin || !plugin.name) {
+      throw new Error('Plugin must have a name property');
+    }
+
+    if (this._plugins.has(plugin.name)) {
+      console.warn(`\x1b[33mWarning: Plugin "${plugin.name}" is already registered. Skipping.\x1b[0m`);
+      return this;
+    }
+
+    // Validate plugin
+    if (typeof plugin.install !== 'function') {
+      throw new Error(`Plugin "${plugin.name}" must have an install() method`);
+    }
+
+    // Install plugin
+    try {
+      plugin.install(this._app, options);
+      this._plugins.set(plugin.name, { plugin, options });
+      console.log(`\x1b[32m  ✓ Plugin loaded: ${plugin.name}${plugin.version ? ` v${plugin.version}` : ''}\x1b[0m`);
+    } catch (err) {
+      console.error(`\x1b[31m  ✗ Plugin "${plugin.name}" failed to install: ${err.message}\x1b[0m`);
+      throw err;
+    }
+
+    return this;
+  }
+
+  /** Check if a plugin is registered */
+  has(name) {
+    return this._plugins.has(name);
+  }
+
+  /** Get a registered plugin */
+  get(name) {
+    const entry = this._plugins.get(name);
+    return entry ? entry.plugin : null;
+  }
+
+  /** List all registered plugins */
+  list() {
+    return Array.from(this._plugins.entries()).map(([name, { plugin }]) => ({
+      name,
+      version: plugin.version || '0.0.0',
+    }));
+  }
+
+  /** Unregister a plugin */
+  unregister(name) {
+    const entry = this._plugins.get(name);
+    if (entry && typeof entry.plugin.uninstall === 'function') {
+      entry.plugin.uninstall(this._app);
+    }
+    this._plugins.delete(name);
+    return this;
+  }
+}
+
+module.exports = { PluginManager };

package/src/core/react-renderer.js

@@ -0,0 +1,244 @@
+/**
+ * VoltJS React Server-Side Renderer
+ * 
+ * Renders React components to HTML on the server using ReactDOMServer.
+ * Supports:
+ *   - renderToString (full SSR with hydration support)
+ *   - renderToStaticMarkup (static HTML, no React client overhead)
+ *   - Layout wrapping with <head>, styles, scripts
+ *   - Passing initial props/state to client for hydration
+ *   - Component registry for file-based component discovery
+ * 
+ * @example
+ * const { ReactRenderer } = require('./react-renderer');
+ * const renderer = new ReactRenderer();
+ * 
+ * // Register a component
+ * renderer.register('App', AppComponent);
+ * 
+ * // Render to full HTML page
+ * const html = renderer.renderPage('App', { tasks: [...] }, {
+ *   title: 'My App',
+ *   styles: ['/css/app.css'],
+ * });
+ */
+
+'use strict';
+
+const React = require('react');
+const ReactDOMServer = require('react-dom/server');
+
+class ReactRenderer {
+  constructor(options = {}) {
+    this._components = new Map();
+    this._layouts = new Map();
+    this._defaultLayout = options.layout || null;
+    this._staticMode = options.static || false;  // true = renderToStaticMarkup
+    this._doctype = options.doctype !== false;
+  }
+
+  /**
+   * Register a React component by name
+   * @param {string} name - Component name
+   * @param {React.Component|Function} component - React component
+   */
+  register(name, component) {
+    this._components.set(name, component);
+    return this;
+  }
+
+  /**
+   * Register a layout component
+   * @param {string} name - Layout name
+   * @param {React.Component|Function} layout - Layout component that accepts { children, ...props }
+   */
+  layout(name, layout) {
+    this._layouts.set(name, layout);
+    return this;
+  }
+
+  /**
+   * Set the default layout
+   * @param {string} name - Layout name
+   */
+  setDefaultLayout(name) {
+    this._defaultLayout = name;
+    return this;
+  }
+
+  /**
+   * Render a React element to HTML string
+   * @param {React.Element} element - React element to render
+   * @returns {string} HTML string
+   */
+  renderToString(element) {
+    if (this._staticMode) {
+      return ReactDOMServer.renderToStaticMarkup(element);
+    }
+    return ReactDOMServer.renderToString(element);
+  }
+
+  /**
+   * Render a registered component by name
+   * @param {string} name - Component name
+   * @param {object} props - Props to pass to the component
+   * @returns {string} HTML string
+   */
+  render(name, props = {}) {
+    const Component = this._components.get(name);
+    if (!Component) {
+      throw new Error(`React component "${name}" not registered. Use renderer.register('${name}', Component) first.`);
+    }
+    const element = React.createElement(Component, props);
+    return this.renderToString(element);
+  }
+
+  /**
+   * Render a component directly (not registered)
+   * @param {React.Component|Function} Component - React component
+   * @param {object} props - Props
+   * @returns {string} HTML string
+   */
+  renderComponent(Component, props = {}) {
+    const element = React.createElement(Component, props);
+    return this.renderToString(element);
+  }
+
+  /**
+   * Render a full HTML page with a React component as body
+   * @param {string|React.Component|Function} componentOrName - Component name or component itself
+   * @param {object} props - Props for the component
+   * @param {object} pageOptions - Page-level options
+   * @param {string} pageOptions.title - Page title
+   * @param {string[]} pageOptions.styles - CSS file paths
+   * @param {string[]} pageOptions.scripts - JS file paths
+   * @param {string} pageOptions.layout - Layout name to use
+   * @param {object} pageOptions.meta - Meta tags { name: content }
+   * @param {string} pageOptions.lang - HTML lang attribute
+   * @param {boolean} pageOptions.hydrate - Include hydration script + initial state
+   * @param {string} pageOptions.containerId - Root container ID (default: 'root')
+   * @param {string} pageOptions.inlineStyles - Inline CSS string
+   * @param {string} pageOptions.headHtml - Extra HTML to inject in <head>
+   * @returns {string} Full HTML document
+   */
+  renderPage(componentOrName, props = {}, pageOptions = {}) {
+    const {
+      title = 'VoltJS App',
+      styles = [],
+      scripts = [],
+      layout = this._defaultLayout,
+      meta = {},
+      lang = 'en',
+      hydrate = false,
+      containerId = 'root',
+      inlineStyles = '',
+      headHtml = '',
+    } = pageOptions;
+
+    // Resolve the component
+    let Component;
+    let componentName;
+    if (typeof componentOrName === 'string') {
+      Component = this._components.get(componentOrName);
+      componentName = componentOrName;
+      if (!Component) {
+        throw new Error(`React component "${componentOrName}" not registered.`);
+      }
+    } else {
+      Component = componentOrName;
+      componentName = Component.displayName || Component.name || 'Component';
+    }
+
+    // Create the React element
+    let element = React.createElement(Component, props);
+
+    // Wrap in layout if specified
+    if (layout) {
+      const Layout = this._layouts.get(layout);
+      if (Layout) {
+        element = React.createElement(Layout, { ...props, title }, element);
+      }
+    }
+
+    // Render to HTML
+    const bodyHtml = this.renderToString(element);
+
+    // Build meta tags
+    const metaTags = Object.entries(meta)
+      .map(([name, content]) => `    <meta name="${name}" content="${content}">`)
+      .join('\n');
+
+    // Build style links
+    const styleLinks = styles
+      .map(href => `    <link rel="stylesheet" href="${href}">`)
+      .join('\n');
+
+    // Build script tags
+    const scriptTags = scripts
+      .map(src => `    <script src="${src}"></script>`)
+      .join('\n');
+
+    // Build hydration script (passes initial props to client React)
+    let hydrationScript = '';
+    if (hydrate) {
+      const safeProps = JSON.stringify(props)
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/&/g, '\\u0026');
+      hydrationScript = `
+    <script>
+      window.__VOLT_INITIAL_STATE__ = ${safeProps};
+      window.__VOLT_COMPONENT__ = "${componentName}";
+    </script>`;
+    }
+
+    // Build the full document
+    const doc = `${this._doctype ? '<!DOCTYPE html>\n' : ''}<html lang="${lang}">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>${this._escapeHtml(title)}</title>
+${metaTags}${styleLinks}${inlineStyles ? `\n    <style>\n${inlineStyles}\n    </style>` : ''}${headHtml ? `\n${headHtml}` : ''}
+</head>
+<body>
+    <div id="${containerId}">${bodyHtml}</div>${hydrationScript}
+${scriptTags}
+</body>
+</html>`;
+
+    return doc;
+  }
+
+  /**
+   * Render a React element to a stream (for large pages)
+   * @param {React.Element} element - React element
+   * @returns {NodeJS.ReadableStream}
+   */
+  renderToStream(element) {
+    if (ReactDOMServer.renderToPipeableStream) {
+      // React 18+
+      return new Promise((resolve, reject) => {
+        const { pipe, abort } = ReactDOMServer.renderToPipeableStream(element, {
+          onShellReady() { resolve({ pipe, abort }); },
+          onError(err) { reject(err); },
+        });
+      });
+    }
+    // Fallback: renderToNodeStream (deprecated but available)
+    if (ReactDOMServer.renderToNodeStream) {
+      return ReactDOMServer.renderToNodeStream(element);
+    }
+    throw new Error('Streaming SSR not available in this React version.');
+  }
+
+  /** Escape HTML entities */
+  _escapeHtml(str) {
+    return String(str)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;');
+  }
+}
+
+module.exports = { ReactRenderer };