@dipanshuhandoo/excelio 0.0.0-stage → 1.0.0

package/dist/cjs-min/workers/reader.worker.cjs

@@ -0,0 +1,2 @@
+var W=Object.create;var N=Object.defineProperty;var C=Object.getOwnPropertyDescriptor;var H=Object.getOwnPropertyNames;var U=Object.getPrototypeOf,$=Object.prototype.hasOwnProperty;var z=(e,r,o,n)=>{if(r&&typeof r=="object"||typeof r=="function")for(let t of H(r))!$.call(e,t)&&t!==o&&N(e,t,{get:()=>r[t],enumerable:!(n=C(r,t))||n.enumerable});return e};var J=(e,r,o)=>(o=e!=null?W(U(e)):{},z(r||!e||!e.__esModule?N(o,"default",{value:e,enumerable:!0}):o,e));var l=require("node:worker_threads");var k=require("node:buffer");var j=J(require("exceljs"),1);var a=class extends Error{constructor(r,{code:o="IO_ERROR",cause:n,details:t}={}){super(r),this.name="ExcelIoError",this.code=o,n!==void 0&&(this.cause=n),t!==void 0&&(this.details=t)}};function F(e,{nullForBlank:r=!0,trimStrings:o=!0,dateFormat:n="iso"}={}){if(e==null)return r?null:"";let t=e&&typeof e=="object"&&"value"in e?e.value:e;if(t==null||t==="")return r?null:"";if(t instanceof Date)return K(t,n);if(typeof t=="object"&&t.text!==void 0&&t.hyperlink!==void 0)return o?String(t.text).trim():String(t.text);if(typeof t=="object"&&Array.isArray(t.richText)){let c=t.richText.map(R=>R.text).join("");return o?c.trim():c}return typeof t=="object"&&t.formula!==void 0?t.result!==void 0?t.result:null:typeof t=="object"&&t.error!==void 0?null:typeof t=="string"&&o?t.trim():t}function K(e,r){switch(r){case"date":return e;case"epoch":return e.getTime();default:return e.toISOString()}}var Z=5e3;async function B(e,r={}){let o=Date.now(),n={totalRows:0,totalSheets:0,durationMs:0},t=[],{headerRow:c=1,nullForBlank:R=!0,trimStrings:L=!0,dateFormat:M="iso",validateRow:x,afterRead:A,onRowError:E="collect",batchSize:P=Z,onProgress:I,signal:D}=r,d=new j.default.Workbook;try{if(k.Buffer.isBuffer(e))await d.xlsx.load(e);else if(e instanceof Uint8Array)await d.xlsx.load(k.Buffer.from(e.buffer,e.byteOffset,e.byteLength));else if(typeof e=="string")await d.xlsx.readFile(e);else if(e&&typeof e.pipe=="function")await d.xlsx.read(e);else throw new a("Invalid input \u2014 expected Buffer, file path, or readable stream",{code:"INVALID_SPEC"})}catch(f){throw f instanceof a?f:new a(`Failed to parse workbook: ${f.message}`,{code:"IO_ERROR",cause:f})}let O=[];for(let f=0;f<d.worksheets.length;f++){if(D?.aborted)throw new a("Aborted",{code:"ABORTED"});let m=d.worksheets[f];n.totalSheets++;let b={sheet:m.name,columns:[],data:[]},u=null;m.eachRow({includeEmpty:!1},(S,y)=>{if(y===c){u=q(S),b.columns=u.filter(Boolean).map(s=>({key:s,header:s}));return}if(y<c||!u)return;if(D?.aborted)throw new a("Aborted",{code:"ABORTED"});let h={},T=!0;for(let s=0;s<u.length;s++){let i=u[s];if(!i)continue;let V=S.getCell(s+1),p=F(V,{nullForBlank:R,trimStrings:L,dateFormat:M});p!==null&&p!==""&&p!==void 0&&(T=!1),h[i]=p}if(T)return;let w={workbookIndex:0,workbookName:void 0,sheetIndex:f,sheetName:m.name,rowNumber:y},g=h;if(A)try{g=A(h,w)??h}catch(s){let i=_(w,"TRANSFORM_ERROR",s.message);if(E==="fail")throw new a(i.message,{code:"ROW_VALIDATION",details:i});t.push(i);return}if(x){let s=x(g,w);if(s){let i=_(w,s.code||"VALIDATION_FAILED",s.message,s.column);if(E==="fail")throw new a(i.message,{code:"ROW_VALIDATION",details:i});t.push(i);return}}b.data.push(g),n.totalRows++,I&&n.totalRows%P===0&&I({phase:"read",sheetName:m.name,rowsProcessed:n.totalRows})}),O.push(b)}return n.durationMs=Date.now()-o,{ok:t.length===0,data:[{workbook:void 0,sheets:O}],errors:t,stats:n}}function q(e){let r=[],o=e.values;if(!Array.isArray(o))return r;for(let n=1;n<o.length;n++){let t=o[n];r.push(t==null?null:String(t).trim())}return r}function _(e,r,o,n){return{workbook:e.workbookIndex,sheet:e.sheetName,row:e.rowNumber,column:n??null,code:r,message:o}}(async()=>{try{let{payload:e,options:r}=l.workerData,o=await B(e,r);l.parentPort.postMessage({ok:!0,result:o})}catch(e){l.parentPort.postMessage({ok:!1,error:{message:e.message,code:e.code,stack:e.stack,details:e.details}})}})();
+//# sourceMappingURL=reader.worker.cjs.map

package/dist/cjs-min/workers/reader.worker.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/workers/reader.worker.js", "../../../src/reader.js", "../../../src/errors.js", "../../../src/coerce.js"],
+  "sourcesContent": ["import { parentPort, workerData } from 'node:worker_threads';\r\nimport { readSource } from '../reader.js';\r\n\r\n(async () => {\r\n  try {\r\n    const { payload, options } = workerData;\r\n    const result = await readSource(payload, options);\r\n    parentPort.postMessage({ ok: true, result });\r\n  } catch (err) {\r\n    parentPort.postMessage({\r\n      ok: false,\r\n      error: { message: err.message, code: err.code, stack: err.stack, details: err.details }\r\n    });\r\n  }\r\n})();\r\n", "import { Readable } from 'node:stream';\r\nimport { Buffer } from 'node:buffer';\r\nimport { createReadStream } from 'node:fs';\r\nimport { stat } from 'node:fs/promises';\r\nimport ExcelJS from 'exceljs';\r\n\r\nimport { ExcelIoError } from './errors.js';\r\nimport { valueForRead } from './coerce.js';\r\n\r\nconst DEFAULT_BATCH = 5000;\r\n\r\n/**\r\n * Read a workbook from a Buffer, file path, or readable stream.\r\n *\r\n * Currently uses the non-streaming `xlsx.load` / `xlsx.read` API for reliability.\r\n * Large files may exceed available memory. Worker-thread offload keeps parsing\r\n * off the main thread, but does not reduce total process memory or isolate it.\r\n * A future optimisation can swap to `stream.xlsx.WorkbookReader` once exceljs\r\n * stabilises its async iterator semantics across versions.\r\n */\r\nexport async function readSource(input, options = {}) {\r\n  const startedAt = Date.now();\r\n  const stats = { totalRows: 0, totalSheets: 0, durationMs: 0 };\r\n  const errors = [];\r\n\r\n  const {\r\n    headerRow = 1,\r\n    nullForBlank = true,\r\n    trimStrings = true,\r\n    dateFormat = 'iso',\r\n    validateRow,\r\n    afterRead,\r\n    onRowError = 'collect',\r\n    batchSize = DEFAULT_BATCH,\r\n    onProgress,\r\n    signal\r\n  } = options;\r\n\r\n  const wb = new ExcelJS.Workbook();\r\n  try {\r\n    if (Buffer.isBuffer(input)) {\r\n      await wb.xlsx.load(input);\r\n    } else if (input instanceof Uint8Array) {\r\n      // Worker boundary downgrades Buffer to Uint8Array; rewrap.\r\n      await wb.xlsx.load(Buffer.from(input.buffer, input.byteOffset, input.byteLength));\r\n    } else if (typeof input === 'string') {\r\n      await wb.xlsx.readFile(input);\r\n    } else if (input && typeof input.pipe === 'function') {\r\n      await wb.xlsx.read(input);\r\n    } else {\r\n      throw new ExcelIoError('Invalid input \u2014 expected Buffer, file path, or readable stream', { code: 'INVALID_SPEC' });\r\n    }\r\n  } catch (err) {\r\n    if (err instanceof ExcelIoError) throw err;\r\n    throw new ExcelIoError(`Failed to parse workbook: ${err.message}`, { code: 'IO_ERROR', cause: err });\r\n  }\r\n\r\n  const sheets = [];\r\n\r\n  for (let s = 0; s < wb.worksheets.length; s++) {\r\n    if (signal?.aborted) throw new ExcelIoError('Aborted', { code: 'ABORTED' });\r\n\r\n    const ws = wb.worksheets[s];\r\n    stats.totalSheets++;\r\n\r\n    const sheetMeta = { sheet: ws.name, columns: [], data: [] };\r\n    let columnKeys = null;\r\n\r\n    ws.eachRow({ includeEmpty: false }, (row, rowNumber) => {\r\n      // Header row\r\n      if (rowNumber === headerRow) {\r\n        columnKeys = readHeaderRow(row);\r\n        sheetMeta.columns = columnKeys\r\n          .filter(Boolean)\r\n          .map(k => ({ key: k, header: k }));\r\n        return;\r\n      }\r\n      if (rowNumber < headerRow || !columnKeys) return;\r\n      if (signal?.aborted) throw new ExcelIoError('Aborted', { code: 'ABORTED' });\r\n\r\n      const obj = {};\r\n      let isEmpty = true;\r\n      for (let i = 0; i < columnKeys.length; i++) {\r\n        const key = columnKeys[i];\r\n        if (!key) continue;\r\n        const cell = row.getCell(i + 1);\r\n        const v = valueForRead(cell, { nullForBlank, trimStrings, dateFormat });\r\n        if (v !== null && v !== '' && v !== undefined) isEmpty = false;\r\n        obj[key] = v;\r\n      }\r\n      if (isEmpty) return;\r\n\r\n      const ctx = {\r\n        workbookIndex: 0,\r\n        workbookName: undefined,\r\n        sheetIndex: s,\r\n        sheetName: ws.name,\r\n        rowNumber\r\n      };\r\n\r\n      let outRow = obj;\r\n      if (afterRead) {\r\n        try {\r\n          outRow = afterRead(obj, ctx) ?? obj;\r\n        } catch (err) {\r\n          const e = mkRowError(ctx, 'TRANSFORM_ERROR', err.message);\r\n          if (onRowError === 'fail') throw new ExcelIoError(e.message, { code: 'ROW_VALIDATION', details: e });\r\n          errors.push(e);\r\n          return;\r\n        }\r\n      }\r\n\r\n      if (validateRow) {\r\n        const issue = validateRow(outRow, ctx);\r\n        if (issue) {\r\n          const e = mkRowError(ctx, issue.code || 'VALIDATION_FAILED', issue.message, issue.column);\r\n          if (onRowError === 'fail') throw new ExcelIoError(e.message, { code: 'ROW_VALIDATION', details: e });\r\n          errors.push(e);\r\n          return;\r\n        }\r\n      }\r\n\r\n      sheetMeta.data.push(outRow);\r\n      stats.totalRows++;\r\n\r\n      if (onProgress && stats.totalRows % batchSize === 0) {\r\n        onProgress({ phase: 'read', sheetName: ws.name, rowsProcessed: stats.totalRows });\r\n      }\r\n    });\r\n\r\n    sheets.push(sheetMeta);\r\n  }\r\n\r\n  stats.durationMs = Date.now() - startedAt;\r\n\r\n  return {\r\n    ok: errors.length === 0,\r\n    data: [{ workbook: undefined, sheets }],\r\n    errors,\r\n    stats\r\n  };\r\n}\r\n\r\n/* \u2500\u2500\u2500\u2500\u2500\u2500 helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\r\n\r\nfunction readHeaderRow(row) {\r\n  const headers = [];\r\n  // exceljs row.values is sparse: index 0 unused, headers start at 1\r\n  const values = row.values;\r\n  if (!Array.isArray(values)) return headers;\r\n  for (let i = 1; i < values.length; i++) {\r\n    const v = values[i];\r\n    headers.push(v == null ? null : String(v).trim());\r\n  }\r\n  return headers;\r\n}\r\n\r\nfunction mkRowError(ctx, code, message, column) {\r\n  return {\r\n    workbook: ctx.workbookIndex,\r\n    sheet: ctx.sheetName,\r\n    row: ctx.rowNumber,\r\n    column: column ?? null,\r\n    code,\r\n    message\r\n  };\r\n}\r\n", "/**\r\n * Custom error type for excelio. No external dependencies \u2014 keeps the package\r\n * portable to any Node project.\r\n *\r\n * Codes:\r\n *   INVALID_SPEC   \u2014 caller passed a malformed spec\r\n *   IO_ERROR       \u2014 corrupt input file, write failure, etc.\r\n *   ABORTED        \u2014 operation cancelled via AbortController\r\n *   WORKER_ERROR   \u2014 worker thread crashed or returned an error\r\n *   ROW_VALIDATION \u2014 a row failed validation (only thrown when onRowError === 'fail')\r\n */\r\nexport class ExcelIoError extends Error {\r\n  constructor(message, { code = 'IO_ERROR', cause, details } = {}) {\r\n    super(message);\r\n    this.name = 'ExcelIoError';\r\n    this.code = code;\r\n    if (cause !== undefined) this.cause = cause;\r\n    if (details !== undefined) this.details = details;\r\n  }\r\n}\r\n", "/**\r\n * Cell value coercion in both directions.\r\n *\r\n * Write side: accept a JS value + optional column type, normalise to what exceljs\r\n * expects. Excel-native types are Number, String, Boolean, Date, formula objects,\r\n * and null.\r\n *\r\n * Read side: take a cell from exceljs and turn it into a portable JS value. Dates\r\n * default to ISO 8601 strings; configurable via `dateFormat`.\r\n */\r\n\r\nconst ISO_DATE_PATTERN = /^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})?)?$/;\r\n\r\n/**\r\n * Normalise a JS value for writing into a cell. Returns the value as-is for most\r\n * types; converts ISO date strings + epoch ms to Date when the column declares\r\n * `type: 'date'`.\r\n */\r\nexport function valueForWrite(value, columnType) {\r\n  if (value === null || value === undefined) return null;\r\n\r\n  if (columnType === 'date') {\r\n    if (value instanceof Date) return value;\r\n    if (typeof value === 'number') return new Date(value);\r\n    if (typeof value === 'string' && ISO_DATE_PATTERN.test(value)) {\r\n      const d = new Date(value);\r\n      return isNaN(d.getTime()) ? value : d;\r\n    }\r\n    return value;\r\n  }\r\n\r\n  if (columnType === 'number' && typeof value === 'string' && value !== '') {\r\n    const n = Number(value);\r\n    return Number.isFinite(n) ? n : value;\r\n  }\r\n\r\n  if (columnType === 'boolean') {\r\n    if (typeof value === 'boolean') return value;\r\n    if (value === 'true' || value === 1) return true;\r\n    if (value === 'false' || value === 0) return false;\r\n  }\r\n\r\n  return value;\r\n}\r\n\r\n/**\r\n * Convert an exceljs cell value into a portable JS value.\r\n *\r\n * options:\r\n *   nullForBlank: boolean   \u2014 empty cells become null (default true)\r\n *   trimStrings:  boolean   \u2014 strip leading/trailing whitespace from strings\r\n *   dateFormat:   'iso' | 'date' | 'epoch'\r\n */\r\nexport function valueForRead(cell, { nullForBlank = true, trimStrings = true, dateFormat = 'iso' } = {}) {\r\n  if (cell === undefined || cell === null) return nullForBlank ? null : '';\r\n\r\n  // exceljs returns CellValue which can be primitive or object; cell.value is the\r\n  // canonical accessor. When called with a raw value (e.g. from streaming), it's\r\n  // already the primitive.\r\n  const raw = (cell && typeof cell === 'object' && 'value' in cell) ? cell.value : cell;\r\n\r\n  if (raw === null || raw === undefined || raw === '') return nullForBlank ? null : '';\r\n\r\n  // Date cells\r\n  if (raw instanceof Date) return formatDate(raw, dateFormat);\r\n\r\n  // Hyperlink object: { text, hyperlink, ... } \u2014 return the visible text\r\n  if (typeof raw === 'object' && raw.text !== undefined && raw.hyperlink !== undefined) {\r\n    return trimStrings ? String(raw.text).trim() : String(raw.text);\r\n  }\r\n\r\n  // Rich text object: { richText: [{ text, font }, ...] }\r\n  if (typeof raw === 'object' && Array.isArray(raw.richText)) {\r\n    const joined = raw.richText.map(r => r.text).join('');\r\n    return trimStrings ? joined.trim() : joined;\r\n  }\r\n\r\n  // Formula object: { formula, result }\r\n  if (typeof raw === 'object' && raw.formula !== undefined) {\r\n    return raw.result !== undefined ? raw.result : null;\r\n  }\r\n\r\n  // Error cell: { error: '#N/A' }\r\n  if (typeof raw === 'object' && raw.error !== undefined) return null;\r\n\r\n  if (typeof raw === 'string') return trimStrings ? raw.trim() : raw;\r\n  return raw;\r\n}\r\n\r\nfunction formatDate(d, fmt) {\r\n  switch (fmt) {\r\n    case 'date':  return d;\r\n    case 'epoch': return d.getTime();\r\n    case 'iso':\r\n    default:      return d.toISOString();\r\n  }\r\n}\r\n"],
+  "mappings": "2cAAA,IAAAA,EAAuC,+BCCvC,IAAAC,EAAuB,uBAGvB,IAAAC,EAAoB,wBCOb,IAAMC,EAAN,cAA2B,KAAM,CACtC,YAAYC,EAAS,CAAE,KAAAC,EAAO,WAAY,MAAAC,EAAO,QAAAC,CAAQ,EAAI,CAAC,EAAG,CAC/D,MAAMH,CAAO,EACb,KAAK,KAAO,eACZ,KAAK,KAAOC,EACRC,IAAU,SAAW,KAAK,MAAQA,GAClCC,IAAY,SAAW,KAAK,QAAUA,EAC5C,CACF,ECkCO,SAASC,EAAaC,EAAM,CAAE,aAAAC,EAAe,GAAM,YAAAC,EAAc,GAAM,WAAAC,EAAa,KAAM,EAAI,CAAC,EAAG,CACvG,GAA0BH,GAAS,KAAM,OAAOC,EAAe,KAAO,GAKtE,IAAMG,EAAOJ,GAAQ,OAAOA,GAAS,UAAY,UAAWA,EAAQA,EAAK,MAAQA,EAEjF,GAAII,GAAQ,MAA6BA,IAAQ,GAAI,OAAOH,EAAe,KAAO,GAGlF,GAAIG,aAAe,KAAM,OAAOC,EAAWD,EAAKD,CAAU,EAG1D,GAAI,OAAOC,GAAQ,UAAYA,EAAI,OAAS,QAAaA,EAAI,YAAc,OACzE,OAAOF,EAAc,OAAOE,EAAI,IAAI,EAAE,KAAK,EAAI,OAAOA,EAAI,IAAI,EAIhE,GAAI,OAAOA,GAAQ,UAAY,MAAM,QAAQA,EAAI,QAAQ,EAAG,CAC1D,IAAME,EAASF,EAAI,SAAS,IAAIG,GAAKA,EAAE,IAAI,EAAE,KAAK,EAAE,EACpD,OAAOL,EAAcI,EAAO,KAAK,EAAIA,CACvC,CAGA,OAAI,OAAOF,GAAQ,UAAYA,EAAI,UAAY,OACtCA,EAAI,SAAW,OAAYA,EAAI,OAAS,KAI7C,OAAOA,GAAQ,UAAYA,EAAI,QAAU,OAAkB,KAE3D,OAAOA,GAAQ,UAAiBF,EAAcE,EAAI,KAAK,EACpDA,CACT,CAEA,SAASC,EAAWG,EAAGC,EAAK,CAC1B,OAAQA,EAAK,CACX,IAAK,OAAS,OAAOD,EACrB,IAAK,QAAS,OAAOA,EAAE,QAAQ,EAE/B,QAAc,OAAOA,EAAE,YAAY,CACrC,CACF,CFvFA,IAAME,EAAgB,IAWtB,eAAsBC,EAAWC,EAAOC,EAAU,CAAC,EAAG,CACpD,IAAMC,EAAY,KAAK,IAAI,EACrBC,EAAQ,CAAE,UAAW,EAAG,YAAa,EAAG,WAAY,CAAE,EACtDC,EAAS,CAAC,EAEV,CACJ,UAAAC,EAAY,EACZ,aAAAC,EAAe,GACf,YAAAC,EAAc,GACd,WAAAC,EAAa,MACb,YAAAC,EACA,UAAAC,EACA,WAAAC,EAAa,UACb,UAAAC,EAAYd,EACZ,WAAAe,EACA,OAAAC,CACF,EAAIb,EAEEc,EAAK,IAAI,EAAAC,QAAQ,SACvB,GAAI,CACF,GAAI,SAAO,SAAShB,CAAK,EACvB,MAAMe,EAAG,KAAK,KAAKf,CAAK,UACfA,aAAiB,WAE1B,MAAMe,EAAG,KAAK,KAAK,SAAO,KAAKf,EAAM,OAAQA,EAAM,WAAYA,EAAM,UAAU,CAAC,UACvE,OAAOA,GAAU,SAC1B,MAAMe,EAAG,KAAK,SAASf,CAAK,UACnBA,GAAS,OAAOA,EAAM,MAAS,WACxC,MAAMe,EAAG,KAAK,KAAKf,CAAK,MAExB,OAAM,IAAIiB,EAAa,sEAAkE,CAAE,KAAM,cAAe,CAAC,CAErH,OAASC,EAAK,CACZ,MAAIA,aAAeD,EAAoBC,EACjC,IAAID,EAAa,6BAA6BC,EAAI,OAAO,GAAI,CAAE,KAAM,WAAY,MAAOA,CAAI,CAAC,CACrG,CAEA,IAAMC,EAAS,CAAC,EAEhB,QAASC,EAAI,EAAGA,EAAIL,EAAG,WAAW,OAAQK,IAAK,CAC7C,GAAIN,GAAQ,QAAS,MAAM,IAAIG,EAAa,UAAW,CAAE,KAAM,SAAU,CAAC,EAE1E,IAAMI,EAAKN,EAAG,WAAWK,CAAC,EAC1BjB,EAAM,cAEN,IAAMmB,EAAY,CAAE,MAAOD,EAAG,KAAM,QAAS,CAAC,EAAG,KAAM,CAAC,CAAE,EACtDE,EAAa,KAEjBF,EAAG,QAAQ,CAAE,aAAc,EAAM,EAAG,CAACG,EAAKC,IAAc,CAEtD,GAAIA,IAAcpB,EAAW,CAC3BkB,EAAaG,EAAcF,CAAG,EAC9BF,EAAU,QAAUC,EACjB,OAAO,OAAO,EACd,IAAII,IAAM,CAAE,IAAKA,EAAG,OAAQA,CAAE,EAAE,EACnC,MACF,CACA,GAAIF,EAAYpB,GAAa,CAACkB,EAAY,OAC1C,GAAIT,GAAQ,QAAS,MAAM,IAAIG,EAAa,UAAW,CAAE,KAAM,SAAU,CAAC,EAE1E,IAAMW,EAAM,CAAC,EACTC,EAAU,GACd,QAASC,EAAI,EAAGA,EAAIP,EAAW,OAAQO,IAAK,CAC1C,IAAMC,EAAMR,EAAWO,CAAC,EACxB,GAAI,CAACC,EAAK,SACV,IAAMC,EAAOR,EAAI,QAAQM,EAAI,CAAC,EACxBG,EAAIC,EAAaF,EAAM,CAAE,aAAA1B,EAAc,YAAAC,EAAa,WAAAC,CAAW,CAAC,EAClEyB,IAAM,MAAQA,IAAM,IAAMA,IAAM,SAAWJ,EAAU,IACzDD,EAAIG,CAAG,EAAIE,CACb,CACA,GAAIJ,EAAS,OAEb,IAAMM,EAAM,CACV,cAAe,EACf,aAAc,OACd,WAAYf,EACZ,UAAWC,EAAG,KACd,UAAAI,CACF,EAEIW,EAASR,EACb,GAAIlB,EACF,GAAI,CACF0B,EAAS1B,EAAUkB,EAAKO,CAAG,GAAKP,CAClC,OAASV,EAAK,CACZ,IAAMmB,EAAIC,EAAWH,EAAK,kBAAmBjB,EAAI,OAAO,EACxD,GAAIP,IAAe,OAAQ,MAAM,IAAIM,EAAaoB,EAAE,QAAS,CAAE,KAAM,iBAAkB,QAASA,CAAE,CAAC,EACnGjC,EAAO,KAAKiC,CAAC,EACb,MACF,CAGF,GAAI5B,EAAa,CACf,IAAM8B,EAAQ9B,EAAY2B,EAAQD,CAAG,EACrC,GAAII,EAAO,CACT,IAAMF,EAAIC,EAAWH,EAAKI,EAAM,MAAQ,oBAAqBA,EAAM,QAASA,EAAM,MAAM,EACxF,GAAI5B,IAAe,OAAQ,MAAM,IAAIM,EAAaoB,EAAE,QAAS,CAAE,KAAM,iBAAkB,QAASA,CAAE,CAAC,EACnGjC,EAAO,KAAKiC,CAAC,EACb,MACF,CACF,CAEAf,EAAU,KAAK,KAAKc,CAAM,EAC1BjC,EAAM,YAEFU,GAAcV,EAAM,UAAYS,IAAc,GAChDC,EAAW,CAAE,MAAO,OAAQ,UAAWQ,EAAG,KAAM,cAAelB,EAAM,SAAU,CAAC,CAEpF,CAAC,EAEDgB,EAAO,KAAKG,CAAS,CACvB,CAEA,OAAAnB,EAAM,WAAa,KAAK,IAAI,EAAID,EAEzB,CACL,GAAIE,EAAO,SAAW,EACtB,KAAM,CAAC,CAAE,SAAU,OAAW,OAAAe,CAAO,CAAC,EACtC,OAAAf,EACA,MAAAD,CACF,CACF,CAIA,SAASuB,EAAcF,EAAK,CAC1B,IAAMgB,EAAU,CAAC,EAEXC,EAASjB,EAAI,OACnB,GAAI,CAAC,MAAM,QAAQiB,CAAM,EAAG,OAAOD,EACnC,QAASV,EAAI,EAAGA,EAAIW,EAAO,OAAQX,IAAK,CACtC,IAAMG,EAAIQ,EAAOX,CAAC,EAClBU,EAAQ,KAAKP,GAAK,KAAO,KAAO,OAAOA,CAAC,EAAE,KAAK,CAAC,CAClD,CACA,OAAOO,CACT,CAEA,SAASF,EAAWH,EAAKO,EAAMC,EAASC,EAAQ,CAC9C,MAAO,CACL,SAAUT,EAAI,cACd,MAAOA,EAAI,UACX,IAAKA,EAAI,UACT,OAAQS,GAAU,KAClB,KAAAF,EACA,QAAAC,CACF,CACF,EDnKC,SAAY,CACX,GAAI,CACF,GAAM,CAAE,QAAAE,EAAS,QAAAC,CAAQ,EAAI,aACvBC,EAAS,MAAMC,EAAWH,EAASC,CAAO,EAChD,aAAW,YAAY,CAAE,GAAI,GAAM,OAAAC,CAAO,CAAC,CAC7C,OAASE,EAAK,CACZ,aAAW,YAAY,CACrB,GAAI,GACJ,MAAO,CAAE,QAASA,EAAI,QAAS,KAAMA,EAAI,KAAM,MAAOA,EAAI,MAAO,QAASA,EAAI,OAAQ,CACxF,CAAC,CACH,CACF,GAAG",
+  "names": ["import_node_worker_threads", "import_node_buffer", "import_exceljs", "ExcelIoError", "message", "code", "cause", "details", "valueForRead", "cell", "nullForBlank", "trimStrings", "dateFormat", "raw", "formatDate", "joined", "r", "d", "fmt", "DEFAULT_BATCH", "readSource", "input", "options", "startedAt", "stats", "errors", "headerRow", "nullForBlank", "trimStrings", "dateFormat", "validateRow", "afterRead", "onRowError", "batchSize", "onProgress", "signal", "wb", "ExcelJS", "ExcelIoError", "err", "sheets", "s", "ws", "sheetMeta", "columnKeys", "row", "rowNumber", "readHeaderRow", "k", "obj", "isEmpty", "i", "key", "cell", "v", "valueForRead", "ctx", "outRow", "e", "mkRowError", "issue", "headers", "values", "code", "message", "column", "payload", "options", "result", "readSource", "err"]
+}

package/dist/cjs-min/workers/writer.worker.cjs

@@ -0,0 +1,2 @@
+var V=Object.create;var D=Object.defineProperty;var $=Object.getOwnPropertyDescriptor;var H=Object.getOwnPropertyNames;var M=Object.getPrototypeOf,z=Object.prototype.hasOwnProperty;var J=(e,t,r,n)=>{if(t&&typeof t=="object"||typeof t=="function")for(let o of H(t))!z.call(e,o)&&o!==r&&D(e,o,{get:()=>t[o],enumerable:!(n=$(t,o))||n.enumerable});return e};var q=(e,t,r)=>(r=e!=null?V(M(e)):{},J(t||!e||!e.__esModule?D(r,"default",{value:e,enumerable:!0}):r,e));var h=require("node:worker_threads");var T=require("node:stream"),P=require("node:fs");var O=q(require("exceljs"),1);var a=class extends Error{constructor(t,{code:r="IO_ERROR",cause:n,details:o}={}){super(t),this.name="ExcelIoError",this.code=r,n!==void 0&&(this.cause=n),o!==void 0&&(this.details=o)}};function _(e,t){if(Array.isArray(e)&&e.length)return e.map(N);if(!t?.length)return[];let r=t[0]||{};return Object.keys(r).map(n=>N({key:n}))}function N(e){if(!e||typeof e!="object"||!e.key)throw new Error(`excelio: column entry must have a "key" property; got ${JSON.stringify(e)}`);return{key:String(e.key),header:e.header??e.key,type:e.type??null,format:e.format??U(e.type),width:e.width??15}}function U(e){switch(e){case"date":return"yyyy-mm-dd hh:mm:ss";case"number":return null;default:return null}}var X=/^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/;function R(e,t){if(e==null)return null;if(t==="date"){if(e instanceof Date)return e;if(typeof e=="number")return new Date(e);if(typeof e=="string"&&X.test(e)){let r=new Date(e);return isNaN(r.getTime())?e:r}return e}if(t==="number"&&typeof e=="string"&&e!==""){let r=Number(e);return Number.isFinite(r)?r:e}if(t==="boolean"){if(typeof e=="boolean")return e;if(e==="true"||e===1)return!0;if(e==="false"||e===0)return!1}return e}var Z=5e3,m=31;async function W(e,t={}){te(e);let{to:r}=t;if(r!==void 0&&e.length>1)throw new a('Multi-workbook output requires omitting "to" \u2014 caller writes each buffer itself.',{code:"INVALID_SPEC"});if(r!==void 0)return await j(e[0],0,r,t),r;let n=[];for(let o=0;o<e.length;o++){let i=await G(e[o],o,t);n.push(i)}return n.length===1?n[0]:n}async function G(e,t,r){let n=[],o=new T.PassThrough;return o.on("data",i=>n.push(i)),await j(e,t,o,r),Buffer.concat(n)}async function j(e,t,r,n){let{signal:o,onProgress:i,beforeWrite:d,batchSize:F=Z,logger:C}=n,b=K(r),k=new O.default.stream.xlsx.WorkbookWriter({stream:b.writable,useStyles:!0,useSharedStrings:!0});Q(k,e.properties);let B=new Set,w=e.sheets||[],S=w.reduce((f,u)=>f+(u.data?.length||0),0),y=0;for(let f=0;f<w.length;f++){if(o?.aborted)throw new a("Aborted",{code:"ABORTED"});let u=w[f],x=ee(u.sheet||`Sheet ${f+1}`,B,C),A={};u.styling?.freezeHeader&&(A.views=[{state:"frozen",ySplit:1}]);let p=k.addWorksheet(x,A),c=_(u.columns,u.data);c.length&&(p.columns=c.map(s=>({key:s.key,header:s.header,width:s.width,style:s.format?{numFmt:s.format}:void 0}))),Y(p,u.styling,c.length);let E=u.data||[];for(let s=0;s<E.length;s++){if(o?.aborted)throw new a("Aborted",{code:"ABORTED"});let l=E[s];d&&(l=d(l,{workbookIndex:t,workbookName:e.workbook,sheetIndex:f,sheetName:x,rowNumber:s+2})??l);let L=c.length?c.reduce((I,g)=>(I[g.key]=R(l[g.key],g.type),I),{}):l;p.addRow(L).commit(),y++,i&&y%F===0&&i({phase:"write",workbookIndex:t,sheetIndex:f,rowsProcessed:y,totalRows:S})}p.commit()}await k.commit(),b.cleanup&&await b.cleanup(),i&&i({phase:"write",workbookIndex:t,sheetIndex:w.length-1,rowsProcessed:y,totalRows:S})}function K(e){if(typeof e=="string"){let t=(0,P.createWriteStream)(e),r=new Promise((n,o)=>{t.once("finish",n),t.once("error",o)});return{writable:t,cleanup:()=>r}}if(e&&typeof e.write=="function")return{writable:e,cleanup:null};throw new a("Invalid write target \u2014 expected file path or writable stream",{code:"INVALID_SPEC"})}function Q(e,t){t&&(t.author&&(e.creator=t.author),t.created&&(e.created=t.created instanceof Date?t.created:new Date(t.created)),t.modified&&(e.modified=t.modified instanceof Date?t.modified:new Date(t.modified)),t.company&&(e.company=t.company),t.title&&(e.title=t.title))}function Y(e,t,r){t&&(t.headerBold&&(e.getRow(1).font={bold:!0}),t.autoFilter&&r>0&&(e.autoFilter={from:{row:1,column:1},to:{row:1,column:r}}))}var v=/[\\/?*[\]:]/g;function ee(e,t,r){let n=String(e).replace(v,"_");if(n.length>m&&(r?.warn&&r.warn(`excelio: sheet name "${e}" truncated to ${m} chars`),n=n.slice(0,m)),!t.has(n))return t.add(n),n;let o=2;for(;;){let i=` (${o})`,d=(n.length+i.length>m?n.slice(0,m-i.length):n)+i;if(!t.has(d))return t.add(d),d;o++}}function te(e){if(!Array.isArray(e)||e.length===0)throw new a("Spec must be a non-empty array of workbooks",{code:"INVALID_SPEC"});for(let t of e){if(!t||typeof t!="object")throw new a("Workbook entries must be objects",{code:"INVALID_SPEC"});if(!Array.isArray(t.sheets)||t.sheets.length===0)throw new a("Workbook must have at least one sheet",{code:"INVALID_SPEC"})}}(async()=>{try{let{payload:e,options:t}=h.workerData,r=await W(e,t);h.parentPort.postMessage({ok:!0,result:r})}catch(e){h.parentPort.postMessage({ok:!1,error:{message:e.message,code:e.code,stack:e.stack,details:e.details}})}})();
+//# sourceMappingURL=writer.worker.cjs.map

package/dist/cjs-min/workers/writer.worker.cjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../src/workers/writer.worker.js", "../../../src/writer.js", "../../../src/errors.js", "../../../src/columns.js", "../../../src/coerce.js"],
+  "sourcesContent": ["import { parentPort, workerData } from 'node:worker_threads';\r\nimport { writeSpec } from '../writer.js';\r\n\r\n(async () => {\r\n  try {\r\n    const { payload, options } = workerData;\r\n    const result = await writeSpec(payload, options);\r\n    parentPort.postMessage({ ok: true, result });\r\n  } catch (err) {\r\n    parentPort.postMessage({\r\n      ok: false,\r\n      error: { message: err.message, code: err.code, stack: err.stack, details: err.details }\r\n    });\r\n  }\r\n})();\r\n", "import { Readable, PassThrough } from 'node:stream';\r\nimport { createWriteStream } from 'node:fs';\r\nimport { pipeline } from 'node:stream/promises';\r\nimport path from 'node:path';\r\nimport ExcelJS from 'exceljs';\r\n\r\nimport { ExcelIoError } from './errors.js';\r\nimport { resolveColumns } from './columns.js';\r\nimport { valueForWrite } from './coerce.js';\r\n\r\nconst DEFAULT_BATCH = 5000;\r\nconst SHEET_NAME_MAX = 31;\r\n\r\n/**\r\n * Write one or more workbooks from a spec.\r\n *\r\n * Returns:\r\n *   - When `to` is omitted: an array of Buffers, one per workbook (single-element\r\n *     array when spec has one workbook).\r\n *   - When `to` is a file path: writes the file, returns the path. Supported only\r\n *     when spec has exactly one workbook.\r\n *   - When `to` is a Writable stream: pipes the workbook into it. Single workbook only.\r\n *\r\n * Multi-workbook with a single `to` target isn't supported (no zip semantics here).\r\n * For multi-workbook output, omit `to` and get buffers back.\r\n */\r\nexport async function writeSpec(spec, options = {}) {\r\n  validateSpec(spec);\r\n\r\n  const { to } = options;\r\n  if (to !== undefined && spec.length > 1) {\r\n    throw new ExcelIoError(\r\n      `Multi-workbook output requires omitting \"to\" \u2014 caller writes each buffer itself.`,\r\n      { code: 'INVALID_SPEC' }\r\n    );\r\n  }\r\n\r\n  if (to !== undefined) {\r\n    await writeOneWorkbook(spec[0], 0, to, options);\r\n    return to;\r\n  }\r\n\r\n  const buffers = [];\r\n  for (let wbIndex = 0; wbIndex < spec.length; wbIndex++) {\r\n    const buf = await writeOneWorkbookToBuffer(spec[wbIndex], wbIndex, options);\r\n    buffers.push(buf);\r\n  }\r\n  // Ergonomic: single-workbook spec returns a single Buffer; multi returns Buffer[]\r\n  return buffers.length === 1 ? buffers[0] : buffers;\r\n}\r\n\r\n/**\r\n * Returns a Readable stream containing the first workbook's bytes. If the spec has\r\n * multiple workbooks, only the first is streamed (callers wanting multi should\r\n * call writeSpec without `to` to get buffers).\r\n */\r\nexport function writeSpecStream(spec, options = {}) {\r\n  validateSpec(spec);\r\n  const passthrough = new PassThrough();\r\n  writeOneWorkbook(spec[0], 0, passthrough, options).catch(err => passthrough.destroy(err));\r\n  return passthrough;\r\n}\r\n\r\n/* \u2500\u2500\u2500\u2500\u2500\u2500 internals \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */\r\n\r\nasync function writeOneWorkbookToBuffer(workbookSpec, wbIndex, options) {\r\n  const chunks = [];\r\n  const collector = new PassThrough();\r\n  collector.on('data', (chunk) => chunks.push(chunk));\r\n  await writeOneWorkbook(workbookSpec, wbIndex, collector, options);\r\n  return Buffer.concat(chunks);\r\n}\r\n\r\nasync function writeOneWorkbook(workbookSpec, wbIndex, target, options) {\r\n  const { signal, onProgress, beforeWrite, batchSize = DEFAULT_BATCH, logger } = options;\r\n\r\n  const sink = resolveSink(target);\r\n\r\n  const wb = new ExcelJS.stream.xlsx.WorkbookWriter({\r\n    stream: sink.writable,\r\n    useStyles: true,\r\n    useSharedStrings: true\r\n  });\r\n\r\n  applyWorkbookProperties(wb, workbookSpec.properties);\r\n\r\n  const usedNames = new Set();\r\n  const sheets = workbookSpec.sheets || [];\r\n  let totalRows = sheets.reduce((n, s) => n + (s.data?.length || 0), 0);\r\n  let rowsProcessed = 0;\r\n\r\n  for (let sIndex = 0; sIndex < sheets.length; sIndex++) {\r\n    if (signal?.aborted) throw new ExcelIoError('Aborted', { code: 'ABORTED' });\r\n\r\n    const sheetSpec = sheets[sIndex];\r\n    const sheetName = sanitiseSheetName(sheetSpec.sheet || `Sheet ${sIndex + 1}`, usedNames, logger);\r\n\r\n    // Pass styling-related options at creation time \u2014 WorksheetWriter (streaming)\r\n    // doesn't allow setting `views` after the fact.\r\n    const wsOptions = {};\r\n    if (sheetSpec.styling?.freezeHeader) {\r\n      wsOptions.views = [{ state: 'frozen', ySplit: 1 }];\r\n    }\r\n    const ws = wb.addWorksheet(sheetName, wsOptions);\r\n\r\n    const cols = resolveColumns(sheetSpec.columns, sheetSpec.data);\r\n    if (cols.length) {\r\n      ws.columns = cols.map(c => ({\r\n        key: c.key,\r\n        header: c.header,\r\n        width: c.width,\r\n        style: c.format ? { numFmt: c.format } : undefined\r\n      }));\r\n    }\r\n\r\n    applyStylingPostColumns(ws, sheetSpec.styling, cols.length);\r\n\r\n    const data = sheetSpec.data || [];\r\n    for (let i = 0; i < data.length; i++) {\r\n      if (signal?.aborted) throw new ExcelIoError('Aborted', { code: 'ABORTED' });\r\n\r\n      let row = data[i];\r\n      if (beforeWrite) {\r\n        row = beforeWrite(row, {\r\n          workbookIndex: wbIndex,\r\n          workbookName: workbookSpec.workbook,\r\n          sheetIndex: sIndex,\r\n          sheetName,\r\n          rowNumber: i + 2  // header is row 1\r\n        }) ?? row;\r\n      }\r\n\r\n      const rowValues = cols.length\r\n        ? cols.reduce((acc, c) => { acc[c.key] = valueForWrite(row[c.key], c.type); return acc; }, {})\r\n        : row;\r\n      ws.addRow(rowValues).commit();\r\n\r\n      rowsProcessed++;\r\n      if (onProgress && rowsProcessed % batchSize === 0) {\r\n        onProgress({ phase: 'write', workbookIndex: wbIndex, sheetIndex: sIndex, rowsProcessed, totalRows });\r\n      }\r\n    }\r\n\r\n    ws.commit();\r\n  }\r\n\r\n  await wb.commit();\r\n  if (sink.cleanup) await sink.cleanup();\r\n\r\n  if (onProgress) {\r\n    onProgress({ phase: 'write', workbookIndex: wbIndex, sheetIndex: sheets.length - 1, rowsProcessed, totalRows });\r\n  }\r\n}\r\n\r\nfunction resolveSink(target) {\r\n  // File path \u2014 register the close promise immediately so we don't miss the\r\n  // 'finish' event if it fires before cleanup() is awaited.\r\n  if (typeof target === 'string') {\r\n    const fileStream = createWriteStream(target);\r\n    const closed = new Promise((resolve, reject) => {\r\n      fileStream.once('finish', resolve);\r\n      fileStream.once('error', reject);\r\n    });\r\n    return { writable: fileStream, cleanup: () => closed };\r\n  }\r\n  // Writable stream supplied by caller \u2014 they own its lifecycle.\r\n  if (target && typeof target.write === 'function') {\r\n    return { writable: target, cleanup: null };\r\n  }\r\n  throw new ExcelIoError(`Invalid write target \u2014 expected file path or writable stream`, { code: 'INVALID_SPEC' });\r\n}\r\n\r\nfunction applyWorkbookProperties(wb, props) {\r\n  if (!props) return;\r\n  if (props.author)   wb.creator = props.author;\r\n  if (props.created)  wb.created = props.created instanceof Date ? props.created : new Date(props.created);\r\n  if (props.modified) wb.modified = props.modified instanceof Date ? props.modified : new Date(props.modified);\r\n  if (props.company)  wb.company = props.company;\r\n  if (props.title)    wb.title = props.title;\r\n}\r\n\r\nfunction applyStylingPostColumns(ws, styling, colCount) {\r\n  if (!styling) return;\r\n  if (styling.headerBold) {\r\n    ws.getRow(1).font = { bold: true };\r\n  }\r\n  if (styling.autoFilter && colCount > 0) {\r\n    ws.autoFilter = { from: { row: 1, column: 1 }, to: { row: 1, column: colCount } };\r\n  }\r\n  // freezeHeader is applied at addWorksheet time (see wsOptions in writeOneWorkbook).\r\n}\r\n\r\nconst FORBIDDEN_SHEET_CHARS = /[\\\\/?*[\\]:]/g;\r\n\r\nfunction sanitiseSheetName(raw, used, logger) {\r\n  let name = String(raw).replace(FORBIDDEN_SHEET_CHARS, '_');\r\n  if (name.length > SHEET_NAME_MAX) {\r\n    if (logger?.warn) logger.warn(`excelio: sheet name \"${raw}\" truncated to ${SHEET_NAME_MAX} chars`);\r\n    name = name.slice(0, SHEET_NAME_MAX);\r\n  }\r\n  if (!used.has(name)) { used.add(name); return name; }\r\n  let i = 2;\r\n  while (true) {\r\n    const suffix = ` (${i})`;\r\n    const candidate = (name.length + suffix.length > SHEET_NAME_MAX\r\n      ? name.slice(0, SHEET_NAME_MAX - suffix.length)\r\n      : name) + suffix;\r\n    if (!used.has(candidate)) { used.add(candidate); return candidate; }\r\n    i++;\r\n  }\r\n}\r\n\r\nfunction validateSpec(spec) {\r\n  if (!Array.isArray(spec) || spec.length === 0) {\r\n    throw new ExcelIoError('Spec must be a non-empty array of workbooks', { code: 'INVALID_SPEC' });\r\n  }\r\n  for (const wb of spec) {\r\n    if (!wb || typeof wb !== 'object') {\r\n      throw new ExcelIoError('Workbook entries must be objects', { code: 'INVALID_SPEC' });\r\n    }\r\n    if (!Array.isArray(wb.sheets) || wb.sheets.length === 0) {\r\n      throw new ExcelIoError('Workbook must have at least one sheet', { code: 'INVALID_SPEC' });\r\n    }\r\n  }\r\n}\r\n\r\n// Helpers exported for tests\r\nexport const __test = { sanitiseSheetName };\r\n", "/**\r\n * Custom error type for excelio. No external dependencies \u2014 keeps the package\r\n * portable to any Node project.\r\n *\r\n * Codes:\r\n *   INVALID_SPEC   \u2014 caller passed a malformed spec\r\n *   IO_ERROR       \u2014 corrupt input file, write failure, etc.\r\n *   ABORTED        \u2014 operation cancelled via AbortController\r\n *   WORKER_ERROR   \u2014 worker thread crashed or returned an error\r\n *   ROW_VALIDATION \u2014 a row failed validation (only thrown when onRowError === 'fail')\r\n */\r\nexport class ExcelIoError extends Error {\r\n  constructor(message, { code = 'IO_ERROR', cause, details } = {}) {\r\n    super(message);\r\n    this.name = 'ExcelIoError';\r\n    this.code = code;\r\n    if (cause !== undefined) this.cause = cause;\r\n    if (details !== undefined) this.details = details;\r\n  }\r\n}\r\n", "/**\r\n * Column metadata helpers.\r\n *\r\n * A column entry shape:\r\n *   { key, header?, type?, format?, width? }\r\n *\r\n *   key    : property name on each data row (required)\r\n *   header : displayed in the first row (defaults to key)\r\n *   type   : 'string' | 'number' | 'boolean' | 'date' (informs cell formatting)\r\n *   format : Excel number-format string (e.g. 'yyyy-mm-dd', '#,##0.00')\r\n *   width  : column width in Excel units (default 15)\r\n */\r\n\r\n/**\r\n * Resolve the columns for a sheet. If the caller provided columns, validate/normalise.\r\n * Otherwise infer from the first row's keys (preserving insertion order).\r\n */\r\nexport function resolveColumns(declaredColumns, data) {\r\n  if (Array.isArray(declaredColumns) && declaredColumns.length) {\r\n    return declaredColumns.map(normaliseColumn);\r\n  }\r\n  if (!data?.length) return [];\r\n  const firstRow = data[0] || {};\r\n  return Object.keys(firstRow).map(k => normaliseColumn({ key: k }));\r\n}\r\n\r\nfunction normaliseColumn(c) {\r\n  if (!c || typeof c !== 'object' || !c.key) {\r\n    throw new Error(`excelio: column entry must have a \"key\" property; got ${JSON.stringify(c)}`);\r\n  }\r\n  return {\r\n    key:    String(c.key),\r\n    header: c.header ?? c.key,\r\n    type:   c.type ?? null,\r\n    format: c.format ?? defaultFormatFor(c.type),\r\n    width:  c.width ?? 15\r\n  };\r\n}\r\n\r\nfunction defaultFormatFor(type) {\r\n  switch (type) {\r\n    case 'date':   return 'yyyy-mm-dd hh:mm:ss';\r\n    case 'number': return null;\r\n    default:       return null;\r\n  }\r\n}\r\n", "/**\r\n * Cell value coercion in both directions.\r\n *\r\n * Write side: accept a JS value + optional column type, normalise to what exceljs\r\n * expects. Excel-native types are Number, String, Boolean, Date, formula objects,\r\n * and null.\r\n *\r\n * Read side: take a cell from exceljs and turn it into a portable JS value. Dates\r\n * default to ISO 8601 strings; configurable via `dateFormat`.\r\n */\r\n\r\nconst ISO_DATE_PATTERN = /^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:?\\d{2})?)?$/;\r\n\r\n/**\r\n * Normalise a JS value for writing into a cell. Returns the value as-is for most\r\n * types; converts ISO date strings + epoch ms to Date when the column declares\r\n * `type: 'date'`.\r\n */\r\nexport function valueForWrite(value, columnType) {\r\n  if (value === null || value === undefined) return null;\r\n\r\n  if (columnType === 'date') {\r\n    if (value instanceof Date) return value;\r\n    if (typeof value === 'number') return new Date(value);\r\n    if (typeof value === 'string' && ISO_DATE_PATTERN.test(value)) {\r\n      const d = new Date(value);\r\n      return isNaN(d.getTime()) ? value : d;\r\n    }\r\n    return value;\r\n  }\r\n\r\n  if (columnType === 'number' && typeof value === 'string' && value !== '') {\r\n    const n = Number(value);\r\n    return Number.isFinite(n) ? n : value;\r\n  }\r\n\r\n  if (columnType === 'boolean') {\r\n    if (typeof value === 'boolean') return value;\r\n    if (value === 'true' || value === 1) return true;\r\n    if (value === 'false' || value === 0) return false;\r\n  }\r\n\r\n  return value;\r\n}\r\n\r\n/**\r\n * Convert an exceljs cell value into a portable JS value.\r\n *\r\n * options:\r\n *   nullForBlank: boolean   \u2014 empty cells become null (default true)\r\n *   trimStrings:  boolean   \u2014 strip leading/trailing whitespace from strings\r\n *   dateFormat:   'iso' | 'date' | 'epoch'\r\n */\r\nexport function valueForRead(cell, { nullForBlank = true, trimStrings = true, dateFormat = 'iso' } = {}) {\r\n  if (cell === undefined || cell === null) return nullForBlank ? null : '';\r\n\r\n  // exceljs returns CellValue which can be primitive or object; cell.value is the\r\n  // canonical accessor. When called with a raw value (e.g. from streaming), it's\r\n  // already the primitive.\r\n  const raw = (cell && typeof cell === 'object' && 'value' in cell) ? cell.value : cell;\r\n\r\n  if (raw === null || raw === undefined || raw === '') return nullForBlank ? null : '';\r\n\r\n  // Date cells\r\n  if (raw instanceof Date) return formatDate(raw, dateFormat);\r\n\r\n  // Hyperlink object: { text, hyperlink, ... } \u2014 return the visible text\r\n  if (typeof raw === 'object' && raw.text !== undefined && raw.hyperlink !== undefined) {\r\n    return trimStrings ? String(raw.text).trim() : String(raw.text);\r\n  }\r\n\r\n  // Rich text object: { richText: [{ text, font }, ...] }\r\n  if (typeof raw === 'object' && Array.isArray(raw.richText)) {\r\n    const joined = raw.richText.map(r => r.text).join('');\r\n    return trimStrings ? joined.trim() : joined;\r\n  }\r\n\r\n  // Formula object: { formula, result }\r\n  if (typeof raw === 'object' && raw.formula !== undefined) {\r\n    return raw.result !== undefined ? raw.result : null;\r\n  }\r\n\r\n  // Error cell: { error: '#N/A' }\r\n  if (typeof raw === 'object' && raw.error !== undefined) return null;\r\n\r\n  if (typeof raw === 'string') return trimStrings ? raw.trim() : raw;\r\n  return raw;\r\n}\r\n\r\nfunction formatDate(d, fmt) {\r\n  switch (fmt) {\r\n    case 'date':  return d;\r\n    case 'epoch': return d.getTime();\r\n    case 'iso':\r\n    default:      return d.toISOString();\r\n  }\r\n}\r\n"],
+  "mappings": "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",
+  "names": ["import_node_worker_threads", "import_node_stream", "import_node_fs", "import_exceljs", "ExcelIoError", "message", "code", "cause", "details", "resolveColumns", "declaredColumns", "data", "normaliseColumn", "firstRow", "k", "c", "defaultFormatFor", "type", "ISO_DATE_PATTERN", "valueForWrite", "value", "columnType", "d", "n", "DEFAULT_BATCH", "SHEET_NAME_MAX", "writeSpec", "spec", "options", "validateSpec", "to", "ExcelIoError", "writeOneWorkbook", "buffers", "wbIndex", "buf", "writeOneWorkbookToBuffer", "writeOneWorkbookToBuffer", "workbookSpec", "wbIndex", "options", "chunks", "collector", "chunk", "writeOneWorkbook", "target", "signal", "onProgress", "beforeWrite", "batchSize", "DEFAULT_BATCH", "logger", "sink", "resolveSink", "wb", "ExcelJS", "applyWorkbookProperties", "usedNames", "sheets", "totalRows", "n", "s", "rowsProcessed", "sIndex", "ExcelIoError", "sheetSpec", "sheetName", "sanitiseSheetName", "wsOptions", "ws", "cols", "resolveColumns", "c", "applyStylingPostColumns", "data", "i", "row", "rowValues", "acc", "valueForWrite", "fileStream", "closed", "resolve", "reject", "props", "styling", "colCount", "FORBIDDEN_SHEET_CHARS", "raw", "used", "name", "SHEET_NAME_MAX", "suffix", "candidate", "validateSpec", "spec", "payload", "options", "result", "writeSpec", "err"]
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,172 @@
+/// <reference types="node" />
+/**
+ * excelio — Plug-and-Play Excel ↔ JSON utility.
+ * TypeScript declarations for consumers; the package itself is plain JS.
+ */
+import type { Readable, Writable } from 'node:stream';
+import type { Buffer } from 'node:buffer';
+
+export type ExcelIoErrorCode =
+  | 'INVALID_SPEC'
+  | 'IO_ERROR'
+  | 'ABORTED'
+  | 'WORKER_ERROR'
+  | 'ROW_VALIDATION';
+
+export class ExcelIoError extends Error {
+  constructor(message: string, options?: { code?: ExcelIoErrorCode; cause?: unknown; details?: unknown });
+  code: ExcelIoErrorCode;
+  cause?: unknown;
+  details?: unknown;
+}
+
+export type ColumnType = 'string' | 'number' | 'boolean' | 'date';
+
+export interface ColumnSpec {
+  /** Property name on each data row. */
+  key: string;
+  /** Header text in row 1. Defaults to `key`. */
+  header?: string;
+  /** Type hint that informs cell formatting and write-side coercion. */
+  type?: ColumnType;
+  /** Excel number-format string (e.g. 'yyyy-mm-dd', '#,##0.00'). */
+  format?: string;
+  /** Column width in Excel units. */
+  width?: number;
+}
+
+export interface SheetStyling {
+  headerBold?: boolean;
+  freezeHeader?: boolean;
+  autoFilter?: boolean;
+}
+
+export interface SheetSpec<Row = Record<string, unknown>> {
+  sheet: string;
+  columns?: ColumnSpec[];
+  styling?: SheetStyling;
+  data: Row[];
+}
+
+export interface WorkbookSpec<Row = Record<string, unknown>> {
+  workbook: string;
+  properties?: {
+    author?: string;
+    company?: string;
+    title?: string;
+    created?: Date | string;
+    modified?: Date | string;
+  };
+  sheets: SheetSpec<Row>[];
+}
+
+export type Spec<Row = Record<string, unknown>> = WorkbookSpec<Row>[];
+
+export interface ParsedColumn {
+  key: string;
+  header: string;
+}
+
+export interface ParsedSheet<Row = Record<string, unknown>> {
+  sheet: string;
+  columns: ParsedColumn[];
+  data: Row[];
+}
+
+export interface ParsedWorkbook<Row = Record<string, unknown>> {
+  workbook: undefined;
+  sheets: ParsedSheet<Row>[];
+}
+
+export interface RowContext {
+  workbookIndex: number;
+  workbookName?: string;
+  sheetIndex: number;
+  sheetName: string;
+  rowNumber: number;
+}
+
+export interface RowError {
+  workbook: number;
+  sheet: string;
+  row: number;
+  column: string | null;
+  code: string;
+  message: string;
+}
+
+export interface ReadResult<Row = Record<string, unknown>> {
+  ok: boolean;
+  data: ParsedWorkbook<Row>[];
+  errors: RowError[];
+  stats: {
+    totalRows: number;
+    totalSheets: number;
+    durationMs: number;
+  };
+}
+
+export interface ProgressEvent {
+  phase: 'read' | 'write';
+  workbookIndex?: number;
+  sheetIndex?: number;
+  sheetName?: string;
+  rowsProcessed: number;
+  totalRows?: number;
+}
+
+export interface Logger {
+  info?: (msg: string, ...args: unknown[]) => void;
+  warn?: (msg: string, ...args: unknown[]) => void;
+  error?: (msg: string, ...args: unknown[]) => void;
+}
+
+export interface CommonOptions {
+  /** Called at batchSize row boundaries; writing also emits a final update. */
+  onProgress?: (e: ProgressEvent) => void;
+  /** Checked between rows/sheets; does not interrupt parsing or synchronous loops. */
+  signal?: AbortSignal;
+  /** BYO logger. Default: no-op. */
+  logger?: Logger;
+  /** Progress notification interval; does not yield processing or bound memory. */
+  batchSize?: number;
+  /** 'auto' (default), true (request worker), false (inline). Hooks/streams force inline. */
+  useWorker?: 'auto' | boolean;
+  /** Auto-mode threshold. Default: { rows: 50_000, bytes: 10MB }. */
+  workerThreshold?: { rows?: number; bytes?: number };
+}
+
+export interface WriteOptions<Row = Record<string, unknown>> extends CommonOptions {
+  /** File path or Writable stream. Omit to receive Buffer(s) back. */
+  to?: string | Writable;
+  /** Per-row transform applied before writing. */
+  beforeWrite?: (row: Row, ctx: RowContext) => Row | void;
+}
+
+export interface ReadOptions<Row = Record<string, unknown>> extends CommonOptions {
+  /** Row number containing headers (1-indexed). Default: 1. */
+  headerRow?: number;
+  /** Empty cells become null instead of ''. Default: true. */
+  nullForBlank?: boolean;
+  /** Trim whitespace from string cells. Default: true. */
+  trimStrings?: boolean;
+  /** Date output format. Default: 'iso'. */
+  dateFormat?: 'iso' | 'date' | 'epoch';
+  /** Per-row transform applied after parsing, before validation. */
+  afterRead?: (row: Row, ctx: RowContext) => Row | void;
+  /** Per-row validation. Return null/undefined for valid; an issue object for invalid. */
+  validateRow?: (row: Row, ctx: RowContext) => null | undefined | { code?: string; message: string; column?: string };
+  /** 'collect' (default) returns errors in the result; 'fail' throws on first. */
+  onRowError?: 'collect' | 'fail';
+}
+
+export interface Excelio {
+  write<Row = Record<string, unknown>, Target extends string | Writable = string | Writable>(spec: Spec<Row>, options: WriteOptions<Row> & { to: Target }): Promise<Target>;
+  write<Row = Record<string, unknown>>(spec: Spec<Row>, options?: WriteOptions<Row> & { to?: undefined }): Promise<Buffer | Buffer[]>;
+  write<Row = Record<string, unknown>>(spec: Spec<Row>, options?: WriteOptions<Row>): Promise<Buffer | Buffer[] | string | Writable>;
+  writeStream<Row = Record<string, unknown>>(spec: Spec<Row>, options?: WriteOptions<Row>): Readable;
+  read<Row = Record<string, unknown>>(input: Buffer | string | Readable, options?: ReadOptions<Row>): Promise<ReadResult<Row>>;
+}
+
+export const excelio: Excelio;
+export default excelio;