@2018kguo/recto 0.1.0 → 0.3.0

package/dist/engine.js

@@ -1,76 +1,151 @@
 // The per-thread engine: owns one WebAssembly instance and replaces it when it trapped or
 // its memory grew past the recycle mark (WebAssembly memory never shrinks). Past the mark, the
-// instance goes as soon as its last document closes; documents still open on an instance keep it.
-import { createGlue } from "../wasm/recto.gen.mjs";
-import { assetBaseUrl, canReadSync, fontFromBundle, loadAssetSync, loadWasm, preloadAssets, } from "./assets.js";
+// instance goes once nothing has been open on it for a moment, and a document still open on an
+// instance keeps it.
+import { PINS } from "../wasm/pins.mjs";
+import { createGlue, PART_TABLE } from "../wasm/recto.gen.mjs";
+import { assetBaseUrl, canReadSync, STANDARD_FONTS, compileWasm, loadAssetSync, preloadAssets, readCheckedSync, } from "./assets.js";
 import { engineFailure, RectoDocument, } from "./document.js";
 import { PdfError } from "./errors.js";
 import { ownedSource, startRangeLoader, } from "./ranged.js";
 const CJK_FONT_ASSET = 14;
 const CMAPS_ASSET = 15;
+const PARTS = ["recto-render.wasm", "recto-more.wasm", "recto-rare.wasm"];
+const ALL_ASSETS = [...STANDARD_FONTS, "cmaps.deflate", "cjk-fallback.ttf"];
+/**
+ * Past this, an open with another document still open gets a new instance. Chosen from
+ * bench/results/recycle.json: retiring at each close made a repeated large file slow.
+ */
+const IDLE_RECYCLE_ABOVE_BYTES = 64 * 1024 * 1024;
 const DEFAULT_RECYCLE_ABOVE_BYTES = 512 * 1024 * 1024;
-/** The wasm, verified and compiled once per thread, per location. */
+const IDLE_MS = 1000;
+/** Each wasm, verified and compiled once per thread, per location. */
+const compiling = new Map();
 const compiled = new Map();
-function compile(base) {
-    const key = base?.href ?? "";
+const moduleKey = (name, base) => `${name} ${base?.href ?? ""}`;
+function compile(name, base) {
+    const key = moduleKey(name, base);
+    let module = compiling.get(key);
+    if (!module) {
+        module = compileWasm(name, base);
+        module.then((done) => compiled.set(key, done), () => compiling.delete(key));
+        compiling.set(key, module);
+    }
+    return module;
+}
+/** A part, from inside a synchronous call. Hashed before it's compiled; this is the only way in but `compile`. */
+function partModule(name, base, hash) {
+    const key = moduleKey(name, base);
     let module = compiled.get(key);
     if (!module) {
-        module = loadWasm(base).then((bytes) => WebAssembly.compile(bytes).catch((error) => {
-            throw new PdfError("missing-asset", `recto could not compile recto.wasm: ${String(error)}. A Content-Security-Policy must allow 'wasm-unsafe-eval'.`, error);
-        }));
-        module.catch(() => compiled.delete(key));
+        module = new WebAssembly.Module(readCheckedSync(name, base, hash));
         compiled.set(key, module);
     }
     return module;
 }
-async function instantiate(generation, base) {
-    const module = await compile(base);
+/** An instance's own SHA-256, for an asset it needs: faster than JavaScript's in a cold browser. */
+export function hashOn(instance) {
+    return (bytes) => {
+        // A function the hash itself runs may be in a part, and that part's check can't use this hash.
+        if (instance.dead || hashing.has(instance)) {
+            return null;
+        }
+        hashing.add(instance);
+        try {
+            return Array.from(instance.glue.sha256(bytes), (byte) => byte.toString(16).padStart(2, "0")).join("");
+        }
+        finally {
+            hashing.delete(instance);
+        }
+    };
+}
+const hashing = new WeakSet();
+function instantiate(generation, base, module, documents = { open: 0 }) {
+    const parts = new Set();
+    // A function of a part that isn't loaded yet: load it, then make the call this was meant to be. A
+    // failure unwinds the engine's frames with its state half-done, so no call can follow on this
+    // instance. What was open on it reopens on another, at its next call.
+    const placeholders = (name) => new Proxy({}, {
+        get: (_, slot) => (...args) => {
+            try {
+                instance.loadPart(name);
+            }
+            catch (error) {
+                instance.abandoned = true;
+                throw error;
+            }
+            const table = exports[PART_TABLE];
+            return table.get(Number(slot))(...args);
+        },
+    });
     // Each instance gets its own glue closure (scripts/package-wasm.mjs), so a retired
     // instance and its memory are collected with it.
-    const glue = createGlue();
+    const glue = createGlue({
+        "part.recto-render": placeholders("recto-render.wasm"),
+        "part.recto-more": placeholders("recto-more.wasm"),
+        "part.recto-rare": placeholders("recto-rare.wasm"),
+    }, 
+    // Something never closed, freed by the collector. Nothing can run on an abandoned instance, which goes
+    // whole; and a free that needs a part it can't get has nobody to tell, and mustn't be an uncaught error.
+    (free) => {
+        if (instance.abandoned || instance.dead) {
+            return;
+        }
+        try {
+            free();
+        }
+        catch {
+            instance.abandoned = true;
+        }
+    });
     const exports = glue.initSync({ module });
     const instance = {
         glue,
+        loadPart(name) {
+            if (!parts.has(name)) {
+                // Its table entries replace its placeholders.
+                new WebAssembly.Instance(partModule(name, base, hashOn(instance)), { primary: exports });
+                parts.add(name);
+            }
+        },
         memory: exports.memory,
+        startBytes: exports.memory.buffer.byteLength,
         generation,
         openDocuments: 0,
+        documents,
         dead: false,
+        abandoned: false,
         failure: undefined,
     };
     // The engine asks for a built-in font (0..13), the CJK fallback or its predefined CMaps
     // the first time a document needs one. It reads a throw as a missing asset, which would
-    // be blank text, so keep the error for the call in progress to rethrow, and retire the
-    // instance so the next open tries again.
+    // be blank text, so keep the error for the call in progress to rethrow, and leave the instance
+    // so the next call tries again.
     glue.setAssetLoader((index) => {
         try {
             if (index === CMAPS_ASSET) {
-                return loadAssetSync("cmaps.brotli", base);
+                return loadAssetSync("cmaps.deflate", base, hashOn(instance));
             }
             if (index === CJK_FONT_ASSET) {
-                return loadAssetSync("cjk-fallback.ttf", base);
+                return loadAssetSync("cjk-fallback.ttf", base, hashOn(instance));
             }
-            return fontFromBundle(loadAssetSync("fonts.bin", base), index);
+            return loadAssetSync(STANDARD_FONTS[index], base, hashOn(instance));
         }
         catch (error) {
-            instance.dead = true;
+            instance.abandoned = true;
             instance.failure = error;
             return;
         }
     });
     return instance;
 }
-/**
- * A copy of the caller's bytes, taken before anything asynchronous, so the buffer is theirs
- * again the moment the call returns its promise. (The engine then copies them into WebAssembly
- * memory, so the file is held twice for the length of the open.)
- */
-function ownedBytes(input) {
+function bytesOf(input) {
     if (ArrayBuffer.isView(input)) {
-        return new Uint8Array(input.buffer, input.byteOffset, input.byteLength).slice();
+        return new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
     }
     // Not instanceof: an ArrayBuffer from another realm (a test runner's sandbox) is just as good.
     if (Object.prototype.toString.call(input) === "[object ArrayBuffer]") {
-        return new Uint8Array(input).slice();
+        return new Uint8Array(input);
     }
     throw new TypeError("expected the PDF's bytes as a Uint8Array, Buffer or ArrayBuffer");
 }
@@ -85,48 +160,120 @@ class RectoEngine {
     #starting = null;
     #base;
     #recycleAboveBytes;
+    /** Past this, an instance with a document open takes no other. */
+    #idleAboveBytes;
+    /** Whether an instance that grew goes once nothing has been open on it for IDLE_MS: the default. */
+    #dropWhenIdle;
+    #idle;
+    /** Across every instance: a document that moved, or stayed on an old one, still counts. */
+    #documents;
     constructor(instance, base, recycleAboveBytes) {
         this.#instance = instance;
         this.#generation = instance.generation;
         this.#base = base;
-        this.#recycleAboveBytes = recycleAboveBytes;
+        this.#recycleAboveBytes = recycleAboveBytes ?? DEFAULT_RECYCLE_ABOVE_BYTES;
+        this.#idleAboveBytes = recycleAboveBytes ?? IDLE_RECYCLE_ABOVE_BYTES;
+        this.#dropWhenIdle = recycleAboveBytes === undefined;
+        this.#documents = instance.documents;
         this.#watch(instance);
     }
     /** Memory only comes back with the instance, so don't keep one past the mark with nothing on it. */
     #watch(instance) {
         instance.onClose = () => {
-            if (this.#instance === instance &&
-                instance.openDocuments === 0 &&
-                instance.memory.buffer.byteLength > this.#recycleAboveBytes) {
+            if (this.#instance !== instance || instance.openDocuments > 0) {
+                return;
+            }
+            const bytes = instance.memory.buffer.byteLength;
+            if (bytes > this.#recycleAboveBytes) {
                 this.#instance = null;
             }
+            else if (this.#dropWhenIdle ? bytes > instance.startBytes : bytes > this.#idleAboveBytes) {
+                clearTimeout(this.#idle);
+                this.#idle = setTimeout(() => {
+                    // Node's fired timer keeps its callback, and with it the instance.
+                    this.#idle = undefined;
+                    if (this.#instance === instance && instance.openDocuments === 0) {
+                        this.#instance = null;
+                    }
+                }, IDLE_MS);
+                // Not a reason for Node to stay running.
+                this.#idle.unref?.();
+            }
         };
     }
+    /** Whether a new document can go on this instance. */
+    #usable(instance) {
+        if (!instance || instance.dead || instance.abandoned) {
+            return false;
+        }
+        const bytes = instance.memory.buffer.byteLength;
+        return bytes <= this.#idleAboveBytes || (bytes <= this.#recycleAboveBytes && instance.openDocuments === 0);
+    }
+    #ready() {
+        return this.#usable(this.#instance) ? this.#instance : null;
+    }
     async #live() {
         const current = this.#instance;
-        if (current && !current.dead && current.memory.buffer.byteLength <= this.#recycleAboveBytes) {
+        if (this.#usable(current)) {
             return current;
         }
-        this.#starting ??= instantiate(this.#generation + 1, this.#base).finally(() => {
+        this.#starting ??= compile("recto.wasm", this.#base)
+            .then((module) => instantiate(this.#generation + 1, this.#base, module, this.#documents))
+            .finally(() => {
             this.#starting = null;
         });
         const started = await this.#starting;
-        this.#generation = started.generation;
-        this.#instance = started;
-        this.#watch(started);
+        this.#adopt(started);
         return started;
     }
+    #adopt(instance) {
+        this.#generation = instance.generation;
+        this.#instance = instance;
+        this.#watch(instance);
+    }
+    /** An instance for a document to reopen on, its own having been abandoned. Synchronous: every call is. */
+    #another() {
+        const current = this.#instance;
+        if (this.#usable(current)) {
+            return current;
+        }
+        // Compiled already: it's what the abandoned instance ran.
+        const instance = instantiate(this.#generation + 1, this.#base, compiled.get(moduleKey("recto.wasm", this.#base)), this.#documents);
+        this.#adopt(instance);
+        return instance;
+    }
     // Async only so a bad argument rejects; everything up to the copy runs synchronously.
     async open(input, options = {}) {
-        return await this.openOwned(ownedBytes(input), options);
+        // With an instance ready, the bytes go into its memory before the first await, and that's
+        // the copy the promise needs: no second one of what may be a large file.
+        const ready = this.#ready();
+        const bytes = bytesOf(input);
+        if (ready) {
+            throwIfAborted(options.signal);
+            return this.#openOn(ready, bytes, options);
+        }
+        return await this.openOwned(bytes.slice(), options);
     }
     /** `bytes` is this call's own: getting an instance can take an await. */
     async openOwned(bytes, options) {
         throwIfAborted(options.signal);
-        const instance = await this.#live();
+        return this.#openOn(await this.#live(), bytes, options);
+    }
+    #openOn(instance, bytes, options) {
+        const password = options.password ?? null;
         let doc;
         try {
-            doc = new RectoDocument(instance, new instance.glue.Document(bytes, options.password ?? null));
+            // Where the file is, read now: an abandoned instance may run nothing.
+            let opened = new instance.glue.Document(bytes, password);
+            let pointer = opened.filePointer();
+            const length = opened.fileLength();
+            doc = new RectoDocument(instance, opened, (_, oldInstance) => {
+                const next = this.#another();
+                // The file goes straight from the old heap to the new one.
+                opened = new next.glue.Document(new Uint8Array(oldInstance.memory.buffer, pointer, length), password);
+                pointer = opened.filePointer();
+                return { instance: next, doc: opened };
+            });
         }
         catch (error) {
             throw engineFailure(instance, error);
@@ -148,9 +295,17 @@ class RectoEngine {
             const out = new Uint8Array(length);
             return loader.read(offset, out) ? out : undefined;
         };
+        const password = options.password ?? null;
         let doc;
         try {
-            doc = new RectoDocument(instance, instance.glue.Document.openRanged(loader.length, loader.chunkBytes, read, options.password ?? null), () => loader.failure);
+            doc = new RectoDocument(instance, instance.glue.Document.openRanged(loader.length, loader.chunkBytes, read, password), () => {
+                // Nothing is fetched twice: the loader keeps what it read.
+                const next = this.#another();
+                return {
+                    instance: next,
+                    doc: next.glue.Document.openRanged(loader.length, loader.chunkBytes, read, password),
+                };
+            }, () => loader.failure);
         }
         catch (error) {
             if (loader.failure && !(error instanceof WebAssembly.RuntimeError)) {
@@ -168,7 +323,7 @@ class RectoEngine {
         return {
             heapBytes: this.#instance?.memory.buffer.byteLength ?? 0,
             generation: this.#generation,
-            openDocuments: this.#instance?.openDocuments ?? 0,
+            openDocuments: this.#documents.open,
         };
     }
 }
@@ -177,12 +332,28 @@ export async function createPdfEngine(options = {}) {
 }
 async function createEngine(options) {
     const base = assetBaseUrl(options.assetBase);
-    if (!canReadSync()) {
-        await preloadAssets(base, options.preloadAssets ?? ["fonts.bin", "cmaps.brotli", "cjk-fallback.ttf"]);
+    const canRead = canReadSync();
+    for (const asset of options.preloadAssets ?? []) {
+        if (asset !== "cmaps.brotli" && asset !== "fonts.bin" && !Object.hasOwn(PINS, asset)) {
+            const accepted = [...Object.keys(PINS), "cmaps.brotli", "fonts.bin"].join(", ");
+            throw new TypeError(`preloadAssets does not know ${JSON.stringify(asset)}. It takes: ${accepted}`);
+        }
     }
-    return new RectoEngine(await instantiate(0, base), base, options.recycleAboveBytes ?? DEFAULT_RECYCLE_ABOVE_BYTES);
+    // cmaps.brotli is the old name of cmaps.deflate, and fonts.bin of all the fonts together.
+    const names = (options.preloadAssets ?? (canRead ? [] : ALL_ASSETS)).flatMap((asset) => asset === "cmaps.brotli" ? "cmaps.deflate" : asset === "fonts.bin" ? STANDARD_FONTS : asset);
+    const isPart = (name) => PARTS.includes(name);
+    const files = names.filter((name) => name !== "recto.wasm" && !isPart(name));
+    // With no way to read a part from inside a call, all of them now, always: nothing listed can take
+    // away the ability to draw.
+    const [module] = await Promise.all([
+        compile("recto.wasm", base),
+        ...(canRead ? names.filter(isPart) : PARTS).map((part) => compile(part, base)),
+        preloadAssets(base, files),
+    ]);
+    return new RectoEngine(instantiate(0, base, module), base, options.recycleAboveBytes);
 }
 let shared = null;
+let sharedReady = null;
 /**
  * Opens a PDF on this thread's shared engine:
  *
@@ -190,10 +361,17 @@ let shared = null;
  *   doc.pageCount; doc.text(0); doc.render(0, { width: 1024 });
  */
 export async function openPdf(bytes, options = {}) {
-    const owned = ownedBytes(bytes);
+    if (sharedReady) {
+        return sharedReady.open(bytes, options);
+    }
+    // Getting the engine takes an await: the buffer has to be the caller's again before it.
+    const owned = bytesOf(bytes).slice();
     if (!shared) {
         const starting = createEngine({});
         shared = starting;
+        starting.then((engine) => {
+            sharedReady = engine;
+        }, () => { });
         // A failure is not kept: the next call tries again.
         starting.catch(() => {
             if (shared === starting) {

package/dist/errors.d.ts

@@ -22,7 +22,7 @@ export type PdfErrorCode =
  | "wrong-thread"
 /** A ranged read failed: the network, an HTTP error, or a server's bad Range answer. */
  | "fetch-failed"
-/** A ranged read waited longer than `timeoutMs`. */
+/** A ranged read waited longer than `timeoutMs`, or passed `totalTimeoutMs`. */
  | "timeout"
 /** A ranged read would pass `maxBytes`, or the file is past what a ranged read can hold. */
  | "too-large"
@@ -30,5 +30,7 @@ export type PdfErrorCode =
  | "failed";
 export declare class PdfError extends Error {
     readonly code: PdfErrorCode;
-    constructor(code: PdfErrorCode, message: string, cause?: unknown);
+    /** On `fetch-failed`, the HTTP status of the answer it objects to. Undefined if the server never answered. */
+    readonly status: number | undefined;
+    constructor(code: PdfErrorCode, message: string, cause?: unknown, status?: number);
 }

package/dist/errors.js

@@ -3,9 +3,12 @@
 // plain RangeError or TypeError instead: that is a bug to fix, not a condition to handle.
 export class PdfError extends Error {
     code;
-    constructor(code, message, cause) {
+    /** On `fetch-failed`, the HTTP status of the answer it objects to. Undefined if the server never answered. */
+    status;
+    constructor(code, message, cause, status) {
         super(message, cause === undefined ? undefined : { cause });
         this.name = "PdfError";
         this.code = code;
+        this.status = status;
     }
 }

package/dist/index.d.ts

@@ -1,7 +1,18 @@
-export { ANNOT_SUBTYPE, boxAt, CHAR_GENERATED, CHAR_UNMAPPED, charsText, PATH_FILL, PATH_STROKE, type PdfAnnotation, type PdfBitmap, type PdfBox, type PdfDocument, type PdfFont, type PdfOutlineItem, type PdfPageInfo, type PdfPageObjects, type PdfPageText, type PdfPathSegments, type PdfRenderOptions, type PdfTextRuns, type PdfWords, SEGMENT_BEZIER, SEGMENT_CLOSE, SEGMENT_LINE, SEGMENT_MOVE, SEGMENT_RECT, } from "./document.ts";
+export { ANNOT_SUBTYPE, boxAt, CHAR_GENERATED, CHAR_UNMAPPED, charsText, PATH_FILL, PATH_STROKE, type PdfAnnotation, type PdfBitmap, type PdfBox, type PdfDocument, type PdfFont, type PdfOutlineItem, type PdfPageInfo, type PdfPageObjects, type PdfPageText, type PdfPathSegments, type PdfRenderAsyncOptions, type PdfRenderOptions, type PdfTextRuns, type PdfWords, SEGMENT_BEZIER, SEGMENT_CLOSE, SEGMENT_LINE, SEGMENT_MOVE, SEGMENT_RECT, } from "./document.ts";
 export { createPdfEngine, openPdf, type PdfEngine, type PdfEngineOptions, type PdfEngineStats, type PdfOpenOptions, } from "./engine.ts";
 export { PdfError, type PdfErrorCode } from "./errors.ts";
+export type { PdfPool, PdfPoolDocument, PdfPoolOpenOptions, PdfPoolOptions } from "./pool.ts";
 export { type PageBox, rasterMeasures, showsGlyphs, vectorMeasures, } from "./page-measures.ts";
 export type { PdfRangedDocument, PdfRangedOpenOptions, PdfRangedStats, PdfRangeSource, } from "./ranged.ts";
 export { BREAK_LINE, BREAK_NONE, BREAK_SPACE, readingOrder, type ReadingOrder, } from "./reading-order.ts";
 export { annotationPaintedText, annotationShownText, annotationTextItems, NOT_TEXT, type PdfTextItem, textItems, visibleCodepoint, } from "./text-items.ts";
+/**
+ * Runs a document's pages across worker threads:
+ *
+ *   using pool = await createPdfPool();
+ *   await using doc = await pool.open(bytes);
+ *   const pages = await Promise.all(Array.from({ length: doc.pageCount }, (_, i) => doc.text(i)));
+ *
+ * Loaded only when called, so a program that doesn't use it doesn't download it.
+ */
+export declare function createPdfPool(options?: import("./pool.ts").PdfPoolOptions): Promise<import("./pool.ts").PdfPool>;

package/dist/index.js

@@ -8,3 +8,16 @@ export { PdfError } from "./errors.js";
 export { rasterMeasures, showsGlyphs, vectorMeasures, } from "./page-measures.js";
 export { BREAK_LINE, BREAK_NONE, BREAK_SPACE, readingOrder, } from "./reading-order.js";
 export { annotationPaintedText, annotationShownText, annotationTextItems, NOT_TEXT, textItems, visibleCodepoint, } from "./text-items.js";
+/**
+ * Runs a document's pages across worker threads:
+ *
+ *   using pool = await createPdfPool();
+ *   await using doc = await pool.open(bytes);
+ *   const pages = await Promise.all(Array.from({ length: doc.pageCount }, (_, i) => doc.text(i)));
+ *
+ * Loaded only when called, so a program that doesn't use it doesn't download it.
+ */
+export async function createPdfPool(options = {}) {
+    const { startPool } = await import("./pool.js");
+    return startPool(options);
+}

package/dist/pool-worker.d.ts

@@ -0,0 +1,14 @@
+export type PoolRequest = {
+    id: number;
+    doc: number;
+    /** Only until this thread has the document. */
+    open?: {
+        bytes: Uint8Array;
+        password: string | undefined;
+    };
+    method: string;
+    args: unknown[];
+};
+export type PoolStart = {
+    assetBase: string | undefined;
+};

package/dist/pool-worker.js

@@ -0,0 +1,65 @@
+// One thread of a pool: opens what it's sent on demand, and answers each call with its result.
+import { createPdfEngine } from "./engine.js";
+const parent = globalThis.process?.getBuiltinModule?.("node:worker_threads")?.parentPort;
+const port = (parent ?? self);
+const docs = new Map();
+let engine;
+/** Every column in a result, so it moves rather than being copied. */
+function buffersIn(value, found) {
+    if (ArrayBuffer.isView(value)) {
+        found.add(value.buffer);
+    }
+    else if (typeof value === "object" && value !== null) {
+        for (const inner of Object.values(value)) {
+            buffersIn(inner, found);
+        }
+    }
+}
+async function answer({ doc: id, open, method, args }) {
+    let doc = docs.get(id);
+    if (!doc) {
+        doc = await engine.open(open.bytes, open.password === undefined ? {} : { password: open.password });
+        docs.set(id, doc);
+    }
+    if (method === "pageCount") {
+        return doc.pageCount;
+    }
+    return doc[method](...args);
+}
+function failureOf(error) {
+    const { name, code, message } = error;
+    return { name, code, message: message ?? String(error) };
+}
+async function handle(message) {
+    if (!("id" in message)) {
+        const { assetBase } = message;
+        try {
+            engine = await createPdfEngine(assetBase ? { assetBase } : {});
+            port.postMessage({ ready: true }, []);
+        }
+        catch (error) {
+            port.postMessage({ startFailed: true, failure: failureOf(error) }, []);
+        }
+        return;
+    }
+    if (message.method === "close") {
+        docs.get(message.doc)?.close();
+        docs.delete(message.doc);
+        return;
+    }
+    try {
+        const result = await answer(message);
+        const buffers = new Set();
+        buffersIn(result, buffers);
+        port.postMessage({ result, opened: docs.has(message.doc) }, [...buffers]);
+    }
+    catch (error) {
+        port.postMessage({ failure: failureOf(error), opened: docs.has(message.doc) }, []);
+    }
+}
+if (parent) {
+    parent.on("message", (message) => void handle(message));
+}
+else {
+    self.onmessage = ({ data }) => void handle(data);
+}

package/dist/pool.d.ts

@@ -0,0 +1,36 @@
+import type { PdfAnnotation, PdfBitmap, PdfOutlineItem, PdfPageInfo, PdfPageObjects, PdfPageText, PdfRenderOptions } from "./document.ts";
+export type PdfPoolOptions = {
+    /** At most this many threads, up to 64. Default: one less than the machine's cores, up to 8. */
+    threads?: number;
+    /** As for `createPdfEngine`. A string: it crosses to the threads. */
+    assetBase?: string;
+};
+export type PdfPoolOpenOptions = {
+    password?: string;
+};
+/** A `PdfDocument` whose calls run on the pool's threads, each a promise. */
+export interface PdfPoolDocument {
+    readonly pageCount: number;
+    pageInfo(index: number): Promise<PdfPageInfo>;
+    text(index: number): Promise<PdfPageText>;
+    objects(index: number): Promise<PdfPageObjects>;
+    annotations(index: number): Promise<PdfAnnotation[]>;
+    outline(): Promise<PdfOutlineItem[]>;
+    /** Takes no `signal`: a call that's running can't be stopped. */
+    render(index: number, options: PdfRenderOptions): Promise<PdfBitmap>;
+    /** Frees it on every thread, and fails its calls still waiting with `closed`. */
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export interface PdfPool {
+    open(bytes: Uint8Array | ArrayBuffer, options?: PdfPoolOpenOptions): Promise<PdfPoolDocument>;
+    /** Threads started so far, and calls waiting for one. */
+    stats(): {
+        threads: number;
+        queued: number;
+    };
+    /** Stops every thread now: anything unfinished fails with `closed`. */
+    close(): void;
+    [Symbol.dispose](): void;
+}
+export declare function startPool(options: PdfPoolOptions): PdfPool;