index.js

'use strict';

// Node entry point for the PDF parser. Two WebAssembly modules cooperate:
//   1. PDFium (pdfium/pdfium.{js,wasm}), an Emscripten build of Google's PDF engine.
//   2. The Rust parser (lib/globeparse_wasm*), built with wasm-pack --target nodejs.
// initialize_pdfium_render() wires the second to the first. The PDF bytes are
// handed straight to WASM and never leave the process: no network, no temp files.

const fs = require('fs');
const path = require('path');

// Fail early and clearly on an unsupported Node, instead of a cryptic Emscripten abort.
(function checkNode() {
  const [maj, min] = process.versions.node.split('.').map(Number);
  if (maj < 18 || (maj === 18 && min < 3)) {
    throw new Error(
      `@captain-sdk/pdf-parser requires Node.js >= 18.3 (detected ${process.versions.node}).`
    );
  }
})();

const wasmMod = require('./lib/globeparse_wasm.js');

let ready = null;

/**
 * @param {{ assetsDir?: string }} [options] - override where the bundled PDFium
 *   assets live. Needed only when a bundler or serverless packager relocates the
 *   package's files away from this module's directory (see README, "Bundlers and
 *   serverless"). Defaults to the pdfium/ folder shipped with the package.
 */
function ensureReady(options) {
  if (!ready) {
    ready = (async () => {
      const assetsDir = (options && options.assetsDir) || path.join(__dirname, 'pdfium');
      const pdfiumJs = path.join(assetsDir, 'pdfium.js');
      if (!fs.existsSync(pdfiumJs)) {
        throw new Error(
          `Could not find the PDFium engine at ${pdfiumJs}. If you use a bundler ` +
          `(webpack, esbuild, Next.js) or a serverless packager (AWS Lambda), the ` +
          `package's pdfium/ and lib/ asset folders may not have been copied into ` +
          `your build. Copy them alongside your output, or pass ` +
          `initParser({ assetsDir: '<path to pdfium folder>' }). See the README ` +
          `"Bundlers and serverless" section.`
        );
      }
      let pdfiumModule;
      try {
        // Emscripten factory; under Node it reads pdfium.wasm from disk via locateFile.
        const PDFiumModule = require(pdfiumJs);
        pdfiumModule = await PDFiumModule({
          locateFile: (p) => path.join(assetsDir, p),
        });
      } catch (err) {
        ready = null;
        throw new Error(`Failed to load the PDFium engine: ${err && err.message ? err.message : err}`);
      }
      // __localModule is the Rust wasm instance's exports (memory + parse callbacks),
      // which pdfium-render needs to shuffle bytes between the two WASM heaps.
      const ok = wasmMod.initialize_pdfium_render(pdfiumModule, wasmMod.__localModule, false);
      if (!ok) {
        ready = null;
        throw new Error('Could not connect the parser to the PDFium engine.');
      }
      // Bind the engine now so the first real parse pays no init cost.
      wasmMod.warm_engine();
    })();
  }
  return ready;
}

/**
 * Load and instantiate the engine (PDFium + parser). Loads ~6 MB of WebAssembly,
 * so the FIRST call is the slow one (up to a few seconds cold). Call this once at
 * startup so your first real parse is fast. Optional: parsePdf() calls it for you.
 * @param {{ assetsDir?: string }} [options]
 * @returns {Promise<void>}
 */
function initParser(options) {
  return ensureReady(options);
}

/**
 * Parse PDF bytes into layout blocks (Text, Table as HTML, Figure placements, ...).
 * @param {Uint8Array|Buffer|ArrayBuffer} bytes
 * @param {{ assetsDir?: string }} [options]
 * @returns {Promise<import('./index').ParseResult>}
 * @throws {Error} when the bytes are not a PDF PDFium can open.
 */
async function parsePdf(bytes, options) {
  await ensureReady(options);
  let u8;
  if (bytes instanceof Uint8Array) u8 = bytes; // Buffer is a Uint8Array
  else if (bytes instanceof ArrayBuffer) u8 = new Uint8Array(bytes);
  else throw new TypeError('parsePdf expects a Uint8Array, Buffer, or ArrayBuffer.');
  // parse_pdf returns the block JSON string, or throws a string on a bad PDF.
  let jsonStr;
  try {
    jsonStr = wasmMod.parse_pdf(u8);
  } catch (err) {
    throw new Error(typeof err === 'string' ? err : String(err));
  }
  return JSON.parse(jsonStr);
}

/**
 * Parse many PDFs with bounded concurrency.
 * @param {Array<Uint8Array|Buffer|ArrayBuffer>} items
 * @param {{
 *   assetsDir?: string,
 *   concurrency?: number,
 *   stopOnError?: boolean,
 *   collectResults?: boolean,
 *   onProgress?: (event: {
 *     index: number,
 *     completed: number,
 *     total: number,
 *     succeeded: number,
 *     failed: number,
 *     ok: boolean
 *   }) => void
 * }} [options]
 * @returns {Promise<{
 *   total: number,
 *   succeeded: number,
 *   failed: number,
 *   results?: Array<
 *     | { ok: true, result: import('./index').ParseResult }
 *     | { ok: false, error: Error }
 *   >
 * }>}
 */
async function parsePdfBatch(items, options) {
  if (!Array.isArray(items)) {
    throw new TypeError('parsePdfBatch expects an array of Uint8Array, Buffer, or ArrayBuffer.');
  }
  const total = items.length;
  const concurrencyRaw = options && options.concurrency != null ? options.concurrency : 4;
  const concurrency = Math.max(1, Math.floor(concurrencyRaw));
  const stopOnError = Boolean(options && options.stopOnError);
  const collectResults = options && options.collectResults != null ? Boolean(options.collectResults) : true;
  const onProgress = options && typeof options.onProgress === 'function' ? options.onProgress : null;
  const results = collectResults ? new Array(total) : undefined;

  await ensureReady(options);

  let nextIndex = 0;
  let completed = 0;
  let succeeded = 0;
  let failed = 0;
  let stoppedError = null;

  async function worker() {
    for (;;) {
      if (stoppedError) return;
      const index = nextIndex++;
      if (index >= total) return;

      try {
        const result = await parsePdf(items[index], options);
        succeeded += 1;
        if (results) results[index] = { ok: true, result };
        if (onProgress) {
          onProgress({ index, completed: completed + 1, total, succeeded, failed, ok: true });
        }
      } catch (err) {
        failed += 1;
        const error = err instanceof Error ? err : new Error(String(err));
        if (results) results[index] = { ok: false, error };
        if (onProgress) {
          onProgress({ index, completed: completed + 1, total, succeeded, failed, ok: false });
        }
        if (stopOnError && !stoppedError) {
          stoppedError = { index, error };
        }
      } finally {
        completed += 1;
      }
    }
  }

  const workers = [];
  const workerCount = Math.min(concurrency, total || 1);
  for (let i = 0; i < workerCount; i += 1) workers.push(worker());
  await Promise.all(workers);

  if (stoppedError) {
    throw new Error(
      `parsePdfBatch failed at index ${stoppedError.index}: ${stoppedError.error.message}`
    );
  }

  const summary = { total, succeeded, failed };
  if (results) summary.results = results;
  return summary;
}

module.exports = { parsePdf, parsePdfBatch, initParser };