@lichens-innovation/ts-common 1.8.0 → 1.9.0

package/README.md

@@ -2,6 +2,8 @@
 
 Reusable generic typescript utilities, types, constants, helpers
 
+> **Note:** The default export is **pure TypeScript** and **environment-agnostic**—it has no dependency on Node.js, browser, or React Native APIs, so the same code runs in any of these runtimes. Subpath imports such as `@lichens-innovation/ts-common/web` target a specific environment and rely on its APIs.
+
 <!-- Package & Status -->
 [![npm version](https://img.shields.io/npm/v/@lichens-innovation/ts-common.svg?style=flat-square)](https://www.npmjs.com/package/@lichens-innovation/ts-common)
 [![npm downloads](https://img.shields.io/npm/dm/@lichens-innovation/ts-common.svg?style=flat-square)](https://www.npmjs.com/package/@lichens-innovation/ts-common)
@@ -27,6 +29,12 @@ Table of content
 - [ts-common](#ts-common)
   - [Prerequisites](#prerequisites)
   - [Scripts](#scripts)
+  - [Optional modules](#optional-modules)
+    - [Excel (`@lichens-innovation/ts-common/excel`)](#excel-lichens-innovationts-commonexcel)
+    - [CSV (`@lichens-innovation/ts-common/csv`)](#csv-lichens-innovationts-commoncsv)
+    - [PDF (`@lichens-innovation/ts-common/pdf`)](#pdf-lichens-innovationts-commonpdf)
+    - [Web (`@lichens-innovation/ts-common/web`)](#web-lichens-innovationts-commonweb)
+    - [MIME (`@lichens-innovation/ts-common/mime`)](#mime-lichens-innovationts-commonmime)
   - [Contributions](#contributions)
   - [Unit tests](#unit-tests)
   - [Library semantic versioning](#library-semantic-versioning)
@@ -50,6 +58,38 @@ Table of content
 | `yarn test:coverage`         | Runs tests with coverage report using Vitest                                |
 | `yarn test:watch`            | Runs tests in watch mode using Vitest                                       |
 
+## Optional modules
+
+This library provides optional subpath modules with external dependencies. Install only the dependencies you need.
+
+### Excel (`@lichens-innovation/ts-common/excel`)
+
+```bash
+npm install exceljs mime
+```
+
+### CSV (`@lichens-innovation/ts-common/csv`)
+
+```bash
+npm install papaparse mime
+```
+
+### PDF (`@lichens-innovation/ts-common/pdf`)
+
+```bash
+npm install jspdf jspdf-autotable
+```
+
+### Web (`@lichens-innovation/ts-common/web`)
+
+No external dependency required.
+
+### MIME (`@lichens-innovation/ts-common/mime`)
+
+```bash
+npm install mime
+```
+
 ## Contributions
 
 Contributions to the project are made by simply improving the current codebase and then creating a Pull Request. If the version field in `package.json` is incremented, the build will be automatically triggered when the PR is merged into the `main` branch, and the new version will be published to our enterprise Git repository.

package/dist/csv.cjs

@@ -0,0 +1,37 @@
+'use strict';
+
+var Papa = require('papaparse');
+var mime = require('mime');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var Papa__default = /*#__PURE__*/_interopDefault(Papa);
+var mime__default = /*#__PURE__*/_interopDefault(mime);
+
+// src/csv/index.ts
+var getMimeType = (extension) => {
+  const mimeType = mime__default.default.getType(extension);
+  if (!mimeType) {
+    throw new Error(`[getMimeType] Mime type not found for extension: "${extension}"`);
+  }
+  return mimeType;
+};
+
+// src/csv/index.ts
+var convertToCsvRow = (row) => {
+  const stringRow = {};
+  for (const [key, value] of Object.entries(row)) {
+    stringRow[key] = String(value ?? "");
+  }
+  return stringRow;
+};
+var generateCsvBlob = (data) => {
+  const rows = data.map(convertToCsvRow);
+  const csv = Papa__default.default.unparse(rows, { header: true, delimiter: "," });
+  return new Blob([csv], { type: getMimeType("csv") });
+};
+
+exports.convertToCsvRow = convertToCsvRow;
+exports.generateCsvBlob = generateCsvBlob;
+//# sourceMappingURL=csv.cjs.map
+//# sourceMappingURL=csv.cjs.map

package/dist/csv.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/mime/index.ts","../src/csv/index.ts"],"names":["mime","Papa"],"mappings":";;;;;;;;;;;AAEO,IAAM,WAAA,GAAc,CAAC,SAAA,KAA8B;AACxD,EAAA,MAAM,QAAA,GAAWA,qBAAA,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;;;ACJO,IAAM,eAAA,GAAkB,CAAC,GAAA,KAA2D;AACzF,EAAA,MAAM,YAAoC,EAAC;AAE3C,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,GAAG,CAAA,EAAG;AAC9C,IAAA,SAAA,CAAU,GAAG,CAAA,GAAI,MAAA,CAAO,KAAA,IAAS,EAAE,CAAA;AAAA,EACrC;AAEA,EAAA,OAAO,SAAA;AACT;AAEO,IAAM,eAAA,GAAkB,CAAC,IAAA,KAA4C;AAC1E,EAAA,MAAM,IAAA,GAAiC,IAAA,CAAK,GAAA,CAAI,eAAe,CAAA;AAC/D,EAAA,MAAM,GAAA,GAAMC,sBAAK,OAAA,CAAQ,IAAA,EAAM,EAAE,MAAA,EAAQ,IAAA,EAAM,SAAA,EAAW,GAAA,EAAK,CAAA;AAE/D,EAAA,OAAO,IAAI,IAAA,CAAK,CAAC,GAAG,CAAA,EAAG,EAAE,IAAA,EAAM,WAAA,CAAY,KAAK,CAAA,EAAG,CAAA;AACrD","file":"csv.cjs","sourcesContent":["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","import Papa from \"papaparse\";\nimport { getMimeType } from \"../mime\";\n\nexport type CellValue = string | number | null | undefined;\n\nexport const convertToCsvRow = (row: Record<string, CellValue>): Record<string, string> => {\n  const stringRow: Record<string, string> = {};\n\n  for (const [key, value] of Object.entries(row)) {\n    stringRow[key] = String(value ?? \"\");\n  }\n\n  return stringRow;\n};\n\nexport const generateCsvBlob = (data: Record<string, CellValue>[]): Blob => {\n  const rows: Record<string, string>[] = data.map(convertToCsvRow);\n  const csv = Papa.unparse(rows, { header: true, delimiter: \",\" });\n\n  return new Blob([csv], { type: getMimeType(\"csv\") });\n};\n"]}

package/dist/csv.d.cts

@@ -0,0 +1,5 @@
+type CellValue = string | number | null | undefined;
+declare const convertToCsvRow: (row: Record<string, CellValue>) => Record<string, string>;
+declare const generateCsvBlob: (data: Record<string, CellValue>[]) => Blob;
+
+export { type CellValue, convertToCsvRow, generateCsvBlob };

package/dist/csv.d.ts

@@ -0,0 +1,5 @@
+type CellValue = string | number | null | undefined;
+declare const convertToCsvRow: (row: Record<string, CellValue>) => Record<string, string>;
+declare const generateCsvBlob: (data: Record<string, CellValue>[]) => Blob;
+
+export { type CellValue, convertToCsvRow, generateCsvBlob };

package/dist/csv.js

@@ -0,0 +1,29 @@
+import Papa from 'papaparse';
+import mime from 'mime';
+
+// src/csv/index.ts
+var getMimeType = (extension) => {
+  const mimeType = mime.getType(extension);
+  if (!mimeType) {
+    throw new Error(`[getMimeType] Mime type not found for extension: "${extension}"`);
+  }
+  return mimeType;
+};
+
+// src/csv/index.ts
+var convertToCsvRow = (row) => {
+  const stringRow = {};
+  for (const [key, value] of Object.entries(row)) {
+    stringRow[key] = String(value ?? "");
+  }
+  return stringRow;
+};
+var generateCsvBlob = (data) => {
+  const rows = data.map(convertToCsvRow);
+  const csv = Papa.unparse(rows, { header: true, delimiter: "," });
+  return new Blob([csv], { type: getMimeType("csv") });
+};
+
+export { convertToCsvRow, generateCsvBlob };
+//# sourceMappingURL=csv.js.map
+//# sourceMappingURL=csv.js.map

package/dist/csv.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/mime/index.ts","../src/csv/index.ts"],"names":[],"mappings":";;;;AAEO,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;;;ACJO,IAAM,eAAA,GAAkB,CAAC,GAAA,KAA2D;AACzF,EAAA,MAAM,YAAoC,EAAC;AAE3C,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,KAAK,MAAA,CAAO,OAAA,CAAQ,GAAG,CAAA,EAAG;AAC9C,IAAA,SAAA,CAAU,GAAG,CAAA,GAAI,MAAA,CAAO,KAAA,IAAS,EAAE,CAAA;AAAA,EACrC;AAEA,EAAA,OAAO,SAAA;AACT;AAEO,IAAM,eAAA,GAAkB,CAAC,IAAA,KAA4C;AAC1E,EAAA,MAAM,IAAA,GAAiC,IAAA,CAAK,GAAA,CAAI,eAAe,CAAA;AAC/D,EAAA,MAAM,GAAA,GAAM,KAAK,OAAA,CAAQ,IAAA,EAAM,EAAE,MAAA,EAAQ,IAAA,EAAM,SAAA,EAAW,GAAA,EAAK,CAAA;AAE/D,EAAA,OAAO,IAAI,IAAA,CAAK,CAAC,GAAG,CAAA,EAAG,EAAE,IAAA,EAAM,WAAA,CAAY,KAAK,CAAA,EAAG,CAAA;AACrD","file":"csv.js","sourcesContent":["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","import Papa from \"papaparse\";\nimport { getMimeType } from \"../mime\";\n\nexport type CellValue = string | number | null | undefined;\n\nexport const convertToCsvRow = (row: Record<string, CellValue>): Record<string, string> => {\n  const stringRow: Record<string, string> = {};\n\n  for (const [key, value] of Object.entries(row)) {\n    stringRow[key] = String(value ?? \"\");\n  }\n\n  return stringRow;\n};\n\nexport const generateCsvBlob = (data: Record<string, CellValue>[]): Blob => {\n  const rows: Record<string, string>[] = data.map(convertToCsvRow);\n  const csv = Papa.unparse(rows, { header: true, delimiter: \",\" });\n\n  return new Blob([csv], { type: getMimeType(\"csv\") });\n};\n"]}

package/dist/dimensions.utils-BwIBA5op.d.cts

@@ -0,0 +1,6 @@
+interface Dimensions {
+    width: number;
+    height: number;
+}
+
+export type { Dimensions as D };

package/dist/dimensions.utils-BwIBA5op.d.ts

@@ -0,0 +1,6 @@
+interface Dimensions {
+    width: number;
+    height: number;
+}
+
+export type { Dimensions as D };

package/dist/excel.cjs

@@ -0,0 +1,177 @@
+'use strict';
+
+var ExcelJS = require('exceljs');
+var mime = require('mime');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var ExcelJS__default = /*#__PURE__*/_interopDefault(ExcelJS);
+var mime__default = /*#__PURE__*/_interopDefault(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__default.default.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__default.default.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") });
+};
+
+exports.WorksheetBuilder = WorksheetBuilder;
+exports.generateExcelBlob = generateExcelBlob;
+exports.rgbToArgb = rgbToArgb;
+exports.sanitizeWorksheetTitle = sanitizeWorksheetTitle;
+//# sourceMappingURL=excel.cjs.map
+//# sourceMappingURL=excel.cjs.map

package/dist/excel.cjs.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":["mime","ExcelJS"],"mappings":"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","file":"excel.cjs","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/excel.d.cts

@@ -0,0 +1,109 @@
+import ExcelJS, { Font, Fill, Alignment } from 'exceljs';
+
+type CellValue = string | number | null | undefined;
+type VerticalAlignment = "top" | "middle" | "bottom";
+type HorizontalAlignment = "left" | "center" | "right";
+type ColumnValueType = "number" | "text" | "auto";
+interface ColumnMetadata {
+    name: string;
+    width: number;
+    valueType?: ColumnValueType;
+}
+interface BorderSide {
+    style?: "thin" | "medium" | "thick" | "dotted" | "dashed" | "double";
+    color?: {
+        argb: string;
+    };
+}
+/**
+ * Type for ExcelJS cell borders.
+ */
+interface CellBorder {
+    top?: BorderSide;
+    bottom?: BorderSide;
+    left?: BorderSide;
+    right?: BorderSide;
+}
+/**
+ * Type for ExcelJS cell styles.
+ * This is a simplified version of ExcelJS.Style that focuses on commonly used properties.
+ */
+interface CellStyle {
+    font?: Partial<Font>;
+    fill?: Partial<Fill>;
+    alignment?: Partial<Alignment>;
+    border?: CellBorder;
+    numFmt?: string;
+}
+/**
+ * Helper type to convert RGB color string to ARGB format for ExcelJS.
+ * ExcelJS uses ARGB format: "FFFFFFFF" where FF is alpha, then RGB.
+ */
+type ArgbColor = {
+    argb: string;
+};
+/**
+ * Helper function to convert RGB color string to ARGB format.
+ * @param rgb - RGB color string without # (e.g., "FFFFFF")
+ * @returns ARGB color object (e.g., { argb: "FFFFFFFF" })
+ */
+declare const rgbToArgb: (rgb: string) => ArgbColor;
+
+interface AddCellArgs {
+    row: number;
+    col: number;
+    value: CellValue;
+    style?: CellStyle;
+}
+interface AddRowArgs {
+    values: CellValue[];
+    styles?: CellStyle[];
+}
+declare class WorksheetBuilder {
+    private worksheet;
+    private currentRow;
+    private defaultRowStyles;
+    constructor(worksheet: ExcelJS.Worksheet);
+    /** Returns the current row index (1-based). */
+    get rowCount(): number;
+    addCell({ row, col, value, style }: AddCellArgs): void;
+    addRow({ values, styles }: AddRowArgs): void;
+    setDefaultRowStyles(styles: CellStyle[]): void;
+    addEmptyRow(): void;
+    setColumnWidths(columnWidths: number[]): void;
+    getWorksheet(): ExcelJS.Worksheet;
+    private applyStyle;
+}
+
+/**
+ * Sanitizes a worksheet title to comply with Excel's limitations.
+ *
+ * Excel enforces strict rules for worksheet names:
+ * - Maximum length of 31 characters (legacy limitation from older Excel versions)
+ * - Certain characters are reserved for special purposes and cannot be used:
+ *   - `:` (colon) - used in cell range references (e.g., A1:B2)
+ *   - `/` (forward slash) - used in file paths
+ *   - `\` (backslash) - used in file paths and escape sequences
+ *   - `?` (question mark) - used as wildcard in formulas
+ *   - `*` (asterisk) - used as wildcard in formulas
+ *   - `[` and `]` (square brackets) - used in external references (e.g., [Book1.xlsx]Sheet1!A1)
+ *
+ * This function removes invalid characters and truncates the title to 31 characters
+ * to ensure compatibility with Excel's file format specifications.
+ *
+ * @param title - The original worksheet title to sanitize
+ * @returns A sanitized title that complies with Excel's naming rules
+ */
+declare const sanitizeWorksheetTitle: (title: string) => string;
+interface GenerateExcelBlobArgs {
+    worksheetTitle: string;
+    data: Record<string, CellValue>[];
+    /**
+     * Metadata for columns, keyed by column name (translated header name).
+     * If not provided, columns will use default width and auto-detect value types.
+     */
+    columnsMetadata: Record<string, ColumnMetadata>;
+}
+declare const generateExcelBlob: (args: GenerateExcelBlobArgs) => Promise<Blob>;
+
+export { type ArgbColor, type CellBorder, type CellStyle, type CellValue, type ColumnMetadata, type ColumnValueType, type HorizontalAlignment, type VerticalAlignment, WorksheetBuilder, generateExcelBlob, rgbToArgb, sanitizeWorksheetTitle };

package/dist/excel.d.ts

@@ -0,0 +1,109 @@
+import ExcelJS, { Font, Fill, Alignment } from 'exceljs';
+
+type CellValue = string | number | null | undefined;
+type VerticalAlignment = "top" | "middle" | "bottom";
+type HorizontalAlignment = "left" | "center" | "right";
+type ColumnValueType = "number" | "text" | "auto";
+interface ColumnMetadata {
+    name: string;
+    width: number;
+    valueType?: ColumnValueType;
+}
+interface BorderSide {
+    style?: "thin" | "medium" | "thick" | "dotted" | "dashed" | "double";
+    color?: {
+        argb: string;
+    };
+}
+/**
+ * Type for ExcelJS cell borders.
+ */
+interface CellBorder {
+    top?: BorderSide;
+    bottom?: BorderSide;
+    left?: BorderSide;
+    right?: BorderSide;
+}
+/**
+ * Type for ExcelJS cell styles.
+ * This is a simplified version of ExcelJS.Style that focuses on commonly used properties.
+ */
+interface CellStyle {
+    font?: Partial<Font>;
+    fill?: Partial<Fill>;
+    alignment?: Partial<Alignment>;
+    border?: CellBorder;
+    numFmt?: string;
+}
+/**
+ * Helper type to convert RGB color string to ARGB format for ExcelJS.
+ * ExcelJS uses ARGB format: "FFFFFFFF" where FF is alpha, then RGB.
+ */
+type ArgbColor = {
+    argb: string;
+};
+/**
+ * Helper function to convert RGB color string to ARGB format.
+ * @param rgb - RGB color string without # (e.g., "FFFFFF")
+ * @returns ARGB color object (e.g., { argb: "FFFFFFFF" })
+ */
+declare const rgbToArgb: (rgb: string) => ArgbColor;
+
+interface AddCellArgs {
+    row: number;
+    col: number;
+    value: CellValue;
+    style?: CellStyle;
+}
+interface AddRowArgs {
+    values: CellValue[];
+    styles?: CellStyle[];
+}
+declare class WorksheetBuilder {
+    private worksheet;
+    private currentRow;
+    private defaultRowStyles;
+    constructor(worksheet: ExcelJS.Worksheet);
+    /** Returns the current row index (1-based). */
+    get rowCount(): number;
+    addCell({ row, col, value, style }: AddCellArgs): void;
+    addRow({ values, styles }: AddRowArgs): void;
+    setDefaultRowStyles(styles: CellStyle[]): void;
+    addEmptyRow(): void;
+    setColumnWidths(columnWidths: number[]): void;
+    getWorksheet(): ExcelJS.Worksheet;
+    private applyStyle;
+}
+
+/**
+ * Sanitizes a worksheet title to comply with Excel's limitations.
+ *
+ * Excel enforces strict rules for worksheet names:
+ * - Maximum length of 31 characters (legacy limitation from older Excel versions)
+ * - Certain characters are reserved for special purposes and cannot be used:
+ *   - `:` (colon) - used in cell range references (e.g., A1:B2)
+ *   - `/` (forward slash) - used in file paths
+ *   - `\` (backslash) - used in file paths and escape sequences
+ *   - `?` (question mark) - used as wildcard in formulas
+ *   - `*` (asterisk) - used as wildcard in formulas
+ *   - `[` and `]` (square brackets) - used in external references (e.g., [Book1.xlsx]Sheet1!A1)
+ *
+ * This function removes invalid characters and truncates the title to 31 characters
+ * to ensure compatibility with Excel's file format specifications.
+ *
+ * @param title - The original worksheet title to sanitize
+ * @returns A sanitized title that complies with Excel's naming rules
+ */
+declare const sanitizeWorksheetTitle: (title: string) => string;
+interface GenerateExcelBlobArgs {
+    worksheetTitle: string;
+    data: Record<string, CellValue>[];
+    /**
+     * Metadata for columns, keyed by column name (translated header name).
+     * If not provided, columns will use default width and auto-detect value types.
+     */
+    columnsMetadata: Record<string, ColumnMetadata>;
+}
+declare const generateExcelBlob: (args: GenerateExcelBlobArgs) => Promise<Blob>;
+
+export { type ArgbColor, type CellBorder, type CellStyle, type CellValue, type ColumnMetadata, type ColumnValueType, type HorizontalAlignment, type VerticalAlignment, WorksheetBuilder, generateExcelBlob, rgbToArgb, sanitizeWorksheetTitle };