pdf-lib (Cantoo Fork)

@cantoo/upng is a PNG and APNG encoder/decoder. It is a modular TypeScript port of the photopea/UPNG.js library, originally used by @pdf-lib/upng.

Key improvements over the original include:

• Performance: Uses fflate for compression instead of pako.
• Modularity: Provided as modular TypeScript modules (decode, encode, quantize, etc.) rather than a monolithic file.
• Packaging: Can be used as a standalone package or accessed via @cantoo/pdf-lib/upng if you are using the @cantoo/pdf-lib package.

Incremental modification allows you to update a PDF without rewriting the entire file structure. This is critical for tasks like digital signatures, where modifying the original byte structure would invalidate existing signatures.

There are two ways to handle this:

1. Automatic Incremental Update: Load the document with { forIncrementalUpdate: true }. When you call save(), pdf-lib automatically generates an incremental update.
2. Manual Incremental Update: Use takeSnapshot() to capture the current state, use snapshot.markRefForSave(page.ref) to specify which objects changed, and then use saveIncremental(snapshot) to generate only the bytes for the changes. You can then concatenate these bytes to the original file.

To force a full rewrite of a document that was loaded for incremental updates, use save({ rewrite: true }).

Before using pdf-lib, be aware of the following functional limitations:

• Text Extraction/Editing: You can extract or edit text within form fields (using PDFTextField.getText or PDFTextField.setText), but you cannot extract or edit plain text that exists on a page outside of a form field.
• HTML/CSS Support: pdf-lib does not support HTML or CSS for adding or embedding content. For HTML-to-PDF workflows, consider using Puppeteer.
• PDF/A and Factur-X Compliance: Methods like convertToPDFA() and embedFacturX() add the necessary structural pieces (XMP/attachments), but they do not rewrite page content (e.g., fonts, transparency, or JavaScript) to ensure full compliance. Always validate the output with dedicated tools like veraPDF or Mustang.

In older versions, drawing required manually creating and registering content streams. In v1.0.0 and later, you can call drawing methods directly on a PDFPage instance, such as drawText, drawImage, drawRectangle, or drawSvgPath.

page.drawText('Creating PDFs in JavaScript is awesome!', {
  x: 50,
  y: 450,
  size: 15,
  font: timesRomanFont,
  color: rgb(0, 0.53, 0.71),
});

Version v1.0.0 introduced several breaking changes, primarily making many API methods asynchronous. Key changes include:

• PDFDocumentFactory is renamed to PDFDocument.
• PDFDocument.create and PDFDocument.load are now asynchronous and must be awaited.
• pdfDoc.createPage is replaced by pdfDoc.addPage.
• PDFDocumentWriter.saveToBytes(pdfDoc) is replaced by pdfDoc.save().
• pdfDoc.embedJPG and pdfDoc.embedPNG are now case-sensitive: embedJpg and embedPng.
• getMaybe is replaced by get. Note that get no longer automatically converts strings to PDFName objects; you must wrap name strings in PDFName.of(...).

In v2.0.0 and above, the drawSvg method on a PDFPage became asynchronous. If your SVG does not contain images, you must now await the call. If your SVG contains images, you must first embed the SVG using pdfDoc.embedSvg(svg) before drawing it.

### If your svg doesn't contain images
```js
const svg = `<svg width="100" height="100"><rect width="100" height="100"/></svg>`;
await pdfPage.drawSvg(svg);

If your svg might contain an image

const svg = '<svg><image href="data:image/png;base64,..."/></svg>';
const pdfSvg = await pdfDoc.embedSvg(svg);
pdfPage.drawSvg(pdfSvg);

To develop with pdf-lib, ensure you have the following prerequisites installed:

• Node.js: version v9.0.0 or greater.
• Yarn: version v1.12.0 or greater.
• Git: version 2.17.2 or greater.

Follow these steps to clone and prepare the project:

1. Clone the repository:

   git clone https://github.com/Hopding/pdf-lib.git
   cd pdf-lib

2. Install dependencies using Yarn:

   yarn install

For general questions, help with the library, or providing feedback, use the Discussions channel.

Note: Do not use GitHub Issues for questions or feedback; Issues are reserved for specific technical tasks. If your question strictly fits a Q&A format, StackOverflow is also a recommended venue.

Since pdf-lib is written in TypeScript, all source code must be correctly typed for the project to compile and for tests to run. Use the following command to verify that your code has no type errors:

yarn typecheck