unpdf 1.6.2 → 1.8.0

package/README.md

@@ -7,7 +7,7 @@ Ships with a serverless build of Mozilla's [PDF.js](https://github.com/mozilla/p
 ## Features
 
 - 🏗️ Works in Node.js, browser and serverless environments
-- 🪭 Includes serverless build of PDF.js ([`unpdf/pdfjs`](./package.json#L34))
+- 🪭 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
@@ -93,11 +93,11 @@ console.log(await document.getMetadata())
 > [!NOTE]
 > The serverless PDF.js bundle is built from PDF.js v5.6.205.
 
-Heart and soul of this package is the [`pdfjs.rollup.config.ts`](./pdfjs.rollup.config.ts) file. It uses [Rollup](https://rollupjs.org/) to bundle PDF.js into a single file for serverless environments. The key techniques:
+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** provide missing APIs like `FinalizationRegistry` (unavailable in Cloudflare Workers).
+- **Global polyfills** provide missing APIs like `Promise.withResolvers` and `FinalizationRegistry` (unavailable in Node.js < 22 and Cloudflare Workers, respectively).
 
 ## API
 
@@ -121,6 +121,21 @@ Returns the resolved PDF.js module. If no other PDF.js build was defined, the se
 function getResolvedPDFJS(): Promise<PDFJS>
 ```
 
+### `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)).
+
+**Type Declaration**
+
+```ts
+function getDocumentProxy(
+  data: DocumentInitParameters['data'],
+  options?: DocumentInitParameters,
+): Promise<PDFDocumentProxy>
+```
+
 ### `getMeta`
 
 Extracts metadata from a PDF. If `parseDates` is set to `true`, the date properties will be parsed into `Date` objects.
@@ -141,7 +156,7 @@ function getMeta(
 
 ### `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. Otherwise, an array of strings for each page will be returned.
+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**
 
@@ -149,20 +164,42 @@ Extracts all text from a PDF. If `mergePages` is set to `true`, the text of all
 function extractText(
   data: DocumentInitParameters['data'] | PDFDocumentProxy,
   options?: {
-    mergePages?: false
+    mergePages?: boolean
   }
 ): Promise<{
   totalPages: number
-  text: string[]
+  text: string | string[]
 }>
-function extractText(
+```
+
+### `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**
+
+```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,
-  options: {
-    mergePages: true
-  }
 ): Promise<{
   totalPages: number
-  text: string
+  items: StructuredTextItem[][]
 }>
 ```
 
@@ -294,26 +331,15 @@ function renderPageAsImage(
     scale?: number
     width?: number
     height?: number
-    toDataURL?: false
+    toDataURL?: boolean
   },
-): Promise<ArrayBuffer>
-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: true
-  },
-): Promise<string>
+): Promise<ArrayBuffer | string>
 ```
 
 **Examples**
 
 ```ts
+import { readFile, writeFile } from 'node:fs/promises'
 import { definePDFJSModule, renderPageAsImage } from 'unpdf'
 
 // Use the official PDF.js build
@@ -331,6 +357,7 @@ await writeFile('dummy-page-1.png', new Uint8Array(result))
 ```
 
 ```ts
+import { readFile, writeFile } from 'node:fs/promises'
 import { definePDFJSModule, renderPageAsImage } from 'unpdf'
 
 await definePDFJSModule(() => import('pdfjs-dist'))
@@ -360,6 +387,15 @@ const html = `<!DOCTYPE html>
 await writeFile('dummy-page-1.html', html)
 ```
 
+## Processing Untrusted PDFs
+
+PDF.js does not execute scripts embedded in PDFs, but resource limits are your job:
+
+- **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.
+
 ## License
 
 [MIT](./LICENSE) License © 2023-PRESENT [Johann Schopplich](https://github.com/johannschopplich)