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

package/docs/api/classes/Builder.md

@@ -0,0 +1,467 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / Builder
+
+# Class: Builder
+
+Builds a new document: pages, navigation and metadata; [Builder.finish](#finish) returns a
+[Document](Document.md) to save. Created in the text module when it is loaded (or `text: true`),
+else in the reading module (text, extract, then base; vector and image pages only). `finish()`
+frees its WebAssembly memory; to drop it unfinished, use `using` or [Builder.free](#free).
+
+## Example
+
+```ts
+await init({ text: true });
+const b = new Builder({ producer: "my app" });
+const page = b.page("A4");
+page.surface().text("Hello, world!", { font: Font.standard("Helvetica"), size: 24, at: [72, 96] });
+page.finish();
+const bytes = b.finish().save();
+```
+
+## Extends
+
+- `Handle`\<`BaseGlue`\>
+
+## Constructors
+
+### Constructor
+
+> **new Builder**(`options?`): `Builder`
+
+#### Parameters
+
+##### options?
+
+[`BuilderOptions`](../interfaces/BuilderOptions.md) = `{}`
+
+version, file ID, producer, creation date, compression, tagging,
+  conformance `profiles`; `text`.
+
+#### Returns
+
+`Builder`
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `not-initialized`, `text-module-not-loaded`; `unknown-option`.
+
+#### Overrides
+
+`Handle<BaseGlue>.constructor`
+
+## Accessors
+
+### hasText
+
+#### Get Signature
+
+> **get** **hasText**(): `boolean`
+
+Whether this builder draws in the text module (fonts and text).
+
+##### Returns
+
+`boolean`
+
+***
+
+### 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`
+
+***
+
+### 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`
+
+## Methods
+
+### \[dispose\]()
+
+> **\[dispose\]**(): `void`
+
+Frees the handle at the end of a `using` block (an alias of `free()`).
+
+#### Returns
+
+`void`
+
+#### Inherited from
+
+`Handle.[dispose]`
+
+***
+
+### 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`
+
+***
+
+### attach()
+
+> **attach**(`name`, `bytes`, `mime`, `options?`): `this`
+
+Attaches a file: PDF/A-3b's associated files, such as an e-invoice's XML. The same name
+again replaces the file. PDF/A-2b and PDF/A-2u refuse attachments at [Builder.finish](#finish),
+and every PDF/A profile refuses one without a MIME type there.
+
+#### Parameters
+
+##### name
+
+`string`
+
+the file name viewers show.
+
+##### bytes
+
+`Uint8Array`
+
+the file's contents.
+
+##### mime
+
+`string`
+
+its MIME type, such as `text/xml`.
+
+##### options?
+
+`AttachmentInit`
+
+how the file relates to the document (`relationship`, default
+  `unspecified`), its `description` and `modDate`.
+
+#### Returns
+
+`this`
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `invalid-argument` for a `modDate` that isn't a PDF date,
+  `unknown-option` for an unknown key, `builder-finished` after [Builder.finish](#finish).
+
+***
+
+### 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`
+
+***
+
+### destination()
+
+> **destination**(`name`, `index`, `fit?`): `this`
+
+Defines the named destination `name`: page `index`, shown as `fit` (default: the page).
+
+#### Parameters
+
+##### name
+
+`string`
+
+##### index
+
+`number`
+
+##### fit?
+
+`FitInit`
+
+#### Returns
+
+`this`
+
+***
+
+### finish()
+
+> **finish**(): [`Document`](Document.md)
+
+Writes fonts, links, the page tree, outline and metadata; the builder (and its unfinished
+pages) take no more calls afterwards.
+
+#### Returns
+
+[`Document`](Document.md)
+
+the new document (unsaved; its save is a full rewrite).
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `page-index-out-of-range`, `unknown-destination`,
+  `invalid-page-labels`, `invalid-geometry`, `subset-failed`, `builder-finished`; under a
+  profile (`profiles` in the options), the first rule the document breaks, with that rule's
+  code (the error reference lists them, from `profile-version-conflict` on).
+
+***
+
+### font()
+
+> **font**(`font`): [`FontInfo`](../interfaces/FontInfo.md)
+
+Registers `font` with this builder (otherwise it is registered at first use).
+
+#### Parameters
+
+##### font
+
+[`Font`](Font.md)
+
+#### Returns
+
+[`FontInfo`](../interfaces/FontInfo.md)
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `text-module-not-loaded`, `invalid-font`, `font-not-embeddable`.
+
+***
+
+### 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`
+
+***
+
+### lang()
+
+> **lang**(`tag`): `this`
+
+The natural language (`/Lang`), a BCP 47 tag.
+
+#### Parameters
+
+##### tag
+
+`string`
+
+#### Returns
+
+`this`
+
+***
+
+### metadata()
+
+> **metadata**(`metadata`): `this`
+
+The metadata, written as the Info dictionary and an XMP packet.
+
+#### Parameters
+
+##### metadata
+
+`MetadataInit`
+
+#### Returns
+
+`this`
+
+***
+
+### outline()
+
+> **outline**(`entries`): `string`[]
+
+Adds outline (bookmark) items with their children.
+
+#### Parameters
+
+##### entries
+
+readonly `OutlineEntryInit`[]
+
+#### Returns
+
+`string`[]
+
+their IDs, in pre-order.
+
+***
+
+### page()
+
+> **page**(`size?`): [`Page`](Page.md)
+
+A new page of a named size or `[width, height]` in points.
+
+#### Parameters
+
+##### size?
+
+[`PageSizeName`](../type-aliases/PageSizeName.md) \| readonly \[`number`, `number`\] = `"A4"`
+
+#### Returns
+
+[`Page`](Page.md)
+
+***
+
+### pageLabels()
+
+> **pageLabels**(`ranges`): `this`
+
+The page labels (`i, ii, 1, 2…`), ranges by first page; checked at finish.
+
+#### Parameters
+
+##### ranges
+
+readonly `PageLabelInit`[]
+
+#### Returns
+
+`this`
+
+***
+
+### release()
+
+> `protected` **release**(): `void`
+
+Frees the WebAssembly side; called at most once, and only while [owned](#owned).
+
+#### Returns
+
+`void`
+
+#### Overrides
+
+`Handle.release`
+
+***
+
+### viewerPreferences()
+
+> **viewerPreferences**(`preferences`): `this`
+
+How viewers present the document when it opens.
+
+#### Parameters
+
+##### preferences
+
+`ViewerPreferencesInit`
+
+#### Returns
+
+`this`
+
+***
+
+### create()
+
+> `static` **create**(`options?`): `Builder`
+
+As `new Builder(options)`.
+
+#### Parameters
+
+##### options?
+
+[`BuilderOptions`](../interfaces/BuilderOptions.md)
+
+#### Returns
+
+`Builder`