@js-ak/excel-toolbox 1.8.2 → 1.9.0

package/build/types/lib/workbook-builder/utils/constants.d.ts

@@ -0,0 +1,47 @@
+export declare const CONTENT_TYPES: {
+    readonly APP: "application/vnd.openxmlformats-officedocument.extended-properties+xml";
+    readonly CORE: "application/vnd.openxmlformats-package.core-properties+xml";
+    readonly RELATIONSHIPS: "application/vnd.openxmlformats-package.relationships+xml";
+    readonly SHARED_STRINGS: "application/vnd.openxmlformats-officedocument.spreadsheetml.sharedStrings+xml";
+    readonly STYLES: "application/vnd.openxmlformats-officedocument.spreadsheetml.styles+xml";
+    readonly THEME: "application/vnd.openxmlformats-officedocument.theme+xml";
+    readonly WORKBOOK: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet.main+xml";
+    readonly WORKSHEET: "application/vnd.openxmlformats-officedocument.spreadsheetml.worksheet+xml";
+    readonly XML: "application/xml";
+};
+export declare const FILE_PATHS: {
+    readonly APP: "docProps/app.xml";
+    readonly CONTENT_TYPES: "[Content_Types].xml";
+    readonly CORE: "docProps/core.xml";
+    readonly RELS: "_rels/.rels";
+    readonly SHARED_STRINGS: "xl/sharedStrings.xml";
+    readonly STYLES: "xl/styles.xml";
+    readonly THEME: "xl/theme/theme1.xml";
+    readonly WORKBOOK: "xl/workbook.xml";
+    readonly WORKBOOK_RELS: "xl/_rels/workbook.xml.rels";
+    readonly WORKSHEET: "xl/worksheets/sheet1.xml";
+};
+export declare const RELATIONSHIP_TYPES: {
+    readonly APP: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties";
+    readonly CORE: "http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties";
+    readonly OFFICE_DOCUMENT: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument";
+    readonly SHARED_STRINGS: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings";
+    readonly STYLES: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles";
+    readonly THEME: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme";
+    readonly WORKSHEET: "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet";
+};
+export declare const XML_DECLARATION = "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>";
+export declare const XML_NAMESPACES: {
+    readonly CONTENT_TYPES: "http://schemas.openxmlformats.org/package/2006/content-types";
+    readonly CORE_PROPERTIES: "http://schemas.openxmlformats.org/package/2006/metadata/core-properties";
+    readonly DC: "http://purl.org/dc/elements/1.1/";
+    readonly DCMITYPE: "http://purl.org/dc/dcmitype/";
+    readonly DCTERMS: "http://purl.org/dc/terms/";
+    readonly DOC_PROPS_VTYPES: "http://schemas.openxmlformats.org/officeDocument/2006/docPropsVTypes";
+    readonly DRAWINGML: "http://schemas.openxmlformats.org/drawingml/2006/main";
+    readonly EXTENDED_PROPERTIES: "http://schemas.openxmlformats.org/officeDocument/2006/extended-properties";
+    readonly OFFICE_DOCUMENT: "http://schemas.openxmlformats.org/officeDocument/2006/relationships";
+    readonly PACKAGE_RELATIONSHIPS: "http://schemas.openxmlformats.org/package/2006/relationships";
+    readonly SPREADSHEET_ML: "http://schemas.openxmlformats.org/spreadsheetml/2006/main";
+    readonly XSI: "http://www.w3.org/2001/XMLSchema-instance";
+};

package/build/types/lib/workbook-builder/utils/date-to-excel-serial.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Converts a JavaScript Date object to Excel serial number format.
+ * Excel stores dates as serial numbers where 1 represents January 1, 1900.
+ *
+ * @param date - The JavaScript Date object to convert
+ *
+ * @returns The Excel serial number as a floating-point number
+ */
+export declare function dateToExcelSerial(date: Date): number;

package/build/types/lib/workbook-builder/utils/index.d.ts

@@ -0,0 +1,18 @@
+export * from "./build-app-xml.js";
+export * from "./build-cell-children.js";
+export * from "./build-content-types-xml.js";
+export * from "./build-shared-strings-xml.js";
+export * from "./build-styles-xml.js";
+export * from "./build-theme-xml.js";
+export * from "./build-workbook-rels-xml.js";
+export * from "./build-workbook-xml.js";
+export * from "./build-worksheet-xml.js";
+export * from "./build-xml.js";
+export * from "./constants.js";
+export * from "./date-to-excel-serial.js";
+export * from "./initialize-files.js";
+export * from "./sheet.js";
+export * from "./write-shared-strings-xml.js";
+export * from "./write-styles-xml.js";
+export * from "./write-worksheet-xml.js";
+export * from "./write-xml.js";

package/build/types/lib/workbook-builder/utils/initialize-files.d.ts

@@ -0,0 +1,13 @@
+import { FILE_PATHS } from "./constants.js";
+export type ExcelFileContent = Buffer | string;
+export type ExcelFiles = {
+    [FILE_PATHS.CONTENT_TYPES]: ExcelFileContent;
+    [FILE_PATHS.RELS]: ExcelFileContent;
+    [FILE_PATHS.WORKBOOK_RELS]: ExcelFileContent;
+    [FILE_PATHS.STYLES]: ExcelFileContent;
+    [FILE_PATHS.SHARED_STRINGS]: ExcelFileContent;
+    [FILE_PATHS.WORKBOOK]: ExcelFileContent;
+    [FILE_PATHS.WORKSHEET]: ExcelFileContent;
+    [key: string]: ExcelFileContent;
+};
+export declare const initializeFiles: (sheetName: string) => ExcelFiles;

package/build/types/lib/workbook-builder/utils/sheet.d.ts

@@ -0,0 +1,21 @@
+import type { CellStyle, MergeCell, SheetData } from "../types/index.js";
+/**
+ * Factory for creating a new sheet with bound helpers.
+ *
+ * @param name - Sheet name
+ * @param fn.addMerge - Function to add a merge range (bound to workbook)
+ * @param fn.removeMerge - Function to remove a merge range (bound to workbook)
+ * @param fn.addOrGetStyle - Function to add or get a style index
+ * @param fn.addSharedString - Function to add a shared string and return its index
+ * @returns SheetData instance with helpers
+ */
+export declare function createSheet(name: string, fn: {
+    addMerge: (mergeCell: MergeCell & {
+        sheetName: string;
+    }) => MergeCell;
+    removeMerge: (mergeCell: MergeCell & {
+        sheetName: string;
+    }) => boolean;
+    addOrGetStyle: (style: CellStyle, sheetName: string) => number;
+    addSharedString: (str: string, sheetName: string) => number;
+}): SheetData;

package/build/types/lib/workbook-builder/utils/write-shared-strings-xml.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Writes the `sharedStrings.xml` content to a file at the given destination.
+ *
+ * Uses a file write stream with backpressure control to avoid buffering large
+ * content in memory.
+ *
+ * @param destination - Absolute or relative file path to write
+ * @param strings - Array of unique strings used in the workbook
+ * @returns Promise that resolves when the write stream finishes
+ */
+export declare function writeSharedStringsXml(destination: string, strings?: string[]): Promise<void>;

package/build/types/lib/workbook-builder/utils/write-styles-xml.d.ts

@@ -0,0 +1,24 @@
+import type { CellXf, XmlNode } from "../types/index.js";
+/**
+ * Writes the `styles.xml` part to a file at the given destination using a write stream.
+ * Falls back to default font/fill/border collections when none are provided.
+ *
+ * @param destination - Absolute or relative file path to write
+ * @param data - Style collections used to construct the stylesheet
+ * @param data.borders - Array of border XmlNodes
+ * @param data.cellXfs - Array of cell format records
+ * @param data.fills - Array of fill XmlNodes
+ * @param data.fonts - Array of font XmlNodes
+ * @param data.numFmts - Array of custom number formats (formatCode and id)
+ * @returns Promise that resolves when the write stream finishes
+ */
+export declare function writeStylesXml(destination: string, data?: {
+    borders: XmlNode["children"];
+    cellXfs: CellXf[];
+    fills: XmlNode["children"];
+    fonts: XmlNode["children"];
+    numFmts: {
+        formatCode: string;
+        id: number;
+    }[];
+}): Promise<void>;

package/build/types/lib/workbook-builder/utils/write-worksheet-xml.d.ts

@@ -0,0 +1,14 @@
+import type { MergeCell, SheetData } from "../types/index.js";
+/**
+ * Writes a worksheet XML file to the given destination using a streaming approach.
+ *
+ * - Streams rows and cells to minimize memory usage
+ * - Tracks the worksheet dimension (min/max rows/cols) while streaming
+ * - Updates the <dimension> ref at the end by rewriting the file in a buffered pass
+ *
+ * @param destination - Absolute or relative file path for the worksheet XML
+ * @param rows - Map of rowIndex -> RowData with cells
+ * @param merges - Merge ranges to append after <sheetData>
+ * @returns Promise that resolves when the file is fully written and dimension updated
+ */
+export declare function writeWorksheetXml(destination: string, rows?: SheetData["rows"], merges?: MergeCell[]): Promise<void>;

package/build/types/lib/workbook-builder/utils/write-xml.d.ts

@@ -0,0 +1,3 @@
+import { Writable } from "node:stream";
+import { XmlNode } from "../types/index.js";
+export declare function writeXml(node: XmlNode, stream: Writable, level?: number, chunkSize?: number): Promise<void>;

package/build/types/lib/workbook-builder/workbook-builder.d.ts

@@ -0,0 +1,110 @@
+import type { Writable } from "node:stream";
+import * as Types from "./types/index.js";
+/**
+ * Builds Excel workbooks by composing sheets, styles, shared strings and merges,
+ * and provides methods to save to file or stream.
+ *
+ * @experimental This API is experimental and might change in future versions.
+ */
+export declare class WorkbookBuilder {
+    #private;
+    /**
+     * Creates a new workbook with a default sheet and initial style collections.
+     *
+     * @param options.defaultSheetName - The name for the initial sheet
+     */
+    constructor({ defaultSheetName, }?: {
+        defaultSheetName?: string | undefined;
+    });
+    /** Returns the internal sheets map. */
+    protected get sheets(): Map<string, Types.SheetData>;
+    /** Returns the shared strings array. */
+    protected get sharedStrings(): string[];
+    /** Replaces the shared strings array. */
+    protected set sharedStrings(sharedStrings: string[]);
+    /** Returns the shared string index map. */
+    protected get sharedStringMap(): Map<string, number>;
+    /** Returns the borders collection. */
+    protected get borders(): (string | Types.XmlNode)[];
+    /** Returns the border cache map (serialized xml -> index). */
+    protected get bordersMap(): Map<string, number>;
+    /** Returns the cellXfs (style records). */
+    protected get cellXfs(): Types.CellXf[];
+    /** Returns the fills collection. */
+    protected get fills(): (string | Types.XmlNode)[];
+    /** Returns the fill cache map (serialized xml -> index). */
+    protected get fillsMap(): Map<string, number>;
+    /** Returns the fonts collection. */
+    protected get fonts(): (string | Types.XmlNode)[];
+    /** Returns the font cache map (serialized xml -> index). */
+    protected get fontsMap(): Map<string, number>;
+    /** Returns the number formats collection. */
+    protected get numFmts(): {
+        formatCode: string;
+        id: number;
+    }[];
+    /** Returns the mapping from serialized style JSON to style index. */
+    protected get styleMap(): Map<string, number>;
+    /** Returns the merge ranges, grouped by sheet name. */
+    protected get mergeCells(): Map<string, Types.MergeCell[]>;
+    /** Public methods */
+    /**
+     * Adds a new sheet to the workbook.
+     *
+     * @throws Error if a sheet with the same name already exists
+     * @param sheetName - Sheet name to add
+     * @returns The created sheet data
+     */
+    addSheet(sheetName: string): Types.SheetData;
+    /** Returns a sheet by name if it exists. */
+    getSheet(sheetName: string): Types.SheetData | undefined;
+    /**
+     * Removes a sheet by name.
+     * If cleanup is enabled, also removes associated shared strings and styles.
+     *
+     * @param sheetName - Sheet name to remove
+     * @returns True if the sheet existed and was removed
+     */
+    removeSheet(sheetName: string): true;
+    /**
+     * Returns a snapshot of the workbook internals for inspection and tests.
+     * The returned structure is deeply frozen to avoid accidental mutations.
+     */
+    getInfo(): {
+        mergeCells: Map<string, Types.MergeCell[]>;
+        sheetsNames: string[];
+        sharedStringMap: Map<string, number>;
+        sharedStrings: string[];
+        styles: {
+            borders: NonNullable<Types.XmlNode["children"]>;
+            cellXfs: Types.CellXf[];
+            fills: NonNullable<Types.XmlNode["children"]>;
+            fonts: NonNullable<Types.XmlNode["children"]>;
+            numFmts: {
+                formatCode: string;
+                id: number;
+            }[];
+            styleMap: Map<string, number>;
+        };
+    };
+    /**
+     * Generates workbook XML parts in-memory and writes a .xlsx zip to disk.
+     *
+     * @param path - Absolute or relative file path to write
+     */
+    saveToFile(path: string): Promise<void>;
+    /**
+     * Saves the workbook to a writable stream using temporary files.
+     * This method creates temporary files from the in-memory data and streams them
+     * to the output stream, avoiding loading the entire file into memory.
+     *
+     * @param output - Writable stream to receive the Excel file
+     * @param options.destination - Optional existing directory to use instead of a system temp directory
+     * @param options.cleanup - Optional flag to cleanup the temporary directory after saving (default: true)
+     * @returns Promise that resolves when the file has been fully written
+     */
+    saveToStream(output: Writable, options?: {
+        destination?: string;
+        cleanup?: boolean;
+    }): Promise<void>;
+}

package/build/types/lib/zip/utils/to-bytes.d.ts

@@ -14,7 +14,7 @@ import { Buffer } from "node:buffer";
  * @returns {Buffer} - A new Buffer of exactly `len` bytes containing:
  *        1. The value's bytes in little-endian order (least significant byte first)
  *        2. Zero padding in any remaining higher-order bytes
- * @throws {RangeError} - If the value requires more bytes than `len` to represent
- *        (though this is currently not explicitly checked)
+ *
+ * @throws {RangeError} - If the length is not positive or the value is negative.
  */
 export declare function toBytes(value: number, len: number): Buffer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@js-ak/excel-toolbox",
-  "version": "1.8.2",
+  "version": "1.9.0",
   "description": "excel-toolbox",
   "publishConfig": {
     "access": "public",
@@ -44,7 +44,9 @@
     "lint": "eslint . --ext .ts",
     "postbuild:esm": "node scripts/write-esm-package.js",
     "postbuild:cjs": "node scripts/write-cjs-package.js",
-    "test": "vitest run",
+    "test:unit": "vitest run --config vitest.unit.config.js",
+    "test:integration": "vitest run --config vitest.integration.config.js",
+    "test": "npm run test:unit && npm run test:integration",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage"
   },