These docs describe changes that aren’t released yet. For the newest release, see the released docs.

Document

An open PDF: read it, edit it with ops (atomic transactions with undo), save it. It holds WebAssembly memory: free it with using or Document.free (an alias).

Example

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

Extends

Handle<BaseGlue>

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

LaminaPdfError reading errors.

Returns

DocumentInfoJs

pageCount

Get Signature

get pageCount(): number

The number of pages.

Throws

LaminaPdfError reading errors.

Returns

number

warnings

Get Signature

get warnings(): readonly LaminaPdfWarning[]

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

Returns

readonly LaminaPdfWarning[]

Methods

[dispose]()

[dispose](): void

Frees the handle at the end of a using block (an alias of free()).

Returns

void

Inherited from

Handle.[dispose]

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

LaminaPdfError 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

LaminaPdfError 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.

extract()

extract<F>(options): ExtractResult[F]

The document’s text for retrieval and LLMs: Markdown or plain text in reading order, the laminapdf.extract/1 JSON with a box for every block, or chunks sized for retrieval. Tables drawn with lines come out as tables, and text a reader can’t see is left out. Needs a document opened while the extract or text module was loaded.

Type Parameters

F

F extends ExtractFormat

Parameters

options

ExtractOptions<F>

Returns

ExtractResult[F]

a string for "markdown" and "text", an Extraction for "json", Chunks for "chunks".

Example

await init({ extract: true });
const doc = Document.open(bytes);
const markdown = doc.extract({ format: "markdown" });
const chunks = doc.extract({ format: "chunks", chunk: { maxTokens: 400 } });

Throws

LaminaPdfError extract-module-not-loaded for a document opened in the base module; page-index-out-of-range; unknown-option (with didYouMean) / invalid-argument for bad options; reading errors (data-pending for a range document: use ensure).

free()

free(): void

Frees the handle’s memory now; without it, the garbage collector frees it later. A second call does nothing, and any other call afterwards throws disposed. Prefer using, which calls this at the end of the block.

Returns

void

Inherited from

Handle.free

page()

page(index): PageRef

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

Parameters

index

number

Returns

PageRef

Throws

LaminaPdfError page-index-out-of-range.

pageById()

pageById(id): PageRef

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

Parameters

id

string

Returns

PageRef

Throws

LaminaPdfError invalid-argument, unknown-page.

pageInfo()

pageInfo(index): PageInfoJs

Page index’s facts.

Parameters

index

number

Returns

PageInfoJs

Throws

LaminaPdfError 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

LaminaPdfError 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

LaminaPdfError as Document.undo.

save()

save(options?): Uint8Array<ArrayBuffer>

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<ArrayBuffer>

the file’s bytes.

Throws

LaminaPdfError 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

LaminaPdfError 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<ArrayBuffer>

report

readonly report: SaveReportJs

Throws

LaminaPdfError 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

LaminaPdfError 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

LaminaPdfError 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

LaminaPdfError 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

LaminaPdfError 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.