@2018kguo/recto 0.1.0 → 0.5.0

package/dist/engine.js

@@ -1,76 +1,154 @@
 // 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, maxDecodedBytes, 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;
         }
     });
+    if (maxDecodedBytes !== undefined) {
+        glue.setMaxDecodedBytes(maxDecodedBytes);
+    }
     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 +163,122 @@ class RectoEngine {
     #starting = null;
     #base;
     #recycleAboveBytes;
-    constructor(instance, base, recycleAboveBytes) {
+    #maxDecodedBytes;
+    /** 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, maxDecodedBytes) {
+        this.#maxDecodedBytes = maxDecodedBytes;
         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.#maxDecodedBytes, 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.#maxDecodedBytes, 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);
@@ -143,14 +295,22 @@ class RectoEngine {
         }
         const owned = ownedSource(source);
         const instance = await this.#live();
-        const loader = startRangeLoader(owned, options);
-        const read = (offset, length) => {
+        const loader = await startRangeLoader(owned, options);
+        const read = (offset, length, ahead) => {
             const out = new Uint8Array(length);
-            return loader.read(offset, out) ? out : undefined;
+            return loader.read(offset, out, ahead) ? 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 +328,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 +337,32 @@ 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),
+    ]);
+    const maxDecodedBytes = options.maxDecodedBytes;
+    if (maxDecodedBytes !== undefined && !(typeof maxDecodedBytes === "number" && maxDecodedBytes >= 0)) {
+        throw new RangeError("maxDecodedBytes must be a number of bytes, 0 or more");
+    }
+    return new RectoEngine(instantiate(0, base, module, maxDecodedBytes), base, options.recycleAboveBytes, maxDecodedBytes);
 }
 let shared = null;
+let sharedReady = null;
 /**
  * Opens a PDF on this thread's shared engine:
  *
@@ -190,10 +370,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 PdfDestination, type PdfDocument, type PdfFont, type PdfLink, type PdfLinkTarget, type PdfOutlineItem, type PdfPageInfo, type PdfPageObjects, type PdfPageText, type PdfPathSegments, type PdfRegionBitmap, 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,15 @@
+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;
+    maxDecodedBytes: number | 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, maxDecodedBytes } = message;
+        try {
+            engine = await createPdfEngine({ ...(assetBase ? { assetBase } : {}), ...(maxDecodedBytes === undefined ? {} : { maxDecodedBytes }) });
+            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,42 @@
+import type { PdfAnnotation, PdfBitmap, PdfBox, PdfLink, PdfOutlineItem, PdfPageInfo, PdfPageObjects, PdfPageText, PdfRegionBitmap, 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;
+    /** As for `createPdfEngine`, on every thread. */
+    maxDecodedBytes?: number;
+};
+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[]>;
+    links(index: number): Promise<PdfLink[]>;
+    outline(): Promise<PdfOutlineItem[]>;
+    /** Takes no `signal`: a call that's running can't be stopped. */
+    render(index: number, options: PdfRenderOptions & {
+        region: PdfBox;
+    }): Promise<PdfRegionBitmap>;
+    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;