@vdhewei/xlsx-template-lib 1.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PeerPackerHe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,7 @@
+## xlsx-template-lib
+
+## Installation
+
+```bash
+npm install @vdhewei/xlsx-template-lib
+```

package/dist/index.d.mts

@@ -0,0 +1,470 @@
+import * as etree from 'elementtree';
+import { Element } from 'elementtree';
+import JsZip from 'jszip';
+import exceljs from 'exceljs';
+export { default as exceljs } from 'exceljs';
+
+interface Placeholder {
+    placeholder: string;
+    type: string;
+    name: string;
+    key?: string;
+    subType?: string;
+    full: boolean;
+    [customKey: string]: any;
+}
+interface Ref {
+    table?: string | null;
+    colAbsolute?: boolean;
+    col: string;
+    rowAbsolute?: boolean;
+    row: number;
+}
+interface Range {
+    start: string;
+    end: string;
+}
+interface SheetInfo {
+    id: number;
+    name: string;
+    filename: string;
+    root?: etree.Element;
+}
+interface SheetInfoMust {
+    id: number;
+    name: string;
+    filename: string;
+    root: etree.Element;
+}
+interface DrawingInfo {
+    filename: string;
+    root: any;
+    relFilename?: string;
+    relRoot?: any;
+}
+interface TableInfo {
+    filename: string;
+    root: any;
+}
+interface RelsInfo {
+    filename: string;
+    root: any;
+}
+interface WorkbookOptions {
+    moveImages?: boolean;
+    substituteAllTableRow?: boolean;
+    moveSameLineImages?: boolean;
+    imageRatio?: number;
+    pushDownPageBreakOnTableSubstitution?: boolean;
+    imageRootPath?: string | null;
+    handleImageError?: ((imageObj: any, error: Error) => void) | null;
+}
+type OutputByType = {
+    readonly base64: string;
+    readonly string: string;
+    readonly text: string;
+    readonly binarystring: string;
+    readonly array: readonly number[];
+    readonly uint8array: Uint8Array;
+    readonly arraybuffer: ArrayBuffer;
+    readonly blob: Blob;
+    readonly nodebuffer: Buffer;
+};
+type CustomReplacer = (cell: any, stringValue: string, placeholder: Placeholder, substitution: any) => string | undefined | null;
+type CustomPlaceholderExtractor = (inputString: string, options: ExtensionOptions) => Placeholder[];
+declare enum BufferType {
+    Base64 = "base64",
+    String = "string",
+    Text = "text",
+    Blob = "blob",
+    Array = "array",
+    NodeBuffer = "nodebuffer",
+    Uint8array = "uint8array",
+    Arraybuffer = "arraybuffer",
+    BinaryString = "binarystring"
+}
+type BeforeReplaceHook = (stringValue: string, substitutions: Record<string, any>) => string | undefined | null;
+type AfterReplaceHook = (resultString: string, stringValue: string, substitutions: Record<string, any>) => string;
+type CustomFormatter = (value: any, placeholder: Placeholder, key?: string) => string | undefined | null;
+type QueryFunction = (obj: Object | Record<string, any>, p: Placeholder) => any | undefined;
+interface ExtensionOptions {
+    customReplacer?: CustomReplacer;
+    customPlaceholderExtractor?: CustomPlaceholderExtractor;
+    replacers?: CustomReplacer[];
+    beforeReplace?: BeforeReplaceHook;
+    afterReplace?: AfterReplaceHook;
+    formatters?: CustomFormatter[];
+    customPlaceholderRegex?: RegExp;
+    enableDefaultParsing?: boolean;
+    customQueryFunction?: QueryFunction;
+}
+type FullOptions = WorkbookOptions & ExtensionOptions;
+type PathImpl<T, Key extends string> = T extends object ? Key extends `${infer K}.${infer Rest}` ? K extends keyof T ? PathImpl<T[K], Rest> : never : Key extends keyof T ? T[Key] : never : any;
+type PathType<T, Key extends string> = string extends Key ? any : PathImpl<T, Key>;
+declare function valueDotGet<T extends Record<string, any> & object, P extends string>(obj: T, path: P, defaultValue?: PathType<T, P>): PathType<T, P>;
+declare function defaultValueDotGet<T extends Record<string, any> & object>(obj: T, p: Placeholder): PathType<T, string>;
+declare const defaultExtractPlaceholders: CustomPlaceholderExtractor;
+declare const defaultFormatters: CustomFormatter[];
+declare const isUrl: (str: string) => boolean;
+declare const toArrayBuffer: (buffer: Buffer) => ArrayBuffer;
+declare class Workbook {
+    option: FullOptions;
+    archive: JsZip;
+    sharedStrings: string[];
+    sharedStringsLookup: Record<string, number>;
+    sharedStringsPath: string;
+    sheets: SheetInfo[] | SheetInfoMust[];
+    sheet: SheetInfo | SheetInfoMust | null;
+    workbook: Element | null;
+    workbookPath: string | null;
+    contentTypes: any;
+    prefix: string | null;
+    workbookRels: Element | null;
+    calChainRel: any;
+    calcChainPath: string;
+    private richDataIsInit;
+    private _relsrichValueRel;
+    private rdrichvalue;
+    private rdrichvaluestructure;
+    private rdRichValueTypes;
+    private richValueRel;
+    private metadata;
+    constructor(option?: FullOptions);
+    static parse(data: Buffer | string, option?: FullOptions): Promise<Workbook>;
+    addReplacer(replacer: CustomReplacer): this;
+    addFormatter(formatter: CustomFormatter): this;
+    setBeforeReplaceHook(hook: BeforeReplaceHook): this;
+    setAfterReplaceHook(hook: AfterReplaceHook): this;
+    setPlaceholderExtractor(extractor: CustomPlaceholderExtractor): this;
+    setPlaceholderRegex(regex: RegExp, enableDefaultParsing?: boolean): this;
+    setQueryFunctionHandler(h: QueryFunction): this;
+    private executeReplacers;
+    private executeFormatters;
+    private executeBeforeReplaceHook;
+    private executeAfterReplaceHook;
+    deleteSheet(sheetName: string | number): Promise<this>;
+    copySheet(sheetName: string | number, copyName?: string, binary?: boolean): Promise<this>;
+    private _rebuild;
+    loadTemplate(data: Buffer | string): Promise<void>;
+    substituteAll(substitutions: Record<string, any>): Promise<void>;
+    substitute(sheetName: string | number, substitutions: Record<string, any>): Promise<void>;
+    generate<T extends JsZip.OutputType>(options?: JsZip.JSZipGeneratorOptions<T>): Promise<OutputByType[T]>;
+    valueGet(substitutions: object | Record<string, any>, p: Placeholder, full?: boolean): any;
+    private writeSharedStrings;
+    private addSharedString;
+    private stringIndex;
+    private replaceString;
+    private loadSheets;
+    loadSheet(sheet: string | number): Promise<SheetInfoMust>;
+    loadSheetRels(sheetFilename: string): Promise<RelsInfo>;
+    private initSheetRels;
+    private loadDrawing;
+    private addContentType;
+    private initDrawing;
+    private writeDrawing;
+    private moveAllImages;
+    private _moveTwoCellAnchor;
+    loadTables(sheet: Element, sheetFilename: string): Promise<TableInfo[]>;
+    private writeTables;
+    private substituteHyperlinks;
+    private substituteTableColumnHeaders;
+    extractPlaceholders(inputString: string): Placeholder[];
+    private splitRef;
+    private joinRef;
+    private nextCol;
+    private nextRow;
+    private charToNum;
+    private numToChar;
+    private generateUUID;
+    private isRange;
+    private isWithin;
+    stringify(value: any, placeholder?: Placeholder, key?: string): string;
+    private insertCellValue;
+    private substituteScalar;
+    private substituteArray;
+    private substituteTable;
+    private initRichData;
+    private writeRichDataAlreadyExist;
+    private writeRichData;
+    private substituteImageInCell;
+    private substituteImage;
+    private cloneElement;
+    private replaceChildren;
+    private getCurrentRow;
+    private getCurrentCell;
+    private updateRowSpan;
+    private splitRange;
+    private joinRange;
+    private pushRight;
+    private pushDown;
+    hideCols(sheetName: string | number, hideItemIndexes: number[]): Promise<this>;
+    private getWidthCell;
+    private getWidthMergeCell;
+    private getHeightCell;
+    private getHeightMergeCell;
+    private getNbRowOfMergeCell;
+    private pixelsToEMUs;
+    private columnWidthToEMUs;
+    private rowHeightToEMUs;
+    private findMaxFileId;
+    private cellInMergeCells;
+    private imageToBuffer;
+    private findMaxId;
+}
+declare const generateXlsxTemplate: <T extends JsZip.OutputType>(data: Buffer, values: Object, options?: JsZip.JSZipGeneratorOptions<T> & FullOptions) => Promise<OutputByType[T]>;
+
+type CellPosition = {
+    Row: string;
+    Column: number;
+    Sheet?: string | number;
+};
+type CellPoint = {
+    Row: number;
+    Column: number;
+};
+interface PlaceholderCellValue {
+    toString(): string;
+    mergeCell(values: string[]): string;
+}
+type ScanTokenData = {
+    value: string;
+    token: string;
+};
+type MacroArgs = {
+    type: string;
+    columnParam: number;
+    rowParam: number[] | number;
+    formatter?: string;
+};
+type ExtractMacroArgs = {
+    argToken: string;
+    startToken: string;
+    endToken: string;
+};
+declare enum RuleToken {
+    AliasToken = "alias",
+    CellToken = "cell",
+    MergeCellToken = "mergeCell",
+    RowCellToken = "rowCell",
+    UseAliasToken = "@",
+    RangeToken = "-",
+    PosToken = ":",
+    FunctionPatternToken = "<?>",
+    AnyToken = "?",
+    VarPatternToken = "${?}",
+    UndefinedToken = "",
+    EqualToken = "=",
+    ArgPosToken = ",",
+    LparenToken = "(",
+    RparenToken = ")",
+    DotGetToken = ".",
+    CompileGenToken = "compile:GenCell",
+    CompileMacroToken = "compile:Macro"
+}
+type RuleValue = {
+    express: string;
+    tokens: RuleToken[];
+    cells?: CellPoint[];
+    key?: string;
+    ref?: string[];
+    func?: string;
+    compileExpress?: string[];
+    posExpr?: RuleValue;
+    funcExpr?: RuleValue;
+    value: string | number[] | number | CellPoint | RangeCell | any[];
+    [key: string]: any;
+};
+type RuleResult = {
+    rules: Map<RuleToken, RuleValue[]>;
+};
+type FilterMacroResult = {
+    tokens: RuleToken[];
+    express: string[];
+};
+type CompileChecker = (iv: RuleResult, ctx: RuleMapOptions) => Error[] | undefined;
+interface RuleOptions {
+    startLine?: number;
+    endLine?: number;
+    endColumn?: number;
+    startColumn?: number;
+    ruleKeyMap?: Map<RuleToken, string>;
+    compileCheckers?: CompileChecker[];
+    compileSheets?: string[];
+    [key: string]: any;
+    setEndRow(end: number): RuleOptions;
+    parseToken(value: string): RuleToken;
+    setEndColumn(end: number): RuleOptions;
+    setStartRow(start: number): RuleOptions;
+    setStartColumn(start: number): RuleOptions;
+    getContextMap(): Map<RuleToken, RuleValue[]>;
+    addRuleMap(key: RuleToken, value: string): RuleOptions;
+    parseDefault(worksheet: exceljs.Worksheet): RuleOptions;
+    getCompileCheckHandlers(): CompileChecker[] | undefined;
+}
+interface RangeCell {
+    minRow: number;
+    maxRow: number;
+    stepRow: number;
+    minColumn: number;
+    maxColumn: number;
+    stepColumn: number;
+    getCells(): CellPoint[];
+}
+declare class RuleMapOptions implements RuleOptions {
+    startLine?: number;
+    endLine?: number;
+    endColumn?: number;
+    startColumn?: number;
+    ruleKeyMap?: Map<RuleToken, string>;
+    compileCheckers?: CompileChecker[];
+    compileSheets?: string[];
+    [key: string]: any;
+    constructor(m?: Map<RuleToken, string>);
+    static withAllSheets(w: exceljs.Workbook, excludes?: string[]): RuleOptions;
+    parseDefault(worksheet: exceljs.Worksheet): RuleOptions;
+    addRuleMap(key: RuleToken, value: string): RuleOptions;
+    setStartRow(start: number): RuleOptions;
+    setStartColumn(start: number): RuleOptions;
+    setEndRow(end: number): RuleOptions;
+    setEndColumn(end: number): RuleOptions;
+    parseToken(value: string): RuleToken;
+    getContextMap(): Map<RuleToken, RuleValue[]>;
+    getCompileCheckHandlers(): CompileChecker[] | undefined;
+}
+declare class CompileContext extends RuleMapOptions {
+    private aliasMap;
+    sheet?: exceljs.Worksheet;
+    constructor(m?: Map<RuleToken, string>);
+    static create(r: RuleMapOptions): CompileContext;
+    private init;
+    loadAlias(m: Map<RuleToken, RuleValue[]>): this;
+    setAlias(key: string, value: string): void;
+    getAlias(key: string): string | undefined;
+    hasAlias(key: string): boolean;
+    filterSheet(sheetName: string): boolean;
+}
+type TokenParserReply = {
+    ok: boolean;
+    values?: any;
+    expr?: RuleValue;
+    [key: string]: any;
+};
+type TokenParser = (ctx: Map<RuleToken, RuleValue[]>, t: RuleToken, value: string) => TokenParserReply;
+type TokenParseResolver = {
+    exists: boolean;
+    handler?: TokenParser;
+};
+declare class DefaultPlaceholderCellValue implements PlaceholderCellValue {
+    private readonly placeholder;
+    private readonly mergeCellPlaceholder?;
+    constructor(p: string, merge?: string);
+    mergeCell(values: string[]): string;
+    toString(): string;
+}
+declare class TokenParserManger {
+    static aliasParse(ctx: Map<RuleToken, RuleValue[]>, token: RuleToken, value: string): TokenParserReply;
+    static equalParse(ctx: Map<RuleToken, RuleValue[]>, token: RuleToken, value: string): TokenParserReply;
+    static cellParse(ctx: Map<RuleToken, RuleValue[]>, token: RuleToken, value: string): TokenParserReply;
+    static useAliasParse(ctx: Map<RuleToken, RuleValue[]>, token: RuleToken, value: string): TokenParserReply;
+    static rangeParse(ctx: Map<RuleToken, RuleValue[]>, token: RuleToken, value: string): TokenParserReply;
+    static posParse(ctx: Map<RuleToken, RuleValue[]>, token: RuleToken, value: string): TokenParserReply;
+    static mergeCellParse(ctx: Map<RuleToken, RuleValue[]>, token: RuleToken, value: string): TokenParserReply;
+    static rowCellParse(ctx: Map<RuleToken, RuleValue[]>, token: RuleToken, value: string): TokenParserReply;
+    static functionPatternParse(ctx: Map<RuleToken, RuleValue[]>, token: RuleToken, value: string): TokenParserReply;
+    static varPatternParse(ctx: Map<RuleToken, RuleValue[]>, token: RuleToken, value: string): TokenParserReply;
+    static compileExprExtract(value: string): RuleToken[];
+    static getTokenByCtx(ctx: Map<RuleToken, RuleValue[]>, token: RuleToken): string;
+    static scanToken(value: string, startToken: string, endTokens: string[]): ScanTokenData[];
+    static split(argsStr: string, argsSplitToken: string, ignoreTokenRange: string[]): string[];
+    static filterMacro(values: string[]): FilterMacroResult | undefined;
+    static extractUseAliasTokens(ctx: Map<RuleToken, RuleValue[]>, args: string[]): RuleToken[];
+    static toList(ctx: Map<RuleToken, RuleValue[]>, endTokens: RuleToken[]): string[];
+    private static parseRangeValue;
+    private static parsePosNumber;
+}
+declare function columnLetterToNumber(letter: string): number;
+declare function columnNumberToLetter(num: number): string;
+type MacroUnitHelper = (v: string) => string;
+declare const loadWorkbook: <T extends ArrayBuffer | Buffer | string>(data: T) => Promise<exceljs.Workbook>;
+declare const scanCellSetPlaceholder: <T extends ArrayBuffer | Buffer | string>(excelBuffer: T, cell: CellPosition & {
+    Sheet: string | number;
+}, placeholder: PlaceholderCellValue) => Promise<ArrayBuffer | undefined>;
+declare const workSheetSetPlaceholder: (worksheet: exceljs.Worksheet, cell: CellPosition, placeholder: PlaceholderCellValue) => exceljs.Worksheet;
+declare const isRuleToken: (t: RuleToken) => boolean;
+declare const getTokenParser: (token: RuleToken) => TokenParseResolver;
+declare const registerTokenParser: (token: RuleToken, h: TokenParser) => boolean;
+declare const registerTokenParserMust: (token: RuleToken, h: TokenParser) => void;
+declare const parseWorkSheetRules: (worksheet: exceljs.Worksheet, options?: RuleOptions) => RuleResult;
+declare const hasGeneratorToken: (tokens: RuleToken[]) => boolean;
+declare const compileWorkSheetPlaceholder: (ctx: CompileContext, sheet: exceljs.Worksheet, result: RuleResult) => Error[] | undefined;
+type CompileResult = {
+    workbook: exceljs.Workbook;
+    configure?: RuleResult;
+    errs?: Error[];
+};
+declare const compileWorkSheet: <T extends ArrayBuffer | Buffer | string>(data: T, sheetName: string | number, options?: RuleOptions) => Promise<exceljs.Xlsx | Error[]>;
+declare class ExprResolver {
+    static toBuffer: (w: exceljs.Workbook) => Promise<Buffer>;
+    static compile: <T extends ArrayBuffer | Buffer | string>(data: T, ruleSheetName: string | number, options?: RuleOptions) => Promise<CompileResult>;
+    static toRowCells: (cells: CellPoint[]) => CellPoint[][];
+    static fetchAlias: (m: Map<RuleToken, RuleValue[]> | RuleResult) => Map<string, string>;
+    static getExprEnd: (macroExpr: string, matchIndex: number, rparenToken: string) => number;
+    static compileCheck: (iv: RuleResult, ctx: RuleOptions) => Error[] | undefined;
+    static extractMacro: (expr: string, options: ExtractMacroArgs) => MacroArgs;
+    static compileRowCells: (ctx: CompileContext, expr: RuleValue, cellPoints: CellPoint[], rowIndex: number, errs: Error[]) => void;
+    static searchIndexOf: (str: string, substr: string[], position?: number) => number;
+    static resolveAliasExpr: (ctx: CompileContext, templateValue: string, index: number) => string;
+    static resolveValueExpr: (ctx: CompileContext, templateValue: string) => string | null;
+    static resolveFunctionExpr: (ctx: CompileContext, templateValue: string, expr: RuleValue) => string;
+    static removeUnExportSheets: (w: exceljs.Workbook, options: RuleOptions) => exceljs.Workbook;
+    static resolveCompileMacroGen: (ctx: CompileContext, expr: string, currentCellIndex: number) => string;
+    static resolveCompileMacroExpr: (ctx: CompileContext, macroExpr: string, macroTokens: RuleToken[], currentCellIndex: number, totalCells: number) => string;
+}
+
+type Argument = {
+    root: string;
+    alias?: string;
+    groups?: string[];
+    suffix?: string;
+    default: number | string | any;
+    func: string;
+    p: Placeholder;
+};
+type CmdFunction = (obj: Object | Record<string, any>, argument: Argument) => any | undefined;
+declare class ArgumentData {
+    root: string;
+    p: Placeholder;
+    default: number | string | any;
+    alias?: string;
+    suffix?: string;
+    groups?: string[];
+    tokenIterIndex: number;
+    private readonly func;
+    constructor(fn: string, p: Placeholder);
+    To(): Argument;
+    Add(startToken: string, value: string | undefined): void;
+    ParseAlias(alias: any | object | Record<string, string>): void;
+}
+declare class ArgumentValue {
+    private readonly value;
+    private readonly defaultValue;
+    constructor(value: any, defValue: any);
+    isUndefined(): boolean;
+    getDefault(): any;
+    getNumber(): number;
+    toString(): string;
+}
+declare const ArgumentValueLoader: (values: Object | Record<string, any>, args: Argument) => ArgumentValue[];
+declare const resolveArgument: (p: Placeholder, data: object | Record<string, any>) => Argument;
+declare const commandExtendQuery: QueryFunction;
+declare const AddCommand: (key: string, h: CmdFunction) => boolean;
+declare const AddCommandMust: (key: string, h: CmdFunction) => void;
+declare const generateCommandsXlsxTemplate: <T extends JsZip.OutputType>(data: Buffer, values: Object, options?: JsZip.JSZipGeneratorOptions<T> & FullOptions) => Promise<OutputByType[T]>;
+declare const getCommands: () => Map<string, CmdFunction>;
+type AutoOptions = RuleOptions & {
+    sheetName?: string;
+};
+declare const compileRuleSheetName = "export_metadata.config";
+declare const generateCommandsXlsxTemplateWithCompile: <T extends JsZip.OutputType>(data: Buffer, values: Object, compileOptions: AutoOptions, options?: JsZip.JSZipGeneratorOptions<T> & FullOptions) => Promise<OutputByType[T]>;
+
+export { AddCommand, AddCommandMust, type AfterReplaceHook, type Argument, ArgumentData, ArgumentValue, ArgumentValueLoader, type AutoOptions, type BeforeReplaceHook, BufferType, type CellPosition, type CmdFunction, CompileContext, type CompileResult, type CustomFormatter, type CustomPlaceholderExtractor, type CustomReplacer, DefaultPlaceholderCellValue, type DrawingInfo, ExprResolver, type ExtensionOptions, type ExtractMacroArgs, type FilterMacroResult, type FullOptions, type MacroArgs, type MacroUnitHelper, type OutputByType, type Placeholder, type PlaceholderCellValue, type QueryFunction, type Range, type Ref, type RelsInfo, RuleMapOptions, type RuleOptions, type RuleResult, RuleToken, type SheetInfo, type TableInfo, TokenParserManger, Workbook, type WorkbookOptions, columnLetterToNumber, columnNumberToLetter, commandExtendQuery, compileRuleSheetName, compileWorkSheet, compileWorkSheetPlaceholder, defaultExtractPlaceholders, defaultFormatters, defaultValueDotGet, generateCommandsXlsxTemplate, generateCommandsXlsxTemplateWithCompile, generateXlsxTemplate, getCommands, getTokenParser, hasGeneratorToken, isRuleToken, isUrl, loadWorkbook, parseWorkSheetRules, registerTokenParser, registerTokenParserMust, resolveArgument, scanCellSetPlaceholder, toArrayBuffer, valueDotGet, workSheetSetPlaceholder };