@reportwright/pdf 0.1.0-beta.1 → 0.1.0-beta.10

package/examples/accessible.mjs

@@ -0,0 +1,28 @@
+// PDF/UA-1 and PDF/A-2a in one file: a structure tree (headings, a list, a figure), artifacts for decoration.
+//
+//   node examples/accessible.mjs font.ttf [out.pdf]
+import fs from 'node:fs';
+import { createPdf } from '../dist/index.js';
+
+const [fontFile, out = 'accessible.pdf'] = process.argv.slice(2);
+if (!fontFile) { console.error('node examples/accessible.mjs font.ttf [out.pdf]'); process.exit(2); }
+const pdf = createPdf(fs.createWriteStream(out), {
+  title: 'Leave policy', tagged: { lang: 'en-GB' },               // PDF/UA-1: a title and tags are required
+  pdfa: { part: 2, conformance: 'a' },                            // PDF/A-2a: archival and tagged
+});
+const font = await pdf.embedFont(fs.readFileSync(fontFile));
+const page = pdf.addPage();
+page.artifact({ type: 'Pagination', subtype: 'Header' }, () => page.text('Example Ltd · HR policies', { x: 40, y: 20, font, size: 8 }));
+page.tag('H1', () => page.text('Leave policy', { x: 40, y: 50, font, size: 22 }));
+page.tag('P', () => page.textBox('Every employee gets the following leave each calendar year.', { x: 40, y: 90, width: 500, font }));
+page.tag('L', () => ['18 days of annual leave', '12 days of sick leave'].forEach((s, i) => page.tag('LI', () => {
+  page.tag('Lbl', () => page.text('•', { x: 40, y: 120 + i * 18, font }));
+  page.tag('LBody', () => page.text(s, { x: 56, y: 120 + i * 18, font }));
+})), { listNumbering: 'Disc' });
+page.figure({ alt: 'Bar chart: annual leave 18 days, sick leave 12 days' }, () => {
+  page.fill(page.path().rect(40, 180, 180, 16), { fill: '#1f4e79' });
+  page.fill(page.path().rect(40, 200, 120, 16), { fill: '#5b9bd5' });
+});
+await page.end();
+const { warnings } = await pdf.end();
+console.log(`wrote ${out}: PDF/UA-1 + PDF/A-2a`, warnings.length ? warnings : '');

package/examples/bulk.mjs

@@ -0,0 +1,19 @@
+// Many files at once: extract text and encrypt in worker threads; a broken file fails alone.
+//
+//   node examples/bulk.mjs [outDir]   writes locked-1.pdf … locked-N.pdf
+import fs from 'node:fs';
+import path from 'node:path';
+import { toBytes, bulk } from '../dist/index.js';
+
+const dir = process.argv[2] ?? '.';
+const make = (label) => toBytes(async (pdf) => {
+  const p = pdf.addPage(); p.text(`${label}: total due 1,250.00`, { x: 40, y: 40, font: pdf.standardFont('Helvetica'), size: 14 }); await p.end();
+});
+const files = [await make('Invoice 1'), new Uint8Array([0x25, 0x50]), await make('Invoice 3')]; // the second is not a PDF
+
+const texts = await bulk(files, 'extractText', { workers: 2 });
+texts.forEach((r, i) => console.log(i + 1, r.ok ? r.value : `failed: ${r.error.code} ${r.error.message}`));
+
+const locked = await bulk(files, 'encrypt', { workers: 2, encrypt: { userPassword: 'open me', ownerPassword: 'full access' } });
+locked.forEach((r, i) => { if (r.ok) fs.writeFileSync(path.join(dir, `locked-${i + 1}.pdf`), r.value); });
+console.log(`encrypted ${locked.filter((r) => r.ok).length} of ${files.length}`);

package/examples/encrypt.mjs

@@ -0,0 +1,23 @@
+// AES-256 password protection with permissions, then reading it back with the password.
+//
+//   node examples/encrypt.mjs [out.pdf]
+import fs from 'node:fs';
+import { toBytes, loadPdf } from '../dist/index.js';
+
+const out = process.argv[2] ?? 'encrypted.pdf';
+const bytes = await toBytes(async (pdf) => {
+  const page = pdf.addPage();
+  page.text('Salary statement: confidential', { x: 40, y: 40, font: pdf.standardFont('Helvetica'), size: 14 });
+  await page.end();
+}, {
+  title: 'Salary statement',
+  encrypt: {
+    userPassword: 'open me',                 // asked when the file opens ('' opens without a prompt)
+    ownerPassword: 'full access',            // lifts the permissions; left out: random
+    algorithm: 'aes-256',                    // or 'aes-128' for very old readers
+    permissions: { print: true, copy: false, modify: false },   // each defaults to true
+  },
+});
+fs.writeFileSync(out, bytes);
+const doc = await loadPdf(bytes, { password: 'open me' });
+console.log(`wrote ${out}: ${doc.encryption.algorithm}, copy allowed: ${doc.encryption.permissions.copy}; text: ${doc.extractText().trim()}`);

package/examples/fill-form.mjs

@@ -0,0 +1,33 @@
+// Forms: create a fillable PDF, fill it after loading, and flatten it into a plain PDF.
+//
+//   node examples/fill-form.mjs [outDir]   writes form.pdf, filled.pdf, flattened.pdf
+import fs from 'node:fs';
+import path from 'node:path';
+import { toBytes, loadPdf } from '../dist/index.js';
+
+const dir = process.argv[2] ?? '.';
+// 1. Create: every field gets its appearance streams, so every viewer shows the same thing.
+const form = await toBytes(async (pdf) => {
+  const font = pdf.standardFont('Helvetica');
+  const page = pdf.addPage();
+  page.text('Leave request', { x: 40, y: 40, font: pdf.standardFont('Helvetica-Bold'), size: 18 });
+  const f = pdf.form;
+  f.textField('name', { page, x: 40, y: 80, width: 240, height: 22, font, tooltip: 'Full name', required: true });
+  f.comboBox('type', { page, x: 40, y: 115, width: 160, height: 22, font, options: ['Annual', 'Sick', 'Unpaid'], value: 'Annual', tooltip: 'Leave type' });
+  f.checkbox('approved', { page, x: 40, y: 150, width: 14, height: 14, tooltip: 'Approved by manager' });
+  page.text('Approved', { x: 60, y: 151, font, size: 11 });
+  await page.end();
+});
+fs.writeFileSync(path.join(dir, 'form.pdf'), form);
+
+// 2. Fill: values by full field name; the appearances are drawn again by the writer.
+const doc = await loadPdf(form);
+console.log('fields:', doc.fields.map((x) => `${x.name} (${x.type})`).join(', '));
+doc.fill({ name: 'Aanya Sharma', type: 'Sick', approved: true });
+fs.writeFileSync(path.join(dir, 'filled.pdf'), (await doc.save()).bytes);
+
+// 3. Flatten: the fields become page content; no AcroForm is left.
+const flat = (await loadPdf(form)).fill({ name: 'Aanya Sharma', type: 'Sick', approved: true }).flatten();
+const flattened = (await flat.save()).bytes;
+fs.writeFileSync(path.join(dir, 'flattened.pdf'), flattened);
+console.log('flattened text:', (await loadPdf(flattened)).page(0).extractText().replace(/\s+/g, ' '));

package/examples/indic.mjs

@@ -0,0 +1,20 @@
+// Hindi (Devanagari) text shaped by HarfBuzz: conjuncts and reordered matras drawn right, copied text in logical order.
+//
+//   npm i harfbuzzjs
+//   node examples/indic.mjs NotoSansDevanagari-Regular.ttf [out.pdf]
+import fs from 'node:fs';
+import { createPdf } from '../dist/index.js';
+import { harfbuzzShaper } from './harfbuzz-shaper.mjs';
+
+const [fontFile, out = 'indic.pdf'] = process.argv.slice(2);
+if (!fontFile) { console.error('node examples/indic.mjs NotoSansDevanagari-Regular.ttf [out.pdf]'); process.exit(2); }
+const pdf = createPdf(fs.createWriteStream(out), { title: 'हिन्दी' });
+const bytes = fs.readFileSync(fontFile);
+const hindi = await pdf.embedFont(bytes, { shaper: harfbuzzShaper(bytes) });
+const latin = pdf.standardFont('Helvetica');
+const page = pdf.addPage();
+page.text('किताब हिन्दी क्षत्रिय', { x: 40, y: 40, font: hindi, size: 24 });
+page.textBox('Mixed text: इस किताब में हिन्दी और English दोनों हैं।', { x: 40, y: 90, width: 400, font: hindi, fallback: [latin], size: 14 });
+await page.end();
+const { warnings } = await pdf.end();
+console.log(`wrote ${out}`, warnings.length ? warnings : '');

package/examples/invoice-facturx.mjs

@@ -0,0 +1,40 @@
+// A self-contained Factur-X invoice: a tagged PDF/A-3a page drawn from the same data as the CII XML embedded in it.
+// (examples/factur-x.mjs does the same from an XML file you already have.)
+//
+//   node examples/invoice-facturx.mjs font.ttf [out.pdf]     any TrueType font, e.g. Inter-Regular.ttf
+//
+// The XML below is a short EN 16931 skeleton for the example. pdf.facturX checks its root, profile ID and that it has
+// no DOCTYPE or entities; it does not validate the invoice: run the Factur-X XSD and Schematron on real invoices.
+import fs from 'node:fs';
+import { createPdf } from '../dist/index.js';
+
+const [fontFile, out = 'invoice-facturx.pdf'] = process.argv.slice(2);
+if (!fontFile) { console.error('node examples/invoice-facturx.mjs font.ttf [out.pdf]'); process.exit(2); }
+const inv = { number: 'INV-2026-001', date: '20261009', seller: 'Example Ltd', buyer: 'Acme GmbH', currency: 'EUR',
+  lines: [['Consulting, 10 h', '1000.00'], ['Licence', '250.00']], net: '1250.00', vat: '237.50', total: '1487.50' };
+const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<rsm:CrossIndustryInvoice xmlns:rsm="urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100" xmlns:ram="urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100" xmlns:udt="urn:un:unece:uncefact:data:standard:UnqualifiedDataType:100">
+<rsm:ExchangedDocumentContext><ram:GuidelineSpecifiedDocumentContextParameter><ram:ID>urn:cen.eu:en16931:2017</ram:ID></ram:GuidelineSpecifiedDocumentContextParameter></rsm:ExchangedDocumentContext>
+<rsm:ExchangedDocument><ram:ID>${inv.number}</ram:ID><ram:TypeCode>380</ram:TypeCode><ram:IssueDateTime><udt:DateTimeString format="102">${inv.date}</udt:DateTimeString></ram:IssueDateTime></rsm:ExchangedDocument>
+<rsm:SupplyChainTradeTransaction><ram:ApplicableHeaderTradeAgreement><ram:SellerTradeParty><ram:Name>${inv.seller}</ram:Name></ram:SellerTradeParty><ram:BuyerTradeParty><ram:Name>${inv.buyer}</ram:Name></ram:BuyerTradeParty></ram:ApplicableHeaderTradeAgreement>
+<ram:ApplicableHeaderTradeSettlement><ram:InvoiceCurrencyCode>${inv.currency}</ram:InvoiceCurrencyCode><ram:SpecifiedTradeSettlementHeaderMonetarySummation><ram:TaxBasisTotalAmount>${inv.net}</ram:TaxBasisTotalAmount><ram:TaxTotalAmount currencyID="${inv.currency}">${inv.vat}</ram:TaxTotalAmount><ram:GrandTotalAmount>${inv.total}</ram:GrandTotalAmount><ram:DuePayableAmount>${inv.total}</ram:DuePayableAmount></ram:SpecifiedTradeSettlementHeaderMonetarySummation></ram:ApplicableHeaderTradeSettlement></rsm:SupplyChainTradeTransaction>
+</rsm:CrossIndustryInvoice>`;
+
+const pdf = createPdf(fs.createWriteStream(out), {
+  title: `Invoice ${inv.number}`, author: inv.seller, pdfa: { part: 3, conformance: 'a' }, tagged: { lang: 'en' },
+});
+const font = await pdf.embedFont(fs.readFileSync(fontFile));   // PDF/A: every font embedded
+const page = pdf.addPage();
+const t = (s, x, y, size = 11) => page.text(s, { x, y, font, size });
+page.tag('H1', () => t(`Invoice ${inv.number}`, 56, 56, 22));
+page.tag('P', () => t(`From ${inv.seller} to ${inv.buyer}`, 56, 96));
+page.tag('Table', () => {
+  page.tag('TR', () => ['Item', `Amount (${inv.currency})`].forEach((h, i) => page.tag('TH', () => t(h, 56 + i * 300, 140), { scope: 'Column', id: `h${i}` })));
+  [...inv.lines, ['Net', inv.net], ['VAT 19%', inv.vat], ['Total', inv.total]].forEach(([item, amount], r) =>
+    page.tag('TR', () => [item, amount].forEach((v, i) => page.tag('TD', () => t(v, 56 + i * 300, 162 + r * 20), { headers: [`h${i}`] }))));
+});
+page.stroke(page.path().moveTo(56, 156).lineTo(540, 156), { width: 0.5 });   // outside any tag: an artifact
+await pdf.facturX(new TextEncoder().encode(xml), { profile: 'EN 16931' });
+await page.end();
+const { warnings } = await pdf.end();
+console.log(`wrote ${out}: PDF/A-3a + factur-x.xml (EN 16931)`, warnings.length ? warnings : '');

package/examples/merge-split.mjs

@@ -0,0 +1,29 @@
+// Read and modify: merge, split, extract text, and an incremental update that keeps the original bytes.
+//
+//   node examples/merge-split.mjs [outDir]   writes merged.pdf, page-1.pdf … page-N.pdf, updated.pdf
+import fs from 'node:fs';
+import path from 'node:path';
+import { toBytes, loadPdf, mergePdfs } from '../dist/index.js';
+
+const dir = process.argv[2] ?? '.';
+const make = (label, n) => toBytes(async (pdf) => {
+  const font = pdf.standardFont('Helvetica');
+  for (let i = 1; i <= n; i++) { const p = pdf.addPage(); p.text(`${label}, page ${i}`, { x: 40, y: 40, font, size: 16 }); await p.end(); }
+}, { title: label });
+const a = await loadPdf(await make('Contract', 2)), b = await loadPdf(await make('Annexure', 1));
+
+const merged = await mergePdfs([a, b]);                         // a new file, every page of each
+fs.writeFileSync(path.join(dir, 'merged.pdf'), merged.bytes);
+const all = await loadPdf(merged.bytes);
+console.log(`merged: ${all.pageCount} pages; text:`, all.extractText().split('\f').map((t) => t.trim()));
+
+for (let i = 0; i < all.pageCount; i++) {                       // split: a fork per page
+  const { bytes } = await all.fork().reorder([i]).save();
+  fs.writeFileSync(path.join(dir, `page-${i + 1}.pdf`), bytes);
+}
+
+const doc = await loadPdf(merged.bytes);
+doc.setInfo({ title: 'Contract (reviewed)' });
+const update = await doc.saveIncremental();                     // original bytes + an appended update
+fs.writeFileSync(path.join(dir, 'updated.pdf'), update.bytes);
+console.log(`split into ${all.pageCount} files; update appended ${update.size - merged.bytes.length} bytes`);

package/examples/sign.mjs

@@ -0,0 +1,29 @@
+// PAdES B-B signature while the PDF streams out, then a second signature appended with saveIncremental.
+//
+//   openssl req -x509 -newkey rsa:2048 -nodes -keyout key.pem -out cert.pem -days 365 -subj "/CN=Example Signer"
+//   node examples/sign.mjs key.pem cert.pem [out.pdf]
+// For a real signature use a certificate from a CA your readers trust, and a timestamp (RFC 3161) for PAdES B-T.
+import fs from 'node:fs';
+import { createPdf, loadPdf, nodeSigner } from '../dist/index.js';
+
+const [keyFile, certFile, out = 'signed.pdf'] = process.argv.slice(2);
+if (!certFile) { console.error('node examples/sign.mjs key.pem cert.pem [out.pdf]'); process.exit(2); }
+const signer = nodeSigner({ key: fs.readFileSync(keyFile, 'utf8'), certs: fs.readFileSync(certFile, 'utf8') });
+
+const chunks = [];
+const pdf = createPdf({ write: (b) => { chunks.push(Buffer.from(b)); } }, { title: 'Offer letter', sign: true });
+const font = pdf.standardFont('Helvetica');
+const page = pdf.addPage();
+page.text('Offer letter', { x: 40, y: 40, font, size: 18 });
+const hr = pdf.form.signature('hr', { page, x: 40, y: 700, width: 200, height: 40, tooltip: 'HR signature' });
+pdf.form.signature('candidate', { page, x: 300, y: 700, width: 200, height: 40, tooltip: 'Candidate signature' });
+await pdf.sign(hr, { signer, reason: 'Issued', location: 'Bengaluru', name: 'HR', certify: 2 });   // DocMDP P=2: signing allowed later
+await page.end();
+await pdf.end();                                                 // the signer runs here, on the streamed bytes' digest
+
+// Countersign: appends an update, so the first signature stays valid.
+const doc = await loadPdf(Buffer.concat(chunks));
+const { bytes } = await doc.saveIncremental({ sign: { field: 'candidate', signer, reason: 'Accepted' } });
+fs.writeFileSync(out, bytes);
+const signatures = (await loadPdf(bytes)).signatures;
+console.log(`wrote ${out}:`, signatures.map((s) => `${s.field} (revision ${s.revision}, covers the whole file: ${s.coversWholeFile})`).join('; '));

package/examples/write.mjs

@@ -0,0 +1,53 @@
+// Text, an image, a table drawn with paths, a link and bookmarks, using the standard fonts (no files needed).
+//
+//   node examples/write.mjs [out.pdf]
+import fs from 'node:fs';
+import zlib from 'node:zlib';
+import { createPdf } from '../dist/index.js';
+
+const out = process.argv[2] ?? 'write.pdf';
+const pdf = createPdf(fs.createWriteStream(out), { title: 'Quarterly report', author: 'Example Ltd' });
+const regular = pdf.standardFont('Helvetica'), bold = pdf.standardFont('Helvetica-Bold');
+
+// A 32 x 32 RGBA PNG made here so the example needs no image file (use fs.readFileSync('logo.png') in real code).
+function png(w, h, pixel) {
+  const chunk = (type, data) => {
+    const b = Buffer.alloc(12 + data.length); b.writeUInt32BE(data.length, 0); b.write(type, 4, 'latin1'); data.copy(b, 8);
+    b.writeUInt32BE(zlib.crc32(b.subarray(4, 8 + data.length)), 8 + data.length); return b;
+  };
+  const ihdr = Buffer.alloc(13); ihdr.writeUInt32BE(w, 0); ihdr.writeUInt32BE(h, 4); ihdr.set([8, 6, 0, 0, 0], 8);
+  const raw = Buffer.alloc(h * (1 + w * 4));
+  for (let y = 0; y < h; y++) for (let x = 0; x < w; x++) raw.set(pixel(x, y), y * (1 + w * 4) + 1 + x * 4);
+  return Buffer.concat([Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]), chunk('IHDR', ihdr), chunk('IDAT', zlib.deflateSync(raw)), chunk('IEND', Buffer.alloc(0))]);
+}
+const logo = await pdf.embedImage(png(32, 32, (x, y) => [31, 78, 121, (x - 16) ** 2 + (y - 16) ** 2 < 256 ? 255 : 0]));
+
+const page = pdf.addPage();                                     // A4; origin top-left, y down, in points
+page.image(logo, { x: 40, y: 40, width: 32 });
+page.text('Quarterly report', { x: 84, y: 44, font: bold, size: 22, color: '#1f4e79' });
+const box = page.textBox('Revenue grew in every region. The table below is drawn with paths: a filled header row, ' +
+  'rules between rows and right-aligned numbers.', { x: 40, y: 90, width: 515, font: regular, size: 11, align: 'justify' });
+
+// A table from paths: no table primitive is needed.
+const rows = [['Region', 'Q1', 'Q2'], ['North', '1,204', '1,390'], ['South', '980', '1,122'], ['West', '1,510', '1,488']];
+const cols = [40, 300, 430], right = 555, rowH = 22, top = 100 + box.height;
+page.fill(page.path().rect(40, top, right - 40, rowH), { fill: '#1f4e79' });
+rows.forEach((r, i) => {
+  const y = top + i * rowH;
+  r.forEach((cell, c) => {
+    const font = i === 0 ? bold : regular, size = 11;
+    const x = c === 0 ? cols[c] + 6 : (cols[c + 1] ?? right) - 6 - font.widthOfText(cell, size);
+    page.text(cell, { x, y: y + 5, font, size, color: i === 0 ? '#ffffff' : 0 });
+  });
+  if (i > 0) page.stroke(page.path().moveTo(40, y + rowH).lineTo(right, y + rowH), { stroke: 0.75, width: 0.5 });
+});
+
+page.text('Read the full report online', { x: 40, y: top + rows.length * rowH + 20, font: regular, color: '#0645ad' });
+page.link(40, top + rows.length * rowH + 20, 160, 14, { url: 'https://example.com/report' });
+
+const p2 = pdf.addPage();
+p2.text('Appendix', { x: 40, y: 40, font: bold, size: 18 });
+pdf.outline([{ title: 'Quarterly report', page: 1 }, { title: 'Appendix', page: 2, level: 1 }]);
+await page.end(); await p2.end();
+const { pages, bytes, warnings } = await pdf.end();
+console.log(`wrote ${out}: ${pages} pages, ${bytes} bytes`, warnings.length ? warnings : '');

package/fflate.d.ts

@@ -0,0 +1,3 @@
+// @reportwright/pdf/fflate: the fflate (MIT) this package bundles, for a bundle that also uses fflate (the ReportWright
+// engine) to share one copy. Its types are fflate's own (npm i -D fflate@0.8.3 to have them).
+export * from 'fflate';

package/index.d.ts

@@ -64,6 +64,13 @@ export interface PdfOptions {
   creationDate?: Date;
   /** Flate-compress content, fonts, object streams (default true). */
   compress?: boolean;
+  /**
+   * The zlib level (0–9) the object streams (the small objects, packed together) and the cross-reference stream are
+   * compressed at. Unset: the object streams at 6 and the cross-reference stream by the bundled fflate at 6, as before
+   * beta.7. Set, both go through the platform's zlib (Node's) at that level: 9 makes the file a little smaller and
+   * slower. The same input and options give the same bytes.
+   */
+  objectStreamLevel?: number;
   /**
    * PDF/A: an output intent (sRGB, or outputIntent: your RGB or CMYK ICC output/monitor profile) and XMP
    * identification. Fonts must be embedded; device colour must match the intent (CMYK needs a CMYK intent, RGB an RGB one).
@@ -646,10 +653,11 @@ export interface FormScope {
 
 export interface Pdf {
   standardFont(name: StandardFontName): Font;
-  /** a TrueType or OpenType/CFF font; subset by default; shaper: text goes through it (complex scripts) */
-  embedFont(bytes: Uint8Array | ArrayBuffer, o?: { subset?: boolean | Subsetter; shaper?: Shaper }): Promise<Font>;
+  /** a TrueType or OpenType/CFF font; subset by default; shaper: text goes through it (complex scripts);
+   * textMapping: 'carrier' (default: Firefox, pdf.js, search) or 'actualText' (a shaped cluster's text only in its ActualText: MuPDF, AI pipelines) */
+  embedFont(bytes: Uint8Array | ArrayBuffer, o?: { subset?: boolean | Subsetter; shaper?: Shaper; textMapping?: 'carrier' | 'actualText' }): Promise<Font>;
   /** a JPEG or PNG, written now as an image XObject. colorSpace: an ICC colour space with the image's component count */
-  embedImage(bytes: Uint8Array | ArrayBuffer, o?: { colorSpace?: IccColorSpace; /** the decoded size a PNG with alpha or interlacing may have; default 64 MB */ maxDecodedBytes?: number }): Promise<Image>;
+  embedImage(bytes: Uint8Array | ArrayBuffer, o?: { colorSpace?: IccColorSpace; /** the decoded size a PNG with alpha or interlacing may have; default 64 MB */ maxDecodedBytes?: number; /** zlib level for a re-compressed PNG (alpha, interlacing): 'default' = 6, or 3 above 2 megapixels; 'fast' = 1; or 1–9 */ compression?: 'default' | 'fast' | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 }): Promise<Image>;
   /** a spot colour: its name and the device colour (gray, RGB, CMYK) shown for it at full tint. One definition per name */
   spotColor(name: string, alternate: number | string | readonly number[]): SpotColor;
   /** an ICC-based colour space from a gray, RGB or CMYK profile (its header is checked) */
@@ -845,3 +853,38 @@ export interface LoadedPdf {
 export function loadPdf(bytes: Uint8Array | ArrayBuffer, options?: LoadOptions): Promise<LoadedPdf>;
 /** every page of each document, in order, in a new file (the first one's catalog, with what the others bring) */
 export function mergePdfs(docs: LoadedPdf[], options?: SaveOptions): Promise<SaveResult & { bytes: Uint8Array }>;
+/** the tasks bulk() runs, by name (no functions cross to a worker) */
+export type BulkTask = 'extractText' | 'merge' | 'split' | 'encrypt';
+export const BULK_TASKS: readonly BulkTask[];
+/** what each task takes per item, and gives back */
+export interface BulkTaskTypes {
+  extractText: { input: Uint8Array | ArrayBuffer; value: string };
+  merge: { input: (Uint8Array | ArrayBuffer)[]; value: Uint8Array };
+  split: { input: Uint8Array | ArrayBuffer; value: Uint8Array[] };
+  encrypt: { input: Uint8Array | ArrayBuffer; value: Uint8Array };
+}
+export type BulkResult<V> = { ok: true; value: V } | { ok: false; error: { name: string; code?: string; message: string } };
+export interface BulkOptions {
+  /** worker threads (1 to 64); default os.availableParallelism() - 1 (at least 1). 1, or no node:worker_threads (browsers): one at a time, in this thread.
+   * Workers are kept warm (unref'd) for 2 s after a call, for the next; small files are sent several at a time */
+  workers?: number;
+  /** each worker's heap cap in MB (resourceLimits.maxOldGenerationSizeMb), 16 to 16384, default 512: an item past it fails with E_WORKER, alone */
+  memoryMb?: number;
+  /** loadPdf's options, for every input */
+  password?: string;
+  budget?: ReadBudget;
+  timeoutMs?: number;
+  /** the encrypt task's encryption */
+  encrypt?: EncryptOptions;
+  /** save()'s options for merge, split and encrypt */
+  save?: SaveOptions;
+  /** each item's result as it finishes (index in inputs) */
+  onResult?: (index: number, result: BulkResult<unknown>) => void;
+  /** each item's time limit in a worker, default 120000, at most 2147483647: past it the worker is ended, the item fails with E_TIMEOUT and the rest go on.
+   * With one input, workers: 1, or a host where workers resolve to 1 (2 CPUs), items run in the calling thread: no time limit and no heap cap apply there. */
+  itemTimeoutMs?: number;
+  /** stops the call: its workers are ended (not kept warm) and bulk rejects with the signal's reason (AbortSignal.timeout(ms) for a time limit) */
+  signal?: AbortSignal;
+}
+/** One named task over many inputs, in parallel worker threads (Node); results in input order, a failing item never stops the rest. */
+export function bulk<T extends BulkTask>(inputs: Iterable<BulkTaskTypes[T]['input']>, task: T, options?: BulkOptions): Promise<BulkResult<BulkTaskTypes[T]['value']>[]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reportwright/pdf",
-  "version": "0.1.0-beta.1",
+  "version": "0.1.0-beta.10",
   "description": "A streaming PDF writer for Node and browsers with no runtime dependencies: flat memory, PDF/A-1b to 3a, PDF/UA-1, Factur-X, embedded TrueType with Unicode text.",
   "type": "module",
   "license": "MIT",
@@ -12,10 +12,12 @@
   "publishConfig": { "access": "public" },
   "exports": {
     ".": { "types": "./index.d.ts", "default": "./dist/index.js" },
+    "./fflate": { "types": "./fflate.d.ts", "default": "./dist/fflate.js" },
+    "./examples/*": "./examples/*",
     "./package.json": "./package.json"
   },
   "types": "./index.d.ts",
-  "files": ["dist", "index.d.ts", "examples", "README.md", "LICENSE", "THIRD-PARTY-NOTICES.md"],
+  "files": ["dist", "index.d.ts", "fflate.d.ts", "examples", "README.md", "LICENSE", "THIRD-PARTY-NOTICES.md"],
   "engines": { "node": ">=20.16" },
   "sideEffects": false
 }