@cj-tech-master/excelts 1.4.5 → 1.5.0

package/dist/types/types.d.ts

@@ -2,8 +2,7 @@
  * Type definitions for ExcelTS
  * This file exports all public types used by the library
  */
-import type { IAnchor } from "./doc/anchor.js";
-export type Buffer = ArrayBuffer;
+export type Buffer = Uint8Array;
 export declare enum PaperSize {
     Legal = 5,
     Executive = 7,
@@ -92,14 +91,26 @@ export interface FillGradientPath {
     stops: GradientStop[];
 }
 export type Fill = FillPattern | FillGradientAngle | FillGradientPath;
-export interface Style {
-    numFmt: string;
+export interface NumFmt {
+    id: number;
+    formatCode: string;
+}
+interface StyleBase {
     font: Partial<Font>;
     alignment: Partial<Alignment>;
     protection: Partial<Protection>;
     border: Partial<Borders>;
     fill: Fill;
 }
+export interface StyleInput extends StyleBase {
+    numFmt: string;
+}
+export interface StyleOutput extends StyleBase {
+    numFmt: NumFmt;
+}
+export interface Style extends StyleBase {
+    numFmt: string | NumFmt;
+}
 export interface Margins {
     top: number;
     left: number;
@@ -143,13 +154,13 @@ export interface HeaderFooter {
     firstFooter: string;
 }
 export interface WorksheetViewCommon {
-    rightToLeft: boolean;
-    activeCell: string;
-    showRuler: boolean;
-    showRowColHeaders: boolean;
-    showGridLines: boolean;
-    zoomScale: number;
-    zoomScaleNormal: number;
+    rightToLeft?: boolean;
+    activeCell?: string;
+    showRuler?: boolean;
+    showRowColHeaders?: boolean;
+    showGridLines?: boolean;
+    zoomScale?: number;
+    zoomScaleNormal?: number;
 }
 export interface WorksheetViewNormal {
     state: "normal";
@@ -248,13 +259,22 @@ export interface CellFormulaValue {
     result?: number | string | boolean | Date | CellErrorValue;
     date1904?: boolean;
 }
+/** Array formula that spans multiple cells */
+export interface CellArrayFormulaValue {
+    formula: string;
+    result?: number | string | boolean | Date | CellErrorValue;
+    /** Must be "array" for array formulas */
+    shareType: "array";
+    /** The range this array formula applies to, e.g. "A1:B2" */
+    ref: string;
+}
 export interface CellSharedFormulaValue {
     sharedFormula: string;
     readonly formula?: string;
     result?: number | string | boolean | Date | CellErrorValue;
     date1904?: boolean;
 }
-export type CellValue = null | number | string | boolean | Date | undefined | CellErrorValue | CellRichTextValue | CellHyperlinkValue | CellFormulaValue | CellSharedFormulaValue;
+export type CellValue = null | number | string | boolean | Date | undefined | CellErrorValue | CellRichTextValue | CellHyperlinkValue | CellFormulaValue | CellArrayFormulaValue | CellSharedFormulaValue;
 export interface CommentMargins {
     insetmode: "auto" | "custom";
     inset: number[];
@@ -271,11 +291,9 @@ export interface Comment {
     editAs?: CommentEditAs;
 }
 export type DataValidationOperator = "between" | "notBetween" | "equal" | "notEqual" | "greaterThan" | "lessThan" | "greaterThanOrEqual" | "lessThanOrEqual";
-export interface DataValidation {
-    type: "list" | "whole" | "decimal" | "date" | "textLength" | "custom";
-    formulae: any[];
+/** Base properties shared by all data validation types */
+interface DataValidationBase {
     allowBlank?: boolean;
-    operator?: DataValidationOperator;
     error?: string;
     errorTitle?: string;
     errorStyle?: string;
@@ -284,16 +302,23 @@ export interface DataValidation {
     showErrorMessage?: boolean;
     showInputMessage?: boolean;
 }
+/** Data validation that requires formulae and operator */
+export interface DataValidationWithFormulae extends DataValidationBase {
+    type: "list" | "whole" | "decimal" | "date" | "textLength" | "custom";
+    formulae: any[];
+    operator?: DataValidationOperator;
+}
+/** Data validation type 'any' - no formulae needed */
+export interface DataValidationAny extends DataValidationBase {
+    type: "any";
+}
+export type DataValidation = DataValidationWithFormulae | DataValidationAny;
 export interface Image {
     extension: "jpeg" | "png" | "gif";
     base64?: string;
     filename?: string;
     buffer?: Buffer;
 }
-export interface ImageRange {
-    tl: IAnchor;
-    br: IAnchor;
-}
 export interface ImagePosition {
     tl: {
         col: number;
@@ -304,6 +329,34 @@ export interface ImagePosition {
         height: number;
     };
 }
+/** Anchor position for image placement */
+export interface ImageAnchor {
+    col: number;
+    row: number;
+    nativeCol?: number;
+    nativeRow?: number;
+    nativeColOff?: number;
+    nativeRowOff?: number;
+}
+/** Range input for addImage - can be a string like "A1:B2" or an object */
+export type AddImageRange = string | {
+    /** Top-left anchor position */
+    tl: ImageAnchor | string;
+    /** Bottom-right anchor position (optional if ext is provided) */
+    br?: ImageAnchor | string;
+    /** Image dimensions (alternative to br) */
+    ext?: {
+        width: number;
+        height: number;
+    };
+    /** How the image behaves when cells are resized */
+    editAs?: "oneCell" | "twoCell" | "absolute";
+    /** Hyperlink for the image */
+    hyperlinks?: {
+        hyperlink?: string;
+        tooltip?: string;
+    };
+};
 export interface ImageHyperlinkValue {
     hyperlink: string;
     tooltip?: string;
@@ -319,7 +372,7 @@ export type Address = {
     address: string;
     col: number;
     row: number;
-    $col$row: string;
+    $col$row?: string;
 };
 export type RowValues = CellValue[] | {
     [key: string]: CellValue;
@@ -331,10 +384,10 @@ export type IconSetTypes = "5Arrows" | "5ArrowsGray" | "5Boxes" | "5Quarters" |
 export type CfvoTypes = "percentile" | "percent" | "num" | "min" | "max" | "formula" | "autoMin" | "autoMax";
 export interface Cvfo {
     type: CfvoTypes;
-    value?: number;
+    value?: number | string;
 }
 export interface ConditionalFormattingBaseRule {
-    priority: number;
+    priority?: number;
     style?: Partial<Style>;
 }
 export interface ExpressionRuleType extends ConditionalFormattingBaseRule {
@@ -350,11 +403,11 @@ export interface Top10RuleType extends ConditionalFormattingBaseRule {
     type: "top10";
     rank: number;
     percent: boolean;
-    bottom: boolean;
+    bottom?: boolean;
 }
 export interface AboveAverageRuleType extends ConditionalFormattingBaseRule {
     type: "aboveAverage";
-    aboveAverage: boolean;
+    aboveAverage?: boolean;
 }
 export interface ColorScaleRuleType extends ConditionalFormattingBaseRule {
     type: "colorScale";
@@ -390,12 +443,17 @@ export interface DataBarRuleType extends ConditionalFormattingBaseRule {
     axisPosition?: "auto" | "middle" | "none";
     direction?: "context" | "leftToRight" | "rightToLeft";
     cfvo?: Cvfo[];
+    color?: Partial<Color>;
 }
 export type ConditionalFormattingRule = ExpressionRuleType | CellIsRuleType | Top10RuleType | AboveAverageRuleType | ColorScaleRuleType | IconSetRuleType | ContainsTextRuleType | TimePeriodRuleType | DataBarRuleType;
 export interface ConditionalFormattingOptions {
     ref: string;
     rules: ConditionalFormattingRule[];
 }
+export interface ConditionalFormattingOptions {
+    ref: string;
+    rules: ConditionalFormattingRule[];
+}
 export interface TableStyleProperties {
     theme?: string;
     showFirstColumn?: boolean;
@@ -409,6 +467,7 @@ export interface TableColumnProperties {
     totalsRowLabel?: string;
     totalsRowFunction?: "none" | "average" | "countNums" | "count" | "max" | "min" | "stdDev" | "var" | "sum" | "custom";
     totalsRowFormula?: string;
+    totalsRowResult?: CellFormulaValue["result"];
     style?: Partial<Style>;
 }
 export interface TableProperties {
@@ -459,6 +518,7 @@ export type DefinedNamesModel = DefinedNamesRanges[];
 export interface RowBreak {
     id: number;
     max: number;
-    min: number;
+    min?: number;
     man: number;
 }
+export {};

package/dist/types/utils/col-cache.d.ts

@@ -1,7 +1,10 @@
 import type { Address, Location } from "../types.js";
-type Range = Location & {
-    tl: string | Address;
-    br: string | Address;
+type CachedAddress = Address & {
+    $col$row: string;
+};
+export type DecodedRange = Location & {
+    tl: string | CachedAddress;
+    br: string | CachedAddress;
     dimensions: string;
     sheetName?: string;
 };
@@ -9,21 +12,21 @@ interface ErrorReference {
     error: string;
     sheetName?: string;
 }
-type DecodeExResult = Address | Range | ErrorReference;
+type DecodeExResult = CachedAddress | DecodedRange | ErrorReference;
 interface ColCache {
     _dictionary: string[];
     _l2nFill: number;
     _l2n: Record<string, number>;
     _n2l: string[];
-    _hash: Record<string, Address>;
+    _hash: Record<string, CachedAddress>;
     _level(n: number): number;
     _fill(level: number): void;
     l2n(l: string): number;
     n2l(n: number): string;
     validateAddress(value: string): boolean;
-    decodeAddress(value: string): Address;
-    getAddress(r: number | string, c?: number): Address;
-    decode(value: string): Address | Range;
+    decodeAddress(value: string): CachedAddress;
+    getAddress(r: number | string, c?: number): CachedAddress;
+    decode(value: string): CachedAddress | DecodedRange;
     decodeEx(value: string): DecodeExResult;
     encodeAddress(row: number, col: number): string;
     encode(...args: number[]): string;

package/dist/types/utils/unzip/extract.d.ts

@@ -1,16 +1,17 @@
 /**
  * Simple ZIP extraction utilities
  * Provides easy-to-use Promise-based API for extracting ZIP files
+ * Works in both Node.js and browser environments
  */
-import { type ZipEntry } from "./parse.js";
+import { type ZipEntryInfo } from "./zip-parser.js";
 /**
  * Extracted file entry
  */
 export interface ExtractedFile {
     /** File path within the ZIP */
     path: string;
-    /** File content as Buffer */
-    data: Buffer;
+    /** File content as Uint8Array */
+    data: Uint8Array;
     /** Whether this is a directory */
     isDirectory: boolean;
     /** Uncompressed size */
@@ -19,7 +20,7 @@ export interface ExtractedFile {
 /**
  * Extract all files from a ZIP buffer
  *
- * @param zipData - ZIP file data as Buffer or Uint8Array
+ * @param zipData - ZIP file data as Buffer, Uint8Array, or ArrayBuffer
  * @returns Map of file paths to their content
  *
  * @example
@@ -34,13 +35,13 @@ export interface ExtractedFile {
  * }
  * ```
  */
-export declare function extractAll(zipData: Buffer | Uint8Array): Promise<Map<string, ExtractedFile>>;
+export declare function extractAll(zipData: Uint8Array | ArrayBuffer): Promise<Map<string, ExtractedFile>>;
 /**
  * Extract a single file from a ZIP buffer
  *
- * @param zipData - ZIP file data as Buffer or Uint8Array
+ * @param zipData - ZIP file data as Buffer, Uint8Array, or ArrayBuffer
  * @param filePath - Path of the file to extract
- * @returns File content as Buffer, or null if not found
+ * @returns File content as Uint8Array, or null if not found
  *
  * @example
  * ```ts
@@ -49,15 +50,15 @@ export declare function extractAll(zipData: Buffer | Uint8Array): Promise<Map<st
  * const zipData = fs.readFileSync("archive.zip");
  * const content = await extractFile(zipData, "readme.txt");
  * if (content) {
- *   console.log(content.toString("utf-8"));
+ *   console.log(new TextDecoder().decode(content));
  * }
  * ```
  */
-export declare function extractFile(zipData: Buffer | Uint8Array, filePath: string): Promise<Buffer | null>;
+export declare function extractFile(zipData: Uint8Array | ArrayBuffer, filePath: string): Promise<Uint8Array | null>;
 /**
  * List all file paths in a ZIP buffer (without extracting content)
  *
- * @param zipData - ZIP file data as Buffer or Uint8Array
+ * @param zipData - ZIP file data as Buffer, Uint8Array, or ArrayBuffer
  * @returns Array of file paths
  *
  * @example
@@ -69,11 +70,11 @@ export declare function extractFile(zipData: Buffer | Uint8Array, filePath: stri
  * console.log(paths); // ["file1.txt", "folder/file2.txt", ...]
  * ```
  */
-export declare function listFiles(zipData: Buffer | Uint8Array): Promise<string[]>;
+export declare function listFiles(zipData: Uint8Array | ArrayBuffer): Promise<string[]>;
 /**
  * Iterate over ZIP entries with a callback (memory efficient for large ZIPs)
  *
- * @param zipData - ZIP file data as Buffer or Uint8Array
+ * @param zipData - ZIP file data as Buffer, Uint8Array, or ArrayBuffer
  * @param callback - Async callback for each entry, return false to stop iteration
  *
  * @example
@@ -83,10 +84,11 @@ export declare function listFiles(zipData: Buffer | Uint8Array): Promise<string[
  * await forEachEntry(zipData, async (path, getData) => {
  *   if (path.endsWith(".xml")) {
  *     const content = await getData();
- *     console.log(content.toString("utf-8"));
+ *     console.log(new TextDecoder().decode(content));
  *   }
  *   return true; // continue iteration
  * });
  * ```
  */
-export declare function forEachEntry(zipData: Buffer | Uint8Array, callback: (path: string, getData: () => Promise<Buffer>, entry: ZipEntry) => Promise<boolean | void>): Promise<void>;
+export declare function forEachEntry(zipData: Uint8Array | ArrayBuffer, callback: (path: string, getData: () => Promise<Uint8Array>, entry: ZipEntryInfo) => Promise<boolean | void>): Promise<void>;
+export { ZipParser, type ZipEntryInfo, type ZipParseOptions } from "./zip-parser.js";

package/dist/types/utils/unzip/index.d.ts

@@ -1,5 +1,19 @@
 /**
  * Unzip utilities for parsing ZIP archives
+ *
+ * Two APIs are provided:
+ *
+ * 1. **Stream-based API** (Node.js only):
+ *    - `Parse`, `createParse` - Parse ZIP files as a stream
+ *    - Best for large files where you don't want to load entire file into memory
+ *    - Requires Node.js `stream` module
+ *
+ * 2. **Buffer-based API** (Browser + Node.js):
+ *    - `extractAll`, `extractFile`, `listFiles`, `forEachEntry`, `ZipParser`
+ *    - Works in both Node.js and browser environments
+ *    - Uses native `DecompressionStream` in browser, `zlib` in Node.js
+ *    - Best for files already loaded into memory (ArrayBuffer, Uint8Array)
+ *
  * Original source: https://github.com/ZJONSSON/node-unzipper
  * License: MIT
  */
@@ -10,4 +24,4 @@ export { bufferStream } from "./buffer-stream.js";
 export { parse as parseBuffer } from "./parse-buffer.js";
 export { parseDateTime } from "./parse-datetime.js";
 export { parseExtraField, type ExtraField, type ZipVars } from "./parse-extra-field.js";
-export { extractAll, extractFile, listFiles, forEachEntry, type ExtractedFile } from "./extract.js";
+export { extractAll, extractFile, listFiles, forEachEntry, ZipParser, type ExtractedFile, type ZipEntryInfo, type ZipParseOptions } from "./extract.js";

package/dist/types/utils/unzip/zip-parser.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Pure Uint8Array-based ZIP parser
+ * Works in both Node.js and browser environments
+ * No dependency on Node.js stream module
+ */
+/**
+ * Parsed ZIP entry
+ */
+export interface ZipEntryInfo {
+    /** File path within the ZIP */
+    path: string;
+    /** Whether this is a directory */
+    isDirectory: boolean;
+    /** Compressed size */
+    compressedSize: number;
+    /** Uncompressed size */
+    uncompressedSize: number;
+    /** Compression method (0 = stored, 8 = deflate) */
+    compressionMethod: number;
+    /** CRC-32 checksum */
+    crc32: number;
+    /** Last modified date */
+    lastModified: Date;
+    /** Offset to local file header */
+    localHeaderOffset: number;
+    /** File comment */
+    comment: string;
+    /** External file attributes */
+    externalAttributes: number;
+    /** Is encrypted */
+    isEncrypted: boolean;
+}
+/**
+ * ZIP parsing options
+ */
+export interface ZipParseOptions {
+    /** Whether to decode file names as UTF-8 (default: true) */
+    decodeStrings?: boolean;
+}
+/**
+ * Parse ZIP file entries from Central Directory
+ */
+export declare function parseZipEntries(data: Uint8Array, options?: ZipParseOptions): ZipEntryInfo[];
+/**
+ * Extract file data for a specific entry
+ */
+export declare function extractEntryData(data: Uint8Array, entry: ZipEntryInfo): Promise<Uint8Array>;
+/**
+ * Extract file data synchronously (Node.js only)
+ */
+export declare function extractEntryDataSync(data: Uint8Array, entry: ZipEntryInfo): Uint8Array;
+/**
+ * High-level ZIP parser class
+ */
+export declare class ZipParser {
+    private data;
+    private entries;
+    private entryMap;
+    constructor(data: Uint8Array | ArrayBuffer, options?: ZipParseOptions);
+    /**
+     * Get all entries in the ZIP file
+     */
+    getEntries(): ZipEntryInfo[];
+    /**
+     * Get entry by path
+     */
+    getEntry(path: string): ZipEntryInfo | undefined;
+    /**
+     * Check if entry exists
+     */
+    hasEntry(path: string): boolean;
+    /**
+     * List all file paths
+     */
+    listFiles(): string[];
+    /**
+     * Extract a single file (async)
+     */
+    extract(path: string): Promise<Uint8Array | null>;
+    /**
+     * Extract a single file (sync, Node.js only)
+     */
+    extractSync(path: string): Uint8Array | null;
+    /**
+     * Extract all files (async)
+     */
+    extractAll(): Promise<Map<string, Uint8Array>>;
+    /**
+     * Iterate over entries with async callback
+     */
+    forEach(callback: (entry: ZipEntryInfo, getData: () => Promise<Uint8Array>) => Promise<boolean | void>): Promise<void>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cj-tech-master/excelts",
-  "version": "1.4.5",
+  "version": "1.5.0",
   "description": "TypeScript Excel Workbook Manager - Read and Write xlsx and csv Files.",
   "private": false,
   "publishConfig": {