Version bump

* Add shading and border settings to paragraph style options.

* Fix prettier

---------

Co-authored-by: Dolan Miu <dolan_miu@hotmail.com>

demo/95-paragraph-style-with-shading-and-borders.ts

@@ -0,0 +1,60 @@
+import * as fs from "fs";
+import { BorderStyle, Document, Packer, Paragraph, TextRun } from "docx";
+
+const doc = new Document({
+    styles: {
+        paragraphStyles: [
+            {
+                id: "withSingleBlackBordersAndYellowShading",
+                name: "Paragraph Style with Black Borders and Yellow Shading",
+                basedOn: "Normal",
+                paragraph: {
+                    shading: {
+                        color: "#fff000",
+                        type: "solid",
+                    },
+                    border: {
+                        top: {
+                            style: BorderStyle.SINGLE,
+                            color: "#000000",
+                            size: 4,
+                        },
+                        bottom: {
+                            style: BorderStyle.SINGLE,
+                            color: "#000000",
+                            size: 4,
+                        },
+                        left: {
+                            style: BorderStyle.SINGLE,
+                            color: "#000000",
+                            size: 4,
+                        },
+                        right: {
+                            style: BorderStyle.SINGLE,
+                            color: "#000000",
+                            size: 4,
+                        },
+                    },
+                },
+            },
+        ],
+    },
+    sections: [
+        {
+            children: [
+                new Paragraph({
+                    style: "withSingleBlackBordersAndYellowShading",
+                    children: [
+                        new TextRun({
+                            text: "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.",
+                        }),
+                    ],
+                }),
+            ],
+        },
+    ],
+});
+
+Packer.toBuffer(doc).then((buffer) => {
+    fs.writeFileSync("My Document.docx", buffer);
+});

docs/usage/packers.md

@@ -2,7 +2,7 @@
 
 > Packers are the way in which `docx` turns your code into `.docx` format. It is completely decoupled from the `docx.Document`.
 
-Packers works in both a node and browser environment (Angular etc). Now, the packer returns a `Buffer`, `Blob` or `base64 string`. It is up to you to take that and persist it with node's `fs`, send it down as a downloadable file, or anything else you wish. As of `version 4+`, this library will not have options to export to PDF.
+Packers works in both a node and browser environment (Angular etc). Now, the packer returns a `Buffer`, `Blob`, `string`, `base64 string`, or `Stream`. It is up to you to take that and persist it with node's `fs`, send it down as a downloadable file, or anything else you wish. As of `version 4+`, this library will not have options to export to PDF.
 
 ### Export as Buffer
 
@@ -14,6 +14,14 @@ Packer.toBuffer(doc).then((buffer) => {
 });
 ```
 
+### Export as string
+
+```ts
+Packer.toString(doc).then((string) => {
+    console.log(string);
+});
+```
+
 ### Export as a `base64` string
 
 ```ts
@@ -32,3 +40,26 @@ Packer.toBlob(doc).then((blob) => {
     saveAs(blob, "example.docx");
 });
 ```
+
+### Export as a Stream
+
+```ts
+Packer.toStream(doc).then((stream) => {
+    // read from stream
+});
+```
+
+### Export using optional arguments
+
+The `Packer` methods support 2 optional arguments.
+
+The first is for controlling the indentation of the xml and should be a `boolean` or `keyof typeof PrettifyType`.
+
+The second is an array of subfile overrides (`{path: string, data: string}[]`). These overrides can be used to write additional subfiles to the result or even override default subfiles in the case that the default handling of these subfiles does not meet your needs.
+
+```ts
+const overrides = [{ path: "word/commentsExtended.xml", data: "string_data" }];
+Packer.toString(doc, true, overrides).then((string) => {
+    console.log(string);
+});
+```

package-lock.json

@@ -1,12 +1,12 @@
 {
     "name": "docx",
-    "version": "9.1.1",
+    "version": "9.2.0",
     "lockfileVersion": 2,
     "requires": true,
     "packages": {
         "": {
             "name": "docx",
-            "version": "9.1.1",
+            "version": "9.2.0",
             "license": "MIT",
             "dependencies": {
                 "@types/node": "^22.7.5",

package.json

@@ -1,6 +1,6 @@
 {
     "name": "docx",
-    "version": "9.1.1",
+    "version": "9.2.0",
     "description": "Easily generate .docx files with JS/TS with a nice declarative API. Works for Node and on the Browser.",
     "type": "module",
     "main": "dist/index.umd.cjs",

src/export/packer/next-compiler.spec.ts

@@ -112,6 +112,41 @@ describe("Compiler", () => {
             },
         );
 
+        it(
+            "should pack subfile overrides",
+            async () => {
+                const file = new File({
+                    sections: [],
+                    comments: {
+                        children: [],
+                    },
+                });
+                const subfileData1 = "comments";
+                const subfileData2 = "commentsExtended";
+                const overrides = [
+                    { path: "word/comments.xml", data: subfileData1 },
+                    { path: "word/commentsExtended.xml", data: subfileData2 },
+                ];
+                const zipFile = compiler.compile(file, "", overrides);
+                const fileNames = Object.keys(zipFile.files).map((f) => zipFile.files[f].name);
+
+                expect(fileNames).is.an.instanceof(Array);
+                expect(fileNames).has.length(20);
+
+                expect(fileNames).to.include("word/comments.xml");
+                expect(fileNames).to.include("word/commentsExtended.xml");
+
+                const commentsText = await zipFile.file("word/comments.xml")?.async("text");
+                const commentsExtendedText = await zipFile.file("word/commentsExtended.xml")?.async("text");
+
+                expect(commentsText).toBe(subfileData1);
+                expect(commentsExtendedText).toBe(subfileData2);
+            },
+            {
+                timeout: 99999999,
+            },
+        );
+
         it("should call the format method X times equalling X files to be formatted", () => {
             // This test is required because before, there was a case where Document was formatted twice, which was inefficient
             // This also caused issues such as running prepForXml multiple times as format() was ran multiple times.

src/export/packer/next-compiler.ts

@@ -9,7 +9,7 @@ import { ImageReplacer } from "./image-replacer";
 import { NumberingReplacer } from "./numbering-replacer";
 import { PrettifyType } from "./packer";
 
-type IXmlifyedFile = {
+export type IXmlifyedFile = {
     readonly data: string;
     readonly path: string;
 };
@@ -47,7 +47,11 @@ export class Compiler {
         this.numberingReplacer = new NumberingReplacer();
     }
 
-    public compile(file: File, prettifyXml?: (typeof PrettifyType)[keyof typeof PrettifyType]): JSZip {
+    public compile(
+        file: File,
+        prettifyXml?: (typeof PrettifyType)[keyof typeof PrettifyType],
+        overrides: readonly IXmlifyedFile[] = [],
+    ): JSZip {
         const zip = new JSZip();
         const xmlifiedFileMapping = this.xmlifyFile(file, prettifyXml);
         const map = new Map<string, IXmlifyedFile | readonly IXmlifyedFile[]>(Object.entries(xmlifiedFileMapping));
@@ -62,6 +66,10 @@ export class Compiler {
             }
         }
 
+        for (const subFile of overrides) {
+            zip.file(subFile.path, subFile.data);
+        }
+
         for (const data of file.Media.Array) {
             if (data.type !== "svg") {
                 zip.file(`word/media/${data.fileName}`, data.data);

src/export/packer/packer.spec.ts

@@ -46,7 +46,7 @@ describe("Packer", () => {
 
             await Packer.toString(file, true);
 
-            expect(spy).toBeCalledWith(expect.anything(), PrettifyType.WITH_2_BLANKS);
+            expect(spy).toBeCalledWith(expect.anything(), PrettifyType.WITH_2_BLANKS, expect.anything());
         });
 
         it("should use a prettify value", async () => {
@@ -55,7 +55,7 @@ describe("Packer", () => {
 
             await Packer.toString(file, PrettifyType.WITH_4_BLANKS);
 
-            expect(spy).toBeCalledWith(expect.anything(), PrettifyType.WITH_4_BLANKS);
+            expect(spy).toBeCalledWith(expect.anything(), PrettifyType.WITH_4_BLANKS, expect.anything());
         });
 
         it("should use an undefined prettify value", async () => {
@@ -64,7 +64,32 @@ describe("Packer", () => {
 
             await Packer.toString(file, false);
 
-            expect(spy).toBeCalledWith(expect.anything(), undefined);
+            expect(spy).toBeCalledWith(expect.anything(), undefined, expect.anything());
+        });
+    });
+
+    describe("overrides", () => {
+        afterEach(() => {
+            vi.restoreAllMocks();
+        });
+
+        it("should use an overrides value", async () => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const spy = vi.spyOn((Packer as any).compiler, "compile");
+            const overrides = [{ path: "word/comments.xml", data: "comments" }];
+
+            await Packer.toString(file, true, overrides);
+
+            expect(spy).toBeCalledWith(expect.anything(), expect.anything(), overrides);
+        });
+
+        it("should use a default overrides value", async () => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const spy = vi.spyOn((Packer as any).compiler, "compile");
+
+            await Packer.toString(file);
+
+            expect(spy).toBeCalledWith(expect.anything(), undefined, []);
         });
     });
 
@@ -162,6 +187,33 @@ describe("Packer", () => {
         });
     });
 
+    describe("#toArrayBuffer()", () => {
+        it("should create a standard docx file", async () => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            vi.spyOn((Packer as any).compiler, "compile").mockReturnValue({
+                generateAsync: () => vi.fn(),
+            });
+            const str = await Packer.toArrayBuffer(file);
+
+            assert.isDefined(str);
+        });
+
+        it("should handle exception if it throws any", () => {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            vi.spyOn((Packer as any).compiler, "compile").mockImplementation(() => {
+                throw new Error();
+            });
+
+            return Packer.toArrayBuffer(file).catch((error) => {
+                assert.isDefined(error);
+            });
+        });
+
+        afterEach(() => {
+            vi.resetAllMocks();
+        });
+    });
+
     describe("#toStream()", () => {
         it("should create a standard docx file", async () => {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any

src/export/packer/packer.ts

@@ -1,8 +1,9 @@
 import { Stream } from "stream";
 
 import { File } from "@file/file";
+import { OutputByType, OutputType } from "@util/output-type";
 
-import { Compiler } from "./next-compiler";
+import { Compiler, IXmlifyedFile } from "./next-compiler";
 
 /**
  * Use blanks to prettify
@@ -21,53 +22,68 @@ const convertPrettifyType = (
     prettify === true ? PrettifyType.WITH_2_BLANKS : prettify === false ? undefined : prettify;
 
 export class Packer {
-    public static async toString(file: File, prettify?: boolean | (typeof PrettifyType)[keyof typeof PrettifyType]): Promise<string> {
-        const zip = this.compiler.compile(file, convertPrettifyType(prettify));
-        const zipData = await zip.generateAsync({
-            type: "string",
+    // eslint-disable-next-line require-await
+    public static async pack<T extends OutputType>(
+        file: File,
+        type: T,
+        prettify?: boolean | (typeof PrettifyType)[keyof typeof PrettifyType],
+        overrides: readonly IXmlifyedFile[] = [],
+    ): Promise<OutputByType[T]> {
+        const zip = this.compiler.compile(file, convertPrettifyType(prettify), overrides);
+        return zip.generateAsync({
+            type,
             mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
             compression: "DEFLATE",
         });
-
-        return zipData;
     }
 
-    public static async toBuffer(file: File, prettify?: boolean | (typeof PrettifyType)[keyof typeof PrettifyType]): Promise<Buffer> {
-        const zip = this.compiler.compile(file, convertPrettifyType(prettify));
-        const zipData = await zip.generateAsync({
-            type: "nodebuffer",
-            mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-            compression: "DEFLATE",
-        });
-
-        return zipData;
+    public static toString(
+        file: File,
+        prettify?: boolean | (typeof PrettifyType)[keyof typeof PrettifyType],
+        overrides: readonly IXmlifyedFile[] = [],
+    ): Promise<string> {
+        return Packer.pack(file, "string", prettify, overrides);
     }
 
-    public static async toBase64String(file: File, prettify?: boolean | (typeof PrettifyType)[keyof typeof PrettifyType]): Promise<string> {
-        const zip = this.compiler.compile(file, convertPrettifyType(prettify));
-        const zipData = await zip.generateAsync({
-            type: "base64",
-            mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-            compression: "DEFLATE",
-        });
-
-        return zipData;
+    public static toBuffer(
+        file: File,
+        prettify?: boolean | (typeof PrettifyType)[keyof typeof PrettifyType],
+        overrides: readonly IXmlifyedFile[] = [],
+    ): Promise<Buffer> {
+        return Packer.pack(file, "nodebuffer", prettify, overrides);
     }
 
-    public static async toBlob(file: File, prettify?: boolean | (typeof PrettifyType)[keyof typeof PrettifyType]): Promise<Blob> {
-        const zip = this.compiler.compile(file, convertPrettifyType(prettify));
-        const zipData = await zip.generateAsync({
-            type: "blob",
-            mimeType: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-            compression: "DEFLATE",
-        });
-
-        return zipData;
+    public static toBase64String(
+        file: File,
+        prettify?: boolean | (typeof PrettifyType)[keyof typeof PrettifyType],
+        overrides: readonly IXmlifyedFile[] = [],
+    ): Promise<string> {
+        return Packer.pack(file, "base64", prettify, overrides);
     }
 
-    public static toStream(file: File, prettify?: boolean | (typeof PrettifyType)[keyof typeof PrettifyType]): Stream {
+    public static toBlob(
+        file: File,
+        prettify?: boolean | (typeof PrettifyType)[keyof typeof PrettifyType],
+        overrides: readonly IXmlifyedFile[] = [],
+    ): Promise<Blob> {
+        return Packer.pack(file, "blob", prettify, overrides);
+    }
+
+    public static toArrayBuffer(
+        file: File,
+        prettify?: boolean | (typeof PrettifyType)[keyof typeof PrettifyType],
+        overrides: readonly IXmlifyedFile[] = [],
+    ): Promise<ArrayBuffer> {
+        return Packer.pack(file, "arraybuffer", prettify, overrides);
+    }
+
+    public static toStream(
+        file: File,
+        prettify?: boolean | (typeof PrettifyType)[keyof typeof PrettifyType],
+        overrides: readonly IXmlifyedFile[] = [],
+    ): Stream {
         const stream = new Stream();
-        const zip = this.compiler.compile(file, convertPrettifyType(prettify));
+        const zip = this.compiler.compile(file, convertPrettifyType(prettify), overrides);
 
         zip.generateAsync({
             type: "nodebuffer",

src/file/paragraph/properties.ts

@@ -38,6 +38,8 @@ export type ILevelParagraphStylePropertiesOptions = {
 };
 
 export type IParagraphStylePropertiesOptions = {
+    readonly border?: IBordersOptions;
+    readonly shading?: IShadingAttributesProperties;
     readonly numbering?:
         | {
               readonly reference: string;
@@ -49,7 +51,6 @@ export type IParagraphStylePropertiesOptions = {
 } & ILevelParagraphStylePropertiesOptions;
 
 export type IParagraphPropertiesOptions = {
-    readonly border?: IBordersOptions;
     readonly heading?: (typeof HeadingLevel)[keyof typeof HeadingLevel];
     readonly bidirectional?: boolean;
     readonly pageBreakBefore?: boolean;
@@ -58,7 +59,6 @@ export type IParagraphPropertiesOptions = {
     readonly bullet?: {
         readonly level: number;
     };
-    readonly shading?: IShadingAttributesProperties;
     readonly widowControl?: boolean;
     readonly frame?: IFrameOptions;
     readonly suppressLineNumbers?: boolean;

src/patcher/from-docx.ts

@@ -11,6 +11,7 @@ import { ConcreteHyperlink, ExternalHyperlink, ParagraphChild } from "@file/para
 import { TargetModeType } from "@file/relationships/relationship/relationship";
 import { IContext } from "@file/xml-components";
 import { uniqueId } from "@util/convenience-functions";
+import { OutputByType, OutputType } from "@util/output-type";
 
 import { appendContentType } from "./content-types-manager";
 import { appendRelationship, getNextRelationshipIndex } from "./relationship-manager";
@@ -47,21 +48,7 @@ type IHyperlinkRelationshipAddition = {
 
 export type IPatch = ParagraphPatch | FilePatch;
 
-// From JSZip
-type OutputByType = {
-    readonly base64: string;
-    // eslint-disable-next-line id-denylist
-    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;
-};
-
-export type PatchDocumentOutputType = keyof OutputByType;
+export type PatchDocumentOutputType = OutputType;
 
 export type PatchDocumentOptions<T extends PatchDocumentOutputType = PatchDocumentOutputType> = {
     readonly outputType: T;

src/util/output-type.ts

@@ -0,0 +1,18 @@
+/* v8 ignore start */
+// Simply type definitions. Can ignore testing and coverage
+// From JSZip
+export type OutputByType = {
+    readonly base64: string;
+    // eslint-disable-next-line id-denylist
+    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;
+};
+
+export type OutputType = keyof OutputByType;
+/* v8 ignore stop */