@dipanshuhandoo/excelio 0.0.0-stage → 1.1.0

package/dist/esm/index.js

@@ -0,0 +1,824 @@
+// src/writer.js
+import { PassThrough } from "node:stream";
+import { createWriteStream } from "node:fs";
+import { rm } from "node:fs/promises";
+import { setImmediate as tick, setTimeout as sleep } from "node:timers/promises";
+import ExcelJS from "exceljs";
+
+// 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/rowSource.js
+function rowSourceKind(data) {
+  if (data === void 0 || data === null) return "empty";
+  if (Array.isArray(data)) return "array";
+  if (typeof data !== "object" && typeof data !== "function") return "invalid";
+  if (typeof data[Symbol.asyncIterator] === "function") return "async";
+  if (typeof data[Symbol.iterator] === "function") return "sync";
+  return "invalid";
+}
+var isIterableSource = (data) => {
+  const kind = rowSourceKind(data);
+  return kind === "sync" || kind === "async";
+};
+var specHasIterable = (spec) => Array.isArray(spec) && spec.some((wb) => (Array.isArray(wb?.sheets) ? wb.sheets : []).some((s) => isIterableSource(s?.data)));
+async function closeIterator(iterator) {
+  if (typeof iterator?.return !== "function") return;
+  try {
+    await iterator.return();
+  } catch {
+  }
+}
+function sourceFailure(err, details, signal) {
+  if (signal?.aborted) return new ExcelIoError("Aborted", { code: "ABORTED", cause: err, details });
+  return new ExcelIoError(`Row source failed for sheet "${details.sheetName}": ${err?.message ?? err}`, {
+    code: "SOURCE_ERROR",
+    cause: err,
+    details
+  });
+}
+
+// src/writer.js
+var DEFAULT_BATCH = 5e3;
+var SHEET_NAME_MAX = 31;
+var EXCEL_MAX_DATA_ROWS = 1048575;
+var OUTPUT_HIGH_WATER_MARK = 8 * 1024 * 1024;
+var BACKLOG_POLL_MS = 5;
+async function writeSpec(spec, options = {}) {
+  preflightWrite(spec, options);
+  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 = {}) {
+  preflightWrite(spec, options);
+  const passthrough = new PassThrough();
+  writeOneWorkbook(spec[0], 0, passthrough, options).catch((err) => passthrough.destroy(err));
+  return passthrough;
+}
+function preflightWrite(spec, options = {}) {
+  validateSpec(spec);
+  validateWriteOptions(options);
+}
+async function writeOneWorkbookToBuffer(workbookSpec, wbIndex, options) {
+  const chunks = [];
+  const collector = new PassThrough();
+  collector.on("data", (chunk) => chunks.push(chunk));
+  await writeOneWorkbook(workbookSpec, wbIndex, collector, options, { owned: true });
+  return Buffer.concat(chunks);
+}
+async function writeOneWorkbook(workbookSpec, wbIndex, target, options, sinkOptions = {}) {
+  const { signal, onProgress, beforeWrite, batchSize = DEFAULT_BATCH, logger } = options;
+  const maxRowsPerSheet = options.maxRowsPerSheet ?? EXCEL_MAX_DATA_ROWS;
+  const sheets = workbookSpec.sheets || [];
+  const sink = resolveSink(target, sinkOptions);
+  let wb = null;
+  try {
+    wb = new ExcelJS.stream.xlsx.WorkbookWriter({
+      stream: sink.writable,
+      useStyles: true,
+      useSharedStrings: resolveSharedStrings(options.sharedStrings, sheets)
+    });
+    applyWorkbookProperties(wb, workbookSpec.properties);
+    const used = /* @__PURE__ */ new Set();
+    const firstNames = sheets.map((s, i) => sanitiseSheetName(s.sheet || `Sheet ${i + 1}`, used, logger));
+    const totalRows = computeTotalRows(sheets);
+    const state = { rowsProcessed: 0, last: { sheetIndex: 0, sheetName: firstNames[0], sheetPart: 1 } };
+    const emit = () => onProgress?.({
+      phase: "write",
+      workbookIndex: wbIndex,
+      ...state.last,
+      rowsProcessed: state.rowsProcessed,
+      totalRows
+    });
+    for (let sIndex = 0; sIndex < sheets.length; sIndex++) {
+      throwIfAborted(signal);
+      const sheetSpec = sheets[sIndex];
+      const writer = createSheetWriter({
+        wb,
+        workbookSpec,
+        wbIndex,
+        sIndex,
+        sheetSpec,
+        firstName: firstNames[sIndex],
+        used,
+        beforeWrite,
+        maxRowsPerSheet,
+        onOpen: (sheetName, sheetPart) => {
+          state.last = { sheetIndex: sIndex, sheetName, sheetPart };
+        },
+        onRow: () => {
+          state.rowsProcessed++;
+          if (onProgress && state.rowsProcessed % batchSize === 0) emit();
+        }
+      });
+      const kind = rowSourceKind(sheetSpec.data);
+      if (kind === "sync" || kind === "async") {
+        await writeIterableSheet({ writer, wb, sink, sheetSpec, kind, signal, batchSize, wbIndex, sIndex });
+      } else {
+        const data = sheetSpec.data || [];
+        writer.start(resolveColumns(sheetSpec.columns, data));
+        for (let i = 0; i < data.length; i++) {
+          throwIfAborted(signal);
+          writer.write(data[i]);
+        }
+      }
+      writer.finish();
+    }
+    const committing = wb.commit();
+    committing.catch(() => {
+    });
+    await Promise.race([committing, sink.failed]);
+    if (sink.cleanup) await Promise.race([sink.cleanup(), sink.failed]);
+    sink.release();
+    emit();
+  } catch (err) {
+    await abortWorkbook(wb, sink, err);
+    throw err;
+  }
+}
+function createSheetWriter({ wb, workbookSpec, wbIndex, sIndex, sheetSpec, firstName, used, beforeWrite, maxRowsPerSheet, onOpen, onRow }) {
+  const baseName = sheetSpec.sheet || `Sheet ${sIndex + 1}`;
+  let cols = [];
+  let ws = null;
+  let sheetName = null;
+  let part = 0;
+  let rowsInPart = 0;
+  const open = () => {
+    part += 1;
+    rowsInPart = 0;
+    sheetName = part === 1 ? firstName : sanitiseSheetName(baseName, used, null);
+    const wsOptions = {};
+    if (sheetSpec.styling?.freezeHeader) wsOptions.views = [{ state: "frozen", ySplit: 1 }];
+    ws = wb.addWorksheet(sheetName, wsOptions);
+    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);
+    onOpen(sheetName, part);
+  };
+  return {
+    get sheetName() {
+      return sheetName ?? firstName;
+    },
+    start(resolvedColumns) {
+      cols = resolvedColumns;
+      open();
+    },
+    write(row) {
+      if (rowsInPart >= maxRowsPerSheet) {
+        ws.commit();
+        open();
+      }
+      let out = row;
+      if (beforeWrite) {
+        out = beforeWrite(row, {
+          workbookIndex: wbIndex,
+          workbookName: workbookSpec.workbook,
+          sheetIndex: sIndex,
+          sheetName,
+          sheetPart: part,
+          rowNumber: rowsInPart + 2
+          // header is row 1
+        }) ?? row;
+      }
+      const values = cols.length ? cols.reduce((acc, c) => {
+        acc[c.key] = valueForWrite(out[c.key], c.type);
+        return acc;
+      }, {}) : out;
+      ws.addRow(values).commit();
+      rowsInPart++;
+      onRow();
+    },
+    finish() {
+      ws?.commit();
+    }
+  };
+}
+async function writeIterableSheet({ writer, wb, sink, sheetSpec, kind, signal, batchSize, wbIndex, sIndex }) {
+  let rowsRead = 0;
+  const details = () => ({ workbookIndex: wbIndex, sheetIndex: sIndex, sheetName: writer.sheetName, rowsRead });
+  let iterator;
+  try {
+    iterator = kind === "async" ? sheetSpec.data[Symbol.asyncIterator]() : sheetSpec.data[Symbol.iterator]();
+  } catch (err) {
+    throw sourceFailure(err, details(), signal);
+  }
+  const next = async () => {
+    let step;
+    try {
+      step = await iterator.next();
+    } catch (err) {
+      throw sourceFailure(err, details(), signal);
+    }
+    if (step === null || typeof step !== "object") {
+      throw sourceFailure(new TypeError("Iterator result is not an object"), details(), signal);
+    }
+    return step;
+  };
+  let finished = false;
+  try {
+    let step = await next();
+    writer.start(resolveColumns(sheetSpec.columns, step.done ? [] : [step.value]));
+    while (!step.done) {
+      throwIfAborted(signal);
+      writer.write(step.value);
+      rowsRead++;
+      if (rowsRead % batchSize === 0) await waitForCapacity({ wb, sink, signal });
+      step = await next();
+    }
+    finished = true;
+  } finally {
+    if (!finished) await closeIterator(iterator);
+  }
+}
+var len = (n) => Number.isFinite(n) ? n : 0;
+var streamLen = (s) => len(s?.writableLength ?? s?._writableState?.length) + len(s?.readableLength ?? s?._readableState?.length);
+function backlogBytes(wb, sink) {
+  let total = streamLen(wb?.zip) + streamLen(wb?.zip?._module) + streamLen(sink?.writable);
+  for (const ws of wb?._worksheets ?? []) {
+    const sb = ws?._stream;
+    if (!sb) continue;
+    for (const buf of sb.buffers ?? []) total += len(buf?.length);
+    for (const p of sb.pipes ?? []) total += streamLen(p);
+  }
+  return total;
+}
+var backlogStats = { peak: 0 };
+async function waitForCapacity({ wb, sink, signal }) {
+  const check = () => {
+    throwIfAborted(signal);
+    if (sink.failure) throw sink.failure;
+  };
+  for (; ; ) {
+    check();
+    const backlog = backlogBytes(wb, sink);
+    if (backlog > backlogStats.peak) backlogStats.peak = backlog;
+    if (backlog <= OUTPUT_HIGH_WATER_MARK) break;
+    await sleep(BACKLOG_POLL_MS);
+  }
+  await tick();
+  check();
+}
+function resolveSink(target, { owned = false } = {}) {
+  const track = (writable, isOwned) => {
+    const sink = { writable, owned: isOwned, failure: null };
+    let onError;
+    sink.failed = new Promise((_, reject) => {
+      onError = (err) => {
+        if (sink.failure) return;
+        sink.failure = err;
+        reject(err);
+      };
+      writable.on("error", onError);
+    });
+    sink.failed.catch(() => {
+    });
+    sink.release = () => {
+      if (!isOwned) writable.removeListener("error", onError);
+    };
+    return sink;
+  };
+  if (typeof target === "string") {
+    const fileStream = createWriteStream(target);
+    const sink = track(fileStream, true);
+    const finished = new Promise((resolve) => fileStream.once("finish", resolve));
+    const closed = new Promise((resolve) => fileStream.once("close", resolve));
+    sink.cleanup = () => finished;
+    sink.remove = async () => {
+      fileStream.destroy();
+      await closed;
+      await rm(target, { force: true });
+    };
+    return sink;
+  }
+  if (target && typeof target.write === "function") {
+    return track(target, owned);
+  }
+  throw new ExcelIoError(`Invalid write target \u2014 expected file path or writable stream`, { code: "INVALID_SPEC" });
+}
+async function abortWorkbook(wb, sink, err) {
+  const quiet = (s) => s?.on?.("error", () => {
+  });
+  try {
+    if (wb) {
+      wb.zip?.unpipe?.(sink.writable);
+      quiet(wb.zip);
+      quiet(wb.zip?._module);
+      for (const ws of wb._worksheets ?? []) (ws?._stream?.pipes ?? []).forEach(quiet);
+      wb.zip?.abort?.();
+    }
+    if (sink.remove) await sink.remove();
+    else if (sink.owned) sink.writable.destroy?.();
+    sink.release();
+  } catch (cleanupError) {
+    try {
+      if (typeof err === "object" && err !== null || typeof err === "function") err.cleanupError = cleanupError;
+    } catch {
+    }
+  }
+}
+function resolveSharedStrings(option = "auto", sheets) {
+  if (typeof option === "boolean") return option;
+  return !sheets.some((s) => isIterableSource(s?.data));
+}
+function computeTotalRows(sheets) {
+  let total = 0;
+  for (const s of sheets) {
+    const kind = rowSourceKind(s.data);
+    if (kind === "array") total += s.data.length;
+    else if (kind === "sync" || kind === "async") {
+      if (s.totalRows === void 0) return void 0;
+      total += s.totalRows;
+    }
+  }
+  return total;
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted) throw new ExcelIoError("Aborted", { code: "ABORTED" });
+}
+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" });
+  }
+  const owners = /* @__PURE__ */ new Map();
+  spec.forEach((wb, wbIndex) => {
+    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" });
+    }
+    wb.sheets.forEach((s, i) => {
+      if (!s || typeof s !== "object") {
+        throw new ExcelIoError(`Workbook ${wbIndex}: sheet entries must be objects`, { code: "INVALID_SPEC" });
+      }
+      const name = s.sheet || `Sheet ${i + 1}`;
+      const kind = rowSourceKind(s.data);
+      if (kind === "invalid") {
+        throw new ExcelIoError(`Sheet "${name}": data must be an array or an iterable of row objects`, { code: "INVALID_SPEC" });
+      }
+      if (kind === "sync" || kind === "async") {
+        if (owners.has(s.data)) {
+          throw new ExcelIoError(
+            `Sheet "${name}": its data source is already used by sheet "${owners.get(s.data)}". Pass a separate iterable (or an array) per sheet.`,
+            { code: "INVALID_SPEC" }
+          );
+        }
+        owners.set(s.data, name);
+      }
+      if (s.totalRows !== void 0 && !(Number.isInteger(s.totalRows) && s.totalRows >= 0)) {
+        throw new ExcelIoError(`Sheet "${name}": totalRows must be a non-negative integer`, { code: "INVALID_SPEC" });
+      }
+    });
+  });
+}
+function validateWriteOptions({ maxRowsPerSheet, sharedStrings, batchSize } = {}) {
+  if (maxRowsPerSheet !== void 0 && !(Number.isInteger(maxRowsPerSheet) && maxRowsPerSheet >= 1 && maxRowsPerSheet <= EXCEL_MAX_DATA_ROWS)) {
+    throw new ExcelIoError(`maxRowsPerSheet must be an integer between 1 and ${EXCEL_MAX_DATA_ROWS}`, { code: "INVALID_SPEC" });
+  }
+  if (sharedStrings !== void 0 && sharedStrings !== "auto" && typeof sharedStrings !== "boolean") {
+    throw new ExcelIoError(`sharedStrings must be 'auto', true or false`, { code: "INVALID_SPEC" });
+  }
+  if (batchSize !== void 0 && !(Number.isInteger(batchSize) && batchSize >= 1)) {
+    throw new ExcelIoError("batchSize must be a positive integer", { code: "INVALID_SPEC" });
+  }
+}
+
+// src/reader.js
+import { Buffer as Buffer2 } from "node:buffer";
+import ExcelJS2 from "exceljs";
+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 ExcelJS2.Workbook();
+  try {
+    if (Buffer2.isBuffer(input)) {
+      await wb.xlsx.load(input);
+    } else if (input instanceof Uint8Array) {
+      await wb.xlsx.load(Buffer2.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
+import { Worker } from "node:worker_threads";
+import { fileURLToPath } from "node:url";
+import { Buffer as Buffer3 } from "node:buffer";
+import path from "node:path";
+import { statSync } from "node:fs";
+var DEFAULT_THRESHOLD = { rows: 5e4, bytes: 10 * 1024 * 1024 };
+var moduleDirectory = typeof __EXCELIO_MODULE_DIR__ !== "undefined" ? __EXCELIO_MODULE_DIR__ : path.dirname(fileURLToPath(import.meta.url));
+var workerExtension = true ? ".js" : ".js";
+var WORKER_PATHS = {
+  write: path.join(moduleDirectory, "workers", `writer.worker${workerExtension}`),
+  read: path.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 (op === "write" && specHasIterable(payload)) {
+    if (useWorker === true) options.logger?.warn?.("excelio: iterable sheet data is written inline; useWorker ignored");
+    return { mode: "inline", reason: "iterable sheet data" };
+  }
+  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 += Array.isArray(sheet?.data) ? sheet.data.length : 0;
+    }
+  }
+  return n;
+}
+function estimateBytes(input) {
+  if (typeof input === "string") {
+    try {
+      return statSync(input).size;
+    } catch {
+      return null;
+    }
+  }
+  if (Buffer3.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 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) => Buffer3.from(value)) : Buffer3.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 = {}) {
+    preflightWrite(spec, options);
+    return maybeUseWorker("write", spec, options, () => writeSpec(spec, options));
+  },
+  /**
+   * Returns a Readable stream for the first workbook. Synchronous return;
+   * spec errors throw immediately, errors during the underlying write surface
+   * via the stream's 'error' event.
+   */
+  writeStream(spec, options = {}) {
+    preflightWrite(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;
+export {
+  ExcelIoError,
+  src_default as default,
+  excelio
+};
+//# sourceMappingURL=index.js.map