node-poppler 7.1.0 → 7.2.0

package/README.md

@@ -40,22 +40,9 @@ For macOS users, you can download the latest versions with [Homebrew](https://br
 brew install poppler
 ```
 
-Once they have been installed, you will need to pass the `poppler-utils` installation directory as a parameter to an instance of the Poppler class:
+## Example usage
 
-```js
-const { Poppler } = require("node-poppler");
-const poppler = new Poppler("/usr/bin");
-```
-
-## API
-
-```js
-const { Poppler } = require("node-poppler");
-```
-
-[**API Documentation can be found here**](https://github.com/Fdawgs/node-poppler/blob/main/API.md)
-
-## Examples
+Please refer to the [JSDoc comments in the source code](./src/index.js) or the [generated type definitions](https://www.npmjs.com/package/node-poppler?activeTab=code) for information on the available options.
 
 ### poppler.pdfToCairo
 
@@ -174,8 +161,8 @@ poppler
 
 Contributions are welcome, and any help is greatly appreciated!
 
-See [the contributing guide](./CONTRIBUTING.md) for details on how to get started.
-Please adhere to this project's [Code of Conduct](./CODE_OF_CONDUCT.md) when contributing.
+See [the contributing guide](https://github.com/Fdawgs/.github/blob/main/CONTRIBUTING.md) for details on how to get started.
+Please adhere to this project's [Code of Conduct](https://github.com/Fdawgs/.github/blob/main/CODE_OF_CONDUCT.md) when contributing.
 
 ## Acknowledgements
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "node-poppler",
-	"version": "7.1.0",
+	"version": "7.2.0",
 	"description": "Asynchronous node.js wrapper for the Poppler PDF rendering library",
 	"keywords": [
 		"async",
@@ -35,7 +35,10 @@
 	"main": "src/index.js",
 	"type": "commonjs",
 	"types": "types/index.d.ts",
-	"repository": "git+https://github.com/Fdawgs/node-poppler.git",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Fdawgs/node-poppler.git"
+	},
 	"homepage": "https://github.com/Fdawgs/node-poppler",
 	"bugs": {
 		"url": "https://github.com/Fdawgs/node-poppler/issues"
@@ -48,7 +51,7 @@
 	},
 	"dependencies": {
 		"camelcase": "^6.3.0",
-		"semver": "^7.5.4",
+		"semver": "^7.6.0",
 		"upath": "^2.0.1"
 	}
 }

package/src/index.js

@@ -1,6 +1,6 @@
 "use strict";
 
-const { execFile, spawn } = require("node:child_process");
+const { execFile, spawn, spawnSync } = require("node:child_process");
 const { promisify } = require("node:util");
 const camelCase = require("camelcase");
 const { lt } = require("semver");
@@ -41,14 +41,13 @@ function parseOptions(acceptedOptions, options, version) {
 	Object.keys(options).forEach((key) => {
 		if (Object.hasOwn(acceptedOptions, key)) {
 			// eslint-disable-next-line valid-typeof -- `type` is a string
-			if (typeof options[key] === acceptedOptions[key].type) {
+			if (acceptedOptions[key].type === typeof options[key]) {
 				// Skip boolean options if false
-
 				if (acceptedOptions[key].type === "boolean" && !options[key]) {
 					return;
 				}
-				// Arg will be empty for some non-standard options
 
+				// Arg will be empty for some non-standard options
 				if (acceptedOptions[key].arg !== "") {
 					args.push(acceptedOptions[key].arg);
 				}
@@ -85,24 +84,50 @@ function parseOptions(acceptedOptions, options, version) {
 }
 
 class Poppler {
-	/** @param {string} [binPath] - Path of poppler-utils binaries. */
+	/**
+	 * @param {string} [binPath] - Path of poppler-utils binaries.
+	 * If not provided, the constructor will attempt to find the Poppler `pdfinfo` binary
+	 * in the PATH environment variable and use that as the path for all binaries.
+	 * For `win32` the binaries are bundled with the package and will be used
+	 * if a local installation is not found.
+	 */
 	constructor(binPath) {
+		this.popplerPath = "";
+
+		/* istanbul ignore else: requires specific OS */
 		if (binPath) {
-			this.popplerPath = normalizeTrim(binPath);
-		} else if (process.platform === "win32") {
-			this.popplerPath = joinSafe(
-				__dirname,
-				"lib",
-				"win32",
-				"poppler-23.11.0",
-				"Library",
-				"bin"
-			);
+			/** @type {string|undefined} */
+			this.popplerPath = binPath;
 		} else {
+			const { platform } = process;
+
+			const which = spawnSync(platform === "win32" ? "where" : "which", [
+				"pdfinfo",
+			]).stdout.toString();
+			const popplerPath = /(.+)pdfinfo/u.exec(which)?.[1];
+
+			if (popplerPath) {
+				this.popplerPath = popplerPath;
+			}
+			if (platform === "win32" && !popplerPath) {
+				this.popplerPath = joinSafe(
+					__dirname,
+					"lib",
+					"win32",
+					"poppler-24.02.0",
+					"Library",
+					"bin"
+				);
+			}
+		}
+
+		/* istanbul ignore next: unable to test due to https://github.com/jestjs/jest/pull/14297 */
+		if (!this.popplerPath) {
 			throw new Error(
-				`${process.platform} poppler-util binaries are not provided, please pass the installation directory as a parameter to the Poppler instance.`
+				`Unable to find ${process.platform} Poppler binaries, please pass the installation directory as a parameter to the Poppler instance.`
 			);
 		}
+		this.popplerPath = normalizeTrim(this.popplerPath);
 	}
 
 	/**
@@ -124,9 +149,7 @@ class Poppler {
 
 		try {
 			const args = parseOptions(acceptedOptions, options);
-			args.push(file);
-			args.push(fileToAttach);
-			args.push(outputFile);
+			args.push(file, fileToAttach, outputFile);
 
 			const { stdout } = await execFileAsync(
 				joinSafe(this.popplerPath, "pdfattach"),
@@ -145,9 +168,9 @@ class Poppler {
 	 * @param {object} [options] - Object containing options to pass to binary.
 	 * @param {boolean} [options.listEmbedded] - List all of the embedded files in the PDF file.
 	 * File names are converted to the text encoding specified by `options.outputEncoding`.
-	 * @param {string} [options.ownerPassword] - Owner password (for encrypted files).
 	 * @param {string} [options.outputEncoding] - Sets the encoding to use for text output.
 	 * This defaults to `UTF-8`.
+	 * @param {string} [options.ownerPassword] - Owner password (for encrypted files).
 	 * @param {string} [options.outputPath] - Set the file name used when saving an embedded file with
 	 * the save option enabled, or the directory if `options.saveall` is used.
 	 * @param {boolean} [options.printVersionInfo] - Print copyright and version info.
@@ -167,16 +190,16 @@ class Poppler {
 	async pdfDetach(file, options = {}) {
 		const acceptedOptions = {
 			listEmbedded: { arg: "-list", type: "boolean" },
-			ownerPassword: { arg: "-opw", type: "string" },
 			outputEncoding: { arg: "-enc", type: "string" },
 			outputPath: { arg: "-o", type: "string" },
+			ownerPassword: { arg: "-opw", type: "string" },
 			printVersionInfo: { arg: "-v", type: "boolean" },
+			saveAllFiles: { arg: "-saveall", type: "boolean" },
 			saveFile: {
 				arg: "-savefile",
 				type: "string",
 				minVersion: "0.86.0",
 			},
-			saveAllFiles: { arg: "-saveall", type: "boolean" },
 			saveSpecificFile: { arg: "-save", type: "number" },
 			userPassword: { arg: "-upw", type: "string" },
 		};
@@ -206,7 +229,7 @@ class Poppler {
 	 * will use for non-embedded fonts.
 	 * @param {string} [options.ownerPassword] - Owner password (for encrypted files).
 	 * @param {boolean} [options.printVersionInfo] - Print copyright and version info.
-	 * @param {string} [options.userPassword] - User password (for encrypted files).	 *
+	 * @param {string} [options.userPassword] - User password (for encrypted files).
 	 * @returns {Promise<string>} A promise that resolves with a stdout string, or rejects with an `Error` object.
 	 */
 	async pdfFonts(file, options = {}) {
@@ -231,11 +254,7 @@ class Poppler {
 			const args = parseOptions(acceptedOptions, options, versionInfo);
 
 			return new Promise((resolve, reject) => {
-				if (Buffer.isBuffer(file)) {
-					args.push("-");
-				} else {
-					args.push(file);
-				}
+				args.push(Buffer.isBuffer(file) ? "-" : file);
 
 				const child = spawn(
 					joinSafe(this.popplerPath, "pdffonts"),
@@ -294,12 +313,12 @@ class Poppler {
 	 * @param {boolean} [options.ccittFile] - Generate CCITT images as CCITT files.
 	 * @param {number} [options.firstPageToConvert] - Specifies the first page to convert.
 	 * @param {number} [options.lastPageToConvert] - Specifies the last page to convert.
-	 * @param {boolean} [options.list] - Instead of writing the images, list the
-	 * images along with various information for each image.
-	 * NOTE: Do not specify the outputPrefix with this option.
 	 * @param {boolean} [options.jbig2File] - Generate JBIG2 images as JBIG2 files.
 	 * @param {boolean} [options.jpeg2000File] - Generate JPEG2000 images at JP2 files.
 	 * @param {boolean} [options.jpegFile] - Generate JPEG images as JPEG files.
+	 * @param {boolean} [options.list] - Instead of writing the images, list the
+	 * images along with various information for each image.
+	 * NOTE: Do not specify the outputPrefix with this option.
 	 * @param {string} [options.ownerPassword] - Owner password (for encrypted files).
 	 * @param {boolean} [options.pngFile] - Change the default output format to PNG.
 	 * @param {boolean} [options.printVersionInfo] - Print copyright and version info.
@@ -313,10 +332,10 @@ class Poppler {
 			ccittFile: { arg: "-ccitt", type: "boolean" },
 			firstPageToConvert: { arg: "-f", type: "number" },
 			lastPageToConvert: { arg: "-l", type: "number" },
-			list: { arg: "-list", type: "boolean" },
 			jbig2File: { arg: "-jbig2", type: "boolean" },
 			jpeg2000File: { arg: "-jp2", type: "boolean" },
 			jpegFile: { arg: "-j", type: "boolean" },
+			list: { arg: "-list", type: "boolean" },
 			ownerPassword: { arg: "-opw", type: "string" },
 			pngFile: { arg: "-png", type: "boolean" },
 			printVersionInfo: { arg: "-v", type: "boolean" },
@@ -336,11 +355,7 @@ class Poppler {
 			const args = parseOptions(acceptedOptions, options, versionInfo);
 
 			return new Promise((resolve, reject) => {
-				if (Buffer.isBuffer(file)) {
-					args.push("-");
-				} else {
-					args.push(file);
-				}
+				args.push(Buffer.isBuffer(file) ? "-" : file);
 
 				if (outputPrefix) {
 					args.push(outputPrefix);
@@ -410,7 +425,6 @@ class Poppler {
 	 * of a Tagged-PDF file.
 	 * @param {boolean} [options.printDocStructText] - Print the textual content along with the
 	 * document structure of a Tagged-PDF file. Note that extracting text this way might be slow
-	 *
 	 * for big PDF files.
 	 * @param {boolean} [options.printIsoDates] - Prints dates in ISO-8601 format (including the time zone).
 	 * @param {boolean} [options.printJS] - Prints all JavaScript in the PDF file.
@@ -461,7 +475,7 @@ class Poppler {
 
 			/**
 			 * Poppler does not set the "File size" metadata value if passed
-			 * a Buffer via stdin, so need to retrieve it from the Buffer
+			 * a Buffer via stdin, so need to retrieve it from the Buffer.
 			 */
 			/** @type {number} */
 			let fileSize;
@@ -577,8 +591,7 @@ class Poppler {
 			const versionInfo = popplerVersionRegex.exec(stderr)[1];
 
 			const args = parseOptions(acceptedOptions, options, versionInfo);
-			args.push(file);
-			args.push(outputPattern);
+			args.push(file, outputPattern);
 
 			const { stdout } = await execFileAsync(
 				joinSafe(this.popplerPath, "pdfseparate"),
@@ -764,17 +777,10 @@ class Poppler {
 			const args = parseOptions(acceptedOptions, options, versionInfo);
 
 			return new Promise((resolve, reject) => {
-				if (Buffer.isBuffer(file)) {
-					args.push("-");
-				} else {
-					args.push(file);
-				}
-
-				if (outputFile) {
-					args.push(outputFile);
-				} else {
-					args.push("-");
-				}
+				args.push(
+					Buffer.isBuffer(file) ? "-" : file,
+					outputFile || "-"
+				);
 
 				const child = spawn(
 					joinSafe(this.popplerPath, "pdftocairo"),
@@ -859,7 +865,7 @@ class Poppler {
 	 * @param {string} [options.ownerPassword] - Owner password (for encrypted files).
 	 * @param {boolean} [options.printVersionInfo] - Print copyright and version info.
 	 * @param {boolean} [options.quiet] - Do not print any messages or errors.
-	 * @param {boolean} [options.singlePage] - generate single HTML that includes all pages.
+	 * @param {boolean} [options.singlePage] - Generate single HTML that includes all pages.
 	 * @param {boolean} [options.stdout] - Use standard output.
 	 * @param {string} [options.userPassword] - User password (for encrypted files).
 	 * @param {number} [options.wordBreakThreshold] - Adjust the word break threshold percent.
@@ -912,11 +918,7 @@ class Poppler {
 			const args = parseOptions(acceptedOptions, options, versionInfo);
 
 			return new Promise((resolve, reject) => {
-				if (Buffer.isBuffer(file)) {
-					args.push("-");
-				} else {
-					args.push(file);
-				}
+				args.push(Buffer.isBuffer(file) ? "-" : file);
 
 				if (outputFile) {
 					args.push(outputFile);
@@ -944,8 +946,8 @@ class Poppler {
 				});
 
 				/**
-				 * pdfToHtml does not return an exit code so check output to see if it was successful.
-				 * @see {@link  https://gitlab.freedesktop.org/poppler/poppler/-/blob/master/utils/pdftohtml.1 | Poppler pdftohtml man}
+				 * PdfToHtml does not return an exit code so check output to see if it was successful.
+				 * @see {@link https://gitlab.freedesktop.org/poppler/poppler/-/blob/master/utils/pdftohtml.1 | Poppler pdftohtml man}
 				 */
 				child.on("close", () => {
 					if (stdOut !== "") {
@@ -1117,13 +1119,7 @@ class Poppler {
 			const args = parseOptions(acceptedOptions, options, versionInfo);
 
 			return new Promise((resolve, reject) => {
-				if (Buffer.isBuffer(file)) {
-					args.push("-");
-				} else {
-					args.push(file);
-				}
-
-				args.push(outputPath);
+				args.push(Buffer.isBuffer(file) ? "-" : file, outputPath);
 
 				const child = spawn(
 					joinSafe(this.popplerPath, "pdftoppm"),
@@ -1212,6 +1208,11 @@ class Poppler {
 	 * This enables all Level 2 featuresplus CID font embedding.
 	 * @param {boolean} [options.level3Sep] - Generate Level 3 separable PostScript.
 	 * The separation handling is the same as for `options.level2Sep`.
+	 * @param {boolean} [options.noCenter] - By default, PDF pages smaller than the paper
+	 * (after any scaling) are centered on the paper. This option causes them to be aligned to
+	 * the lower-left corner of the paper instead.
+	 * @param {boolean} [options.noCrop] - By default, printing output is cropped to the CropBox
+	 * specified in the PDF file. This option disables cropping.
 	 * @param {boolean} [options.noEmbedCIDFonts] - By default, any CID PostScript fonts which are
 	 * embedded in the PDF file are copied into the PostScript file. This option disables that embedding.
 	 * No attempt is made to substitute for non-embedded CID PostScript fonts.
@@ -1225,11 +1226,6 @@ class Poppler {
 	 * @param {boolean} [options.noEmbedType1Fonts] - By default, any Type 1 fonts which are embedded in the PDF file
 	 * are copied into the PostScript file. This option causes pdfToPs to substitute base fonts instead.
 	 * Embedded fonts make PostScript files larger, but may be necessary for readable output.
-	 * @param {boolean} [options.noCenter] - By default, PDF pages smaller than the paper
-	 * (after any scaling) are centered on the paper. This option causes them to be aligned to
-	 * the lower-left corner of the paper instead.
-	 * @param {boolean} [options.noCrop] - By default, printing output is cropped to the CropBox
-	 * specified in the PDF file. This option disables cropping.
 	 * @param {boolean} [options.noShrink] - Do not scale PDF pages which are larger than the paper.
 	 * By default, pages larger than the paper are shrunk to fit.
 	 * @param {boolean} [options.opi] - Generate OPI comments for all images and forms which have OPI information.
@@ -1304,6 +1300,8 @@ class Poppler {
 			level2Sep: { arg: "-level2sep", type: "boolean" },
 			level3: { arg: "-level3", type: "boolean" },
 			level3Sep: { arg: "-level3sep", type: "boolean" },
+			noCenter: { arg: "-nocenter", type: "boolean" },
+			noCrop: { arg: "-nocrop", type: "boolean" },
 			noEmbedCIDFonts: { arg: "-noembcidps", type: "boolean" },
 			noEmbedCIDTrueTypeFonts: {
 				arg: "-noembcidtt",
@@ -1311,8 +1309,6 @@ class Poppler {
 			},
 			noEmbedTrueTypeFonts: { arg: "-noembtt", type: "boolean" },
 			noEmbedType1Fonts: { arg: "-noembt1", type: "boolean" },
-			noCenter: { arg: "-nocenter", type: "boolean" },
-			noCrop: { arg: "-nocrop", type: "boolean" },
 			noShrink: { arg: "-noshrink", type: "boolean" },
 			opi: { arg: "-opi", type: "boolean" },
 			optimizecolorspace: {
@@ -1328,11 +1324,11 @@ class Poppler {
 			passfonts: { arg: "-passfonts", type: "boolean" },
 			preload: { arg: "-preload", type: "boolean" },
 			printVersionInfo: { arg: "-v", type: "boolean" },
+			processColorFormat: { arg: "-processcolorformat", type: "string" },
 			processColorProfile: {
 				arg: "-processcolorprofile",
 				type: "string",
 			},
-			processColorFormat: { arg: "-processcolorformat", type: "string" },
 			quiet: { arg: "-q", type: "boolean" },
 			rasterize: {
 				arg: "-rasterize",
@@ -1355,17 +1351,10 @@ class Poppler {
 			const args = parseOptions(acceptedOptions, options, versionInfo);
 
 			return new Promise((resolve, reject) => {
-				if (Buffer.isBuffer(file)) {
-					args.push("-");
-				} else {
-					args.push(file);
-				}
-
-				if (outputFile) {
-					args.push(outputFile);
-				} else {
-					args.push("-");
-				}
+				args.push(
+					Buffer.isBuffer(file) ? "-" : file,
+					outputFile || "-"
+				);
 
 				const child = spawn(
 					joinSafe(this.popplerPath, "pdftops"),
@@ -1425,7 +1414,7 @@ class Poppler {
 	 * @param {boolean} [options.boundingBoxXhtmlLayout] - Generate an XHTML file containing
 	 * bounding box information for each block, line, and word in the file.
 	 * @param {boolean} [options.cropBox] - Use the crop box rather than the media box with
-	 * `options.boundingBoxXhtml` and `options.boundingBoxXhtmlLayout`
+	 * `options.boundingBoxXhtml` and `options.boundingBoxXhtmlLayout`.
 	 * @param {number} [options.cropHeight] - Specifies the height of crop area in pixels
 	 * (image output) or points (vector output).
 	 * @param {number} [options.cropWidth] - Specifies the width of crop area in pixels
@@ -1512,17 +1501,10 @@ class Poppler {
 			const args = parseOptions(acceptedOptions, options, versionInfo);
 
 			return new Promise((resolve, reject) => {
-				if (Buffer.isBuffer(file)) {
-					args.push("-");
-				} else {
-					args.push(file);
-				}
-
-				if (outputFile) {
-					args.push(outputFile);
-				} else {
-					args.push("-");
-				}
+				args.push(
+					Buffer.isBuffer(file) ? "-" : file,
+					outputFile || "-"
+				);
 
 				const child = spawn(
 					joinSafe(this.popplerPath, "pdftotext"),
@@ -1612,5 +1594,5 @@ class Poppler {
 	}
 }
 
-module.exports.Poppler = Poppler;
-module.exports.default = Poppler;
+module.exports.default = Poppler; // ESM default export
+module.exports.Poppler = Poppler; // TypeScript and named export