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

package/docs/api/functions/callbackSource.md

@@ -0,0 +1,33 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@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/extractWithModels.md

@@ -0,0 +1,70 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@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

@@ -0,0 +1,48 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@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, If-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`.

package/docs/api/functions/init.md

@@ -0,0 +1,36 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / init
+
+# Function: init()
+
+> **init**(`input?`): `Promise`\<`void`\>
+
+Loads the base WebAssembly module (fetched next to the package); with `{ text: true }`, the text
+module too. Idempotent: later calls return at once (or load the text module). Everything else
+in the package is synchronous and needs this promise to have resolved.
+
+## Parameters
+
+### input?
+
+[`WasmSource`](../type-aliases/WasmSource.md) \| [`InitOptions`](../interfaces/InitOptions.md)
+
+where the base module comes from (a URL, `Response`, bytes or
+  `WebAssembly.Module`), or options; omitted, the file next to the package.
+
+## Returns
+
+`Promise`\<`void`\>
+
+## Example
+
+```ts
+await init(); // or: await init({ text: true })
+```

package/docs/api/functions/isExtractLoaded.md

@@ -0,0 +1,21 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / isExtractLoaded
+
+# Function: isExtractLoaded()
+
+> **isExtractLoaded**(): `boolean`
+
+Whether documents opened or built from now on can extract text: the extract or the text module
+is loaded. A document opened earlier stays in the module it was opened in; ask it with
+[Document.canExtractText](../classes/Document.md#canextracttext).
+
+## Returns
+
+`boolean`

package/docs/api/functions/isInitialized.md

@@ -0,0 +1,19 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / isInitialized
+
+# Function: isInitialized()
+
+> **isInitialized**(): `boolean`
+
+Whether `init()` has finished.
+
+## Returns
+
+`boolean`

package/docs/api/functions/isLaminaPdfError.md

@@ -0,0 +1,41 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / isLaminaPdfError
+
+# Function: isLaminaPdfError()
+
+> **isLaminaPdfError**\<`C`\>(`e`, `code?`): `e is LaminaPdfError<C>`
+
+Whether `e` is a [LaminaPdfError](../classes/LaminaPdfError.md), with `code` when given.
+
+## Type Parameters
+
+### C
+
+`C` *extends* [`ErrorCode`](../type-aliases/ErrorCode.md)
+
+## Parameters
+
+### e
+
+`unknown`
+
+anything caught.
+
+### code?
+
+`C`
+
+the code to match.
+
+## Returns
+
+`e is LaminaPdfError<C>`
+
+true for a LaminaPdfError (with that code).

package/docs/api/functions/isTextLoaded.md

@@ -0,0 +1,19 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / isTextLoaded
+
+# Function: isTextLoaded()
+
+> **isTextLoaded**(): `boolean`
+
+Whether the text module is loaded (builders created now can draw text).
+
+## Returns
+
+`boolean`

package/docs/api/functions/loadExtract.md

@@ -0,0 +1,28 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / loadExtract
+
+# Function: loadExtract()
+
+> **loadExtract**(`source?`): `Promise`\<`void`\>
+
+Loads the extract module (reading plus text extraction). Documents opened afterwards can
+extract text with `page.text()`. Idempotent; not needed when the text module is loaded.
+
+## Parameters
+
+### source?
+
+[`WasmSource`](../type-aliases/WasmSource.md)
+
+where it comes from; omitted, the file next to the package.
+
+## Returns
+
+`Promise`\<`void`\>

package/docs/api/functions/loadText.md

@@ -0,0 +1,28 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / loadText
+
+# Function: loadText()
+
+> **loadText**(`source?`): `Promise`\<`void`\>
+
+Loads the text module (fonts, shaping and text layout; about 940 KB gzipped). Builders
+created afterwards can draw text. Idempotent.
+
+## Parameters
+
+### source?
+
+[`WasmSource`](../type-aliases/WasmSource.md)
+
+where it comes from; omitted, the file next to the package.
+
+## Returns
+
+`Promise`\<`void`\>

package/docs/api/functions/onLeak.md

@@ -0,0 +1,29 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / onLeak
+
+# Function: onLeak()
+
+> **onLeak**(`hook?`): `void`
+
+Reports every document, builder and image created from now on that the garbage collector
+reclaims without a `free()` or `using`: a debugging aid for code that should free what it
+makes. Reclaimed handles are freed anyway, only later. `onLeak()` turns the reports off.
+
+## Parameters
+
+### hook?
+
+(`leak`) => `void`
+
+called once per leaked handle, some time after the collection.
+
+## Returns
+
+`void`

package/docs/api/functions/reset.md

@@ -0,0 +1,22 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / reset
+
+# Function: reset()
+
+> **reset**(): `void`
+
+Replaces each loaded module's instance with a fresh one, so its memory returns to the size it
+had after `init()`: WebAssembly memory grows and never shrinks, and this gives it back. Every
+document, page, builder and save job made before throws `instance-reset` afterwards, so call it
+while none is in use, such as between jobs on a server. Images and fonts keep working.
+
+## Returns
+
+`void`

package/docs/api/functions/wasmMemory.md

@@ -0,0 +1,22 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / wasmMemory
+
+# Function: wasmMemory()
+
+> **wasmMemory**(): [`WasmMemory`](../interfaces/WasmMemory.md)
+
+The size of each loaded module's WebAssembly memory. Memory grows and never shrinks; freed
+documents and builders leave room that later ones reuse.
+
+## Returns
+
+[`WasmMemory`](../interfaces/WasmMemory.md)
+
+the byte length of each loaded module's memory.

package/docs/api/interfaces/BuilderOptions.md

@@ -0,0 +1,108 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / BuilderOptions
+
+# Interface: BuilderOptions
+
+Options for a new [Builder](../classes/Builder.md).
+
+## Extends
+
+- `Omit`\<[`BuildOptions`](../type-aliases/BuildOptions.md), `"id"`\>
+
+## Properties
+
+### compress?
+
+> `optional` **compress?**: `boolean`
+
+Flate-compress content streams (default `true`).
+
+#### Inherited from
+
+`Omit.compress`
+
+***
+
+### creationDate?
+
+> `optional` **creationDate?**: `string`
+
+`/CreationDate`, a PDF date (`D:20261030120000Z`).
+
+#### Inherited from
+
+`Omit.creationDate`
+
+***
+
+### id?
+
+> `readonly` `optional` **id?**: `string` \| `Uint8Array`\<`ArrayBufferLike`\>
+
+`/ID[0]`: 16 bytes, as 32 hex digits or a `Uint8Array` (default: derived from the content).
+
+***
+
+### producer?
+
+> `optional` **producer?**: `string`
+
+`/Producer`.
+
+#### Inherited from
+
+`Omit.producer`
+
+***
+
+### profiles?
+
+> `optional` **profiles?**: `ProfileInit`[]
+
+Conformance profiles: `PDF/UA-1` with at most one PDF/A profile. `finish` then fails
+with a coded error for each machine-checkable rule the document breaks.
+
+#### Inherited from
+
+`Omit.profiles`
+
+***
+
+### tagged?
+
+> `optional` **tagged?**: `boolean`
+
+A tagged document (structure tree, `/MarkInfo`) even before any element (default
+`false`; a page using `beginTag` or `beginArtifact` makes it tagged either way).
+
+#### Inherited from
+
+`Omit.tagged`
+
+***
+
+### text?
+
+> `readonly` `optional` **text?**: `boolean`
+
+Build in the text module (fonts and text). Default: when it is loaded. `true` without the
+text module loaded throws `text-module-not-loaded`.
+
+***
+
+### version?
+
+> `optional` **version?**: `PdfVersionInit`
+
+The header version (default 1.7).
+
+#### Inherited from
+
+`Omit.version`

package/docs/api/interfaces/ByteRange.md

@@ -0,0 +1,29 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / ByteRange
+
+# Interface: ByteRange
+
+A byte range of the input.
+
+## Properties
+
+### length
+
+> `readonly` **length**: `number`
+
+Number of bytes.
+
+***
+
+### offset
+
+> `readonly` **offset**: `number`
+
+First byte.

package/docs/api/interfaces/ChunkOptions.md

@@ -0,0 +1,37 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / ChunkOptions
+
+# Interface: ChunkOptions
+
+How the Markdown is cut into chunks.
+
+## Properties
+
+### maxTokens?
+
+> `readonly` `optional` **maxTokens?**: `number`
+
+A chunk's budget in approximate tokens (characters / 4); 512 by default. Blocks are never cut.
+
+***
+
+### overlap?
+
+> `readonly` `optional` **overlap?**: `number`
+
+Approximate tokens of whole blocks a chunk repeats from the one before it; 0 by default.
+
+***
+
+### splitOn?
+
+> `readonly` `optional` **splitOn?**: [`SplitOn`](../type-aliases/SplitOn.md)
+
+Where chunks may start.

package/docs/api/interfaces/Diagnostic.md

@@ -0,0 +1,67 @@
+---
+version: "0.2.0-alpha.4"
+---
+
+[**@laminapdf/sdk**](../README.md)
+
+***
+
+[@laminapdf/sdk](../README.md) / Diagnostic
+
+# Interface: Diagnostic\<C\>
+
+The ADR 0026 §1 object: what `LaminaPdfError.toJSON()` returns and the WASM throws.
+
+## Type Parameters
+
+### C
+
+`C` *extends* `string` = [`ErrorCode`](../type-aliases/ErrorCode.md)
+
+## Properties
+
+### code
+
+> `readonly` **code**: `C`
+
+***
+
+### data?
+
+> `readonly` `optional` **data?**: `Readonly`\<`Record`\<`string`, `unknown`\>\>
+
+***
+
+### didYouMean?
+
+> `readonly` `optional` **didYouMean?**: readonly `string`[]
+
+***
+
+### docsUrl
+
+> `readonly` **docsUrl**: `string`
+
+***
+
+### hint?
+
+> `readonly` `optional` **hint?**: `string`
+
+***
+
+### kind
+
+> `readonly` **kind**: [`ErrorKind`](../type-aliases/ErrorKind.md)
+
+***
+
+### location?
+
+> `readonly` `optional` **location?**: [`Location`](Location.md)
+
+***
+
+### message
+
+> `readonly` **message**: `string`