voltjs-framework 1.0.0

package/src/api/rest.js

@@ -0,0 +1,204 @@
+/**
+ * VoltJS REST API Builder
+ * 
+ * Rapid REST API scaffolding with automatic CRUD, resource routing,
+ * versioning, and response formatting.
+ * 
+ * @example
+ * const { RestAPI } = require('voltjs');
+ * 
+ * const api = new RestAPI(app, { prefix: '/api/v1' });
+ * 
+ * api.resource('users', {
+ *   async index(req, res) { res.json(await User.all()); },
+ *   async show(req, res) { res.json(await User.find(req.params.id)); },
+ *   async store(req, res) { res.json(await User.create(req.body), 201); },
+ *   async update(req, res) { res.json(await User.updateById(req.params.id, req.body)); },
+ *   async destroy(req, res) { await User.deleteById(req.params.id); res.noContent(); },
+ * });
+ */
+
+'use strict';
+
+class RestAPI {
+  constructor(app, options = {}) {
+    this.app = app;
+    this.prefix = options.prefix || '/api';
+    this.version = options.version || null;
+    this.middleware = options.middleware || [];
+    this.resources = new Map();
+
+    // Default response transformer
+    this.transformer = options.transformer || null;
+  }
+
+  /** Define a full REST resource */
+  resource(name, handlers, options = {}) {
+    const base = `${this.prefix}/${name}`;
+    const middleware = [...this.middleware, ...(options.middleware || [])];
+
+    const routes = {
+      index:   { method: 'get',    path: base,            handler: handlers.index },
+      store:   { method: 'post',   path: base,            handler: handlers.store || handlers.create },
+      show:    { method: 'get',    path: `${base}/:id`,   handler: handlers.show },
+      update:  { method: 'put',    path: `${base}/:id`,   handler: handlers.update },
+      patch:   { method: 'patch',  path: `${base}/:id`,   handler: handlers.patch || handlers.update },
+      destroy: { method: 'delete', path: `${base}/:id`,   handler: handlers.destroy || handlers.delete },
+    };
+
+    for (const [action, route] of Object.entries(routes)) {
+      if (route.handler) {
+        const only = options.only;
+        const except = options.except;
+        if (only && !only.includes(action)) continue;
+        if (except && except.includes(action)) continue;
+
+        this.app[route.method](route.path, ...middleware, this._wrap(route.handler));
+      }
+    }
+
+    // Custom actions
+    if (handlers.custom) {
+      for (const [method, path, handler] of handlers.custom) {
+        this.app[method](`${base}${path}`, ...middleware, this._wrap(handler));
+      }
+    }
+
+    this.resources.set(name, { base, routes });
+    return this;
+  }
+
+  /** Define a single route */
+  route(method, path, handler, ...middleware) {
+    const fullPath = `${this.prefix}${path}`;
+    this.app[method](fullPath, ...this.middleware, ...middleware, this._wrap(handler));
+    return this;
+  }
+
+  /** GET shorthand */
+  get(path, handler, ...mw) { return this.route('get', path, handler, ...mw); }
+  /** POST shorthand */
+  post(path, handler, ...mw) { return this.route('post', path, handler, ...mw); }
+  /** PUT shorthand */
+  put(path, handler, ...mw) { return this.route('put', path, handler, ...mw); }
+  /** PATCH shorthand */
+  patch(path, handler, ...mw) { return this.route('patch', path, handler, ...mw); }
+  /** DELETE shorthand */
+  delete(path, handler, ...mw) { return this.route('delete', path, handler, ...mw); }
+
+  /** Create an API group with shared prefix and middleware */
+  group(prefix, middleware, fn) {
+    if (typeof middleware === 'function') {
+      fn = middleware;
+      middleware = [];
+    }
+    const sub = new RestAPI(this.app, {
+      prefix: `${this.prefix}${prefix}`,
+      middleware: [...this.middleware, ...middleware],
+      transformer: this.transformer,
+    });
+    fn(sub);
+    return this;
+  }
+
+  /** API versioning */
+  version(v, fn) {
+    return this.group(`/v${v}`, fn);
+  }
+
+  /** Standard success response */
+  static success(res, data, statusCode = 200, meta = {}) {
+    const response = {
+      success: true,
+      data,
+      ...(Object.keys(meta).length > 0 ? { meta } : {}),
+    };
+    res.json(response, statusCode);
+  }
+
+  /** Standard error response */
+  static error(res, message, statusCode = 400, errors = null) {
+    const response = {
+      success: false,
+      error: { message, code: statusCode },
+      ...(errors ? { errors } : {}),
+    };
+    res.json(response, statusCode);
+  }
+
+  /** Paginated response */
+  static paginated(res, data, meta) {
+    res.json({
+      success: true,
+      data,
+      meta: {
+        page: meta.page,
+        perPage: meta.perPage,
+        total: meta.total,
+        totalPages: meta.totalPages,
+        hasNext: meta.hasNext,
+        hasPrev: meta.hasPrev,
+      },
+    });
+  }
+
+  /** List all registered API routes */
+  listRoutes() {
+    const routes = [];
+    for (const [name, resource] of this.resources) {
+      for (const [action, route] of Object.entries(resource.routes)) {
+        if (route.handler) {
+          routes.push({
+            resource: name,
+            action,
+            method: route.method.toUpperCase(),
+            path: route.path,
+          });
+        }
+      }
+    }
+    return routes;
+  }
+
+  // ===== INTERNAL =====
+
+  _wrap(handler) {
+    return async (req, res) => {
+      try {
+        const result = await handler(req, res);
+        // Auto-send if handler returns a value but didn't respond
+        if (result !== undefined && !res.writableEnded) {
+          if (this.transformer) {
+            res.json(this.transformer(result));
+          } else {
+            res.json(result);
+          }
+        }
+      } catch (error) {
+        if (!res.writableEnded) {
+          const status = error.statusCode || error.status || 500;
+          RestAPI.error(res, error.message || 'Internal Server Error', status);
+        }
+      }
+    };
+  }
+}
+
+/** API Error helper */
+class ApiError extends Error {
+  constructor(message, statusCode = 400) {
+    super(message);
+    this.statusCode = statusCode;
+    this.name = 'ApiError';
+  }
+
+  static badRequest(msg = 'Bad Request') { return new ApiError(msg, 400); }
+  static unauthorized(msg = 'Unauthorized') { return new ApiError(msg, 401); }
+  static forbidden(msg = 'Forbidden') { return new ApiError(msg, 403); }
+  static notFound(msg = 'Not Found') { return new ApiError(msg, 404); }
+  static conflict(msg = 'Conflict') { return new ApiError(msg, 409); }
+  static validation(msg = 'Validation Failed') { return new ApiError(msg, 422); }
+  static internal(msg = 'Internal Server Error') { return new ApiError(msg, 500); }
+}
+
+module.exports = { RestAPI, ApiError };

package/src/api/websocket.js

@@ -0,0 +1,285 @@
+/**
+ * VoltJS WebSocket Server
+ * 
+ * Real-time WebSocket server with rooms, broadcasting, authentication,
+ * and automatic heartbeat.
+ * 
+ * @example
+ * const { WebSocketServer } = require('voltjs');
+ * 
+ * const wss = new WebSocketServer(app, { path: '/ws' });
+ * 
+ * wss.on('connection', (client) => {
+ *   client.join('lobby');
+ *   client.on('chat', (data) => {
+ *     wss.to('lobby').emit('chat', { user: client.id, ...data });
+ *   });
+ * });
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const { EventEmitter } = require('events');
+
+class WebSocketServer extends EventEmitter {
+  constructor(app, options = {}) {
+    super();
+    this.path = options.path || '/ws';
+    this.clients = new Map();
+    this.rooms = new Map();
+    this.heartbeatInterval = options.heartbeat || 30000;
+    this.authHandler = options.auth || null;
+    this._wss = null;
+
+    if (app && app._server) {
+      this._attachToServer(app._server);
+    } else if (app) {
+      // Defer attachment until server starts
+      const originalListen = app.listen?.bind(app);
+      if (originalListen) {
+        app.listen = (...args) => {
+          const server = originalListen(...args);
+          this._attachToServer(server);
+          return server;
+        };
+      }
+    }
+  }
+
+  _attachToServer(server) {
+    try {
+      const { WebSocketServer: WSS } = require('ws');
+      this._wss = new WSS({ server, path: this.path });
+
+      this._wss.on('connection', (ws, req) => this._onConnection(ws, req));
+
+      // Heartbeat timer
+      this._heartbeatTimer = setInterval(() => this._heartbeat(), this.heartbeatInterval);
+      if (this._heartbeatTimer.unref) this._heartbeatTimer.unref();
+    } catch (e) {
+      console.warn('[Volt] WebSocket: "ws" package not installed. Run: npm install ws');
+    }
+  }
+
+  async _onConnection(ws, req) {
+    const client = new WebSocketClient(ws, req, this);
+
+    // Authentication
+    if (this.authHandler) {
+      try {
+        const authResult = await this.authHandler(req, client);
+        if (authResult === false) {
+          ws.close(4001, 'Unauthorized');
+          return;
+        }
+        if (typeof authResult === 'object') {
+          client.user = authResult;
+        }
+      } catch (err) {
+        ws.close(4001, 'Auth failed');
+        return;
+      }
+    }
+
+    this.clients.set(client.id, client);
+
+    // Message handling
+    ws.on('message', (raw) => {
+      try {
+        const message = JSON.parse(raw.toString());
+        const event = message.event || 'message';
+        const data = message.data || message;
+        
+        client.emit(event, data);
+        this.emit(event, data, client);
+      } catch {
+        client.emit('message', raw.toString());
+      }
+    });
+
+    ws.on('close', () => {
+      // Leave all rooms
+      for (const [roomName, members] of this.rooms) {
+        members.delete(client.id);
+        if (members.size === 0) this.rooms.delete(roomName);
+      }
+      this.clients.delete(client.id);
+      this.emit('disconnect', client);
+    });
+
+    ws.on('error', (err) => {
+      this.emit('error', err, client);
+    });
+
+    ws.isAlive = true;
+    ws.on('pong', () => { ws.isAlive = true; });
+
+    this.emit('connection', client);
+  }
+
+  /** Broadcast to all connected clients */
+  broadcast(event, data, exclude = null) {
+    const payload = JSON.stringify({ event, data });
+    for (const [id, client] of this.clients) {
+      if (exclude && (exclude === id || exclude === client)) continue;
+      client._send(payload);
+    }
+  }
+
+  /** Send to a specific room */
+  to(room) {
+    return {
+      emit: (event, data) => {
+        const members = this.rooms.get(room);
+        if (!members) return;
+        const payload = JSON.stringify({ event, data });
+        for (const clientId of members) {
+          const client = this.clients.get(clientId);
+          if (client) client._send(payload);
+        }
+      },
+      clients: () => {
+        const members = this.rooms.get(room);
+        if (!members) return [];
+        return [...members].map(id => this.clients.get(id)).filter(Boolean);
+      },
+      count: () => {
+        return this.rooms.get(room)?.size || 0;
+      },
+    };
+  }
+
+  /** Get a client by ID */
+  client(id) {
+    return this.clients.get(id);
+  }
+
+  /** Get all connected client IDs */
+  get clientIds() {
+    return [...this.clients.keys()];
+  }
+
+  /** Get connected client count */
+  get clientCount() {
+    return this.clients.size;
+  }
+
+  /** Get all room names */
+  get roomNames() {
+    return [...this.rooms.keys()];
+  }
+
+  /** Require authentication */
+  requireAuth(handler) {
+    this.authHandler = handler;
+    return this;
+  }
+
+  /** Close the WebSocket server */
+  close() {
+    if (this._heartbeatTimer) clearInterval(this._heartbeatTimer);
+    if (this._wss) this._wss.close();
+    this.clients.clear();
+    this.rooms.clear();
+  }
+
+  _heartbeat() {
+    if (!this._wss) return;
+    for (const [id, client] of this.clients) {
+      if (!client._ws.isAlive) {
+        client._ws.terminate();
+        this.clients.delete(id);
+        continue;
+      }
+      client._ws.isAlive = false;
+      client._ws.ping();
+    }
+  }
+}
+
+class WebSocketClient extends EventEmitter {
+  constructor(ws, req, server) {
+    super();
+    this._ws = ws;
+    this._server = server;
+    this.id = crypto.randomBytes(8).toString('hex');
+    this.ip = req.headers['x-forwarded-for'] || req.socket?.remoteAddress;
+    this.user = null;
+    this.data = {}; // Custom per-client data
+    
+    // Parse URL params
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    this.query = Object.fromEntries(url.searchParams);
+  }
+
+  /** Send event+data to this client */
+  emit(event, data) {
+    if (event === 'newListener' || event === 'removeListener') {
+      return super.emit(event, data);
+    }
+
+    // If there are listeners, fire them (internal event)
+    if (this.listenerCount(event) > 0) {
+      super.emit(event, data);
+      return this;
+    }
+
+    // Otherwise, send to the WebSocket
+    this._send(JSON.stringify({ event, data }));
+    return this;
+  }
+
+  /** Send raw data */
+  send(data) {
+    this._send(typeof data === 'string' ? data : JSON.stringify(data));
+    return this;
+  }
+
+  /** Join a room */
+  join(room) {
+    if (!this._server.rooms.has(room)) {
+      this._server.rooms.set(room, new Set());
+    }
+    this._server.rooms.get(room).add(this.id);
+    return this;
+  }
+
+  /** Leave a room */
+  leave(room) {
+    const members = this._server.rooms.get(room);
+    if (members) {
+      members.delete(this.id);
+      if (members.size === 0) this._server.rooms.delete(room);
+    }
+    return this;
+  }
+
+  /** Get rooms this client is in */
+  get rooms() {
+    const rooms = [];
+    for (const [name, members] of this._server.rooms) {
+      if (members.has(this.id)) rooms.push(name);
+    }
+    return rooms;
+  }
+
+  /** Broadcast to all except this client */
+  broadcast(event, data) {
+    this._server.broadcast(event, data, this.id);
+    return this;
+  }
+
+  /** Disconnect this client */
+  disconnect(code = 1000, reason = '') {
+    this._ws.close(code, reason);
+  }
+
+  _send(payload) {
+    if (this._ws.readyState === 1) { // OPEN
+      this._ws.send(payload);
+    }
+  }
+}
+
+module.exports = { WebSocketServer, WebSocketClient };

package/src/cli/build.js

@@ -0,0 +1,111 @@
+/**
+ * VoltJS CLI — `volt build`
+ * Prepares the application for production.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const c = {
+  reset: '\x1b[0m', bold: '\x1b[1m', dim: '\x1b[2m',
+  red: '\x1b[31m', green: '\x1b[32m', yellow: '\x1b[33m', cyan: '\x1b[36m',
+};
+
+module.exports = function build(args) {
+  const cwd = process.cwd();
+  const distDir = path.join(cwd, 'dist');
+
+  console.log(`${c.cyan}${c.bold}⚡ VoltJS Build${c.reset}\n`);
+
+  // Clean dist
+  if (fs.existsSync(distDir)) {
+    fs.rmSync(distDir, { recursive: true, force: true });
+  }
+  fs.mkdirSync(distDir, { recursive: true });
+
+  // Copy relevant files to dist
+  const copyDirs = ['pages', 'api', 'views', 'components', 'models', 'middleware', 'config', 'public', 'database'];
+  const copyFiles = ['app.js', 'index.js', 'server.js', 'volt.config.js', 'package.json'];
+
+  let fileCount = 0;
+
+  for (const dir of copyDirs) {
+    const src = path.join(cwd, dir);
+    if (fs.existsSync(src)) {
+      copyRecursive(src, path.join(distDir, dir));
+      console.log(`  ${c.green}✓${c.reset} ${dir}/`);
+      fileCount++;
+    }
+  }
+
+  for (const file of copyFiles) {
+    const src = path.join(cwd, file);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, path.join(distDir, file));
+      console.log(`  ${c.green}✓${c.reset} ${file}`);
+      fileCount++;
+    }
+  }
+
+  // Create production-ready package.json
+  const pkgPath = path.join(cwd, 'package.json');
+  if (fs.existsSync(pkgPath)) {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+    const prodPkg = {
+      name: pkg.name,
+      version: pkg.version,
+      private: true,
+      scripts: { start: 'node app.js' },
+      dependencies: pkg.dependencies || {},
+    };
+    fs.writeFileSync(path.join(distDir, 'package.json'), JSON.stringify(prodPkg, null, 2));
+  }
+
+  // Minify CSS files
+  const cssDir = path.join(distDir, 'public', 'css');
+  if (fs.existsSync(cssDir)) {
+    const cssFiles = fs.readdirSync(cssDir).filter(f => f.endsWith('.css'));
+    for (const file of cssFiles) {
+      const content = fs.readFileSync(path.join(cssDir, file), 'utf-8');
+      const minified = content
+        .replace(/\/\*[\s\S]*?\*\//g, '') // Remove comments
+        .replace(/\s+/g, ' ')             // Collapse whitespace
+        .replace(/\s*([{}:;,])\s*/g, '$1') // Remove spaces around symbols
+        .trim();
+      fs.writeFileSync(path.join(cssDir, file), minified);
+    }
+    console.log(`  ${c.green}✓${c.reset} CSS minified`);
+  }
+
+  // Create necessary dirs
+  for (const dir of ['logs', 'storage']) {
+    fs.mkdirSync(path.join(distDir, dir), { recursive: true });
+  }
+
+  console.log(`
+${c.green}${c.bold}✓ Build complete!${c.reset} ${c.dim}(${fileCount} items)${c.reset}
+
+${c.bold}To deploy:${c.reset}
+  ${c.cyan}cd dist${c.reset}
+  ${c.cyan}npm install --production${c.reset}
+  ${c.cyan}npm start${c.reset}
+`);
+};
+
+function copyRecursive(src, dest) {
+  if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
+  
+  const entries = fs.readdirSync(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    
+    if (entry.isDirectory()) {
+      copyRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}