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

package/dist/document.d.ts

@@ -0,0 +1,267 @@
+import type { WasmDocument, WasmPage, WasmSaveJob } from "@laminapdf/wasm/base";
+import { type LaminaPdfWarning } from "./errors.js";
+import { type ExtractFormat, type ExtractOptions, type ExtractResult } from "./extract.js";
+import { type BaseGlue } from "./init.js";
+import { Handle } from "./internal/handle.js";
+import type { Instance } from "./internal/instance.js";
+import { type RangeOptions, type RangeSource, type RangeState } from "./source/range.js";
+import { PageText, type TextOptions } from "./text.js";
+import { Transaction } from "./transaction.js";
+import type { DocumentInfo, Edited, Op, OpenOptions, OpLog, PageInfo, Progress, SaveOptions, SaveReport, UndoOutcome } from "./types.js";
+/**
+ * A page of a {@link Document}, held by its ID: moving pages doesn't retarget it (ADR 0028 F2).
+ * Freed with its document; every call after that throws `disposed`.
+ */
+export declare class PageRef extends Handle<BaseGlue> {
+    #private;
+    /** @internal */
+    constructor(page: WasmPage, doc: Document, instance: Instance<BaseGlue>);
+    /** The page's stable ID (`p12.0`). */
+    get id(): string;
+    /** The page's current 0-based index. @throws {@link LaminaPdfError} `unknown-page` when it is gone. */
+    get index(): number;
+    /** The page's facts now. @throws {@link LaminaPdfError} `unknown-page` when it is gone. */
+    get info(): PageInfo;
+    /**
+     * The page's text: lines in reading order, runs, and every glyph's quad in page space.
+     * Needs a document opened while the extract or text module was loaded.
+     *
+     * @example
+     * ```ts
+     * await init({ extract: true });
+     * const doc = Document.open(bytes);
+     * const text = doc.page(0).text().text();
+     * ```
+     * @param options - `skipInvisible` leaves out invisible text (OCR layers).
+     * @throws {@link LaminaPdfError} `extract-module-not-loaded` for a document opened in the base
+     *   module; `unknown-page`; reading errors (`data-pending` for a range document: use `ensure`).
+     */
+    text(options?: TextOptions): PageText;
+    protected release(): void;
+}
+/**
+ * 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`.
+ */
+export declare class SaveJob extends Handle<BaseGlue> {
+    #private;
+    /** @internal */
+    constructor(job: WasmSaveJob, doc: Document, instance: Instance<BaseGlue>);
+    /**
+     * Runs at most `budget` work units.
+     *
+     * @returns `{ state: "progress", … }`, or `{ state: "done", bytes, report }` at the end.
+     * @throws {@link LaminaPdfError} `cancelled`, `document-changed`, `job-finished`, or the save's errors.
+     */
+    step(budget: number): ({
+        readonly state: "progress";
+    } & Progress) | {
+        readonly state: "done";
+        readonly bytes: Uint8Array<ArrayBuffer>;
+        readonly report: SaveReport;
+    };
+    /** Stops the job: its next step fails with `cancelled`. */
+    cancel(): void;
+    protected release(): void;
+}
+/**
+ * An open PDF: read it, edit it with ops (atomic transactions with undo), save it. It holds
+ * WebAssembly memory: free it with `using` or {@link Document.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" });
+ * ```
+ */
+export declare class Document extends Handle<BaseGlue> {
+    #private;
+    /**
+     * @internal Wraps a raw document (from `open`, `openRange` or `Builder.finish`) of `instance`.
+     */
+    constructor(doc: WasmDocument, instance: Instance<BaseGlue>, range?: RangeState);
+    /**
+     * Opens a document whose bytes are fetched range by range ({@link httpRangeSource},
+     * {@link callbackSource}): 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 {@link Document.ensure}.
+     *
+     * @param source - the file (or a promise of it, as `httpRangeSource` returns).
+     * @param options - open options (password, strict, limits) and fetch options.
+     * @returns the document, once open has everything it needs.
+     * @throws {@link LaminaPdfError} as {@link Document.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.
+     */
+    static openRange(source: RangeSource | Promise<RangeSource>, options?: OpenOptions & RangeOptions): Promise<Document>;
+    /**
+     * Runs a synchronous call on this document, fetching what it needs first: for a document
+     * from {@link Document.openRange}, a `data-pending` makes it fetch the ranges asked for and
+     * call `f` again. For other documents it just returns `f()`.
+     *
+     * @example
+     * ```ts
+     * const doc = await Document.openRange(httpRangeSource(url));
+     * const pages = await doc.ensure(() => doc.pages);
+     * ```
+     * @param f - 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.
+     * @param options - `signal` aborts this call's fetches (the open's signal applies to the open
+     *   only).
+     * @returns what `f` returns.
+     * @throws what `f` throws, and as {@link Document.openRange}.
+     */
+    ensure<T>(f: () => T | Promise<T>, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<T>;
+    /**
+     * 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.
+     *
+     * @param bytes - the PDF file.
+     * @param options - password, strict mode, limits.
+     * @returns the document.
+     * @throws {@link LaminaPdfError} `not-pdf`, `password-required`, `wrong-password`, `limit-exceeded`,
+     *   `strict`, …; `unknown-option` / `invalid-argument` for bad options; `not-initialized`.
+     */
+    static open(bytes: Uint8Array | ArrayBuffer, options?: OpenOptions): Document;
+    /**
+     * 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.
+     */
+    get canExtractText(): boolean;
+    /** The number of pages. @throws {@link LaminaPdfError} reading errors. */
+    get pageCount(): number;
+    /** Every page's facts, in order (one page-tree walk). @throws {@link LaminaPdfError} reading errors. */
+    get pages(): readonly PageInfo[];
+    /**
+     * Page `index`'s facts.
+     *
+     * @throws {@link LaminaPdfError} `page-index-out-of-range`.
+     */
+    pageInfo(index: number): PageInfo;
+    /**
+     * A handle on page `index` that follows the page by its ID.
+     *
+     * @throws {@link LaminaPdfError} `page-index-out-of-range`.
+     */
+    page(index: number): PageRef;
+    /**
+     * A handle on the page with `id` (`p12.0`).
+     *
+     * @throws {@link LaminaPdfError} `invalid-argument`, `unknown-page`.
+     */
+    pageById(id: string): PageRef;
+    /**
+     * 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.
+     *
+     * @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 } });
+     * ```
+     * @returns a string for `"markdown"` and `"text"`, an {@link Extraction} for `"json"`,
+     *   {@link Chunk}s for `"chunks"`.
+     * @throws {@link LaminaPdfError} `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`).
+     */
+    extract<F extends ExtractFormat>(options: ExtractOptions<F>): ExtractResult[F];
+    /** The Info dictionary's text entries (document text). @throws {@link LaminaPdfError} reading errors. */
+    get info(): DocumentInfo;
+    /** Every warning so far (build warnings first), each the ADR 0026 §1 object. */
+    get warnings(): readonly LaminaPdfWarning[];
+    /** Whether there are changes no save has written yet. */
+    get hasUnsavedChanges(): boolean;
+    /**
+     * Applies `ops` in order as one transaction: all of them, or none.
+     *
+     * @returns the pages the edit touched.
+     * @throws {@link LaminaPdfError} `unknown-option` / `invalid-argument` for a value that isn't an op;
+     *   the first failing op's error (`unknown-page`, …), with nothing applied.
+     */
+    apply(ops: readonly Op[]): Edited;
+    /**
+     * Applies an op log (`{ v: 1, ops }`, as JSON text or an object) as one transaction.
+     *
+     * @throws {@link LaminaPdfError} `invalid-op-log`, `unsupported-version`; as {@link Document.apply}.
+     */
+    applyLog(log: string | OpLog): Edited;
+    /**
+     * 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.
+     *
+     * @param edit - collects ops on `tx`; synchronous only (a callback returning a promise is
+     *   refused with `invalid-argument` and nothing is applied).
+     * @returns what `edit` returned.
+     * @throws {@link LaminaPdfError} `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 {@link Document.apply}.
+     * @example
+     * ```ts
+     * doc.transact((tx) => {
+     *   tx.setInfo({ title: "Report" });
+     *   tx.rotatePage(doc.page(0).id, 90);
+     * });
+     * ```
+     */
+    transact<T>(edit: (tx: Transaction) => T): T;
+    /**
+     * Undoes the newest transaction.
+     *
+     * @returns how it went, or `undefined` when there is nothing to undo.
+     * @throws {@link LaminaPdfError} `saved-not-rebased`; reading errors.
+     */
+    undo(): UndoOutcome | undefined;
+    /**
+     * Redoes the newest undone transaction.
+     *
+     * @returns how it went, or `undefined` when there is nothing to redo.
+     * @throws {@link LaminaPdfError} as {@link Document.undo}.
+     */
+    redo(): UndoOutcome | undefined;
+    /**
+     * Saves and rebases onto the output (later edits and saves build on it).
+     *
+     * @param options - `mode` (`auto`, `incremental`, `fullRewrite`), overrides, output form.
+     * @returns the file's bytes.
+     * @throws {@link LaminaPdfError} `would-invalidate-signatures`, `requires-rewrite`, `encrypted-base`, …
+     */
+    save(options?: SaveOptions): Uint8Array<ArrayBuffer>;
+    /**
+     * As {@link Document.save}, with the save's report (mode used, bytes written, renumbering, …).
+     *
+     * @throws {@link LaminaPdfError} as {@link Document.save}.
+     */
+    saveWithReport(options?: SaveOptions): {
+        readonly bytes: Uint8Array<ArrayBuffer>;
+        readonly report: SaveReport;
+    };
+    /**
+     * A save as a job stepped by the caller (to keep a UI responsive).
+     *
+     * @throws {@link LaminaPdfError} `unknown-option` / `invalid-argument` for bad options.
+     */
+    saveJob(options?: SaveOptions): SaveJob;
+    /**
+     * Rebases onto `bytes`, the output of a save whose rebase failed (`not-rebased`).
+     *
+     * @throws {@link LaminaPdfError} `no-pending-save`; reading errors in `bytes`.
+     */
+    rebase(bytes: Uint8Array): void;
+    protected release(): void;
+}
+//# sourceMappingURL=document.d.ts.map

package/dist/document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.d.ts","sourceRoot":"","sources":["../src/document.ts"],"names":[],"mappings":"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"}