unpdf 1.9.0 → 2.0.0

package/README.md

@@ -1,16 +1,17 @@
 # unpdf
 
-Utilities for PDF extraction and rendering across all JavaScript runtimes – Node.js, Deno, Bun, the browser, and serverless environments like Cloudflare Workers. Especially useful for AI applications that need to summarize or analyze PDF documents.
+Utilities for PDF extraction and rendering across all JavaScript runtimes – Node.js, Bun, the browser, and serverless environments like Cloudflare Workers. Especially useful for AI applications that need to summarize or analyze PDF documents.
 
 Ships with a serverless build of Mozilla's [PDF.js](https://github.com/mozilla/pdf.js), optimized for edge environments. If you're coming from [`pdf-parse`](https://www.npmjs.com/package/pdf-parse), `unpdf` is a modern, actively maintained alternative with broader runtime support.
 
 ## Features
 
-- 🏗️ Works in Node.js, browser and serverless environments
-- 🪭 Includes serverless build of PDF.js ([`unpdf/pdfjs`](./package.json))
-- 💬 Extract [text](#extract-text-from-pdf), [links](#extractlinks), and [images](#extractimages) from PDF files
-- 🧠 Perfect for AI applications and PDF summarization
-- 🧱 Opt-in to official or legacy PDF.js build
+- 🏗️ Works in Node.js 24+, Bun, browsers, and serverless environments ([Cloudflare Workers example](./examples/cloudflare))
+- 🪭 Includes serverless build of PDF.js ([`unpdf/pdfjs`](#how-it-works))
+- 💬 Extract [text](#extract-text), [images as PNG](#extract-images-as-png), links, and metadata – no native dependencies
+- 🖼️ [Render pages as PNG, JPEG, or WebP](#render-a-page-as-an-image)
+- 🔍 [Spot scanned pages](#spot-scanned-pages) before sending them to OCR
+- 🧱 Opt-in to a [custom PDF.js build](#custom-pdfjs-build)
 
 ## Installation
 
@@ -22,379 +23,195 @@ pnpm add unpdf
 npm install unpdf
 ```
 
-## Usage
+## Use Cases
 
-### Extract Text From PDF
+Every method takes binary PDF data (`Uint8Array`, `ArrayBuffer`) or a document proxy from [`getDocumentProxy`](#getdocumentproxy). Pass a proxy to run several methods on one document without parsing it again.
+
+### Extract Text
 
 ```ts
 import { extractText, getDocumentProxy } from 'unpdf'
 
-// Fetch a PDF from the web or load it from the file system
 const buffer = await fetch('https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf')
   .then(res => res.arrayBuffer())
 
 const pdf = await getDocumentProxy(new Uint8Array(buffer))
 const { totalPages, text } = await extractText(pdf, { mergePages: true })
-
-console.log(`Total pages: ${totalPages}`)
-console.log(text)
 ```
 
-### Official or Legacy PDF.js Build
-
-Usually you don't need to worry about the PDF.js build. `unpdf` ships with a serverless build of the latest PDF.js version. However, if you want to use the official PDF.js version or the legacy build, you can define a custom PDF.js module.
+Without `mergePages`, `text` holds one string per page. For coordinates and font sizes, e.g. to detect tables, use [`extractTextItems`](#extracttextitems).
 
-> [!WARNING]
-> PDF.js v5.x uses `Promise.withResolvers`, which may not be supported in all environments, such as Node < 22. Consider using the bundled serverless build, which includes a polyfill, or use an older version of PDF.js.
+### Extract Images as PNG
 
-For example, if you want to use the official PDF.js build:
+PNG encoding needs no canvas and no native dependency, so it also runs in Cloudflare Workers:
 
 ```ts
-import { definePDFJSModule, extractText, getDocumentProxy } from 'unpdf'
+import { writeFile } from 'node:fs/promises'
+import { extractImages } from 'unpdf'
 
-// Define the PDF.js build before using any other unpdf method
-await definePDFJSModule(() => import('pdfjs-dist'))
+const images = await extractImages(pdf, 1, { format: 'png' })
 
-// Now, you can use all unpdf methods with the official PDF.js build
-const pdf = await getDocumentProxy(/* … */)
-const { text } = await extractText(pdf)
+for (const [index, image] of images.entries())
+  await writeFile(`image-${index + 1}.png`, image.data)
 ```
 
-### PDF.js API
+Without `format`, `data` holds raw RGBA pixels. Each image carries its `bounds` on the page.
 
-`unpdf` provides helpful [methods](#api) to work with PDF files, such as `extractText` and `extractImages`, which should cover most use cases. However, if you need more control over the PDF.js API, you can use the `getResolvedPDFJS` method to get the resolved PDF.js module.
+In browsers, a document proxy decodes some images into bitmaps, which `extractImages` skips. Pass binary data instead, or create the proxy with `isOffscreenCanvasSupported: false` and `isImageDecoderSupported: false`.
 
-Access the PDF.js API directly by calling `getResolvedPDFJS`:
+### Render a Page as an Image
+
+Browsers render on a DOM canvas, which a Web Worker lacks. Node.js and Bun need [`@napi-rs/canvas`](https://github.com/Brooooooklyn/canvas), passed as `canvasImport`. Serverless runtimes like Cloudflare Workers have no canvas.
 
 ```ts
-import { getResolvedPDFJS } from 'unpdf'
+import { renderPageAsImage } from 'unpdf'
 
-const { version } = await getResolvedPDFJS()
+const image = await renderPageAsImage(pdf, 1, {
+  canvasImport: () => import('@napi-rs/canvas'),
+  scale: 2,
+  format: 'jpeg',
+  quality: 0.8,
+})
 ```
 
-> [!NOTE]
-> If no other PDF.js build was defined, the serverless build will always be used.
+### Spot Scanned Pages
 
-For example, you can use the `getDocument` method to load a PDF file and then use the `getMetadata` method to get the metadata of the PDF file:
+`inspectPages` measures text and images per page – where to draw the line between a text page and a scan depends on your documents:
 
 ```ts
-import { readFile } from 'node:fs/promises'
-import { getResolvedPDFJS } from 'unpdf'
+import { inspectPages } from 'unpdf'
 
-const { getDocument } = await getResolvedPDFJS()
-const data = await readFile('./dummy.pdf')
-const document = await getDocument(new Uint8Array(data)).promise
+const { pages } = await inspectPages(pdf)
 
-console.log(await document.getMetadata())
+// Hidden OCR layers count as invisible text, so subtract them.
+const scannedPageNumbers = pages
+  .map((page, index) => ({ ...page, pageNumber: index + 1 }))
+  .filter(page => page.textLength - page.invisibleTextLength < 20 && page.imageCoverage > 0.8)
+  .map(page => page.pageNumber)
 ```
 
-## How It Works
+### Process Untrusted PDFs
 
-> [!NOTE]
-> The serverless PDF.js bundle is built from PDF.js v6.4.299. It requires the global `Iterator` constructor (Safari 18.4+); without it, importing the bundle throws.
-
-Heart and soul of this package is the [`pdfjs.rolldown.config.ts`](./pdfjs.rolldown.config.ts) file. It uses [Rolldown](https://rolldown.rs/) to bundle PDF.js into a single file for serverless environments. The key techniques:
+PDF.js does not execute scripts embedded in PDFs, but resource limits are your job:
 
-- **String replacements** strip browser-specific references from the PDF.js source.
-- **Worker inlining** embeds the PDF.js worker directly into the main bundle, since serverless runtimes can't load separate worker files.
-- **Global polyfills** provide missing APIs like `Promise.withResolvers` and `FinalizationRegistry` (unavailable in Node.js < 22 and Cloudflare Workers, respectively).
+- **Image decoding:** `maxImageSize` is unlimited by default – pass e.g. `getDocumentProxy(data, { maxImageSize: 16_777_216 })` (~16 MP) so a single declared image can't allocate gigabytes.
+- **Page fan-out:** `extractText`, `extractTextItems`, `extractLinks`, and `inspectPages` process all pages in one call – check `pdf.numPages` against a limit first.
+- **Timeouts:** with the serverless build, parsing runs on your event loop (no worker) – race extraction calls against a timeout.
 
 ## API
 
-### `definePDFJSModule`
+`data` is binary PDF data or a `PDFDocumentProxy` throughout.
 
-Allows to define a custom PDF.js build. This method should be called before using any other method. If no custom build is defined, the serverless build will be used.
+### `getDocumentProxy`
 
-**Type Declaration**
+Creates a `PDFDocumentProxy` with `useSystemFonts: true`. In Node.js with `pdfjs-dist` installed, it uses that package's standard fonts instead of system fonts, and its CJK character maps (`cMapUrl`). Cloudflare Workers have no local `pdfjs-dist` – to extract text from CJK fonts without embedded mappings, pass `cMapUrl: 'https://unpkg.com/pdfjs-dist@6.4.299/cmaps/'`, `cMapPacked: true`, and `useWorkerFetch: true`. Your options override the defaults.
 
 ```ts
-function definePDFJSModule(pdfjs: () => Promise<PDFJS>): Promise<void>
+function getDocumentProxy(data: Uint8Array | ArrayBuffer, options?: DocumentInitParameters): Promise<PDFDocumentProxy>
 ```
 
-### `getResolvedPDFJS`
-
-Returns the resolved PDF.js module. If no other PDF.js build was defined, the serverless build will be used. This method is useful if you want to use the PDF.js API directly.
+### `extractText`
 
-**Type Declaration**
+Extracts the text of every page, or one string with `mergePages: true` – line breaks kept, at most one blank line in a row.
 
 ```ts
-function getResolvedPDFJS(): Promise<PDFJS>
+function extractText(data, options?: { mergePages?: boolean }): Promise<{ totalPages: number, text: string | string[] }>
 ```
 
-### `getDocumentProxy`
-
-Creates a `PDFDocumentProxy` from binary PDF data. Every extraction method accepts either raw data or an existing proxy – use this when you want to reuse one document across multiple calls.
-
-Applies sensible defaults: `useSystemFonts: true`; in Node.js additionally `disableFontFace: true`, plus `standardFontDataUrl` and `cMapUrl`/`cMapPacked` resolved from the local `pdfjs-dist` package for standard font and CJK character map support (see the font rendering tip in [`renderPageAsImage`](#renderpageasimage)).
+### `extractTextItems`
 
-**Type Declaration**
+Extracts positioned text items per page: `str`, `x` and `y` in PDF space (origin bottom-left), `width`, `height`, `fontSize`, `fontFamily`, `dir`, `hasEOL`.
 
 ```ts
-function getDocumentProxy(
-  data: DocumentInitParameters['data'],
-  options?: DocumentInitParameters,
-): Promise<PDFDocumentProxy>
+function extractTextItems(data): Promise<{ totalPages: number, items: StructuredTextItem[][] }>
 ```
 
-### `getMeta`
-
-Extracts metadata from a PDF. If `parseDates` is set to `true`, the date properties will be parsed into `Date` objects.
+### `extractLinks`
 
-**Type Declaration**
+Extracts the URLs of link annotations per page.
 
 ```ts
-function getMeta(
-  data: DocumentInitParameters['data'] | PDFDocumentProxy,
-  options?: {
-    parseDates?: boolean
-  },
-): Promise<{
-  info: Record<string, any>
-  metadata: Record<string, any>
-}>
+function extractLinks(data): Promise<{ totalPages: number, links: string[][] }>
 ```
 
-### `extractText`
-
-Extracts all text from a PDF. If `mergePages` is set to `true`, the text of all pages will be merged into a single string with line breaks preserved and at most one blank line in a row. Otherwise, an array of strings for each page will be returned.
+### `extractImages`
 
-**Type Declaration**
+Extracts the images painted on a page – image XObjects, inline images, and image masks – as RGBA pixels or PNG bytes, each with `width`, `height`, and `bounds` in PDF space.
 
 ```ts
-function extractText(
-  data: DocumentInitParameters['data'] | PDFDocumentProxy,
-  options?: {
-    mergePages?: boolean
-  }
-): Promise<{
-  totalPages: number
-  text: string | string[]
-}>
+function extractImages(data, pageNumber: number, options?: { format?: 'rgba' | 'png' }): Promise<ExtractedImage[]>
 ```
 
-### `extractTextItems`
-
-Extracts text with layout information – one array of positioned items per page. Useful when plain text is not enough and you need coordinates, font sizes, or reading direction, e.g. for table detection or positional parsing.
+### `renderPageAsImage`
 
-**Type Declaration**
+Renders a page as image bytes, or as a data URL with `toDataURL: true`. `width` or `height` scale the page to that size.
 
 ```ts
-interface StructuredTextItem {
-  str: string
-  /** X position in PDF coordinate space (origin: bottom-left). */
-  x: number
-  /** Y position in PDF coordinate space (origin: bottom-left). */
-  y: number
-  width: number
-  height: number
-  fontSize: number
-  fontFamily: string
-  /** Text direction: `"ltr"`, `"rtl"`, or `"ttb"`. */
-  dir: string
-  /** Whether the text item is followed by a line break. */
-  hasEOL: boolean
-}
-
-function extractTextItems(
-  data: DocumentInitParameters['data'] | PDFDocumentProxy,
-): Promise<{
-  totalPages: number
-  items: StructuredTextItem[][]
-}>
+function renderPageAsImage(data, pageNumber: number, options?: {
+  canvasImport?: () => Promise<typeof import('@napi-rs/canvas')>
+  scale?: number // Default: 1
+  width?: number
+  height?: number
+  format?: 'png' | 'jpeg' | 'webp' // Default: 'png'
+  quality?: number // From 0 to 1, for JPEG and WebP
+  toDataURL?: boolean
+}): Promise<Uint8Array | string>
 ```
 
-### `extractLinks`
-
-Extracts all links from a PDF document, including hyperlinks and external URLs.
-
-**Type Declaration**
-
-```ts
-function extractLinks(
-  data: DocumentInitParameters['data'] | PDFDocumentProxy,
-): Promise<{
-  totalPages: number
-  links: string[]
-}>
-```
+### `inspectPages`
 
-**Example**
+Measures each page: `textLength`, `invisibleTextLength` (text drawn invisibly, as by OCR layers), `imageCount`, and `imageCoverage` (share of the page covered by images, from 0 to 1).
 
 ```ts
-import { readFile } from 'node:fs/promises'
-import { extractLinks, getDocumentProxy } from 'unpdf'
-
-// Load a PDF file
-const buffer = await readFile('./document.pdf')
-const pdf = await getDocumentProxy(new Uint8Array(buffer))
-
-// Extract all links from the PDF
-const { totalPages, links } = await extractLinks(pdf)
-
-console.log(`Total pages: ${totalPages}`)
-console.log(`Found ${links.length} links:`)
-for (const link of links) console.log(link)
+function inspectPages(data): Promise<{ totalPages: number, pages: PageInspection[] }>
 ```
 
-### `extractImages`
-
-Extracts images from a specific page of a PDF document, including necessary metadata such as width, height, and calculated color channels. Works with both the serverless and official PDF.js build.
+### `getMeta`
 
-**Type Declaration**
+Extracts the `/Info` dictionary and the XMP metadata (`null` without). `parseDates: true` turns the dates into `Date` objects.
 
 ```ts
-interface ExtractedImageObject {
-  data: Uint8ClampedArray
-  width: number
-  height: number
-  channels: 1 | 3 | 4
-  key: string
-}
-
-function extractImages(
-  data: DocumentInitParameters['data'] | PDFDocumentProxy,
-  pageNumber: number,
-): Promise<ExtractedImageObject[]>
+function getMeta(data, options?: { parseDates?: boolean }): Promise<{ info: PDFInfo, metadata: Metadata | null }>
 ```
 
-**Example**
+### `definePDFJSModule`
 
-> [!NOTE]
-> The following example uses the [sharp](https://github.com/lovell/sharp) library to process and save the extracted images. You will need to install it with your preferred package manager.
+Sets the PDF.js build every other method uses. It loads on first use.
 
 ```ts
-import { readFile, writeFile } from 'node:fs/promises'
-import sharp from 'sharp'
-import { extractImages, getDocumentProxy } from 'unpdf'
-
-async function extractPdfImages() {
-  const buffer = await readFile('./document.pdf')
-  const pdf = await getDocumentProxy(new Uint8Array(buffer))
-
-  // Extract images from page 1
-  const imagesData = await extractImages(pdf, 1)
-  console.log(`Found ${imagesData.length} images on page 1`)
-
-  // Process each image with sharp (optional)
-  let totalImagesProcessed = 0
-  for (const imgData of imagesData) {
-    const imageIndex = ++totalImagesProcessed
-
-    await sharp(imgData.data, {
-      raw: {
-        width: imgData.width,
-        height: imgData.height,
-        channels: imgData.channels
-      }
-    })
-      .png()
-      .toFile(`image-${imageIndex}.png`)
-
-    console.log(`Saved image ${imageIndex} (${imgData.width}x${imgData.height}, ${imgData.channels} channels)`)
-  }
-}
-
-extractPdfImages().catch(console.error)
+function definePDFJSModule(pdfjs: () => Promise<PDFJS>): void
 ```
 
-### `renderPageAsImage`
-
-To render a PDF page as an image, you can use the `renderPageAsImage` method. This method will return an `ArrayBuffer` of the rendered image. It can also return a data URL (`string`) if `toDataURL` option is set to `true`.
-
-> [!NOTE]
-> This method will only work in Node.js and browser environments.
-
-In order to use this method, make sure to meet the following requirements:
-
-- Use the official PDF.js build (see [Official or Legacy PDF.js Build](#official-or-legacy-pdfjs-build)).
-- Install the [`@napi-rs/canvas`](https://github.com/Brooooooklyn/canvas) package if you are using Node.js. This package is required to render the PDF page as an image.
-
-> [!TIP]
-> In Node.js, `getDocumentProxy` automatically sets `disableFontFace: true` and resolves `standardFontDataUrl` from your local `pdfjs-dist` package for correct font rendering. To customize this behavior, pass your own options:
->
-> ```ts
-> const pdf = await getDocumentProxy(buffer, {
->   disableFontFace: false,
->   standardFontDataUrl: 'https://unpkg.com/pdfjs-dist@latest/standard_fonts/',
-> })
-> ```
+### `getResolvedPDFJS`
 
-**Type Declaration**
+Returns the resolved PDF.js module – the serverless build, unless `definePDFJSModule` set another – to call the PDF.js API directly.
 
 ```ts
-function renderPageAsImage(
-  data: DocumentInitParameters['data'] | PDFDocumentProxy,
-  pageNumber: number,
-  options?: {
-    canvasImport?: () => Promise<typeof import('@napi-rs/canvas')>
-    /** @default 1.0 */
-    scale?: number
-    width?: number
-    height?: number
-    toDataURL?: boolean
-  },
-): Promise<ArrayBuffer | string>
+function getResolvedPDFJS(): Promise<PDFJS>
 ```
 
-**Examples**
-
-```ts
-import { readFile, writeFile } from 'node:fs/promises'
-import { definePDFJSModule, renderPageAsImage } from 'unpdf'
+## Custom PDF.js Build
 
-// Use the official PDF.js build
-await definePDFJSModule(() => import('pdfjs-dist'))
-
-const pdf = await readFile('./dummy.pdf')
-const buffer = new Uint8Array(pdf)
-const pageNumber = 1
-
-const result = await renderPageAsImage(buffer, pageNumber, {
-  canvasImport: () => import('@napi-rs/canvas'),
-  scale: 2,
-})
-await writeFile('dummy-page-1.png', new Uint8Array(result))
-```
+`unpdf` uses its serverless build unless you define another one, e.g. to pin a different PDF.js version. Install `pdfjs-dist` and call `definePDFJSModule` before any other method:
 
 ```ts
-import { readFile, writeFile } from 'node:fs/promises'
-import { definePDFJSModule, renderPageAsImage } from 'unpdf'
-
-await definePDFJSModule(() => import('pdfjs-dist'))
+import { definePDFJSModule } from 'unpdf'
 
-const pdf = await readFile('./dummy.pdf')
-const buffer = new Uint8Array(pdf)
-const pageNumber = 1
+definePDFJSModule(() => import('pdfjs-dist/legacy/build/pdf.mjs'))
+```
 
-const result = await renderPageAsImage(buffer, pageNumber, {
-  canvasImport: () => import('@napi-rs/canvas'),
-  scale: 2,
-  toDataURL: true,
-})
+In Node.js, import the legacy build as shown. The default `pdfjs-dist` entry targets current browsers – it fails on Node.js 24 and warns on newer versions. `renderPageAsImage` still requires `canvasImport`, though PDF.js draws with the `@napi-rs/canvas` that `pdfjs-dist` installs as an optional dependency.
 
-const html = `<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8">
-    <meta name="viewport" content="width=device-width, initial-scale=1.0">
-    <title>Dummy Page</title>
-  </head>
-  <body>
-    <img alt="Example Page" src="${result}">
-  </body>
-</html>`
-
-await writeFile('dummy-page-1.html', html)
-```
+## How It Works
 
-## Processing Untrusted PDFs
+> [!NOTE]
+> The serverless PDF.js bundle is built from PDF.js v6.4.299. It requires the global `Iterator` constructor (Safari 18.4+); without it, importing the bundle throws.
 
-PDF.js does not execute scripts embedded in PDFs, but resource limits are your job:
+Heart and soul of this package is the [`pdfjs.rolldown.config.ts`](./pdfjs.rolldown.config.ts) file. It uses [Rolldown](https://rolldown.rs/) to bundle PDF.js into a single file for serverless environments. The key techniques:
 
-- **Image decoding:** `maxImageSize` is unlimited by default – pass e.g. `maxImageSize: 16_777_216` (~16 MP) so a single declared image can't allocate gigabytes.
-- **Page fan-out:** `extractText`, `extractTextItems`, and `extractLinks` process all pages in one call – check `pdf.numPages` against a limit first.
-- **Timeouts:** with the serverless build, parsing runs on your event loop (no worker) – race extraction calls against a timeout.
-- The raw `getDocument` from `unpdf/pdfjs` applies none of these defaults.
+- **String replacements** strip browser-specific references from the PDF.js source.
+- **Worker inlining** embeds the PDF.js worker directly into the main bundle, since serverless runtimes can't load separate worker files.
+- **Global polyfills** fill in newer APIs like `Promise.try` and `Map.prototype.getOrInsert` for runtimes that lack them, plus `FinalizationRegistry` for Cloudflare Workers.
 
 ## License