Skip to main content

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​

ParameterTypeDescription
optionsDocumentOptionsOptions that control the operation.

Returns​

PdfDocument

Properties​

PropertyTypeDefault valueDescriptionDefined in
_debugThreadSafebooleanfalseWhen true, warns about potential concurrent access on reentrant calls.
_lockLevelnumber0Reentrant 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​

ParameterTypeDescription
namestringThe name to assign or look up.
targetPdfPageThe 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​

ParameterTypeDescription
titlestringThe outline title.
targetstring | PdfPageThe destination page, outline target, or structure element.
optionsOutlineOptionsOptions 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​

ParameterTypeDescription
optionsPageOptionsOptions that control the operation.

Returns​

PdfPage

The new page builder.


attachFile()​

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

Embeds a file attachment in the document.

Parameters​

ParameterTypeDescription
namestringThe name to assign or look up.
dataBinaryDataThe binary image or font data.
optionsAttachmentOptionsOptions 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​

ParameterTypeDescription
optionsSoftMaskOptionsMask BBox dimensions.
build(mask) => voidCallback 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​

ParameterTypeDescription
dataBinaryDataThe binary image or font data.
optionsEmbedTrueTypeFontOptionsOptions 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​

ParameterTypeDescription
certificatesUint8Array<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​

ParameterTypeDefault valueDescription
indexnumberundefinedZero-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​

ParameterTypeDescription
runsreadonly InlineTextRun[]The styled inline runs.
optionsMeasureRichTextOptionsBlock 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​

ParameterTypeDescription
textstringThe text to measure (treated as a single line).
optionsMeasureTextOptionsFont 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​

ParameterTypeDescription
textstringThe text to wrap and measure.
optionsMeasureTextBlockOptionsBlock 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​

ParameterTypeDescription
namestringThe family name used as the font option.
facesFontFamilyInputThe 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​

ParameterTypeDescription
optionsTemplateDocumentOptionsOptions 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​

ParameterTypeDescription
pathstringThe 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​

ParameterTypeDescription
fieldNamesstring[]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​

ParameterTypeDescription
targetPdfPageThe destination page, outline target, or structure element.
optionsPageLabelOptionsOptions 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​

ParameterTypeDescription
shaperTextShaper | undefinedThe 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​

ParameterTypeDescription
metadataXmpMetadataInput | undefinedThe 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​

ParameterTypeDescription
sinkByteSinkThe 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​

ParameterTypeDescription
sinkByteSinkThe 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​

ParameterTypeDescription
pathstringThe file path to write to.

Returns​

Promise<void>


estimateSignatureSize()​

static estimateSignatureSize(certificateBytes?): number;

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

Parameters​

ParameterTypeDescription
certificateBytes?Uint8Array<ArrayBufferLike> | nullOptional certificate bytes for size estimation.

Returns​

number

The estimated placeholder size in bytes.