From 7a95c8f41721b5d2f6c743a12e3f266d37a683da Mon Sep 17 00:00:00 2001 From: Yukihiro Hasegawa <49516827+y-hsgw@users.noreply.github.com> Date: Tue, 10 Mar 2026 00:13:19 +0900 Subject: [PATCH] Clarify exported XlsxTemplate types in the declaration file (#221) --- lib/index.d.ts | 107 +++++++++++++------------- package.json | 3 +- test/helpers-test.ts | 13 ++++ test/module/typings/cjs/index.ts | 33 ++++++++ test/module/typings/cjs/package.json | 16 ++++ test/module/typings/cjs/tsconfig.json | 11 +++ test/module/typings/esm/index.ts | 74 ++++++++++++++++++ test/module/typings/esm/package.json | 16 ++++ test/module/typings/esm/tsconfig.json | 11 +++ 9 files changed, 228 insertions(+), 56 deletions(-) create mode 100644 test/module/typings/cjs/index.ts create mode 100644 test/module/typings/cjs/package.json create mode 100644 test/module/typings/cjs/tsconfig.json create mode 100644 test/module/typings/esm/index.ts create mode 100644 test/module/typings/esm/package.json create mode 100644 test/module/typings/esm/tsconfig.json diff --git a/lib/index.d.ts b/lib/index.d.ts index 4613c49..6202452 100644 --- a/lib/index.d.ts +++ b/lib/index.d.ts @@ -1,54 +1,51 @@ import * as etree from "elementtree"; import * as JSZip from "jszip"; -export interface TemplatePlaceholder{ - type: string; - string?: string; - full: boolean; - name: string; - key: string; - placeholder?: string +declare namespace XlsxTemplate { + interface TemplatePlaceholder { + type: string; + string?: string; + full: boolean; + name: string; + key: string; + placeholder?: string; + subType?: string; + } + + interface NamedTable { + filename: string; + root: etree.Element; + } + + interface OutputByType { + base64: string; + uint8array: Uint8Array; + arraybuffer: ArrayBuffer; + blob: Blob; + nodebuffer: Buffer; + } + + type GenerateType = keyof OutputByType; + + type GenerateOptions = { + type: T; + }; + + interface RangeSplit { + start: string; + end: string; + } + + interface ReferenceAddress { + table?: string; + colAbsolute?: boolean; + col: string; + rowAbsolute?: boolean; + row: number; + } } -export interface NamedTable{ - filename: string; - root: etree.Element; -} - -namespace XlsxTemplate { - -} - -interface OutputByType { - base64: string; - uint8array: Uint8Array; - arraybuffer: ArrayBuffer; - blob: Blob; - nodebuffer: Buffer; -} - -type GenerateType = keyof OutputByType; - -export type GenerateOptions = { - type: T; -}; - -interface RangeSplit -{ - start: string; - end: string; -} - -interface ReferenceAddress -{ - table?: string; - colAbsolute?: boolean; - col : string; - rowAbsolute?: boolean; - row : number; -} - -class XlsxTemplate +declare class XlsxTemplate { public readonly sharedStrings: string[]; protected readonly workbook: etree.ElementTree; @@ -62,16 +59,16 @@ class XlsxTemplate public copySheet(sheetName : string, copyName : string, binary? : boolean) : this; public loadTemplate(data : Buffer) : void; public substitute(sheetName : string | number, substitutions : Object) : void; - public generate(options: GenerateOptions): OutputByType[T]; + public generate(options: XlsxTemplate.GenerateOptions): XlsxTemplate.OutputByType[T]; public generate() : any; public replaceString(oldString : string, newString : string) : number; // returns idx public stringIndex(s : string) : number; // returns idx public writeSharedStrings() : void; - public splitRef(ref : string) : ReferenceAddress; - public joinRef(ref : ReferenceAddress) : string; + public splitRef(ref : string) : XlsxTemplate.ReferenceAddress; + public joinRef(ref : XlsxTemplate.ReferenceAddress) : string; public addSharedString(s : string) : any; // I think s is a string? Not sure what its return "idx" is though, I think it's a number? Is "idx" short for "index"? - public substituteScalar(cell : any, string: string, placeholder: TemplatePlaceholder, substitution: any): string; + public substituteScalar(cell : any, string: string, placeholder: XlsxTemplate.TemplatePlaceholder, substitution: any): string; public charToNum(str : string) : number; public numToChar(num : number) : string; public nextCol(ref : string) : string; @@ -79,9 +76,9 @@ class XlsxTemplate public stringify(value : Date | number | boolean | string) : string; public isWithin(ref : string, startRef : string, endRef : string) : boolean; public isRange(ref : string) : boolean; - public splitRange(range : string) : RangeSplit; - public joinRange(range : RangeSplit) : string; - public extractPlaceholders(templateString : string) : TemplatePlaceholder[]; + public splitRange(range : string) : XlsxTemplate.RangeSplit; + public joinRange(range : XlsxTemplate.RangeSplit) : string; + public extractPlaceholders(templateString : string) : XlsxTemplate.TemplatePlaceholder[]; // need typing properly protected _rebuild() : void; @@ -100,8 +97,8 @@ class XlsxTemplate protected substituteTableColumnHeaders(tables : any, substitutions : any) : void; protected insertCellValue(cell : any, substitution : any) : string; protected substituteArray(cells : any[], cell : any, substitution : any); - protected substituteTable(row : any, newTableRows : any, cells : any[], cell : any, namedTables : any, substitution : any, key : any, placeholder : TemplatePlaceholder, drawing : etree.ElementTree) : any; - protected substituteImage(cell : any, string : string, placeholder: TemplatePlaceholder, substitution : any, drawing : etree.ElementTree) : boolean + protected substituteTable(row : any, newTableRows : any, cells : any[], cell : any, namedTables : any, substitution : any, key : any, placeholder : XlsxTemplate.TemplatePlaceholder, drawing : etree.ElementTree) : any; + protected substituteImage(cell : any, string : string, placeholder: XlsxTemplate.TemplatePlaceholder, substitution : any, drawing : etree.ElementTree) : boolean protected substituteImageInCell(cell : any, substitution : any) : boolean; protected cloneElement(element : any, deep? : any) : any; protected replaceChildren(parent : any, children : any) : void; diff --git a/package.json b/package.json index 2587963..8ffd9ae 100644 --- a/package.json +++ b/package.json @@ -69,7 +69,8 @@ }, "scripts": { "compile": "tsc", - "test": "npm run compile && jest", + "test:module": "find test/module -name package.json -execdir npm test \\;", + "test": "npm run compile && npm run test:module && jest", "prepublishOnly": "npm run compile" }, "readme": "", diff --git a/test/helpers-test.ts b/test/helpers-test.ts index dac91af..519e232 100644 --- a/test/helpers-test.ts +++ b/test/helpers-test.ts @@ -128,6 +128,19 @@ describe("Helpers", function() { }]); }); + it("can extract placeholders with subtypes", function() { + var t = new XlsxTemplate(); + + expect(t.extractPlaceholders("${table:foo.bar:image}")).toEqual([{ + full: true, + key: "bar", + name: "foo", + placeholder: "${table:foo.bar:image}", + subType: "image", + type: "table" + }]); + }); + it("can handle strings with no placeholders", function() { var t = new XlsxTemplate(); diff --git a/test/module/typings/cjs/index.ts b/test/module/typings/cjs/index.ts new file mode 100644 index 0000000..12e6da6 --- /dev/null +++ b/test/module/typings/cjs/index.ts @@ -0,0 +1,33 @@ +import XlsxTemplate = require("xlsx-template"); + +const generateType: XlsxTemplate.GenerateType = "base64"; + +const placeholder: XlsxTemplate.TemplatePlaceholder = { + type: "normal", + full: true, + name: "foo", + key: "bar", +}; + +const namedTable: XlsxTemplate.NamedTable = { + filename: "table1.xml", + root: {} as any, +}; + +const outputByType: XlsxTemplate.OutputByType = { + base64: "base64string", + uint8array: new Uint8Array(), + arraybuffer: new ArrayBuffer(0), + blob: new Blob(), + nodebuffer: Buffer.from([]), +}; + +const rangeSplit: XlsxTemplate.RangeSplit = { + start: "A1", + end: "C3", +}; + +const referenceAddress: XlsxTemplate.ReferenceAddress = { + col: "A", + row: 1, +}; \ No newline at end of file diff --git a/test/module/typings/cjs/package.json b/test/module/typings/cjs/package.json new file mode 100644 index 0000000..0eaefc1 --- /dev/null +++ b/test/module/typings/cjs/package.json @@ -0,0 +1,16 @@ +{ + "name": "commonjs-typings-test", + "version": "1.0.0", + "description": "", + "type": "commonjs", + "scripts": { + "test:types": "tsc --noEmit", + "test": "npm i --no-save --no-package-lock && npm run test:types" + }, + "keywords": [], + "author": "", + "license": "MIT", + "dependencies": { + "xlsx-template": "file:../../../.." + } +} diff --git a/test/module/typings/cjs/tsconfig.json b/test/module/typings/cjs/tsconfig.json new file mode 100644 index 0000000..fbef331 --- /dev/null +++ b/test/module/typings/cjs/tsconfig.json @@ -0,0 +1,11 @@ +{ + "compilerOptions": { + "target": "es2015", + "module": "commonjs", + "esModuleInterop": true, + "noEmit": true, + "strict": false, + "skipLibCheck": true, + "types": ["node"] + }, +} diff --git a/test/module/typings/esm/index.ts b/test/module/typings/esm/index.ts new file mode 100644 index 0000000..da17d66 --- /dev/null +++ b/test/module/typings/esm/index.ts @@ -0,0 +1,74 @@ +import XlsxTemplate, { + GenerateOptions, + GenerateType, + TemplatePlaceholder, + NamedTable, + OutputByType, + RangeSplit, + ReferenceAddress, +} from "xlsx-template"; + +const generateType1: XlsxTemplate.GenerateType = "base64"; +const generateType2: GenerateType = "base64"; + +const generateOptions1: XlsxTemplate.GenerateOptions = { + type: "base64", +}; +const generateOptions2: GenerateOptions = { + type: "base64", +}; + +const placeholder1: XlsxTemplate.TemplatePlaceholder = { + type: "normal", + full: true, + name: "foo", + key: "bar", +}; +const placeholder2: TemplatePlaceholder = { + type: "normal", + full: true, + name: "foo", + key: "bar", +}; + +const namedTable1: XlsxTemplate.NamedTable = { + filename: "table1.xml", + root: {} as any, +}; +const namedTable2: NamedTable = { + filename: "table1.xml", + root: {} as any, +}; + +const outputByType1: XlsxTemplate.OutputByType = { + base64: "base64string", + uint8array: new Uint8Array(), + arraybuffer: new ArrayBuffer(0), + blob: new Blob(), + nodebuffer: Buffer.from([]), +}; +const outputByType2: OutputByType = { + base64: "base64string", + uint8array: new Uint8Array(), + arraybuffer: new ArrayBuffer(0), + blob: new Blob(), + nodebuffer: Buffer.from([]), +}; + +const rangeSplit1: XlsxTemplate.RangeSplit = { + start: "A1", + end: "C3", +}; +const rangeSplit2: RangeSplit = { + start: "A1", + end: "C3", +}; + +const referenceAddress1: XlsxTemplate.ReferenceAddress = { + col: "A", + row: 1, +}; +const referenceAddress2: ReferenceAddress = { + col: "A", + row: 1, +}; \ No newline at end of file diff --git a/test/module/typings/esm/package.json b/test/module/typings/esm/package.json new file mode 100644 index 0000000..f27b1b1 --- /dev/null +++ b/test/module/typings/esm/package.json @@ -0,0 +1,16 @@ +{ + "name": "esm-typings-test", + "version": "1.0.0", + "description": "", + "type": "module", + "scripts": { + "test:types": "tsc --noEmit", + "test": "npm i --no-save --no-package-lock && npm run test:types" + }, + "keywords": [], + "author": "", + "license": "MIT", + "dependencies": { + "xlsx-template": "file:../../../.." + } +} diff --git a/test/module/typings/esm/tsconfig.json b/test/module/typings/esm/tsconfig.json new file mode 100644 index 0000000..fbef331 --- /dev/null +++ b/test/module/typings/esm/tsconfig.json @@ -0,0 +1,11 @@ +{ + "compilerOptions": { + "target": "es2015", + "module": "commonjs", + "esModuleInterop": true, + "noEmit": true, + "strict": false, + "skipLibCheck": true, + "types": ["node"] + }, +}