@cj-tech-master/excelts 1.6.2 → 1.6.3

package/dist/types/stream/xlsx/workbook-reader.d.ts

@@ -1,44 +1,133 @@
 import { EventEmitter } from "events";
-interface WorkbookReaderOptions {
-    worksheets?: string;
-    sharedStrings?: string;
-    hyperlinks?: string;
-    styles?: string;
-    entries?: string;
+import { Readable } from "stream";
+import { StylesXform } from "../../xlsx/xform/style/styles-xform.js";
+import { WorksheetReader } from "./worksheet-reader.js";
+import { HyperlinkReader } from "./hyperlink-reader.js";
+import type { WorksheetState, Font, WorkbookProperties } from "../../types.js";
+/** Internal options type that includes undocumented 'prep' value */
+export interface InternalWorksheetOptions {
+    worksheets?: "emit" | "ignore" | "prep";
+    sharedStrings?: "cache" | "emit" | "ignore";
+    hyperlinks?: "cache" | "emit" | "ignore";
+    styles?: "cache" | "ignore";
+    entries?: "emit" | "ignore";
 }
-declare class WorkbookReader extends EventEmitter {
-    input: any;
-    options: WorkbookReaderOptions;
-    styles: any;
-    stream?: any;
-    sharedStrings?: any[];
-    workbookRels?: any[];
-    properties?: any;
-    model?: any;
-    constructor(input: any, options?: WorkbookReaderOptions);
-    _getStream(input: any): any;
-    read(input?: any, options?: WorkbookReaderOptions): Promise<void>;
-    [Symbol.asyncIterator](): AsyncIterableIterator<any>;
-    parse(input?: any, options?: WorkbookReaderOptions): AsyncIterableIterator<{
-        eventType: string;
-        value: any;
+/** Rich text item from shared strings */
+export interface SharedStringRichText {
+    richText: Array<{
+        font: Partial<Font> | null;
+        text: string | null;
     }>;
-    _emitEntry(payload: any): void;
-    _parseRels(entry: any): Promise<void>;
-    _parseWorkbook(entry: any): Promise<void>;
-    _parseSharedStrings(entry: any): AsyncIterableIterator<{
+}
+/** Shared string value - either plain text or rich text */
+export type SharedStringValue = string | SharedStringRichText;
+/** Relationship entry from workbook.xml.rels */
+export interface WorkbookRelationship {
+    Id: string;
+    Target: string;
+    Type?: string;
+}
+/** Sheet metadata from workbook.xml */
+export interface SheetMetadata {
+    id: number;
+    name: string;
+    state?: WorksheetState;
+    rId: string;
+}
+/** Workbook model parsed from workbook.xml */
+export interface WorkbookModel {
+    sheets?: SheetMetadata[];
+    properties?: Partial<WorkbookProperties>;
+    views?: unknown[];
+    definedNames?: unknown[];
+}
+/** Properties parsed from workbook.xml (workbookPr element) */
+export interface WorkbookPropertiesXform {
+    model?: Partial<WorkbookProperties>;
+}
+/** Entry event payload */
+interface EntryPayload {
+    type: "shared-strings" | "styles" | "workbook" | "worksheet" | "hyperlinks";
+    id?: string;
+}
+/** Parse event types */
+export type ParseEventType = "shared-strings" | "worksheet" | "hyperlinks";
+export interface SharedStringEvent {
+    eventType: "shared-strings";
+    value: {
         index: number;
-        text: any;
-    }>;
-    _parseStyles(entry: any): Promise<void>;
-    _parseWorksheet(iterator: any, sheetNo: string): IterableIterator<{
-        eventType: string;
-        value: any;
-    }>;
-    _parseHyperlinks(iterator: any, sheetNo: string): IterableIterator<{
-        eventType: string;
-        value: any;
+        text: SharedStringValue;
+    };
+}
+export interface WorksheetReadyEvent {
+    eventType: "worksheet";
+    value: WorksheetReader;
+}
+export interface HyperlinksEvent {
+    eventType: "hyperlinks";
+    value: HyperlinkReader;
+}
+export type ParseEvent = SharedStringEvent | WorksheetReadyEvent | HyperlinksEvent;
+/**
+ * Options for WorkbookReader
+ */
+export interface WorkbookReaderOptions {
+    /**
+     * Specifies whether to emit worksheets ('emit') or not ('ignore').
+     * @default 'emit'
+     */
+    worksheets?: "emit" | "ignore";
+    /**
+     * Specifies whether to cache shared strings ('cache'), emit them ('emit'), or ignore them ('ignore').
+     * @default 'cache'
+     */
+    sharedStrings?: "cache" | "emit" | "ignore";
+    /**
+     * Specifies whether to cache hyperlinks ('cache'), emit them ('emit'), or ignore them ('ignore').
+     * @default 'ignore'
+     */
+    hyperlinks?: "cache" | "emit" | "ignore";
+    /**
+     * Specifies whether to cache styles ('cache') or ignore them ('ignore').
+     * @default 'ignore'
+     */
+    styles?: "cache" | "ignore";
+    /**
+     * Specifies whether to emit entries ('emit') or not ('ignore').
+     * @default 'ignore'
+     */
+    entries?: "emit" | "ignore";
+}
+declare class WorkbookReader extends EventEmitter {
+    input: string | Readable;
+    options: {
+        worksheets: "emit" | "ignore";
+        sharedStrings: "cache" | "emit" | "ignore";
+        hyperlinks: "cache" | "emit" | "ignore";
+        styles: "cache" | "ignore";
+        entries: "emit" | "ignore";
+    };
+    styles: StylesXform;
+    stream?: Readable;
+    sharedStrings?: SharedStringValue[];
+    workbookRels?: WorkbookRelationship[];
+    properties?: WorkbookPropertiesXform;
+    model?: WorkbookModel;
+    constructor(input: string | Readable, options?: WorkbookReaderOptions);
+    _getStream(input: string | Readable): Readable;
+    read(input?: string | Readable, options?: WorkbookReaderOptions): Promise<void>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<WorksheetReader>;
+    parse(input?: string | Readable, options?: WorkbookReaderOptions): AsyncIterableIterator<ParseEvent>;
+    _emitEntry(payload: EntryPayload): void;
+    _parseRels(entry: NodeJS.ReadableStream): Promise<void>;
+    _parseWorkbook(entry: NodeJS.ReadableStream): Promise<void>;
+    _parseSharedStrings(entry: NodeJS.ReadableStream): AsyncIterableIterator<{
+        index: number;
+        text: SharedStringValue;
     }>;
+    _parseStyles(entry: NodeJS.ReadableStream): Promise<void>;
+    _parseWorksheet(iterator: AsyncIterable<unknown>, sheetNo: string): IterableIterator<WorksheetReadyEvent>;
+    _parseHyperlinks(iterator: AsyncIterable<unknown>, sheetNo: string): IterableIterator<HyperlinksEvent>;
 }
 declare const WorkbookReaderOptions: {
     readonly worksheets: readonly ["emit", "ignore"];

package/dist/types/stream/xlsx/workbook-writer.d.ts

@@ -1,51 +1,134 @@
+import fs from "fs";
+import { Zip } from "fflate";
+import { StreamBuf } from "../../utils/stream-buf.js";
+import { StylesXform } from "../../xlsx/xform/style/styles-xform.js";
+import { SharedStrings } from "../../utils/shared-strings.js";
+import { DefinedNames } from "../../doc/defined-names.js";
+import { WorksheetWriter } from "./worksheet-writer.js";
 import type Stream from "stream";
-interface WorkbookWriterOptions {
+import type { Image, WorkbookView, AddWorksheetOptions } from "../../types.js";
+/** Internal medium type for storing images in workbook */
+interface Medium extends Image {
+    type: "image";
+    name: string;
+}
+/** Internal comment reference type for tracking comment files */
+interface CommentRef {
+    commentName: string;
+    vmlDrawing: string;
+}
+export interface ZlibOptions {
+    /** @default constants.Z_NO_FLUSH */
+    flush?: number;
+    /** @default constants.Z_FINISH */
+    finishFlush?: number;
+    /** @default 16*1024 */
+    chunkSize?: number;
+    windowBits?: number;
+    /** compression level (0-9) */
+    level?: number;
+    memLevel?: number;
+    strategy?: number;
+    dictionary?: Buffer | NodeJS.TypedArray | DataView | ArrayBuffer;
+}
+export interface ZipOptions {
+    comment?: string;
+    forceLocalTime?: boolean;
+    forceZip64?: boolean;
+    store?: boolean;
+    zlib?: Partial<ZlibOptions>;
+    /** Alternative way to set compression level */
+    compressionOptions?: {
+        level?: number;
+    };
+}
+export interface WorkbookWriterOptions {
+    /** The date the workbook was created */
     created?: Date;
+    /** The date the workbook was last modified */
     modified?: Date;
+    /** The author of the workbook */
     creator?: string;
+    /** Who last modified the workbook */
     lastModifiedBy?: string;
+    /** The date the workbook was last printed */
     lastPrinted?: Date;
+    /** Specifies whether to use shared strings in the workbook. Default is false */
     useSharedStrings?: boolean;
+    /** Specifies whether to add style information to the workbook. Default is false */
     useStyles?: boolean;
-    zip?: any;
+    /** Zip compression options */
+    zip?: Partial<ZipOptions>;
+    /** Specifies a writable stream to write the XLSX workbook to */
     stream?: Stream;
+    /** If stream not specified, this field specifies the path to a file to write the XLSX workbook to */
     filename?: string;
 }
 declare class WorkbookWriter {
+    /** The date the workbook was created */
     created: Date;
+    /** The date the workbook was last modified */
     modified: Date;
+    /** The author of the workbook */
     creator: string;
+    /** Who last modified the workbook */
     lastModifiedBy: string;
+    /** The date the workbook was last printed */
     lastPrinted?: Date;
+    /** Whether to use shared strings */
     useSharedStrings: boolean;
-    sharedStrings: any;
-    styles: any;
-    _definedNames: any;
-    _worksheets: any[];
-    views: any[];
-    zipOptions?: any;
+    /** Shared strings collection - internal use */
+    sharedStrings: SharedStrings;
+    /** Style manager - internal use */
+    styles: StylesXform;
+    /** Defined names - internal use */
+    _definedNames: DefinedNames;
+    /** Worksheets collection */
+    _worksheets: WorksheetWriter[];
+    /** Workbook views controls how many separate windows Excel will open */
+    views: WorkbookView[];
+    /** Zip options - internal use */
+    zipOptions?: Partial<ZipOptions>;
+    /** Compression level (0-9) */
     compressionLevel: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
-    media: any[];
-    commentRefs: any[];
-    zip: any;
-    stream: any;
-    promise: Promise<any>;
+    /** Media collection (images) - internal use */
+    media: Medium[];
+    /** Comment references - internal use */
+    commentRefs: CommentRef[];
+    /** Zip instance - internal use */
+    zip: Zip;
+    /** Output stream - internal use */
+    stream: Stream | fs.WriteStream | InstanceType<typeof StreamBuf>;
+    /** Internal promise for async operations */
+    promise: Promise<void[]>;
     constructor(options?: WorkbookWriterOptions);
-    get definedNames(): any;
-    _openStream(path: string): any;
-    _addFile(data: string | Buffer, name: string, base64?: boolean): void;
+    get definedNames(): DefinedNames;
+    _openStream(path: string): InstanceType<typeof StreamBuf>;
+    _addFile(data: string | Uint8Array, name: string, base64?: boolean): void;
     _commitWorksheets(): Promise<void>;
-    commit(): Promise<any>;
+    commit(): Promise<void>;
     get nextId(): number;
-    addImage(image: any): number;
-    getImage(id: number): any;
-    addWorksheet(name?: string, options?: any): any;
-    getWorksheet(id?: string | number): any;
+    /**
+     * Add Image to Workbook and return the id
+     */
+    addImage(image: Image): number;
+    /**
+     * Get image by id
+     */
+    getImage(id: number): Image | undefined;
+    /**
+     * Add a new worksheet and return a reference to it
+     */
+    addWorksheet(name?: string, options?: Partial<AddWorksheetOptions>): WorksheetWriter;
+    /**
+     * Fetch sheet by name or id
+     */
+    getWorksheet(id?: string | number): WorksheetWriter | undefined;
     addStyles(): Promise<void>;
     addThemes(): Promise<void>;
     addOfficeRels(): Promise<void>;
     addContentTypes(): Promise<void>;
-    addMedia(): Promise<any>;
+    addMedia(): Promise<void[]>;
     addApp(): Promise<void>;
     addCore(): Promise<void>;
     addSharedStrings(): Promise<void>;

package/dist/types/stream/xlsx/worksheet-reader.d.ts

@@ -1,37 +1,55 @@
 import { EventEmitter } from "events";
-interface WorksheetReaderOptions {
-    workbook: any;
+import { Dimensions } from "../../doc/range.js";
+import { Row } from "../../doc/row.js";
+import { Column } from "../../doc/column.js";
+import type { WorkbookReader, InternalWorksheetOptions } from "./workbook-reader.js";
+import type { WorksheetState } from "../../types.js";
+/** Hyperlink reference from worksheet XML */
+export interface WorksheetHyperlink {
+    ref: string;
+    rId: string;
+}
+/** Events emitted during worksheet parsing */
+export type WorksheetEventType = "row" | "hyperlink";
+/** Row event emitted during parsing */
+export interface RowEvent {
+    eventType: "row";
+    value: Row;
+}
+/** Hyperlink event emitted during parsing */
+export interface HyperlinkEvent {
+    eventType: "hyperlink";
+    value: WorksheetHyperlink;
+}
+export type WorksheetEvent = RowEvent | HyperlinkEvent;
+export interface WorksheetReaderOptions {
+    workbook: WorkbookReader;
     id: number;
-    iterator: any;
-    options?: any;
+    iterator: AsyncIterable<unknown>;
+    options?: InternalWorksheetOptions;
 }
 declare class WorksheetReader extends EventEmitter {
-    workbook: any;
+    workbook: WorkbookReader;
     id: number | string;
-    iterator: any;
-    options: any;
+    iterator: AsyncIterable<unknown>;
+    options: InternalWorksheetOptions;
     name: string;
-    state?: string;
+    state?: WorksheetState;
     private _columns;
     private _keys;
     private _dimensions;
-    hyperlinks?: {
-        [key: string]: any;
-    };
+    hyperlinks?: Record<string, WorksheetHyperlink>;
     constructor({ workbook, id, iterator, options }: WorksheetReaderOptions);
     destroy(): void;
-    get dimensions(): any;
-    get columns(): any[] | null;
-    getColumn(c: string | number): any;
-    getColumnKey(key: string): any;
-    setColumnKey(key: string, value: any): void;
+    get dimensions(): Dimensions;
+    get columns(): Column[] | null;
+    getColumn(c: string | number): Column;
+    getColumnKey(key: string): Column | undefined;
+    setColumnKey(key: string, value: Column): void;
     deleteColumnKey(key: string): void;
-    eachColumnKey(f: (column: any, key: string) => void): void;
+    eachColumnKey(f: (column: Column, key: string) => void): void;
     read(): Promise<void>;
-    [Symbol.asyncIterator](): AsyncIterableIterator<any>;
-    parse(): AsyncIterableIterator<Array<{
-        eventType: string;
-        value: any;
-    }>>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<Row>;
+    parse(): AsyncIterableIterator<WorksheetEvent[]>;
 }
 export { WorksheetReader };

package/dist/types/stream/xlsx/worksheet-writer.d.ts

@@ -1,85 +1,119 @@
-import type { RowBreak } from "../../types.js";
+import { Dimensions } from "../../doc/range.js";
+import { StringBuf } from "../../utils/string-buf.js";
+import { Row } from "../../doc/row.js";
+import { Column } from "../../doc/column.js";
+import { SheetRelsWriter } from "./sheet-rels-writer.js";
+import { SheetCommentsWriter } from "./sheet-comments-writer.js";
+import { DataValidations } from "../../doc/data-validations.js";
+import type { StreamBuf } from "../../utils/stream-buf.js";
+import type { RowBreak, PageSetup, HeaderFooter, WorksheetProperties, WorksheetView, WorksheetState, AutoFilter, WorksheetProtection, ConditionalFormattingOptions } from "../../types.js";
 interface WorksheetWriterOptions {
     id: number;
     name?: string;
     workbook: any;
     useSharedStrings?: boolean;
-    properties?: any;
-    state?: string;
-    pageSetup?: any;
-    views?: any[];
-    autoFilter?: any;
-    headerFooter?: any;
+    properties?: Partial<WorksheetProperties>;
+    state?: WorksheetState;
+    pageSetup?: Partial<PageSetup>;
+    views?: Partial<WorksheetView>[];
+    autoFilter?: AutoFilter;
+    headerFooter?: Partial<HeaderFooter>;
 }
 declare class WorksheetWriter {
     id: number;
     name: string;
-    state: string;
-    _rows: any[] | null;
-    _columns: any[] | null;
+    state: WorksheetState;
+    /** Rows stored while being worked on. Set to null after commit. */
+    _rows: Row[] | null;
+    /** Column definitions */
+    _columns: Column[] | null;
+    /** Column keys mapping: key => Column */
     _keys: {
-        [key: string]: any;
+        [key: string]: Column;
     };
-    _merges: any[];
-    _sheetRelsWriter: any;
-    _sheetCommentsWriter: any;
-    _dimensions: any;
+    /** Merged cell ranges */
+    _merges: Dimensions[];
+    _sheetRelsWriter: SheetRelsWriter;
+    _sheetCommentsWriter: SheetCommentsWriter;
+    _dimensions: Dimensions;
     _rowZero: number;
     committed: boolean;
-    dataValidations: any;
+    dataValidations: DataValidations;
+    /** Shared formulae by address */
     _formulae: {
-        [key: string]: any;
+        [key: string]: unknown;
     };
     _siFormulae: number;
-    conditionalFormatting: any[];
+    conditionalFormatting: ConditionalFormattingOptions[];
     rowBreaks: RowBreak[];
-    properties: any;
-    headerFooter: any;
-    pageSetup: any;
+    properties: Partial<WorksheetProperties> & {
+        defaultRowHeight: number;
+        dyDescent: number;
+        outlineLevelCol: number;
+        outlineLevelRow: number;
+    };
+    headerFooter: Partial<HeaderFooter>;
+    pageSetup: Partial<PageSetup> & {
+        margins: PageSetup["margins"];
+    };
     useSharedStrings: boolean;
     _workbook: any;
     hasComments: boolean;
-    _views: any[];
-    autoFilter: any;
-    _media: any[];
-    sheetProtection: any;
-    _stream?: any;
+    _views: Partial<WorksheetView>[];
+    autoFilter: AutoFilter | null;
+    _media: unknown[];
+    sheetProtection: {
+        sheet?: boolean;
+        algorithmName?: string;
+        saltValue?: string;
+        spinCount?: number;
+        hashValue?: string;
+        [key: string]: unknown;
+    } | null;
+    _stream?: InstanceType<typeof StreamBuf>;
     startedData: boolean;
-    _background?: any;
+    _background?: {
+        imageId?: number;
+        rId?: string;
+    };
     _headerRowCount?: number;
+    /** Relationship Id - assigned by WorkbookWriter */
+    rId?: string;
     constructor(options: WorksheetWriterOptions);
     get workbook(): any;
     get stream(): any;
     destroy(): void;
     commit(): void;
-    get dimensions(): any;
-    get views(): any[];
-    get columns(): any[] | null;
-    set columns(value: any[]);
-    getColumnKey(key: string): any;
-    setColumnKey(key: string, value: any): void;
+    get dimensions(): Dimensions;
+    get views(): Partial<WorksheetView>[];
+    get columns(): Column[] | null;
+    set columns(value: Partial<Column>[]);
+    getColumnKey(key: string): Column | undefined;
+    setColumnKey(key: string, value: Column): void;
     deleteColumnKey(key: string): void;
-    eachColumnKey(f: (column: any, key: string) => void): void;
-    getColumn(c: string | number): any;
+    eachColumnKey(f: (column: Column, key: string) => void): void;
+    getColumn(c: string | number): Column;
     get _nextRow(): number;
-    eachRow(options: any, iteratee?: (row: any, rowNumber: number) => void): void;
-    _commitRow(cRow: any): void;
-    get lastRow(): any;
-    findRow(rowNumber: number): any;
-    getRow(rowNumber: number): any;
-    addRow(value: any): any;
-    findCell(r: any, c?: number): any;
-    getCell(r: any, c?: number): any;
-    mergeCells(...cells: any[]): void;
-    addConditionalFormatting(cf: any): void;
-    removeConditionalFormatting(filter: any): void;
+    eachRow(options: {
+        includeEmpty?: boolean;
+    } | ((row: Row, rowNumber: number) => void), iteratee?: (row: Row, rowNumber: number) => void): void;
+    _commitRow(cRow: Row): void;
+    get lastRow(): Row | undefined;
+    findRow(rowNumber: number): Row | undefined;
+    getRow(rowNumber: number): Row;
+    addRow(value: any[] | Record<string, any>): Row;
+    findCell(r: string | number, c?: number): any;
+    getCell(r: string | number, c?: number): any;
+    mergeCells(...cells: (string | number)[]): void;
+    addConditionalFormatting(cf: ConditionalFormattingOptions): void;
+    removeConditionalFormatting(filter?: number | ((cf: ConditionalFormattingOptions) => boolean)): void;
     addBackgroundImage(imageId: number): void;
     getBackgroundImageId(): number | undefined;
-    protect(password?: string, options?: any): Promise<void>;
+    protect(password?: string, options?: Partial<WorksheetProtection>): Promise<void>;
     unprotect(): void;
     _write(text: string): void;
-    _writeSheetProperties(xmlBuf: any, properties: any, pageSetup: any): void;
-    _writeSheetFormatProperties(xmlBuf: any, properties: any): void;
+    _writeSheetProperties(xmlBuf: StringBuf, properties: Partial<WorksheetProperties> | undefined, pageSetup: Partial<PageSetup> | undefined): void;
+    _writeSheetFormatProperties(xmlBuf: StringBuf, properties: Partial<WorksheetProperties> | undefined): void;
     _writeOpenWorksheet(): void;
     _writeColumns(): void;
     _writeOpenSheetData(): void;

package/dist/types/types.d.ts

@@ -481,22 +481,6 @@ export interface TableProperties {
     rows: any[][];
 }
 export type TableColumn = Required<TableColumnProperties>;
-export interface JSZipGeneratorOptions {
-    compression: "STORE" | "DEFLATE";
-    compressionOptions: null | {
-        level: number;
-    };
-}
-export interface XlsxReadOptions {
-    ignoreNodes?: string[];
-    maxRows?: number;
-    maxCols?: number;
-}
-export interface XlsxWriteOptions {
-    zip?: Partial<JSZipGeneratorOptions>;
-    useSharedStrings?: boolean;
-    useStyles?: boolean;
-}
 export interface Media {
     type: string;
     name: string;
@@ -509,6 +493,10 @@ export interface AddWorksheetOptions {
     headerFooter?: Partial<HeaderFooter>;
     views?: Array<Partial<WorksheetView>>;
     state?: WorksheetState;
+    /** Specifies whether to use shared strings. Overrides workbook setting. */
+    useSharedStrings?: boolean;
+    /** Apply an auto filter to the worksheet */
+    autoFilter?: AutoFilter;
 }
 export interface DefinedNamesRanges {
     name: string;

package/package.json

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