unpdf 0.6.1 → 0.7.1

package/README.md

@@ -34,25 +34,25 @@ yarn add unpdf
 ### Extract Text From PDF
 
 ```ts
-import { extractPDFText } from "unpdf";
+import { extractText, getDocumentProxy } from "unpdf";
 
 // Fetch a PDF file from the web
-const pdf = await fetch(
+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
-const pdf = await readFile("./dummy.pdf");
+const buffer = await readFile("./dummy.pdf");
 
-// Pass the PDF buffer to the relevant method
-const { totalPages, text } = await extractPDFText(new Uint8Array(pdf), {
-  mergePages: true,
-});
+// Load PDF from buffer
+const pdf = await getDocumentProxy(new Uint8Array(pdf));
+// Extract text from PDF
+const { totalPages, text } = await extractText(pdf, { mergePages: true });
 ```
 
 ### Use Legacy Or Custom PDF.js Build
 
-Generally, 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 an older version or the legacy build, you can define a custom PDF.js module.
+Generally, 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.
 
 ```ts
 // Before using any other methods, define the PDF.js module
@@ -132,19 +132,21 @@ Returns the resolved PDF.js module. If no build is defined, the latest version w
 function getResolvedPDFJS(): Promise<PDFJS>;
 ```
 
-### `getPDFMeta`
+### `getMeta`
 
 ```ts
-function getPDFMeta(data: BinaryData | PDFDocumentProxy): Promise<{
+function getMeta(data: BinaryData | PDFDocumentProxy): Promise<{
   info: Record<string, any>;
   metadata: Record<string, any>;
 }>;
 ```
 
-### `extractPDFText`
+### `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.
 
 ```ts
-function extractPDFText(
+function extractText(
   data: BinaryData | PDFDocumentProxy,
   { mergePages }?: { mergePages?: boolean },
 ): Promise<{
@@ -153,20 +155,70 @@ function extractPDFText(
 }>;
 ```
 
-### `getImagesFromPage`
+### `renderPageAsImage`
+
+> [!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, you have to meet the following requirements:
+
+- Use the official PDF.js build
+- Install the [`canvas`](https://www.npmjs.com/package/canvas) package in Node.js environments
+
+**Example**
+
+```ts
+import { defineUnPDFConfig, renderPageAsImage } from "unpdf";
+
+defineUnPDFConfig({
+  // Use the official PDF.js build
+  pdfjs: () => import("pdfjs-dist"),
+});
+
+const pdf = await readFile("./dummy.pdf");
+const buffer = new Uint8Array(pdf);
+const pageNumber = 1;
+
+const result = await renderPageAsImage(buffer, pageNumber, {
+  canvas: () => import("canvas"),
+});
+await writeFile("dummy-page-1.png", Buffer.from(result));
+```
+
+**Type Declaration**
 
 ```ts
-function getImagesFromPage(
+declare function renderPageAsImage(
   data: BinaryData | PDFDocumentProxy,
   pageNumber: number,
-): Promise<ArrayBuffer[]>;
+  options?: {
+    canvas?: () => Promise<typeof "canvas">;
+    /** @default 1 */
+    scale?: number
+    width?: number;
+    height?: number;
+  },
+): Promise<ArrayBuffer>;
+```
+
+### `extractImages`
+
+```ts
+function extractImages(
+  data: BinaryData | PDFDocumentProxy,
+  pageNumber: number,
+): Promise<Uint8ClampedArray[]>;
 ```
 
 ## FAQ
 
-### What About Canvas?
+### Why Is `canvas` A Peer Dependency?
+
+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.
 
-The official PDF.js library depends on the optional `canvas` module, 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.
+However, to render PDF pages as images, you need to install the `canvas` module in Node.js environments. That's why `canvas` is a peer dependency.
 
 ## License
 

package/dist/index.cjs

@@ -1,6 +1,8 @@
 'use strict';
 
 let resolvedModule;
+const isNode = globalThis.process?.release?.name === "node";
+const isBrowser = typeof window !== "undefined";
 async function getDocumentProxy(data, options = {}) {
   const { getDocument } = await getResolvedPDFJS();
   const pdf = await getDocument({
@@ -10,12 +12,6 @@ async function getDocumentProxy(data, options = {}) {
   }).promise;
   return pdf;
 }
-async function defineUnPDFConfig(options) {
-  const { pdfjs } = { ...options };
-  if (pdfjs) {
-    await resolvePDFJSImports(pdfjs, { force: true });
-  }
-}
 async function getResolvedPDFJS() {
   if (!resolvedModule) {
     await resolvePDFJSImports();
@@ -49,7 +45,7 @@ function isPDFDocumentProxy(data) {
   return typeof data === "object" && data !== null && "_pdfInfo" in data;
 }
 
-async function getPDFMeta$1(data) {
+async function getMeta$1(data) {
   const pdf = isPDFDocumentProxy(data) ? data : await getDocumentProxy(data);
   const meta = await pdf.getMetadata();
   return {
@@ -58,7 +54,7 @@ async function getPDFMeta$1(data) {
   };
 }
 
-async function extractPDFText$1(data, options = {}) {
+async function extractText$1(data, options = {}) {
   const { mergePages = false } = { ...options };
   const pdf = isPDFDocumentProxy(data) ? data : await getDocumentProxy(data);
   const texts = await Promise.all(
@@ -80,41 +76,131 @@ async function getPageText(pdf, pageNumber) {
   return items.map(({ str }) => str).join("\n");
 }
 
-async function getImagesFromPage$1(data, pageNumber) {
+async function extractImages$1(data, pageNumber) {
   const pdf = isPDFDocumentProxy(data) ? data : await getDocumentProxy(data);
   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}.`
+    );
+  }
   const operatorList = await page.getOperatorList();
   const { OPS } = await getResolvedPDFJS();
   const images = [];
-  for (const op of operatorList.fnArray) {
+  for (let i = 0; i < operatorList.fnArray.length; i++) {
+    const op = operatorList.fnArray[i];
     if (op !== OPS.paintImageXObject) {
       continue;
     }
-    const image = await page.objs.get(operatorList.argsArray[op][0]);
-    if (image.data) {
-      images.push(image.data.buffer);
-    }
+    const imageKey = operatorList.argsArray[i][0];
+    const image = await page.objs.get(imageKey);
+    images.push(image.data);
   }
   return images;
 }
+async function renderPageAsImage$1(data, pageNumber, options = {}) {
+  const pdf = isPDFDocumentProxy(data) ? data : await getDocumentProxy(data);
+  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 });
+  if (options.width) {
+    outputScale = options.width / viewport.width;
+  } else if (options.height) {
+    outputScale = options.height / viewport.height;
+  }
+  if (outputScale !== 1 && outputScale > 0) {
+    viewport = page.getViewport({ scale: outputScale });
+  }
+  const canvasFactory = await createIsomorphicCanvasFactory(options.canvas);
+  const ctx = canvasFactory.create(viewport.width, viewport.height);
+  await page.render({
+    canvasContext: ctx.context,
+    viewport
+  }).promise;
+  const dataUrl = isBrowser ? ctx.canvas.toDataURL() : ctx.canvas.toDataURL();
+  const response = await fetch(dataUrl);
+  return await response.arrayBuffer();
+}
+async function createIsomorphicCanvasFactory(canvas) {
+  const _canvas = await canvas?.();
+  return {
+    _createCanvas(width, height) {
+      if (isBrowser) {
+        const canvas2 = document.createElement("canvas");
+        canvas2.width = width;
+        canvas2.height = height;
+        return canvas2;
+      } else 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 defineUnPDFConfig(options) {
+  const { pdfjs } = { ...options };
+  if (pdfjs) {
+    await resolvePDFJSImports(pdfjs, { force: true });
+  }
+}
 
-const getPDFMeta = async (...args) => {
+const getMeta = async (...args) => {
+  await resolvePDFJSImports();
+  return await getMeta$1(...args);
+};
+const extractText = async (...args) => {
   await resolvePDFJSImports();
-  return await getPDFMeta$1(...args);
+  return await extractText$1(...args);
 };
-const extractPDFText = async (...args) => {
+const extractPDFText = extractText;
+const extractImages = async (...args) => {
   await resolvePDFJSImports();
-  return await extractPDFText$1(...args);
+  return await extractImages$1(...args);
 };
-const getImagesFromPage = async (...args) => {
+const renderPageAsImage = async (...args) => {
   await resolvePDFJSImports();
-  return await getImagesFromPage$1(...args);
+  return await renderPageAsImage$1(...args);
 };
 
 exports.defineUnPDFConfig = defineUnPDFConfig;
+exports.extractImages = extractImages;
 exports.extractPDFText = extractPDFText;
+exports.extractText = extractText;
 exports.getDocumentProxy = getDocumentProxy;
-exports.getImagesFromPage = getImagesFromPage;
-exports.getPDFMeta = getPDFMeta;
+exports.getMeta = getMeta;
 exports.getResolvedPDFJS = getResolvedPDFJS;
+exports.renderPageAsImage = renderPageAsImage;
 exports.resolvePDFJSImports = resolvePDFJSImports;

package/dist/index.d.cts

@@ -1,19 +1,27 @@
 import { BinaryData, PDFDocumentProxy, DocumentInitParameters } from './types/src/display/api';
+import * as canvas from 'canvas';
 import * as _PDFJS from './types/src/pdf';
 
-declare function getPDFMeta$1(data: BinaryData | PDFDocumentProxy): Promise<{
+declare function getMeta$1(data: BinaryData | PDFDocumentProxy): Promise<{
     info: Record<string, any>;
     metadata: Record<string, any>;
 }>;
 
-declare function extractPDFText$1(data: BinaryData | PDFDocumentProxy, options?: {
+declare function extractText$1(data: BinaryData | PDFDocumentProxy, options?: {
     mergePages?: boolean;
 }): Promise<{
     totalPages: number;
     text: string | string[];
 }>;
 
-declare function getImagesFromPage$1(data: BinaryData | PDFDocumentProxy, pageNumber: number): Promise<ArrayBuffer[]>;
+declare function extractImages$1(data: BinaryData | PDFDocumentProxy, pageNumber: number): Promise<Uint8ClampedArray[]>;
+declare function renderPageAsImage$1(data: BinaryData | PDFDocumentProxy, pageNumber: number, options?: {
+    canvas?: () => Promise<typeof canvas>;
+    /** @default 1 */
+    scale?: number;
+    width?: number;
+    height?: number;
+}): Promise<ArrayBuffer>;
 
 type PDFJS = typeof _PDFJS;
 interface UnPDFConfiguration {
@@ -26,9 +34,11 @@ interface UnPDFConfiguration {
      * // Use the legacy build
      * () => import('pdfjs-dist/legacy/build/pdf.js')
      */
-    pdfjs?: () => Promise<PDFJS>;
+    pdfjs?: () => Promise<any>;
 }
 
+declare function defineUnPDFConfig(options: UnPDFConfiguration): Promise<void>;
+
 /**
  * Returns a PDFDocumentProxy instance from a given binary data.
  *
@@ -36,14 +46,16 @@ interface UnPDFConfiguration {
  * - `isEvalSupported: false`
  */
 declare function getDocumentProxy(data: BinaryData, options?: DocumentInitParameters): Promise<PDFDocumentProxy>;
-declare function defineUnPDFConfig(options: UnPDFConfiguration): Promise<void>;
 declare function getResolvedPDFJS(): Promise<PDFJS>;
-declare function resolvePDFJSImports(pdfjsResolver?: () => Promise<PDFJS>, { force }?: {
+declare function resolvePDFJSImports(pdfjsResolver?: () => Promise<any>, { force }?: {
     force?: boolean | undefined;
 }): Promise<void>;
 
-declare const getPDFMeta: typeof getPDFMeta$1;
-declare const extractPDFText: typeof extractPDFText$1;
-declare const getImagesFromPage: typeof getImagesFromPage$1;
+declare const getMeta: typeof getMeta$1;
+declare const extractText: typeof extractText$1;
+/** @deprecated Use `extractText` instead. */
+declare const extractPDFText: typeof extractText$1;
+declare const extractImages: typeof extractImages$1;
+declare const renderPageAsImage: typeof renderPageAsImage$1;
 
-export { defineUnPDFConfig, extractPDFText, getDocumentProxy, getImagesFromPage, getPDFMeta, getResolvedPDFJS, resolvePDFJSImports };
+export { defineUnPDFConfig, extractImages, extractPDFText, extractText, getDocumentProxy, getMeta, getResolvedPDFJS, renderPageAsImage, resolvePDFJSImports };

package/dist/index.d.mts

@@ -1,19 +1,27 @@
 import { BinaryData, PDFDocumentProxy, DocumentInitParameters } from './types/src/display/api';
+import * as canvas from 'canvas';
 import * as _PDFJS from './types/src/pdf';
 
-declare function getPDFMeta$1(data: BinaryData | PDFDocumentProxy): Promise<{
+declare function getMeta$1(data: BinaryData | PDFDocumentProxy): Promise<{
     info: Record<string, any>;
     metadata: Record<string, any>;
 }>;
 
-declare function extractPDFText$1(data: BinaryData | PDFDocumentProxy, options?: {
+declare function extractText$1(data: BinaryData | PDFDocumentProxy, options?: {
     mergePages?: boolean;
 }): Promise<{
     totalPages: number;
     text: string | string[];
 }>;
 
-declare function getImagesFromPage$1(data: BinaryData | PDFDocumentProxy, pageNumber: number): Promise<ArrayBuffer[]>;
+declare function extractImages$1(data: BinaryData | PDFDocumentProxy, pageNumber: number): Promise<Uint8ClampedArray[]>;
+declare function renderPageAsImage$1(data: BinaryData | PDFDocumentProxy, pageNumber: number, options?: {
+    canvas?: () => Promise<typeof canvas>;
+    /** @default 1 */
+    scale?: number;
+    width?: number;
+    height?: number;
+}): Promise<ArrayBuffer>;
 
 type PDFJS = typeof _PDFJS;
 interface UnPDFConfiguration {
@@ -26,9 +34,11 @@ interface UnPDFConfiguration {
      * // Use the legacy build
      * () => import('pdfjs-dist/legacy/build/pdf.js')
      */
-    pdfjs?: () => Promise<PDFJS>;
+    pdfjs?: () => Promise<any>;
 }
 
+declare function defineUnPDFConfig(options: UnPDFConfiguration): Promise<void>;
+
 /**
  * Returns a PDFDocumentProxy instance from a given binary data.
  *
@@ -36,14 +46,16 @@ interface UnPDFConfiguration {
  * - `isEvalSupported: false`
  */
 declare function getDocumentProxy(data: BinaryData, options?: DocumentInitParameters): Promise<PDFDocumentProxy>;
-declare function defineUnPDFConfig(options: UnPDFConfiguration): Promise<void>;
 declare function getResolvedPDFJS(): Promise<PDFJS>;
-declare function resolvePDFJSImports(pdfjsResolver?: () => Promise<PDFJS>, { force }?: {
+declare function resolvePDFJSImports(pdfjsResolver?: () => Promise<any>, { force }?: {
     force?: boolean | undefined;
 }): Promise<void>;
 
-declare const getPDFMeta: typeof getPDFMeta$1;
-declare const extractPDFText: typeof extractPDFText$1;
-declare const getImagesFromPage: typeof getImagesFromPage$1;
+declare const getMeta: typeof getMeta$1;
+declare const extractText: typeof extractText$1;
+/** @deprecated Use `extractText` instead. */
+declare const extractPDFText: typeof extractText$1;
+declare const extractImages: typeof extractImages$1;
+declare const renderPageAsImage: typeof renderPageAsImage$1;
 
-export { defineUnPDFConfig, extractPDFText, getDocumentProxy, getImagesFromPage, getPDFMeta, getResolvedPDFJS, resolvePDFJSImports };
+export { defineUnPDFConfig, extractImages, extractPDFText, extractText, getDocumentProxy, getMeta, getResolvedPDFJS, renderPageAsImage, resolvePDFJSImports };

package/dist/index.d.ts

@@ -1,19 +1,27 @@
 import { BinaryData, PDFDocumentProxy, DocumentInitParameters } from './types/src/display/api';
+import * as canvas from 'canvas';
 import * as _PDFJS from './types/src/pdf';
 
-declare function getPDFMeta$1(data: BinaryData | PDFDocumentProxy): Promise<{
+declare function getMeta$1(data: BinaryData | PDFDocumentProxy): Promise<{
     info: Record<string, any>;
     metadata: Record<string, any>;
 }>;
 
-declare function extractPDFText$1(data: BinaryData | PDFDocumentProxy, options?: {
+declare function extractText$1(data: BinaryData | PDFDocumentProxy, options?: {
     mergePages?: boolean;
 }): Promise<{
     totalPages: number;
     text: string | string[];
 }>;
 
-declare function getImagesFromPage$1(data: BinaryData | PDFDocumentProxy, pageNumber: number): Promise<ArrayBuffer[]>;
+declare function extractImages$1(data: BinaryData | PDFDocumentProxy, pageNumber: number): Promise<Uint8ClampedArray[]>;
+declare function renderPageAsImage$1(data: BinaryData | PDFDocumentProxy, pageNumber: number, options?: {
+    canvas?: () => Promise<typeof canvas>;
+    /** @default 1 */
+    scale?: number;
+    width?: number;
+    height?: number;
+}): Promise<ArrayBuffer>;
 
 type PDFJS = typeof _PDFJS;
 interface UnPDFConfiguration {
@@ -26,9 +34,11 @@ interface UnPDFConfiguration {
      * // Use the legacy build
      * () => import('pdfjs-dist/legacy/build/pdf.js')
      */
-    pdfjs?: () => Promise<PDFJS>;
+    pdfjs?: () => Promise<any>;
 }
 
+declare function defineUnPDFConfig(options: UnPDFConfiguration): Promise<void>;
+
 /**
  * Returns a PDFDocumentProxy instance from a given binary data.
  *
@@ -36,14 +46,16 @@ interface UnPDFConfiguration {
  * - `isEvalSupported: false`
  */
 declare function getDocumentProxy(data: BinaryData, options?: DocumentInitParameters): Promise<PDFDocumentProxy>;
-declare function defineUnPDFConfig(options: UnPDFConfiguration): Promise<void>;
 declare function getResolvedPDFJS(): Promise<PDFJS>;
-declare function resolvePDFJSImports(pdfjsResolver?: () => Promise<PDFJS>, { force }?: {
+declare function resolvePDFJSImports(pdfjsResolver?: () => Promise<any>, { force }?: {
     force?: boolean | undefined;
 }): Promise<void>;
 
-declare const getPDFMeta: typeof getPDFMeta$1;
-declare const extractPDFText: typeof extractPDFText$1;
-declare const getImagesFromPage: typeof getImagesFromPage$1;
+declare const getMeta: typeof getMeta$1;
+declare const extractText: typeof extractText$1;
+/** @deprecated Use `extractText` instead. */
+declare const extractPDFText: typeof extractText$1;
+declare const extractImages: typeof extractImages$1;
+declare const renderPageAsImage: typeof renderPageAsImage$1;
 
-export { defineUnPDFConfig, extractPDFText, getDocumentProxy, getImagesFromPage, getPDFMeta, getResolvedPDFJS, resolvePDFJSImports };
+export { defineUnPDFConfig, extractImages, extractPDFText, extractText, getDocumentProxy, getMeta, getResolvedPDFJS, renderPageAsImage, resolvePDFJSImports };