voltjs-framework 1.0.0

package/src/utils/cron.js

@@ -0,0 +1,213 @@
+/**
+ * VoltJS Cron
+ * 
+ * Cron-like scheduled task runner with human-readable syntax.
+ * 
+ * @example
+ * const { Cron } = require('voltjs');
+ * 
+ * const cron = new Cron();
+ * cron.schedule('cleanup', '0 * * * *', async () => {   // Every hour
+ *   await cleanupOldFiles();
+ * });
+ * cron.schedule('report', '0 9 * * 1', sendWeeklyReport); // Mon 9am
+ * 
+ * cron.start();
+ */
+
+'use strict';
+
+class Cron {
+  constructor() {
+    this.tasks = new Map();
+    this.running = false;
+    this._timer = null;
+  }
+
+  /** Schedule a task */
+  schedule(name, expression, handler, options = {}) {
+    const parsed = Cron.parse(expression);
+    
+    this.tasks.set(name, {
+      name,
+      expression,
+      parsed,
+      handler,
+      enabled: options.enabled !== false,
+      runOnStart: options.runOnStart || false,
+      lastRun: null,
+      nextRun: null,
+      runCount: 0,
+      errors: 0,
+    });
+
+    return this;
+  }
+
+  /** Remove a task */
+  remove(name) {
+    this.tasks.delete(name);
+    return this;
+  }
+
+  /** Enable a task */
+  enable(name) {
+    const task = this.tasks.get(name);
+    if (task) task.enabled = true;
+    return this;
+  }
+
+  /** Disable a task */
+  disable(name) {
+    const task = this.tasks.get(name);
+    if (task) task.enabled = false;
+    return this;
+  }
+
+  /** Start the scheduler */
+  start() {
+    if (this.running) return;
+    this.running = true;
+
+    // Run-on-start tasks
+    for (const task of this.tasks.values()) {
+      if (task.runOnStart && task.enabled) {
+        this._runTask(task);
+      }
+    }
+
+    // Check every second
+    this._timer = setInterval(() => this._tick(), 1000);
+    if (this._timer.unref) this._timer.unref();
+    return this;
+  }
+
+  /** Stop the scheduler */
+  stop() {
+    this.running = false;
+    if (this._timer) {
+      clearInterval(this._timer);
+      this._timer = null;
+    }
+    return this;
+  }
+
+  /** Get status of all tasks */
+  status() {
+    const tasks = [];
+    for (const task of this.tasks.values()) {
+      tasks.push({
+        name: task.name,
+        expression: task.expression,
+        enabled: task.enabled,
+        lastRun: task.lastRun,
+        runCount: task.runCount,
+        errors: task.errors,
+      });
+    }
+    return { running: this.running, tasks };
+  }
+
+  /** Run a task immediately by name */
+  async run(name) {
+    const task = this.tasks.get(name);
+    if (!task) throw new Error(`Task not found: ${name}`);
+    return this._runTask(task);
+  }
+
+  /** Convenience helpers */
+  everyMinute(name, handler) { return this.schedule(name, '* * * * *', handler); }
+  every5Minutes(name, handler) { return this.schedule(name, '*/5 * * * *', handler); }
+  every15Minutes(name, handler) { return this.schedule(name, '*/15 * * * *', handler); }
+  every30Minutes(name, handler) { return this.schedule(name, '*/30 * * * *', handler); }
+  hourly(name, handler) { return this.schedule(name, '0 * * * *', handler); }
+  daily(name, handler) { return this.schedule(name, '0 0 * * *', handler); }
+  weekly(name, handler) { return this.schedule(name, '0 0 * * 0', handler); }
+  monthly(name, handler) { return this.schedule(name, '0 0 1 * *', handler); }
+
+  // ===== PARSING =====
+
+  /** Parse cron expression: minute hour day month weekday */
+  static parse(expression) {
+    const parts = expression.trim().split(/\s+/);
+    if (parts.length !== 5) {
+      throw new Error(`Invalid cron expression: ${expression} (need 5 fields: min hour day month weekday)`);
+    }
+
+    return {
+      minute: Cron._parseField(parts[0], 0, 59),
+      hour: Cron._parseField(parts[1], 0, 23),
+      day: Cron._parseField(parts[2], 1, 31),
+      month: Cron._parseField(parts[3], 1, 12),
+      weekday: Cron._parseField(parts[4], 0, 6),
+    };
+  }
+
+  /** Check if now matches the cron pattern */
+  static matches(parsed, date) {
+    return (
+      parsed.minute.includes(date.getMinutes()) &&
+      parsed.hour.includes(date.getHours()) &&
+      parsed.day.includes(date.getDate()) &&
+      parsed.month.includes(date.getMonth() + 1) &&
+      parsed.weekday.includes(date.getDay())
+    );
+  }
+
+  static _parseField(field, min, max) {
+    if (field === '*') {
+      return Array.from({ length: max - min + 1 }, (_, i) => min + i);
+    }
+
+    const values = new Set();
+
+    for (const part of field.split(',')) {
+      if (part.includes('/')) {
+        // Step: */5 or 1-30/5
+        const [range, step] = part.split('/');
+        const stepNum = parseInt(step);
+        const [start, end] = range === '*' ? [min, max] : range.split('-').map(Number);
+        for (let i = start; i <= (end || max); i += stepNum) {
+          values.add(i);
+        }
+      } else if (part.includes('-')) {
+        // Range: 1-5
+        const [start, end] = part.split('-').map(Number);
+        for (let i = start; i <= end; i++) values.add(i);
+      } else {
+        // Single value
+        values.add(parseInt(part));
+      }
+    }
+
+    return [...values];
+  }
+
+  // ===== INTERNAL =====
+
+  _tick() {
+    const now = new Date();
+    // Only check at second 0 to avoid double-firing
+    if (now.getSeconds() !== 0) return;
+
+    for (const task of this.tasks.values()) {
+      if (!task.enabled) continue;
+      if (Cron.matches(task.parsed, now)) {
+        this._runTask(task);
+      }
+    }
+  }
+
+  async _runTask(task) {
+    try {
+      task.lastRun = new Date();
+      task.runCount++;
+      await task.handler();
+    } catch (error) {
+      task.errors++;
+      console.error(`[Cron] Task "${task.name}" failed:`, error.message);
+    }
+  }
+}
+
+module.exports = { Cron };

package/src/utils/date.js

@@ -0,0 +1,223 @@
+/**
+ * VoltJS DateHelper
+ * 
+ * Date manipulation and formatting without external dependencies.
+ * 
+ * @example
+ * const { DateHelper } = require('voltjs');
+ * 
+ * DateHelper.format(new Date(), 'YYYY-MM-DD HH:mm:ss');
+ * DateHelper.ago(new Date('2024-01-01')); // "6 months ago"
+ * DateHelper.add(new Date(), 7, 'days');
+ * DateHelper.diff(date1, date2, 'hours');
+ */
+
+'use strict';
+
+class DateHelper {
+  /** Format a date string: YYYY, MM, DD, HH, mm, ss, ddd, MMM */
+  static format(date, fmt = 'YYYY-MM-DD HH:mm:ss') {
+    const d = new Date(date);
+    const days = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+    const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+    const fullMonths = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];
+    const fullDays = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+
+    const pad = (n) => String(n).padStart(2, '0');
+
+    return fmt
+      .replace('YYYY', d.getFullYear())
+      .replace('YY', String(d.getFullYear()).slice(-2))
+      .replace('MMMM', fullMonths[d.getMonth()])
+      .replace('MMM', months[d.getMonth()])
+      .replace('MM', pad(d.getMonth() + 1))
+      .replace('DD', pad(d.getDate()))
+      .replace('dddd', fullDays[d.getDay()])
+      .replace('ddd', days[d.getDay()])
+      .replace('HH', pad(d.getHours()))
+      .replace('hh', pad(d.getHours() % 12 || 12))
+      .replace('mm', pad(d.getMinutes()))
+      .replace('ss', pad(d.getSeconds()))
+      .replace('A', d.getHours() >= 12 ? 'PM' : 'AM')
+      .replace('a', d.getHours() >= 12 ? 'pm' : 'am');
+  }
+
+  /** Relative time: "2 hours ago", "in 3 days" */
+  static ago(date) {
+    const now = Date.now();
+    const d = new Date(date).getTime();
+    const diff = now - d;
+    const abs = Math.abs(diff);
+    const future = diff < 0;
+
+    const seconds = Math.floor(abs / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    const weeks = Math.floor(days / 7);
+    const months = Math.floor(days / 30);
+    const years = Math.floor(days / 365);
+
+    let text;
+    if (seconds < 5) text = 'just now';
+    else if (seconds < 60) text = `${seconds} seconds`;
+    else if (minutes === 1) text = '1 minute';
+    else if (minutes < 60) text = `${minutes} minutes`;
+    else if (hours === 1) text = '1 hour';
+    else if (hours < 24) text = `${hours} hours`;
+    else if (days === 1) text = '1 day';
+    else if (days < 7) text = `${days} days`;
+    else if (weeks === 1) text = '1 week';
+    else if (weeks < 4) text = `${weeks} weeks`;
+    else if (months === 1) text = '1 month';
+    else if (months < 12) text = `${months} months`;
+    else if (years === 1) text = '1 year';
+    else text = `${years} years`;
+
+    if (text === 'just now') return text;
+    return future ? `in ${text}` : `${text} ago`;
+  }
+
+  /** Add time to a date */
+  static add(date, amount, unit = 'days') {
+    const d = new Date(date);
+    switch (unit) {
+      case 'seconds': case 'second': d.setSeconds(d.getSeconds() + amount); break;
+      case 'minutes': case 'minute': d.setMinutes(d.getMinutes() + amount); break;
+      case 'hours': case 'hour': d.setHours(d.getHours() + amount); break;
+      case 'days': case 'day': d.setDate(d.getDate() + amount); break;
+      case 'weeks': case 'week': d.setDate(d.getDate() + amount * 7); break;
+      case 'months': case 'month': d.setMonth(d.getMonth() + amount); break;
+      case 'years': case 'year': d.setFullYear(d.getFullYear() + amount); break;
+    }
+    return d;
+  }
+
+  /** Subtract time from a date */
+  static subtract(date, amount, unit = 'days') {
+    return DateHelper.add(date, -amount, unit);
+  }
+
+  /** Get difference between two dates */
+  static diff(date1, date2, unit = 'days') {
+    const ms = Math.abs(new Date(date1) - new Date(date2));
+    switch (unit) {
+      case 'milliseconds': case 'ms': return ms;
+      case 'seconds': case 'second': return Math.floor(ms / 1000);
+      case 'minutes': case 'minute': return Math.floor(ms / 60000);
+      case 'hours': case 'hour': return Math.floor(ms / 3600000);
+      case 'days': case 'day': return Math.floor(ms / 86400000);
+      case 'weeks': case 'week': return Math.floor(ms / 604800000);
+      case 'months': case 'month': return Math.floor(ms / 2592000000);
+      case 'years': case 'year': return Math.floor(ms / 31536000000);
+      default: return ms;
+    }
+  }
+
+  /** Check if a date is today */
+  static isToday(date) {
+    const d = new Date(date);
+    const today = new Date();
+    return d.toDateString() === today.toDateString();
+  }
+
+  /** Check if a date is in the past */
+  static isPast(date) { return new Date(date) < new Date(); }
+
+  /** Check if a date is in the future */
+  static isFuture(date) { return new Date(date) > new Date(); }
+
+  /** Check if two dates are the same day */
+  static isSameDay(d1, d2) {
+    return new Date(d1).toDateString() === new Date(d2).toDateString();
+  }
+
+  /** Get start of day/week/month/year */
+  static startOf(date, unit = 'day') {
+    const d = new Date(date);
+    switch (unit) {
+      case 'day': d.setHours(0, 0, 0, 0); break;
+      case 'week': d.setDate(d.getDate() - d.getDay()); d.setHours(0, 0, 0, 0); break;
+      case 'month': d.setDate(1); d.setHours(0, 0, 0, 0); break;
+      case 'year': d.setMonth(0, 1); d.setHours(0, 0, 0, 0); break;
+    }
+    return d;
+  }
+
+  /** Get end of day/week/month/year */
+  static endOf(date, unit = 'day') {
+    const d = new Date(date);
+    switch (unit) {
+      case 'day': d.setHours(23, 59, 59, 999); break;
+      case 'week': d.setDate(d.getDate() + (6 - d.getDay())); d.setHours(23, 59, 59, 999); break;
+      case 'month': d.setMonth(d.getMonth() + 1, 0); d.setHours(23, 59, 59, 999); break;
+      case 'year': d.setMonth(11, 31); d.setHours(23, 59, 59, 999); break;
+    }
+    return d;
+  }
+
+  /** Get ISO week number */
+  static weekNumber(date) {
+    const d = new Date(date);
+    d.setHours(0, 0, 0, 0);
+    d.setDate(d.getDate() + 3 - (d.getDay() + 6) % 7);
+    const week1 = new Date(d.getFullYear(), 0, 4);
+    return 1 + Math.round(((d - week1) / 86400000 - 3 + (week1.getDay() + 6) % 7) / 7);
+  }
+
+  /** Check if year is a leap year */
+  static isLeapYear(year) {
+    return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+  }
+
+  /** Get days in month */
+  static daysInMonth(year, month) {
+    return new Date(year, month, 0).getDate();
+  }
+
+  /** Parse a date from various formats */
+  static parse(str) {
+    // Try ISO format first
+    const d = new Date(str);
+    if (!isNaN(d)) return d;
+
+    // Try DD/MM/YYYY
+    const dmy = str.match(/^(\d{1,2})[\/\-](\d{1,2})[\/\-](\d{4})$/);
+    if (dmy) return new Date(parseInt(dmy[3]), parseInt(dmy[2]) - 1, parseInt(dmy[1]));
+
+    // Try relative: "5 days ago", "in 3 hours"
+    const agoMatch = str.match(/^(\d+)\s+(second|minute|hour|day|week|month|year)s?\s+ago$/i);
+    if (agoMatch) return DateHelper.subtract(new Date(), parseInt(agoMatch[1]), agoMatch[2] + 's');
+
+    const inMatch = str.match(/^in\s+(\d+)\s+(second|minute|hour|day|week|month|year)s?$/i);
+    if (inMatch) return DateHelper.add(new Date(), parseInt(inMatch[1]), inMatch[2] + 's');
+
+    return null;
+  }
+
+  /** ISO string (UTC) */
+  static toISO(date) { return new Date(date).toISOString(); }
+
+  /** Unix timestamp (seconds) */
+  static toUnix(date) { return Math.floor(new Date(date).getTime() / 1000); }
+
+  /** From Unix timestamp */
+  static fromUnix(timestamp) { return new Date(timestamp * 1000); }
+
+  /** Current timestamp in ms */
+  static now() { return Date.now(); }
+
+  /** Generate date range */
+  static range(start, end, step = 'day') {
+    const dates = [];
+    let current = new Date(start);
+    const endDate = new Date(end);
+    while (current <= endDate) {
+      dates.push(new Date(current));
+      current = DateHelper.add(current, 1, step);
+    }
+    return dates;
+  }
+}
+
+module.exports = { DateHelper };

package/src/utils/events.js

@@ -0,0 +1,181 @@
+/**
+ * VoltJS EventBus
+ * 
+ * Typed event emitter with async support, wildcard patterns, and once listeners.
+ * 
+ * @example
+ * const { EventBus } = require('voltjs');
+ * 
+ * const bus = new EventBus();
+ * bus.on('user:created', (user) => console.log('Created:', user));
+ * bus.on('user:*', (data) => console.log('User event:', data));
+ * bus.emit('user:created', { id: 1, name: 'Jane' });
+ */
+
+'use strict';
+
+class EventBus {
+  constructor() {
+    this._listeners = new Map();
+    this._onceListeners = new Map();
+    this._wildcardListeners = [];
+  }
+
+  /** Register an event listener */
+  on(event, handler) {
+    if (event.includes('*')) {
+      const pattern = new RegExp('^' + event.replace(/\*/g, '.*') + '$');
+      this._wildcardListeners.push({ pattern, handler, original: event });
+      return this;
+    }
+
+    if (!this._listeners.has(event)) {
+      this._listeners.set(event, []);
+    }
+    this._listeners.get(event).push(handler);
+    return this;
+  }
+
+  /** Register a one-time listener */
+  once(event, handler) {
+    if (!this._onceListeners.has(event)) {
+      this._onceListeners.set(event, []);
+    }
+    this._onceListeners.get(event).push(handler);
+    return this;
+  }
+
+  /** Remove a listener */
+  off(event, handler) {
+    if (handler) {
+      const listeners = this._listeners.get(event);
+      if (listeners) {
+        this._listeners.set(event, listeners.filter(h => h !== handler));
+      }
+      const once = this._onceListeners.get(event);
+      if (once) {
+        this._onceListeners.set(event, once.filter(h => h !== handler));
+      }
+      this._wildcardListeners = this._wildcardListeners.filter(
+        w => !(w.original === event && w.handler === handler)
+      );
+    } else {
+      this._listeners.delete(event);
+      this._onceListeners.delete(event);
+    }
+    return this;
+  }
+
+  /** Emit an event (supports async handlers) */
+  async emit(event, ...args) {
+    const results = [];
+
+    // Exact match listeners
+    const listeners = this._listeners.get(event) || [];
+    for (const handler of listeners) {
+      results.push(await handler(...args));
+    }
+
+    // Once listeners
+    const onceListeners = this._onceListeners.get(event) || [];
+    this._onceListeners.delete(event);
+    for (const handler of onceListeners) {
+      results.push(await handler(...args));
+    }
+
+    // Wildcard listeners
+    for (const { pattern, handler } of this._wildcardListeners) {
+      if (pattern.test(event)) {
+        results.push(await handler(...args, event));
+      }
+    }
+
+    return results;
+  }
+
+  /** Emit synchronously (no await) */
+  emitSync(event, ...args) {
+    const listeners = this._listeners.get(event) || [];
+    for (const handler of listeners) handler(...args);
+
+    const onceListeners = this._onceListeners.get(event) || [];
+    this._onceListeners.delete(event);
+    for (const handler of onceListeners) handler(...args);
+
+    for (const { pattern, handler } of this._wildcardListeners) {
+      if (pattern.test(event)) handler(...args, event);
+    }
+  }
+
+  /** Wait for an event to fire */
+  waitFor(event, timeout = 30000) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.off(event, handler);
+        reject(new Error(`Timeout waiting for event: ${event}`));
+      }, timeout);
+
+      const handler = (...args) => {
+        clearTimeout(timer);
+        resolve(args.length === 1 ? args[0] : args);
+      };
+
+      this.once(event, handler);
+    });
+  }
+
+  /** Check if event has listeners */
+  hasListeners(event) {
+    const exact = (this._listeners.get(event) || []).length > 0;
+    const once = (this._onceListeners.get(event) || []).length > 0;
+    const wildcard = this._wildcardListeners.some(w => w.pattern.test(event));
+    return exact || once || wildcard;
+  }
+
+  /** Get listener count for an event */
+  listenerCount(event) {
+    let count = (this._listeners.get(event) || []).length;
+    count += (this._onceListeners.get(event) || []).length;
+    count += this._wildcardListeners.filter(w => w.pattern.test(event)).length;
+    return count;
+  }
+
+  /** Get all registered event names */
+  eventNames() {
+    const names = new Set([
+      ...this._listeners.keys(),
+      ...this._onceListeners.keys(),
+      ...this._wildcardListeners.map(w => w.original),
+    ]);
+    return [...names];
+  }
+
+  /** Remove all listeners */
+  removeAll() {
+    this._listeners.clear();
+    this._onceListeners.clear();
+    this._wildcardListeners = [];
+    return this;
+  }
+
+  /** Create a namespaced event bus */
+  namespace(prefix) {
+    const self = this;
+    return {
+      on: (event, handler) => self.on(`${prefix}:${event}`, handler),
+      once: (event, handler) => self.once(`${prefix}:${event}`, handler),
+      off: (event, handler) => self.off(`${prefix}:${event}`, handler),
+      emit: (event, ...args) => self.emit(`${prefix}:${event}`, ...args),
+    };
+  }
+
+  /** Pipe events from another event bus */
+  pipe(source, events) {
+    for (const event of events) {
+      source.on(event, (...args) => this.emit(event, ...args));
+    }
+    return this;
+  }
+}
+
+module.exports = { EventBus };