@laminapdf/sdk 0.2.0-alpha.3 → 0.2.0-alpha.5

package/docs/api/classes/ExtractJob.md

@@ -0,0 +1,236 @@
+---
+version: "0.2.0-alpha.5"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / ExtractJob
+
+# Class: ExtractJob\<F\>
+
+An extraction in progress, from [Document.extractJob](Document.md#extractjob). It holds WebAssembly memory and is
+freed with its document, or earlier with `free()` or `using`.
+
+## Extends
+
+- `Handle`\<`BaseGlue`\>
+
+## Type Parameters
+
+### F
+
+`F` *extends* [`ExtractFormat`](../type-aliases/ExtractFormat.md) = [`ExtractFormat`](../type-aliases/ExtractFormat.md)
+
+## 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`
+
+***
+
+### provide()
+
+> **provide**(`result`): `void`
+
+Hands the job the result of its open request.
+
+#### Parameters
+
+##### result
+
+[`ModelResult`](../type-aliases/ModelResult.md)
+
+#### Returns
+
+`void`
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `model-result-unexpected` when nothing was asked for or `result`
+  is the other model's; `invalid-argument` / `unknown-option` for a malformed result.
+
+***
+
+### 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?`): [`ExtractStep`](../type-aliases/ExtractStep.md)\<`F`\>
+
+Extracts up to `budget` pages. While a model's result is awaited, the step returns
+`{ state: "progress", phase: "model", request }` and does nothing more until
+[provide](#provide) answers it.
+
+#### Parameters
+
+##### budget?
+
+`number` = `1`
+
+#### Returns
+
+[`ExtractStep`](../type-aliases/ExtractStep.md)\<`F`\>
+
+progress, or `{ state: "done", output }` with the output in the job's format.
+
+#### Throws
+
+[LaminaPdfError](LaminaPdfError.md) `cancelled`, `document-changed`, `job-finished`, the reading errors.

package/docs/api/classes/Font.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/Image.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/LaminaPdfError.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/Page.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/PageRef.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/PageText.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/PageTextRun.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/PendingPath.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/SaveJob.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/classes/Surface.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)
@@ -20,13 +20,15 @@ geometry is reported by [Page.finish](Page.md#finish) (`invalid-geometry`).
 > **artifact**(`kind`, `draw`): `this`
 
 Draws what `draw` draws as an artifact: decoration, running heads and footers, backgrounds;
-content outside the structure tree.
+content outside the structure tree. `"header"`, `"footer"` and `"watermark"` are pagination
+artifacts that also say which (`/Subtype`), a header attached to the page's top edge and a
+footer to its bottom (`/Attached`).
 
 #### Parameters
 
 ##### kind
 
-`"layout"` \| `"page"` \| `"pagination"` \| `"background"`
+`"layout"` \| `"page"` \| `"pagination"` \| `"background"` \| `"header"` \| `"footer"` \| `"watermark"`
 
 ##### draw
 
@@ -273,7 +275,8 @@ Draws `text`: shaped, bidi-resolved, one line per line break (needs the text mod
 
 `TextRunJs`
 
-what the run measures.
+what the run measures, with `bottom`: where the next element can start (the next text box's top), the
+  descent below the last line that draws something, before the surface's transform; left out when nothing is.
 
 #### Throws
 
@@ -301,7 +304,9 @@ Lays `text` out in `options.box`, breaking lines at Unicode line-break opportuni
 
 `TextLayoutJs`
 
-the lines drawn and where the overflow starts (UTF-16 offsets).
+the lines drawn, where the overflow starts (UTF-16 offsets; test it with `!== undefined`, as `0` means no
+  line fitted) and `bottom`: the last line that draws something, before the surface's transform; left out when none
+  does.
 
 #### Throws
 

package/docs/api/classes/Transaction.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/functions/callbackSource.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/functions/extractWithModels.md

@@ -0,0 +1,70 @@
+---
+version: "0.2.0-alpha.5"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / extractWithModels
+
+# Function: extractWithModels()
+
+> **extractWithModels**\<`F`\>(`doc`, `options`, `models`, `__namedParameters?`): `Promise`\<[`ExtractResult`](../interfaces/ExtractResult.md)\[`F`\]\>
+
+Runs an extraction whose models the host runs asynchronously: steps a job, and for each
+request awaits the matching function of `models`, then hands its result back.
+
+## Type Parameters
+
+### F
+
+`F` *extends* [`ExtractFormat`](../type-aliases/ExtractFormat.md)
+
+## Parameters
+
+### doc
+
+[`Document`](../classes/Document.md)
+
+### options
+
+[`ExtractJobOptions`](../type-aliases/ExtractJobOptions.md)\<`F`\>
+
+### models
+
+[`HostModels`](../interfaces/HostModels.md)
+
+### \_\_namedParameters?
+
+#### budget?
+
+`number` = `16`
+
+#### signal?
+
+`AbortSignal`
+
+## Returns
+
+`Promise`\<[`ExtractResult`](../interfaces/ExtractResult.md)\[`F`\]\>
+
+## Example
+
+```ts
+const json = await extractWithModels(
+  doc,
+  { format: "json", models: { layout: { name: "my-layout", version: "1", sha256, licence: "Apache-2.0" } } },
+  { layout: async ({ page, dpi }) => myModel.detect(await render(page, dpi)) },
+);
+```
+On a document opened with `Document.openRange`, a step that needs bytes not yet fetched ends
+the job with `data-pending`, as every error ends a job; fetch the file first (`await
+doc.ensure(() => doc.pages)` reads only the page tree, so read the whole file for a long
+extraction), or wrap the call in `doc.ensure`, which runs it again, models included.
+
+## Throws
+
+[LaminaPdfError](../classes/LaminaPdfError.md) as [ExtractJob.step](../classes/ExtractJob.md#step); `invalid-argument` when
+  `options.models` names a model `models` has no function for; `cancelled` once `signal`
+  aborts, also when the model rejects because of it (the model's error is the `cause`).

package/docs/api/functions/httpRangeSource.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)
@@ -19,7 +19,7 @@ its `Last-Modified`); a response whose `ETag`, `Last-Modified` or total size dif
 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
+The server must allow `Range` (across origins: `Access-Control-Allow-Headers: Range, If-Range` and
 `Access-Control-Expose-Headers: Content-Range, Content-Length, ETag`) and must not compress
 the response.
 

package/docs/api/functions/init.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/functions/isExtractLoaded.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/functions/isInitialized.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/functions/isLaminaPdfError.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/functions/isTextLoaded.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/functions/loadExtract.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/functions/loadText.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/functions/onLeak.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/functions/reset.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/functions/wasmMemory.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/interfaces/BuilderOptions.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/interfaces/ByteRange.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/interfaces/ChunkOptions.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/interfaces/Diagnostic.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/interfaces/ExtractOptions.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/interfaces/ExtractResult.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/interfaces/FontInfo.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/interfaces/HostModels.md

@@ -0,0 +1,57 @@
+---
+version: "0.2.0-alpha.5"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / HostModels
+
+# Interface: HostModels
+
+The host's models for [extractWithModels](../functions/extractWithModels.md): each renders the page it is asked for and runs.
+
+## Properties
+
+### layout?
+
+> `readonly` `optional` **layout?**: (`request`, `signal`) => `Promise`\<readonly [`LayoutRegion`](LayoutRegion.md)[]\>
+
+A layout model's regions on `request.page`, rendered at `request.dpi`.
+
+#### Parameters
+
+##### request
+
+[`ModelRequest`](ModelRequest.md)
+
+##### signal
+
+`AbortSignal` \| `undefined`
+
+#### Returns
+
+`Promise`\<readonly [`LayoutRegion`](LayoutRegion.md)[]\>
+
+***
+
+### ocr?
+
+> `readonly` `optional` **ocr?**: (`request`, `signal`) => `Promise`\<readonly [`OcrWord`](OcrWord.md)[]\>
+
+An OCR engine's words on `request.page`, rendered at `request.dpi`, in `request.langs`.
+
+#### Parameters
+
+##### request
+
+[`ModelRequest`](ModelRequest.md)
+
+##### signal
+
+`AbortSignal` \| `undefined`
+
+#### Returns
+
+`Promise`\<readonly [`OcrWord`](OcrWord.md)[]\>

package/docs/api/interfaces/HttpRangeOptions.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)

package/docs/api/interfaces/InitOptions.md

@@ -1,5 +1,5 @@
 ---
-version: "0.2.0-alpha.3"
+version: "0.2.0-alpha.5"
 ---
 
 [**@laminapdf/sdk**](../README.md)