unpdf 0.5.4 → 0.6.1

package/README.md

@@ -1,16 +1,18 @@
 # unpdf
 
-A collection of utilities to work with PDFs. Uses Mozilla's [PDF.js](https://github.com/mozilla/pdf.js) under the hood and lazily initializes the library.
+A collection of utilities to work with PDFs. Designed specifically for Deno, workers and other nodeless environments.
 
-`unpdf` takes advantage of [export conditions](https://nodejs.org/api/packages.html#packages_conditional_exports) to circumvent build issues in serverless environments. For example, PDF.js depends on the optional `canvas` module, which [doesn't work inside worker threads](https://github.com/Automattic/node-canvas/issues/1394).
+`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.
 
 This library is also intended as a modern alternative to the unmaintained but still popular [`pdf-parse`](https://www.npmjs.com/package/pdf-parse).
 
 ## Features
 
-- 🏗️ Conditional exports for Browser, Node and worker environments
+- 🏗️ Works in Node.js, browser and workers
+- 🪭 Includes serverless build of PDF.js ([`unpdf/pdfjs`](./package.json#L45))
 - 💬 Extract text and images from PDFs
 - 🧱 Opt-in to legacy PDF.js build
+- 💨 Zero dependencies
 
 ## Installation
 
@@ -29,32 +31,37 @@ yarn add unpdf
 
 ## Usage
 
+### Extract Text From PDF
+
 ```ts
-import { extractPDFText } from 'unpdf'
+import { extractPDFText } from "unpdf";
 
 // Fetch a PDF file from the web
-const pdf = await fetch('https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf')
-  .then(res => res.arrayBuffer())
+const pdf = 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 pdf = await readFile("./dummy.pdf");
 
 // Pass the PDF buffer to the relevant method
-const { totalPages, text } = await extractPDFText(
-  new Uint8Array(pdf), { mergePages: true }
-)
+const { totalPages, text } = await extractPDFText(new Uint8Array(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.
+
 ```ts
 // Before using any other methods, define the PDF.js module
-import { defineUnPDFConfig } from 'unpdf'
+import { defineUnPDFConfig } from "unpdf";
 
-// Use the legacy build
 defineUnPDFConfig({
-  pdfjs: () => import('pdfjs-dist/legacy/build/pdf.js')
-})
+  // Use the legacy build
+  pdfjs: () => import("pdfjs-dist/legacy/build/pdf.js"),
+});
 
 // Now, you can use the other methods
 // …
@@ -62,10 +69,32 @@ defineUnPDFConfig({
 
 ### Access the PDF.js Module
 
+This will return the resolved PDF.js module. If no build is defined, the serverless build bundled with `unpdf` will be initialized.
+
+```ts
+import { getResolvedPDFJS } from "unpdf";
+
+const { version } = await getResolvedPDFJS();
+```
+
+### Use Serverless PDF.js Build In 🦕 Deno
+
+Instead of using the methods provided by `unpdf`, you can directly import the serverless PDF.js build in Deno. This is useful if you want to use the PDF.js API directly.
+
 ```ts
-import { getResolvedPDFJS } from 'unpdf'
+import { getDocument } from "https://esm.sh/unpdf/pdfjs";
+
+const data = Deno.readFileSync("dummy.pdf");
+const doc = await getDocument(data).promise;
 
-const { version } = await getResolvedPDFJS()
+console.log(await doc.getMetadata());
+
+for (let i = 1; i <= doc.numPages; i++) {
+  const page = await doc.getPage(i);
+  const textContent = await page.getTextContent();
+  const contents = textContent.items.map((item) => item.str).join(" ");
+  console.log(contents);
+}
 ```
 
 ## Config
@@ -78,9 +107,10 @@ interface UnPDFConfiguration {
    * the PDF.js module.
    *
    * @example
+   * // Use the legacy build
    * () => import('pdfjs-dist/legacy/build/pdf.js')
    */
-  pdfjs?: () => Promise<typeof PDFJS>
+  pdfjs?: () => Promise<PDFJS>;
 }
 ```
 
@@ -91,7 +121,7 @@ interface UnPDFConfiguration {
 Define a custom PDF.js module, like the legacy build. Make sure to call this method before using any other methods.
 
 ```ts
-function defineUnPDFConfig(config: UnPDFConfiguration): Promise<void>
+function defineUnPDFConfig(config: UnPDFConfiguration): Promise<void>;
 ```
 
 ### `getResolvedPDFJS`
@@ -99,18 +129,16 @@ function defineUnPDFConfig(config: UnPDFConfiguration): Promise<void>
 Returns the resolved PDF.js module. If no build is defined, the latest version will be initialized.
 
 ```ts
-function getResolvedPDFJS(): Promise<typeof import('pdfjs-dist')>
+function getResolvedPDFJS(): Promise<PDFJS>;
 ```
 
 ### `getPDFMeta`
 
 ```ts
-function getPDFMeta(
-  data: BinaryData | PDFDocumentProxy
-): Promise<{
-  info: Record<string, any>
-  metadata: Record<string, any>
-}>
+function getPDFMeta(data: BinaryData | PDFDocumentProxy): Promise<{
+  info: Record<string, any>;
+  metadata: Record<string, any>;
+}>;
 ```
 
 ### `extractPDFText`
@@ -118,11 +146,11 @@ function getPDFMeta(
 ```ts
 function extractPDFText(
   data: BinaryData | PDFDocumentProxy,
-  { mergePages }?: { mergePages?: boolean }
+  { mergePages }?: { mergePages?: boolean },
 ): Promise<{
-  totalPages: number
-  text: string | string[]
-}>
+  totalPages: number;
+  text: string | string[];
+}>;
 ```
 
 ### `getImagesFromPage`
@@ -130,10 +158,16 @@ function extractPDFText(
 ```ts
 function getImagesFromPage(
   data: BinaryData | PDFDocumentProxy,
-  pageNumber: number
-): Promise<ArrayBuffer[]>
+  pageNumber: number,
+): Promise<ArrayBuffer[]>;
 ```
 
+## FAQ
+
+### What About Canvas?
+
+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.
+
 ## License
 
 [MIT](./LICENSE) License © 2023-PRESENT [Johann Schopplich](https://github.com/johannschopplich)

package/dist/index.cjs

@@ -0,0 +1,120 @@
+'use strict';
+
+let resolvedModule;
+async function getDocumentProxy(data, options = {}) {
+  const { getDocument } = await getResolvedPDFJS();
+  const pdf = await getDocument({
+    data,
+    isEvalSupported: false,
+    ...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();
+  }
+  return resolvedModule;
+}
+async function resolvePDFJSImports(pdfjsResolver, { force = false } = {}) {
+  if (resolvedModule && !force) {
+    return;
+  }
+  if (pdfjsResolver) {
+    try {
+      const _import = await pdfjsResolver();
+      resolvedModule = _import.default || _import;
+      return;
+    } catch {
+      throw new Error(
+        "Resolving failed. Please check the provided configuration."
+      );
+    }
+  }
+  try {
+    resolvedModule = await import('unpdf/pdfjs');
+  } catch {
+    throw new Error(
+      "PDF.js is not available. Please add the package as a dependency."
+    );
+  }
+}
+function isPDFDocumentProxy(data) {
+  return typeof data === "object" && data !== null && "_pdfInfo" in data;
+}
+
+async function getPDFMeta$1(data) {
+  const pdf = isPDFDocumentProxy(data) ? data : await getDocumentProxy(data);
+  const meta = await pdf.getMetadata();
+  return {
+    info: meta?.info ?? {},
+    metadata: meta?.metadata?.getAll() ?? {}
+  };
+}
+
+async function extractPDFText$1(data, 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))
+  );
+  const filteredTexts = texts.filter(Boolean);
+  return {
+    totalPages: pdf.numPages,
+    text: mergePages ? filteredTexts.join("\n\n") : filteredTexts
+  };
+}
+async function getPageText(pdf, pageNumber) {
+  const page = await pdf.getPage(pageNumber);
+  const content = await page.getTextContent();
+  const items = content.items;
+  if (items.length === 0) {
+    return;
+  }
+  return items.map(({ str }) => str).join("\n");
+}
+
+async function getImagesFromPage$1(data, pageNumber) {
+  const pdf = isPDFDocumentProxy(data) ? data : await getDocumentProxy(data);
+  const page = await pdf.getPage(pageNumber);
+  const operatorList = await page.getOperatorList();
+  const { OPS } = await getResolvedPDFJS();
+  const images = [];
+  for (const op of operatorList.fnArray) {
+    if (op !== OPS.paintImageXObject) {
+      continue;
+    }
+    const image = await page.objs.get(operatorList.argsArray[op][0]);
+    if (image.data) {
+      images.push(image.data.buffer);
+    }
+  }
+  return images;
+}
+
+const getPDFMeta = async (...args) => {
+  await resolvePDFJSImports();
+  return await getPDFMeta$1(...args);
+};
+const extractPDFText = async (...args) => {
+  await resolvePDFJSImports();
+  return await extractPDFText$1(...args);
+};
+const getImagesFromPage = async (...args) => {
+  await resolvePDFJSImports();
+  return await getImagesFromPage$1(...args);
+};
+
+exports.defineUnPDFConfig = defineUnPDFConfig;
+exports.extractPDFText = extractPDFText;
+exports.getDocumentProxy = getDocumentProxy;
+exports.getImagesFromPage = getImagesFromPage;
+exports.getPDFMeta = getPDFMeta;
+exports.getResolvedPDFJS = getResolvedPDFJS;
+exports.resolvePDFJSImports = resolvePDFJSImports;

package/dist/index.d.cts

@@ -0,0 +1,49 @@
+import { BinaryData, PDFDocumentProxy, DocumentInitParameters } from './types/src/display/api';
+import * as _PDFJS from './types/src/pdf';
+
+declare function getPDFMeta$1(data: BinaryData | PDFDocumentProxy): Promise<{
+    info: Record<string, any>;
+    metadata: Record<string, any>;
+}>;
+
+declare function extractPDFText$1(data: BinaryData | PDFDocumentProxy, options?: {
+    mergePages?: boolean;
+}): Promise<{
+    totalPages: number;
+    text: string | string[];
+}>;
+
+declare function getImagesFromPage$1(data: BinaryData | PDFDocumentProxy, pageNumber: number): Promise<ArrayBuffer[]>;
+
+type PDFJS = typeof _PDFJS;
+interface UnPDFConfiguration {
+    /**
+     * By default, UnPDF will use the latest version of PDF.js. If you want to
+     * use an older version or the legacy build, set a promise that resolves to
+     * the PDF.js module.
+     *
+     * @example
+     * // Use the legacy build
+     * () => import('pdfjs-dist/legacy/build/pdf.js')
+     */
+    pdfjs?: () => Promise<PDFJS>;
+}
+
+/**
+ * Returns a PDFDocumentProxy instance from a given binary data.
+ *
+ * Applies the following defaults:
+ * - `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 }?: {
+    force?: boolean | undefined;
+}): Promise<void>;
+
+declare const getPDFMeta: typeof getPDFMeta$1;
+declare const extractPDFText: typeof extractPDFText$1;
+declare const getImagesFromPage: typeof getImagesFromPage$1;
+
+export { defineUnPDFConfig, extractPDFText, getDocumentProxy, getImagesFromPage, getPDFMeta, getResolvedPDFJS, resolvePDFJSImports };

package/dist/index.d.mts

@@ -0,0 +1,49 @@
+import { BinaryData, PDFDocumentProxy, DocumentInitParameters } from './types/src/display/api';
+import * as _PDFJS from './types/src/pdf';
+
+declare function getPDFMeta$1(data: BinaryData | PDFDocumentProxy): Promise<{
+    info: Record<string, any>;
+    metadata: Record<string, any>;
+}>;
+
+declare function extractPDFText$1(data: BinaryData | PDFDocumentProxy, options?: {
+    mergePages?: boolean;
+}): Promise<{
+    totalPages: number;
+    text: string | string[];
+}>;
+
+declare function getImagesFromPage$1(data: BinaryData | PDFDocumentProxy, pageNumber: number): Promise<ArrayBuffer[]>;
+
+type PDFJS = typeof _PDFJS;
+interface UnPDFConfiguration {
+    /**
+     * By default, UnPDF will use the latest version of PDF.js. If you want to
+     * use an older version or the legacy build, set a promise that resolves to
+     * the PDF.js module.
+     *
+     * @example
+     * // Use the legacy build
+     * () => import('pdfjs-dist/legacy/build/pdf.js')
+     */
+    pdfjs?: () => Promise<PDFJS>;
+}
+
+/**
+ * Returns a PDFDocumentProxy instance from a given binary data.
+ *
+ * Applies the following defaults:
+ * - `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 }?: {
+    force?: boolean | undefined;
+}): Promise<void>;
+
+declare const getPDFMeta: typeof getPDFMeta$1;
+declare const extractPDFText: typeof extractPDFText$1;
+declare const getImagesFromPage: typeof getImagesFromPage$1;
+
+export { defineUnPDFConfig, extractPDFText, getDocumentProxy, getImagesFromPage, getPDFMeta, getResolvedPDFJS, resolvePDFJSImports };

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+import { BinaryData, PDFDocumentProxy, DocumentInitParameters } from './types/src/display/api';
+import * as _PDFJS from './types/src/pdf';
+
+declare function getPDFMeta$1(data: BinaryData | PDFDocumentProxy): Promise<{
+    info: Record<string, any>;
+    metadata: Record<string, any>;
+}>;
+
+declare function extractPDFText$1(data: BinaryData | PDFDocumentProxy, options?: {
+    mergePages?: boolean;
+}): Promise<{
+    totalPages: number;
+    text: string | string[];
+}>;
+
+declare function getImagesFromPage$1(data: BinaryData | PDFDocumentProxy, pageNumber: number): Promise<ArrayBuffer[]>;
+
+type PDFJS = typeof _PDFJS;
+interface UnPDFConfiguration {
+    /**
+     * By default, UnPDF will use the latest version of PDF.js. If you want to
+     * use an older version or the legacy build, set a promise that resolves to
+     * the PDF.js module.
+     *
+     * @example
+     * // Use the legacy build
+     * () => import('pdfjs-dist/legacy/build/pdf.js')
+     */
+    pdfjs?: () => Promise<PDFJS>;
+}
+
+/**
+ * Returns a PDFDocumentProxy instance from a given binary data.
+ *
+ * Applies the following defaults:
+ * - `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 }?: {
+    force?: boolean | undefined;
+}): Promise<void>;
+
+declare const getPDFMeta: typeof getPDFMeta$1;
+declare const extractPDFText: typeof extractPDFText$1;
+declare const getImagesFromPage: typeof getImagesFromPage$1;
+
+export { defineUnPDFConfig, extractPDFText, getDocumentProxy, getImagesFromPage, getPDFMeta, getResolvedPDFJS, resolvePDFJSImports };

package/dist/index.mjs

@@ -0,0 +1,112 @@
+let resolvedModule;
+async function getDocumentProxy(data, options = {}) {
+  const { getDocument } = await getResolvedPDFJS();
+  const pdf = await getDocument({
+    data,
+    isEvalSupported: false,
+    ...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();
+  }
+  return resolvedModule;
+}
+async function resolvePDFJSImports(pdfjsResolver, { force = false } = {}) {
+  if (resolvedModule && !force) {
+    return;
+  }
+  if (pdfjsResolver) {
+    try {
+      const _import = await pdfjsResolver();
+      resolvedModule = _import.default || _import;
+      return;
+    } catch {
+      throw new Error(
+        "Resolving failed. Please check the provided configuration."
+      );
+    }
+  }
+  try {
+    resolvedModule = await import('unpdf/pdfjs');
+  } catch {
+    throw new Error(
+      "PDF.js is not available. Please add the package as a dependency."
+    );
+  }
+}
+function isPDFDocumentProxy(data) {
+  return typeof data === "object" && data !== null && "_pdfInfo" in data;
+}
+
+async function getPDFMeta$1(data) {
+  const pdf = isPDFDocumentProxy(data) ? data : await getDocumentProxy(data);
+  const meta = await pdf.getMetadata();
+  return {
+    info: meta?.info ?? {},
+    metadata: meta?.metadata?.getAll() ?? {}
+  };
+}
+
+async function extractPDFText$1(data, 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))
+  );
+  const filteredTexts = texts.filter(Boolean);
+  return {
+    totalPages: pdf.numPages,
+    text: mergePages ? filteredTexts.join("\n\n") : filteredTexts
+  };
+}
+async function getPageText(pdf, pageNumber) {
+  const page = await pdf.getPage(pageNumber);
+  const content = await page.getTextContent();
+  const items = content.items;
+  if (items.length === 0) {
+    return;
+  }
+  return items.map(({ str }) => str).join("\n");
+}
+
+async function getImagesFromPage$1(data, pageNumber) {
+  const pdf = isPDFDocumentProxy(data) ? data : await getDocumentProxy(data);
+  const page = await pdf.getPage(pageNumber);
+  const operatorList = await page.getOperatorList();
+  const { OPS } = await getResolvedPDFJS();
+  const images = [];
+  for (const op of operatorList.fnArray) {
+    if (op !== OPS.paintImageXObject) {
+      continue;
+    }
+    const image = await page.objs.get(operatorList.argsArray[op][0]);
+    if (image.data) {
+      images.push(image.data.buffer);
+    }
+  }
+  return images;
+}
+
+const getPDFMeta = async (...args) => {
+  await resolvePDFJSImports();
+  return await getPDFMeta$1(...args);
+};
+const extractPDFText = async (...args) => {
+  await resolvePDFJSImports();
+  return await extractPDFText$1(...args);
+};
+const getImagesFromPage = async (...args) => {
+  await resolvePDFJSImports();
+  return await getImagesFromPage$1(...args);
+};
+
+export { defineUnPDFConfig, extractPDFText, getDocumentProxy, getImagesFromPage, getPDFMeta, getResolvedPDFJS, resolvePDFJSImports };

package/dist/pdfjs.d.mts

@@ -0,0 +1 @@
+export * from './types/src/pdf.d.ts'

package/dist/pdfjs.d.ts

@@ -0,0 +1 @@
+export * from './types/src/pdf.d.ts'