chromiumly 2.4.0 → 2.5.1

package/src/chromium/converters/url.converter.ts

@@ -1,69 +1,93 @@
-import { PathLike } from "fs";
-
-import { URL } from "url";
-
+import {URL} from "url";
 import FormData from "form-data";
-
-import { GotenbergUtils, PdfFormat } from "../../common";
+import {GotenbergUtils, PdfFormat, PathLikeOrReadStream} from "../../common";
 import {
-  EmulatedMediaType,
-  PageProperties,
+    EmulatedMediaType,
+    PageProperties,
 } from "../interfaces/converter.types";
-import { ConverterUtils } from "../utils/converter.utils";
-import { Converter } from "./converter";
-import { ChromiumRoute } from "../../main.config";
+import {ConverterUtils} from "../utils/converter.utils";
+import {Converter} from "./converter";
+import {ChromiumRoute} from "../../main.config";
 
+/**
+ * Class representing a URL converter that extends the base Converter class.
+ * This class is used to convert content from a URL to PDF using Gotenberg service.
+ *
+ * @extends Converter
+ */
 export class UrlConverter extends Converter {
-  constructor() {
-    super(ChromiumRoute.URL);
-  }
+    /**
+     * Creates an instance of UrlConverter.
+     * Initializes the converter with the URL conversion route.
+     */
+    constructor() {
+        super(ChromiumRoute.URL);
+    }
 
-  async convert({
-    url,
-    header,
-    footer,
-    properties,
-    pdfFormat,
-    pdfUA,
-    emulatedMediaType,
-    waitDelay,
-    waitForExpression,
-    userAgent,
-    extraHttpHeaders,
-    failOnConsoleExceptions,
-  }: {
-    url: string;
-    header?: PathLike;
-    footer?: PathLike;
-    properties?: PageProperties;
-    pdfFormat?: PdfFormat;
-    pdfUA?: boolean;
-    emulatedMediaType?: EmulatedMediaType;
-    waitDelay?: string;
-    waitForExpression?: string;
-    userAgent?: string;
-    extraHttpHeaders?: Record<string, string>;
-    failOnConsoleExceptions?: boolean;
-  }): Promise<Buffer> {
-    const _url = new URL(url);
-    const data = new FormData();
+    /**
+     * Converts content from a URL to PDF.
+     *
+     * @param {Object} options - Conversion options.
+     * @param {string} options.url - The URL of the content to be converted to PDF.
+     * @param {PathLikeOrReadStream} [options.header] - PathLike or ReadStream of the header HTML content.
+     * @param {PathLikeOrReadStream} [options.footer] - PathLike or ReadStream of the footer HTML content.
+     * @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 {EmulatedMediaType} [options.emulatedMediaType] - Emulated media type for the conversion.
+     * @param {string} [options.waitDelay] - Delay before the conversion process starts.
+     * @param {string} [options.waitForExpression] - JavaScript expression to wait for before completing the conversion.
+     * @param {string} [options.userAgent] - User agent string to use during the conversion.
+     * @param {Record<string, string>} [options.extraHttpHeaders] - Additional HTTP headers for the conversion.
+     * @param {boolean} [options.failOnConsoleExceptions] - Whether to fail on console exceptions during conversion.
+     * @returns {Promise<Buffer>} A Promise resolving to the converted PDF content as a Buffer.
+     */
+    async convert({
+                      url,
+                      header,
+                      footer,
+                      properties,
+                      pdfFormat,
+                      pdfUA,
+                      emulatedMediaType,
+                      waitDelay,
+                      waitForExpression,
+                      userAgent,
+                      extraHttpHeaders,
+                      failOnConsoleExceptions,
+                  }: {
+        url: string;
+        header?: PathLikeOrReadStream;
+        footer?: PathLikeOrReadStream;
+        properties?: PageProperties;
+        pdfFormat?: PdfFormat;
+        pdfUA?: boolean;
+        emulatedMediaType?: EmulatedMediaType;
+        waitDelay?: string;
+        waitForExpression?: string;
+        userAgent?: string;
+        extraHttpHeaders?: Record<string, string>;
+        failOnConsoleExceptions?: boolean;
+    }): Promise<Buffer> {
+        const _url = new URL(url);
+        const data = new FormData();
 
-    data.append("url", _url.href);
+        data.append("url", _url.href);
 
-    ConverterUtils.customize(data, {
-      header,
-      footer,
-      properties,
-      pdfFormat,
-      pdfUA,
-      emulatedMediaType,
-      waitDelay,
-      waitForExpression,
-      userAgent,
-      extraHttpHeaders,
-      failOnConsoleExceptions,
-    });
+        await ConverterUtils.customize(data, {
+            header,
+            footer,
+            properties,
+            pdfFormat,
+            pdfUA,
+            emulatedMediaType,
+            waitDelay,
+            waitForExpression,
+            userAgent,
+            extraHttpHeaders,
+            failOnConsoleExceptions,
+        });
 
-    return GotenbergUtils.fetch(this.endpoint, data);
-  }
-}
+        return GotenbergUtils.fetch(this.endpoint, data);
+    }
+}

package/src/chromium/index.ts

@@ -1,3 +1,3 @@
-export { HtmlConverter } from "./converters/html.converter";
-export { MarkdownConverter } from "./converters/markdown.converter";
-export { UrlConverter } from "./converters/url.converter";
+export {HtmlConverter} from "./converters/html.converter";
+export {MarkdownConverter} from "./converters/markdown.converter";
+export {UrlConverter} from "./converters/url.converter";

package/src/chromium/interfaces/converter.types.ts

@@ -1,41 +1,41 @@
-import { PathLike } from "fs";
-import { PdfFormat } from "../../common";
+import {PathLikeOrReadStream, PdfFormat} from "../../common";
 
 type PageSize = {
-  width: number; // Paper width, in inches (default 8.5)
-  height: number; //Paper height, in inches (default 11)
+    width: number; // Paper width, in inches (default 8.5)
+    height: number; //Paper height, in inches (default 11)
 };
 
 type PageMargins = {
-  top: number; // Top margin, in inches (default 0.39)
-  bottom: number; // Bottom margin, in inches (default 0.39)
-  left: number; // Left margin, in inches (default 0.39)
-  right: number; // Right margin, in inches (default 0.39)
+    top: number; // Top margin, in inches (default 0.39)
+    bottom: number; // Bottom margin, in inches (default 0.39)
+    left: number; // Left margin, in inches (default 0.39)
+    right: number; // Right margin, in inches (default 0.39)
 };
 
 export type PageProperties = {
-  size?: PageSize;
-  margins?: PageMargins;
-  preferCssPageSize?: boolean; // Define whether to prefer page size as defined by CSS (default false)
-  printBackground?: boolean; // Print the background graphics (default false)
-  omitBackground?: boolean; // Hide the default white background and allow generating PDFs with transparency (default false)
-  landscape?: boolean; // Set the paper orientation to landscape (default false)
-  scale?: number; // The scale of the page rendering (default 1.0)
-  nativePageRanges?: { from: number; to: number }; // Page ranges to print
+    size?: PageSize;
+    margins?: PageMargins;
+    preferCssPageSize?: boolean; // Define whether to prefer page size as defined by CSS (default false)
+    printBackground?: boolean; // Print the background graphics (default false)
+    omitBackground?: boolean; // Hide the default white background and allow generating PDFs with transparency (default false)
+    landscape?: boolean; // Set the paper orientation to landscape (default false)
+    scale?: number; // The scale of the page rendering (default 1.0)
+    nativePageRanges?: { from: number; to: number }; // Page ranges to print
 };
 
 export type EmulatedMediaType = "screen" | "print";
 
+
 export type ConversionOptions = {
-  header?: PathLike | Buffer;
-  footer?: PathLike | Buffer;
-  properties?: PageProperties;
-  pdfFormat?: PdfFormat;
-  pdfUA?: boolean; // Enable PDF for Universal Access for optimal accessibility (default false)
-  emulatedMediaType?: EmulatedMediaType;
-  waitDelay?: string; // Duration (e.g, '5s') to wait when loading an HTML document before converting it into PDF
-  waitForExpression?: string; // JavaScript expression to wait before converting an HTML document into PDF until it returns true.
-  userAgent?: string;
-  extraHttpHeaders?: Record<string, string>;
-  failOnConsoleExceptions?: boolean; // Return a 409 Conflict response if there are exceptions in the Chromium console (default false)
+    header?: PathLikeOrReadStream;
+    footer?: PathLikeOrReadStream;
+    properties?: PageProperties;
+    pdfFormat?: PdfFormat;
+    pdfUA?: boolean; // Enable PDF for Universal Access for optimal accessibility (default false)
+    emulatedMediaType?: EmulatedMediaType;
+    waitDelay?: string; // Duration (e.g, '5s') to wait when loading an HTML document before converting it into PDF
+    waitForExpression?: string; // JavaScript's expression to wait before converting an HTML document into PDF until it returns true.
+    userAgent?: string;
+    extraHttpHeaders?: Record<string, string>;
+    failOnConsoleExceptions?: boolean; // Return a 409 Conflict response if there are exceptions in the Chromium console (default false)
 };

package/src/chromium/utils/converter.utils.ts

@@ -1,147 +1,173 @@
-import { constants, createReadStream, promises } from "fs";
+import {constants, createReadStream, promises} from "fs";
 import FormData from "form-data";
 
-import { GotenbergUtils } from "../../common/gotenberg.utils";
 import {
-  ConversionOptions,
-  PageProperties,
+    ConversionOptions,
+    PageProperties,
 } from "../interfaces/converter.types";
+import {GotenbergUtils, PathLikeOrReadStream} from "../../common";
+import {ReadStream} from "fs";
 
+/**
+ * Utility class for handling common tasks related to conversion.
+ */
 export class ConverterUtils {
-  public static injectPageProperties(
-    data: FormData,
-    pageProperties: PageProperties
-  ): void {
-    if (pageProperties.size) {
-      GotenbergUtils.assert(
-        pageProperties.size.width >= 1.0 && pageProperties.size.height >= 1.5,
-        "size is smaller than the minimum printing requirements (i.e. 1.0 x 1.5 in)"
-      );
-
-      data.append("paperWidth", pageProperties.size.width);
-      data.append("paperHeight", pageProperties.size.height);
+    /**
+     * Adds page properties to the FormData object based on the provided PageProperties.
+     *
+     * @param {FormData} data - The FormData object to which page properties will be added.
+     * @param {PageProperties} pageProperties - The page properties to be added to the FormData.
+     */
+    public static addPageProperties(
+        data: FormData,
+        pageProperties: PageProperties
+    ): void {
+        if (pageProperties.size) {
+            GotenbergUtils.assert(
+                pageProperties.size.width >= 1.0 && pageProperties.size.height >= 1.5,
+                "size is smaller than the minimum printing requirements (i.e. 1.0 x 1.5 in)"
+            );
+
+            data.append("paperWidth", pageProperties.size.width);
+            data.append("paperHeight", pageProperties.size.height);
+        }
+
+        if (pageProperties.margins) {
+            GotenbergUtils.assert(
+                pageProperties.margins.top >= 0 &&
+                pageProperties.margins.bottom >= 0 &&
+                pageProperties.margins.left >= 0 &&
+                pageProperties.margins.left >= 0,
+                "negative margins are not allowed"
+            );
+
+            data.append("marginTop", pageProperties.margins.top);
+            data.append("marginBottom", pageProperties.margins.bottom);
+            data.append("marginLeft", pageProperties.margins.left);
+            data.append("marginRight", pageProperties.margins.right);
+        }
+
+        if (pageProperties.preferCssPageSize) {
+            data.append(
+                "preferCssPageSize",
+                String(pageProperties.preferCssPageSize)
+            );
+        }
+
+        if (pageProperties.printBackground) {
+            data.append("printBackground", String(pageProperties.printBackground));
+        }
+
+        if (pageProperties.omitBackground) {
+            data.append("omitBackground", String(pageProperties.omitBackground));
+        }
+
+        if (pageProperties.landscape) {
+            data.append("landscape", String(pageProperties.landscape));
+        }
+
+        if (pageProperties.scale) {
+            GotenbergUtils.assert(
+                pageProperties.scale >= 0.1 && pageProperties.scale <= 2.0,
+                "scale is outside of [0.1 - 2] range"
+            );
+
+            data.append("scale", pageProperties.scale);
+        }
+
+        if (pageProperties.nativePageRanges) {
+            GotenbergUtils.assert(
+                pageProperties.nativePageRanges.from > 0 &&
+                pageProperties.nativePageRanges.to > 0 &&
+                pageProperties.nativePageRanges.to >=
+                pageProperties.nativePageRanges.from,
+                "page ranges syntax error"
+            );
+
+            data.append(
+                "nativePageRanges",
+                `${pageProperties.nativePageRanges.from}-${pageProperties.nativePageRanges.to}`
+            );
+        }
+    }
+
+    /**
+     * Adds a file to the FormData object.
+     *
+     * @param {FormData} data - The FormData object to which the file will be added.
+     * @param {PathLikeOrReadStream} file - The file to be added (either a PathLike or a ReadStream).
+     * @param {string} name - The name to be used for the file in the FormData.
+     * @returns {Promise<void>} A Promise that resolves once the file has been added.
+     */
+    public static async addFile(data: FormData, file: PathLikeOrReadStream, name: string) {
+        if (Buffer.isBuffer(file)) {
+            data.append("files", file, name);
+        } else if (file instanceof ReadStream) {
+            data.append("files", file, name);
+        } else {
+            await promises.access(file, constants.R_OK);
+            data.append("files", createReadStream(file), name);
+        }
+    }
+
+    /**
+     * Customizes the FormData object based on the provided conversion options.
+     *
+     * @param {FormData} data - The FormData object to be customized.
+     * @param {ConversionOptions} options - The conversion options to apply to the FormData.
+     * @returns {Promise<void>} A Promise that resolves once the customization is complete.
+     */
+    public static async customize(
+        data: FormData,
+        options: ConversionOptions
+    ): Promise<void> {
+        if (options.pdfFormat) {
+            data.append("pdfa", options.pdfFormat);
+        }
+
+        if (options.pdfUA) {
+            data.append("pdfua", String(options.pdfUA));
+        }
+
+        if (options.header) {
+            const {header} = options;
+            await ConverterUtils.addFile(data, header, "header.html")
+        }
+
+        if (options.footer) {
+            const {footer} = options;
+            await ConverterUtils.addFile(data, footer, "footer.html")
+        }
+
+        if (options.emulatedMediaType) {
+            data.append("emulatedMediaType", options.emulatedMediaType);
+        }
+
+        if (options.properties) {
+            ConverterUtils.addPageProperties(data, options.properties);
+        }
+
+        if (options.waitDelay) {
+            data.append("waitDelay", options.waitDelay);
+        }
+
+        if (options.waitForExpression) {
+            data.append("waitForExpression", options.waitForExpression);
+        }
+
+        if (options.userAgent) {
+            data.append("userAgent", options.userAgent);
+        }
+
+        if (options.extraHttpHeaders) {
+            data.append("extraHttpHeaders", JSON.stringify(options.extraHttpHeaders));
+        }
+
+        if (options.failOnConsoleExceptions) {
+            data.append(
+                "failOnConsoleExceptions",
+                String(options.failOnConsoleExceptions)
+            );
+        }
     }
-
-    if (pageProperties.margins) {
-      GotenbergUtils.assert(
-        pageProperties.margins.top >= 0 &&
-          pageProperties.margins.bottom >= 0 &&
-          pageProperties.margins.left >= 0 &&
-          pageProperties.margins.left >= 0,
-        "negative margins are not allowed"
-      );
-
-      data.append("marginTop", pageProperties.margins.top);
-      data.append("marginBottom", pageProperties.margins.bottom);
-      data.append("marginLeft", pageProperties.margins.left);
-      data.append("marginRight", pageProperties.margins.right);
-    }
-
-    if (pageProperties.preferCssPageSize) {
-      data.append(
-        "preferCssPageSize",
-        String(pageProperties.preferCssPageSize)
-      );
-    }
-
-    if (pageProperties.printBackground) {
-      data.append("printBackground", String(pageProperties.printBackground));
-    }
-
-    if (pageProperties.omitBackground) {
-      data.append("omitBackground", String(pageProperties.omitBackground));
-    }
-
-    if (pageProperties.landscape) {
-      data.append("landscape", String(pageProperties.landscape));
-    }
-
-    if (pageProperties.scale) {
-      GotenbergUtils.assert(
-        pageProperties.scale >= 0.1 && pageProperties.scale <= 2.0,
-        "scale is outside of [0.1 - 2] range"
-      );
-
-      data.append("scale", pageProperties.scale);
-    }
-
-    if (pageProperties.nativePageRanges) {
-      GotenbergUtils.assert(
-        pageProperties.nativePageRanges.from > 0 &&
-          pageProperties.nativePageRanges.to > 0 &&
-          pageProperties.nativePageRanges.to >=
-            pageProperties.nativePageRanges.from,
-        "page ranges syntax error"
-      );
-
-      data.append(
-        "nativePageRanges",
-        `${pageProperties.nativePageRanges.from}-${pageProperties.nativePageRanges.to}`
-      );
-    }
-  }
-
-  public static async customize(
-    data: FormData,
-    options: ConversionOptions
-  ): Promise<void> {
-    if (options.pdfFormat) {
-      data.append("pdfa", options.pdfFormat);
-    }
-
-    if (options.pdfUA) {
-      data.append("pdfua", String(options.pdfUA));
-    }
-
-    if (options.header) {
-      const { header } = options;
-      if (Buffer.isBuffer(header)) {
-        data.append("files", header, "header.html");
-      } else {
-        await promises.access(options.header, constants.R_OK);
-        data.append("files", createReadStream(options.header), "header.html");
-      }
-    }
-
-    if (options.footer) {
-      const { footer } = options;
-      if (Buffer.isBuffer(footer)) {
-        data.append("files", footer, "footer.html");
-      } else {
-        await promises.access(options.footer, constants.R_OK);
-        data.append("files", createReadStream(options.footer), "footer.html");
-      }
-    }
-
-    if (options.emulatedMediaType) {
-      data.append("emulatedMediaType", options.emulatedMediaType);
-    }
-
-    if (options.properties) {
-      ConverterUtils.injectPageProperties(data, options.properties);
-    }
-
-    if (options.waitDelay) {
-      data.append("waitDelay", options.waitDelay);
-    }
-
-    if (options.waitForExpression) {
-      data.append("waitForExpression", options.waitForExpression);
-    }
-
-    if (options.userAgent) {
-      data.append("userAgent", options.userAgent);
-    }
-
-    if (options.extraHttpHeaders) {
-      data.append("extraHttpHeaders", JSON.stringify(options.extraHttpHeaders));
-    }
-
-    if (options.failOnConsoleExceptions) {
-      data.append(
-        "failOnConsoleExceptions",
-        String(options.failOnConsoleExceptions)
-      );
-    }
-  }
 }