voltjs-framework 1.0.0

package/src/utils/http.js

@@ -0,0 +1,461 @@
+/**
+ * VoltJS HttpClient
+ * 
+ * Zero-dependency HTTP client for external API calls.
+ * 
+ * @example
+ * const { HttpClient } = require('voltjs');
+ * 
+ * const api = new HttpClient({ baseURL: 'https://api.example.com' });
+ * api.setHeader('Authorization', 'Bearer token');
+ * 
+ * const users = await api.get('/users');
+ * const created = await api.post('/users', { name: 'John' });
+ * 
+ * // Quick usage
+ * const data = await HttpClient.get('https://api.example.com/data');
+ */
+
+'use strict';
+
+const https = require('https');
+const http = require('http');
+const { URL } = require('url');
+const zlib = require('zlib');
+
+class HttpClient {
+  constructor(options = {}) {
+    this.baseURL = options.baseURL || '';
+    this.headers = {
+      'Content-Type': 'application/json',
+      'Accept': 'application/json',
+      'User-Agent': 'VoltJS/1.0',
+      ...options.headers,
+    };
+    this.timeout = options.timeout || 30000;
+    this.retries = options.retries || 0;
+    this.retryDelay = options.retryDelay || 1000;
+
+    this._interceptors = { request: [], response: [] };
+  }
+
+  /** Set a default header */
+  setHeader(key, value) {
+    this.headers[key] = value;
+    return this;
+  }
+
+  /** Set Bearer token */
+  setBearerToken(token) {
+    this.headers.Authorization = `Bearer ${token}`;
+    return this;
+  }
+
+  /** Set Basic auth */
+  setBasicAuth(username, password) {
+    const cred = Buffer.from(`${username}:${password}`).toString('base64');
+    this.headers.Authorization = `Basic ${cred}`;
+    return this;
+  }
+
+  /** Add request interceptor */
+  onRequest(fn) { this._interceptors.request.push(fn); return this; }
+
+  /** Add response interceptor */
+  onResponse(fn) { this._interceptors.response.push(fn); return this; }
+
+  // HTTP Methods
+  async get(url, options = {}) { return this.request('GET', url, null, options); }
+  async post(url, data, options = {}) { return this.request('POST', url, data, options); }
+  async put(url, data, options = {}) { return this.request('PUT', url, data, options); }
+  async patch(url, data, options = {}) { return this.request('PATCH', url, data, options); }
+  async delete(url, options = {}) { return this.request('DELETE', url, null, options); }
+  async head(url, options = {}) { return this.request('HEAD', url, null, options); }
+
+  /** Core request method */
+  async request(method, url, data = null, options = {}) {
+    const fullURL = url.startsWith('http') ? url : this.baseURL + url;
+    const parsed = new URL(fullURL);
+
+    // Query params
+    if (options.params) {
+      for (const [key, value] of Object.entries(options.params)) {
+        parsed.searchParams.set(key, value);
+      }
+    }
+
+    let reqConfig = {
+      method,
+      url: parsed.toString(),
+      headers: { ...this.headers, ...options.headers },
+      data,
+    };
+
+    // Run request interceptors
+    for (const fn of this._interceptors.request) {
+      reqConfig = await fn(reqConfig) || reqConfig;
+    }
+
+    // Serialize body
+    let body = null;
+    if (reqConfig.data !== null && reqConfig.data !== undefined) {
+      if (typeof reqConfig.data === 'string' || Buffer.isBuffer(reqConfig.data)) {
+        body = reqConfig.data;
+      } else if (reqConfig.data instanceof URLSearchParams) {
+        body = reqConfig.data.toString();
+        reqConfig.headers['Content-Type'] = 'application/x-www-form-urlencoded';
+      } else {
+        body = JSON.stringify(reqConfig.data);
+      }
+    }
+
+    // Retry logic
+    let lastError;
+    const maxAttempts = (options.retries ?? this.retries) + 1;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        const response = await this._doRequest(parsed, method, reqConfig.headers, body, options);
+
+        // Run response interceptors
+        let result = response;
+        for (const fn of this._interceptors.response) {
+          result = await fn(result) || result;
+        }
+
+        return result;
+      } catch (err) {
+        lastError = err;
+        if (attempt < maxAttempts) {
+          await new Promise(r => setTimeout(r, this.retryDelay * attempt));
+        }
+      }
+    }
+
+    throw lastError;
+  }
+
+  /** Download a file */
+  async download(url, filePath) {
+    const fs = require('fs');
+    const path = require('path');
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    return new Promise((resolve, reject) => {
+      const fullURL = url.startsWith('http') ? url : this.baseURL + url;
+      const parsed = new URL(fullURL);
+      const transport = parsed.protocol === 'https:' ? https : http;
+
+      transport.get(fullURL, { headers: this.headers }, (response) => {
+        if (response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+          // Follow redirects
+          return this.download(response.headers.location, filePath).then(resolve).catch(reject);
+        }
+
+        const file = fs.createWriteStream(filePath);
+        response.pipe(file);
+        file.on('finish', () => {
+          file.close();
+          resolve({ path: filePath, size: fs.statSync(filePath).size });
+        });
+      }).on('error', reject);
+    });
+  }
+
+  // ===== STATIC SHORTCUTS =====
+
+  static async get(url, options = {}) { return new HttpClient(options).get(url, options); }
+  static async post(url, data, options = {}) { return new HttpClient(options).post(url, data, options); }
+  static async put(url, data, options = {}) { return new HttpClient(options).put(url, data, options); }
+  static async patch(url, data, options = {}) { return new HttpClient(options).patch(url, data, options); }
+  static async delete(url, options = {}) { return new HttpClient(options).delete(url, options); }
+
+  // ===== SWR: STALE-WHILE-REVALIDATE =====
+
+  /**
+   * SWR-like data fetching with cache + background revalidation
+   * 
+   * @example
+   * const fetcher = HttpClient.swr({ ttl: 30, revalidate: 60 });
+   * const data = await fetcher.get('/api/users'); // Cached + background refresh
+   * fetcher.invalidate('/api/users');
+   */
+  static swr(options = {}) {
+    const client = new HttpClient(options);
+    const cache = new Map();
+    const ttl = (options.ttl || 60) * 1000; // stale after N seconds
+    const revalidateTTL = (options.revalidate || 300) * 1000; // refetch after N seconds
+    const dedupeInterval = (options.dedupe || 2) * 1000;
+    const inflight = new Map();
+
+    const getCacheKey = (method, url, params) =>
+      `${method}:${url}:${JSON.stringify(params || {})}`;
+
+    const fetcher = {
+      async get(url, params = {}) {
+        const key = getCacheKey('GET', url, params);
+        const now = Date.now();
+        const entry = cache.get(key);
+
+        // Return cached data if fresh
+        if (entry && (now - entry.timestamp) < ttl) {
+          return entry.data;
+        }
+
+        // Return stale data + revalidate in background
+        if (entry && (now - entry.timestamp) < revalidateTTL) {
+          // Dedupe: don't fire multiple revalidations
+          if (!inflight.has(key)) {
+            const revalidate = client.get(url, { params }).then(res => {
+              cache.set(key, { data: res, timestamp: Date.now() });
+              return res;
+            }).finally(() => {
+              setTimeout(() => inflight.delete(key), dedupeInterval);
+            });
+            inflight.set(key, revalidate);
+          }
+          return entry.data; // Return stale immediately
+        }
+
+        // No cache or expired: fetch fresh
+        if (inflight.has(key)) return inflight.get(key); // Dedupe
+
+        const promise = client.get(url, { params }).then(res => {
+          cache.set(key, { data: res, timestamp: Date.now() });
+          return res;
+        }).finally(() => {
+          setTimeout(() => inflight.delete(key), dedupeInterval);
+        });
+
+        inflight.set(key, promise);
+        return promise;
+      },
+
+      /** Invalidate cache for a URL */
+      invalidate(url) {
+        for (const key of cache.keys()) {
+          if (key.includes(url)) cache.delete(key);
+        }
+      },
+
+      /** Invalidate all cache */
+      invalidateAll() { cache.clear(); },
+
+      /** Mutate cached data directly (optimistic update) */
+      mutate(url, data) {
+        for (const [key, entry] of cache.entries()) {
+          if (key.includes(url)) {
+            entry.data = typeof data === 'function' ? data(entry.data) : data;
+            entry.timestamp = Date.now();
+          }
+        }
+      },
+
+      /** Prefetch data into cache */
+      async prefetch(url, params = {}) {
+        const key = getCacheKey('GET', url, params);
+        const res = await client.get(url, { params });
+        cache.set(key, { data: res, timestamp: Date.now() });
+        return res;
+      },
+
+      /** Get cache stats */
+      stats() {
+        return { size: cache.size, inflight: inflight.size };
+      },
+    };
+
+    return fetcher;
+  }
+
+  // ===== ABORT / CANCEL =====
+
+  /**
+   * Create an abortable request
+   * 
+   * @example
+   * const { promise, abort } = HttpClient.abortable('https://api.example.com/data');
+   * setTimeout(() => abort(), 5000); // Cancel after 5s
+   * const data = await promise;
+   */
+  static abortable(url, options = {}) {
+    let aborted = false;
+    let rejectFn;
+
+    const promise = new Promise((resolve, reject) => {
+      rejectFn = reject;
+      if (aborted) return reject(new Error('Request aborted'));
+
+      const client = new HttpClient(options);
+      client.get(url, { ...options, allowError: true }).then(resolve).catch(reject);
+    });
+
+    return {
+      promise,
+      abort() {
+        aborted = true;
+        if (rejectFn) rejectFn(new Error('Request aborted'));
+      },
+    };
+  }
+
+  // ===== POLLING =====
+
+  /**
+   * Poll a URL at intervals
+   * 
+   * @example
+   * const poller = HttpClient.poll('https://api.example.com/status', {
+   *   interval: 5000,
+   *   onData: (data) => console.log(data),
+   *   until: (data) => data.status === 'complete',
+   * });
+   * 
+   * poller.stop(); // Stop polling
+   */
+  static poll(url, options = {}) {
+    const {
+      interval = 5000,
+      onData,
+      onError,
+      until,
+      maxAttempts = Infinity,
+      immediate = true,
+    } = options;
+
+    const client = new HttpClient(options);
+    let timer = null;
+    let attempts = 0;
+    let stopped = false;
+
+    const tick = async () => {
+      if (stopped) return;
+      attempts++;
+      try {
+        const res = await client.get(url);
+        if (onData) onData(res.data || res, attempts);
+        if (until && until(res.data || res)) {
+          stopped = true;
+          return;
+        }
+      } catch (err) {
+        if (onError) onError(err, attempts);
+      }
+      if (!stopped && attempts < maxAttempts) {
+        timer = setTimeout(tick, interval);
+      }
+    };
+
+    if (immediate) tick();
+    else timer = setTimeout(tick, interval);
+
+    return {
+      stop() { stopped = true; if (timer) clearTimeout(timer); },
+      get attempts() { return attempts; },
+      get running() { return !stopped; },
+    };
+  }
+
+  // ===== CONCURRENT REQUESTS =====
+
+  /**
+   * Execute multiple requests in parallel
+   * 
+   * @example
+   * const [users, posts] = await HttpClient.all([
+   *   HttpClient.get('/api/users'),
+   *   HttpClient.get('/api/posts'),
+   * ]);
+   */
+  static all(requests) {
+    return Promise.all(requests);
+  }
+
+  /** Like Promise.allSettled — returns all results even if some fail */
+  static allSettled(requests) {
+    return Promise.allSettled(requests);
+  }
+
+  /** Race: return first to resolve */
+  static race(requests) {
+    return Promise.race(requests);
+  }
+
+  // ===== INTERNAL =====
+
+  _doRequest(parsed, method, headers, body, options) {
+    return new Promise((resolve, reject) => {
+      const transport = parsed.protocol === 'https:' ? https : http;
+
+      const reqOptions = {
+        hostname: parsed.hostname,
+        port: parsed.port || (parsed.protocol === 'https:' ? 443 : 80),
+        path: parsed.pathname + parsed.search,
+        method,
+        headers: { ...headers },
+        timeout: options.timeout || this.timeout,
+      };
+
+      if (body) {
+        reqOptions.headers['Content-Length'] = Buffer.byteLength(body);
+      }
+
+      // Accept gzip
+      reqOptions.headers['Accept-Encoding'] = 'gzip, deflate';
+
+      const req = transport.request(reqOptions, (res) => {
+        const chunks = [];
+
+        // Handle gzip
+        let stream = res;
+        const encoding = res.headers['content-encoding'];
+        if (encoding === 'gzip') {
+          stream = res.pipe(zlib.createGunzip());
+        } else if (encoding === 'deflate') {
+          stream = res.pipe(zlib.createInflate());
+        }
+
+        stream.on('data', chunk => chunks.push(chunk));
+        stream.on('end', () => {
+          const rawBody = Buffer.concat(chunks).toString('utf-8');
+          
+          let parsedBody = rawBody;
+          const contentType = res.headers['content-type'] || '';
+          if (contentType.includes('application/json')) {
+            try { parsedBody = JSON.parse(rawBody); } catch { }
+          }
+
+          const response = {
+            status: res.statusCode,
+            statusText: res.statusMessage,
+            headers: res.headers,
+            data: parsedBody,
+            raw: rawBody,
+            ok: res.statusCode >= 200 && res.statusCode < 300,
+          };
+
+          if (!response.ok && !options.allowError) {
+            const error = new Error(`HTTP ${res.statusCode}: ${res.statusMessage}`);
+            error.response = response;
+            reject(error);
+          } else {
+            resolve(response);
+          }
+        });
+        stream.on('error', reject);
+      });
+
+      req.on('error', reject);
+      req.on('timeout', () => {
+        req.destroy();
+        reject(new Error(`Request timed out after ${reqOptions.timeout}ms`));
+      });
+
+      if (body) req.write(body);
+      req.end();
+    });
+  }
+}
+
+module.exports = { HttpClient };

package/src/utils/logger.js

@@ -0,0 +1,186 @@
+/**
+ * VoltJS Logger
+ * 
+ * Structured, colorful logging with levels, file output, and request logging.
+ * 
+ * @example
+ * const { Logger } = require('voltjs');
+ * 
+ * const log = new Logger({ level: 'debug', file: 'logs/app.log' });
+ * log.info('Server started', { port: 3000 });
+ * log.error('Failed', { error: err.message });
+ * 
+ * // Request logging middleware
+ * app.use(Logger.requestLogger());
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const LEVELS = { trace: 0, debug: 1, info: 2, warn: 3, error: 4, fatal: 5, silent: 6 };
+
+const COLORS = {
+  trace: '\x1b[90m',   // gray
+  debug: '\x1b[36m',   // cyan
+  info:  '\x1b[32m',   // green
+  warn:  '\x1b[33m',   // yellow
+  error: '\x1b[31m',   // red
+  fatal: '\x1b[35m',   // magenta
+  reset: '\x1b[0m',
+  dim:   '\x1b[2m',
+  bold:  '\x1b[1m',
+};
+
+const ICONS = { trace: '·', debug: '◆', info: '✓', warn: '⚠', error: '✗', fatal: '☠' };
+
+class Logger {
+  constructor(options = {}) {
+    this.level = options.level || process.env.LOG_LEVEL || 'info';
+    this.colorize = options.colorize !== false;
+    this.timestamp = options.timestamp !== false;
+    this.file = options.file || null;
+    this.maxFileSize = options.maxFileSize || 10 * 1024 * 1024; // 10MB
+    this.prefix = options.prefix || '';
+
+    if (this.file) {
+      const dir = path.dirname(this.file);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  trace(message, meta) { this._log('trace', message, meta); }
+  debug(message, meta) { this._log('debug', message, meta); }
+  info(message, meta)  { this._log('info', message, meta); }
+  warn(message, meta)  { this._log('warn', message, meta); }
+  error(message, meta) { this._log('error', message, meta); }
+  fatal(message, meta) { this._log('fatal', message, meta); }
+
+  /** Create a child logger with prefix */
+  child(prefix) {
+    return new Logger({
+      level: this.level,
+      colorize: this.colorize,
+      timestamp: this.timestamp,
+      file: this.file,
+      prefix: this.prefix ? `${this.prefix}:${prefix}` : prefix,
+    });
+  }
+
+  /** Time an operation */
+  time(label) {
+    const start = performance.now();
+    return {
+      end: (meta) => {
+        const duration = (performance.now() - start).toFixed(2);
+        this.debug(`${label} completed in ${duration}ms`, meta);
+      },
+    };
+  }
+
+  /** Create table from data */
+  table(data) {
+    if (!Array.isArray(data) || data.length === 0) return;
+    console.table(data);
+  }
+
+  /** Request logging middleware */
+  static requestLogger(options = {}) {
+    const logger = new Logger(options);
+
+    return (req, res) => {
+      const start = Date.now();
+      
+      const originalEnd = res.end.bind(res);
+      res.end = (...args) => {
+        const duration = Date.now() - start;
+        const status = res.statusCode;
+        const color = status >= 500 ? 'error' : status >= 400 ? 'warn' : 'info';
+        
+        logger._log(color, `${req.method} ${req.url} ${status} ${duration}ms`, {
+          method: req.method,
+          url: req.url,
+          status,
+          duration: `${duration}ms`,
+          ip: req.headers['x-forwarded-for'] || req.socket?.remoteAddress,
+          userAgent: req.headers['user-agent'],
+        });
+
+        originalEnd(...args);
+      };
+    };
+  }
+
+  /** Log to JSON format (for production/log aggregators) */
+  static json(options = {}) {
+    const logger = new Logger({ ...options, colorize: false });
+    logger._formatJSON = true;
+    return logger;
+  }
+
+  // ===== INTERNAL =====
+
+  _log(level, message, meta) {
+    if (LEVELS[level] < LEVELS[this.level]) return;
+
+    const ts = this.timestamp ? new Date().toISOString() : '';
+    const prefix = this.prefix ? `[${this.prefix}]` : '';
+
+    // JSON format
+    if (this._formatJSON) {
+      const entry = {
+        timestamp: ts,
+        level,
+        message,
+        ...(this.prefix ? { context: this.prefix } : {}),
+        ...(meta || {}),
+      };
+      const line = JSON.stringify(entry);
+      process.stdout.write(line + '\n');
+      if (this.file) this._writeFile(line);
+      return;
+    }
+
+    // Pretty format
+    const metaStr = meta ? ' ' + JSON.stringify(meta) : '';
+    
+    if (this.colorize) {
+      const c = COLORS[level] || '';
+      const icon = ICONS[level] || '';
+      const tsStr = ts ? `${COLORS.dim}${ts}${COLORS.reset} ` : '';
+      const prefixStr = prefix ? `${COLORS.dim}${prefix}${COLORS.reset} ` : '';
+      const levelStr = `${c}${COLORS.bold}${level.toUpperCase().padEnd(5)}${COLORS.reset}`;
+      const metaColored = meta ? ` ${COLORS.dim}${JSON.stringify(meta)}${COLORS.reset}` : '';
+      
+      process.stdout.write(`${tsStr}${c}${icon}${COLORS.reset} ${levelStr} ${prefixStr}${message}${metaColored}\n`);
+    } else {
+      const line = `${ts} ${level.toUpperCase().padEnd(5)} ${prefix} ${message}${metaStr}`.trim();
+      process.stdout.write(line + '\n');
+    }
+
+    // File output
+    if (this.file) {
+      const fileLine = `${ts} ${level.toUpperCase().padEnd(5)} ${prefix} ${message}${metaStr}`.trim();
+      this._writeFile(fileLine);
+    }
+  }
+
+  _writeFile(line) {
+    try {
+      // Rotate if too large
+      if (fs.existsSync(this.file)) {
+        const stat = fs.statSync(this.file);
+        if (stat.size > this.maxFileSize) {
+          const rotated = this.file + '.' + Date.now();
+          fs.renameSync(this.file, rotated);
+        }
+      }
+      fs.appendFileSync(this.file, line + '\n');
+    } catch (e) {
+      // Silently fail file logging
+    }
+  }
+}
+
+module.exports = { Logger };