voltjs-framework 1.0.0

package/src/utils/mail.js

@@ -0,0 +1,347 @@
+/**
+ * VoltJS Mail Module
+ * 
+ * Send emails via SMTP with zero external dependencies.
+ * Uses raw TCP sockets for SMTP communication.
+ * 
+ * @example
+ * const { Mail } = require('voltjs');
+ * 
+ * const mailer = new Mail({
+ *   host: 'smtp.gmail.com',
+ *   port: 587,
+ *   secure: false,
+ *   user: 'you@gmail.com',
+ *   password: 'your-app-password',
+ *   from: 'My App <you@gmail.com>',
+ * });
+ * 
+ * await mailer.send({
+ *   to: 'user@example.com',
+ *   subject: 'Welcome!',
+ *   html: '<h1>Welcome to our app!</h1>',
+ * });
+ */
+
+'use strict';
+
+const net = require('net');
+const tls = require('tls');
+const crypto = require('crypto');
+
+class Mail {
+  constructor(config = {}) {
+    this._config = {
+      host: config.host || process.env.MAIL_HOST || 'localhost',
+      port: config.port || parseInt(process.env.MAIL_PORT) || 587,
+      secure: config.secure !== undefined ? config.secure : false,
+      user: config.user || process.env.MAIL_USER || null,
+      password: config.password || process.env.MAIL_PASSWORD || null,
+      from: config.from || process.env.MAIL_FROM || 'VoltJS <noreply@voltjs.dev>',
+      timeout: config.timeout || 10000,
+    };
+    this._templates = new Map();
+  }
+
+  /** Send an email */
+  async send(options) {
+    const message = {
+      from: options.from || this._config.from,
+      to: Array.isArray(options.to) ? options.to : [options.to],
+      cc: options.cc ? (Array.isArray(options.cc) ? options.cc : [options.cc]) : [],
+      bcc: options.bcc ? (Array.isArray(options.bcc) ? options.bcc : [options.bcc]) : [],
+      subject: options.subject || '(no subject)',
+      text: options.text || '',
+      html: options.html || '',
+      attachments: options.attachments || [],
+      replyTo: options.replyTo || null,
+      headers: options.headers || {},
+    };
+
+    // If template is specified, render it
+    if (options.template) {
+      const rendered = this._renderTemplate(options.template, options.data || {});
+      if (!message.html) message.html = rendered;
+    }
+
+    return this._sendSMTP(message);
+  }
+
+  /** Send email using a template */
+  async sendTemplate(templateName, to, data = {}, options = {}) {
+    const html = this._renderTemplate(templateName, data);
+    return this.send({
+      to,
+      subject: options.subject || data.subject || templateName,
+      html,
+      ...options,
+    });
+  }
+
+  /** Register an email template */
+  template(name, htmlTemplate) {
+    this._templates.set(name, htmlTemplate);
+    return this;
+  }
+
+  /** Send to multiple recipients */
+  async sendBulk(recipients, options) {
+    const results = [];
+    for (const recipient of recipients) {
+      try {
+        const to = typeof recipient === 'string' ? recipient : recipient.email;
+        const data = typeof recipient === 'object' ? recipient : {};
+        await this.send({ ...options, to, data: { ...options.data, ...data } });
+        results.push({ to, status: 'sent' });
+      } catch (err) {
+        results.push({ to: recipient, status: 'failed', error: err.message });
+      }
+    }
+    return results;
+  }
+
+  /** Verify SMTP connection */
+  async verify() {
+    try {
+      const socket = await this._connect();
+      await this._readResponse(socket);
+      await this._command(socket, `EHLO ${this._config.host}`);
+      socket.destroy();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // ===== SMTP IMPLEMENTATION =====
+
+  async _sendSMTP(message) {
+    const socket = await this._connect();
+
+    try {
+      // Read greeting
+      await this._readResponse(socket);
+
+      // EHLO
+      await this._command(socket, `EHLO ${this._config.host}`);
+
+      // STARTTLS if not already secure
+      if (!this._config.secure && this._config.port !== 465) {
+        try {
+          await this._command(socket, 'STARTTLS');
+          // Upgrade to TLS — in production, you'd upgrade the socket here
+        } catch {
+          // STARTTLS not supported, continue unencrypted
+        }
+      }
+
+      // AUTH
+      if (this._config.user && this._config.password) {
+        await this._command(socket, 'AUTH LOGIN');
+        await this._command(socket, Buffer.from(this._config.user).toString('base64'));
+        await this._command(socket, Buffer.from(this._config.password).toString('base64'));
+      }
+
+      // MAIL FROM
+      const fromAddr = this._extractEmail(message.from);
+      await this._command(socket, `MAIL FROM:<${fromAddr}>`);
+
+      // RCPT TO
+      const allRecipients = [...message.to, ...message.cc, ...message.bcc];
+      for (const to of allRecipients) {
+        const toAddr = this._extractEmail(to);
+        await this._command(socket, `RCPT TO:<${toAddr}>`);
+      }
+
+      // DATA
+      await this._command(socket, 'DATA');
+
+      // Build message
+      const emailData = this._buildMessage(message);
+      await this._command(socket, emailData + '\r\n.');
+
+      // QUIT
+      await this._command(socket, 'QUIT');
+
+      socket.destroy();
+      return { success: true, messageId: this._generateMessageId() };
+    } catch (err) {
+      socket.destroy();
+      throw new Error(`Failed to send email: ${err.message}`);
+    }
+  }
+
+  _connect() {
+    return new Promise((resolve, reject) => {
+      const options = {
+        host: this._config.host,
+        port: this._config.port,
+        timeout: this._config.timeout,
+      };
+
+      const socket = this._config.secure
+        ? tls.connect(options, () => resolve(socket))
+        : net.connect(options, () => resolve(socket));
+
+      socket.on('error', reject);
+      socket.on('timeout', () => {
+        socket.destroy();
+        reject(new Error('SMTP connection timed out'));
+      });
+    });
+  }
+
+  _command(socket, data) {
+    return new Promise((resolve, reject) => {
+      socket.write(data + '\r\n', (err) => {
+        if (err) return reject(err);
+        this._readResponse(socket).then(resolve).catch(reject);
+      });
+    });
+  }
+
+  _readResponse(socket) {
+    return new Promise((resolve, reject) => {
+      const timeout = setTimeout(() => reject(new Error('SMTP response timeout')), this._config.timeout);
+
+      socket.once('data', (data) => {
+        clearTimeout(timeout);
+        const response = data.toString();
+        const code = parseInt(response.substring(0, 3));
+        if (code >= 400) {
+          reject(new Error(`SMTP error ${code}: ${response}`));
+        } else {
+          resolve(response);
+        }
+      });
+    });
+  }
+
+  _buildMessage(message) {
+    const boundary = `----VoltJS_${crypto.randomBytes(16).toString('hex')}`;
+    const messageId = this._generateMessageId();
+
+    let msg = '';
+    msg += `Message-ID: <${messageId}>\r\n`;
+    msg += `Date: ${new Date().toUTCString()}\r\n`;
+    msg += `From: ${message.from}\r\n`;
+    msg += `To: ${message.to.join(', ')}\r\n`;
+    if (message.cc.length > 0) msg += `Cc: ${message.cc.join(', ')}\r\n`;
+    msg += `Subject: ${this._encodeSubject(message.subject)}\r\n`;
+    if (message.replyTo) msg += `Reply-To: ${message.replyTo}\r\n`;
+    msg += 'MIME-Version: 1.0\r\n';
+    msg += `X-Mailer: VoltJS/1.0\r\n`;
+
+    // Custom headers
+    for (const [key, value] of Object.entries(message.headers)) {
+      msg += `${key}: ${value}\r\n`;
+    }
+
+    if (message.attachments.length > 0) {
+      msg += `Content-Type: multipart/mixed; boundary="${boundary}"\r\n\r\n`;
+
+      // Body part
+      msg += `--${boundary}\r\n`;
+      if (message.html) {
+        msg += 'Content-Type: text/html; charset=UTF-8\r\n\r\n';
+        msg += message.html;
+      } else {
+        msg += 'Content-Type: text/plain; charset=UTF-8\r\n\r\n';
+        msg += message.text;
+      }
+      msg += '\r\n';
+
+      // Attachments
+      for (const att of message.attachments) {
+        msg += `--${boundary}\r\n`;
+        msg += `Content-Type: ${att.type || 'application/octet-stream'}; name="${att.name}"\r\n`;
+        msg += `Content-Disposition: attachment; filename="${att.name}"\r\n`;
+        msg += 'Content-Transfer-Encoding: base64\r\n\r\n';
+        msg += (att.data instanceof Buffer ? att.data : Buffer.from(att.data)).toString('base64');
+        msg += '\r\n';
+      }
+      msg += `--${boundary}--`;
+    } else if (message.html) {
+      msg += 'Content-Type: text/html; charset=UTF-8\r\n\r\n';
+      msg += message.html;
+    } else {
+      msg += 'Content-Type: text/plain; charset=UTF-8\r\n\r\n';
+      msg += message.text;
+    }
+
+    return msg;
+  }
+
+  _extractEmail(str) {
+    const match = String(str).match(/<(.+?)>/);
+    return match ? match[1] : str.trim();
+  }
+
+  _encodeSubject(subject) {
+    // Encode non-ASCII subjects
+    if (/[^\x00-\x7F]/.test(subject)) {
+      return `=?UTF-8?B?${Buffer.from(subject).toString('base64')}?=`;
+    }
+    return subject;
+  }
+
+  _generateMessageId() {
+    return `${Date.now()}.${crypto.randomBytes(8).toString('hex')}@voltjs.dev`;
+  }
+
+  _renderTemplate(name, data) {
+    let template = this._templates.get(name);
+    if (!template) {
+      throw new Error(`Email template "${name}" not found`);
+    }
+
+    // Simple template rendering: {{variable}}
+    return template.replace(/\{\{\s*(.+?)\s*\}\}/g, (_, key) => {
+      const keys = key.split('.');
+      let value = data;
+      for (const k of keys) {
+        value = value?.[k];
+      }
+      return value !== undefined ? String(value) : '';
+    });
+  }
+
+  // ===== STATIC HELPERS =====
+
+  /** Quick send without instantiation */
+  static async quickSend(config, options) {
+    const mailer = new Mail(config);
+    return mailer.send(options);
+  }
+
+  /** Create a beautiful HTML email from a simple template */
+  static htmlTemplate(title, body, options = {}) {
+    const primaryColor = options.primaryColor || '#667eea';
+    const footerText = options.footer || 'Sent with VoltJS';
+
+    return `
+<!DOCTYPE html>
+<html>
+<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"></head>
+<body style="margin:0;padding:0;background:#f4f4f7;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif;">
+  <table width="100%" cellpadding="0" cellspacing="0" style="background:#f4f4f7;padding:40px 0;">
+    <tr><td align="center">
+      <table width="600" cellpadding="0" cellspacing="0" style="background:#ffffff;border-radius:8px;overflow:hidden;box-shadow:0 2px 8px rgba(0,0,0,0.08);">
+        <tr><td style="background:${primaryColor};padding:30px;text-align:center;">
+          <h1 style="margin:0;color:#ffffff;font-size:24px;">${title}</h1>
+        </td></tr>
+        <tr><td style="padding:30px;color:#333;font-size:16px;line-height:1.6;">
+          ${body}
+        </td></tr>
+        <tr><td style="padding:20px 30px;text-align:center;color:#888;font-size:12px;border-top:1px solid #eee;">
+          ${footerText}
+        </td></tr>
+      </table>
+    </td></tr>
+  </table>
+</body>
+</html>`;
+  }
+}
+
+module.exports = { Mail };

package/src/utils/paginator.js

@@ -0,0 +1,179 @@
+/**
+ * VoltJS Paginator
+ * 
+ * Pagination helper for database results and arrays.
+ * 
+ * @example
+ * const { Paginator } = require('voltjs');
+ * 
+ * const result = Paginator.paginate(allItems, { page: 2, perPage: 20 });
+ * // {
+ * //   data: [...],
+ * //   meta: { page: 2, perPage: 20, total: 150, totalPages: 8, hasNext: true, hasPrev: true }
+ * // }
+ * 
+ * // As middleware:
+ * app.get('/users', async (req, res) => {
+ *   const page = Paginator.fromRequest(req);
+ *   const users = await User.paginate(page.page, page.perPage);
+ *   res.json(users);
+ * });
+ */
+
+'use strict';
+
+class Paginator {
+  /** Paginate an array of items */
+  static paginate(items, options = {}) {
+    const page = Math.max(1, parseInt(options.page) || 1);
+    const perPage = Math.min(Math.max(1, parseInt(options.perPage) || 20), options.maxPerPage || 100);
+    const total = items.length;
+    const totalPages = Math.ceil(total / perPage);
+    const offset = (page - 1) * perPage;
+
+    const data = items.slice(offset, offset + perPage);
+
+    return {
+      data,
+      meta: {
+        page,
+        perPage,
+        total,
+        totalPages,
+        from: total > 0 ? offset + 1 : 0,
+        to: Math.min(offset + perPage, total),
+        hasNext: page < totalPages,
+        hasPrev: page > 1,
+        nextPage: page < totalPages ? page + 1 : null,
+        prevPage: page > 1 ? page - 1 : null,
+      },
+    };
+  }
+
+  /** Create pagination from pre-sliced data (database query) */
+  static fromQuery(data, total, options = {}) {
+    const page = Math.max(1, parseInt(options.page) || 1);
+    const perPage = Math.max(1, parseInt(options.perPage) || 20);
+    const totalPages = Math.ceil(total / perPage);
+    const offset = (page - 1) * perPage;
+
+    return {
+      data,
+      meta: {
+        page,
+        perPage,
+        total,
+        totalPages,
+        from: total > 0 ? offset + 1 : 0,
+        to: Math.min(offset + perPage, total),
+        hasNext: page < totalPages,
+        hasPrev: page > 1,
+        nextPage: page < totalPages ? page + 1 : null,
+        prevPage: page > 1 ? page - 1 : null,
+      },
+    };
+  }
+
+  /** Extract pagination params from request */
+  static fromRequest(req, defaults = {}) {
+    const query = req.query || {};
+    return {
+      page: parseInt(query.page) || defaults.page || 1,
+      perPage: Math.min(
+        parseInt(query.per_page || query.perPage || query.limit) || defaults.perPage || 20,
+        defaults.maxPerPage || 100
+      ),
+      sort: query.sort || defaults.sort || null,
+      order: (query.order || defaults.order || 'asc').toLowerCase(),
+    };
+  }
+
+  /** Generate SQL LIMIT/OFFSET clause */
+  static sql(options = {}) {
+    const page = Math.max(1, parseInt(options.page) || 1);
+    const perPage = Math.max(1, parseInt(options.perPage) || 20);
+    const offset = (page - 1) * perPage;
+    return { limit: perPage, offset, sql: `LIMIT ${perPage} OFFSET ${offset}` };
+  }
+
+  /** Generate pagination links (for API responses) */
+  static links(baseURL, meta) {
+    const links = {};
+    const separator = baseURL.includes('?') ? '&' : '?';
+
+    links.first = `${baseURL}${separator}page=1&per_page=${meta.perPage}`;
+    links.last = `${baseURL}${separator}page=${meta.totalPages}&per_page=${meta.perPage}`;
+
+    if (meta.hasNext) {
+      links.next = `${baseURL}${separator}page=${meta.nextPage}&per_page=${meta.perPage}`;
+    }
+    if (meta.hasPrev) {
+      links.prev = `${baseURL}${separator}page=${meta.prevPage}&per_page=${meta.perPage}`;
+    }
+
+    return links;
+  }
+
+  /** Generate page numbers for UI rendering */
+  static pageNumbers(currentPage, totalPages, maxVisible = 7) {
+    const pages = [];
+    
+    if (totalPages <= maxVisible) {
+      for (let i = 1; i <= totalPages; i++) pages.push(i);
+      return pages;
+    }
+
+    const half = Math.floor(maxVisible / 2);
+    let start = Math.max(1, currentPage - half);
+    let end = Math.min(totalPages, start + maxVisible - 1);
+    
+    if (end - start < maxVisible - 1) {
+      start = Math.max(1, end - maxVisible + 1);
+    }
+
+    if (start > 1) {
+      pages.push(1);
+      if (start > 2) pages.push('...');
+    }
+
+    for (let i = start; i <= end; i++) pages.push(i);
+
+    if (end < totalPages) {
+      if (end < totalPages - 1) pages.push('...');
+      pages.push(totalPages);
+    }
+
+    return pages;
+  }
+
+  /** Cursor-based pagination */
+  static cursorPaginate(items, options = {}) {
+    const perPage = Math.max(1, parseInt(options.perPage) || 20);
+    const cursor = options.cursor || null;
+    const cursorField = options.cursorField || 'id';
+
+    let filtered = items;
+    if (cursor) {
+      const cursorIndex = items.findIndex(item => String(item[cursorField]) === String(cursor));
+      if (cursorIndex >= 0) {
+        filtered = items.slice(cursorIndex + 1);
+      }
+    }
+
+    const data = filtered.slice(0, perPage);
+    const hasMore = filtered.length > perPage;
+    const nextCursor = data.length > 0 ? data[data.length - 1][cursorField] : null;
+
+    return {
+      data,
+      meta: {
+        perPage,
+        hasMore,
+        nextCursor: hasMore ? nextCursor : null,
+        prevCursor: cursor,
+      },
+    };
+  }
+}
+
+module.exports = { Paginator };