@dipanshuhandoo/excelio 0.0.0-stage → 1.0.0

package/dist/cjs/index.cjs

@@ -0,0 +1,584 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.js
+var src_exports = {};
+__export(src_exports, {
+  ExcelIoError: () => ExcelIoError,
+  default: () => src_default,
+  excelio: () => excelio
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/writer.js
+var import_node_stream = require("node:stream");
+var import_node_fs = require("node:fs");
+var import_exceljs = __toESM(require("exceljs"), 1);
+
+// src/errors.js
+var ExcelIoError = class extends Error {
+  constructor(message, { code = "IO_ERROR", cause, details } = {}) {
+    super(message);
+    this.name = "ExcelIoError";
+    this.code = code;
+    if (cause !== void 0) this.cause = cause;
+    if (details !== void 0) this.details = details;
+  }
+};
+
+// src/columns.js
+function resolveColumns(declaredColumns, data) {
+  if (Array.isArray(declaredColumns) && declaredColumns.length) {
+    return declaredColumns.map(normaliseColumn);
+  }
+  if (!data?.length) return [];
+  const firstRow = data[0] || {};
+  return Object.keys(firstRow).map((k) => normaliseColumn({ key: k }));
+}
+function normaliseColumn(c) {
+  if (!c || typeof c !== "object" || !c.key) {
+    throw new Error(`excelio: column entry must have a "key" property; got ${JSON.stringify(c)}`);
+  }
+  return {
+    key: String(c.key),
+    header: c.header ?? c.key,
+    type: c.type ?? null,
+    format: c.format ?? defaultFormatFor(c.type),
+    width: c.width ?? 15
+  };
+}
+function defaultFormatFor(type) {
+  switch (type) {
+    case "date":
+      return "yyyy-mm-dd hh:mm:ss";
+    case "number":
+      return null;
+    default:
+      return null;
+  }
+}
+
+// src/coerce.js
+var ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;
+function valueForWrite(value, columnType) {
+  if (value === null || value === void 0) return null;
+  if (columnType === "date") {
+    if (value instanceof Date) return value;
+    if (typeof value === "number") return new Date(value);
+    if (typeof value === "string" && ISO_DATE_PATTERN.test(value)) {
+      const d = new Date(value);
+      return isNaN(d.getTime()) ? value : d;
+    }
+    return value;
+  }
+  if (columnType === "number" && typeof value === "string" && value !== "") {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : value;
+  }
+  if (columnType === "boolean") {
+    if (typeof value === "boolean") return value;
+    if (value === "true" || value === 1) return true;
+    if (value === "false" || value === 0) return false;
+  }
+  return value;
+}
+function valueForRead(cell, { nullForBlank = true, trimStrings = true, dateFormat = "iso" } = {}) {
+  if (cell === void 0 || cell === null) return nullForBlank ? null : "";
+  const raw = cell && typeof cell === "object" && "value" in cell ? cell.value : cell;
+  if (raw === null || raw === void 0 || raw === "") return nullForBlank ? null : "";
+  if (raw instanceof Date) return formatDate(raw, dateFormat);
+  if (typeof raw === "object" && raw.text !== void 0 && raw.hyperlink !== void 0) {
+    return trimStrings ? String(raw.text).trim() : String(raw.text);
+  }
+  if (typeof raw === "object" && Array.isArray(raw.richText)) {
+    const joined = raw.richText.map((r) => r.text).join("");
+    return trimStrings ? joined.trim() : joined;
+  }
+  if (typeof raw === "object" && raw.formula !== void 0) {
+    return raw.result !== void 0 ? raw.result : null;
+  }
+  if (typeof raw === "object" && raw.error !== void 0) return null;
+  if (typeof raw === "string") return trimStrings ? raw.trim() : raw;
+  return raw;
+}
+function formatDate(d, fmt) {
+  switch (fmt) {
+    case "date":
+      return d;
+    case "epoch":
+      return d.getTime();
+    case "iso":
+    default:
+      return d.toISOString();
+  }
+}
+
+// src/writer.js
+var DEFAULT_BATCH = 5e3;
+var SHEET_NAME_MAX = 31;
+async function writeSpec(spec, options = {}) {
+  validateSpec(spec);
+  const { to } = options;
+  if (to !== void 0 && spec.length > 1) {
+    throw new ExcelIoError(
+      `Multi-workbook output requires omitting "to" \u2014 caller writes each buffer itself.`,
+      { code: "INVALID_SPEC" }
+    );
+  }
+  if (to !== void 0) {
+    await writeOneWorkbook(spec[0], 0, to, options);
+    return to;
+  }
+  const buffers = [];
+  for (let wbIndex = 0; wbIndex < spec.length; wbIndex++) {
+    const buf = await writeOneWorkbookToBuffer(spec[wbIndex], wbIndex, options);
+    buffers.push(buf);
+  }
+  return buffers.length === 1 ? buffers[0] : buffers;
+}
+function writeSpecStream(spec, options = {}) {
+  validateSpec(spec);
+  const passthrough = new import_node_stream.PassThrough();
+  writeOneWorkbook(spec[0], 0, passthrough, options).catch((err) => passthrough.destroy(err));
+  return passthrough;
+}
+async function writeOneWorkbookToBuffer(workbookSpec, wbIndex, options) {
+  const chunks = [];
+  const collector = new import_node_stream.PassThrough();
+  collector.on("data", (chunk) => chunks.push(chunk));
+  await writeOneWorkbook(workbookSpec, wbIndex, collector, options);
+  return Buffer.concat(chunks);
+}
+async function writeOneWorkbook(workbookSpec, wbIndex, target, options) {
+  const { signal, onProgress, beforeWrite, batchSize = DEFAULT_BATCH, logger } = options;
+  const sink = resolveSink(target);
+  const wb = new import_exceljs.default.stream.xlsx.WorkbookWriter({
+    stream: sink.writable,
+    useStyles: true,
+    useSharedStrings: true
+  });
+  applyWorkbookProperties(wb, workbookSpec.properties);
+  const usedNames = /* @__PURE__ */ new Set();
+  const sheets = workbookSpec.sheets || [];
+  let totalRows = sheets.reduce((n, s) => n + (s.data?.length || 0), 0);
+  let rowsProcessed = 0;
+  for (let sIndex = 0; sIndex < sheets.length; sIndex++) {
+    if (signal?.aborted) throw new ExcelIoError("Aborted", { code: "ABORTED" });
+    const sheetSpec = sheets[sIndex];
+    const sheetName = sanitiseSheetName(sheetSpec.sheet || `Sheet ${sIndex + 1}`, usedNames, logger);
+    const wsOptions = {};
+    if (sheetSpec.styling?.freezeHeader) {
+      wsOptions.views = [{ state: "frozen", ySplit: 1 }];
+    }
+    const ws = wb.addWorksheet(sheetName, wsOptions);
+    const cols = resolveColumns(sheetSpec.columns, sheetSpec.data);
+    if (cols.length) {
+      ws.columns = cols.map((c) => ({
+        key: c.key,
+        header: c.header,
+        width: c.width,
+        style: c.format ? { numFmt: c.format } : void 0
+      }));
+    }
+    applyStylingPostColumns(ws, sheetSpec.styling, cols.length);
+    const data = sheetSpec.data || [];
+    for (let i = 0; i < data.length; i++) {
+      if (signal?.aborted) throw new ExcelIoError("Aborted", { code: "ABORTED" });
+      let row = data[i];
+      if (beforeWrite) {
+        row = beforeWrite(row, {
+          workbookIndex: wbIndex,
+          workbookName: workbookSpec.workbook,
+          sheetIndex: sIndex,
+          sheetName,
+          rowNumber: i + 2
+          // header is row 1
+        }) ?? row;
+      }
+      const rowValues = cols.length ? cols.reduce((acc, c) => {
+        acc[c.key] = valueForWrite(row[c.key], c.type);
+        return acc;
+      }, {}) : row;
+      ws.addRow(rowValues).commit();
+      rowsProcessed++;
+      if (onProgress && rowsProcessed % batchSize === 0) {
+        onProgress({ phase: "write", workbookIndex: wbIndex, sheetIndex: sIndex, rowsProcessed, totalRows });
+      }
+    }
+    ws.commit();
+  }
+  await wb.commit();
+  if (sink.cleanup) await sink.cleanup();
+  if (onProgress) {
+    onProgress({ phase: "write", workbookIndex: wbIndex, sheetIndex: sheets.length - 1, rowsProcessed, totalRows });
+  }
+}
+function resolveSink(target) {
+  if (typeof target === "string") {
+    const fileStream = (0, import_node_fs.createWriteStream)(target);
+    const closed = new Promise((resolve, reject) => {
+      fileStream.once("finish", resolve);
+      fileStream.once("error", reject);
+    });
+    return { writable: fileStream, cleanup: () => closed };
+  }
+  if (target && typeof target.write === "function") {
+    return { writable: target, cleanup: null };
+  }
+  throw new ExcelIoError(`Invalid write target \u2014 expected file path or writable stream`, { code: "INVALID_SPEC" });
+}
+function applyWorkbookProperties(wb, props) {
+  if (!props) return;
+  if (props.author) wb.creator = props.author;
+  if (props.created) wb.created = props.created instanceof Date ? props.created : new Date(props.created);
+  if (props.modified) wb.modified = props.modified instanceof Date ? props.modified : new Date(props.modified);
+  if (props.company) wb.company = props.company;
+  if (props.title) wb.title = props.title;
+}
+function applyStylingPostColumns(ws, styling, colCount) {
+  if (!styling) return;
+  if (styling.headerBold) {
+    ws.getRow(1).font = { bold: true };
+  }
+  if (styling.autoFilter && colCount > 0) {
+    ws.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: colCount } };
+  }
+}
+var FORBIDDEN_SHEET_CHARS = /[\\/?*[\]:]/g;
+function sanitiseSheetName(raw, used, logger) {
+  let name = String(raw).replace(FORBIDDEN_SHEET_CHARS, "_");
+  if (name.length > SHEET_NAME_MAX) {
+    if (logger?.warn) logger.warn(`excelio: sheet name "${raw}" truncated to ${SHEET_NAME_MAX} chars`);
+    name = name.slice(0, SHEET_NAME_MAX);
+  }
+  if (!used.has(name)) {
+    used.add(name);
+    return name;
+  }
+  let i = 2;
+  while (true) {
+    const suffix = ` (${i})`;
+    const candidate = (name.length + suffix.length > SHEET_NAME_MAX ? name.slice(0, SHEET_NAME_MAX - suffix.length) : name) + suffix;
+    if (!used.has(candidate)) {
+      used.add(candidate);
+      return candidate;
+    }
+    i++;
+  }
+}
+function validateSpec(spec) {
+  if (!Array.isArray(spec) || spec.length === 0) {
+    throw new ExcelIoError("Spec must be a non-empty array of workbooks", { code: "INVALID_SPEC" });
+  }
+  for (const wb of spec) {
+    if (!wb || typeof wb !== "object") {
+      throw new ExcelIoError("Workbook entries must be objects", { code: "INVALID_SPEC" });
+    }
+    if (!Array.isArray(wb.sheets) || wb.sheets.length === 0) {
+      throw new ExcelIoError("Workbook must have at least one sheet", { code: "INVALID_SPEC" });
+    }
+  }
+}
+
+// src/reader.js
+var import_node_buffer = require("node:buffer");
+var import_exceljs2 = __toESM(require("exceljs"), 1);
+var DEFAULT_BATCH2 = 5e3;
+async function readSource(input, options = {}) {
+  const startedAt = Date.now();
+  const stats = { totalRows: 0, totalSheets: 0, durationMs: 0 };
+  const errors = [];
+  const {
+    headerRow = 1,
+    nullForBlank = true,
+    trimStrings = true,
+    dateFormat = "iso",
+    validateRow,
+    afterRead,
+    onRowError = "collect",
+    batchSize = DEFAULT_BATCH2,
+    onProgress,
+    signal
+  } = options;
+  const wb = new import_exceljs2.default.Workbook();
+  try {
+    if (import_node_buffer.Buffer.isBuffer(input)) {
+      await wb.xlsx.load(input);
+    } else if (input instanceof Uint8Array) {
+      await wb.xlsx.load(import_node_buffer.Buffer.from(input.buffer, input.byteOffset, input.byteLength));
+    } else if (typeof input === "string") {
+      await wb.xlsx.readFile(input);
+    } else if (input && typeof input.pipe === "function") {
+      await wb.xlsx.read(input);
+    } else {
+      throw new ExcelIoError("Invalid input \u2014 expected Buffer, file path, or readable stream", { code: "INVALID_SPEC" });
+    }
+  } catch (err) {
+    if (err instanceof ExcelIoError) throw err;
+    throw new ExcelIoError(`Failed to parse workbook: ${err.message}`, { code: "IO_ERROR", cause: err });
+  }
+  const sheets = [];
+  for (let s = 0; s < wb.worksheets.length; s++) {
+    if (signal?.aborted) throw new ExcelIoError("Aborted", { code: "ABORTED" });
+    const ws = wb.worksheets[s];
+    stats.totalSheets++;
+    const sheetMeta = { sheet: ws.name, columns: [], data: [] };
+    let columnKeys = null;
+    ws.eachRow({ includeEmpty: false }, (row, rowNumber) => {
+      if (rowNumber === headerRow) {
+        columnKeys = readHeaderRow(row);
+        sheetMeta.columns = columnKeys.filter(Boolean).map((k) => ({ key: k, header: k }));
+        return;
+      }
+      if (rowNumber < headerRow || !columnKeys) return;
+      if (signal?.aborted) throw new ExcelIoError("Aborted", { code: "ABORTED" });
+      const obj = {};
+      let isEmpty = true;
+      for (let i = 0; i < columnKeys.length; i++) {
+        const key = columnKeys[i];
+        if (!key) continue;
+        const cell = row.getCell(i + 1);
+        const v = valueForRead(cell, { nullForBlank, trimStrings, dateFormat });
+        if (v !== null && v !== "" && v !== void 0) isEmpty = false;
+        obj[key] = v;
+      }
+      if (isEmpty) return;
+      const ctx = {
+        workbookIndex: 0,
+        workbookName: void 0,
+        sheetIndex: s,
+        sheetName: ws.name,
+        rowNumber
+      };
+      let outRow = obj;
+      if (afterRead) {
+        try {
+          outRow = afterRead(obj, ctx) ?? obj;
+        } catch (err) {
+          const e = mkRowError(ctx, "TRANSFORM_ERROR", err.message);
+          if (onRowError === "fail") throw new ExcelIoError(e.message, { code: "ROW_VALIDATION", details: e });
+          errors.push(e);
+          return;
+        }
+      }
+      if (validateRow) {
+        const issue = validateRow(outRow, ctx);
+        if (issue) {
+          const e = mkRowError(ctx, issue.code || "VALIDATION_FAILED", issue.message, issue.column);
+          if (onRowError === "fail") throw new ExcelIoError(e.message, { code: "ROW_VALIDATION", details: e });
+          errors.push(e);
+          return;
+        }
+      }
+      sheetMeta.data.push(outRow);
+      stats.totalRows++;
+      if (onProgress && stats.totalRows % batchSize === 0) {
+        onProgress({ phase: "read", sheetName: ws.name, rowsProcessed: stats.totalRows });
+      }
+    });
+    sheets.push(sheetMeta);
+  }
+  stats.durationMs = Date.now() - startedAt;
+  return {
+    ok: errors.length === 0,
+    data: [{ workbook: void 0, sheets }],
+    errors,
+    stats
+  };
+}
+function readHeaderRow(row) {
+  const headers = [];
+  const values = row.values;
+  if (!Array.isArray(values)) return headers;
+  for (let i = 1; i < values.length; i++) {
+    const v = values[i];
+    headers.push(v == null ? null : String(v).trim());
+  }
+  return headers;
+}
+function mkRowError(ctx, code, message, column) {
+  return {
+    workbook: ctx.workbookIndex,
+    sheet: ctx.sheetName,
+    row: ctx.rowNumber,
+    column: column ?? null,
+    code,
+    message
+  };
+}
+
+// src/workerPool.js
+var import_node_worker_threads = require("node:worker_threads");
+var import_node_url = require("node:url");
+var import_node_buffer2 = require("node:buffer");
+var import_node_path = __toESM(require("node:path"), 1);
+var import_node_fs2 = require("node:fs");
+var DEFAULT_THRESHOLD = { rows: 5e4, bytes: 10 * 1024 * 1024 };
+var moduleDirectory = typeof __dirname !== "undefined" ? __dirname : import_node_path.default.dirname((0, import_node_url.fileURLToPath)(void 0));
+var workerExtension = true ? ".cjs" : ".js";
+var WORKER_PATHS = {
+  write: import_node_path.default.join(moduleDirectory, "workers", `writer.worker${workerExtension}`),
+  read: import_node_path.default.join(moduleDirectory, "workers", `reader.worker${workerExtension}`)
+};
+async function maybeUseWorker(op, payload, options, inlineFn) {
+  const decision = decideMode(op, payload, options);
+  if (decision.mode === "inline") return inlineFn();
+  return runInWorker(op, payload, sanitiseOptions(options));
+}
+function decideMode(op, payload, options) {
+  const useWorker = options.useWorker ?? "auto";
+  if (op === "read" && payload && typeof payload.pipe === "function") {
+    return { mode: "inline", reason: "stream input" };
+  }
+  if (hasHook(options)) return { mode: "inline", reason: "hooks present" };
+  if (useWorker === false) return { mode: "inline", reason: "disabled" };
+  if (useWorker === true) return { mode: "worker", reason: "forced" };
+  const threshold = { ...DEFAULT_THRESHOLD, ...options.workerThreshold || {} };
+  if (op === "write") {
+    const totalRows = estimateRows(payload);
+    if (totalRows >= threshold.rows) return { mode: "worker", reason: `rows ${totalRows} \u2265 ${threshold.rows}` };
+    return { mode: "inline", reason: "below threshold" };
+  }
+  if (op === "read") {
+    const bytes = estimateBytes(payload);
+    if (bytes !== null && bytes >= threshold.bytes) return { mode: "worker", reason: `bytes ${bytes} \u2265 ${threshold.bytes}` };
+    return { mode: "inline", reason: "below threshold or unknown size" };
+  }
+  return { mode: "inline", reason: "unknown op" };
+}
+function hasHook(options) {
+  return Boolean(
+    options.validateRow || options.beforeWrite || options.afterRead || options.onProgress || options.logger || options.signal || // streams can't cross thread boundaries via postMessage either
+    options.to && typeof options.to !== "string"
+  );
+}
+function estimateRows(spec) {
+  if (!Array.isArray(spec)) return 0;
+  let n = 0;
+  for (const wb of spec) {
+    for (const sheet of wb?.sheets || []) {
+      n += sheet.data?.length || 0;
+    }
+  }
+  return n;
+}
+function estimateBytes(input) {
+  if (typeof input === "string") {
+    try {
+      return (0, import_node_fs2.statSync)(input).size;
+    } catch {
+      return null;
+    }
+  }
+  if (import_node_buffer2.Buffer.isBuffer(input)) return input.length;
+  return null;
+}
+function sanitiseOptions(options) {
+  const { validateRow, beforeWrite, afterRead, onProgress, signal, logger, to, ...rest } = options;
+  void validateRow;
+  void beforeWrite;
+  void afterRead;
+  void onProgress;
+  void signal;
+  void logger;
+  return { ...rest, ...typeof to === "string" ? { to } : {} };
+}
+function runInWorker(op, payload, options) {
+  return new Promise((resolve, reject) => {
+    const workerPath = WORKER_PATHS[op];
+    if (!workerPath) {
+      reject(new ExcelIoError(`No worker for op "${op}"`, { code: "WORKER_ERROR" }));
+      return;
+    }
+    let worker;
+    try {
+      worker = new import_node_worker_threads.Worker(workerPath, { workerData: { op, payload, options } });
+    } catch (err) {
+      reject(new ExcelIoError(err.message, { code: "WORKER_ERROR", cause: err }));
+      return;
+    }
+    let settled = false;
+    worker.once("message", (msg) => {
+      settled = true;
+      void worker.terminate().catch(() => {
+      });
+      if (msg.ok) {
+        const result = op === "write" && options.to === void 0 ? Array.isArray(msg.result) ? msg.result.map((value) => import_node_buffer2.Buffer.from(value)) : import_node_buffer2.Buffer.from(msg.result) : msg.result;
+        resolve(result);
+      } else reject(new ExcelIoError(msg.error?.message || "Worker error", {
+        code: msg.error?.code || "WORKER_ERROR",
+        cause: msg.error,
+        details: msg.error?.details
+      }));
+    });
+    worker.once("error", (err) => {
+      settled = true;
+      void worker.terminate().catch(() => {
+      });
+      reject(new ExcelIoError(err.message, { code: "WORKER_ERROR", cause: err }));
+    });
+    worker.once("exit", (code) => {
+      if (!settled) {
+        reject(new ExcelIoError(`Worker exited without a result (code ${code})`, { code: "WORKER_ERROR" }));
+      }
+    });
+  });
+}
+
+// src/index.js
+var excelio = {
+  /**
+   * Write one or more workbooks. Returns a Buffer (or array of Buffers for
+   * multi-workbook specs) when `to` is omitted; writes to file/stream when `to`
+   * is provided and returns the target.
+   */
+  async write(spec, options = {}) {
+    return maybeUseWorker("write", spec, options, () => writeSpec(spec, options));
+  },
+  /**
+   * Returns a Readable stream for the first workbook. Synchronous return;
+   * errors during the underlying write surface via the stream's 'error' event.
+   */
+  writeStream(spec, options = {}) {
+    return writeSpecStream(spec, options);
+  },
+  /**
+   * Read a workbook from a Buffer, file path, or Readable stream. Returns a
+   * structured result with parsed data, per-row errors, and stats.
+   */
+  async read(input, options = {}) {
+    return maybeUseWorker("read", input, options, () => readSource(input, options));
+  }
+};
+var src_default = excelio;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ExcelIoError,
+  excelio
+});
+//# sourceMappingURL=index.cjs.map