chromiumly 2.4.0 → 2.5.1

package/src/libre-office/utils/tests/libre-office.utils.test.ts

@@ -1,86 +1,118 @@
 // eslint-disable-next-line @typescript-eslint/no-unused-vars
-import { promises, createReadStream } from "fs";
-import { LibreOfficeUtils } from "../libre-office.utils";
+import {promises, createReadStream} from "fs";
+import {LibreOfficeUtils} from "../libre-office.utils";
 
 import FormData from "form-data";
+import FileType from "file-type";
 
 describe("LibreOfficeUtils", () => {
-  const mockPromisesAccess = jest.spyOn(promises, "access");
-  const mockFormDataAppend = jest.spyOn(FormData.prototype, "append");
-  const data = new FormData();
+    const mockPromisesAccess = jest.spyOn(promises, "access");
+    const mockFormDataAppend = jest.spyOn(FormData.prototype, "append");
+    const mockFromBuffer = jest.spyOn(FileType, "fromBuffer");
 
-  beforeEach(() => {
-    (createReadStream as jest.Mock) = jest
-      .fn()
-      .mockImplementation((file) => file);
-  });
+    const data = new FormData();
 
-  afterEach(() => {
-    jest.resetAllMocks();
-  });
-
-  describe("injectFiles", () => {
-    describe("when files exist", () => {
-      it("should append each file to data", async () => {
-        mockPromisesAccess.mockResolvedValue();
-        await LibreOfficeUtils.injectFiles(
-          ["path/to/file.docx", "path/to/file.bib"],
-          data
-        );
-        expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
-      });
+    beforeEach(() => {
+        (createReadStream as jest.Mock) = jest
+            .fn()
+            .mockImplementation((file) => file);
     });
 
-    describe("when one of the files has unsupported format", () => {
-      it("should throw an error", async () => {
-        mockPromisesAccess.mockResolvedValue();
-        await expect(() =>
-          LibreOfficeUtils.injectFiles(
-            ["path/to/file.rar", "path/to/file.pdf"],
-            data
-          )
-        ).rejects.toThrow(".rar is not supported");
-      });
+    afterEach(() => {
+        jest.resetAllMocks();
     });
 
-    describe("when one of the files does not exist", () => {
-      it("should throw an error", async () => {
-        const errorMessage =
-          "ENOENT: no such file or directory, access 'path/to/index.html'";
-        mockPromisesAccess.mockRejectedValue(new Error(errorMessage));
-        await expect(() =>
-          LibreOfficeUtils.injectFiles(
-            ["path/to/file.pdf", "path/to/another-file.pdf"],
-            data
-          )
-        ).rejects.toThrow(errorMessage);
-      });
-    });
-  });
+    describe("addFiles", () => {
+        describe("when files exist", () => {
+            describe("when files parameter contains paths", () => {
+                it("should append each file to data", async () => {
+                    mockPromisesAccess.mockResolvedValue();
+                    await LibreOfficeUtils.addFiles(
+                        ["path/to/file.docx", "path/to/file.bib"],
+                        data
+                    );
+                    expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+                });
+            })
+            describe("when files parameter contains a buffer", () => {
+                it("should append each file to data", async () => {
+                    mockPromisesAccess.mockResolvedValueOnce();
+                    mockFromBuffer.mockResolvedValueOnce({
+                        ext: "docx",
+                        mime: "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
+                    })
+                    await LibreOfficeUtils.addFiles(
+                        [Buffer.from("data"), "path/to/file.bib"],
+                        data
+                    );
+                    expect(mockFormDataAppend).toHaveBeenCalledTimes(2);
+                });
+            })
+        });
+
+        describe("when one of the files has undetermined format", () => {
+            it("should throw an error", async () => {
+                mockPromisesAccess.mockResolvedValueOnce();
+                mockFromBuffer.mockResolvedValueOnce(undefined
+                )
+
+                await expect(LibreOfficeUtils.addFiles(
+                    [Buffer.from("data"), "path/to/file.bib"],
+                    data
+                )).rejects.toThrow("File type could not be determined");
+            });
+        })
 
-  describe("injectPageProperties", () => {
-    describe("Page landscape", () => {
-      describe("when landscape parameter is set", () => {
-        it("should append landscape to data", () => {
-          LibreOfficeUtils.injectPageProperties(data, {
-            landscape: true,
-          });
-          expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
-          expect(data.append).toHaveBeenCalledWith("landscape", "true");
+        describe("when one of the files has unsupported format", () => {
+            it("should throw an error", async () => {
+                mockPromisesAccess.mockResolvedValueOnce();
+                await expect(() =>
+                    LibreOfficeUtils.addFiles(
+                        ["path/to/file.rar", "path/to/file.pdf"],
+                        data
+                    )
+                ).rejects.toThrow("rar is not supported");
+            });
+        });
+
+        describe("when one of the files does not exist", () => {
+            it("should throw an error", async () => {
+                const errorMessage =
+                    "ENOENT: no such file or directory, access 'path/to/index.html'";
+                mockPromisesAccess.mockRejectedValueOnce(new Error(errorMessage));
+                await expect(() =>
+                    LibreOfficeUtils.addFiles(
+                        ["path/to/file.pdf", "path/to/another-file.pdf"],
+                        data
+                    )
+                ).rejects.toThrow(errorMessage);
+            });
         });
-      });
     });
 
-    describe("Page ranges", () => {
-      describe("when nativePageRanges is valid", () => {
-        it("should append nativePageRanges to data", () => {
-          LibreOfficeUtils.injectPageProperties(data, {
-            nativePageRanges: { from: 1, to: 6 },
-          });
-          expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
-          expect(data.append).toHaveBeenCalledWith("nativePageRanges", "1-6");
+    describe("addPageProperties", () => {
+        describe("Page landscape", () => {
+            describe("when landscape parameter is set", () => {
+                it("should append landscape to data", () => {
+                    LibreOfficeUtils.addPageProperties(data, {
+                        landscape: true,
+                    });
+                    expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+                    expect(data.append).toHaveBeenCalledWith("landscape", "true");
+                });
+            });
+        });
+
+        describe("Page ranges", () => {
+            describe("when nativePageRanges is valid", () => {
+                it("should append nativePageRanges to data", () => {
+                    LibreOfficeUtils.addPageProperties(data, {
+                        nativePageRanges: {from: 1, to: 6},
+                    });
+                    expect(mockFormDataAppend).toHaveBeenCalledTimes(1);
+                    expect(data.append).toHaveBeenCalledWith("nativePageRanges", "1-6");
+                });
+            });
         });
-      });
     });
-  });
 });

package/src/main.config.ts

@@ -1,36 +1,82 @@
-import { Gotenberg } from "./gotenberg";
+import {Gotenberg} from "./gotenberg";
 
+/**
+ * Enum representing the available Chromium routes for conversion.
+ * @enum {string}
+ */
 export enum ChromiumRoute {
-  URL = "url",
-  HTML = "html",
-  MARKDOWN = "markdown",
+    URL = "url",
+    HTML = "html",
+    MARKDOWN = "markdown",
 }
 
+/**
+ * Enum representing the available routes for the PDF engine.
+ * @enum {string}
+ */
 enum PdfEngineRoute {
-  MERGE = "merge",
+    MERGE = "merge",
 }
 
+/**
+ * Enum representing the available routes for LibreOffice.
+ * @enum {string}
+ */
 enum LibreOfficeRoute {
-  CONVERT = "convert",
+    CONVERT = "convert",
 }
+
+/**
+ * Class providing constants and routes for interacting with the Gotenberg service and related engines.
+ */
 export class Chromiumly {
-  public static readonly GOTENBERG_ENDPOINT = Gotenberg.endpoint;
+    /**
+     * The Gotenberg service endpoint.
+     * @type {string}
+     */
+    public static readonly GOTENBERG_ENDPOINT = Gotenberg.endpoint;
 
-  public static readonly CHROMIUM_PATH = "forms/chromium/convert";
-  public static readonly PDF_ENGINES_PATH = "forms/pdfengines";
-  public static readonly LIBRE_OFFICE_PATH = "forms/libreoffice";
+    /**
+     * The path for Chromium-related conversions.
+     * @type {string}
+     */
+    public static readonly CHROMIUM_PATH = "forms/chromium/convert";
 
-  public static readonly CHROMIUM_ROUTES = {
-    url: ChromiumRoute.URL,
-    html: ChromiumRoute.HTML,
-    markdown: ChromiumRoute.MARKDOWN,
-  };
+    /**
+     * The path for PDF engine-related operations.
+     * @type {string}
+     */
+    public static readonly PDF_ENGINES_PATH = "forms/pdfengines";
 
-  public static readonly PDF_ENGINE_ROUTES = {
-    merge: PdfEngineRoute.MERGE,
-  };
+    /**
+     * The path for LibreOffice-related conversions.
+     * @type {string}
+     */
+    public static readonly LIBRE_OFFICE_PATH = "forms/libreoffice";
 
-  public static readonly LIBRE_OFFICE_ROUTES = {
-    convert: LibreOfficeRoute.CONVERT,
-  };
-}
+    /**
+     * Routes for Chromium conversions.
+     * @type {Object}
+     */
+    public static readonly CHROMIUM_ROUTES = {
+        url: ChromiumRoute.URL,
+        html: ChromiumRoute.HTML,
+        markdown: ChromiumRoute.MARKDOWN,
+    };
+
+    /**
+     * Routes for PDF engine operations.
+     * @type {Object}
+     */
+    public static readonly PDF_ENGINE_ROUTES = {
+        merge: PdfEngineRoute.MERGE,
+    };
+
+    /**
+     * Routes for LibreOffice conversions.
+     * @type {Object}
+     */
+    public static readonly LIBRE_OFFICE_ROUTES = {
+        convert: LibreOfficeRoute.CONVERT,
+    };
+}

package/src/main.ts

@@ -1,3 +1,3 @@
-export { PdfFormat } from "./common/constants";
-export { HtmlConverter, MarkdownConverter, UrlConverter } from "./chromium";
-export { PDFEngine } from "./pdf-engines";
+export {PdfFormat} from "./common/constants";
+export {HtmlConverter, MarkdownConverter, UrlConverter} from "./chromium";
+export {PDFEngine} from "./pdf-engines";

package/src/pdf-engines/index.ts

@@ -1 +1 @@
-export { PDFEngine } from "./pdf.engine";
+export {PDFEngine} from "./pdf.engine";

package/src/pdf-engines/pdf.engine.ts

@@ -1,65 +1,93 @@
-import { PathLike, promises } from "fs";
+import {promises} from "fs";
 import path from "path";
 
 import FormData from "form-data";
 
-import { Chromiumly } from "../main.config";
-import { GotenbergUtils, PdfFormat } from "../common";
-import { LibreOfficeUtils, PageProperties } from "../libre-office";
-import { PDFEngineUtils } from "./utils/engine.utils";
+import {Chromiumly} from "../main.config";
+import {GotenbergUtils, PathLikeOrReadStream, PdfFormat} from "../common";
+import {LibreOfficeUtils, PageProperties} from "../libre-office";
+import {PDFEngineUtils} from "./utils/engine.utils";
 
+/**
+ * Class representing a PDF engine for various operations such as merging and conversion.
+ */
 export class PDFEngine {
-  public static async merge({ files }: { files: PathLike[] }): Promise<Buffer> {
-    const data = new FormData();
-    await PDFEngineUtils.injectFiles(files, data);
-    const endpoint = `${Chromiumly.GOTENBERG_ENDPOINT}/${Chromiumly.PDF_ENGINES_PATH}/${Chromiumly.PDF_ENGINE_ROUTES.merge}`;
-    return GotenbergUtils.fetch(endpoint, data);
-  }
+    /**
+     * Merges multiple PDF files into a single PDF document.
+     *
+     * @param {Object} options - Options for the merge operation.
+     * @param {PathLikeOrReadStream[]} options.files - An array of PathLikes or ReadStreams to the PDF files to be merged.
+     * @returns {Promise<Buffer>} A Promise resolving to the merged PDF content as a Buffer.
+     */
+    public static async merge({files}: { files: PathLikeOrReadStream[] }): Promise<Buffer> {
+        const data = new FormData();
+        await PDFEngineUtils.addFiles(files, data);
+        const endpoint = `${Chromiumly.GOTENBERG_ENDPOINT}/${Chromiumly.PDF_ENGINES_PATH}/${Chromiumly.PDF_ENGINE_ROUTES.merge}`;
+        return GotenbergUtils.fetch(endpoint, data);
+    }
 
-  public static async convert({
-    files,
-    properties,
-    pdfFormat,
-    pdfUA,
-    merge,
-  }: {
-    files: PathLike[];
-    properties?: PageProperties;
-    pdfFormat?: PdfFormat;
-    pdfUA?: boolean;
-    merge?: boolean;
-  }): Promise<Buffer> {
-    const data = new FormData();
+    /**
+     * Converts various document formats to PDF.
+     *
+     * @param {Object} options - Options for the conversion operation.
+     * @param {PathLikeOrReadStream[]} options.files - An array of PathLikes or ReadStreams to the files to be converted to PDF.
+     * @param {PageProperties} [options.properties] - Page properties for the conversion.
+     * @param {PdfFormat} [options.pdfFormat] - PDF format options.
+     * @param {boolean} [options.pdfUA] - Indicates whether to generate PDF/UA compliant output.
+     * @param {boolean} [options.merge] - Indicates whether to merge the resulting PDFs.
+     * @returns {Promise<Buffer>} A Promise resolving to the converted PDF content as a Buffer.
+     */
+    public static async convert({
+                                    files,
+                                    properties,
+                                    pdfFormat,
+                                    pdfUA,
+                                    merge,
+                                }: {
+        files: PathLikeOrReadStream[];
+        properties?: PageProperties;
+        pdfFormat?: PdfFormat;
+        pdfUA?: boolean;
+        merge?: boolean;
+    }): Promise<Buffer> {
+        const data = new FormData();
 
-    if (pdfFormat) {
-      data.append("pdfa", pdfFormat);
-    }
+        if (pdfFormat) {
+            data.append("pdfa", pdfFormat);
+        }
 
-    if (pdfUA) {
-      data.append("pdfUA", String(pdfUA));
-    }
+        if (pdfUA) {
+            data.append("pdfUA", String(pdfUA));
+        }
 
-    if (merge) {
-      data.append("merge", String(merge));
-    }
+        if (merge) {
+            data.append("merge", String(merge));
+        }
 
-    if (properties) {
-      LibreOfficeUtils.injectPageProperties(data, properties);
-    }
+        if (properties) {
+            LibreOfficeUtils.addPageProperties(data, properties);
+        }
 
-    await LibreOfficeUtils.injectFiles(files, data);
+        await LibreOfficeUtils.addFiles(files, data);
 
-    const endpoint = `${Chromiumly.GOTENBERG_ENDPOINT}/${Chromiumly.LIBRE_OFFICE_PATH}/${Chromiumly.LIBRE_OFFICE_ROUTES.convert}`;
+        const endpoint = `${Chromiumly.GOTENBERG_ENDPOINT}/${Chromiumly.LIBRE_OFFICE_PATH}/${Chromiumly.LIBRE_OFFICE_ROUTES.convert}`;
 
-    return GotenbergUtils.fetch(endpoint, data);
-  }
+        return GotenbergUtils.fetch(endpoint, data);
+    }
 
-  public static async generate(
-    filename: string,
-    buffer: Buffer
-  ): Promise<void> {
-    const __generated__ = path.resolve(process.cwd(), "__generated__");
-    await promises.mkdir(path.resolve(__generated__), { recursive: true });
-    await promises.writeFile(path.resolve(__generated__, filename), buffer);
-  }
+    /**
+     * Generates a PDF file from a buffer and saves it to the "__generated__" directory.
+     *
+     * @param {string} filename - The filename for the generated PDF.
+     * @param {Buffer} buffer - The PDF content as a Buffer.
+     * @returns {Promise<void>} A Promise that resolves once the file is generated and saved.
+     */
+    public static async generate(
+        filename: string,
+        buffer: Buffer
+    ): Promise<void> {
+        const __generated__ = path.resolve(process.cwd(), "__generated__");
+        await promises.mkdir(path.resolve(__generated__), {recursive: true});
+        await promises.writeFile(path.resolve(__generated__, filename), buffer);
+    }
 }