Document

An open PDF: read it, edit it with ops (atomic transactions with undo), save it.

Example

await init();
const doc = Document.open(bytes);
doc.transact((tx) => tx.setInfo({ title: "Final" }));
const updated = doc.save({ mode: "incremental" });
doc.free();

Accessors

canExtractText

Get Signature

get canExtractText(): boolean

Whether page(i).text() works on this document: it was opened or built while the extract or the text module was loaded. A document opened before the module loaded stays in the base module; save and reopen it to move it.

Returns

boolean

hasUnsavedChanges

Get Signature

get hasUnsavedChanges(): boolean

Whether there are changes no save has written yet.

Returns

boolean

info

Get Signature

get info(): DocumentInfoJs

The Info dictionary’s text entries (document text).

Throws

LaminaError reading errors.

Returns

DocumentInfoJs

pageCount

Get Signature

get pageCount(): number

The number of pages.

Throws

LaminaError reading errors.

Returns

number

warnings

Get Signature

get warnings(): readonly LaminaWarning[]

Every warning so far (build warnings first), each the ADR 0026 §1 object.

Returns

readonly LaminaWarning[]

Methods

[dispose]()

[dispose](): void

Frees the document at the end of a using block.

Returns

void

apply()

apply(ops): EditedJs

Applies ops in order as one transaction: all of them, or none.

Parameters

ops

readonly OpJs[]

Returns

EditedJs

the pages the edit touched.

Throws

LaminaError unknown-option / invalid-argument for a value that isn’t an op; the first failing op’s error (unknown-page, …), with nothing applied.

applyLog()

applyLog(log): EditedJs

Applies an op log ({ v: 1, ops }, as JSON text or an object) as one transaction.

Parameters

log

string | OpLog

Returns

EditedJs

Throws

LaminaError invalid-op-log, unsupported-version; as Document.apply.

ensure()

ensure<T>(f, options?): Promise<T>

Runs a synchronous call on this document, fetching what it needs first: for a document from Document.openRange, a data-pending makes it fetch the ranges asked for and call f again. For other documents it just returns f().

Type Parameters

T

T

Parameters

f

() => T | Promise<T>

the call (it may run several times; keep it free of side effects). An async function works too: its data-pending rejections are caught the same way.

options?

signal aborts this call’s fetches (the open’s signal applies to the open only).

signal?

AbortSignal

Returns

Promise<T>

what f returns.

Example

const doc = await Document.openRange(httpRangeSource(url));
const pages = await doc.ensure(() => doc.pages);

Throws

what f throws, and as Document.openRange.

free()

free(): void

Frees the document’s WASM memory now; without it, it is freed when garbage-collected. Calling it twice is harmless; using the document afterwards is not (L2b adds disposed).

Returns

void

page()

page(index): PageRef

A handle on page index that follows the page by its ID.

Parameters

index

number

Returns

PageRef

Throws

LaminaError page-index-out-of-range.

pageById()

pageById(id): PageRef

A handle on the page with id (p12.0).

Parameters

id

string

Returns

PageRef

Throws

LaminaError invalid-argument, unknown-page.

pageInfo()

pageInfo(index): PageInfoJs

Page index’s facts.

Parameters

index

number

Returns

PageInfoJs

Throws

LaminaError page-index-out-of-range.

rebase()

rebase(bytes): void

Rebases onto bytes, the output of a save whose rebase failed (not-rebased).

Parameters

bytes

Uint8Array

Returns

void

Throws

LaminaError no-pending-save; reading errors in bytes.

redo()

redo(): any

Redoes the newest undone transaction.

Returns

any

how it went, or undefined when there is nothing to redo.

Throws

LaminaError as Document.undo.

save()

save(options?): Uint8Array

Saves and rebases onto the output (later edits and saves build on it).

Parameters

options?

any

mode (auto, incremental, fullRewrite), overrides, output form.

Returns

Uint8Array

the file’s bytes.

Throws

LaminaError would-invalidate-signatures, requires-rewrite, encrypted-base, …

saveJob()

saveJob(options?): SaveJob

A save as a job stepped by the caller (to keep a UI responsive).

Parameters

options?

any

Returns

SaveJob

Throws

LaminaError unknown-option / invalid-argument for bad options.

saveWithReport()

saveWithReport(options?): object

As Document.save, with the save’s report (mode used, bytes written, renumbering, …).

Parameters

options?

any

Returns

object

bytes

readonly bytes: Uint8Array

report

readonly report: SaveReportJs

Throws

LaminaError as Document.save.

transact()

transact<T>(edit): T

Runs edit with a transaction handle and applies what it collected as one transaction (ADR 0006 §2). When edit throws, nothing is applied and the error propagates. The ops are applied when edit returns: reads inside edit see the document before the transaction.

Type Parameters

T

T

Parameters

edit

(tx) => T

collects ops on tx; synchronous only (a callback returning a promise is refused with invalid-argument and nothing is applied).

Returns

T

what edit returned.

Throws

LaminaError nested-transaction when called (or when apply, undo, redo, save… are called) inside a transact of the same document; invalid-argument for an async callback; as Document.apply.

Example

doc.transact((tx) => {
  tx.setInfo({ title: "Report" });
  tx.rotatePage(doc.page(0).id, 90);
});

undo()

undo(): any

Undoes the newest transaction.

Returns

any

how it went, or undefined when there is nothing to undo.

Throws

LaminaError saved-not-rebased; reading errors.

open()

static open(bytes, options?): Document

Opens a document from its bytes (the bytes are copied into the WASM memory).

The password is tried as given. When that fails with wrong-password and its NFKC form differs, the NFKC form is tried too: R5/R6 passwords are prepared with SASLprep, whose normalisation the WASM modules leave out (ADR 0016 §7), while R2–R4 passwords must reach the core unchanged.

Parameters

bytes

ArrayBuffer | Uint8Array<ArrayBufferLike>

the PDF file.

options?

OpenOptions

password, strict mode, limits.

Returns

Document

the document.

Throws

LaminaError not-pdf, password-required, wrong-password, limit-exceeded, strict, …; unknown-option / invalid-argument for bad options; not-initialized.

openRange()

static openRange(source, options?): Promise<Document>

Opens a document whose bytes are fetched range by range (httpRangeSource, callbackSource): only what the open needs is fetched (the end of the file, the xref, the catalog). Calls on the document stay synchronous; one that needs bytes not fetched yet throws data-pending with ranges, so wrap later reads in Document.ensure.

Parameters

source

RangeSource | Promise<RangeSource>

the file (or a promise of it, as httpRangeSource returns).

options?

OpenOptions & RangeOptions = {}

open options (password, strict, limits) and fetch options.

Returns

Promise<Document>

the document, once open has everything it needs.

Throws

LaminaError as Document.open; data-pending when fetching made no progress or maxRounds ran out; source-budget-exceeded; the source’s own errors (fetch-failed, source-changed); the signal’s reason when aborted.