voltjs-framework 1.0.0

package/src/utils/pdf.js

@@ -0,0 +1,417 @@
+/**
+ * VoltJS PDF Generator
+ * 
+ * Generate PDF documents from HTML or programmatically.
+ * Uses raw PDF spec — zero external dependencies.
+ * 
+ * @example
+ * const { PDF } = require('voltjs');
+ * 
+ * const pdf = new PDF();
+ * pdf.addPage()
+ *    .setFont('Helvetica', 16)
+ *    .text('Hello VoltJS!', 50, 700)
+ *    .setFont('Helvetica', 12)
+ *    .text('Generated with VoltJS PDF', 50, 670)
+ *    .line(50, 660, 550, 660)
+ *    .save('output.pdf');
+ */
+
+'use strict';
+
+const fs = require('fs');
+
+class PDF {
+  constructor(options = {}) {
+    this._objects = [];
+    this._pages = [];
+    this._currentPage = null;
+    this._fonts = new Map();
+    this._pageWidth = options.width || 612;  // US Letter
+    this._pageHeight = options.height || 792;
+    this._margin = options.margin || 50;
+    this._fontSize = 12;
+    this._fontName = 'Helvetica';
+
+    // Register standard fonts
+    this._registerStandardFonts();
+  }
+
+  /** Add a new page */
+  addPage(options = {}) {
+    const width = options.width || this._pageWidth;
+    const height = options.height || this._pageHeight;
+
+    this._currentPage = {
+      width,
+      height,
+      content: [],
+    };
+    this._pages.push(this._currentPage);
+    return this;
+  }
+
+  /** Set font */
+  setFont(name, size) {
+    this._fontName = name || 'Helvetica';
+    this._fontSize = size || 12;
+    if (this._currentPage) {
+      this._currentPage.content.push(`/F1 ${this._fontSize} Tf`);
+    }
+    return this;
+  }
+
+  /** Add text to current page */
+  text(str, x, y, options = {}) {
+    if (!this._currentPage) this.addPage();
+
+    const escapedStr = this._escapeString(str);
+    const alignment = options.align || 'left';
+
+    this._currentPage.content.push('BT');
+    this._currentPage.content.push(`/F1 ${this._fontSize} Tf`);
+
+    if (options.color) {
+      const rgb = this._hexToRgb(options.color);
+      this._currentPage.content.push(`${rgb.r} ${rgb.g} ${rgb.b} rg`);
+    }
+
+    this._currentPage.content.push(`${x} ${y} Td`);
+    this._currentPage.content.push(`(${escapedStr}) Tj`);
+    this._currentPage.content.push('ET');
+
+    return this;
+  }
+
+  /** Add a line */
+  line(x1, y1, x2, y2, options = {}) {
+    if (!this._currentPage) this.addPage();
+
+    const lineWidth = options.width || 1;
+    const content = this._currentPage.content;
+
+    if (options.color) {
+      const rgb = this._hexToRgb(options.color);
+      content.push(`${rgb.r} ${rgb.g} ${rgb.b} RG`);
+    }
+
+    content.push(`${lineWidth} w`);
+    content.push(`${x1} ${y1} m`);
+    content.push(`${x2} ${y2} l`);
+    content.push('S');
+
+    return this;
+  }
+
+  /** Add a rectangle */
+  rect(x, y, width, height, options = {}) {
+    if (!this._currentPage) this.addPage();
+    const content = this._currentPage.content;
+
+    if (options.fill) {
+      const rgb = this._hexToRgb(options.fill);
+      content.push(`${rgb.r} ${rgb.g} ${rgb.b} rg`);
+    }
+    if (options.stroke) {
+      const rgb = this._hexToRgb(options.stroke);
+      content.push(`${rgb.r} ${rgb.g} ${rgb.b} RG`);
+    }
+
+    content.push(`${x} ${y} ${width} ${height} re`);
+    content.push(options.fill && options.stroke ? 'B' : options.fill ? 'f' : 'S');
+
+    return this;
+  }
+
+  /** Add a circle */
+  circle(cx, cy, radius, options = {}) {
+    if (!this._currentPage) this.addPage();
+    const content = this._currentPage.content;
+
+    if (options.fill) {
+      const rgb = this._hexToRgb(options.fill);
+      content.push(`${rgb.r} ${rgb.g} ${rgb.b} rg`);
+    }
+
+    // Approximate circle with bezier curves
+    const k = 0.5523;
+    const kr = k * radius;
+
+    content.push(`${cx + radius} ${cy} m`);
+    content.push(`${cx + radius} ${cy + kr} ${cx + kr} ${cy + radius} ${cx} ${cy + radius} c`);
+    content.push(`${cx - kr} ${cy + radius} ${cx - radius} ${cy + kr} ${cx - radius} ${cy} c`);
+    content.push(`${cx - radius} ${cy - kr} ${cx - kr} ${cy - radius} ${cx} ${cy - radius} c`);
+    content.push(`${cx + kr} ${cy - radius} ${cx + radius} ${cy - kr} ${cx + radius} ${cy} c`);
+    content.push(options.fill ? 'f' : 'S');
+
+    return this;
+  }
+
+  /** Add a table */
+  table(data, x, y, options = {}) {
+    if (!this._currentPage) this.addPage();
+
+    const cellWidth = options.cellWidth || 100;
+    const cellHeight = options.cellHeight || 25;
+    const headerBg = options.headerBg || '#667eea';
+    const headers = options.headers || (data.length > 0 ? Object.keys(data[0]) : []);
+
+    let currentY = y;
+
+    // Draw header
+    headers.forEach((header, i) => {
+      this.rect(x + i * cellWidth, currentY, cellWidth, cellHeight, { fill: headerBg, stroke: '#333333' });
+      this.setFont('Helvetica', 10);
+      this._currentPage.content.push('1 1 1 rg'); // White text
+      this.text(String(header), x + i * cellWidth + 5, currentY + 8);
+      this._currentPage.content.push('0 0 0 rg'); // Reset to black
+    });
+
+    currentY -= cellHeight;
+
+    // Draw data rows
+    for (const row of data) {
+      headers.forEach((header, i) => {
+        this.rect(x + i * cellWidth, currentY, cellWidth, cellHeight, { stroke: '#cccccc' });
+        this.setFont('Helvetica', 9);
+        this.text(String(row[header] ?? ''), x + i * cellWidth + 5, currentY + 8);
+      });
+      currentY -= cellHeight;
+    }
+
+    return this;
+  }
+
+  /** Add header section */
+  header(title, subtitle = '') {
+    if (!this._currentPage) this.addPage();
+
+    const y = this._pageHeight - this._margin;
+
+    // Header bar
+    this.rect(0, y - 10, this._pageWidth, 60, { fill: '#667eea' });
+    this._currentPage.content.push('1 1 1 rg');
+    this.setFont('Helvetica', 20);
+    this.text(title, this._margin, y + 15);
+
+    if (subtitle) {
+      this.setFont('Helvetica', 10);
+      this.text(subtitle, this._margin, y);
+    }
+
+    this._currentPage.content.push('0 0 0 rg');
+    return this;
+  }
+
+  /** Add paragraph (auto-wrapping text) */
+  paragraph(str, x, y, maxWidth, options = {}) {
+    if (!this._currentPage) this.addPage();
+
+    const fontSize = options.fontSize || this._fontSize;
+    const lineHeight = options.lineHeight || fontSize * 1.5;
+    const charWidth = fontSize * 0.5; // Approximate
+    const maxChars = Math.floor(maxWidth / charWidth);
+
+    const words = str.split(' ');
+    let line = '';
+    let currentY = y;
+
+    for (const word of words) {
+      if ((line + ' ' + word).length > maxChars) {
+        this.setFont(this._fontName, fontSize);
+        this.text(line.trim(), x, currentY);
+        currentY -= lineHeight;
+        line = word;
+      } else {
+        line += (line ? ' ' : '') + word;
+      }
+    }
+    if (line) {
+      this.setFont(this._fontName, fontSize);
+      this.text(line.trim(), x, currentY);
+    }
+
+    return this;
+  }
+
+  /** Generate PDF buffer */
+  toBuffer() {
+    return Buffer.from(this._build(), 'binary');
+  }
+
+  /** Save to file */
+  save(filePath) {
+    fs.writeFileSync(filePath, this.toBuffer());
+    return filePath;
+  }
+
+  // ===== INTERNAL PDF GENERATION =====
+
+  _build() {
+    const objects = [];
+    let objectNum = 0;
+
+    const addObj = (content) => {
+      objectNum++;
+      objects.push({ num: objectNum, content });
+      return objectNum;
+    };
+
+    // Catalog
+    const catalogNum = addObj('<<\n/Type /Catalog\n/Pages 2 0 R\n>>');
+
+    // Pages parent (will be filled later)
+    const pagesNum = addObj(''); // Placeholder
+
+    // Font
+    const fontNum = addObj('<<\n/Type /Font\n/Subtype /Type1\n/BaseFont /Helvetica\n>>');
+
+    // Build pages
+    const pageNums = [];
+    for (const page of this._pages) {
+      // Page content stream
+      const stream = page.content.join('\n');
+      const streamLength = Buffer.byteLength(stream, 'binary');
+      const streamNum = addObj(
+        `<<\n/Length ${streamLength}\n>>\nstream\n${stream}\nendstream`
+      );
+
+      // Page object
+      const pageNum = addObj(
+        `<<\n/Type /Page\n/Parent ${pagesNum} 0 R\n/MediaBox [0 0 ${page.width} ${page.height}]\n/Contents ${streamNum} 0 R\n/Resources <<\n/Font <<\n/F1 ${fontNum} 0 R\n>>\n>>\n>>`
+      );
+      pageNums.push(pageNum);
+    }
+
+    // Update pages parent
+    objects[pagesNum - 1].content = `<<\n/Type /Pages\n/Kids [${pageNums.map(n => `${n} 0 R`).join(' ')}]\n/Count ${pageNums.length}\n>>`;
+
+    // Build PDF
+    let pdf = '%PDF-1.4\n';
+    const offsets = [];
+
+    for (const obj of objects) {
+      offsets.push(pdf.length);
+      pdf += `${obj.num} 0 obj\n${obj.content}\nendobj\n`;
+    }
+
+    // Cross-reference table
+    const xrefOffset = pdf.length;
+    pdf += `xref\n0 ${objects.length + 1}\n`;
+    pdf += '0000000000 65535 f \n';
+    for (const offset of offsets) {
+      pdf += `${String(offset).padStart(10, '0')} 00000 n \n`;
+    }
+
+    // Trailer
+    pdf += `trailer\n<<\n/Size ${objects.length + 1}\n/Root ${catalogNum} 0 R\n>>\nstartxref\n${xrefOffset}\n%%EOF`;
+
+    return pdf;
+  }
+
+  _escapeString(str) {
+    return String(str)
+      .replace(/\\/g, '\\\\')
+      .replace(/\(/g, '\\(')
+      .replace(/\)/g, '\\)');
+  }
+
+  _hexToRgb(hex) {
+    const cleaned = hex.replace('#', '');
+    const r = parseInt(cleaned.substring(0, 2), 16) / 255;
+    const g = parseInt(cleaned.substring(2, 4), 16) / 255;
+    const b = parseInt(cleaned.substring(4, 6), 16) / 255;
+    return { r: r.toFixed(3), g: g.toFixed(3), b: b.toFixed(3) };
+  }
+
+  _registerStandardFonts() {
+    this._fonts.set('Helvetica', '/Helvetica');
+    this._fonts.set('Times', '/Times-Roman');
+    this._fonts.set('Courier', '/Courier');
+  }
+
+  // ===== STATIC HELPERS =====
+
+  /** Quick PDF from HTML-like content */
+  static fromData(data, options = {}) {
+    const pdf = new PDF(options);
+    const page = pdf.addPage();
+
+    let y = pdf._pageHeight - pdf._margin - 50;
+    const title = options.title || 'Report';
+
+    pdf.header(title, options.subtitle || new Date().toLocaleString());
+
+    if (Array.isArray(data) && data.length > 0 && typeof data[0] === 'object') {
+      y -= 80;
+      pdf.table(data, pdf._margin, y, {
+        headers: options.headers || Object.keys(data[0]),
+        cellWidth: options.cellWidth || Math.floor((pdf._pageWidth - pdf._margin * 2) / Object.keys(data[0]).length),
+      });
+    }
+
+    return pdf;
+  }
+
+  /** Generate PDF invoice */
+  static invoice(invoiceData) {
+    const pdf = new PDF();
+    pdf.addPage();
+
+    const w = pdf._pageWidth;
+    const h = pdf._pageHeight;
+    const m = pdf._margin;
+    let y = h - m;
+
+    // Header
+    pdf.setFont('Helvetica', 24);
+    pdf.text('INVOICE', m, y);
+
+    pdf.setFont('Helvetica', 10);
+    y -= 30;
+    pdf.text(`Invoice #: ${invoiceData.number || '001'}`, m, y);
+    y -= 15;
+    pdf.text(`Date: ${invoiceData.date || new Date().toLocaleDateString()}`, m, y);
+    y -= 15;
+    pdf.text(`Due: ${invoiceData.dueDate || 'On Receipt'}`, m, y);
+
+    // From
+    y -= 30;
+    pdf.setFont('Helvetica', 12);
+    pdf.text('From:', m, y);
+    pdf.setFont('Helvetica', 10);
+    y -= 15;
+    pdf.text(invoiceData.from?.name || 'Company', m, y);
+    y -= 12;
+    pdf.text(invoiceData.from?.address || '', m, y);
+
+    // To
+    y -= 30;
+    pdf.setFont('Helvetica', 12);
+    pdf.text('Bill To:', m, y);
+    pdf.setFont('Helvetica', 10);
+    y -= 15;
+    pdf.text(invoiceData.to?.name || 'Client', m, y);
+    y -= 12;
+    pdf.text(invoiceData.to?.address || '', m, y);
+
+    // Items table
+    y -= 30;
+    if (invoiceData.items && invoiceData.items.length > 0) {
+      pdf.table(invoiceData.items, m, y, {
+        headers: ['description', 'quantity', 'price', 'total'],
+        cellWidth: (w - m * 2) / 4,
+      });
+    }
+
+    // Total
+    y -= (invoiceData.items?.length || 0) * 25 + 50;
+    pdf.setFont('Helvetica', 14);
+    const total = invoiceData.items?.reduce((sum, item) => sum + (item.total || 0), 0) || 0;
+    pdf.text(`Total: $${total.toFixed(2)}`, w - m - 150, y);
+
+    return pdf;
+  }
+}
+
+module.exports = { PDF };

package/src/utils/queue.js

@@ -0,0 +1,199 @@
+/**
+ * VoltJS Queue
+ * 
+ * In-process job queue with retries, delays, priorities, and concurrency control.
+ * 
+ * @example
+ * const { Queue } = require('voltjs');
+ * 
+ * const queue = new Queue('emails', { concurrency: 3, retries: 3 });
+ * 
+ * queue.process(async (job) => {
+ *   await sendEmail(job.data);
+ * });
+ * 
+ * queue.add({ to: 'user@example.com', subject: 'Hello' }, { priority: 'high' });
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const { EventEmitter } = require('events');
+
+class Queue extends EventEmitter {
+  constructor(name, options = {}) {
+    super();
+    this.name = name;
+    this.concurrency = options.concurrency || 1;
+    this.maxRetries = options.retries || 3;
+    this.retryDelay = options.retryDelay || 1000; // ms
+    this.timeout = options.timeout || 30000; // 30s
+
+    this.jobs = [];
+    this.processing = 0;
+    this.handler = null;
+    this.paused = false;
+
+    this.stats = { completed: 0, failed: 0, retried: 0, total: 0 };
+    this._delayed = [];
+  }
+
+  /** Add a job to the queue */
+  add(data, options = {}) {
+    const job = {
+      id: options.id || crypto.randomBytes(8).toString('hex'),
+      data,
+      priority: this._priorityValue(options.priority || 'normal'),
+      retries: 0,
+      maxRetries: options.retries || this.maxRetries,
+      delay: options.delay || 0,
+      createdAt: Date.now(),
+      status: 'pending',
+    };
+
+    this.stats.total++;
+
+    if (job.delay > 0) {
+      const timer = setTimeout(() => {
+        this._enqueue(job);
+        this._delayed = this._delayed.filter(d => d.id !== job.id);
+      }, job.delay);
+      if (timer.unref) timer.unref();
+      this._delayed.push({ id: job.id, timer });
+    } else {
+      this._enqueue(job);
+    }
+
+    this.emit('added', job);
+    return job;
+  }
+
+  /** Add multiple jobs */
+  addBulk(items, options = {}) {
+    return items.map(data => this.add(data, options));
+  }
+
+  /** Register job processor */
+  process(handler) {
+    this.handler = handler;
+    this._tick();
+  }
+
+  /** Pause the queue */
+  pause() {
+    this.paused = true;
+    this.emit('paused');
+  }
+
+  /** Resume the queue */
+  resume() {
+    this.paused = false;
+    this.emit('resumed');
+    this._tick();
+  }
+
+  /** Get queue size */
+  size() {
+    return this.jobs.length;
+  }
+
+  /** Get queue status */
+  status() {
+    return {
+      name: this.name,
+      pending: this.jobs.length,
+      processing: this.processing,
+      delayed: this._delayed.length,
+      paused: this.paused,
+      ...this.stats,
+    };
+  }
+
+  /** Clear all pending jobs */
+  clear() {
+    this.jobs = [];
+    this._delayed.forEach(d => clearTimeout(d.timer));
+    this._delayed = [];
+    this.emit('cleared');
+  }
+
+  /** Remove a specific job by ID */
+  remove(id) {
+    const idx = this.jobs.findIndex(j => j.id === id);
+    if (idx >= 0) {
+      this.jobs.splice(idx, 1);
+      return true;
+    }
+    return false;
+  }
+
+  // ===== INTERNAL =====
+
+  _enqueue(job) {
+    // Insert sorted by priority (higher priority = processed first)
+    let inserted = false;
+    for (let i = 0; i < this.jobs.length; i++) {
+      if (job.priority > this.jobs[i].priority) {
+        this.jobs.splice(i, 0, job);
+        inserted = true;
+        break;
+      }
+    }
+    if (!inserted) this.jobs.push(job);
+    this._tick();
+  }
+
+  async _tick() {
+    if (this.paused || !this.handler) return;
+    if (this.processing >= this.concurrency) return;
+    if (this.jobs.length === 0) return;
+
+    const job = this.jobs.shift();
+    job.status = 'processing';
+    this.processing++;
+
+    try {
+      // Timeout wrapper
+      const result = await Promise.race([
+        this.handler(job),
+        new Promise((_, reject) =>
+          setTimeout(() => reject(new Error(`Job ${job.id} timed out`)), this.timeout)
+        ),
+      ]);
+
+      job.status = 'completed';
+      job.result = result;
+      this.stats.completed++;
+      this.emit('completed', job);
+
+    } catch (error) {
+      job.retries++;
+      
+      if (job.retries <= job.maxRetries) {
+        job.status = 'retrying';
+        job.lastError = error.message;
+        this.stats.retried++;
+        this.emit('retrying', job, error);
+
+        // Exponential backoff
+        const delay = this.retryDelay * Math.pow(2, job.retries - 1);
+        setTimeout(() => this._enqueue(job), delay);
+      } else {
+        job.status = 'failed';
+        job.error = error.message;
+        this.stats.failed++;
+        this.emit('failed', job, error);
+      }
+    } finally {
+      this.processing--;
+      this._tick(); // Process next
+    }
+  }
+
+  _priorityValue(priority) {
+    const map = { low: 1, normal: 5, high: 10, critical: 20 };
+    return typeof priority === 'number' ? priority : (map[priority] || 5);
+  }
+}
+
+module.exports = { Queue };