Class: PdfDocument

A mutable builder for creating new PDF documents from scratch. It manages pages, fonts, metadata, outlines, attachments, accessibility data, encryption, and serialization.

Constructors

Constructor

new PdfDocument(options?): PdfDocument;

Creates a new mutable PDF document builder.

Parameters

Parameter	Type	Description
options	DocumentOptions	Options that control the operation.

Returns

PdfDocument

Properties

Property	Type	Default value	Description	Defined in
_debugThreadSafe	boolean	false	When true, warns about potential concurrent access on reentrant calls.
_lockLevel	number	0	Reentrant call counter for thread-safety debugging.

Accessors

pageCount

Get Signature

get pageCount(): number;

The number of pages currently in the document.

Returns

number

---

remainingPages

Get Signature

get remainingPages(): number;

Returns the number of pages that have been added but not yet written via writeNextPage.

Returns

number

Methods

addNamedDestination()

addNamedDestination(name, target): void;

Adds a named destination that points to a page.

Parameters

Parameter	Type	Description
name	string	The name to assign or look up.
target	PdfPage	The destination page, outline target, or structure element.

Returns

void

---

addOutline()

addOutline(
   title, 
   target, 
   options?): PdfOutlineItem;

Adds a top-level outline item to the document.

Parameters

Parameter	Type	Description
title	string	The outline title.
target	string | PdfPage	The destination page, outline target, or structure element.
options	OutlineOptions	Options that control the operation.

Returns

PdfOutlineItem

The created outline item handle.

---

addPage()

addPage(options?): PdfPage;

Adds a page to the document and returns its page builder.

Parameters

Parameter	Type	Description
options	PageOptions	Options that control the operation.

Returns

PdfPage

The new page builder.

---

attachFile()

attachFile(
   name, 
   data, 
   options?): void;

Embeds a file attachment in the document.

Parameters

Parameter	Type	Description
name	string	The name to assign or look up.
data	BinaryData	The binary image or font data.
options	AttachmentOptions	Options that control the operation.

Returns

void

---

clone()

clone(): PdfDocument;

Creates a deep clone of this document. The clone is independently modifiable — it copies all pages, fonts, images, metadata, and the structure tree. Embedded font data is reused from the shared font cache (cross-document sharing).

Returns

PdfDocument

A new PdfDocument instance with a deep copy of the document model.

---

createLuminositySoftMask()

createLuminositySoftMask(options, build): SoftMaskHandle;

Creates a luminosity soft mask backed by a Form XObject. Pass the returned handle to ExtGStateOptions.softMask via PdfPage.setExtGState to apply the mask.

The mask sub-builder supports path operations only. Painted regions with high luminosity (white) become opaque; black becomes transparent.

Parameters

Parameter	Type	Description
options	SoftMaskOptions	Mask BBox dimensions.
build	(mask) => void	Callback that receives the mask sub-builder.

Returns

SoftMaskHandle

A handle referencing the created soft-mask Form XObject.

---

embedTrueTypeFont()

embedTrueTypeFont(data, options?): PdfEmbeddedFont;

Embeds a TrueType font and registers it under the provided name.

Parameters

Parameter	Type	Description
data	BinaryData	The binary image or font data.
options	EmbedTrueTypeFontOptions	Options that control the operation.

Returns

PdfEmbeddedFont

The result of the operation.

---

encryptForRecipients()

encryptForRecipients(certificates): void;

Configures certificate-based (public-key) encryption for the document. Each recipient certificate is a DER-encoded X.509 certificate whose public key is used to encrypt a random 20-byte seed. The /SubFilter /adbe.pkcs7.s5 security handler stores the encrypted seeds in a /Recipients array so each recipient can decrypt the document with their private key.

For simplicity this method only implements encryption — existing encrypted files are not decrypted.

Parameters

Parameter	Type	Description
certificates	Uint8Array<ArrayBufferLike>[]	An array of DER-encoded X.509 certificate bytes.

Returns

void

---

flattenForms()

flattenForms(): void;

Flattens form fields into static page content where possible.

Returns

void

---

getPage()

getPage(index, origin?): PdfPage;

Returns a PdfPage builder for an existing page, so already-created pages (for example those produced by renderTemplate) can be drawn on with the absolute coordinate APIs.

Parameters

Parameter	Type	Default value	Description
index	number	undefined	Zero-based page index.
origin	"bottom-left" | "top-left"	"bottom-left"	Coordinate origin for the returned builder. Defaults to "bottom-left".

Returns

PdfPage

A page builder writing into the existing page.

---

measureRichText()

measureRichText(runs, options): BlockTextMetrics;

Measures a paragraph of inline rich-text runs without drawing it.

Parameters

Parameter	Type	Description
runs	readonly InlineTextRun[]	The styled inline runs.
options	MeasureRichTextOptions	Block options including width (no position needed).

Returns

BlockTextMetrics

The measured block metrics in PDF points.

---

measureText()

measureText(text, options?): TextMetrics;

Measures a single line of text without drawing it, using the document's registered fonts and defaults. Returns the rendered width and the line height (font size). For wrapped multi-line text use measureTextBlock.

Parameters

Parameter	Type	Description
text	string	The text to measure (treated as a single line).
options	MeasureTextOptions	Font and style options (no position needed).

Returns

TextMetrics

The measured width and height in PDF points.

---

measureTextBlock()

measureTextBlock(text, options): BlockTextMetrics;

Measures a wrapped text block without drawing it. Returns the width of the longest line, the total height, and the line count after wrapping.

Parameters

Parameter	Type	Description
text	string	The text to wrap and measure.
options	MeasureTextBlockOptions	Block options including width (no position needed).

Returns

BlockTextMetrics

The measured block metrics in PDF points.

---

registerFontFamily()

registerFontFamily(name, faces): string;

Registers a named font family so text APIs can select a face with the bold and italic flags instead of tracking individual font handles.

Faces may be built-in FontNames or handles returned by embedTrueTypeFont. Pass the family name as the font option on subsequent PdfPage.text/PdfPage.textBlock calls.

Parameters

Parameter	Type	Description
name	string	The family name used as the font option.
faces	FontFamilyInput	The faces that make up the family.

Returns

string

The family name, for convenient inline use as a font value.

Example

const inter = doc.registerFontFamily("Inter", {
  regular: doc.embedTrueTypeFont(regularBytes, { family: "Inter" }),
  bold: doc.embedTrueTypeFont(boldBytes, { family: "Inter" }),
});
page.text("Heading", { x: 56, y: 760, font: inter, bold: true });

---

renderTemplate()

renderTemplate(options): void;

Renders a template document into this PDF document.

Use the fonts option to register embedded font families before rendering so they are available by name in template blocks and styles:

doc.renderTemplate({
  blocks: [ ... ],
  fonts: {
    Inter: {
      regular: interRegularBytes,
      bold: interBoldBytes,
    }
  }
});

Parameters

Parameter	Type	Description
options	TemplateDocumentOptions	Options that control the operation.

Returns

void

---

save()

save(path): Promise<void>;

Serializes the document and writes it to a file path. Convenience alias for writeToFile for Node.js callers. In the browser, use toUint8Array or toBlob instead.

Parameters

Parameter	Type	Description
path	string	The file path to write to.

Returns

Promise<void>

---

setCalculationOrder()

setCalculationOrder(fieldNames): void;

Sets the calculation order for form fields. The order determines the sequence in which field calculations run when a field value changes.

Parameters

Parameter	Type	Description
fieldNames	string[]	The ordered list of form field names.

Returns

void

---

setPageLabel()

setPageLabel(target, options): void;

Sets the label style for a page-label range beginning at the target page.

Parameters

Parameter	Type	Description
target	PdfPage	The destination page, outline target, or structure element.
options	PageLabelOptions	Options that control the operation.

Returns

void

---

setTextShaper()

setTextShaper(shaper): void;

Sets a custom text shaper for complex script shaping (Devanagari, Khmer, Myanmar, Arabic, Thai, etc.). When provided, the shaper is called for each text run that requires shaping. If not provided, the default shaper handles basic ligature and joining-form substitution but will throw an UNSUPPORTED_SCRIPT error for scripts it does not support. External shapers such as harfbuzzjs or fontkit can be plugged in to enable full shaping support.

Parameters

Parameter	Type	Description
shaper	TextShaper | undefined	The custom text shaper to use, or undefined to revert to the default.

Returns

void

Example

import { createDocument } from "@barrierbreak/a11ydocs-pdf";

const doc = createDocument();

// Plug in harfbuzzjs for full complex-script shaping:
// import { createHarfBuzzShaper } from "harfbuzzjs-shaper";
// doc.setTextShaper(createHarfBuzzShaper(harfbuzzInstance));

---

setXmpMetadata()

setXmpMetadata(metadata): void;

Sets or clears the document XMP metadata packet.

Parameters

Parameter	Type	Description
metadata	XmpMetadataInput | undefined	The XMP metadata input, or undefined to clear it.

Returns

void

---

toArrayBuffer()

toArrayBuffer(): ArrayBuffer;

Serializes the document into an ArrayBuffer.

Returns

ArrayBuffer

The serialized PDF data as an ArrayBuffer.

---

toBlob()

toBlob(): Blob;

Serializes the document into a PDF Blob.

Returns

Blob

The serialized PDF data as a Blob.

---

toModel()

toModel(): PdfDocumentModel;

Returns the internal document model used by the serializer.

Returns

PdfDocumentModel

The internal document model.

---

toUint8Array()

toUint8Array(): Uint8Array;

Serializes the document into PDF bytes.

Returns

Uint8Array

The serialized or collected bytes.

---

validateCompliance()

validateCompliance(): readonly PdfComplianceIssue[];

Validates the current document model against enabled compliance rules.

Returns

readonly PdfComplianceIssue[]

The compliance issues found in the current model.

---

writeNextPage()

writeNextPage(sink): Promise<PdfPage>;

Writes all previously added pages to the sink and returns a new PdfPage for the next page. When called repeatedly this streams pages as they are built, reducing peak memory for very large documents (1000+ pages).

Parameters

Parameter	Type	Description
sink	ByteSink	The sink that receives the serialized bytes.

Returns

Promise<PdfPage>

A new page builder for continuing to add pages.

---

writeTo()

writeTo(sink): Promise<void>;

Streams the serialized document to a byte sink.

Parameters

Parameter	Type	Description
sink	ByteSink	The sink that receives written byte chunks.

Returns

Promise<void>

---

writeToFile()

writeToFile(path): Promise<void>;

Serializes the document and writes it to a file path.

Parameters

Parameter	Type	Description
path	string	The file path to write to.

Returns

Promise<void>

---

estimateSignatureSize()

static estimateSignatureSize(certificateBytes?): number;

Estimates the byte size needed for a detached-signature placeholder.

Parameters

Parameter	Type	Description
certificateBytes?	Uint8Array<ArrayBufferLike> | null	Optional certificate bytes for size estimation.

Returns

number

The estimated placeholder size in bytes.