@lichens-innovation/ts-common 1.7.0 → 1.9.0

package/dist/excel.js

@@ -0,0 +1,167 @@
+import ExcelJS from 'exceljs';
+import mime from 'mime';
+
+// src/excel/excel-generator.ts
+var WorksheetBuilder = class {
+  worksheet;
+  currentRow;
+  defaultRowStyles;
+  constructor(worksheet) {
+    this.worksheet = worksheet;
+    this.currentRow = 1;
+    this.defaultRowStyles = [];
+  }
+  /** Returns the current row index (1-based). */
+  get rowCount() {
+    return this.currentRow;
+  }
+  addCell({ row, col, value, style }) {
+    const cell = this.worksheet.getCell(row + 1, col + 1);
+    cell.value = value ?? "";
+    if (style) {
+      this.applyStyle(cell, style);
+    }
+  }
+  addRow({ values, styles }) {
+    const stylesToUse = styles ?? this.defaultRowStyles;
+    const row = this.worksheet.addRow(values);
+    for (let col = 0; col < values.length; col++) {
+      const style = stylesToUse[col];
+      if (style) {
+        const cell = row.getCell(col + 1);
+        this.applyStyle(cell, style);
+      }
+    }
+    this.currentRow++;
+  }
+  setDefaultRowStyles(styles) {
+    this.defaultRowStyles = styles;
+  }
+  addEmptyRow() {
+    this.worksheet.addRow([]);
+    this.currentRow++;
+  }
+  setColumnWidths(columnWidths) {
+    this.worksheet.columns = columnWidths.map((width) => ({ width }));
+  }
+  getWorksheet() {
+    return this.worksheet;
+  }
+  applyStyle(cell, style) {
+    if (style.font) {
+      cell.font = { ...cell.font, ...style.font };
+    }
+    if (style.fill) {
+      cell.fill = style.fill;
+    }
+    if (style.alignment) {
+      cell.alignment = { ...cell.alignment, ...style.alignment };
+    }
+    if (style.border) {
+      cell.border = { ...cell.border, ...style.border };
+    }
+    if (style.numFmt) {
+      cell.numFmt = style.numFmt;
+    }
+  }
+};
+
+// src/excel/excel-generator.types.ts
+var rgbToArgb = (rgb) => {
+  return { argb: `FF${rgb}` };
+};
+var getMimeType = (extension) => {
+  const mimeType = mime.getType(extension);
+  if (!mimeType) {
+    throw new Error(`[getMimeType] Mime type not found for extension: "${extension}"`);
+  }
+  return mimeType;
+};
+
+// src/utils/types.utils.ts
+var isNullish = (value) => value === null || value === void 0;
+
+// src/excel/exceljs.utils.ts
+var sanitizeWorksheetTitle = (title) => {
+  const MAX_LENGTH = 31;
+  const INVALID_CHARS = /[:/\\?*[\]]/g;
+  return title.trim().replace(INVALID_CHARS, "").slice(0, MAX_LENGTH);
+};
+var toSafeCellValue = ({ value, valueType }) => {
+  if (!isNullish(value) && valueType === "number") {
+    const numValue = typeof value === "number" ? value : Number(value);
+    return isNaN(numValue) ? value : numValue;
+  }
+  return value ?? "";
+};
+var toSafeCellValues = ({ headers, rowData, columnsMetadata }) => {
+  return headers.map((header) => {
+    const value = rowData[header];
+    const metadata = columnsMetadata?.[header];
+    const valueType = metadata?.valueType ?? "auto";
+    return toSafeCellValue({ value, valueType });
+  });
+};
+var applyTextFormatting = ({ row, headers, columnsMetadata }) => {
+  for (let colIndex = 0; colIndex < headers.length; colIndex++) {
+    const header = headers[colIndex];
+    const metadata = columnsMetadata?.[header];
+    const valueType = metadata?.valueType ?? "auto";
+    if (valueType === "text") {
+      const cell = row.getCell(colIndex + 1);
+      cell.numFmt = "@";
+    }
+  }
+};
+var applyHeaderStyles = (headerRow) => {
+  headerRow.font = { bold: true };
+  headerRow.fill = {
+    type: "pattern",
+    pattern: "solid",
+    fgColor: { argb: "FFE0E0E0" }
+  };
+  headerRow.alignment = { wrapText: true, vertical: "top" };
+};
+var setupHeaderFrozenRow = ({ worksheet, headers }) => {
+  const headerRow = worksheet.addRow(headers);
+  applyHeaderStyles(headerRow);
+  worksheet.views = [{ state: "frozen", ySplit: 1 }];
+};
+var applyDataRowStyles = ({ worksheet, startRowIndex, endRowIndex }) => {
+  for (let rowIndex = startRowIndex; rowIndex <= endRowIndex; rowIndex++) {
+    const row = worksheet.getRow(rowIndex);
+    row.alignment = { wrapText: false, vertical: "top" };
+  }
+};
+var setColumnWidths = ({ worksheet, headers, columnsMetadata }) => {
+  worksheet.columns = headers.map((header) => {
+    const metadata = columnsMetadata[header];
+    return metadata ? { width: metadata.width } : {};
+  });
+};
+var addDataRows = ({ worksheet, headers, columnsMetadata, data }) => {
+  for (const rowData of data) {
+    const safeCellValues = toSafeCellValues({ headers, rowData, columnsMetadata });
+    const row = worksheet.addRow(safeCellValues);
+    applyTextFormatting({ row, headers, columnsMetadata });
+  }
+  applyDataRowStyles({ worksheet, startRowIndex: 2, endRowIndex: data.length + 1 });
+};
+var generateExcelBlob = async (args) => {
+  const { data, columnsMetadata, worksheetTitle } = args;
+  if (data.length === 0) {
+    throw new Error("No data to export");
+  }
+  const headers = Object.keys(data[0]);
+  const workbook = new ExcelJS.Workbook();
+  const worksheet = workbook.addWorksheet(sanitizeWorksheetTitle(worksheetTitle));
+  setupHeaderFrozenRow({ worksheet, headers });
+  addDataRows({ worksheet, headers, columnsMetadata, data });
+  setColumnWidths({ worksheet, headers, columnsMetadata });
+  const buffer = await workbook.xlsx.writeBuffer();
+  return new Blob([buffer], { type: getMimeType("xlsx") });
+};
+
+export { WorksheetBuilder, generateExcelBlob, rgbToArgb, sanitizeWorksheetTitle };
+//# sourceMappingURL=excel.js.map
+//# sourceMappingURL=excel.js.map

package/dist/excel.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/excel/excel-generator.ts","../src/excel/excel-generator.types.ts","../src/mime/index.ts","../src/utils/types.utils.ts","../src/excel/exceljs.utils.ts"],"names":[],"mappings":";;;;AAeO,IAAM,mBAAN,MAAuB;AAAA,EACpB,SAAA;AAAA,EACA,UAAA;AAAA,EACA,gBAAA;AAAA,EAER,YAAY,SAAA,EAA8B;AACxC,IAAA,IAAA,CAAK,SAAA,GAAY,SAAA;AACjB,IAAA,IAAA,CAAK,UAAA,GAAa,CAAA;AAClB,IAAA,IAAA,CAAK,mBAAmB,EAAC;AAAA,EAC3B;AAAA;AAAA,EAGA,IAAI,QAAA,GAAmB;AACrB,IAAA,OAAO,IAAA,CAAK,UAAA;AAAA,EACd;AAAA,EAEA,QAAQ,EAAE,GAAA,EAAK,GAAA,EAAK,KAAA,EAAO,OAAM,EAAsB;AACrD,IAAA,MAAM,OAAO,IAAA,CAAK,SAAA,CAAU,QAAQ,GAAA,GAAM,CAAA,EAAG,MAAM,CAAC,CAAA;AACpD,IAAA,IAAA,CAAK,QAAQ,KAAA,IAAS,EAAA;AAEtB,IAAA,IAAI,KAAA,EAAO;AACT,MAAA,IAAA,CAAK,UAAA,CAAW,MAAM,KAAK,CAAA;AAAA,IAC7B;AAAA,EACF;AAAA,EAEA,MAAA,CAAO,EAAE,MAAA,EAAQ,MAAA,EAAO,EAAqB;AAC3C,IAAA,MAAM,WAAA,GAAc,UAAU,IAAA,CAAK,gBAAA;AACnC,IAAA,MAAM,GAAA,GAAM,IAAA,CAAK,SAAA,CAAU,MAAA,CAAO,MAAM,CAAA;AAGxC,IAAA,KAAA,IAAS,GAAA,GAAM,CAAA,EAAG,GAAA,GAAM,MAAA,CAAO,QAAQ,GAAA,EAAA,EAAO;AAC5C,MAAA,MAAM,KAAA,GAAQ,YAAY,GAAG,CAAA;AAC7B,MAAA,IAAI,KAAA,EAAO;AACT,QAAA,MAAM,IAAA,GAAO,GAAA,CAAI,OAAA,CAAQ,GAAA,GAAM,CAAC,CAAA;AAChC,QAAA,IAAA,CAAK,UAAA,CAAW,MAAM,KAAK,CAAA;AAAA,MAC7B;AAAA,IACF;AAEA,IAAA,IAAA,CAAK,UAAA,EAAA;AAAA,EACP;AAAA,EAEA,oBAAoB,MAAA,EAA2B;AAC7C,IAAA,IAAA,CAAK,gBAAA,GAAmB,MAAA;AAAA,EAC1B;AAAA,EAEA,WAAA,GAAoB;AAClB,IAAA,IAAA,CAAK,SAAA,CAAU,MAAA,CAAO,EAAE,CAAA;AACxB,IAAA,IAAA,CAAK,UAAA,EAAA;AAAA,EACP;AAAA,EAEA,gBAAgB,YAAA,EAA8B;AAC5C,IAAA,IAAA,CAAK,SAAA,CAAU,UAAU,YAAA,CAAa,GAAA,CAAI,CAAC,KAAA,MAAW,EAAE,OAAM,CAAE,CAAA;AAAA,EAClE;AAAA,EAEA,YAAA,GAAkC;AAChC,IAAA,OAAO,IAAA,CAAK,SAAA;AAAA,EACd;AAAA,EAEQ,UAAA,CAAW,MAAoB,KAAA,EAAwB;AAC7D,IAAA,IAAI,MAAM,IAAA,EAAM;AACd,MAAA,IAAA,CAAK,OAAO,EAAE,GAAG,KAAK,IAAA,EAAM,GAAG,MAAM,IAAA,EAAK;AAAA,IAC5C;AAEA,IAAA,IAAI,MAAM,IAAA,EAAM;AACd,MAAA,IAAA,CAAK,OAAO,KAAA,CAAM,IAAA;AAAA,IACpB;AAEA,IAAA,IAAI,MAAM,SAAA,EAAW;AACnB,MAAA,IAAA,CAAK,YAAY,EAAE,GAAG,KAAK,SAAA,EAAW,GAAG,MAAM,SAAA,EAAU;AAAA,IAC3D;AAEA,IAAA,IAAI,MAAM,MAAA,EAAQ;AAChB,MAAA,IAAA,CAAK,SAAS,EAAE,GAAG,KAAK,MAAA,EAAQ,GAAG,MAAM,MAAA,EAAO;AAAA,IAClD;AAEA,IAAA,IAAI,MAAM,MAAA,EAAQ;AAChB,MAAA,IAAA,CAAK,SAAS,KAAA,CAAM,MAAA;AAAA,IACtB;AAAA,EACF;AACF;;;ACzCO,IAAM,SAAA,GAAY,CAAC,GAAA,KAA2B;AACnD,EAAA,OAAO,EAAE,IAAA,EAAM,CAAA,EAAA,EAAK,GAAG,CAAA,CAAA,EAAG;AAC5B;ACrDO,IAAM,WAAA,GAAc,CAAC,SAAA,KAA8B;AACxD,EAAA,MAAM,QAAA,GAAW,IAAA,CAAK,OAAA,CAAQ,SAAS,CAAA;AACvC,EAAA,IAAI,CAAC,QAAA,EAAU;AACb,IAAA,MAAM,IAAI,KAAA,CAAM,CAAA,kDAAA,EAAqD,SAAS,CAAA,CAAA,CAAG,CAAA;AAAA,EACnF;AAEA,EAAA,OAAO,QAAA;AACT,CAAA;;;ACPO,IAAM,SAAA,GAAY,CAAC,KAAA,KAA8C,KAAA,KAAU,QAAQ,KAAA,KAAU,MAAA;;;ACsB7F,IAAM,sBAAA,GAAyB,CAAC,KAAA,KAA0B;AAC/D,EAAA,MAAM,UAAA,GAAa,EAAA;AACnB,EAAA,MAAM,aAAA,GAAgB,cAAA;AAEtB,EAAA,OAAO,KAAA,CAAM,MAAK,CAAE,OAAA,CAAQ,eAAe,EAAE,CAAA,CAAE,KAAA,CAAM,CAAA,EAAG,UAAU,CAAA;AACpE;AAOA,IAAM,eAAA,GAAkB,CAAC,EAAE,KAAA,EAAO,WAAU,KAAsC;AAChF,EAAA,IAAI,CAAC,SAAA,CAAU,KAAK,CAAA,IAAK,cAAc,QAAA,EAAU;AAC/C,IAAA,MAAM,WAAW,OAAO,KAAA,KAAU,QAAA,GAAW,KAAA,GAAQ,OAAO,KAAK,CAAA;AACjE,IAAA,OAAO,KAAA,CAAM,QAAQ,CAAA,GAAI,KAAA,GAAQ,QAAA;AAAA,EACnC;AAEA,EAAA,OAAO,KAAA,IAAS,EAAA;AAClB,CAAA;AAQA,IAAM,mBAAmB,CAAC,EAAE,OAAA,EAAS,OAAA,EAAS,iBAAgB,KAAyC;AACrG,EAAA,OAAO,OAAA,CAAQ,GAAA,CAAI,CAAC,MAAA,KAAW;AAC7B,IAAA,MAAM,KAAA,GAAQ,QAAQ,MAAM,CAAA;AAC5B,IAAA,MAAM,QAAA,GAAW,kBAAkB,MAAM,CAAA;AACzC,IAAA,MAAM,SAAA,GAAY,UAAU,SAAA,IAAa,MAAA;AACzC,IAAA,OAAO,eAAA,CAAgB,EAAE,KAAA,EAAO,SAAA,EAAW,CAAA;AAAA,EAC7C,CAAC,CAAA;AACH,CAAA;AAQA,IAAM,sBAAsB,CAAC,EAAE,GAAA,EAAK,OAAA,EAAS,iBAAgB,KAAqC;AAChG,EAAA,KAAA,IAAS,QAAA,GAAW,CAAA,EAAG,QAAA,GAAW,OAAA,CAAQ,QAAQ,QAAA,EAAA,EAAY;AAC5D,IAAA,MAAM,MAAA,GAAS,QAAQ,QAAQ,CAAA;AAC/B,IAAA,MAAM,QAAA,GAAW,kBAAkB,MAAM,CAAA;AACzC,IAAA,MAAM,SAAA,GAAY,UAAU,SAAA,IAAa,MAAA;AAEzC,IAAA,IAAI,cAAc,MAAA,EAAQ;AACxB,MAAA,MAAM,IAAA,GAAO,GAAA,CAAI,OAAA,CAAQ,QAAA,GAAW,CAAC,CAAA;AACrC,MAAA,IAAA,CAAK,MAAA,GAAS,GAAA;AAAA,IAChB;AAAA,EACF;AACF,CAAA;AAEA,IAAM,iBAAA,GAAoB,CAAC,SAAA,KAAiC;AAC1D,EAAA,SAAA,CAAU,IAAA,GAAO,EAAE,IAAA,EAAM,IAAA,EAAK;AAC9B,EAAA,SAAA,CAAU,IAAA,GAAO;AAAA,IACf,IAAA,EAAM,SAAA;AAAA,IACN,OAAA,EAAS,OAAA;AAAA,IACT,OAAA,EAAS,EAAE,IAAA,EAAM,UAAA;AAAW,GAC9B;AACA,EAAA,SAAA,CAAU,SAAA,GAAY,EAAE,QAAA,EAAU,IAAA,EAAM,UAAU,KAAA,EAAM;AAC1D,CAAA;AAOA,IAAM,oBAAA,GAAuB,CAAC,EAAE,SAAA,EAAW,SAAQ,KAAsC;AACvF,EAAA,MAAM,SAAA,GAAY,SAAA,CAAU,MAAA,CAAO,OAAO,CAAA;AAC1C,EAAA,iBAAA,CAAkB,SAAS,CAAA;AAC3B,EAAA,SAAA,CAAU,QAAQ,CAAC,EAAE,OAAO,QAAA,EAAU,MAAA,EAAQ,GAAG,CAAA;AACnD,CAAA;AAQA,IAAM,qBAAqB,CAAC,EAAE,SAAA,EAAW,aAAA,EAAe,aAAY,KAAoC;AACtG,EAAA,KAAA,IAAS,QAAA,GAAW,aAAA,EAAe,QAAA,IAAY,WAAA,EAAa,QAAA,EAAA,EAAY;AACtE,IAAA,MAAM,GAAA,GAAM,SAAA,CAAU,MAAA,CAAO,QAAQ,CAAA;AACrC,IAAA,GAAA,CAAI,SAAA,GAAY,EAAE,QAAA,EAAU,KAAA,EAAO,UAAU,KAAA,EAAM;AAAA,EACrD;AACF,CAAA;AAQA,IAAM,kBAAkB,CAAC,EAAE,SAAA,EAAW,OAAA,EAAS,iBAAgB,KAAiC;AAC9F,EAAA,SAAA,CAAU,OAAA,GAAU,OAAA,CAAQ,GAAA,CAAI,CAAC,MAAA,KAAW;AAC1C,IAAA,MAAM,QAAA,GAAW,gBAAgB,MAAM,CAAA;AACvC,IAAA,OAAO,WAAW,EAAE,KAAA,EAAO,QAAA,CAAS,KAAA,KAAU,EAAC;AAAA,EACjD,CAAC,CAAA;AACH,CAAA;AASA,IAAM,cAAc,CAAC,EAAE,WAAW,OAAA,EAAS,eAAA,EAAiB,MAAK,KAA6B;AAC5F,EAAA,KAAA,MAAW,WAAW,IAAA,EAAM;AAC1B,IAAA,MAAM,iBAAiB,gBAAA,CAAiB,EAAE,OAAA,EAAS,OAAA,EAAS,iBAAiB,CAAA;AAC7E,IAAA,MAAM,GAAA,GAAM,SAAA,CAAU,MAAA,CAAO,cAAc,CAAA;AAC3C,IAAA,mBAAA,CAAoB,EAAE,GAAA,EAAK,OAAA,EAAS,eAAA,EAAiB,CAAA;AAAA,EACvD;AAEA,EAAA,kBAAA,CAAmB,EAAE,WAAW,aAAA,EAAe,CAAA,EAAG,aAAa,IAAA,CAAK,MAAA,GAAS,GAAG,CAAA;AAClF,CAAA;AAYO,IAAM,iBAAA,GAAoB,OAAO,IAAA,KAA+C;AACrF,EAAA,MAAM,EAAE,IAAA,EAAM,eAAA,EAAiB,cAAA,EAAe,GAAI,IAAA;AAElD,EAAA,IAAI,IAAA,CAAK,WAAW,CAAA,EAAG;AACrB,IAAA,MAAM,IAAI,MAAM,mBAAmB,CAAA;AAAA,EACrC;AAEA,EAAA,MAAM,OAAA,GAAU,MAAA,CAAO,IAAA,CAAK,IAAA,CAAK,CAAC,CAAC,CAAA;AACnC,EAAA,MAAM,QAAA,GAAW,IAAI,OAAA,CAAQ,QAAA,EAAS;AACtC,EAAA,MAAM,SAAA,GAAY,QAAA,CAAS,YAAA,CAAa,sBAAA,CAAuB,cAAc,CAAC,CAAA;AAE9E,EAAA,oBAAA,CAAqB,EAAE,SAAA,EAAW,OAAA,EAAS,CAAA;AAC3C,EAAA,WAAA,CAAY,EAAE,SAAA,EAAW,OAAA,EAAS,eAAA,EAAiB,MAAM,CAAA;AACzD,EAAA,eAAA,CAAgB,EAAE,SAAA,EAAW,OAAA,EAAS,eAAA,EAAiB,CAAA;AAEvD,EAAA,MAAM,MAAA,GAAS,MAAM,QAAA,CAAS,IAAA,CAAK,WAAA,EAAY;AAC/C,EAAA,OAAO,IAAI,IAAA,CAAK,CAAC,MAAM,CAAA,EAAG,EAAE,IAAA,EAAM,WAAA,CAAY,MAAM,CAAA,EAAG,CAAA;AACzD","file":"excel.js","sourcesContent":["import ExcelJS from \"exceljs\";\nimport type { CellStyle, CellValue } from \"./excel-generator.types\";\n\ninterface AddCellArgs {\n  row: number;\n  col: number;\n  value: CellValue;\n  style?: CellStyle;\n}\n\ninterface AddRowArgs {\n  values: CellValue[];\n  styles?: CellStyle[];\n}\n\nexport class WorksheetBuilder {\n  private worksheet: ExcelJS.Worksheet;\n  private currentRow: number;\n  private defaultRowStyles: CellStyle[];\n\n  constructor(worksheet: ExcelJS.Worksheet) {\n    this.worksheet = worksheet;\n    this.currentRow = 1; // ExcelJS uses 1-based indexing\n    this.defaultRowStyles = [];\n  }\n\n  /** Returns the current row index (1-based). */\n  get rowCount(): number {\n    return this.currentRow;\n  }\n\n  addCell({ row, col, value, style }: AddCellArgs): void {\n    const cell = this.worksheet.getCell(row + 1, col + 1); // Convert to 1-based\n    cell.value = value ?? \"\";\n\n    if (style) {\n      this.applyStyle(cell, style);\n    }\n  }\n\n  addRow({ values, styles }: AddRowArgs): void {\n    const stylesToUse = styles ?? this.defaultRowStyles;\n    const row = this.worksheet.addRow(values);\n\n    // Apply styles to each cell in the row\n    for (let col = 0; col < values.length; col++) {\n      const style = stylesToUse[col];\n      if (style) {\n        const cell = row.getCell(col + 1); // ExcelJS uses 1-based indexing\n        this.applyStyle(cell, style);\n      }\n    }\n\n    this.currentRow++;\n  }\n\n  setDefaultRowStyles(styles: CellStyle[]): void {\n    this.defaultRowStyles = styles;\n  }\n\n  addEmptyRow(): void {\n    this.worksheet.addRow([]);\n    this.currentRow++;\n  }\n\n  setColumnWidths(columnWidths: number[]): void {\n    this.worksheet.columns = columnWidths.map((width) => ({ width }));\n  }\n\n  getWorksheet(): ExcelJS.Worksheet {\n    return this.worksheet;\n  }\n\n  private applyStyle(cell: ExcelJS.Cell, style: CellStyle): void {\n    if (style.font) {\n      cell.font = { ...cell.font, ...style.font };\n    }\n\n    if (style.fill) {\n      cell.fill = style.fill as ExcelJS.Fill;\n    }\n\n    if (style.alignment) {\n      cell.alignment = { ...cell.alignment, ...style.alignment };\n    }\n\n    if (style.border) {\n      cell.border = { ...cell.border, ...style.border };\n    }\n\n    if (style.numFmt) {\n      cell.numFmt = style.numFmt;\n    }\n  }\n}\n","import type { Font, Fill, Alignment } from \"exceljs\";\n\nexport type CellValue = string | number | null | undefined;\n\nexport type VerticalAlignment = \"top\" | \"middle\" | \"bottom\";\nexport type HorizontalAlignment = \"left\" | \"center\" | \"right\";\n\nexport type ColumnValueType = \"number\" | \"text\" | \"auto\";\n\nexport interface ColumnMetadata {\n  name: string;\n  width: number;\n  valueType?: ColumnValueType;\n}\n\ninterface BorderSide {\n  style?: \"thin\" | \"medium\" | \"thick\" | \"dotted\" | \"dashed\" | \"double\";\n  color?: { argb: string };\n}\n\n/**\n * Type for ExcelJS cell borders.\n */\nexport interface CellBorder {\n  top?: BorderSide;\n  bottom?: BorderSide;\n  left?: BorderSide;\n  right?: BorderSide;\n}\n\n/**\n * Type for ExcelJS cell styles.\n * This is a simplified version of ExcelJS.Style that focuses on commonly used properties.\n */\nexport interface CellStyle {\n  font?: Partial<Font>;\n  fill?: Partial<Fill>;\n  alignment?: Partial<Alignment>;\n  border?: CellBorder;\n  numFmt?: string;\n}\n\n/**\n * Helper type to convert RGB color string to ARGB format for ExcelJS.\n * ExcelJS uses ARGB format: \"FFFFFFFF\" where FF is alpha, then RGB.\n */\nexport type ArgbColor = { argb: string };\n\n/**\n * Helper function to convert RGB color string to ARGB format.\n * @param rgb - RGB color string without # (e.g., \"FFFFFF\")\n * @returns ARGB color object (e.g., { argb: \"FFFFFFFF\" })\n */\nexport const rgbToArgb = (rgb: string): ArgbColor => {\n  return { argb: `FF${rgb}` };\n};\n","import mime from \"mime\";\n\nexport const getMimeType = (extension: string): string => {\n  const mimeType = mime.getType(extension);\n  if (!mimeType) {\n    throw new Error(`[getMimeType] Mime type not found for extension: \"${extension}\"`);\n  }\n\n  return mimeType;\n};\n","export const NO_OP: () => void = () => {};\n\nexport const isNullish = (value: unknown): value is null | undefined => value === null || value === undefined;\n\nexport const isNumber = (value?: unknown | null): value is number => {\n  if (isNullish(value)) {\n    return false;\n  }\n\n  if (typeof value !== 'number') {\n    return false;\n  }\n\n  if (isNaN(value)) {\n    return false;\n  }\n\n  return true;\n};\n\nexport const isString = (value?: unknown | null): value is string => {\n  if (isNullish(value)) {\n    return false;\n  }\n\n  if (typeof value !== 'string') {\n    return false;\n  }\n\n  return true;\n};\n","import ExcelJS from \"exceljs\";\nimport { getMimeType } from \"../mime\";\nimport { isNullish } from \"../utils\";\nimport type { CellValue, ColumnMetadata } from \"./excel-generator.types\";\n\n/**\n * Sanitizes a worksheet title to comply with Excel's limitations.\n *\n * Excel enforces strict rules for worksheet names:\n * - Maximum length of 31 characters (legacy limitation from older Excel versions)\n * - Certain characters are reserved for special purposes and cannot be used:\n *   - `:` (colon) - used in cell range references (e.g., A1:B2)\n *   - `/` (forward slash) - used in file paths\n *   - `\\` (backslash) - used in file paths and escape sequences\n *   - `?` (question mark) - used as wildcard in formulas\n *   - `*` (asterisk) - used as wildcard in formulas\n *   - `[` and `]` (square brackets) - used in external references (e.g., [Book1.xlsx]Sheet1!A1)\n *\n * This function removes invalid characters and truncates the title to 31 characters\n * to ensure compatibility with Excel's file format specifications.\n *\n * @param title - The original worksheet title to sanitize\n * @returns A sanitized title that complies with Excel's naming rules\n */\nexport const sanitizeWorksheetTitle = (title: string): string => {\n  const MAX_LENGTH = 31;\n  const INVALID_CHARS = /[:/\\\\?*[\\]]/g;\n\n  return title.trim().replace(INVALID_CHARS, \"\").slice(0, MAX_LENGTH);\n};\n\ninterface ToSafeCellValueArgs {\n  value: CellValue;\n  valueType: ColumnMetadata[\"valueType\"];\n}\n\nconst toSafeCellValue = ({ value, valueType }: ToSafeCellValueArgs): CellValue => {\n  if (!isNullish(value) && valueType === \"number\") {\n    const numValue = typeof value === \"number\" ? value : Number(value);\n    return isNaN(numValue) ? value : numValue;\n  }\n\n  return value ?? \"\";\n};\n\ninterface ToSafeCellValuesArgs {\n  headers: string[];\n  rowData: Record<string, CellValue>;\n  columnsMetadata?: Record<string, ColumnMetadata>;\n}\n\nconst toSafeCellValues = ({ headers, rowData, columnsMetadata }: ToSafeCellValuesArgs): CellValue[] => {\n  return headers.map((header) => {\n    const value = rowData[header];\n    const metadata = columnsMetadata?.[header];\n    const valueType = metadata?.valueType ?? \"auto\";\n    return toSafeCellValue({ value, valueType });\n  });\n};\n\ninterface ApplyTextFormattingArgs {\n  row: ExcelJS.Row;\n  headers: string[];\n  columnsMetadata?: Record<string, ColumnMetadata>;\n}\n\nconst applyTextFormatting = ({ row, headers, columnsMetadata }: ApplyTextFormattingArgs): void => {\n  for (let colIndex = 0; colIndex < headers.length; colIndex++) {\n    const header = headers[colIndex];\n    const metadata = columnsMetadata?.[header];\n    const valueType = metadata?.valueType ?? \"auto\";\n\n    if (valueType === \"text\") {\n      const cell = row.getCell(colIndex + 1);\n      cell.numFmt = \"@\";\n    }\n  }\n};\n\nconst applyHeaderStyles = (headerRow: ExcelJS.Row): void => {\n  headerRow.font = { bold: true };\n  headerRow.fill = {\n    type: \"pattern\",\n    pattern: \"solid\",\n    fgColor: { argb: \"FFE0E0E0\" },\n  };\n  headerRow.alignment = { wrapText: true, vertical: \"top\" };\n};\n\ninterface SetupHeaderFrozenRowArgs {\n  worksheet: ExcelJS.Worksheet;\n  headers: string[];\n}\n\nconst setupHeaderFrozenRow = ({ worksheet, headers }: SetupHeaderFrozenRowArgs): void => {\n  const headerRow = worksheet.addRow(headers);\n  applyHeaderStyles(headerRow);\n  worksheet.views = [{ state: \"frozen\", ySplit: 1 }];\n};\n\ninterface ApplyDataRowStylesArgs {\n  worksheet: ExcelJS.Worksheet;\n  startRowIndex: number;\n  endRowIndex: number;\n}\n\nconst applyDataRowStyles = ({ worksheet, startRowIndex, endRowIndex }: ApplyDataRowStylesArgs): void => {\n  for (let rowIndex = startRowIndex; rowIndex <= endRowIndex; rowIndex++) {\n    const row = worksheet.getRow(rowIndex);\n    row.alignment = { wrapText: false, vertical: \"top\" };\n  }\n};\n\ninterface SetColumnWidthsArgs {\n  worksheet: ExcelJS.Worksheet;\n  headers: string[];\n  columnsMetadata: Record<string, ColumnMetadata>;\n}\n\nconst setColumnWidths = ({ worksheet, headers, columnsMetadata }: SetColumnWidthsArgs): void => {\n  worksheet.columns = headers.map((header) => {\n    const metadata = columnsMetadata[header];\n    return metadata ? { width: metadata.width } : {};\n  });\n};\n\ninterface AddDataRowsArgs {\n  worksheet: ExcelJS.Worksheet;\n  headers: string[];\n  columnsMetadata: Record<string, ColumnMetadata>;\n  data: Record<string, CellValue>[];\n}\n\nconst addDataRows = ({ worksheet, headers, columnsMetadata, data }: AddDataRowsArgs): void => {\n  for (const rowData of data) {\n    const safeCellValues = toSafeCellValues({ headers, rowData, columnsMetadata });\n    const row = worksheet.addRow(safeCellValues);\n    applyTextFormatting({ row, headers, columnsMetadata });\n  }\n\n  applyDataRowStyles({ worksheet, startRowIndex: 2, endRowIndex: data.length + 1 });\n};\n\ninterface GenerateExcelBlobArgs {\n  worksheetTitle: string;\n  data: Record<string, CellValue>[];\n  /**\n   * Metadata for columns, keyed by column name (translated header name).\n   * If not provided, columns will use default width and auto-detect value types.\n   */\n  columnsMetadata: Record<string, ColumnMetadata>;\n}\n\nexport const generateExcelBlob = async (args: GenerateExcelBlobArgs): Promise<Blob> => {\n  const { data, columnsMetadata, worksheetTitle } = args;\n\n  if (data.length === 0) {\n    throw new Error(\"No data to export\");\n  }\n\n  const headers = Object.keys(data[0]);\n  const workbook = new ExcelJS.Workbook();\n  const worksheet = workbook.addWorksheet(sanitizeWorksheetTitle(worksheetTitle));\n\n  setupHeaderFrozenRow({ worksheet, headers });\n  addDataRows({ worksheet, headers, columnsMetadata, data });\n  setColumnWidths({ worksheet, headers, columnsMetadata });\n\n  const buffer = await workbook.xlsx.writeBuffer();\n  return new Blob([buffer], { type: getMimeType(\"xlsx\") });\n};\n"]}

package/dist/index.cjs

@@ -1,94 +1,6 @@
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+'use strict';
 
-// src/index.ts
-var index_exports = {};
-__export(index_exports, {
-  HZ_TO_RPM: () => HZ_TO_RPM,
-  M3PS_TO_GPM: () => M3PS_TO_GPM,
-  M_TO_INCHES: () => M_TO_INCHES,
-  NO_OP: () => NO_OP,
-  PA_TO_FT: () => PA_TO_FT,
-  PeriodsInMS: () => PeriodsInMS,
-  REGEX_ALPHANUMERIC: () => REGEX_ALPHANUMERIC,
-  REGEX_IPV4: () => REGEX_IPV4,
-  SCHEME_PREFIXES: () => SCHEME_PREFIXES,
-  W_TO_HP: () => W_TO_HP,
-  buildTicksForChart: () => buildTicksForChart,
-  capitalizeFirst: () => capitalizeFirst,
-  closeWebSocket: () => closeWebSocket,
-  countWords: () => countWords,
-  dateAs_HHMMSS: () => dateAs_HHMMSS,
-  dateAs_YYYYMMDD: () => dateAs_YYYYMMDD,
-  dateAs_YYYYMMDD_HHMMSS: () => dateAs_YYYYMMDD_HHMMSS,
-  extractBase64FromDataUri: () => extractBase64FromDataUri,
-  formatUnixTimestamp: () => formatUnixTimestamp,
-  fromHzToRpm: () => fromHzToRpm,
-  fromM3psToGPM: () => fromM3psToGPM,
-  fromMToInches: () => fromMToInches,
-  fromPaToFt: () => fromPaToFt,
-  fromWToHp: () => fromWToHp,
-  getColorForPercentage: () => getColorForPercentage,
-  getContrastTextColor: () => getContrastTextColor,
-  getCurrentUnixTimestamp: () => getCurrentUnixTimestamp,
-  getErrorMessage: () => getErrorMessage,
-  getLuminance: () => getLuminance,
-  getOpacityHexValue: () => getOpacityHexValue,
-  getOrderOfMagnitudeExponent: () => getOrderOfMagnitudeExponent,
-  getTickDomain: () => getTickDomain,
-  hasScheme: () => hasScheme,
-  hexToNormalizedRgb: () => hexToNormalizedRgb,
-  hexToRgb: () => hexToRgb,
-  isActiveTimestamp: () => isActiveTimestamp,
-  isAlphanumeric: () => isAlphanumeric,
-  isBlank: () => isBlank,
-  isExpiredTimestamp: () => isExpiredTimestamp,
-  isHttpClientErrorStatus: () => isHttpClientErrorStatus,
-  isHttpServerErrorStatus: () => isHttpServerErrorStatus,
-  isHttpSuccessStatus: () => isHttpSuccessStatus,
-  isLightColor: () => isLightColor,
-  isNotBlank: () => isNotBlank,
-  isNullish: () => isNullish,
-  isNumber: () => isNumber,
-  isString: () => isString,
-  isWsClosable: () => isWsClosable,
-  isWsOpenOrConnecting: () => isWsOpenOrConnecting,
-  nowAsDate: () => nowAsDate,
-  nowAsDateTime: () => nowAsDateTime,
-  nowAsDateTimeForFilename: () => nowAsDateTimeForFilename,
-  nowAsTime: () => nowAsTime,
-  removeDiacriticalMarks: () => removeDiacriticalMarks,
-  rgbToHex: () => rgbToHex,
-  rgbToString: () => rgbToString,
-  rgbaToHex: () => rgbaToHex,
-  rgbaToHexWithAlpha: () => rgbaToHexWithAlpha,
-  rgbaToString: () => rgbaToString,
-  roundToNiceNumber: () => roundToNiceNumber,
-  roundUpToNearest10: () => roundUpToNearest10,
-  sleep: () => sleep,
-  tickFormatter: () => tickFormatter,
-  toFixed: () => toFixed,
-  toToleranceLabel: () => toToleranceLabel,
-  tooltipValueFormatter: () => tooltipValueFormatter,
-  truncate: () => truncate
-});
-module.exports = __toCommonJS(index_exports);
+var dateFns = require('date-fns');
 
 // src/utils/types.utils.ts
 var NO_OP = () => {
@@ -246,32 +158,29 @@ var getColorForPercentage = (percent) => {
   };
   return "rgb(" + [color.r, color.g, color.b].join(",") + ")";
 };
-
-// src/utils/date.utils.ts
-var import_date_fns = require("date-fns");
 var dateAs_HHMMSS = (value) => {
   if (isNullish(value)) return "";
-  return (0, import_date_fns.format)(value, "HH:mm:ss");
+  return dateFns.format(value, "HH:mm:ss");
 };
 var dateAs_YYYYMMDD = (value) => {
   if (isNullish(value)) return "";
-  return (0, import_date_fns.format)(value, "yyyy-MM-dd");
+  return dateFns.format(value, "yyyy-MM-dd");
 };
 var dateAs_YYYYMMDD_HHMMSS = (value) => {
   if (isNullish(value)) return "";
-  return (0, import_date_fns.format)(value, "yyyy-MM-dd HH:mm:ss");
+  return dateFns.format(value, "yyyy-MM-dd HH:mm:ss");
 };
 var nowAsTime = () => dateAs_HHMMSS(/* @__PURE__ */ new Date());
 var nowAsDate = () => dateAs_YYYYMMDD(/* @__PURE__ */ new Date());
 var nowAsDateTime = () => dateAs_YYYYMMDD_HHMMSS(/* @__PURE__ */ new Date());
 var nowAsDateTimeForFilename = () => {
-  return (0, import_date_fns.format)(/* @__PURE__ */ new Date(), "yyyy-MM-dd_HH-mm-ss");
+  return dateFns.format(/* @__PURE__ */ new Date(), "yyyy-MM-dd_HH-mm-ss");
 };
 var DEFAULT_DATE_FORMAT = "yyyy-MM-dd HH:mm:ss";
 var formatUnixTimestamp = (timestamp, dateFormat = DEFAULT_DATE_FORMAT) => {
   if (!timestamp) return "N/A";
   try {
-    return (0, import_date_fns.format)(new Date(timestamp * 1e3), dateFormat);
+    return dateFns.format(new Date(timestamp * 1e3), dateFormat);
   } catch {
     return "Invalid date";
   }
@@ -322,29 +231,6 @@ var isHttpServerErrorStatus = (status) => {
   return status >= 500;
 };
 
-// src/utils/number.utils.ts
-var toFixed = (value, decimals = 0) => {
-  if (isNullish(value)) return 0;
-  if (decimals < 0) throw new Error("[toFixed] decimals must be >= 0");
-  if (decimals === 0) return Math.round(value);
-  const multiplier = Math.pow(10, decimals);
-  return Math.round(value * multiplier) / multiplier;
-};
-var roundUpToNearest10 = (value) => {
-  if (isNullish(value)) return 0;
-  return Math.ceil(value / 10) * 10;
-};
-var getOrderOfMagnitudeExponent = (n) => {
-  if (isNullish(n)) return 0;
-  if (!isNumber(n)) return 0;
-  const absValue = Math.abs(n);
-  if (absValue === 0) {
-    return 0;
-  }
-  const integerPart = Math.floor(absValue);
-  return Math.floor(Math.log10(integerPart));
-};
-
 // src/utils/regex.ts
 var REGEX_ALPHANUMERIC = /^[a-zA-Z0-9-_ $%#(){}:/.]+$/;
 var REGEX_IPV4 = /^(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/;
@@ -378,8 +264,43 @@ var truncate = (str, maxLength, ellipsis = "...") => {
   return str.slice(0, maxLength - ellipsis.length) + ellipsis;
 };
 
+// src/utils/number.utils.ts
+var isInputValidNumber = (value) => {
+  if (isBlank(value)) return false;
+  const num = Number(value.trim());
+  return Number.isFinite(num);
+};
+var isInputValidInteger = (value) => {
+  if (!isInputValidNumber(value)) return false;
+  const num = Number(value.trim());
+  return Number.isInteger(num);
+};
+var formatIntegerDisplay = (value) => String(toFixed(value, 0));
+var toFixed = (value, decimals = 0) => {
+  if (isNullish(value)) return 0;
+  if (decimals < 0) throw new Error("[toFixed] decimals must be >= 0");
+  if (decimals === 0) return Math.round(value);
+  const multiplier = Math.pow(10, decimals);
+  return Math.round(value * multiplier) / multiplier;
+};
+var roundUpToNearest10 = (value) => {
+  if (isNullish(value)) return 0;
+  return Math.ceil(value / 10) * 10;
+};
+var getOrderOfMagnitudeExponent = (n) => {
+  if (isNullish(n)) return 0;
+  if (!isNumber(n)) return 0;
+  const absValue = Math.abs(n);
+  if (absValue === 0) {
+    return 0;
+  }
+  const integerPart = Math.floor(absValue);
+  return Math.floor(Math.log10(integerPart));
+};
+
 // src/utils/thread.utils.ts
 var sleep = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+var yieldToMainThread = () => sleep(0);
 
 // src/utils/time.utils.ts
 var ONE_SECOND_IN_MS = 1e3;
@@ -460,74 +381,77 @@ var closeWebSocket = (ws) => {
   } catch {
   }
 };
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  HZ_TO_RPM,
-  M3PS_TO_GPM,
-  M_TO_INCHES,
-  NO_OP,
-  PA_TO_FT,
-  PeriodsInMS,
-  REGEX_ALPHANUMERIC,
-  REGEX_IPV4,
-  SCHEME_PREFIXES,
-  W_TO_HP,
-  buildTicksForChart,
-  capitalizeFirst,
-  closeWebSocket,
-  countWords,
-  dateAs_HHMMSS,
-  dateAs_YYYYMMDD,
-  dateAs_YYYYMMDD_HHMMSS,
-  extractBase64FromDataUri,
-  formatUnixTimestamp,
-  fromHzToRpm,
-  fromM3psToGPM,
-  fromMToInches,
-  fromPaToFt,
-  fromWToHp,
-  getColorForPercentage,
-  getContrastTextColor,
-  getCurrentUnixTimestamp,
-  getErrorMessage,
-  getLuminance,
-  getOpacityHexValue,
-  getOrderOfMagnitudeExponent,
-  getTickDomain,
-  hasScheme,
-  hexToNormalizedRgb,
-  hexToRgb,
-  isActiveTimestamp,
-  isAlphanumeric,
-  isBlank,
-  isExpiredTimestamp,
-  isHttpClientErrorStatus,
-  isHttpServerErrorStatus,
-  isHttpSuccessStatus,
-  isLightColor,
-  isNotBlank,
-  isNullish,
-  isNumber,
-  isString,
-  isWsClosable,
-  isWsOpenOrConnecting,
-  nowAsDate,
-  nowAsDateTime,
-  nowAsDateTimeForFilename,
-  nowAsTime,
-  removeDiacriticalMarks,
-  rgbToHex,
-  rgbToString,
-  rgbaToHex,
-  rgbaToHexWithAlpha,
-  rgbaToString,
-  roundToNiceNumber,
-  roundUpToNearest10,
-  sleep,
-  tickFormatter,
-  toFixed,
-  toToleranceLabel,
-  tooltipValueFormatter,
-  truncate
-});
+
+exports.HZ_TO_RPM = HZ_TO_RPM;
+exports.M3PS_TO_GPM = M3PS_TO_GPM;
+exports.M_TO_INCHES = M_TO_INCHES;
+exports.NO_OP = NO_OP;
+exports.PA_TO_FT = PA_TO_FT;
+exports.PeriodsInMS = PeriodsInMS;
+exports.REGEX_ALPHANUMERIC = REGEX_ALPHANUMERIC;
+exports.REGEX_IPV4 = REGEX_IPV4;
+exports.SCHEME_PREFIXES = SCHEME_PREFIXES;
+exports.W_TO_HP = W_TO_HP;
+exports.buildTicksForChart = buildTicksForChart;
+exports.capitalizeFirst = capitalizeFirst;
+exports.closeWebSocket = closeWebSocket;
+exports.countWords = countWords;
+exports.dateAs_HHMMSS = dateAs_HHMMSS;
+exports.dateAs_YYYYMMDD = dateAs_YYYYMMDD;
+exports.dateAs_YYYYMMDD_HHMMSS = dateAs_YYYYMMDD_HHMMSS;
+exports.extractBase64FromDataUri = extractBase64FromDataUri;
+exports.formatIntegerDisplay = formatIntegerDisplay;
+exports.formatUnixTimestamp = formatUnixTimestamp;
+exports.fromHzToRpm = fromHzToRpm;
+exports.fromM3psToGPM = fromM3psToGPM;
+exports.fromMToInches = fromMToInches;
+exports.fromPaToFt = fromPaToFt;
+exports.fromWToHp = fromWToHp;
+exports.getColorForPercentage = getColorForPercentage;
+exports.getContrastTextColor = getContrastTextColor;
+exports.getCurrentUnixTimestamp = getCurrentUnixTimestamp;
+exports.getErrorMessage = getErrorMessage;
+exports.getLuminance = getLuminance;
+exports.getOpacityHexValue = getOpacityHexValue;
+exports.getOrderOfMagnitudeExponent = getOrderOfMagnitudeExponent;
+exports.getTickDomain = getTickDomain;
+exports.hasScheme = hasScheme;
+exports.hexToNormalizedRgb = hexToNormalizedRgb;
+exports.hexToRgb = hexToRgb;
+exports.isActiveTimestamp = isActiveTimestamp;
+exports.isAlphanumeric = isAlphanumeric;
+exports.isBlank = isBlank;
+exports.isExpiredTimestamp = isExpiredTimestamp;
+exports.isHttpClientErrorStatus = isHttpClientErrorStatus;
+exports.isHttpServerErrorStatus = isHttpServerErrorStatus;
+exports.isHttpSuccessStatus = isHttpSuccessStatus;
+exports.isInputValidInteger = isInputValidInteger;
+exports.isInputValidNumber = isInputValidNumber;
+exports.isLightColor = isLightColor;
+exports.isNotBlank = isNotBlank;
+exports.isNullish = isNullish;
+exports.isNumber = isNumber;
+exports.isString = isString;
+exports.isWsClosable = isWsClosable;
+exports.isWsOpenOrConnecting = isWsOpenOrConnecting;
+exports.nowAsDate = nowAsDate;
+exports.nowAsDateTime = nowAsDateTime;
+exports.nowAsDateTimeForFilename = nowAsDateTimeForFilename;
+exports.nowAsTime = nowAsTime;
+exports.removeDiacriticalMarks = removeDiacriticalMarks;
+exports.rgbToHex = rgbToHex;
+exports.rgbToString = rgbToString;
+exports.rgbaToHex = rgbaToHex;
+exports.rgbaToHexWithAlpha = rgbaToHexWithAlpha;
+exports.rgbaToString = rgbaToString;
+exports.roundToNiceNumber = roundToNiceNumber;
+exports.roundUpToNearest10 = roundUpToNearest10;
+exports.sleep = sleep;
+exports.tickFormatter = tickFormatter;
+exports.toFixed = toFixed;
+exports.toToleranceLabel = toToleranceLabel;
+exports.tooltipValueFormatter = tooltipValueFormatter;
+exports.truncate = truncate;
+exports.yieldToMainThread = yieldToMainThread;
+//# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map