@laminapdf/sdk 0.2.0-alpha.2 → 0.2.0-alpha.4

package/docs/api/classes/Document.md

@@ -0,0 +1,854 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / Document
+
+# Class: 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](#free) (an alias).
+
+## Example
+
+```ts
+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](LaminaPdfError.md) reading errors.
+
+##### Returns
+
+`DocumentInfoJs`
+
+***
+
+### instance
+
+#### Get Signature
+
+> **get** `protected` **instance**(): `Instance`\<`G`\>
+
+The instance this handle lives in (for the handles it makes).
+
+##### Returns
+
+`Instance`\<`G`\>
+
+#### Inherited from
+
+`Handle.instance`
+
+***
+
+### isFreed
+
+#### Get Signature
+
+> **get** `protected` **isFreed**(): `boolean`
+
+Whether `free()` ran on this handle or its parent.
+
+##### Returns
+
+`boolean`
+
+#### Inherited from
+
+`Handle.isFreed`
+
+***
+
+### isTagged
+
+#### Get Signature
+
+> **get** **isTagged**(): `boolean`
+
+Whether the document says it is tagged (`/MarkInfo /Marked true`); it doesn't check the tree.
+Needs a document opened while the extract or text module was loaded, as `page.text()` does.
+
+##### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `extract-module-not-loaded`; reading errors.
+
+##### Returns
+
+`boolean`
+
+***
+
+### owned
+
+#### Get Signature
+
+> **get** `protected` **owned**(): `boolean`
+
+Whether the handle's raw objects can be freed: its instance is current and hasn't trapped.
+
+##### Returns
+
+`boolean`
+
+#### Inherited from
+
+`Handle.owned`
+
+***
+
+### pageCount
+
+#### Get Signature
+
+> **get** **pageCount**(): `number`
+
+The number of pages.
+
+##### Throws
+
+[LaminaPdfError](LaminaPdfError.md) reading errors.
+
+##### Returns
+
+`number`
+
+***
+
+### pages
+
+#### Get Signature
+
+> **get** **pages**(): readonly `PageInfoJs`[]
+
+Every page's facts, in order (one page-tree walk).
+
+##### Throws
+
+[LaminaPdfError](LaminaPdfError.md) reading errors.
+
+##### Returns
+
+readonly `PageInfoJs`[]
+
+***
+
+### warnings
+
+#### Get Signature
+
+> **get** **warnings**(): readonly [`LaminaPdfWarning`](../type-aliases/LaminaPdfWarning.md)[]
+
+Every warning so far (build warnings first), each the ADR 0026 §1 object.
+
+##### Returns
+
+readonly [`LaminaPdfWarning`](../type-aliases/LaminaPdfWarning.md)[]
+
+## 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 `Op`[]
+
+#### Returns
+
+`EditedJs`
+
+the pages the edit touched.
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `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`](../interfaces/OpLog.md)
+
+#### Returns
+
+`EditedJs`
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `invalid-op-log`, `unsupported-version`; as [Document.apply](#apply).
+
+***
+
+### assertLive()
+
+> `protected` **assertLive**(): `void`
+
+#### Returns
+
+`void`
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `disposed` after `free()` (here or on the parent);
+  `instance-reset` when the instance was replaced (a trapped one is replaced first).
+
+#### Inherited from
+
+`Handle.assertLive`
+
+***
+
+### call()
+
+> `protected` **call**\<`T`\>(`f`): `T`
+
+Runs `f` (calls into the glue) on this live handle; see Instance.call.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+#### Parameters
+
+##### f
+
+(`glue`) => `T`
+
+#### Returns
+
+`T`
+
+#### Inherited from
+
+`Handle.call`
+
+***
+
+### 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](#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
+
+```ts
+const doc = await Document.openRange(httpRangeSource(url));
+const pages = await doc.ensure(() => doc.pages);
+```
+
+#### Throws
+
+what `f` throws, and as [Document.openRange](#openrange).
+
+***
+
+### extract()
+
+> **extract**\<`F`\>(`options`): [`ExtractResult`](../interfaces/ExtractResult.md)\[`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`](../type-aliases/ExtractFormat.md)
+
+#### Parameters
+
+##### options
+
+[`ExtractOptions`](../interfaces/ExtractOptions.md)\<`F`\>
+
+#### Returns
+
+[`ExtractResult`](../interfaces/ExtractResult.md)\[`F`\]
+
+a string for `"markdown"` and `"text"`, an [Extraction](../type-aliases/Extraction.md) for `"json"`,
+  [Chunk](../type-aliases/Chunk.md)s for `"chunks"`.
+
+#### Example
+
+```ts
+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](LaminaPdfError.md) `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`).
+
+***
+
+### extractJob()
+
+> **extractJob**\<`F`\>(`options`): [`ExtractJob`](ExtractJob.md)\<`F`\>
+
+An extraction stepped a page at a time, for models the host runs: each step that needs a
+model's result stops with a `request` (the page and resolution to render), answered with
+[ExtractJob.provide](ExtractJob.md#provide). [extractWithModels](../functions/extractWithModels.md) loops one for async models. Needs a
+document opened while the extract or text module was loaded.
+
+#### Type Parameters
+
+##### F
+
+`F` *extends* [`ExtractFormat`](../type-aliases/ExtractFormat.md)
+
+#### Parameters
+
+##### options
+
+[`ExtractJobOptions`](../type-aliases/ExtractJobOptions.md)\<`F`\>
+
+#### Returns
+
+[`ExtractJob`](ExtractJob.md)\<`F`\>
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) as [Document.extract](#extract).
+
+***
+
+### 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`
+
+***
+
+### namedDestination()
+
+> **namedDestination**(`name`): `TargetJs` \| `undefined`
+
+Where the named destination `name` goes (the names a link or a `#nameddest=` address uses),
+or `undefined` when the document has none by that name. Needs a document opened while the
+extract or text module was loaded.
+
+#### Parameters
+
+##### name
+
+`string`
+
+#### Returns
+
+`TargetJs` \| `undefined`
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) as [Document.outline](#outline).
+
+***
+
+### outline()
+
+> **outline**(): `OutlineNodeJs`[]
+
+The outline (bookmarks): its top-level items in order, each with its children, and where
+each goes as a page and a view in page space; empty without one. Needs a document opened
+while the extract or text module was loaded.
+
+#### Returns
+
+`OutlineNodeJs`[]
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `extract-module-not-loaded` for a document opened in the base
+  module; reading errors (`data-pending` for a range document: use `ensure`).
+
+***
+
+### page()
+
+> **page**(`index`): [`PageRef`](PageRef.md)
+
+A handle on page `index` that follows the page by its ID.
+
+#### Parameters
+
+##### index
+
+`number`
+
+#### Returns
+
+[`PageRef`](PageRef.md)
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `page-index-out-of-range`.
+
+***
+
+### pageById()
+
+> **pageById**(`id`): [`PageRef`](PageRef.md)
+
+A handle on the page with `id` (`p12.0`).
+
+#### Parameters
+
+##### id
+
+`string`
+
+#### Returns
+
+[`PageRef`](PageRef.md)
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `invalid-argument`, `unknown-page`.
+
+***
+
+### pageInfo()
+
+> **pageInfo**(`index`): `PageInfoJs`
+
+Page `index`'s facts.
+
+#### Parameters
+
+##### index
+
+`number`
+
+#### Returns
+
+`PageInfoJs`
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `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](LaminaPdfError.md) `no-pending-save`; reading errors in `bytes`.
+
+***
+
+### redo()
+
+> **redo**(): `UndoOutcomeJs` \| `undefined`
+
+Redoes the newest undone transaction.
+
+#### Returns
+
+`UndoOutcomeJs` \| `undefined`
+
+how it went, or `undefined` when there is nothing to redo.
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) as [Document.undo](#undo).
+
+***
+
+### release()
+
+> `protected` **release**(): `void`
+
+Frees the WebAssembly side; called at most once, and only while [owned](#owned).
+
+#### Returns
+
+`void`
+
+#### Overrides
+
+`Handle.release`
+
+***
+
+### save()
+
+> **save**(`options?`): `Uint8Array`\<`ArrayBuffer`\>
+
+Saves and rebases onto the output (later edits and saves build on it).
+
+#### Parameters
+
+##### options?
+
+`SaveOptionsInit`
+
+`mode` (`auto`, `incremental`, `fullRewrite`), overrides, output form.
+
+#### Returns
+
+`Uint8Array`\<`ArrayBuffer`\>
+
+the file's bytes.
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `would-invalidate-signatures`, `requires-rewrite`, `encrypted-base`, …
+
+***
+
+### saveJob()
+
+> **saveJob**(`options?`): [`SaveJob`](SaveJob.md)
+
+A save as a job stepped by the caller (to keep a UI responsive).
+
+#### Parameters
+
+##### options?
+
+`SaveOptionsInit`
+
+#### Returns
+
+[`SaveJob`](SaveJob.md)
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `unknown-option` / `invalid-argument` for bad options.
+
+***
+
+### saveWithReport()
+
+> **saveWithReport**(`options?`): `object`
+
+As [Document.save](#save), with the save's report (mode used, bytes written, renumbering, …).
+
+#### Parameters
+
+##### options?
+
+`SaveOptionsInit`
+
+#### Returns
+
+`object`
+
+##### bytes
+
+> `readonly` **bytes**: `Uint8Array`\<`ArrayBuffer`\>
+
+##### report
+
+> `readonly` **report**: `SaveReportJs`
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) as [Document.save](#save).
+
+***
+
+### structureTree()
+
+> **structureTree**(): `StructureNodeJs`[] \| `undefined`
+
+The structure tree's top-level elements in reading order, or `undefined` for a document
+without one. A text run's `mcid` (on [PageTextRun](PageTextRun.md)) links it to the element whose
+`{ type: "content", page, mcid }` kid names it. Needs the extract or text module, as
+`page.text()` does.
+
+#### Returns
+
+`StructureNodeJs`[] \| `undefined`
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `extract-module-not-loaded`; reading errors.
+
+***
+
+### 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](LaminaPdfError.md) `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](#apply).
+
+#### Example
+
+```ts
+doc.transact((tx) => {
+  tx.setInfo({ title: "Report" });
+  tx.rotatePage(doc.page(0).id, 90);
+});
+```
+
+***
+
+### undo()
+
+> **undo**(): `UndoOutcomeJs` \| `undefined`
+
+Undoes the newest transaction.
+
+#### Returns
+
+`UndoOutcomeJs` \| `undefined`
+
+how it went, or `undefined` when there is nothing to undo.
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `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`](../interfaces/OpenOptions.md)
+
+password, strict mode, limits.
+
+#### Returns
+
+`Document`
+
+the document.
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `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](../functions/httpRangeSource.md),
+[callbackSource](../functions/callbackSource.md)): 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](#ensure).
+
+#### Parameters
+
+##### source
+
+[`RangeSource`](../interfaces/RangeSource.md) \| `Promise`\<[`RangeSource`](../interfaces/RangeSource.md)\>
+
+the file (or a promise of it, as `httpRangeSource` returns).
+
+##### options?
+
+[`OpenOptions`](../interfaces/OpenOptions.md) & [`RangeOptions`](../interfaces/RangeOptions.md) = `{}`
+
+open options (password, strict, limits) and fetch options.
+
+#### Returns
+
+`Promise`\<`Document`\>
+
+the document, once open has everything it needs.
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) as [Document.open](#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.