pdfjs-serverless 1.3.0 → 2.0.0

package/README.md

@@ -1,8 +1,8 @@
 # pdfjs-serverless
 
-A redistribution of Mozilla's [PDF.js](https://github.com/mozilla/pdf.js) as a single bundle for edge and serverless runtimes, like Cloudflare Workers. Use it as a drop-in replacement for `pdfjs-dist` to parse PDF documents and extract text content – no extra dependencies needed.
+A redistribution of Mozilla's [PDF.js](https://github.com/mozilla/pdf.js) as a bundle for edge and serverless runtimes, like Cloudflare Workers. Use it as a drop-in replacement for `pdfjs-dist` to parse PDF documents and extract text content – no extra dependencies needed.
 
-The whole export is about 1.6 MB (minified) and ships the complete PDF.js type declarations.
+The main bundle is about 1.7 MB (minified) and leaves the image decoders to an [opt-in import](#decoding-ccitt-jbig2-and-jpeg-2000-images). It ships the complete PDF.js type declarations and is tested in Node.js 24+, Bun, and Cloudflare Workers.
 
 ## Installation
 
@@ -19,7 +19,7 @@ npm install pdfjs-serverless
 > [!TIP]
 > For common operations, such as extracting text content or images from PDF files, you can use the [`unpdf` package](https://github.com/unjs/unpdf). It is a wrapper around `pdfjs-serverless` and provides a simple API for common use cases.
 
-`pdfjs-serverless` provides the same API as the original PDF.js library. To use any of the PDF.js exports, rename the import to `pdfjs-serverless` instead of `pdfjs-dist`:
+Swap the import from `pdfjs-dist` to `pdfjs-serverless`:
 
 ```diff
 - import { getDocument } from 'pdfjs-dist'
@@ -36,54 +36,68 @@ export default {
     if (request.method !== 'POST')
       return new Response('Method Not Allowed', { status: 405 })
 
-    // Get the PDF file from the POST request body as a buffer
-    const data = await request.arrayBuffer()
+    const data = new Uint8Array(await request.arrayBuffer())
+    const document = await getDocument({ data, useSystemFonts: true }).promise
 
-    const document = await getDocument({
-      data: new Uint8Array(data),
-      useSystemFonts: true,
-    }).promise
-
-    // Get metadata and initialize output object
-    const metadata = await document.getMetadata()
-    const output = {
-      metadata,
-      pages: []
-    }
-
-    // Iterate through each page and fetch the text content
-    for (let i = 1; i <= document.numPages; i++) {
-      const page = await document.getPage(i)
-      const textContent = await page.getTextContent()
-      const contents = textContent.items.map(item => item.str).join(' ')
-
-      // Add page content to output
-      output.pages.push({
-        pageNumber: i,
-        content: contents
-      })
+    const pages = []
+    for (let pageNumber = 1; pageNumber <= document.numPages; pageNumber++) {
+      const page = await document.getPage(pageNumber)
+      const { items } = await page.getTextContent()
+      pages.push({ pageNumber, content: items.map(item => item.str).join(' ') })
     }
 
-    // Return the results as JSON
-    return new Response(JSON.stringify(output), {
-      headers: { 'Content-Type': 'application/json' }
-    })
-  }
+    return Response.json({ metadata: await document.getMetadata(), pages })
+  },
 }
 ```
 
-Ready-to-run examples for Cloudflare Workers and Pages Functions live in [`examples/`](./examples).
+A ready-to-run Cloudflare Workers example lives in [`examples/cloudflare`](./examples/cloudflare).
+
+### Rendering Pages
+
+Rendering needs a canvas implementation, which serverless runtimes like Cloudflare Workers lack. In Node.js, hand [`@napi-rs/canvas`](https://github.com/Brooooooklyn/canvas) to the bundle through a well-known global symbol and expose its `Path2D`:
+
+```ts
+import { writeFile } from 'node:fs/promises'
+import * as canvas from '@napi-rs/canvas'
+import { getDocument } from 'pdfjs-serverless'
+import 'pdfjs-serverless/image-decoders'
+
+globalThis[Symbol.for('pdfjs-serverless.canvasModule')] = canvas
+globalThis.Path2D ??= canvas.Path2D
+
+const document = await getDocument({ data }).promise
+const page = await document.getPage(1)
+const viewport = page.getViewport({ scale: 2 })
+const target = canvas.createCanvas(viewport.width, viewport.height)
+
+await page.render({ canvas: target, canvasContext: target.getContext('2d'), viewport }).promise
+await writeFile('page-1.png', await target.encode('png'))
+```
+
+Without a canvas module, rendering throws a descriptive error.
+
+### Decoding CCITT, JBIG2, and JPEG 2000 Images
+
+Rendering a page or reading its image data needs PDF.js' JBIG2 and OpenJPEG decoders for images in these formats. Text extraction doesn't, so your bundle leaves them out unless you import them once:
+
+```ts
+import 'pdfjs-serverless/image-decoders'
+```
+
+The decoders then load on the first such image. Without the import, PDF.js skips these images and warns that the import is missing.
 
 ## How It Works
 
 > [!NOTE]
-> `pdfjs-serverless` is currently built from PDF.js v5.6.205.
+> `pdfjs-serverless` 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 [`rolldown.config.ts`](./rolldown.config.ts) file. It uses [Rolldown](https://rolldown.rs/) to bundle PDF.js into a single file for serverless environments. The key techniques:
+Heart and soul of this package is the [`rolldown.config.ts`](./rolldown.config.ts) file. It uses [Rolldown](https://rolldown.rs/) to bundle PDF.js for serverless environments. The key techniques:
 
-- **String replacements** rewrite the environment detection: `isNodeJS` becomes `typeof window === "undefined"`, so serverless runtimes take the Node.js code paths – paradoxical, but it unlocks the right branches. The `@napi-rs/canvas` import is bridged to `globalThis[Symbol.for("pdfjs-serverless.canvasModule")]` – assign an API-compatible canvas module to that symbol to enable rendering, otherwise accessing it throws a descriptive error.
+- **String replacements** rewrite the environment detection: `isNodeJS` becomes `typeof window === "undefined"`, so serverless runtimes take the Node.js code paths – paradoxical, but it unlocks the right branches. The `@napi-rs/canvas` import is bridged to a global symbol (see [Rendering Pages](#rendering-pages)).
 - **Worker inlining** embeds the PDF.js worker directly into the main bundle, since serverless runtimes can't load separate worker files.
-- **Mocks and polyfills** provide missing globals: `DOMMatrix`, `navigator` and `FinalizationRegistry` are stubbed in [`src/mocks.mjs`](./src/mocks.mjs); `Promise.withResolvers`, `Uint8Array.prototype.toHex` and friends are polyfilled in [`src/polyfills.mjs`](./src/polyfills.mjs).
+- **Bundled image decoders** ship PDF.js' JBIG2 and OpenJPEG decoders, WASM and JS fallback, as lazy chunks behind [`pdfjs-serverless/image-decoders`](#decoding-ccitt-jbig2-and-jpeg-2000-images), so CCITT, JBIG2, and JPEG 2000 images decode without `pdfjs-dist` or a `wasmUrl`. Where the runtime can't compile WASM, as in Cloudflare Workers, the bundle turns `useWasm` off and the JS decoders take over. Bundlers that resolve the `workerd` condition, like Wrangler, ship only the JS fallbacks.
+- **Mocks and polyfills** provide missing globals: `DOMMatrix`, `navigator` and `FinalizationRegistry` are stubbed in [`src/mocks.mjs`](./src/mocks.mjs); `Promise.try`, `Map.prototype.getOrInsert`, `Uint8Array.prototype.toHex` and friends are polyfilled in [`src/polyfills.mjs`](./src/polyfills.mjs).
 
 ## Inspiration
 

package/dist/image-decoders.d.mts

@@ -0,0 +1 @@
+export {}

package/dist/image-decoders.mjs

@@ -0,0 +1 @@
+globalThis[Symbol.for(`pdfjs-serverless.loadImageDecoder`)]??=async e=>{let{loadDecoder:t}=await import(`#pdfjs-decoders`);return await t(e)};

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import * as PDFJS from './types/src/pdf'
+import * as PDFJS from './types/src/pdf.js'
 
 /**
  * @deprecated Import from `pdfjs-serverless` instead. Will be removed in v2.
@@ -18,5 +18,5 @@ import * as PDFJS from './types/src/pdf'
 declare function resolvePDFJS(): Promise<typeof PDFJS>
 
 export { resolvePDFJS }
-export * from './types/src/pdf'
-export type { TextContent, TextItem, TextMarkedContent, TextStyle } from './types/src/display/api'
+export * from './types/src/pdf.js'
+export type { TextContent, TextItem, TextMarkedContent, TextStyle } from './types/src/display/api.js'