unpdf 0.12.2 → 1.0.0

package/README.md

@@ -1,6 +1,6 @@
 # unpdf
 
-A collection of utilities to work with PDFs. Designed specifically for Deno, workers and other nodeless environments.
+A collection of utilities for working with PDF files. Designed specifically for Bun, Deno, and serverless environments. However, it also works in Node.js and the browser.
 
 `unpdf` ships with a serverless build/redistribution of Mozilla's [PDF.js](https://github.com/mozilla/pdf.js) for serverless environments. Apart from some string replacements and mocks, [`unenv`](https://github.com/unjs/unenv) does the heavy lifting by converting Node.js specific code to be platform-agnostic. See [`pdfjs.rollup.config.ts`](./pdfjs.rollup.config.ts) for all the details.
 
@@ -8,15 +8,18 @@ This library is also intended as a modern alternative to the unmaintained but st
 
 ## Features
 
-- 🏗️ Works in Node.js, browser and workers
+- 🏗️ Made for Node.js, browser and serverless environments
 - 🪭 Includes serverless build of PDF.js ([`unpdf/pdfjs`](./package.json#L34))
-- 💬 Extract text and images from PDFs
+- 💬 Extract [text](#extract-text-from-pdf) and [images](#extractimages) from PDF files
 - 🧱 Opt-in to legacy PDF.js build
 - 💨 Zero dependencies
 
 ## PDF.js Compatibility
 
-The serverless build of PDF.js provided by `unpdf` is based on PDF.js v4.6.82. If you need a different version, you can [use another PDF.js build](#use-official-or-legacy-pdfjs-build).
+> [!Tip]
+> The serverless PDF.js bundle provided by `unpdf` is built from PDF.js v5.2.133.
+
+You can use an [official PDF.js build](#use-official-or-legacy-pdfjs-build) by using the [`definePDFJSModule`](#definepdfjsmodule) method. This is useful if you want to use a specific version or a custom build of PDF.js.
 
 ## Installation
 
@@ -24,13 +27,13 @@ Run the following command to add `unpdf` to your project.
 
 ```bash
 # pnpm
-pnpm add unpdf
+pnpm add -D unpdf
 
 # npm
-npm install unpdf
+npm install -D unpdf
 
 # yarn
-yarn add unpdf
+yarn add -D unpdf
 ```
 
 ## Usage
@@ -40,32 +43,37 @@ yarn add unpdf
 ```ts
 import { extractText, getDocumentProxy } from 'unpdf'
 
-// Fetch a PDF file from the web
-const buffer = await fetch(
-  'https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf',
-).then(res => res.arrayBuffer())
-
-// Or load it from the filesystem
+// Either fetch a PDF file 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 buffer = await readFile('./dummy.pdf')
 
-// Load PDF from buffer
+// Then, load the PDF file into a PDF.js document
 const pdf = await getDocumentProxy(new Uint8Array(buffer))
-// Extract text from PDF
+
+// Finally, extract the text from the PDF file
 const { totalPages, text } = await extractText(pdf, { mergePages: true })
 
 console.log(`Total pages: ${totalPages}`)
 console.log(text)
 ```
 
-### Access the PDF.js API
+### PDF.js API
 
-This will return the resolved PDF.js module and gives full access to the PDF.js API, like:
+`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.
 
-- `getDocument`
-- `version`
-- … and all other methods
+Access the PDF.js API directly by calling `getResolvedPDFJS`:
 
-Especially useful for platforms like 🦕 Deno or if you want to use the PDF.js API directly. If no custom build was defined beforehand, the serverless build bundled with `unpdf` will be initialized.
+```ts
+import { getResolvedPDFJS } from 'unpdf'
+
+const { version } = await getResolvedPDFJS()
+```
+
+> [!NOTE]
+> If no other PDF.js build was defined, the serverless build will always be used.
+
+For example, you can use the `getDocument` method to load a PDF file and then use the `getPage` method to get a specific page. You can also use the `getTextContent` method to extract the text from the page.
 
 ```ts
 import { getResolvedPDFJS } from 'unpdf'
@@ -86,55 +94,40 @@ for (let i = 1; i <= doc.numPages; i++) {
 
 ### Use Official or Legacy PDF.js Build
 
-Generally speaking, 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.
+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.
 
 > [!WARNING]
-> The latest PDF.js v4.6.82 uses `Promise.withResolvers`, which may not be supported in all environments, such as Node < 22. Consider to use the bundled serverless build, which includes a polyfill, or use an older version of PDF.js.
+> Later PDF.js v4.x versions uses `Promise.withResolvers`, which may not be supported in all environments, such as Node < 22. Consider to use the bundled serverless build, which includes a polyfill, or use an older version of PDF.js.
+
+For example, if you want to use the official PDF.js build, you can do the following:
 
 ```ts
-// Before using any other method, define the PDF.js module
-// if you need another PDF.js build
-import { configureUnPDF } from 'unpdf'
+import { definePDFJSModule } from 'unpdf'
 
-await configureUnPDF({
-  // Use the official PDF.js build (make sure to install it first)
-  pdfjs: () => import('pdfjs-dist'),
-})
+// Define the PDF.js build before using any other unpdf method
+await definePDFJSModule(() => import('pdfjs-dist'))
 
-// Now, you can use the other methods
-// …
+// Now, you can use all unpdf methods with the official PDF.js build
+const { text } = await extractText(pdf)
 ```
 
-## Config
-
-```ts
-interface UnPDFConfiguration {
-  /**
-   * By default, UnPDF will use the latest version of PDF.js compiled for
-   * serverless environments. If you want to use a different version, you can
-   * provide a custom resolver function.
-   *
-   * @example
-   * // Use the official PDF.js build (make sure to install it first)
-   * () => import('pdfjs-dist')
-   */
-  pdfjs?: () => Promise<PDFJS>
-}
-```
+## API
 
-## Methods
+### `definePDFJSModule`
 
-### `configureUnPDF`
+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.
 
-Define a custom PDF.js module, like the legacy build. Make sure to call this method before using any other methods.
+**Type Declaration**
 
 ```ts
-function configureUnPDF(config: UnPDFConfiguration): Promise<void>
+function definePDFJSModule(pdfjs: () => Promise<PDFJS>): Promise<void>
 ```
 
 ### `getResolvedPDFJS`
 
-Returns the resolved PDF.js module. If no build is defined, the latest version will be initialized.
+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.
+
+**Type Declaration**
 
 ```ts
 function getResolvedPDFJS(): Promise<PDFJS>
@@ -142,6 +135,8 @@ function getResolvedPDFJS(): Promise<PDFJS>
 
 ### `getMeta`
 
+**Type Declaration**
+
 ```ts
 function getMeta(
   data: DocumentInitParameters['data'] | PDFDocumentProxy,
@@ -155,47 +150,109 @@ function getMeta(
 
 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.
 
+**Type Declaration**
+
 ```ts
 function extractText(
   data: DocumentInitParameters['data'] | PDFDocumentProxy,
-  { mergePages }?: { mergePages?: boolean },
+  options?: {
+    mergePages?: false
+  }
 ): Promise<{
   totalPages: number
-  text: string | string[]
+  text: string[]
+}>
+function extractText(
+  data: DocumentInitParameters['data'] | PDFDocumentProxy,
+  options: {
+    mergePages: true
+  }
+): Promise<{
+  totalPages: number
+  text: string
 }>
 ```
 
-### `renderPageAsImage`
+### `extractImages`
+
+Extracts images from a specific page of a PDF document, including necessary metadata such as width, height, and calculated color channels.
 
 > [!NOTE]
 > This method will only work in Node.js and browser environments.
 
-To render a PDF page as an image, you can use the `renderPageAsImage` method. This method will return an `ArrayBuffer` of the rendered image.
+In order to use this method, make sure to meet the following requirements:
 
-In order to use this method, you have to meet the following requirements:
+- Use the official PDF.js build (see below for details).
+- 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.
 
-- Use the official PDF.js build
-- Install the [`canvas`](https://www.npmjs.com/package/canvas) package in Node.js environments
+**Type Declaration**
+
+```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[]>
+```
 
 **Example**
 
+> [!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.
+
 ```ts
-import { configureUnPDF, renderPageAsImage } from 'unpdf'
+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)`)
+  }
+}
 
-await configureUnPDF({
-  // Use the official PDF.js build
-  pdfjs: () => import('pdfjs-dist'),
-})
+extractPdfImages().catch(console.error)
+```
 
-const pdf = await readFile('./dummy.pdf')
-const buffer = new Uint8Array(pdf)
-const pageNumber = 1
+### `renderPageAsImage`
 
-const result = await renderPageAsImage(buffer, pageNumber, {
-  canvas: () => import('canvas'),
-})
-await writeFile('dummy-page-1.png', result)
-```
+To render a PDF page as an image, you can use the `renderPageAsImage` method. This method will return an `ArrayBuffer` of the rendered image.
+
+> [!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 below for details).
+- 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.
 
 **Type Declaration**
 
@@ -204,8 +261,8 @@ declare function renderPageAsImage(
   data: DocumentInitParameters['data'],
   pageNumber: number,
   options?: {
-    canvas?: () => Promise<typeof import('canvas')>
-    /** @default 1 */
+    canvasImport?: () => Promise<typeof import('@napi-rs/canvas')>
+    /** @default 1.0 */
     scale?: number
     width?: number
     height?: number
@@ -213,13 +270,24 @@ declare function renderPageAsImage(
 ): Promise<ArrayBuffer>
 ```
 
-## FAQ
+**Example**
+
+```ts
+import { definePDFJSModule, renderPageAsImage } from 'unpdf'
 
-### Why Is `canvas` An Optional Dependency?
+// Use the official PDF.js build
+await definePDFJSModule(() => import('pdfjs-dist'))
 
-The official PDF.js library depends on the `canvas` module for Node.js environments, which [doesn't work inside worker threads](https://github.com/Automattic/node-canvas/issues/1394). That's why `unpdf` ships with a serverless build of PDF.js that mocks the `canvas` module.
+const pdf = await readFile('./dummy.pdf')
+const buffer = new Uint8Array(pdf)
+const pageNumber = 1
 
-However, to render PDF pages as images in Node.js environments, you need to install the `canvas` module. That's why it is a peer dependency.
+const result = await renderPageAsImage(buffer, pageNumber, {
+  canvasImport: () => import('@napi-rs/canvas'),
+  scale: 2,
+})
+await writeFile('dummy-page-1.png', new Uint8Array(result))
+```
 
 ## License
 

package/dist/index.cjs

@@ -16,24 +16,21 @@ async function getDocumentProxy(data, options = {}) {
 }
 async function getResolvedPDFJS() {
   if (!resolvedModule) {
-    await resolvePDFJSImports();
+    await resolvePDFJSImport();
   }
   return resolvedModule;
 }
-async function resolvePDFJSImports(pdfjsResolver, { force = false } = {}) {
-  if (resolvedModule && !force) {
+async function resolvePDFJSImport(pdfjsResolver, { reload = false } = {}) {
+  if (resolvedModule && !reload) {
     return;
   }
   if (pdfjsResolver) {
     try {
       resolvedModule = await interopDefault(pdfjsResolver());
-      if (resolvedModule && "resolvePDFJS" in resolvedModule) {
-        resolvedModule = await resolvedModule.resolvePDFJS();
-      }
       return;
     } catch (error) {
       console.error(error);
-      throw new Error("Resolving failed. Please check the provided configuration.");
+      throw new Error("PDF.js could not be resolved. Please check the resolver function.");
     }
   }
   try {
@@ -41,7 +38,7 @@ async function resolvePDFJSImports(pdfjsResolver, { force = false } = {}) {
     resolvedModule = await resolvePDFJS();
   } catch (error) {
     console.error(error);
-    throw new Error("PDF.js is not available. Please add the package as a dependency.");
+    throw new Error("PDF.js package not available. Please install it first.");
   }
 }
 function isPDFDocumentProxy(data) {
@@ -52,6 +49,87 @@ async function interopDefault(m) {
   return resolved.default || resolved;
 }
 
+let canvasModule;
+/**
+ * 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
+ */
+class BaseCanvasFactory {
+  #enableHWA = false;
+  constructor({ enableHWA = false } = {}) {
+    this.#enableHWA = enableHWA;
+  }
+  create(width, height) {
+    const canvas = this._createCanvas(width, height);
+    return {
+      canvas,
+      context: canvas.getContext("2d", {
+        willReadFrequently: !this.#enableHWA
+      })
+    };
+  }
+  reset({ canvas }, width, height) {
+    if (!canvas) {
+      throw new Error("Canvas is not specified");
+    }
+    canvas.width = width;
+    canvas.height = height;
+  }
+  destroy(context) {
+    if (!context.canvas) {
+      throw new Error("Canvas is not specified");
+    }
+    context.canvas.width = 0;
+    context.canvas.height = 0;
+    context.canvas = void 0;
+    context.context = void 0;
+  }
+  // eslint-disable-next-line unused-imports/no-unused-vars
+  _createCanvas(width, height) {
+    throw new Error("Not implemented");
+  }
+}
+/**
+ * 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
+ */
+class DOMCanvasFactory extends BaseCanvasFactory {
+  _document;
+  constructor({ ownerDocument = globalThis.document, enableHWA = false } = {}) {
+    super({ enableHWA });
+    this._document = ownerDocument;
+  }
+  _createCanvas(width, height) {
+    const canvas = this._document.createElement("canvas");
+    canvas.width = width;
+    canvas.height = height;
+    return canvas;
+  }
+}
+class NodeCanvasFactory extends BaseCanvasFactory {
+  constructor({ enableHWA = false } = {}) {
+    super({ enableHWA });
+  }
+  _createCanvas(width, height) {
+    if (!canvasModule) {
+      throw new Error("@napi-rs/canvas module is not resolved");
+    }
+    return canvasModule.createCanvas(width, height);
+  }
+}
+async function resolveCanvasModule(canvasImport) {
+  canvasModule ??= await interopDefault(canvasImport());
+}
+function injectCanvasConstructors() {
+  if (!canvasModule)
+    return;
+  globalThis.DOMMatrix ??= canvasModule.DOMMatrix;
+  globalThis.ImageData ??= canvasModule.ImageData;
+  globalThis.Path2D ??= canvasModule.Path2D;
+}
+
 async function extractImages$1(data, pageNumber) {
   const pdf = isPDFDocumentProxy(data) ? data : await getDocumentProxy(data);
   if (pageNumber < 1 || pageNumber > pdf.numPages) {
@@ -88,74 +166,41 @@ async function extractImages$1(data, pageNumber) {
   return images;
 }
 async function renderPageAsImage$1(data, pageNumber, options = {}) {
-  const canvasFactory = await createIsomorphicCanvasFactory(options.canvas);
-  const pdf = isPDFDocumentProxy(data) ? data : await getDocumentProxy(data, { canvasFactory });
+  const CanvasFactory = await createIsomorphicCanvasFactory(options.canvasImport);
+  const pdf = isPDFDocumentProxy(data) ? data : await getDocumentProxy(data, { CanvasFactory });
   const page = await pdf.getPage(pageNumber);
   if (pageNumber < 1 || pageNumber > pdf.numPages) {
     throw new Error(`Invalid page number. Must be between 1 and ${pdf.numPages}.`);
   }
-  let outputScale = options.scale || 1;
-  let viewport = page.getViewport({ scale: outputScale });
+  const defaultViewport = page.getViewport({ scale: 1 });
+  let scale = options.scale || 1;
   if (options.width) {
-    outputScale = options.width / viewport.width;
+    scale = options.width / defaultViewport.width;
   } else if (options.height) {
-    outputScale = options.height / viewport.height;
+    scale = options.height / defaultViewport.height;
   }
-  if (outputScale !== 1 && outputScale > 0) {
-    viewport = page.getViewport({ scale: outputScale });
-  }
-  const ctx = canvasFactory.create(viewport.width, viewport.height);
+  const viewport = page.getViewport({ scale: Math.max(0, scale) });
+  const drawingContext = new CanvasFactory().create(viewport.width, viewport.height);
   await page.render({
-    canvasContext: ctx.context,
+    canvasContext: drawingContext.context,
     viewport
   }).promise;
-  const dataUrl = isBrowser ? ctx.canvas.toDataURL() : ctx.canvas.toDataURL();
+  const dataUrl = drawingContext.canvas.toDataURL();
   const response = await fetch(dataUrl);
   return await response.arrayBuffer();
 }
-async function createIsomorphicCanvasFactory(canvas) {
-  const _canvas = canvas ? await interopDefault(canvas()) : void 0;
-  return {
-    _createCanvas(width, height) {
-      if (isBrowser) {
-        const canvas2 = document.createElement("canvas");
-        canvas2.width = width;
-        canvas2.height = height;
-        return canvas2;
-      }
-      if (isNode) {
-        if (!_canvas) {
-          throw new Error('Failed to resolve "canvas" package.');
-        }
-        return _canvas.createCanvas(width, height);
-      }
-      throw new Error("Unsupported environment for canvas creation.");
-    },
-    create(width, height) {
-      const _canvas2 = this._createCanvas(width, height);
-      const context = _canvas2.getContext(
-        "2d"
-      );
-      return {
-        canvas: _canvas2,
-        context
-      };
-    },
-    reset(ctx, width, height) {
-      if (ctx.canvas) {
-        ctx.canvas.width = width;
-        ctx.canvas.height = height;
-      }
-    },
-    destroy(ctx) {
-      if (ctx.canvas) {
-        ctx.canvas.width = 0;
-        ctx.canvas.height = 0;
-      }
-      ctx.canvas = void 0;
-      ctx.context = void 0;
+async function createIsomorphicCanvasFactory(canvasImport) {
+  if (isBrowser)
+    return DOMCanvasFactory;
+  if (isNode) {
+    if (!canvasImport) {
+      throw new Error('Parameter "canvasImport" is required in Node.js environment.');
     }
-  };
+    await resolveCanvasModule(canvasImport);
+    injectCanvasConstructors();
+    return NodeCanvasFactory;
+  }
+  throw new Error("Unsupported environment for canvas creation.");
 }
 
 async function getMeta$1(data) {
@@ -168,7 +213,7 @@ async function getMeta$1(data) {
 }
 
 async function extractText$1(data, options = {}) {
-  const { mergePages = false } = { ...options };
+  const { mergePages = false } = options;
   const pdf = isPDFDocumentProxy(data) ? data : await getDocumentProxy(data);
   const texts = await Promise.all(
     Array.from({ length: pdf.numPages }, (_, i) => getPageText(pdf, i + 1))
@@ -184,36 +229,36 @@ async function getPageText(document, pageNumber) {
   return content.items.filter((item) => item.str != null).map((item) => item.str + (item.hasEOL ? "\n" : "")).join("");
 }
 
+async function definePDFJSModule(pdfjs) {
+  await resolvePDFJSImport(pdfjs, { reload: true });
+}
 async function configureUnPDF(options) {
-  const { pdfjs } = { ...options };
-  if (pdfjs) {
-    await resolvePDFJSImports(pdfjs, { force: true });
-  }
+  await resolvePDFJSImport(options.pdfjs, { reload: true });
 }
 
 const getMeta = async (...args) => {
-  await resolvePDFJSImports();
+  await resolvePDFJSImport();
   return await getMeta$1(...args);
 };
 const extractText = async (...args) => {
-  await resolvePDFJSImports();
+  await resolvePDFJSImport();
   return await extractText$1(...args);
 };
 const extractImages = async (...args) => {
-  await resolvePDFJSImports();
+  await resolvePDFJSImport();
   return await extractImages$1(...args);
 };
 const renderPageAsImage = async (...args) => {
-  await resolvePDFJSImports();
+  await resolvePDFJSImport();
   return await renderPageAsImage$1(...args);
 };
 
 exports.configureUnPDF = configureUnPDF;
-exports.createIsomorphicCanvasFactory = createIsomorphicCanvasFactory;
+exports.definePDFJSModule = definePDFJSModule;
 exports.extractImages = extractImages;
 exports.extractText = extractText;
 exports.getDocumentProxy = getDocumentProxy;
 exports.getMeta = getMeta;
 exports.getResolvedPDFJS = getResolvedPDFJS;
 exports.renderPageAsImage = renderPageAsImage;
-exports.resolvePDFJSImports = resolvePDFJSImports;
+exports.resolvePDFJSImport = resolvePDFJSImport;