unpdf 1.9.1 → 2.0.0

package/README.md

@@ -6,11 +6,11 @@ Ships with a serverless build of Mozilla's [PDF.js](https://github.com/mozilla/p
 
 ## Features
 
-- 🏗️ Works in Node.js 22+, Bun, browsers, and serverless environments ([Cloudflare Workers example](./examples/cloudflare))
+- 🏗️ 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](#extracttext), [positioned text](#extracttextitems), [links](#extractlinks), [images](#extractimages), and [metadata](#getmeta) from PDF files
-- 🖼️ [Render pages as images](#renderpageasimage)
-- 🧠 Perfect for AI applications and PDF summarization
+- 💬 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
@@ -23,268 +23,171 @@ pnpm add unpdf
 npm install unpdf
 ```
 
-## Usage
+## Use Cases
+
+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)
 ```
 
-## How It Works
+Without `mergePages`, `text` holds one string per page. For coordinates and font sizes, e.g. to detect tables, use [`extractTextItems`](#extracttextitems).
 
-> [!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.
+### Extract Images as PNG
 
-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:
+PNG encoding needs no canvas and no native dependency, so it also runs in Cloudflare Workers:
 
-- **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.
-
-## API
-
-### `definePDFJSModule`
-
-Sets the PDF.js build every other method uses – call it before any of them. See [Custom PDF.js Build](#custom-pdfjs-build).
+```ts
+import { writeFile } from 'node:fs/promises'
+import { extractImages } from 'unpdf'
 
-**Type Declaration**
+const images = await extractImages(pdf, 1, { format: 'png' })
 
-```ts
-function definePDFJSModule(pdfjs: () => Promise<PDFJS>): Promise<void>
+for (const [index, image] of images.entries())
+  await writeFile(`image-${index + 1}.png`, image.data)
 ```
 
-### `getResolvedPDFJS`
-
-Returns the resolved PDF.js module – the serverless build, unless `definePDFJSModule` set another. Use it to call the PDF.js API directly.
+Without `format`, `data` holds raw RGBA pixels. Each image carries its `bounds` on the page.
 
-**Type Declaration**
+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`.
 
-```ts
-function getResolvedPDFJS(): Promise<PDFJS>
-```
+### Render a Page as an Image
 
-**Example**
+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,
+})
 ```
 
-### `getDocumentProxy`
+### Spot Scanned Pages
 
-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.
+`inspectPages` measures text and images per page – where to draw the line between a text page and a scan depends on your documents:
 
-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. Without `pdfjs-dist` installed, the Node.js defaults are skipped.
+```ts
+import { inspectPages } from 'unpdf'
 
-**Type Declaration**
+const { pages } = await inspectPages(pdf)
 
-```ts
-function getDocumentProxy(
-  data: DocumentInitParameters['data'],
-  options?: DocumentInitParameters,
-): Promise<PDFDocumentProxy>
+// 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)
 ```
 
-**Example**
+### Process Untrusted PDFs
 
-Your options override the defaults:
+PDF.js does not execute scripts embedded in PDFs, but resource limits are your job:
 
-```ts
-const pdf = await getDocumentProxy(buffer, {
-  disableFontFace: false,
-  standardFontDataUrl: 'https://unpkg.com/pdfjs-dist@latest/standard_fonts/',
-})
-```
+- **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.
 
-### `getMeta`
+## API
 
-Extracts metadata from a PDF. If `parseDates` is set to `true`, the date properties will be parsed into `Date` objects.
+`data` is binary PDF data or a `PDFDocumentProxy` throughout.
+
+### `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 getMeta(
-  data: DocumentInitParameters['data'] | PDFDocumentProxy,
-  options?: {
-    parseDates?: boolean
-  },
-): Promise<{
-  info: Record<string, any>
-  metadata: Record<string, any>
-}>
+function getDocumentProxy(data: Uint8Array | ArrayBuffer, options?: DocumentInitParameters): Promise<PDFDocumentProxy>
 ```
 
 ### `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.
-
-**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 extractText(
-  data: DocumentInitParameters['data'] | PDFDocumentProxy,
-  options?: {
-    mergePages?: boolean
-  }
-): Promise<{
-  totalPages: number
-  text: string | string[]
-}>
+function extractText(data, options?: { mergePages?: boolean }): Promise<{ totalPages: number, text: string | string[] }>
 ```
 
 ### `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.
-
-**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
-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 extractTextItems(data): Promise<{ totalPages: number, items: StructuredTextItem[][] }>
 ```
 
 ### `extractLinks`
 
-Extracts all links from a PDF document, including hyperlinks and external URLs.
-
-**Type Declaration**
+Extracts the URLs of link annotations per page.
 
 ```ts
-function extractLinks(
-  data: DocumentInitParameters['data'] | PDFDocumentProxy,
-): Promise<{
-  totalPages: number
-  links: string[]
-}>
+function extractLinks(data): Promise<{ totalPages: number, links: string[][] }>
 ```
 
-**Example**
+### `extractImages`
+
+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
-import { readFile } from 'node:fs/promises'
-import { extractLinks, getDocumentProxy } from 'unpdf'
+function extractImages(data, pageNumber: number, options?: { format?: 'rgba' | 'png' }): Promise<ExtractedImage[]>
+```
 
-// Load a PDF file
-const buffer = await readFile('./document.pdf')
-const pdf = await getDocumentProxy(new Uint8Array(buffer))
+### `renderPageAsImage`
 
-// Extract all links from the PDF
-const { totalPages, links } = await extractLinks(pdf)
+Renders a page as image bytes, or as a data URL with `toDataURL: true`. `width` or `height` scale the page to that size.
 
-console.log(`Total pages: ${totalPages}`)
-console.log(`Found ${links.length} links:`)
-for (const link of links) console.log(link)
+```ts
+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>
 ```
 
-### `extractImages`
+### `inspectPages`
 
-Extracts images from a specific page of a PDF document, including necessary metadata such as width, height, and calculated color channels.
-
-**Type Declaration**
+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
-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 inspectPages(data): Promise<{ totalPages: number, pages: PageInspection[] }>
 ```
 
-**Example**
+### `getMeta`
 
-Saves each image as PNG with [sharp](https://github.com/lovell/sharp), installed separately:
+Extracts the `/Info` dictionary and the XMP metadata (`null` without). `parseDates: true` turns the dates into `Date` objects.
 
 ```ts
-import { readFile } from 'node:fs/promises'
-import sharp from 'sharp'
-import { extractImages, getDocumentProxy } from 'unpdf'
-
-const buffer = await readFile('./document.pdf')
-const pdf = await getDocumentProxy(new Uint8Array(buffer))
-const images = await extractImages(pdf, 1)
-
-for (const [index, image] of images.entries()) {
-  await sharp(image.data, {
-    raw: { width: image.width, height: image.height, channels: image.channels },
-  })
-    .png()
-    .toFile(`image-${index + 1}.png`)
-}
+function getMeta(data, options?: { parseDates?: boolean }): Promise<{ info: PDFInfo, metadata: Metadata | null }>
 ```
 
-### `renderPageAsImage`
-
-Renders a PDF page as PNG and returns its bytes as an `ArrayBuffer`, or a data URL (`string`) with `toDataURL: true`.
-
-Rendering needs a canvas: browsers bring their own, while Node.js and Bun need the [`@napi-rs/canvas`](https://github.com/Brooooooklyn/canvas) package, passed as `canvasImport`. Serverless runtimes like Cloudflare Workers have neither.
+### `definePDFJSModule`
 
-**Type Declaration**
+Sets the PDF.js build every other method uses. It loads on first use.
 
 ```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 definePDFJSModule(pdfjs: () => Promise<PDFJS>): void
 ```
 
-**Example**
-
-```ts
-import { readFile, writeFile } from 'node:fs/promises'
-import { renderPageAsImage } from 'unpdf'
+### `getResolvedPDFJS`
 
-const buffer = await readFile('./dummy.pdf')
-const image = await renderPageAsImage(new Uint8Array(buffer), 1, {
-  canvasImport: () => import('@napi-rs/canvas'),
-  scale: 2,
-})
+Returns the resolved PDF.js module – the serverless build, unless `definePDFJSModule` set another – to call the PDF.js API directly.
 
-await writeFile('dummy-page-1.png', new Uint8Array(image))
+```ts
+function getResolvedPDFJS(): Promise<PDFJS>
 ```
 
 ## Custom PDF.js Build
@@ -292,24 +195,23 @@ await writeFile('dummy-page-1.png', new Uint8Array(image))
 `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 { definePDFJSModule, extractText, getDocumentProxy } from 'unpdf'
+import { definePDFJSModule } from 'unpdf'
 
-await definePDFJSModule(() => import('pdfjs-dist/legacy/build/pdf.mjs'))
-
-const pdf = await getDocumentProxy(/* … */)
-const { text } = await extractText(pdf)
+definePDFJSModule(() => import('pdfjs-dist/legacy/build/pdf.mjs'))
 ```
 
-In Node.js, import the legacy build as shown. The default `pdfjs-dist` entry targets current browsers – it fails on Node.js 24 and older and warns on newer versions.
+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.
 
-## Processing Untrusted PDFs
+## How It Works
 
-PDF.js does not execute scripts embedded in PDFs, but resource limits are your job:
+> [!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.
 
-- **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.
+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:
+
+- **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