@2018kguo/recto 0.3.0 → 0.5.1

package/dist/pool.js

@@ -39,6 +39,7 @@ class Pool {
     #limit;
     #ceiling;
     #assetBase;
+    #maxDecodedBytes;
     #threads = [];
     /** Started and not yet ready. */
     #startingThreads = new Set();
@@ -46,10 +47,11 @@ class Pool {
     #nextFile = 0;
     #nextId = 0;
     #closed = false;
-    constructor(limit, assetBase) {
+    constructor(limit, assetBase, maxDecodedBytes) {
         this.#limit = limit;
         this.#ceiling = limit;
         this.#assetBase = assetBase;
+        this.#maxDecodedBytes = maxDecodedBytes;
     }
     #spawn() {
         const thread = { worker: null, running: null };
@@ -147,7 +149,7 @@ class Pool {
                 };
                 thread.worker = worker;
             }
-            const start = { assetBase: this.#assetBase };
+            const start = { assetBase: this.#assetBase, maxDecodedBytes: this.#maxDecodedBytes };
             thread.worker.postMessage(start);
         }
         catch (error) {
@@ -240,13 +242,15 @@ class Pool {
             text: (index) => call("text", index),
             objects: (index) => call("objects", index),
             annotations: (index) => call("annotations", index),
+            links: (index) => call("links", index),
             outline: () => call("outline"),
-            render: (index, renderOptions) => {
+            render: ((index, renderOptions) => {
                 if (renderOptions?.signal) {
                     return Promise.reject(new TypeError("a pool's render takes no signal: a call that's running can't be stopped. pool.close() ends all of them."));
                 }
-                return call("render", index, { width: renderOptions?.width, maxHeight: renderOptions?.maxHeight });
-            },
+                const { width, maxHeight, region } = renderOptions ?? {};
+                return call("render", index, region === undefined ? { width, maxHeight } : { width, maxHeight, region });
+            }),
             close,
             [Symbol.asyncDispose]: close,
         };
@@ -283,5 +287,9 @@ export function startPool(options) {
     const assetBase = options.assetBase !== undefined && typeof location !== "undefined"
         ? new URL(options.assetBase, location.href).href
         : options.assetBase;
-    return new Pool(threads, assetBase);
+    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 Pool(threads, assetBase, maxDecodedBytes);
 }

package/dist/ranged.d.ts

@@ -43,19 +43,37 @@ export type PdfRangedStats = {
 export type PdfRangedDocument = PdfDocument & {
     stats(): PdfRangedStats;
 };
+/**
+ * Bytes `start..end`. With `yieldTail`, read no further than that many bytes before the file's
+ * end, where a suffix asked for beside it starts, so no byte comes twice.
+ */
 type Range = {
     start: number;
     end: number;
+    yieldTail?: number;
+};
+/** The file's last `suffix` bytes (`bytes=-n`), asked for before its size is known. */
+type Suffix = {
+    suffix: number;
 };
+type Request = Range | Suffix;
+/** `received`: the bytes read off the response, `bytes` and any read past it. */
 type Answer = {
     start: number;
     bytes: Uint8Array;
     length: number;
     etag: string | null;
     status: number;
+    received: number;
 };
-/** Fetches `ranges`; `limit` is how many bytes may still arrive. */
-type Fetch = (ranges: Range[], timeoutMs: number, limit: number) => Answer[];
+/**
+ * Fetches `requests` in parallel; `limit` is how many bytes may still arrive. A range that
+ * fails throws. A suffix that isn't answered as one (a server that ignores or refuses it)
+ * gives null, and isn't counted: the caller asks for the tail by its offset instead.
+ */
+type Answers = (Answer | null)[];
+type Fetch = (requests: Request[], timeoutMs: number, limit: number) => Answers;
+type FetchAsync = (requests: Request[], timeoutMs: number, limit: number) => Promise<Answers>;
 /** Fetched chunks of one file and the policy for fetching more. */
 declare class RangeLoader {
     #private;
@@ -71,25 +89,37 @@ declare class RangeLoader {
         signal: AbortSignal | undefined;
     });
     stats(): PdfRangedStats;
-    /** Fetches chunks `firstChunk..endChunk`, keeping only those not held yet. */
-    fetchChunks(firstChunk: number, endChunk: number): void;
+    /**
+     * The first round: the head and, in parallel, the tail as a suffix, then the last
+     * cross-reference section if the tail didn't hold it. A file the head covers needs no more;
+     * a server that doesn't answer the suffix gets the tail by offset in a round of its own.
+     */
+    begin(fetchAsync: FetchAsync | null): Promise<void>;
+    /**
+     * `failure`, or when what's held shows the file isn't a PDF (see `notPdfBytes`), that it isn't: an
+     * error or sign-in page fails to parse, or runs into `maxBytes`, and neither says why. Only when
+     * enough of the first KiB is held to tell.
+     */
+    explain(failure: unknown): unknown;
     /**
      * The `startxref` offset in the fetched last chunk, if it names one. Null for a linearized
      * file, whose trailer points at the first-page section near the head.
      */
     startxref(): number | null;
     /**
-     * Copies [offset, offset + out.length) into `out`, fetching what is missing first. On a
-     * failed fetch it records the failure and fails the read; the call that made it then
-     * throws the failure.
+     * Copies [offset, offset + out.length) into `out`, fetching what is missing first, and if it
+     * fetches, `ahead` bytes past it too, as far as the budget allows: the engine's guess at what
+     * it reads next, which then costs no round trip of its own. On a failed fetch it records the
+     * failure and fails the read; the call that made it then throws the failure.
      */
-    read(offset: number, out: Uint8Array): boolean;
+    read(offset: number, out: Uint8Array, ahead?: number): boolean;
 }
 /**
- * Starts a ranged read of `source`: the head, then (for a larger file) the tail and its last
- * cross-reference section. Blocks while it fetches.
+ * Starts a ranged read of `source`: the head and tail, then the last cross-reference section
+ * if the tail didn't hold it. Blocks while it fetches, except in a browser, where these
+ * rounds are `fetch` calls.
  */
-export declare function startRangeLoader(source: string | Uint8Array, options?: PdfRangedOpenOptions): RangeLoader;
+export declare function startRangeLoader(source: string | Uint8Array, options?: PdfRangedOpenOptions): Promise<RangeLoader>;
 /**
  * The caller's source in a form that stays valid across an await: bytes copied, a URL as an
  * absolute http(s) string. Runs before anything asynchronous.