unpdf 1.9.1 → 2.0.0

package/dist/index.d.mts

@@ -1,98 +1,130 @@
 import { DocumentInitParameters, PDFDocumentProxy } from "./types/src/display/api.js";
-import { Canvas, SKRSContext2D } from "@napi-rs/canvas";
-import { Metadata } from "./types/src/display/metadata.js";
+import "./types/src/display/optional_content_config.js";
 import * as PDFJS from "./types/src/pdf.js";
-//#region src/_internal/canvas.d.ts
-interface CanvasFactoryContext {
-  canvas?: HTMLCanvasElement | Canvas;
-  context?: CanvasRenderingContext2D | SKRSContext2D | null;
-}
+import { Metadata, Metadata as Metadata$1 } from "./types/src/display/metadata.js";
 /**
- * Derived from the PDF.js project by the Mozilla Foundation.
- * @see https://github.com/mozilla/pdf.js/blob/b8de9a372f9bbf7e33adb362eeae5ef1919dba73/src/display/canvas_factory.js#L18
- * @license Apache-2.0
+ * Axis-aligned box in PDF user space, origin bottom-left: in the coordinates of
+ * the page's `/MediaBox`, unrotated by its `/Rotate`, and unscaled by its
+ * `/UserUnit`.
  */
-declare class BaseCanvasFactory {
-  #private;
-  constructor({ enableHWA }?: {
-    enableHWA?: boolean | undefined;
-  });
-  create(width: number, height: number): {
-    canvas: Canvas | HTMLCanvasElement;
-    context: SKRSContext2D | CanvasRenderingContext2D | null;
-  };
-  reset({ canvas }: CanvasFactoryContext, width: number, height: number): void;
-  destroy(context: CanvasFactoryContext): void;
-  _createCanvas(width: number, height: number): HTMLCanvasElement | Canvas;
-}
-/**
- * Derived from the PDF.js project by the Mozilla Foundation.
- * @see https://github.com/mozilla/pdf.js/blob/b8de9a372f9bbf7e33adb362eeae5ef1919dba73/src/display/canvas_factory.js#L18
- * @license Apache-2.0
- */
-declare class DOMCanvasFactory extends BaseCanvasFactory {
-  _document: Document;
-  constructor({ ownerDocument, enableHWA }?: {
-    ownerDocument?: Document | undefined;
-    enableHWA?: boolean | undefined;
-  });
-  _createCanvas(width: number, height: number): HTMLCanvasElement;
+interface Bounds {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
 }
-declare class NodeCanvasFactory extends BaseCanvasFactory {
-  constructor({ enableHWA }?: {
-    enableHWA?: boolean | undefined;
-  });
-  _createCanvas(width: number, height: number): Canvas;
+interface ExtractImagesOptions {
+  /**
+   * Encoding of each image's `data`: raw RGBA pixels, or a PNG file.
+   *
+   * @default 'rgba'
+   */
+  format?: "rgba" | "png";
 }
-//#endregion
-//#region src/image.d.ts
-interface ExtractedImageObject {
-  data: Uint8ClampedArray;
+interface ExtractedImage {
+  /** RGBA pixels, four bytes per pixel, row by row from the top – or PNG bytes with `format: 'png'`. */
+  data: Uint8Array;
   width: number;
   height: number;
-  channels: 1 | 3 | 4;
-  key: string;
+  /** PDF.js object ID of the image, `null` for a small inline image, which PDF.js passes without one. */
+  key: string | null;
+  /** Box the image covers on the page, in PDF user space with the origin at the bottom left. */
+  bounds: Bounds;
 }
 /**
- * Extracts images from a specific page of a PDF document, including necessary metadata,
- * such as width, height, and calculated color channels.
+ * Extracts the images painted on a page – image XObjects, inline images, and
+ * image masks – as RGBA pixels. Image masks come out opaque black where they
+ * paint and transparent elsewhere, since their color is the fill color at the
+ * time of painting. A 1×1 image mask that paints its pixel, which PDF.js
+ * turns into a solid fill, is skipped.
+ *
+ * @remarks
+ * A caller-supplied document proxy created with `isOffscreenCanvasSupported`
+ * or `isImageDecoderSupported` (both on by default outside of Node.js) hands
+ * some images out as bitmaps instead of pixels, which are skipped.
  */
-declare function extractImages$1(data: DocumentInitParameters['data'] | PDFDocumentProxy, pageNumber: number): Promise<ExtractedImageObject[]>;
-declare function renderPageAsImage$1(data: DocumentInitParameters['data'] | PDFDocumentProxy, pageNumber: number, options?: {
-  canvasImport?: () => Promise<typeof import('@napi-rs/canvas')>;
-  /** @default 1.0 */
+export declare function extractImages(data: DocumentInitParameters["data"] | PDFDocumentProxy, pageNumber: number, options?: ExtractImagesOptions): Promise<ExtractedImage[]>;
+interface RenderPageAsImageOptions {
+  canvasImport?: () => Promise<typeof import("@napi-rs/canvas")>;
+  /** @default 1 */
   scale?: number;
   width?: number;
   height?: number;
+  /** @default 'png' */
+  format?: "png" | "jpeg" | "webp";
+  /** Encoder quality from 0 to 1, for `jpeg` and `webp` only. */
+  quality?: number;
+  toDataURL?: boolean;
+}
+export declare function renderPageAsImage(data: DocumentInitParameters["data"] | PDFDocumentProxy, pageNumber: number, options?: RenderPageAsImageOptions & {
   toDataURL?: false;
-}): Promise<ArrayBuffer>;
-declare function renderPageAsImage$1(data: DocumentInitParameters['data'] | PDFDocumentProxy, pageNumber: number, options: {
-  canvasImport?: () => Promise<typeof import('@napi-rs/canvas')>;
-  /** @default 1.0 */
-  scale?: number;
-  width?: number;
-  height?: number;
+}): Promise<Uint8Array>;
+export declare function renderPageAsImage(data: DocumentInitParameters["data"] | PDFDocumentProxy, pageNumber: number, options: RenderPageAsImageOptions & {
   toDataURL: true;
 }): Promise<string>;
-export declare function createIsomorphicCanvasFactory(canvasImport?: () => Promise<typeof import('@napi-rs/canvas')>): Promise<typeof DOMCanvasFactory | typeof NodeCanvasFactory>;
-//#endregion
-//#region src/links.d.ts
-declare function extractLinks$1(data: DocumentInitParameters['data'] | PDFDocumentProxy): Promise<{
+export declare function renderPageAsImage(data: DocumentInitParameters["data"] | PDFDocumentProxy, pageNumber: number, options?: RenderPageAsImageOptions): Promise<Uint8Array | string>;
+interface PageInspection {
+  /** Characters of all text on the page, visible or not, whitespace excluded. */
+  textLength: number;
+  /**
+   * Characters that paint nothing: drawn with text rendering mode 3 or 7 –
+   * typically the OCR layer of a scan – or in a layer the document hides.
+   * Whitespace excluded.
+   */
+  invisibleTextLength: number;
+  /** Image XObjects, inline images, and image masks painted on the page. */
+  imageCount: number;
+  /**
+   * Fraction of the page's view box covered by images, from 0 to 1. Overlapping
+   * images count once, and a rotated or skewed image counts with its
+   * axis-aligned bounds.
+   */
+  imageCoverage: number;
+}
+/**
+ * Measures the text and images of every page, such as to tell scanned pages
+ * from born-digital ones. Where that line lies is left to the caller.
+ */
+export declare function inspectPages(data: DocumentInitParameters["data"] | PDFDocumentProxy): Promise<{
   totalPages: number;
-  links: string[];
+  pages: PageInspection[];
 }>;
-//#endregion
-//#region src/meta.d.ts
-declare function getMeta$1(data: DocumentInitParameters['data'] | PDFDocumentProxy, options?: {
-  parseDates?: boolean;
+export declare function extractLinks(data: DocumentInitParameters["data"] | PDFDocumentProxy): Promise<{
+  totalPages: number;
+  links: string[][];
+}>;
+interface PDFInfo<DateValue = string> {
+  PDFFormatVersion: string;
+  Language: string | null;
+  EncryptFilterName: string | null;
+  IsLinearized: boolean;
+  IsAcroFormPresent: boolean;
+  IsXFAPresent: boolean;
+  IsCollectionPresent: boolean;
+  IsSignaturesPresent: boolean;
+  Title?: string;
+  Author?: string;
+  Subject?: string;
+  Keywords?: string;
+  Creator?: string;
+  Producer?: string;
+  CreationDate?: DateValue;
+  ModDate?: DateValue;
+  Trapped?: {
+    name: string;
+  };
+  /** Non-standard `/Info` entries, keyed by their PDF name. */
+  Custom?: Map<string, string | number | boolean | {
+    name: string;
+  }>;
+}
+export declare function getMeta<ParseDates extends boolean = false>(data: DocumentInitParameters["data"] | PDFDocumentProxy, options?: {
+  parseDates?: ParseDates;
 }): Promise<{
-  info: Record<string, any>;
-  metadata: Metadata;
+  info: PDFInfo<ParseDates extends true ? Date | null : string>;
+  metadata: Metadata$1 | null;
 }>;
-//#endregion
-//#region src/text.d.ts
 interface StructuredTextItem {
-  /** Text content. */
   str: string;
   /** X position in PDF coordinate space (origin: bottom-left). */
   x: number;
@@ -104,77 +136,50 @@ interface StructuredTextItem {
   height: number;
   /** Font size derived from the transformation matrix. */
   fontSize: number;
-  /** Font family resolved from the page's style table, empty when unknown. */
+  /** Font family, empty when unknown. */
   fontFamily: string;
-  /** Text direction: `"ltr"`, `"rtl"`, or `"ttb"`. */
-  dir: string;
-  /** Whether the text item is followed by a line break. */
+  dir: "ltr" | "rtl" | "ttb";
   hasEOL: boolean;
 }
-declare function extractTextItems$1(data: DocumentInitParameters['data'] | PDFDocumentProxy): Promise<{
+export declare function extractTextItems(data: DocumentInitParameters["data"] | PDFDocumentProxy): Promise<{
   totalPages: number;
   items: StructuredTextItem[][];
 }>;
-declare function extractText$1(data: DocumentInitParameters['data'] | PDFDocumentProxy, options?: {
+export declare function extractText(data: DocumentInitParameters["data"] | PDFDocumentProxy, options?: {
   mergePages?: false;
 }): Promise<{
   totalPages: number;
   text: string[];
 }>;
-declare function extractText$1(data: DocumentInitParameters['data'] | PDFDocumentProxy, options: {
+export declare function extractText(data: DocumentInitParameters["data"] | PDFDocumentProxy, options: {
   mergePages: true;
 }): Promise<{
   totalPages: number;
   text: string;
 }>;
-declare function extractText$1(data: DocumentInitParameters['data'] | PDFDocumentProxy, options?: {
+export declare function extractText(data: DocumentInitParameters["data"] | PDFDocumentProxy, options?: {
   mergePages?: boolean;
 }): Promise<{
   totalPages: number;
   text: string | string[];
 }>;
-//#endregion
-//#region src/config.d.ts
 /**
- * Sets the PDF.js build every other method uses – call it before any of them.
- * Without it, the serverless build is used.
+ * Creates a `PDFDocumentProxy` from binary PDF data, with `useSystemFonts:
+ * true`. In Node.js with `pdfjs-dist` installed, it uses that package's
+ * standard fonts instead of system fonts, and its packed CMaps.
+ */
+export declare function getDocumentProxy(data: DocumentInitParameters["data"], options?: DocumentInitParameters): Promise<PDFDocumentProxy>;
+/**
+ * Sets the PDF.js build every other method uses. The build loads on first use,
+ * so call this before any other method. Without it, the serverless build is
+ * used.
  *
  * @example
  * // In Node.js, the legacy build of `pdfjs-dist` (install it first)
  * import { definePDFJSModule } from 'unpdf'
  *
- * await definePDFJSModule(() => import('pdfjs-dist/legacy/build/pdf.mjs'))
- */
-export declare function definePDFJSModule(pdfjs: () => Promise<any>): Promise<void>;
-/** @deprecated Use `definePDFJSModule` instead. Will be removed in v2. */
-export declare function configureUnPDF(options: {
-  pdfjs?: () => Promise<any>;
-}): Promise<void>;
-//#endregion
-//#region src/utils.d.ts
-/**
- * Creates a `PDFDocumentProxy` from binary PDF data.
- *
- * Applies the following defaults:
- * - `useSystemFonts: true`
- *
- * In Node.js environments, additionally applies:
- * - `disableFontFace: true`
- * - `standardFontDataUrl` resolved from the local `pdfjs-dist` package
- * - `cMapUrl` and `cMapPacked` resolved from the local `pdfjs-dist` package
+ * definePDFJSModule(() => import('pdfjs-dist/legacy/build/pdf.mjs'))
  */
-export declare function getDocumentProxy(data: DocumentInitParameters['data'], options?: DocumentInitParameters): Promise<PDFDocumentProxy>;
+export declare function definePDFJSModule(pdfjs: () => Promise<any>): void;
 export declare function getResolvedPDFJS(): Promise<typeof PDFJS>;
-export declare function resolvePDFJSImport(pdfjsResolver?: () => Promise<any>, { reload }?: {
-  reload?: boolean | undefined;
-}): Promise<void>;
-//#endregion
-//#region src/index.d.ts
-export declare const getMeta: typeof getMeta$1;
-export declare const extractText: typeof extractText$1;
-export declare const extractTextItems: typeof extractTextItems$1;
-export declare const extractImages: typeof extractImages$1;
-export declare const renderPageAsImage: typeof renderPageAsImage$1;
-export declare const extractLinks: typeof extractLinks$1;
-//#endregion
-export type { StructuredTextItem };
+export type { Bounds, ExtractImagesOptions, ExtractedImage, Metadata, PDFInfo, PageInspection, RenderPageAsImageOptions, StructuredTextItem };