@web-ts-toolkit/pdf-reader 0.42.2 → 0.47.1

package/index.d.mts

@@ -14,7 +14,12 @@ type PdfTypedArray = Int8Array | Uint8Array | Uint8ClampedArray | Int16Array | U
  * PDF.js `getDocument(...)` source accepted by the package root.
  *
  * Prefer trusted in-memory bytes when possible. PDF.js may transfer typed-array
- * ownership to its worker during load.
+ * ownership to its worker during load, detaching the caller's buffer: keep no
+ * further use of the buffer after `load()` starts and retry a detached-input
+ * failure with fresh bytes. In-memory `data` references stay borrowed (never
+ * copied by the package), so only the byte size is re-validated after source
+ * policy approval; concurrent byte-content mutation is caller-visible and
+ * unsupported.
  */
 type PdfSource = string | URL | ArrayBuffer | PdfTypedArray | number[] | PdfDocumentInitParameters;
 type TransformMatrix = readonly [number, number, number, number, number, number];
@@ -29,10 +34,20 @@ type PageImageOutputMode = 'data-url' | 'blob';
  * rejected and a later `load()` call will start a fresh attempt.
  */
 type PdfReaderState = 'new' | 'loading' | 'loaded' | 'iterating' | 'failed' | 'destroyed';
-/** PDF.js text output without requiring consumers to import PDF.js internals. */
+/** PDF.js text output; use `pdfTextToString` to assemble plain text without importing PDF.js internals. */
 type PdfTextContent = Awaited<ReturnType<PDFPageProxy['getTextContent']>>;
 interface PdfReaderLimits {
-    /** Maximum known in-memory source bytes accepted before PDF.js starts loading. Unset by default. */
+    /**
+     * Maximum known in-memory source bytes accepted before PDF.js starts loading. Unset by default.
+     *
+     * The limit counts PDF.js byte conversion: binary-string code units (one
+     * byte each), number-array entries (one byte each), and buffer/view
+     * `byteLength` (sliced views count only their slice). It is checked before
+     * source-policy approval and rechecked after approval, so growth during
+     * approval still fails before loading. Remote downloads have no
+     * synchronously knowable length and stay application-owned via
+     * fetch/range transport controls.
+     */
     maxSourceBytes?: number;
     /** Maximum number of document pages accepted after loading. Defaults to 1,000. */
     maxDocumentPages?: number;
@@ -55,17 +70,32 @@ interface PdfReaderLogger {
     warn(message: string, error?: unknown): void;
 }
 interface PdfReaderSourceInfo {
-    /** Immutable shallow snapshot that will be passed to PDF.js if policy allows it. */
+    /**
+     * Immutable shallow snapshot that will be passed to PDF.js if policy allows it.
+     *
+     * Stabilized request fields (`url` as a string, `httpHeaders` as an owned
+     * frozen record) are read once before policy approval, so later caller
+     * mutation or getter re-evaluation cannot change the effective request.
+     * Opaque objects (`data` bytes, `worker`, factories, range transports) are
+     * deliberately borrowed by reference and pass through unchanged; the
+     * snapshot freezes only the outer params object, not recursive contents.
+     */
     rawSource: Readonly<PdfDocumentInitParameters>;
     /** Broad source shape so callers can distinguish direct bytes from URL-based inputs. */
     kind: 'bytes' | 'url' | 'document-init-parameters';
     /** Normalized URL string when one is present on the source. */
     url?: string;
-    /** Known byte length for direct byte sources and `DocumentInitParameters.data` when synchronously measurable. */
+    /** Known byte length for direct byte sources and `DocumentInitParameters.data` when synchronously measurable: binary-string length, array length, or buffer/view `byteLength`. Remote URL sources report `undefined`; their response-byte limits remain application-owned. */
     byteLength?: number;
     /** True when the source carries any custom HTTP headers. */
     hasHttpHeaders: boolean;
-    /** Shallow copy of recognized HTTP headers when the source uses a plain object. */
+    /**
+     * Owned frozen copy of the effective HTTP headers enumerated exactly as
+     * PDF.js consumes them (`for...in`, inherited included, `undefined`
+     * skipped, values string-coerced). Non-plain containers (e.g. `Headers`)
+     * report `hasHttpHeaders: true` with no value entries rather than a
+     * false-equivalent record; gate on `hasHttpHeaders` to block them.
+     */
     httpHeaders?: Readonly<Record<string, string>>;
     /** Whether PDF.js would send credentials for URL-based loading. */
     withCredentials: boolean;
@@ -81,21 +111,44 @@ interface PdfReaderOptions {
     sourcePolicy?: PdfReaderSourcePolicy;
 }
 interface LoadOptions {
-    /** Cancels only the current load caller, not other callers sharing the same underlying PDF.js task. */
+    /**
+     * Cancels only the current load caller, not other callers sharing the same underlying PDF.js task.
+     * Structurally validated across realms: boolean `aborted`, callable
+     * `addEventListener`/`removeEventListener`. Omitted/`undefined` means no
+     * signal; `null` and malformed values throw `INVALID_OPTION` before loading,
+     * including when the document is already loaded.
+     */
     signal?: AbortSignal;
-    /** Caller-local deadline in milliseconds for waiting on `load()`. */
+    /** Caller-local deadline in milliseconds for waiting on `load()`. Must be a positive finite number not exceeding 2,147,483,647 (the maximum browser/Node timer delay); larger values are rejected with `INVALID_OPTION`. */
     deadlineMs?: number;
 }
 interface ConvertOptions {
+    /**
+     * 1-based page selection: one page number or an inclusive `[start, end]`
+     * tuple. Reversed tuples are normalized; defaults to all pages.
+     */
     pageRange?: PageRange;
+    /** Render scale factor or page-size callback. Defaults to `1.5`. */
     viewportScale?: ViewportScale;
+    /** Page render format. Defaults to `'image/png'`. */
     imageFormat?: PageImageMimeType;
+    /** JPEG quality from `0` through `1`, applied only to `'image/jpeg'`. Defaults to `0.92`; PNG output ignores it. */
     jpegQuality?: number;
+    /** Render the full page under `page.pageImage`. Defaults to `true`. */
     includePageImage?: boolean;
+    /** Page-image payload shape. Defaults to `'data-url'`. */
     pageImageOutput?: PageImageOutputMode;
+    /** Include PDF.js `TextContent` under `page.text`. Defaults to `true`. */
     includeText?: boolean;
+    /** Best-effort embedded raster extraction under `page.images`. Defaults to `false`. */
     includeEmbeddedImages?: boolean;
-    /** Stops between expensive steps and cancels an active page render. */
+    /**
+     * Stops between expensive steps, including after canvas/viewport callbacks, and settles page-stage waits promptly. Active renders are cancelled. Cancellation/failure of an already-created render permanently closes the reader and starts public teardown; the initiating call keeps ABORTED/native error, while later operations reject DESTROYED. Retry requires a fresh reader and fresh bytes. Pre-render/non-render cancellation and encoding cancellation after successful rendering permit same-reader reuse; other started PDF.js work stays observed, and cleanup waits for cached-page ownership to become idle (or destruction). A suspended pages() consumer observes cancellation on resume.
+     * Structurally validated across realms: boolean `aborted`, callable
+     * `addEventListener`/`removeEventListener`. Omitted/`undefined` means no
+     * signal; `null` and malformed values reject with `INVALID_OPTION` before
+     * page acquisition and release the operation lock for valid reuse.
+     */
     signal?: AbortSignal;
 }
 interface DataUrlPageImage {
@@ -114,14 +167,30 @@ type PageImageResult = DataUrlPageImage | BlobPageImage;
 interface ExtractedImage {
     /** Best-effort PNG data URL copied from a PDF.js image object. */
     dataUrl: string;
+    /** Left edge in PDF user-space units, before viewport scaling. */
     x: number;
+    /**
+     * Upper bound in PDF user-space units, before viewport scaling.
+     *
+     * `y` is the top of the transformed unit square (`max` of the mapped
+     * corners), not the baseline origin.
+     */
     y: number;
+    /** Width in PDF user-space units, before viewport scaling. */
     width: number;
+    /** Height in PDF user-space units, before viewport scaling. */
     height: number;
+    /**
+     * Decoded PDF.js image source size in bytes (`dataLen` when reported,
+     * else raw `data.byteLength`). Not the encoded PNG data-URL length.
+     */
     size: number;
     mimeType: 'image/png';
+    /** Unscaled page width in PDF user-space units (`viewport.width / viewport.scale`). */
     pageWidth: number;
+    /** Unscaled page height in PDF user-space units (`viewport.height / viewport.scale`). */
     pageHeight: number;
+    /** Full six-value graphics transform active when the image was painted. */
     transform: TransformMatrix;
 }
 interface PageResult {
@@ -168,17 +237,95 @@ declare class PDFReader {
      * use supported PDF.js read methods, but must not call `destroy()` on the
      * proxy while the reader owns lifecycle teardown. Call `reader.destroy()` to
      * release document and worker resources.
+     * After explicit destruction or automatic closure of an interrupted render,
+     * throws `DESTROYED` synchronously before validating options or starting work.
+     *
+     * Signals are structurally validated across realms: boolean `aborted` and
+     * callable `addEventListener`/`removeEventListener`. Omitted/`undefined`
+     * means no signal; `null` and malformed values throw `INVALID_OPTION`
+     * synchronously, even when already loaded, before policy/PDF.js work.
      */
     load(signal?: AbortSignal): Promise<PDFDocumentProxy>;
     load(options?: LoadOptions): Promise<PDFDocumentProxy>;
-    /** Streams page results so callers do not need to retain the entire document conversion in memory. */
+    /**
+     * Streams page results so callers do not need to retain the entire document conversion in memory.
+     *
+     * Page-stage waits (`getPage`, text, operator list, render, encoding) settle
+     * promptly with `ABORTED`/`DESTROYED` via the shared cancellation/wait
+     * contract. Active renders are cancelled; racing other PDF.js work does not
+     * stop it. Already-started promises remain observed even if a synchronous
+     * callback aborts/destroys before wait registration. Late `getPage()` values
+     * are never processed; late text/operator values are dropped. Page cleanup
+     * is deferred until package-owned acquisitions, processing, and upstream
+     * stage promises for that cached page are idle, including safe retries.
+     * Canvas factories and viewport callbacks are followed by lifecycle checks
+     * before subsequent allocation/rendering. Caller settlement releases the
+     * operation lock, but does not imply upstream work has finished.
+     * Cancellation/failure of an already-created render permanently closes the
+     * reader and starts public PDF.js teardown. The initiating call retains
+     * `ABORTED` or the native error; later operations reject `DESTROYED`. Retry
+     * with a fresh reader and fresh bytes (PDF.js may have transferred the input).
+     * Pre-render and non-render failures, and encoding cancellation/failure after
+     * successful rendering, do not automatically close the reader.
+     * A suspended generator only observes abort/destroy on the next
+     * `next()`/`return()`; destruction cannot force suspended consumer code to run.
+     * Malformed signals (including `null`) reject with `INVALID_OPTION` before
+     * page acquisition. Omitted/`undefined` signals are accepted.
+     */
     pages(options?: ConvertOptions): AsyncGenerator<PageResult>;
     /** Collects `pages()` into an array. Prefer `pages()` for large documents. */
     convert(options?: ConvertOptions): Promise<PageResult[]>;
-    /** Terminates the loading task and document resources. The reader cannot be reused afterwards. */
+    /**
+     * Terminates the loading task and document resources. The reader cannot be reused afterwards.
+     *
+     * A caller-created PDF.js `PDFWorker` passed on the source stays
+     * caller-owned: neither `destroy()` nor PDF.js task teardown destroys it.
+     * Destroy it explicitly in your own `finally` block, even if this method
+     * rejects.
+     *
+     * In-flight page-stage waiters settle promptly with `DESTROYED`, but their
+     * uncancellable getPage/text/operator work stays observed in the background.
+     * Active renders are cancelled. This method waits for PDF.js loading/document
+     * destruction, not for orphaned `getPage`/text/operator/image-object
+     * continuations, which never start later processing. It clears retained
+     * page ownership; late acquisitions receive best-effort cleanup. Await
+     * active operations to observe their temporary canvas release. It cannot
+     * force a suspended `pages()` consumer to resume; that consumer observes
+     * destruction on next resume.
+     * Render cancellation/failure also starts this teardown automatically without
+     * awaiting it or replacing the initiating error. This method always returns
+     * the same teardown promise, including its rejection; call it to observe that
+     * outcome. Automatic teardown rejection is observed even if you never do.
+     */
     destroy(): Promise<void>;
 }
 
+/**
+ * Assemble already-extracted PDF.js text in supplied item order, without mutation.
+ *
+ * Preserves each string verbatim, including whitespace and Unicode. Appends one
+ * `\n` after each text item with `hasEOL: true`, even an empty or final item;
+ * existing newlines are not deduplicated and trailing whitespace is not trimmed.
+ * Marked-content entries are skipped. XFA-style string items without `hasEOL`
+ * contribute their string only. Empty or marker-only content returns `''`.
+ *
+ * No spaces are guessed between fragments. This is not OCR, layout/reading-order
+ * reconstruction, or streaming extraction; PDF.js has already materialized the
+ * content (and may have normalized its text). The helper allocates a new string
+ * and applies no resource limits of its own. Display untrusted text via
+ * `textContent`, not HTML.
+ *
+ * @param content - Raw page text, such as `PageResult.text` when present.
+ * @returns Concatenated text with explicit PDF.js end-of-line markers honored.
+ * @example
+ * ```ts
+ * import { pdfTextToString } from '@web-ts-toolkit/pdf-reader';
+ *
+ * if (page.text) output.textContent = pdfTextToString(page.text);
+ * ```
+ */
+declare function pdfTextToString(content: PdfTextContent): string;
+
 interface PdfUrlSourceOptions {
     /** Basic authentication headers forwarded to PDF.js URL loading. */
     httpHeaders?: Readonly<Record<string, string>>;
@@ -224,7 +371,11 @@ declare function pdfUrlSource(url: string | URL, options?: PdfUrlSourceOptions):
  *
  * When passing an existing DOM `Worker`, the caller retains ownership of
  * terminating it.
+ *
+ * A caller-created PDF.js `PDFWorker` passed on a `PdfSource` is likewise
+ * never destroyed by the reader or by PDF.js task teardown: destroy it
+ * explicitly in a `finally` block, even when `reader.destroy()` rejects.
  */
 declare function configurePdfWorker(worker: string | Worker): void;
 
-export { type BlobPageImage, type ConvertOptions, type DataUrlPageImage, type ExtractedImage, type LoadOptions, type LoadedPdfDocument, type LoadedPdfPage, PDFReader, type PageImageMimeType, type PageImageOutputMode, type PageImageResult, type PageRange, type PageResult, type PdfDocumentInitParameters, PdfReaderError, type PdfReaderErrorCode, type PdfReaderLimits, type PdfReaderLogger, type PdfReaderOptions, type PdfReaderSourceInfo, type PdfReaderSourcePolicy, type PdfReaderState, type PdfSource, type PdfTextContent, type PdfTypedArray, type PdfUrlSource, type PdfUrlSourceOptions, type TransformMatrix, type ViewportScale, configurePdfWorker, pdfUrlSource };
+export { type BlobPageImage, type ConvertOptions, type DataUrlPageImage, type ExtractedImage, type LoadOptions, type LoadedPdfDocument, type LoadedPdfPage, PDFReader, type PageImageMimeType, type PageImageOutputMode, type PageImageResult, type PageRange, type PageResult, type PdfDocumentInitParameters, PdfReaderError, type PdfReaderErrorCode, type PdfReaderLimits, type PdfReaderLogger, type PdfReaderOptions, type PdfReaderSourceInfo, type PdfReaderSourcePolicy, type PdfReaderState, type PdfSource, type PdfTextContent, type PdfTypedArray, type PdfUrlSource, type PdfUrlSourceOptions, type TransformMatrix, type ViewportScale, configurePdfWorker, pdfTextToString, pdfUrlSource };