qpdf-node 0.0.0-stage → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,30 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 qpdf-node contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
23
+ ---
24
+
25
+ This license covers only the source code in this repository (the C++ core, the
26
+ Node.js and WebAssembly bindings, and the TypeScript wrapper). The compiled
27
+ addon and WebAssembly module statically link qpdf (Apache License 2.0), zlib,
28
+ and libjpeg-turbo; their licenses and notices are in THIRD_PARTY_NOTICES.md.
29
+ The distributed package is therefore licensed "MIT AND Apache-2.0" as a whole,
30
+ not MIT alone.
package/README.md CHANGED
@@ -1,3 +1,418 @@
1
- # Temporary Holding Version
1
+ # qpdf-node
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Extract, merge and split PDF pages from Node.js and (experimentally) the browser, on top of
4
+ [qpdf](https://github.com/qpdf/qpdf) (C++, Apache-2.0). One shared C++ core serves two bindings:
5
+
6
+ - **Node.js**: a C++ [N-API](https://nodejs.org/api/n-api.html) addon written with `node-addon-api`,
7
+ built with CMake through `cmake-js`. Work runs on the libuv thread pool.
8
+ - **WebAssembly**: an Emscripten/embind module over the same core, bytes in and bytes out, meant to
9
+ run inside a Web Worker.
10
+
11
+ No `qpdf` executable is spawned, and the stale third-party `qpdf-wasm` npm package is not used.
12
+
13
+ > **Status: 0.2.1 (prepared, not yet released).** `qpdf-node@0.2.0` is on npm as a single bundled
14
+ > package; 0.2.1 is the first release with per-platform packages (see
15
+ > [0.2.0 versus 0.2.1](#020-versus-021)). The release workflow
16
+ > (`.github/workflows/release.yml`) is written to build and test the prebuilt addons on every
17
+ > supported platform, but has not run for 0.2.1 yet; see [Releasing](#releasing) and [Platform support](#platform-support) for what is and is not
18
+ > verified. This package replaces the earlier `pdq-node` (Rust/pdq); see
19
+ > [Changes from pdq-node](#changes-from-pdq-node).
20
+
21
+ ## Install
22
+
23
+ ```sh
24
+ npm install qpdf-node
25
+ ```
26
+
27
+ That is the only package you install. You never choose a platform: `qpdf-node` lists one
28
+ platform package per supported system in `optionalDependencies`, each marked with `os`, `cpu` and
29
+ (on Linux) `libc`, so npm, pnpm and yarn download only the one that matches your machine. The
30
+ platform packages (`qpdf-node-darwin-arm64`, `qpdf-node-darwin-x64`, `qpdf-node-linux-x64-gnu`,
31
+ `qpdf-node-linux-arm64-gnu`, `qpdf-node-win32-x64-msvc`) are an implementation detail: they hold the
32
+ native addon and have no API, so do not depend on them directly. There are no install scripts and no
33
+ download at install time.
34
+
35
+ Package sizes (measured on the darwin-arm64 package; the other four are expected to be similar
36
+ since they are built from the same sources, but have not been measured):
37
+
38
+ | Package | Compressed | Unpacked |
39
+ | -------------------------- | ------------ | ------------ |
40
+ | `qpdf-node` (root) | about 31 kB | about 94 kB |
41
+ | one platform package | about 1.0 MB | about 2.6 MB |
42
+ | what `npm install` fetches | about 1.0 MB | about 2.7 MB |
43
+
44
+ The exact sizes are printed by `npm pack` and by `pnpm smoke:packages`.
45
+
46
+ Install without optional dependencies (`--omit=optional`, `--no-optional`) or copy `node_modules`
47
+ between platforms, and the platform package is missing: the loader then fails with an error that
48
+ names the missing package. Reinstall on the target machine.
49
+
50
+ ### 0.2.0 versus 0.2.1
51
+
52
+ - **`qpdf-node@0.2.0`** was published as one self-contained package that bundled all five addons
53
+ (roughly 17 MB unpacked and 6-7 MB compressed, an estimate from five addons of about 3 MB each) and had no `optionalDependencies`. It stays on npm
54
+ unchanged: npm versions are immutable.
55
+ - **`qpdf-node@0.2.1` and later** use the layout above: a JavaScript-only root package plus one small
56
+ platform package per system. Installing is smaller and faster, and the API is identical. Nothing
57
+ in your code changes; just `npm install qpdf-node@latest`.
58
+
59
+ At load time the addon is looked up in this order:
60
+
61
+ 1. `build/Release/qpdf_node.node` inside the package directory: a source checkout after
62
+ `pnpm run build:native`. Published packages do not contain it.
63
+ 2. The platform package for the running Node.js (`qpdf-node-<platform>-<arch>[-abi]`).
64
+
65
+ A file that exists but fails to load is reported as is, and an unsupported platform gets an error
66
+ that lists the supported packages.
67
+
68
+ ## Platform support
69
+
70
+ | Platform package (installed automatically) | OS / CPU | Built on GitHub runner | Notes |
71
+ | ------------------------------------------ | -------------------- | ---------------------- | --------------------------------------------------- |
72
+ | `qpdf-node-darwin-arm64` | macOS, Apple silicon | `macos-15` | Locally built and tested. Minimum macOS 12. |
73
+ | `qpdf-node-darwin-x64` | macOS, Intel | `macos-15-intel` | Built by CI only. Minimum macOS 12. |
74
+ | `qpdf-node-linux-x64-gnu` | Linux x64, glibc | `ubuntu-22.04` | Built by CI only. glibc 2.35 or newer. |
75
+ | `qpdf-node-linux-arm64-gnu` | Linux arm64, glibc | `ubuntu-22.04-arm` | Built by CI only. glibc 2.35 or newer. |
76
+ | `qpdf-node-win32-x64-msvc` | Windows x64 | `windows-2022` | Built by CI only. Needs the Microsoft VC++ runtime. |
77
+
78
+ **Not supported:** musl Linux (Alpine), 32-bit systems, Windows arm64, FreeBSD. The loader reports
79
+ these as unsupported (musl is detected and is not mistaken for glibc); build from source there.
80
+ "Built by CI only" means the workflow is written for it but no one has yet seen it run: expect to fix
81
+ the first run of each non-macOS-arm64 job. On Windows, paths with characters outside the system code
82
+ page are untested (path handling in `native/core/file_operations.cc` uses `std::filesystem` with
83
+ narrow strings).
84
+
85
+ ## API
86
+
87
+ ```ts
88
+ import { merge, splitPages, pageCount, openPdf, qpdfVersion, QpdfError } from "qpdf-node";
89
+
90
+ // Bytes in, bytes out. The document is parsed once and kept in memory.
91
+ const pdf = await openPdf(bytes); // Buffer or Uint8Array
92
+ try {
93
+ console.log(pdf.pageCount);
94
+ const subset: Uint8Array = await pdf.extract([3, 1, 2]); // 1-based, in this order
95
+ } finally {
96
+ await pdf.close();
97
+ }
98
+
99
+ // Path-based. A string input is shorthand for { path }.
100
+ await merge({
101
+ inputs: ["cover.pdf", { path: "body.pdf", pages: "2-z" }],
102
+ output: "out/book.pdf",
103
+ });
104
+ await splitPages({ input: "book.pdf", outputPattern: "out/page-%d.pdf" }); // page-01.pdf, ...
105
+ await splitPages({ input: "book.pdf", outputPattern: "out/chunk-%d.pdf", pagesPerFile: 50 });
106
+ const pages: number = await pageCount({ input: "book.pdf" });
107
+ qpdfVersion(); // "12.4.2"
108
+ ```
109
+
110
+ Every function returns a promise and runs its PDF work off the event loop. Paths are strings;
111
+ relative paths are relative to the process working directory. Output directories must already exist.
112
+
113
+ ### `openPdf(input): Promise<OpenedPdf>`
114
+
115
+ `input` is a non-empty `Uint8Array` (a `Buffer` is one). The bytes are copied into the addon and
116
+ parsed **once**; the parsed qpdf document stays in memory inside the handle and every `extract`
117
+ reuses it. Nothing is written to disk. Changing `input` after `openPdf` resolves has no effect.
118
+
119
+ | Member | Description |
120
+ | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
121
+ | `pageCount` | Number of pages, counted by walking the page tree (not by trusting `/Count`). |
122
+ | `extract(pages)` | A new unencrypted PDF (`Buffer`) holding `pages` in the given order. `pages` is a non-empty array of **distinct** integers from 1 to `pageCount`; anything else rejects with `INVALID_ARGUMENT` before any work starts. Output is deterministic: the same request on the same handle returns the same bytes. |
123
+ | `close()` | Idempotent. Waits for extractions already in progress, which still complete; later `extract` calls reject with `INVALID_ARGUMENT`. Releases the parsed document. A handle that is garbage collected without `close()` is released too, but possibly late, so close it in a `finally`. |
124
+
125
+ `extract` calls may overlap, but they run one after another for a given handle: qpdf's objects are
126
+ not thread-safe, and copied streams are read lazily from the source while the output is written, so
127
+ the handle serializes them. Different handles run in parallel.
128
+
129
+ What `extract` copies: the selected pages with everything they reference (content, fonts, images,
130
+ annotations), resources and sizes a page inherits from the page tree pushed onto the page, and the
131
+ source's PDF version. Streams are copied exactly as stored (no decoding, no recompression). Links
132
+ that point at pages that were not selected are left dangling (null), they do not drag those pages
133
+ in. Interactive form fields, outlines and named destinations are not restructured; a digital
134
+ signature survives as data but is no longer valid on a subset.
135
+
136
+ Encrypted inputs that need a real password are not supported by `openPdf`; inputs that open with
137
+ the empty user password work and the output is unencrypted. A damaged PDF is repaired when qpdf
138
+ can, silently; otherwise `openPdf` rejects with `OPERATION_FAILED`.
139
+
140
+ ### `merge(options): Promise<void>`
141
+
142
+ | Option | Type | Description |
143
+ | ---------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------- |
144
+ | `inputs` | `Array<string \| { path; pages? }>` | Inputs in output order. At least one. |
145
+ | `output` | `string` | Output file. An existing file is replaced. It is written beside the target and renamed into place on success. |
146
+ | `password` | `string?` | Only for encrypted inputs that do not open with the empty user password. Used for every input. |
147
+
148
+ `pages` selects pages of one input, in output order:
149
+
150
+ | Expression | Selects |
151
+ | ---------- | ------------------------------------- |
152
+ | `5` | page 5 |
153
+ | `1-3` | pages 1, 2, 3 |
154
+ | `4-z` | page 4 through the last page |
155
+ | `z`, `r1` | the last page |
156
+ | `r10-r1` | the last ten pages, in document order |
157
+ | `7-3,1,r1` | pages 7 down to 3, then 1, then last |
158
+
159
+ Pages are 1-based, `z` is the last page, `rN` is the Nth page from the end, `A-B` with `B` before `A`
160
+ runs backwards, and commas join parts in the order written. Whitespace is not allowed. A page may be
161
+ listed more than once (the second use is a shallow copy). Bad syntax rejects with `INVALID_ARGUMENT`
162
+ before any file is touched; a page beyond the document rejects with `OPERATION_FAILED` and is never
163
+ clamped. `output` must not be one of the inputs.
164
+
165
+ ### `splitPages(options): Promise<void>`
166
+
167
+ | Option | Type | Description |
168
+ | --------------- | --------- | ------------------------------------------------------------------------------ |
169
+ | `input` | `string` | The PDF to split. |
170
+ | `outputPattern` | `string` | Output path template with exactly one `%d`. |
171
+ | `pagesPerFile` | `number?` | Consecutive pages per output file, an integer from 1 to 4294967295. Default 1. |
172
+ | `password` | `string?` | Only for encrypted inputs that do not open with the empty user password. |
173
+
174
+ With one page per file, `%d` is the original page number, zero-padded to the width of the last page
175
+ number (`page-07.pdf` in a 12-page file). With `pagesPerFile > 1`, `%d` is the 1-based chunk number,
176
+ zero-padded to the width of the chunk count; the last chunk may be short. Existing files are
177
+ replaced; each file is written atomically, one after another. A failure part-way leaves the files
178
+ already written. `splitPages` resolves with nothing.
179
+
180
+ ### `pageCount(options): Promise<number>`
181
+
182
+ `{ input, password? }`. Counts pages by walking the page tree.
183
+
184
+ ### Errors
185
+
186
+ Every promise rejects with `QpdfError`, which has a `code` and, for native failures, a `cause`:
187
+
188
+ - `INVALID_ARGUMENT`: the request was rejected before any output was written (wrong type, empty path,
189
+ no inputs, bad page range syntax or page 0, missing or repeated `%d`, `output` equal to an input,
190
+ use after `close()`).
191
+ - `OPERATION_FAILED`: qpdf could not do the work (missing or unreadable input, not a PDF, page out of
192
+ bounds, wrong password, unwritable output directory). Messages name the operation and the paths
193
+ involved; passwords are never put in messages.
194
+
195
+ Option objects are validated at run time, so untyped JavaScript gets the same errors. No C++
196
+ exception ever reaches JavaScript: the core converts everything qpdf throws into one error type at
197
+ its boundary, and the bindings turn that into a rejected promise (Node) or a JavaScript `Error`
198
+ with the same `code` (WebAssembly).
199
+
200
+ ## Building from source
201
+
202
+ Developed and verified on macOS arm64 (Apple Clang 21, CMake 3.29.5, Node 24.14). Linux and Windows
203
+ builds are done by the release workflow (see [Releasing](#releasing)).
204
+
205
+ Requirements: Node.js 20 or newer, [pnpm](https://pnpm.io) 10, [CMake](https://cmake.org) 3.20 or
206
+ newer, a C++20 compiler, and network access at configure time
207
+ (CMake fetches the pinned sources below; for offline builds pass
208
+ `-DFETCHCONTENT_SOURCE_DIR_QPDF=<dir>` and `-DFETCHCONTENT_SOURCE_DIR_ZLIB=<dir>` pointing at
209
+ checkouts of the pinned commits; libjpeg-turbo is fetched by a nested build and has no such override).
210
+
211
+ ```sh
212
+ pnpm install
213
+ pnpm build # native addon (cmake-js, Release) + TypeScript -> packages/node/dist
214
+ pnpm test # Node tests against the built addon
215
+ pnpm check # prettier --check, tsc --noEmit
216
+ pnpm format # prettier --write
217
+ ```
218
+
219
+ `pnpm --filter qpdf-node build:native:debug` builds an unoptimized addon. The addon is written to
220
+ `packages/node/build/Release/qpdf_node.node`; the first build compiles qpdf and takes a few minutes.
221
+ It only links the system C++ runtime and libc.
222
+
223
+ ### Pinned dependencies
224
+
225
+ All are fetched by CMake (`cmake/ThirdParty.cmake`) at a full commit hash, so a moved tag cannot
226
+ change a build:
227
+
228
+ | Dependency | Version | Commit |
229
+ | ------------- | ------- | ------------------------------------------ |
230
+ | qpdf | 12.4.2 | `4eba95899886e851cc41d76886483b347612f2a8` |
231
+ | zlib | 1.3.1 | `51b7f2abdade71cd9bb0e7a373ef2610ec6f9daf` |
232
+ | libjpeg-turbo | 3.1.4.1 | `9217719d3a58633923b096af4c1d50d304768a64` |
233
+
234
+ qpdf is built with its own crypto code (no OpenSSL or GnuTLS) and with zlib and libjpeg-turbo built
235
+ from the sources above rather than found on the system, so native and WebAssembly builds link the
236
+ same versions. To bump qpdf, change the commit and version comment in `cmake/ThirdParty.cmake`, then
237
+ rebuild, rerun the tests, and regenerate the notices (`node scripts/generate-third-party-notices.mjs`).
238
+
239
+ ### WebAssembly build
240
+
241
+ Needs the [Emscripten SDK](https://emscripten.org/docs/getting_started/downloads.html) (tested with
242
+ emcc 7.0.0). No `wasm-pack`, no Rust.
243
+
244
+ ```sh
245
+ source /path/to/emsdk/emsdk_env.sh
246
+ pnpm build:wasm # emcmake cmake -S . -B build/wasm ... && cmake --build build/wasm --target qpdf_wasm
247
+ pnpm test:wasm # runs native/wasm/smoke-test.mjs against build/wasm/qpdf-core.mjs under Node.js
248
+ ```
249
+
250
+ Output: `build/wasm/qpdf-core.mjs` (ES module, `createQpdfCore()`) and `build/wasm/qpdf-core.wasm`
251
+ (about 1.3 MB). It uses native WebAssembly exceptions (`-fwasm-exceptions`) and a 2 MB stack.
252
+
253
+ ```js
254
+ import createQpdfCore from "./qpdf-core.mjs";
255
+ const core = await createQpdfCore();
256
+ const pdf = core.openPdf(uint8Array); // sync; throws Error with .code on failure
257
+ pdf.pageCount;
258
+ const bytes = pdf.extract([3, 1, 2]); // Uint8Array, a copy out of WebAssembly memory
259
+ pdf.close();
260
+ ```
261
+
262
+ The WebAssembly API is **synchronous and in memory**: `openPdf(Uint8Array)`, `pageCount`,
263
+ `extract(pages)`, `close()`, `qpdfVersion()`. It has no file-system operations (`merge`,
264
+ `splitPages`, path `pageCount` are Node-only) and no password option yet. Because a large document
265
+ blocks while it is parsed or written, **run it in a Web Worker**. `native/wasm/qpdf-worker.mjs` is a
266
+ ready-made worker with a small `postMessage` protocol that transfers PDF bytes instead of copying
267
+ them; put `qpdf-core.mjs` and `qpdf-core.wasm` next to it and start it with
268
+ `new Worker(new URL("./qpdf-worker.mjs", import.meta.url), { type: "module" })` (protocol in the
269
+ file's header comment).
270
+
271
+ **Verification status:** the WebAssembly module was built and its smoke test passed under Node.js.
272
+ It has not been run in a browser or a Web Worker, and `qpdf-worker.mjs` has not been run at all.
273
+ It is **not published to npm**: the release workflow builds it (`wasm-build` job), runs the Node.js
274
+ smoke test and uploads `qpdf-core.mjs`, `qpdf-core.wasm` and `qpdf-worker.mjs` as the
275
+ `qpdf-wasm-build` workflow artifact. Nothing in `qpdf-node` depends on it, and the publish job does
276
+ not wait for it. A separate package (for example `qpdf-node-wasm`) should only be added after it is
277
+ verified in a browser.
278
+
279
+ ## Releasing
280
+
281
+ Six packages, all at the same version: the five platform packages of the
282
+ [table above](#platform-support) and the root `qpdf-node`. The root lists every platform package in
283
+ `optionalDependencies` at that exact version; npm installs only the one whose `os`, `cpu` and `libc`
284
+ fields match the machine. The root contains no binary, and each platform package contains one
285
+ `qpdf_node.node`, `LICENSE` and `THIRD_PARTY_NOTICES.md` (qpdf's Apache-2.0 license and notices).
286
+
287
+ The workspace manifest `packages/node/package.json` is `private` and does not list the platform
288
+ packages (they are not on the registry before a release, so `pnpm install --frozen-lockfile` could not
289
+ resolve them). Published packages are instead staged by checked-in scripts into `build/npm/`:
290
+
291
+ | Command | What it does |
292
+ | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
293
+ | `pnpm verify:release [--tag vX.Y.Z]` | Checks that package version, `CMakeLists.txt` version, the tag, the repository URL, the root scripts and the workflow's runner list agree. |
294
+ | `pnpm stage:addon [--target T] [--addon F] [--out D]` | Copies a built addon to `D/qpdf_node.<T>.node` (the CI artifact name; defaults: this machine, built addon, `build/addons`). |
295
+ | `pnpm package:platform --all --addons D [--out build/npm]` | Stages all five `qpdf-node-<T>` packages from `D/qpdf_node.<T>.node`; fails if one is missing. `--target T [--addon F]` stages one. |
296
+ | `pnpm --filter qpdf-node run build:ts && pnpm package:root` | Stages `qpdf-node` (compiled JS, declarations, license files, `optionalDependencies`). It contains no binary. |
297
+ | `pnpm smoke:packages --root DIR --platform DIR` | Packs the root and one platform package, installs both into an empty project with no `build/`, runs a PDF operation and checks the addon was loaded from the platform package. |
298
+ | `pnpm publish:packages [--dir build/npm] [--dry-run]` | Publishes the five platform packages first and `qpdf-node` last; skips versions already on the registry. |
299
+
300
+ To cut a release: bump `version` in `packages/node/package.json` **and** `project(... VERSION ...)` in
301
+ `CMakeLists.txt`, merge, then push the tag `vX.Y.Z`. The workflow `release.yml` then:
302
+
303
+ 1. `prepare`: `pnpm check` and `verify:release`.
304
+ 2. `build-native` (one job per platform, in parallel): `pnpm build`, `pnpm test` against the built
305
+ addon, then uploads the addon as `qpdf_node.<target>.node` (artifact `addon-<target>`).
306
+ 3. `package`: downloads all five addons, builds the TypeScript and stages the five platform packages
307
+ and the root package (artifact `npm-packages`).
308
+ 4. `test-artifacts` (per platform, Node.js 20): downloads the packages, packs the root and that
309
+ platform's package, installs both into an empty project and runs `smoke:packages`. This proves the
310
+ package layout and the loader on each supported runner, not just the build.
311
+ 5. `publish`: publishes the five platform packages, then `qpdf-node`. A failure in any earlier job
312
+ stops the release before anything is published. If a publish fails part-way, fix the cause and
313
+ re-run the job: versions already published are skipped. Versions with a prerelease suffix
314
+ (`0.3.0-rc.1`) are published under the `next` dist-tag.
315
+ 6. `wasm-build` runs independently (see [WebAssembly build](#webassembly-build)); it is not part of
316
+ the npm packages.
317
+
318
+ Running the workflow by hand (Actions, "Run workflow") does steps 1-4 and `npm publish --dry-run` of
319
+ all six packages. It publishes nothing and needs no npm credentials.
320
+
321
+ The staged `repository`, `homepage` and `bugs` fields point at `taoche/qpdf-node`
322
+ (`QPDF_NODE_REPOSITORY_URL` or `GITHUB_REPOSITORY` overrides `repository`). npm provenance requires the
323
+ published `repository` to match the repository that runs the workflow.
324
+
325
+ ### What was and was not validated locally
326
+
327
+ Validated on macOS arm64: `pnpm install --frozen-lockfile`, `pnpm check`, `pnpm build`, `pnpm test`,
328
+ `verify:release`, `stage:addon`, `package:platform --all`, `package:root`, `publish:packages --dry-run`
329
+ (all six packages), and `smoke:packages` (root and `qpdf-node-darwin-arm64` tarballs installed into an
330
+ empty project; the addon loads from `node_modules/qpdf-node-darwin-arm64/qpdf_node.node`). Installing
331
+ only the root tarball, with its five platform packages redirected to local tarballs, installed just the
332
+ darwin-arm64 one, which shows npm's `os`/`cpu` selection. Locally the other four addon files were
333
+ stand-in copies of the arm64 addon, so only the darwin-arm64 selection was exercised end to end. The
334
+ loader's choice for the other targets and for musl is covered by unit tests with a fake file system.
335
+
336
+ **Not validated locally:** the Linux, Windows and macOS x64 builds, the per-runner tarball smoke
337
+ tests, and the WebAssembly job. An attempt to build the Linux arm64 addon in an `ubuntu:22.04` Docker
338
+ container was abandoned: cmake-js stopped with "C++ Compiler toolset is not available" because only
339
+ `g++-12` (no plain `g++`) was installed there. GitHub's Ubuntu runners ship `g++`, and the workflow
340
+ additionally installs `g++-12` and exports `CC` / `CXX`, but whether cmake-js accepts that
341
+ combination there is unverified. The first workflow run is the real test of these jobs; use the
342
+ manual "Run workflow" dry run before pushing a tag.
343
+
344
+ ### npm credentials
345
+
346
+ All five platform packages and `qpdf-node` must be publishable by the workflow. Two options:
347
+
348
+ - **Token (needed for the first publish of the platform packages).** The platform package names do not
349
+ exist yet, so the token must be allowed to create new packages (for example a granular token
350
+ with read/write on all packages, which you can narrow afterwards) and also publish `qpdf-node`.
351
+ Store it as the repository secret `NPM_TOKEN`. The workflow passes it only to the publish step as
352
+ `NODE_AUTH_TOKEN`; npm does not print it. Use an account with 2FA enforced for publishing
353
+ "authorization only", or an automation token, since CI cannot enter a one-time password.
354
+ - **Trusted publishing (recommended after the first release).** In each package's settings on
355
+ npmjs.com, add a GitHub Actions trusted publisher: this repository and workflow file `release.yml`.
356
+ Trusted publishers can only be added to packages that already exist, hence the token for the first
357
+ release. The publish job has `id-token: write` and runs Node.js 24 (npm 11.5.1 or newer, as
358
+ trusted publishing requires); once configured, delete `NPM_TOKEN`. On tag pushes the scripts pass
359
+ `--provenance`.
360
+
361
+ The workflow does not create a GitHub release and uses no other secrets.
362
+
363
+ ## Behavior and limitations
364
+
365
+ - Outputs are always unencrypted, even when the input was encrypted (qpdf decrypts on load).
366
+ - No linearization and no output encryption.
367
+ - Output is deterministic (qpdf's deterministic `/ID`), written with streams preserved and a newline
368
+ before `endstream`.
369
+ - qpdf repairs damaged cross-reference data when it can. Its warnings are discarded.
370
+ - Inputs are read lazily from disk by qpdf (not memory-mapped by this package): do not modify an input
371
+ file while an operation on it runs.
372
+ - `splitPages` writes files one after another (not in parallel). `merge` and each split file are
373
+ written atomically.
374
+ - One libuv thread-pool thread is used per operation (`UV_THREADPOOL_SIZE`, default 4).
375
+ - Not covered by tests: encrypted inputs and passwords (needs an encrypted fixture), and very large
376
+ files. The tests build their small PDFs in memory; when a `qpdf` executable is on `PATH`, tests also
377
+ run `qpdf --check` on outputs (not required).
378
+
379
+ ## Changes from pdq-node
380
+
381
+ - The package is now `qpdf-node` and the error class `QpdfError` (codes unchanged). The Rust
382
+ workspace, napi-rs, and the pdq crate are gone; the Artistic-2.0 license text went with pdq.
383
+ - `openPdf` no longer uses temporary files: it keeps one parsed in-memory qpdf document. Repeated
384
+ pages in `extract` are still rejected (the earlier limitation), although qpdf could write them.
385
+ - `merge` page ranges are the same syntax, now parsed by this package (`native/core/page_range.cc`);
386
+ `z` and `r1` both mean the last page. A page may now be repeated in a `merge` range.
387
+ - Streams are no longer re-encoded differently from the source; output bytes differ from pdq's.
388
+ - Damaged-file repair is qpdf's, and its warnings are silent instead of printed to stderr.
389
+ - `splitPages` is sequential and per-file atomic.
390
+ - Output `merge` of an input with no pages is skipped; if nothing remains it rejects with
391
+ `OPERATION_FAILED`.
392
+
393
+ ## Repository layout
394
+
395
+ ```
396
+ CMakeLists.txt Root build: pinned dependencies, core, and the addon / WebAssembly targets
397
+ cmake/ThirdParty.cmake Pinned qpdf, zlib, libjpeg-turbo
398
+ native/core/ Shared C++ core (no Node or Emscripten dependency)
399
+ pdf_core.hh Public core API: Document, PageRange, assemblePages, Error
400
+ document.cc qpdf-backed open / extract / assemble, exception boundary
401
+ page_range.cc Page range parser
402
+ file_operations.{hh,cc} Path-based merge / splitPages / pageCount (not in WebAssembly)
403
+ native/node/ N-API addon (node-addon-api): addon.cc, CMakeLists.txt
404
+ native/wasm/ Emscripten module: wasm_bindings.cc, qpdf-worker.mjs, smoke-test.mjs
405
+ packages/node/ The "qpdf-node" TypeScript wrapper (src/native-loader.ts finds the addon) and tests
406
+ scripts/ generate-third-party-notices.mjs; release scripts (release-lib, stage-addon,
407
+ package-platform, package-root, smoke-test-packages, verify-release,
408
+ publish-packages)
409
+ .github/workflows/ release.yml: build the five addons, stage, test and publish six packages
410
+ ```
411
+
412
+ ## License
413
+
414
+ The source in this repository is under the [MIT License](LICENSE). The compiled addon and
415
+ WebAssembly module statically link [qpdf](https://github.com/qpdf/qpdf) (Apache License 2.0), zlib,
416
+ and libjpeg-turbo; their licenses are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). The
417
+ package is licensed `MIT AND Apache-2.0` as a whole. This project is not affiliated with the qpdf
418
+ authors.