@laminapdf/sdk 0.0.0-stage → 0.2.0-alpha.3

package/docs/api/classes/SaveJob.md

@@ -0,0 +1,205 @@
+---
+version: "0.2.0-alpha.3"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / SaveJob
+
+# Class: SaveJob
+
+A save in progress, stepped by the caller with a budget of work units (ADR 0028 §3). Freed with
+its document; every call after that throws `disposed`.
+
+## Extends
+
+- `Handle`\<`BaseGlue`\>
+
+## Accessors
+
+### 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`
+
+***
+
+### 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`
+
+***
+
+### cancel()
+
+> **cancel**(): `void`
+
+Stops the job: its next step fails with `cancelled`.
+
+#### Returns
+
+`void`
+
+***
+
+### 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`
+
+***
+
+### release()
+
+> `protected` **release**(): `void`
+
+Frees the WebAssembly side; called at most once, and only while [owned](#owned).
+
+#### Returns
+
+`void`
+
+#### Overrides
+
+`Handle.release`
+
+***
+
+### step()
+
+> **step**(`budget`): `object` & `ProgressJs` \| \{ `bytes`: `Uint8Array`\<`ArrayBuffer`\>; `report`: `SaveReportJs`; `state`: `"done"`; \}
+
+Runs at most `budget` work units.
+
+#### Parameters
+
+##### budget
+
+`number`
+
+#### Returns
+
+`object` & `ProgressJs` \| \{ `bytes`: `Uint8Array`\<`ArrayBuffer`\>; `report`: `SaveReportJs`; `state`: `"done"`; \}
+
+`{ state: "progress", … }`, or `{ state: "done", bytes, report }` at the end.
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `cancelled`, `document-changed`, `job-finished`, or the save's errors.

package/docs/api/classes/Surface.md

@@ -0,0 +1,326 @@
+---
+version: "0.2.0-alpha.3"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / Surface
+
+# Class: Surface
+
+What a page is drawn with. Methods that set state return the surface, so calls chain; invalid
+geometry is reported by [Page.finish](Page.md#finish) (`invalid-geometry`).
+
+## Methods
+
+### artifact()
+
+> **artifact**(`kind`, `draw`): `this`
+
+Draws what `draw` draws as an artifact: decoration, running heads and footers, backgrounds;
+content outside the structure tree.
+
+#### Parameters
+
+##### kind
+
+`"layout"` \| `"page"` \| `"pagination"` \| `"background"`
+
+##### draw
+
+(`s`) => `void`
+
+#### Returns
+
+`this`
+
+***
+
+### blendMode()
+
+> **blendMode**(`mode`): `this`
+
+The blend mode.
+
+#### Parameters
+
+##### mode
+
+`"normal"` \| `"multiply"` \| `"screen"` \| `"overlay"` \| `"darken"` \| `"lighten"` \| `"colorDodge"` \| `"colorBurn"` \| `"hardLight"` \| `"softLight"` \| `"difference"` \| `"exclusion"` \| `"hue"` \| `"saturation"` \| `"color"` \| `"luminosity"`
+
+#### Returns
+
+`this`
+
+***
+
+### fillColor()
+
+> **fillColor**(`color`): `this`
+
+The colour fills (and text) use.
+
+#### Parameters
+
+##### color
+
+[`Color`](../type-aliases/Color.md)
+
+#### Returns
+
+`this`
+
+***
+
+### image()
+
+> **image**(`image`, `rect`, `alt?`): `this`
+
+Draws `image` scaled into `rect`; with `alt`, as a `Figure` structure element with that
+alternate text.
+
+#### Parameters
+
+##### image
+
+[`Image`](Image.md)
+
+##### rect
+
+[`Rect`](../type-aliases/Rect.md)
+
+##### alt?
+
+`string`
+
+#### Returns
+
+`this`
+
+***
+
+### link()
+
+> **link**(`rect`, `target`, `contents?`): `this`
+
+A link annotation over `rect`, with `contents` as its alternate text.
+
+#### Parameters
+
+##### rect
+
+[`Rect`](../type-aliases/Rect.md)
+
+##### target
+
+`LinkTargetInit`
+
+##### contents?
+
+`string`
+
+#### Returns
+
+`this`
+
+***
+
+### opacity()
+
+> **opacity**(`fill`, `stroke`): `this`
+
+Fill and stroke opacity, 0 to 1.
+
+#### Parameters
+
+##### fill
+
+`number`
+
+##### stroke
+
+`number`
+
+#### Returns
+
+`this`
+
+***
+
+### path()
+
+> **path**(`build`): [`PendingPath`](PendingPath.md)
+
+A path, built by `build`, to paint.
+
+#### Parameters
+
+##### build
+
+(`p`) => `void`
+
+#### Returns
+
+[`PendingPath`](PendingPath.md)
+
+#### Example
+
+```ts
+surface.path((p) => p.moveTo(56, 590).lineTo(539, 590)).stroke({ width: 0.5 });
+```
+
+***
+
+### restore()
+
+> **restore**(): `this`
+
+Restores the graphics state (`Q`).
+
+#### Returns
+
+`this`
+
+***
+
+### save()
+
+> **save**(): `this`
+
+Saves the graphics state (`q`).
+
+#### Returns
+
+`this`
+
+***
+
+### strokeColor()
+
+> **strokeColor**(`color`): `this`
+
+The colour strokes use.
+
+#### Parameters
+
+##### color
+
+[`Color`](../type-aliases/Color.md)
+
+#### Returns
+
+`this`
+
+***
+
+### tag()
+
+> **tag**(`tag`, `draw`): `this`
+
+Draws what `draw` draws inside the structure element `tag`: its text, paths and images
+become the element's content, elements opened inside it its children, links its `Link`
+children, in reading order. Elements and artifacts `draw` leaves open end with it, also when
+it throws. A page using an element makes the document tagged.
+
+#### Parameters
+
+##### tag
+
+[`Tag`](../type-aliases/Tag.md)
+
+##### draw
+
+(`s`) => `void`
+
+#### Returns
+
+`this`
+
+#### Example
+
+```ts
+s.tag("Sect", (s) => {
+  s.text("Results", { font, size: 18, at: [56, 96], tag: "H1" });
+  s.tag({ type: "P", lang: "en-GB" }, (s) => s.textBox(summary, { font, size: 11, box }));
+});
+```
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `invalid-argument` for an unknown type without a `role`.
+
+***
+
+### text()
+
+> **text**(`text`, `options`): `TextRunJs`
+
+Draws `text`: shaped, bidi-resolved, one line per line break (needs the text module).
+
+#### Parameters
+
+##### text
+
+`string`
+
+##### options
+
+[`TextOptions`](../interfaces/TextOptions.md)
+
+#### Returns
+
+`TextRunJs`
+
+what the run measures.
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `text-module-not-loaded`, `missing-glyph`, `font-not-shapable`, …
+
+***
+
+### textBox()
+
+> **textBox**(`text`, `options`): `TextLayoutJs`
+
+Lays `text` out in `options.box`, breaking lines at Unicode line-break opportunities.
+
+#### Parameters
+
+##### text
+
+`string`
+
+##### options
+
+[`TextBoxOptions`](../interfaces/TextBoxOptions.md)
+
+#### Returns
+
+`TextLayoutJs`
+
+the lines drawn and where the overflow starts (UTF-16 offsets).
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) as [Surface.text](#text); `text-overflow` with `overflow: "error"`.
+
+***
+
+### transform()
+
+> **transform**(`matrix`): `this`
+
+Applies `matrix` (page space) to what is drawn next. See [Matrix](../variables/Matrix.md).
+
+#### Parameters
+
+##### matrix
+
+[`Transform`](../type-aliases/Transform.md)
+
+#### Returns
+
+`this`

package/docs/api/classes/Transaction.md

@@ -0,0 +1,111 @@
+---
+version: "0.2.0-alpha.3"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / Transaction
+
+# Class: Transaction
+
+Collects the ops of one [Document.transact](Document.md#transact) call.
+
+## Constructors
+
+### Constructor
+
+> **new Transaction**(): `Transaction`
+
+#### Returns
+
+`Transaction`
+
+## Accessors
+
+### ops
+
+#### Get Signature
+
+> **get** **ops**(): readonly `Op`[]
+
+The ops collected so far.
+
+##### Returns
+
+readonly `Op`[]
+
+## Methods
+
+### apply()
+
+> **apply**(`op`): `this`
+
+Adds `op` to the transaction.
+
+#### Parameters
+
+##### op
+
+`Op`
+
+#### Returns
+
+`this`
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `no-transaction` after `transact` returned.
+
+***
+
+### rotatePage()
+
+> **rotatePage**(`page`, `rotate`): `this`
+
+Sets a page's `/Rotate` (`rotatePage`).
+
+#### Parameters
+
+##### page
+
+`string`
+
+the page's ID (`doc.page(0).id`).
+
+##### rotate
+
+[`Rotation`](../type-aliases/Rotation.md)
+
+0, 90, 180 or 270 degrees.
+
+#### Returns
+
+`this`
+
+***
+
+### setInfo()
+
+> **setInfo**(`patch`, `at?`): `this`
+
+Patches the Info dictionary (`setInfo`).
+
+#### Parameters
+
+##### patch
+
+[`InfoPatch`](../type-aliases/InfoPatch.md)
+
+the entries to set (a string) or remove (`null`).
+
+##### at?
+
+`string`
+
+the modification date to write (`D:20261030120000Z`); omitted, none is written.
+
+#### Returns
+
+`this`

package/docs/api/functions/callbackSource.md

@@ -0,0 +1,33 @@
+---
+version: "0.2.0-alpha.3"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / callbackSource
+
+# Function: callbackSource()
+
+> **callbackSource**(`size`, `read`): [`RangeSource`](../interfaces/RangeSource.md)
+
+A [RangeSource](../interfaces/RangeSource.md) over a caller's read function (a `Blob.slice`, a file handle, an IPC call).
+
+## Parameters
+
+### size
+
+`number`
+
+the file's size in bytes.
+
+### read
+
+(`offset`, `length`, `signal?`) => `Promise`\<`Uint8Array`\<`ArrayBufferLike`\>\>
+
+returns the `length` bytes at `offset`.
+
+## Returns
+
+[`RangeSource`](../interfaces/RangeSource.md)

package/docs/api/functions/httpRangeSource.md

@@ -0,0 +1,48 @@
+---
+version: "0.2.0-alpha.3"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / httpRangeSource
+
+# Function: httpRangeSource()
+
+> **httpRangeSource**(`url`, `options?`): `Promise`\<[`RangeSource`](../interfaces/RangeSource.md)\>
+
+A [RangeSource](../interfaces/RangeSource.md) over a URL, for `Document.openRange`. The first request asks for the
+last `tail` bytes, which gives the size and the part of the file a reader needs first (the
+xref is at the end). Every later request sends `If-Range` with the first strong `ETag` (else
+its `Last-Modified`); a response whose `ETag`, `Last-Modified` or total size differs fails
+with `source-changed`. A server that ignores
+`Range` (it answers `200`) is read with that one full download.
+
+The server must allow `Range` (across origins: `Access-Control-Allow-Headers: Range` and
+`Access-Control-Expose-Headers: Content-Range, Content-Length, ETag`) and must not compress
+the response.
+
+## Parameters
+
+### url
+
+`string` \| `URL`
+
+the file.
+
+### options?
+
+[`HttpRangeOptions`](../interfaces/HttpRangeOptions.md) = `{}`
+
+headers, credentials, signal, block size.
+
+## Returns
+
+`Promise`\<[`RangeSource`](../interfaces/RangeSource.md)\>
+
+the source, once the first request has answered.
+
+## Throws
+
+[LaminaPdfError](../classes/LaminaPdfError.md) `fetch-failed` (with `data.status`), `source-changed`.