qpdf-node 0.0.0-stage → 0.2.0

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