voltjs-framework 1.0.0

package/src/utils/excel.js

@@ -0,0 +1,482 @@
+/**
+ * VoltJS Excel Module
+ * 
+ * Import and export Excel files (XLSX, CSV) with zero external dependencies.
+ * Uses native Node.js buffers to read/write Excel format.
+ * 
+ * @example
+ * const { Excel } = require('voltjs');
+ * 
+ * // Export to CSV
+ * const csv = Excel.toCSV([
+ *   { name: 'John', age: 30, email: 'john@test.com' },
+ *   { name: 'Jane', age: 25, email: 'jane@test.com' },
+ * ]);
+ * 
+ * // Import from CSV
+ * const data = Excel.fromCSV(csvString);
+ * 
+ * // Generate XLSX
+ * const buffer = Excel.createXLSX(data, { sheetName: 'Users' });
+ * fs.writeFileSync('users.xlsx', buffer);
+ * 
+ * // Parse XLSX 
+ * const rows = Excel.parseXLSX(buffer);
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+
+class Excel {
+  // ===== CSV OPERATIONS =====
+
+  /** Convert array of objects to CSV string */
+  static toCSV(data, options = {}) {
+    if (!Array.isArray(data) || data.length === 0) return '';
+
+    const delimiter = options.delimiter || ',';
+    const lineBreak = options.lineBreak || '\n';
+    const headers = options.headers || Object.keys(data[0]);
+    const includeHeaders = options.includeHeaders !== false;
+
+    const escapeValue = (val) => {
+      if (val === null || val === undefined) return '';
+      const str = String(val);
+      if (str.includes(delimiter) || str.includes('"') || str.includes('\n') || str.includes('\r')) {
+        return `"${str.replace(/"/g, '""')}"`;
+      }
+      return str;
+    };
+
+    const lines = [];
+    if (includeHeaders) {
+      lines.push(headers.map(escapeValue).join(delimiter));
+    }
+
+    for (const row of data) {
+      lines.push(headers.map(h => escapeValue(row[h])).join(delimiter));
+    }
+
+    return lines.join(lineBreak);
+  }
+
+  /** Parse CSV string to array of objects */
+  static fromCSV(csvString, options = {}) {
+    const delimiter = options.delimiter || ',';
+    const hasHeaders = options.hasHeaders !== false;
+
+    const lines = Excel._parseCSVLines(csvString, delimiter);
+    if (lines.length === 0) return [];
+
+    if (hasHeaders) {
+      const headers = lines[0];
+      return lines.slice(1).map(row => {
+        const obj = {};
+        headers.forEach((h, i) => {
+          obj[h] = row[i] !== undefined ? row[i] : '';
+        });
+        return obj;
+      });
+    }
+
+    return lines;
+  }
+
+  /** Parse CSV with proper quote handling */
+  static _parseCSVLines(text, delimiter = ',') {
+    const lines = [];
+    let current = [];
+    let field = '';
+    let inQuotes = false;
+
+    for (let i = 0; i < text.length; i++) {
+      const ch = text[i];
+      const next = text[i + 1];
+
+      if (inQuotes) {
+        if (ch === '"' && next === '"') {
+          field += '"';
+          i++;
+        } else if (ch === '"') {
+          inQuotes = false;
+        } else {
+          field += ch;
+        }
+      } else {
+        if (ch === '"') {
+          inQuotes = true;
+        } else if (ch === delimiter) {
+          current.push(field.trim());
+          field = '';
+        } else if (ch === '\n' || (ch === '\r' && next === '\n')) {
+          current.push(field.trim());
+          if (current.some(f => f !== '')) lines.push(current);
+          current = [];
+          field = '';
+          if (ch === '\r') i++;
+        } else {
+          field += ch;
+        }
+      }
+    }
+
+    // Last field
+    current.push(field.trim());
+    if (current.some(f => f !== '')) lines.push(current);
+
+    return lines;
+  }
+
+  /** Read CSV file */
+  static readCSV(filePath, options = {}) {
+    const content = fs.readFileSync(filePath, options.encoding || 'utf-8');
+    return Excel.fromCSV(content, options);
+  }
+
+  /** Write CSV file */
+  static writeCSV(filePath, data, options = {}) {
+    const csv = Excel.toCSV(data, options);
+    fs.writeFileSync(filePath, csv, options.encoding || 'utf-8');
+    return filePath;
+  }
+
+  // ===== XLSX OPERATIONS =====
+
+  /** Create a simple XLSX file (ZIP-based XML spreadsheet) */
+  static createXLSX(data, options = {}) {
+    if (!Array.isArray(data) || data.length === 0) {
+      throw new Error('Data must be a non-empty array of objects');
+    }
+
+    const sheetName = options.sheetName || 'Sheet1';
+    const headers = options.headers || Object.keys(data[0]);
+
+    // Build the sheet XML
+    let sheetData = '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n';
+    sheetData += '<worksheet xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main">\n';
+    sheetData += '<sheetData>\n';
+
+    // Header row
+    sheetData += '<row r="1">\n';
+    headers.forEach((h, i) => {
+      const col = Excel._columnLetter(i);
+      sheetData += `<c r="${col}1" t="inlineStr"><is><t>${Excel._escapeXML(String(h))}</t></is></c>\n`;
+    });
+    sheetData += '</row>\n';
+
+    // Data rows
+    data.forEach((row, rowIndex) => {
+      const r = rowIndex + 2;
+      sheetData += `<row r="${r}">\n`;
+      headers.forEach((h, colIndex) => {
+        const col = Excel._columnLetter(colIndex);
+        const val = row[h];
+        if (val === null || val === undefined) {
+          sheetData += `<c r="${col}${r}" t="inlineStr"><is><t></t></is></c>\n`;
+        } else if (typeof val === 'number') {
+          sheetData += `<c r="${col}${r}"><v>${val}</v></c>\n`;
+        } else {
+          sheetData += `<c r="${col}${r}" t="inlineStr"><is><t>${Excel._escapeXML(String(val))}</t></is></c>\n`;
+        }
+      });
+      sheetData += '</row>\n';
+    });
+
+    sheetData += '</sheetData>\n';
+    sheetData += '</worksheet>';
+
+    // Build XLSX (ZIP format with required XML files)
+    const files = {
+      '[Content_Types].xml': Excel._contentTypes(),
+      '_rels/.rels': Excel._rootRels(),
+      'xl/_rels/workbook.xml.rels': Excel._workbookRels(),
+      'xl/workbook.xml': Excel._workbook(sheetName),
+      'xl/worksheets/sheet1.xml': sheetData,
+    };
+
+    return Excel._createZip(files);
+  }
+
+  /** Parse XLSX file to array of objects */
+  static parseXLSX(bufferOrPath) {
+    let buffer;
+    if (typeof bufferOrPath === 'string') {
+      buffer = fs.readFileSync(bufferOrPath);
+    } else {
+      buffer = bufferOrPath;
+    }
+
+    // Extract ZIP entries
+    const entries = Excel._extractZip(buffer);
+
+    // Find the sheet XML
+    const sheetEntry = entries['xl/worksheets/sheet1.xml'] || entries['xl/worksheets/Sheet1.xml'];
+    if (!sheetEntry) {
+      throw new Error('No worksheet found in XLSX file');
+    }
+
+    const sheetXML = sheetEntry.toString('utf-8');
+
+    // Check for shared strings
+    let sharedStrings = [];
+    const sharedStringsEntry = entries['xl/sharedStrings.xml'];
+    if (sharedStringsEntry) {
+      const ssXML = sharedStringsEntry.toString('utf-8');
+      const ssMatches = ssXML.matchAll(/<t[^>]*>([^<]*)<\/t>/g);
+      for (const m of ssMatches) {
+        sharedStrings.push(m[1]);
+      }
+    }
+
+    // Parse rows
+    const rows = [];
+    const rowMatches = sheetXML.matchAll(/<row[^>]*>([\s\S]*?)<\/row>/g);
+
+    for (const rowMatch of rowMatches) {
+      const row = [];
+      const cellMatches = rowMatch[1].matchAll(/<c[^>]*(?:t="([^"]*)")?[^>]*>(?:<(?:is|v)>(?:<t>)?([^<]*)(?:<\/t>)?<\/(?:is|v)>)?<\/c>/g);
+
+      for (const cellMatch of cellMatches) {
+        const type = cellMatch[1];
+        let value = cellMatch[2] || '';
+
+        if (type === 's' && sharedStrings.length > 0) {
+          value = sharedStrings[parseInt(value)] || value;
+        }
+
+        value = Excel._unescapeXML(value);
+        row.push(value);
+      }
+      rows.push(row);
+    }
+
+    if (rows.length === 0) return [];
+
+    // First row as headers
+    const headers = rows[0];
+    return rows.slice(1).map(row => {
+      const obj = {};
+      headers.forEach((h, i) => {
+        obj[h] = row[i] !== undefined ? row[i] : '';
+      });
+      return obj;
+    });
+  }
+
+  /** Write XLSX file */
+  static writeXLSX(filePath, data, options = {}) {
+    const buffer = Excel.createXLSX(data, options);
+    fs.writeFileSync(filePath, buffer);
+    return filePath;
+  }
+
+  // ===== TSV OPERATIONS =====
+
+  /** Convert to TSV (Tab-Separated Values) */
+  static toTSV(data, options = {}) {
+    return Excel.toCSV(data, { ...options, delimiter: '\t' });
+  }
+
+  /** Parse TSV */
+  static fromTSV(tsvString, options = {}) {
+    return Excel.fromCSV(tsvString, { ...options, delimiter: '\t' });
+  }
+
+  // ===== JSON OPERATIONS =====
+
+  /** Convert to formatted JSON */
+  static toJSON(data, pretty = true) {
+    return JSON.stringify(data, null, pretty ? 2 : 0);
+  }
+
+  /** Convert to JSON file */
+  static writeJSON(filePath, data, pretty = true) {
+    fs.writeFileSync(filePath, Excel.toJSON(data, pretty));
+    return filePath;
+  }
+
+  /** Read JSON file */
+  static readJSON(filePath) {
+    return JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  }
+
+  // ===== HELPERS =====
+
+  static _columnLetter(index) {
+    let letter = '';
+    while (index >= 0) {
+      letter = String.fromCharCode(65 + (index % 26)) + letter;
+      index = Math.floor(index / 26) - 1;
+    }
+    return letter;
+  }
+
+  static _escapeXML(str) {
+    return str
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&apos;');
+  }
+
+  static _unescapeXML(str) {
+    return str
+      .replace(/&amp;/g, '&')
+      .replace(/&lt;/g, '<')
+      .replace(/&gt;/g, '>')
+      .replace(/&quot;/g, '"')
+      .replace(/&apos;/g, "'");
+  }
+
+  static _contentTypes() {
+    return '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n' +
+      '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">\n' +
+      '<Default Extension="rels" ContentType="application/vnd.openxmlformats-package.relationships+xml"/>\n' +
+      '<Default Extension="xml" ContentType="application/xml"/>\n' +
+      '<Override PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml"/>\n' +
+      '<Override PartName="/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml"/>\n' +
+      '</Types>';
+  }
+
+  static _rootRels() {
+    return '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n' +
+      '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">\n' +
+      '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>\n' +
+      '</Relationships>';
+  }
+
+  static _workbookRels() {
+    return '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n' +
+      '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">\n' +
+      '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>\n' +
+      '</Relationships>';
+  }
+
+  static _workbook(sheetName) {
+    return '<?xml version="1.0" encoding="UTF-8" standalone="yes"?>\n' +
+      '<workbook xmlns="http://schemas.openxmlformats.org/spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">\n' +
+      '<sheets>\n' +
+      `<sheet name="${sheetName}" sheetId="1" r:id="rId1"/>\n` +
+      '</sheets>\n' +
+      '</workbook>';
+  }
+
+  /** Create a simple ZIP file from an object of {path: content} */
+  static _createZip(files) {
+    // Simple ZIP file creator (PKZIP format)
+    const entries = [];
+    const centralDir = [];
+    let offset = 0;
+
+    for (const [filepath, content] of Object.entries(files)) {
+      const data = Buffer.from(content, 'utf-8');
+      const compressed = zlib.deflateRawSync(data);
+
+      const filenameBuffer = Buffer.from(filepath, 'utf-8');
+
+      // Local file header
+      const localHeader = Buffer.alloc(30);
+      localHeader.writeUInt32LE(0x04034b50, 0);  // Local file header signature
+      localHeader.writeUInt16LE(20, 4);            // Version needed
+      localHeader.writeUInt16LE(0, 6);             // General purpose flag
+      localHeader.writeUInt16LE(8, 8);             // Compression method (deflate)
+      localHeader.writeUInt16LE(0, 10);            // Last mod time
+      localHeader.writeUInt16LE(0, 12);            // Last mod date
+      localHeader.writeUInt32LE(Excel._crc32(data), 14); // CRC-32
+      localHeader.writeUInt32LE(compressed.length, 18);   // Compressed size
+      localHeader.writeUInt32LE(data.length, 22);         // Uncompressed size
+      localHeader.writeUInt16LE(filenameBuffer.length, 26); // Filename length
+
+      const entry = Buffer.concat([localHeader, filenameBuffer, compressed]);
+      entries.push(entry);
+
+      // Central directory header
+      const cdHeader = Buffer.alloc(46);
+      cdHeader.writeUInt32LE(0x02014b50, 0);  // Central directory signature
+      cdHeader.writeUInt16LE(20, 4);            // Version made by
+      cdHeader.writeUInt16LE(20, 6);            // Version needed
+      cdHeader.writeUInt16LE(0, 8);             // General purpose flag
+      cdHeader.writeUInt16LE(8, 10);            // Compression method
+      cdHeader.writeUInt16LE(0, 12);            // Last mod time
+      cdHeader.writeUInt16LE(0, 14);            // Last mod date
+      cdHeader.writeUInt32LE(Excel._crc32(data), 16);
+      cdHeader.writeUInt32LE(compressed.length, 20);
+      cdHeader.writeUInt32LE(data.length, 24);
+      cdHeader.writeUInt16LE(filenameBuffer.length, 28);
+      cdHeader.writeUInt32LE(offset, 42);       // Relative offset
+
+      centralDir.push(Buffer.concat([cdHeader, filenameBuffer]));
+      offset += entry.length;
+    }
+
+    const centralDirBuffer = Buffer.concat(centralDir);
+    const centralDirOffset = offset;
+
+    // End of central directory
+    const eocd = Buffer.alloc(22);
+    eocd.writeUInt32LE(0x06054b50, 0);
+    eocd.writeUInt16LE(Object.keys(files).length, 8);  // Total entries
+    eocd.writeUInt16LE(Object.keys(files).length, 10);
+    eocd.writeUInt32LE(centralDirBuffer.length, 12);
+    eocd.writeUInt32LE(centralDirOffset, 16);
+
+    return Buffer.concat([...entries, centralDirBuffer, eocd]);
+  }
+
+  /** Extract files from a ZIP buffer */
+  static _extractZip(buffer) {
+    const entries = {};
+    let offset = 0;
+
+    while (offset < buffer.length - 4) {
+      const signature = buffer.readUInt32LE(offset);
+
+      if (signature === 0x04034b50) { // Local file header
+        const compressionMethod = buffer.readUInt16LE(offset + 8);
+        const compressedSize = buffer.readUInt32LE(offset + 18);
+        const uncompressedSize = buffer.readUInt32LE(offset + 22);
+        const filenameLen = buffer.readUInt16LE(offset + 26);
+        const extraLen = buffer.readUInt16LE(offset + 28);
+
+        const filename = buffer.slice(offset + 30, offset + 30 + filenameLen).toString('utf-8');
+        const dataStart = offset + 30 + filenameLen + extraLen;
+        const data = buffer.slice(dataStart, dataStart + compressedSize);
+
+        try {
+          if (compressionMethod === 8) {
+            entries[filename] = zlib.inflateRawSync(data);
+          } else {
+            entries[filename] = data;
+          }
+        } catch {
+          entries[filename] = data;
+        }
+
+        offset = dataStart + compressedSize;
+      } else {
+        break;
+      }
+    }
+
+    return entries;
+  }
+
+  /** CRC-32 calculation */
+  static _crc32(data) {
+    let crc = 0xFFFFFFFF;
+    for (let i = 0; i < data.length; i++) {
+      crc ^= data[i];
+      for (let j = 0; j < 8; j++) {
+        if (crc & 1) crc = (crc >>> 1) ^ 0xEDB88320;
+        else crc >>>= 1;
+      }
+    }
+    return (crc ^ 0xFFFFFFFF) >>> 0;
+  }
+}
+
+module.exports = { Excel };