pdf2json v4.1.0 release
Note: required node version is raised to v22.23.2, the current (jod) LTS version.
Previous v20.18.0 (iron) has been EOL since April 30, 2026.
pdf2json v4.1.0 is a major infrastructure and DevOps modernization release. It replaces the external
Jest test harness with Node.js's native node:test runner, cuts test execution time by ~88% (from ~13s
down to ~1.6s), eliminates ~250 transitive development dependencies (~5,000 lines pruned from
package-lock.json), bumps the minimum engine baseline to Node.js 22 LTS, resolves TypeScript CommonJS
declaration constructability issues, and hardens CI/CD pipelines across multiple operating systems.
Highlights
• Native node:test Migration: Replaced Jest with Node.js built-in node:test and node:assert/strict
across all 7 test suites (74+ tests), eliminating ~250 transitive dependencies and reducing unit test
run times from ~13s to ~1.6s.
• Node.js 22 LTS Baseline: Updated engines.node to >=22.23.2 to leverage native test coverage filtering
(--test-coverage-exclude), resolve V8 coverage sourcemap mapping crashes, and align with active LTS.
• CommonJS TypeScript Declaration Fix: Added declaration merging in pdfparser.d.cts (export =
PDFParser) so CommonJS TypeScript consumers can construct instances without encountering compiler error
TS2351: This expression is not constructable.
• Zero-Dependency Core Preserved: Reaffirmed zero runtime dependencies while pruning dead
devDependencies and consolidating the linting stack into unified typescript-eslint.
• CI/CD & Script Hardening: Multi-OS GitHub Actions workflow matrix (ubuntu-latest and windows-latest),
clean and reproducible npm ci builds, automated test error code verification, and clearer test
reporting for expected failure scenarios.
Detailed Changes
1. Test Runner & Coverage Modernization (#434, #435)
• Jest to node:test Transition:
• Migrated all 7 test suites from Jest syntax to Node.js built-in node:test (describe, it) and
node:assert/strict:
• test.cjs (Federal forms parsing)
• _test_cli.cjs (CLI flag validation and exit code contracts)
• _test_errors.cjs (Corrupt/invalid file error handling)
• _test_sortBidiTexts.cjs (Bidirectional text spatial sorting)
• _test_stream.cjs (Stream parsing API)
• _test_testMultipleDataPDF.cjs (Multi-parse stability)
• _test_type3glyph.cjs (Type3 glyph rendering)
• Deleted jest.config.json and uninstalled jest and all related packages.
• Bounded Timeouts & Discovery:
• Configured --test-timeout=15000 (15s) in package.json to prevent event-based tests from hanging
indefinitely.
• Simplified script test discovery using quoted glob patterns ("test/test*.cjs").
• Native Node Code Coverage:
• Configured native coverage via --experimental-test-coverage with dual reporters: spec table
output to stdout and standard LCOV output written to coverage/lcov.info.
• Excluded test/base/bundled files via --test-coverage-exclude="test/" --test-coverage-
exclude="base/" --test-coverage-exclude="lib/pdfjs-code.js".
• Added coverage/ to .gitignore.
2. TypeScript Typings & Bundling (#434)
• CommonJS Declaration Merging:
• Introduced pdfparser.d.cts combining declare class PDFParser with declare namespace PDFParser and
ending with export = PDFParser.
• Updated bundle-pdfjs-base.js to copy pdfparser.d.cts directly into dist/, eliminating the fragile
regex replacement on pdfparser.d.ts.
• Rollup Build Configuration:
• Added /^node:.*/ regex external matching in rollup.config.js.
• Pruned unused Rollup plugins: @rollup/plugin-commonjs, @rollup/plugin-node-resolve,
@rollup/plugin-eslint, and unused @rollup/plugin-json from the CLI bundle.
• Kept Rollup sourcemaps enabled (sourcemap: true) to resolve build warnings from @rollup/plugin-
typescript.
3. Shell Scripts & Reporting Clarity (#435)
• Corpus Test Script Verification:
• Updated p2j.forms.sh and p2j.one.sh to capture exit codes ($?) and fail immediately on unexpected
non-zero statuses.
• Removed outdated disabled diff -rq checks that were failing against legacy pre-v2 schemas.
• Expected Failure Clarification:
• In p2j.one.sh, explicitly validated that the misc exception test suite produces exit code 1 with
exactly 16 successes and 6 failures.
• Clarified terminal reporting to label intentional failures as 6 fail (expected) followed by ✓
Misc test passed: 16 success, 6 fail (expected exceptions for error-handling verification) to
eliminate confusion during test runs.
4. CI/CD & Toolchain (#434)
• GitHub Actions:
• Added multi-OS matrix testing across ubuntu-latest and windows-latest with bash shell defaults in
ci.yml.
• Upgraded CI runner from Node.js 20.18.0 to 22.23.2.
• Replaced manual rm -rf node_modules && npm i with deterministic npm ci.
• Added an explicit npm run lint step.
• Replaced npx rollup in package.json with direct rollup calls to avoid npm_config_allow_scripts
environment collisions.
• Updated build:clean script to safely unset npm_config_allow_scripts before running npm ci && npm
run build.
5. Dependency Management
• ESLint & TypeScript Stack Consolidation:
• Replaced separate @typescript-eslint/eslint-plugin and @typescript-eslint/parser with unified
typescript-eslint (^8.70.0) in eslint.config.js.
• Aligned @types/node to ^22.20.2 matching Node.js 22 LTS.
• Cleaned up redundant resolutions, overrides, and empty dependencies/bundleDependencies entries in
package.json.
• Automated Dependency Bumps:
• @babel/core from 7.29.0 to 7.29.7 (#433)
• js-yaml from 3.14.2 to 3.15.2 (#431)
• brace-expansion (updates across 1.x, 2.x, 5.x) (#430)
• browserslist from 4.28.2 to 4.28.8 (#429)
• @humanfs/node from 0.16.7 to 0.16.8 (#428)
• tslib from ^2.6.2 to ^2.8.1
──────
Breaking Changes & Migration Guide
Warning
- required node version is raised to v22.23.2, the current (jod) LTS version.
- revious v20.18.0 (iron) has been EOL since April 30, 2026.
──────