Merge pull request #569 from Fdawgs/chore/tidy

.github/dependabot.yml

@@ -24,6 +24,7 @@ updates:
                   - "@commitlint*"
           eslint:
               patterns:
+                  - "@eslint-community*"
                   - "eslint*"
       ignore:
           # Below are dependencies that have migrated to ESM

.github/workflows/cd.yml

@@ -53,11 +53,11 @@ jobs:
             - name: Publish to NPM
               env:
                   NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-              # Build docs and TS definitions, and remove dev values
+              # Build docs/definitions, and remove dev values
               # from package.json before publishing to reduce package size
               run: |
                   npm i --ignore-scripts
-                  npm run build
+                  npm run build --if-present
                   npm pkg delete commitlint devDependencies jest scripts
                   npm publish --access public --ignore-scripts --provenance
 
@@ -66,6 +66,7 @@ jobs:
         needs: release
         if: needs.release.outputs.release_created == 'true'
         runs-on: ubuntu-latest
+        environment: main
         permissions:
             contents: read
             id-token: write
@@ -85,16 +86,16 @@ jobs:
 
             - name: Scope package
               run: |
-                  pkgName=$(npm pkg get name | tr -d '"')
+                  pkgName=$(node -p "require('./package.json').name")
                   npm pkg set name="@fdawgs/$pkgName"
 
             - name: Publish to GitHub Packages
               env:
                   NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-              # Build docs and TS definitions, and remove dev values
+              # Build docs/definitions, and remove dev values
               # from package.json before publishing to reduce package size
               run: |
                   npm i --ignore-scripts
-                  npm run build
+                  npm run build --if-present
                   npm pkg delete commitlint devDependencies jest scripts
                   npm publish --access public --ignore-scripts --provenance

.github/workflows/ci.yml

@@ -69,8 +69,8 @@ jobs:
             - name: Run License Checker
               run: npm run lint:licenses
 
-            - name: Compile TypeScript Definition File
-              run: npm run build
+            - name: Run Build
+              run: npm run build --if-present
 
     commit-lint:
         name: Lint Commit Messages

.gitignore

@@ -135,6 +135,9 @@ dist
 # Clinic.js
 .clinic
 
+# Auto generated files
+types/
+
 # lock files
 bun.lockb
 package-lock.json

.prettierignore

@@ -137,9 +137,8 @@ dist
 
 # Auto generated files
 package.json
-API.md
 CHANGELOG.md
-/types/index.d.ts
+types/
 
 # lock files
 bun.lockb

README.md

@@ -47,15 +47,9 @@ const { Poppler } = require("node-poppler");
 const poppler = new Poppler("/usr/bin");
 ```
 
-## API
+## Example usage
 
-```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
 

package.json

@@ -50,7 +50,7 @@
 		"node": ">=18.0.0"
 	},
 	"scripts": {
-		"build": "tsc && jsdoc2md src/index.js > API.md",
+		"build": "tsc",
 		"jest": "jest",
 		"jest:coverage": "jest --coverage",
 		"lint": "eslint . --cache --ext js,jsx --ignore-path .gitignore",
@@ -86,27 +86,26 @@
 		"testTimeout": 60000
 	},
 	"devDependencies": {
-		"@commitlint/cli": "^19.0.3",
-		"@commitlint/config-conventional": "^19.0.3",
+		"@commitlint/cli": "^19.1.0",
+		"@commitlint/config-conventional": "^19.1.0",
 		"@eslint-community/eslint-plugin-eslint-comments": "^4.1.0",
 		"@types/jest": "^29.5.12",
-		"eslint": "^8.56.0",
+		"eslint": "^8.57.0",
 		"eslint-config-airbnb-base": "^15.0.0",
 		"eslint-config-prettier": "^9.1.0",
 		"eslint-plugin-import": "^2.29.1",
 		"eslint-plugin-jest": "^27.9.0",
-		"eslint-plugin-jsdoc": "^48.1.0",
+		"eslint-plugin-jsdoc": "^48.2.1",
 		"eslint-plugin-promise": "^6.1.1",
-		"eslint-plugin-regexp": "^2.2.0",
+		"eslint-plugin-regexp": "^2.3.0",
 		"eslint-plugin-security": "^2.1.1",
 		"glob": "^10.3.10",
 		"husky": "^9.0.11",
 		"jest": "^29.7.0",
-		"jsdoc-to-markdown": "^8.0.1",
 		"license-checker": "^25.0.1",
 		"prettier": "^3.2.5",
 		"spdx-copyleft": "^1.0.0",
-		"typescript": "^5.3.3"
+		"typescript": "^5.4.2"
 	},
 	"dependencies": {
 		"camelcase": "^6.3.0",

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");
@@ -84,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 binary path for all binaries.
+	 * For `win32` the binary is 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-24.02.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);
 	}
 
 	/**
@@ -1568,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

src/index.test.js

@@ -1,3 +1,4 @@
+/* eslint-disable global-require, security/detect-child-process -- Mocking child_process */
 /* eslint-disable jest/no-conditional-expect -- Depends on the version of the binary */
 /* eslint-disable security/detect-non-literal-fs-filename -- Test files are not user-provided */
 
@@ -60,7 +61,7 @@ describe("Node-Poppler module", () => {
 	describe("Constructor", () => {
 		let platform;
 
-		beforeEach(() => {
+		beforeAll(() => {
 			// Copy the process platform
 			({ platform } = process);
 		});
@@ -72,27 +73,35 @@ describe("Node-Poppler module", () => {
 			});
 		});
 
-		it("Creates a new Poppler instance without the binary path set on win32", () => {
-			Object.defineProperty(process, "platform", {
-				value: "win32",
-			});
-
-			const poppler = new Poppler();
-			expect(poppler.popplerPath).toBe(windowsPath);
-		});
-
-		it("Throws an Error if the binary path is not set and the platform is not win32", () => {
+		/**
+		 * @todo Fix this test, mocking of "node:" scheme not supported yet.
+		 * @see {@link https://github.com/jestjs/jest/pull/14297 | Jest PR #14297}
+		 */
+		// eslint-disable-next-line jest/no-disabled-tests -- Blocked by Jest PR #14297
+		it.skip("Throws an Error if the binary path is not found", () => {
 			Object.defineProperty(process, "platform", {
 				value: "mockOS",
 			});
 
+			// Ensure the mock is used by the UnRTF constructor
+			jest.resetModules();
+			jest.mock("node:child_process", () => ({
+				spawnSync: jest.fn(() => ({
+					stdout: {
+						toString: () => "",
+					},
+				})),
+			}));
+			require("node:child_process");
+			const { Poppler: PopplerMock } = require("./index");
+
 			expect.assertions(1);
 			try {
 				// eslint-disable-next-line no-unused-vars -- This is intentional
-				const poppler = new Poppler();
+				const poppler = new PopplerMock();
 			} catch (err) {
 				expect(err.message).toBe(
-					`${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.`
 				);
 			}
 		});