webspresso 0.0.95 → 0.0.97

package/plugins/xlsx/engine.js

@@ -0,0 +1,397 @@
+'use strict';
+
+/**
+ * Webspresso XLSX Core Engine
+ * High-performance Excel spreadsheet generator, parser, and ORM exporter
+ * @module plugins/xlsx/engine
+ */
+
+const ExcelJS = require('exceljs');
+const { PassThrough } = require('stream');
+
+/**
+ * Common formula injection trigger characters
+ * @type {RegExp}
+ */
+const FORMULA_INJECTION_REGEX = /^([=+\-@\t\r])/;
+
+/**
+ * Neutralizes Excel formula injection by escaping dangerous prefixes
+ * @param {*} value
+ * @returns {*}
+ */
+function sanitizeFormula(value) {
+  if (typeof value === 'string' && FORMULA_INJECTION_REGEX.test(value)) {
+    return `'${value}`;
+  }
+  return value;
+}
+
+/**
+ * Converts a 6-character hex color (e.g. '4F46E5' or '#4F46E5') to ARGB
+ * @param {string} hex
+ * @returns {string}
+ */
+function hexToArgb(hex) {
+  if (!hex || typeof hex !== 'string') return 'FF4F46E5';
+  let clean = hex.replace(/^#/, '').trim();
+  if (clean.length === 3) {
+    clean = clean.split('').map((c) => c + c).join('');
+  }
+  if (clean.length === 6) {
+    return `FF${clean.toUpperCase()}`;
+  }
+  if (clean.length === 8) {
+    return clean.toUpperCase();
+  }
+  return 'FF4F46E5';
+}
+
+/**
+ * Automatically calculates optimal column widths based on headers and sample rows
+ * @param {ExcelJS.Worksheet} worksheet
+ * @param {Array<Object>} columns
+ * @param {Array<Object>} rows
+ */
+function applyAutoWidths(worksheet, columns, rows) {
+  if (!columns || !Array.isArray(columns)) return;
+
+  columns.forEach((col, index) => {
+    const colIndex = index + 1;
+    let maxLength = col.header ? String(col.header).length : 10;
+
+    // Sample up to first 100 rows for performance
+    const sampleLimit = Math.min(rows.length, 100);
+    for (let i = 0; i < sampleLimit; i++) {
+      const val = rows[i] ? rows[i][col.key] : '';
+      if (val !== null && val !== undefined) {
+        const strVal = val instanceof Date ? 'YYYY-MM-DD HH:mm:ss' : String(val);
+        if (strVal.length > maxLength) {
+          maxLength = strVal.length;
+        }
+      }
+    }
+
+    const column = worksheet.getColumn(colIndex);
+    column.width = Math.min(Math.max(maxLength + 4, 12), 60);
+  });
+}
+
+/**
+ * Applies styled headers to a worksheet
+ * @param {ExcelJS.Worksheet} worksheet
+ * @param {Object} [style]
+ */
+function applyHeaderStyle(worksheet, style = {}) {
+  const headerRow = worksheet.getRow(1);
+  const bgColor = hexToArgb(style.bg || style.fill || '4F46E5');
+  const textColor = hexToArgb(style.color || style.textColor || 'FFFFFF');
+
+  headerRow.height = style.height || 26;
+  headerRow.eachCell((cell) => {
+    cell.font = {
+      name: style.fontName || 'Segoe UI',
+      size: style.fontSize || 11,
+      bold: style.bold !== false,
+      color: { argb: textColor },
+    };
+    cell.fill = {
+      type: 'pattern',
+      pattern: 'solid',
+      fgColor: { argb: bgColor },
+    };
+    cell.alignment = {
+      vertical: 'middle',
+      horizontal: style.align || 'left',
+      wrapText: false,
+    };
+    cell.border = {
+      top: { style: 'thin', color: { argb: 'FFE5E7EB' } },
+      left: { style: 'thin', color: { argb: 'FFE5E7EB' } },
+      bottom: { style: 'medium', color: { argb: 'FF3730A3' } },
+      right: { style: 'thin', color: { argb: 'FFE5E7EB' } },
+    };
+  });
+}
+
+/**
+ * Generates an Excel XLSX workbook buffer from declarative options
+ * @param {Object} options
+ * @param {string} [options.creator='Webspresso']
+ * @param {string} [options.title]
+ * @param {Date} [options.created]
+ * @param {boolean} [options.sanitizeFormulas=true]
+ * @param {Array<Object>|Object} options.sheets - Sheet configuration(s)
+ * @returns {Promise<Buffer>}
+ */
+async function generate(options = {}) {
+  const workbook = new ExcelJS.Workbook();
+  workbook.creator = options.creator || 'Webspresso';
+  workbook.created = options.created || new Date();
+  if (options.title) workbook.title = options.title;
+
+  const sanitize = options.sanitizeFormulas !== false;
+
+  // Normalize sheets: can be single object or array
+  const rawSheets = options.sheets
+    ? Array.isArray(options.sheets) ? options.sheets : [options.sheets]
+    : [{ name: options.name || 'Sheet1', columns: options.columns, rows: options.rows || options.data || [] }];
+
+  for (let idx = 0; idx < rawSheets.length; idx++) {
+    const sheetConfig = rawSheets[idx];
+    const sheetName = sheetConfig.name || `Sheet${idx + 1}`;
+    const worksheet = workbook.addWorksheet(sheetName, {
+      views: sheetConfig.views || [{ state: 'frozen', xSplit: 0, ySplit: 1 }],
+    });
+
+    const rows = Array.isArray(sheetConfig.rows)
+      ? sheetConfig.rows
+      : Array.isArray(sheetConfig.data)
+        ? sheetConfig.data
+        : [];
+
+    // Derive columns if not explicitly provided
+    let columns = sheetConfig.columns;
+    if (!columns && rows.length > 0 && typeof rows[0] === 'object' && rows[0] !== null) {
+      columns = Object.keys(rows[0]).map((key) => ({
+        header: key,
+        key,
+      }));
+    }
+
+    if (columns && Array.isArray(columns)) {
+      worksheet.columns = columns.map((col) => ({
+        header: col.header || col.name || col.key,
+        key: col.key,
+        width: col.width || 15,
+        style: col.style || {},
+      }));
+
+      // Apply auto-widths if requested (default: true)
+      if (sheetConfig.autoWidth !== false) {
+        applyAutoWidths(worksheet, columns, rows);
+      }
+
+      // Add rows
+      for (const row of rows) {
+        const rowData = {};
+        for (const col of columns) {
+          let val = row ? row[col.key] : '';
+          if (sanitize) {
+            val = sanitizeFormula(val);
+          }
+          rowData[col.key] = val !== undefined ? val : null;
+        }
+        worksheet.addRow(rowData);
+      }
+
+      // Format headers
+      applyHeaderStyle(worksheet, sheetConfig.headerStyle || options.headerStyle);
+
+      // Apply zebra striping or row borders if enabled
+      if (sheetConfig.striped !== false) {
+        worksheet.eachRow((row, rowNumber) => {
+          if (rowNumber === 1) return;
+          row.alignment = { vertical: 'middle' };
+          if (rowNumber % 2 === 0) {
+            row.eachCell((cell) => {
+              if (!cell.fill || cell.fill.type !== 'pattern') {
+                cell.fill = {
+                  type: 'pattern',
+                  pattern: 'solid',
+                  fgColor: { argb: 'FFF9FAFB' },
+                };
+              }
+            });
+          }
+        });
+      }
+    }
+  }
+
+  const buffer = await workbook.xlsx.writeBuffer();
+  return Buffer.from(buffer);
+}
+
+/**
+ * Parses an XLSX buffer or stream into JSON objects
+ * @param {Buffer|import('stream').Readable} input
+ * @param {Object} [options]
+ * @param {string|number} [options.sheet] - Sheet name or 1-based index
+ * @param {number} [options.headerRow=1] - Row index of headers
+ * @param {number} [options.dataStartRow=2] - Row index where data begins
+ * @param {boolean} [options.raw=false] - Return raw cell values without formatting
+ * @param {Function} [options.transformRow] - Custom row transformer
+ * @returns {Promise<Array<Object>|Object.<string, Array<Object>>>}
+ */
+async function parse(input, options = {}) {
+  const workbook = new ExcelJS.Workbook();
+
+  if (Buffer.isBuffer(input)) {
+    await workbook.xlsx.load(input);
+  } else if (input && typeof input.pipe === 'function') {
+    await workbook.xlsx.read(input);
+  } else {
+    throw new Error('parseXlsx requires a valid Buffer or Readable Stream');
+  }
+
+  const headerRowIdx = options.headerRow || 1;
+  const dataStartRowIdx = options.dataStartRow || headerRowIdx + 1;
+  const transformRow = typeof options.transformRow === 'function' ? options.transformRow : null;
+
+  function parseWorksheet(ws) {
+    const headers = [];
+    const headerRow = ws.getRow(headerRowIdx);
+
+    headerRow.eachCell({ includeEmpty: false }, (cell, colNumber) => {
+      let val = cell.value;
+      if (typeof val === 'object' && val !== null) {
+        val = val.text || val.result || String(val);
+      }
+      const headerName = String(val || `col_${colNumber}`).trim();
+      headers[colNumber] = headerName;
+    });
+
+    const rows = [];
+    const rowCount = ws.rowCount;
+
+    for (let r = dataStartRowIdx; r <= rowCount; r++) {
+      const row = ws.getRow(r);
+      if (!row || !row.hasValues) continue;
+
+      const rowObj = {};
+      let hasData = false;
+
+      headers.forEach((header, colNum) => {
+        if (!header) return;
+        const cell = row.getCell(colNum);
+        let cellVal = cell.value;
+
+        if (cellVal && typeof cellVal === 'object') {
+          if (cellVal instanceof Date) {
+            // Keep Date instance or format
+          } else if (cellVal.text !== undefined) {
+            cellVal = cellVal.text;
+          } else if (cellVal.result !== undefined) {
+            cellVal = cellVal.result;
+          }
+        }
+
+        if (cellVal !== null && cellVal !== undefined && cellVal !== '') {
+          hasData = true;
+        }
+
+        rowObj[header] = cellVal !== undefined ? cellVal : null;
+      });
+
+      if (hasData) {
+        rows.push(transformRow ? transformRow(rowObj, rows.length) : rowObj);
+      }
+    }
+
+    return rows;
+  }
+
+  // If specific sheet requested
+  if (options.sheet !== undefined) {
+    let ws;
+    if (typeof options.sheet === 'number') {
+      ws = workbook.getWorksheet(options.sheet);
+    } else {
+      ws = workbook.getWorksheet(String(options.sheet));
+    }
+
+    if (!ws) {
+      throw new Error(`Worksheet "${options.sheet}" not found in XLSX workbook`);
+    }
+
+    return parseWorksheet(ws);
+  }
+
+  // If only 1 sheet exists, return array directly for convenience
+  if (workbook.worksheets.length === 1) {
+    return parseWorksheet(workbook.worksheets[0]);
+  }
+
+  // Multiple sheets: return dictionary keyed by sheet name
+  const result = {};
+  for (const ws of workbook.worksheets) {
+    result[ws.name] = parseWorksheet(ws);
+  }
+  return result;
+}
+
+/**
+ * Automatically exports records from an ORM Repository into an Excel workbook buffer
+ * @param {Object} repository - Model repository from db.getRepository('Model')
+ * @param {Object} [filterOrQuery={}] - Query filters
+ * @param {Object} [options={}] - Export options
+ * @returns {Promise<Buffer>}
+ */
+async function fromModel(repository, filterOrQuery = {}, options = {}) {
+  if (!repository || (typeof repository.find !== 'function' && typeof repository.query !== 'function')) {
+    throw new Error('fromModel requires a valid Webspresso Model Repository');
+  }
+
+  let records;
+  if (typeof filterOrQuery === 'function') {
+    if (typeof repository.query !== 'function') {
+      throw new Error('fromModel query callback requires a repository with query() method');
+    }
+    records = await filterOrQuery(repository.query());
+  } else {
+    records = typeof repository.find === 'function' ? await repository.find(filterOrQuery) : [];
+  }
+
+  const modelName = repository.model?.name || 'Records';
+  const sheetName = options.sheetName || options.name || modelName;
+
+  let columns = options.columns;
+  if (!columns && repository.model?.schema?.shape) {
+    const hidden = new Set(repository.model.hidden || []);
+    columns = Object.keys(repository.model.schema.shape)
+      .filter((col) => !hidden.has(col))
+      .map((col) => ({
+        header: col.charAt(0).toUpperCase() + col.slice(1).replace(/_/g, ' '),
+        key: col,
+      }));
+  }
+
+  return generate({
+    creator: options.creator || 'Webspresso ORM',
+    title: options.title || `${modelName} Export`,
+    sheets: [
+      {
+        name: sheetName,
+        columns,
+        rows: records,
+        headerStyle: options.headerStyle,
+      },
+    ],
+  });
+}
+
+/**
+ * Creates a high-performance streaming workbook writer for massive datasets
+ * @param {import('stream').Writable} outputStream
+ * @param {Object} [options]
+ * @returns {ExcelJS.stream.xlsx.WorkbookWriter}
+ */
+function createStreamWriter(outputStream, options = {}) {
+  return new ExcelJS.stream.xlsx.WorkbookWriter({
+    stream: outputStream,
+    useStyles: options.useStyles !== false,
+    useSharedStrings: options.useSharedStrings || false,
+  });
+}
+
+module.exports = {
+  generate,
+  parse,
+  fromModel,
+  createStreamWriter,
+  sanitizeFormula,
+  applyHeaderStyle,
+  applyAutoWidths,
+  hexToArgb,
+};

package/plugins/xlsx/index.js

@@ -0,0 +1,91 @@
+'use strict';
+
+/**
+ * Webspresso XLSX Plugin
+ * Excel spreadsheet generation, parsing, ORM export, streaming, and res.xlsx() integration
+ * @module plugins/xlsx
+ */
+
+const engine = require('./engine');
+const { createXlsxMiddleware, XLSX_MIME_TYPE } = require('./middleware');
+const { createXlsxServices } = require('./services');
+
+/**
+ * Standalone XLSX Toolkit Singleton
+ */
+const xlsx = {
+  ...engine,
+  MIME_TYPE: XLSX_MIME_TYPE,
+  createMiddleware: createXlsxMiddleware,
+  createServices: createXlsxServices,
+};
+
+/**
+ * XLSX Plugin for Webspresso
+ * @param {Object} [options]
+ * @param {boolean} [options.enabled=true]
+ * @param {boolean} [options.sanitizeFormulas=true] - Prevent Formula Injection attacks
+ * @param {Object} [options.headerStyle] - Default header styling (fill, font, border)
+ * @param {Object} [options.db] - Optional database instance for model export services
+ * @returns {import('../../index').Plugin}
+ */
+function xlsxPlugin(options = {}) {
+  const {
+    enabled = true,
+    sanitizeFormulas = true,
+    headerStyle = { fill: '4F46E5', color: 'FFFFFF', bold: true },
+    db: dbOption,
+  } = options;
+
+  return {
+    name: 'xlsx',
+    version: '1.0.0',
+    description: 'Excel XLSX spreadsheet engine, res.xlsx() response decorator, and ORM export tools',
+    enabled,
+
+    register(ctx) {
+      if (!enabled) return;
+
+      // 1. Expose on PluginContext & global app
+      ctx.xlsx = xlsx;
+      if (ctx.app) {
+        ctx.app.xlsx = xlsx;
+      }
+
+      // 2. Register built-in services (xlsx.generate, xlsx.parse, xlsx.exportModel)
+      if (ctx.app && ctx.app.serviceRegistry) {
+        const db = dbOption ?? ctx.db ?? ctx.app?.get?.('db') ?? null;
+        const services = createXlsxServices({ db, ...options });
+        for (const [name, def] of Object.entries(services)) {
+          if (!ctx.app.serviceRegistry.has(name)) {
+            ctx.app.serviceRegistry.register(name, def);
+          }
+        }
+      }
+
+      // 3. Register named middleware & global decorator
+      const middleware = createXlsxMiddleware({
+        sanitizeFormulas,
+        headerStyle,
+        ...options,
+      });
+
+      if (ctx.middlewares) {
+        ctx.middlewares.xlsx = middleware;
+      }
+
+      if (ctx.app && typeof ctx.app.use === 'function') {
+        ctx.app.use(middleware);
+      }
+    },
+  };
+}
+
+module.exports = {
+  xlsxPlugin,
+  xlsx,
+  createXlsxMiddleware,
+  createXlsxServices,
+  XLSX_MIME_TYPE,
+  ...engine,
+};

package/plugins/xlsx/middleware.js

@@ -0,0 +1,87 @@
+'use strict';
+
+/**
+ * XLSX Express Middleware
+ * Decorates res.xlsx() and req.parseXlsx() helpers
+ * @module plugins/xlsx/middleware
+ */
+
+const { generate, parse, fromModel } = require('./engine');
+
+const XLSX_MIME_TYPE = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
+
+/**
+ * Creates the XLSX middleware
+ * @param {Object} [globalOptions]
+ * @returns {Function}
+ */
+function createXlsxMiddleware(globalOptions = {}) {
+  return (req, res, next) => {
+    // 1. Response Helper: res.xlsx(data, filename, options)
+    res.xlsx = async function (data, filename = 'export.xlsx', options = {}) {
+      try {
+        let buffer;
+
+        if (Buffer.isBuffer(data)) {
+          buffer = data;
+        } else if (data && typeof data.find === 'function' && data.model) {
+          // Repository instance
+          buffer = await fromModel(data, options.filter || options.query || {}, {
+            ...globalOptions,
+            ...options,
+          });
+        } else if (Array.isArray(data)) {
+          buffer = await generate({
+            ...globalOptions,
+            ...options,
+            sheets: [
+              {
+                name: options.sheetName || 'Data',
+                columns: options.columns,
+                rows: data,
+                headerStyle: options.headerStyle,
+              },
+            ],
+          });
+        } else if (data && typeof data === 'object') {
+          buffer = await generate({
+            ...globalOptions,
+            ...options,
+            ...data,
+          });
+        } else {
+          throw new Error('res.xlsx() expects an Array of rows, a sheets object, a Model Repository, or a Buffer');
+        }
+
+        const safeFilename = filename.endsWith('.xlsx') ? filename : `${filename}.xlsx`;
+
+        res.setHeader('Content-Type', XLSX_MIME_TYPE);
+        res.setHeader(
+          'Content-Disposition',
+          `attachment; filename="${encodeURIComponent(safeFilename)}"; filename*=UTF-8''${encodeURIComponent(safeFilename)}`
+        );
+        res.setHeader('Content-Length', buffer.length);
+
+        return res.end(buffer);
+      } catch (err) {
+        return next(err);
+      }
+    };
+
+    // 2. Request Helper: req.parseXlsx(fileOrBuffer, options)
+    req.parseXlsx = async function (fileOrBuffer, options = {}) {
+      const target = fileOrBuffer || req.file?.buffer || req.rawBody || req.body;
+      if (!target) {
+        throw new Error('req.parseXlsx requires a file Buffer or multipart req.file.buffer');
+      }
+      return parse(target, options);
+    };
+
+    next();
+  };
+}
+
+module.exports = {
+  createXlsxMiddleware,
+  XLSX_MIME_TYPE,
+};

package/plugins/xlsx/services.js

@@ -0,0 +1,118 @@
+'use strict';
+
+/**
+ * Built-in XLSX Services
+ * Exposed via ctx.service('xlsx.*') and req.service('xlsx.*')
+ * @module plugins/xlsx/services
+ */
+
+const { z } = require('zod');
+const { generate, parse, fromModel } = require('./engine');
+
+/**
+ * Creates built-in services for the XLSX plugin
+ * @param {Object} [options]
+ * @param {Object} [options.db]
+ * @returns {Object.<string, Object>}
+ */
+function createXlsxServices(options = {}) {
+  return {
+    'xlsx.generate': {
+      schema: z.object({
+        sheets: z.array(
+          z.object({
+            name: z.string().optional(),
+            columns: z.array(z.object({ header: z.string(), key: z.string(), width: z.number().optional() })).optional(),
+            rows: z.array(z.record(z.any())),
+          })
+        ).or(z.object({
+          name: z.string().optional(),
+          columns: z.array(z.object({ header: z.string(), key: z.string(), width: z.number().optional() })).optional(),
+          rows: z.array(z.record(z.any())),
+        })),
+        creator: z.string().optional(),
+        title: z.string().optional(),
+      }),
+      handler: async (input) => {
+        const buffer = await generate(input);
+        return {
+          base64: buffer.toString('base64'),
+          size: buffer.length,
+          mimeType: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+        };
+      },
+    },
+
+    'xlsx.parse': {
+      schema: z.object({
+        base64: z.string().optional(),
+        sheet: z.union([z.string(), z.number()]).optional(),
+        headerRow: z.number().optional(),
+      }),
+      handler: async (input) => {
+        if (!input.base64 && !input.buffer) {
+          throw new Error('xlsx.parse requires base64 string or buffer');
+        }
+        const buffer = input.buffer || Buffer.from(input.base64, 'base64');
+        const data = await parse(buffer, {
+          sheet: input.sheet,
+          headerRow: input.headerRow,
+        });
+
+        const rowCount = Array.isArray(data)
+          ? data.length
+          : Object.values(data).reduce((acc, sheetRows) => acc + sheetRows.length, 0);
+
+        return {
+          data,
+          rowCount,
+        };
+      },
+    },
+
+    'xlsx.exportModel': {
+      schema: z.object({
+        model: z.string().min(1),
+        filter: z.record(z.any()).optional().default({}),
+        columns: z.array(z.string()).optional(),
+        filename: z.string().optional(),
+      }),
+      handler: async (input, ctx) => {
+        const db = ctx.db || options.db;
+        if (!db || typeof db.getRepository !== 'function') {
+          throw new Error('xlsx.exportModel requires an active database connection');
+        }
+
+        const repo = db.getRepository(input.model);
+        if (!repo) {
+          throw new Error(`Model repository "${input.model}" not found`);
+        }
+
+        let customColumns;
+        if (input.columns) {
+          customColumns = input.columns.map((c) => ({
+            header: c.charAt(0).toUpperCase() + c.slice(1).replace(/_/g, ' '),
+            key: c,
+          }));
+        }
+
+        const buffer = await fromModel(repo, input.filter, {
+          columns: customColumns,
+          title: `${input.model} Export`,
+        });
+
+        const filename = input.filename || `${input.model.toLowerCase()}_export.xlsx`;
+
+        return {
+          filename: filename.endsWith('.xlsx') ? filename : `${filename}.xlsx`,
+          base64: buffer.toString('base64'),
+          size: buffer.length,
+        };
+      },
+    },
+  };
+}
+
+module.exports = {
+  createXlsxServices,
+};