docs: add JSDoc comments

cherfia · Dec 10, 2023 · daa7783 · daa7783
1 parent 8e1ef9e
commit daa7783
Show file tree

Hide file tree

Showing 11 changed files with 259 additions and 13 deletions.
diff --git a/src/chromium/converters/converter.ts b/src/chromium/converters/converter.ts
@@ -1,8 +1,21 @@
 import {Chromiumly, ChromiumRoute} from "../../main.config";
 
+/**
+ * Abstract class representing a generic converter.
+ * Concrete converter classes should extend this class and implement specific conversion logic.
+ */
 export abstract class Converter {
+    /**
+     * The endpoint URL for the converter.
+     */
     readonly endpoint: string;
 
+    /**
+     * Creates an instance of the Converter class.
+     * Initializes the endpoint URL based on the provided ChromiumRoute.
+     *
+     * @param {ChromiumRoute} route - The ChromiumRoute enum value representing the conversion route.
+     */
     constructor(route: ChromiumRoute) {
         this.endpoint = `${Chromiumly.GOTENBERG_ENDPOINT}/${Chromiumly.CHROMIUM_PATH}/${Chromiumly.CHROMIUM_ROUTES[route]}`;
     }

diff --git a/src/chromium/converters/html.converter.ts b/src/chromium/converters/html.converter.ts
@@ -1,4 +1,3 @@
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
 import FormData from "form-data";
 
 import {GotenbergUtils, PathLikeOrReadStream, PdfFormat} from "../../common";
@@ -10,11 +9,39 @@ import {ConverterUtils} from "../utils/converter.utils";
 import {Converter} from "./converter";
 import {ChromiumRoute} from "../../main.config";
 
+/**
+ * Class representing an HTML converter that extends the base Converter class.
+ * This class is used to convert HTML content to PDF using Gotenberg service.
+ *
+ * @extends Converter
+ */
 export class HtmlConverter extends Converter {
+    /**
+     * Creates an instance of HtmlConverter.
+     * Initializes the converter with the HTML conversion route.
+     */
     constructor() {
         super(ChromiumRoute.HTML);
     }
 
+    /**
+     * Converts HTML content to PDF.
+     *
+     * @param {Object} options - Conversion options.
+     * @param {PathLikeOrReadStream} options.html - PathLike or ReadStream of the HTML content to be converted.
+     * @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({
                       html,
                       header,
@@ -44,7 +71,7 @@ export class HtmlConverter extends Converter {
     }): Promise<Buffer> {
         const data = new FormData();
 
-        await ConverterUtils.addFile(data, html, "index.html")
+        await ConverterUtils.addFile(data, html, "index.html");
 
         await ConverterUtils.customize(data, {
             header,
@@ -62,4 +89,4 @@ export class HtmlConverter extends Converter {
 
         return GotenbergUtils.fetch(this.endpoint, data);
     }
-}
+}
diff --git a/src/chromium/converters/markdown.converter.ts b/src/chromium/converters/markdown.converter.ts
@@ -9,11 +9,40 @@ import {ConverterUtils} from "../utils/converter.utils";
 import {Converter} from "./converter";
 import {ChromiumRoute} from "../../main.config";
 
+/**
+ * Class representing a Markdown converter that extends the base Converter class.
+ * This class is used to convert HTML with markdown content to PDF using Gotenberg service.
+ *
+ * @extends Converter
+ */
 export class MarkdownConverter extends Converter {
+    /**
+     * Creates an instance of MarkdownConverter.
+     * Initializes the converter with the Markdown conversion route.
+     */
     constructor() {
         super(ChromiumRoute.MARKDOWN);
     }
 
+    /**
+     * Converts HTML with markdown content to PDF.
+     *
+     * @param {Object} options - Conversion options.
+     * @param {PathLikeOrReadStream} options.html - PathLike or ReadStream of the HTML content to be converted.
+     * @param {PathLikeOrReadStream} options.markdown - PathLike or ReadStream of the Markdown content to be converted.
+     * @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({
                       html,
                       markdown,
@@ -65,4 +94,4 @@ export class MarkdownConverter extends Converter {
 
         return GotenbergUtils.fetch(this.endpoint, data);
     }
-}
+}
diff --git a/src/chromium/converters/url.converter.ts b/src/chromium/converters/url.converter.ts
@@ -1,7 +1,5 @@
 import {URL} from "url";
-
 import FormData from "form-data";
-
 import {GotenbergUtils, PdfFormat, PathLikeOrReadStream} from "../../common";
 import {
     EmulatedMediaType,
@@ -11,11 +9,39 @@ 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 {
+    /**
+     * Creates an instance of UrlConverter.
+     * Initializes the converter with the URL conversion route.
+     */
     constructor() {
         super(ChromiumRoute.URL);
     }
 
+    /**
+     * 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,
@@ -64,4 +90,4 @@ export class UrlConverter extends Converter {
 
         return GotenbergUtils.fetch(this.endpoint, data);
     }
-}
+}
diff --git a/src/chromium/utils/converter.utils.ts b/src/chromium/utils/converter.utils.ts
@@ -8,7 +8,16 @@ import {
 import {GotenbergUtils, PathLikeOrReadStream} from "../../common";
 import {ReadStream} from "fs";
 
+/**
+ * Utility class for handling common tasks related to conversion.
+ */
 export class ConverterUtils {
+    /**
+     * 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
@@ -82,6 +91,14 @@ export class ConverterUtils {
         }
     }
 
+    /**
+     * 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);
@@ -93,6 +110,13 @@ export class ConverterUtils {
         }
     }
 
+    /**
+     * 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

diff --git a/src/common/gotenberg.utils.ts b/src/common/gotenberg.utils.ts
@@ -1,13 +1,31 @@
 import FormData from "form-data";
 import fetch from "node-fetch";
 
+/**
+ * Utility class for common tasks related to the Gotenberg service.
+ */
 export class GotenbergUtils {
+    /**
+     * Asserts that a condition is true; otherwise, throws an error with the specified message.
+     *
+     * @param {boolean} condition - The condition to assert.
+     * @param {string} message - The error message to throw if the condition is false.
+     * @throws {Error} Throws an error with the specified message if the condition is false.
+     */
     public static assert(condition: boolean, message: string): asserts condition {
         if (!condition) {
             throw new Error(message);
         }
     }
 
+    /**
+     * Performs a POST request to the specified Gotenberg endpoint with the provided FormData.
+     *
+     * @param {string} endpoint - The Gotenberg endpoint URL.
+     * @param {FormData} data - The FormData object to be sent in the POST request.
+     * @returns {Promise<Buffer>} A Promise that resolves to the response body as a Buffer.
+     * @throws {Error} Throws an error if the HTTP response status is not OK.
+     */
     public static async fetch(endpoint: string, data: FormData): Promise<Buffer> {
         const response = await fetch(endpoint, {
             method: "post",
@@ -20,6 +38,7 @@ export class GotenbergUtils {
         if (!response.ok) {
             throw new Error(`${response.status} ${response.statusText}`);
         }
+
         return response.buffer();
     }
-}
+}
diff --git a/src/gotenberg.ts b/src/gotenberg.ts
@@ -15,7 +15,16 @@ if (dotenvConfig.error) {
     dotenv.config({path: path.resolve(envFileFallback)});
 }
 
+/**
+ * Class representing configuration for interacting with Gotenberg service.
+ */
 export class Gotenberg {
+    /**
+     * The Gotenberg service endpoint.
+     * Defaults to the value from the environment variable `GOTENBERG_ENDPOINT`, or falls back to the configuration file.
+     * @type {string}
+     */
     public static endpoint: string =
         process.env.GOTENBERG_ENDPOINT || config.get<string>("gotenberg.endpoint");
 }
+
diff --git a/src/libre-office/utils/libre-office.utils.ts b/src/libre-office/utils/libre-office.utils.ts
@@ -7,7 +7,17 @@ import {GotenbergUtils, PathLikeOrReadStream} from "../../common";
 import {LIBRE_OFFICE_EXTENSIONS} from "./constants";
 import {PageProperties} from "../interfaces/libre-office.types";
 
+/**
+ * Utility class for handling common tasks related to LibreOffice conversions.
+ */
 export class LibreOfficeUtils {
+    /**
+     * Adds files to the FormData object for LibreOffice conversion.
+     *
+     * @param {PathLikeOrReadStream[]} files - An array of files to be added to the FormData.
+     * @param {FormData} data - The FormData object to which files will be added.
+     * @throws {Error} Throws an error if the file extension is not supported.
+     */
     public static async addFiles(files: PathLikeOrReadStream[], data: FormData) {
         for (const [key, file] of files.entries()) {
             const filename = `file${key}`
@@ -28,6 +38,12 @@ export class LibreOfficeUtils {
         }
     }
 
+    /**
+     * 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