pd4ml 0.0.0-stage → 1.0.0

package/lib/installer.js

@@ -0,0 +1,218 @@
+'use strict';
+// Downloads a PD4ML build from the PD4ML Maven repository and makes it the module's default:
+//
+//   pd4ml install                    the most recent 4.* release (also: npx pd4ml install)
+//   pd4ml install --snapshots        the most recent 4.* build, snapshots included
+//   pd4ml install 4.0.23fx2          an exact version
+//
+// or install() / installAsync() from code. The jar is stored in the user's cache directory
+// (PD4ML_HOME to choose another) with the Bouncy Castle jars PD4ML needs for encryption and
+// signing, every file verified against its published SHA-1 checksum. With no build installed
+// or configured, the first use of PD4ML downloads one (PD4ML_AUTO_INSTALL=0 turns that off).
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const { InstallError } = require('./errors');
+
+const REPOSITORY = 'https://pd4ml.com/maven2';
+const CENTRAL = 'https://repo1.maven.org/maven2';
+const GROUP_PATH = 'com/pd4ml/pd4ml';
+/** The Bouncy Castle version PD4ML is built against (https://pd4ml.com/docs/#2.-obtaining-pd4ml). */
+const BOUNCYCASTLE_VERSION = '1.84';
+const BOUNCYCASTLE = ['bcprov-jdk18on', 'bcpkix-jdk18on', 'bcutil-jdk18on'];
+const MANIFEST = 'installed.json';
+const VERSION = /^(\d+)\.(\d+)\.(\d+)(?:fx(\d+)(?:a(\d+))?)?(-jakarta)?(-SNAPSHOT)?$/;
+
+// ------------------------------------------------------------------------------------- versions
+
+/**
+ * An ordering key for a PD4ML version (4.1.1, 4.0.23fx2, 4.0.23fx1a1, 4.1.2-SNAPSHOT), or null
+ * for an unknown form. A snapshot sorts below its release, an fxNaM pre-release below fxN.
+ */
+function versionKey(version) {
+  const m = VERSION.exec(version);
+  if (!m) return null;
+  const n = i => (m[i] === undefined ? 0 : Number(m[i]));
+  return [n(1), n(2), n(3), n(4), m[5] === undefined ? 1 : 0, n(5), m[7] === undefined ? 1 : 0];
+}
+
+function compareKeys(a, b) {
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return a[i] - b[i];
+  return 0;
+}
+
+/** Versions sorted oldest first (unknown forms dropped). */
+function sortVersions(versions) {
+  return versions.filter(v => versionKey(v)).sort((a, b) => compareKeys(versionKey(a), versionKey(b)));
+}
+
+/** The most recent `major`.* version: releases only unless `snapshots`, -jakarta only with `jakarta`. */
+function selectVersion(versions, { major = 4, snapshots = false, jakarta = false } = {}) {
+  const candidates = sortVersions(versions.filter(v => {
+    const k = versionKey(v);
+    return k && k[0] === major && (snapshots || !v.endsWith('-SNAPSHOT')) && v.includes('-jakarta') === jakarta;
+  }));
+  if (!candidates.length) throw new InstallError(`no ${major}.* version in the repository`);
+  return candidates[candidates.length - 1];
+}
+
+// ------------------------------------------------------------------------------------- download
+
+async function fetchBytes(url) {
+  let response;
+  try {
+    response = await fetch(url, { headers: { 'User-Agent': 'pd4ml-node' } });
+  } catch (e) {
+    throw new InstallError(`cannot download ${url}: ${e.cause ? e.cause.message : e.message}`);
+  }
+  if (!response.ok) throw new InstallError(`cannot download ${url} (HTTP ${response.status})`);
+  return Buffer.from(await response.arrayBuffer());
+}
+
+/** The versions the repository lists. */
+async function availableVersionsAsync(repository = REPOSITORY) {
+  const xml = (await fetchBytes(`${repository}/${GROUP_PATH}/maven-metadata.xml`)).toString('utf8');
+  return [...xml.matchAll(/<version>([^<]+)<\/version>/g)].map(m => m[1].trim());
+}
+
+async function jarName(version, repository) {
+  if (!version.endsWith('-SNAPSHOT')) return `pd4ml-${version}.jar`;
+  const xml = (await fetchBytes(`${repository}/${GROUP_PATH}/${version}/maven-metadata.xml`)).toString('utf8');
+  for (const sv of xml.matchAll(/<snapshotVersion>([\s\S]*?)<\/snapshotVersion>/g)) {
+    const tag = t => (sv[1].match(new RegExp(`<${t}>([^<]*)</${t}>`)) || [])[1];
+    if (tag('extension') === 'jar' && !tag('classifier') && tag('value')) return `pd4ml-${tag('value')}.jar`;
+  }
+  const ts = (xml.match(/<timestamp>([^<]+)</) || [])[1];
+  const build = (xml.match(/<buildNumber>([^<]+)</) || [])[1];
+  if (ts && build) return `pd4ml-${version.slice(0, -'-SNAPSHOT'.length)}-${ts}-${build}.jar`;
+  throw new InstallError(`no jar listed for ${version}`);
+}
+
+async function download(url, file, { force, quiet }) {
+  if (!force && fs.existsSync(file)) return;
+  if (!quiet) process.stderr.write(`downloading ${url}\n`);
+  const data = await fetchBytes(url);
+  const expected = (await fetchBytes(url + '.sha1')).toString('ascii').trim().split(/\s+/)[0].toLowerCase();
+  const actual = crypto.createHash('sha1').update(data).digest('hex');
+  if (expected && actual !== expected) throw new InstallError(`checksum mismatch for ${url}: ${actual} != ${expected}`);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.part`;
+  fs.writeFileSync(tmp, data);
+  fs.renameSync(tmp, file);
+}
+
+/**
+ * Downloads a PD4ML build (unless already there) and makes it the default one; resolves to the
+ * jar's path. Options: snapshots, jakarta, repository, home, force, quiet, bouncycastle (default true).
+ */
+async function installAsync(version = 'latest', options = {}) {
+  const repository = options.repository || REPOSITORY;
+  const home = options.home || defaultHome();
+  if (version === 'latest') {
+    version = selectVersion(await availableVersionsAsync(repository), { snapshots: options.snapshots, jakarta: options.jakarta });
+  }
+  const name = await jarName(version, repository);
+  const jar = path.join(home, name);
+  await download(`${repository}/${GROUP_PATH}/${version}/${name}`, jar, options);
+  const libs = [];
+  if (options.bouncycastle !== false) {
+    for (const artifact of BOUNCYCASTLE) {
+      const lib = `${artifact}-${BOUNCYCASTLE_VERSION}.jar`;
+      await download(`${CENTRAL}/org/bouncycastle/${artifact}/${BOUNCYCASTLE_VERSION}/${lib}`, path.join(home, 'lib', lib), options);
+      libs.push(`lib/${lib}`);
+    }
+  }
+  const manifest = { ...readManifest(home), version, jar: name, libs, repository, installed: new Date().toISOString() };
+  const tmp = path.join(home, `${MANIFEST}.${process.pid}.part`); // several processes may install at once
+  fs.writeFileSync(tmp, JSON.stringify(manifest, null, 2));
+  fs.renameSync(tmp, path.join(home, MANIFEST));
+  if (!options.quiet) process.stderr.write(`PD4ML ${version}: ${jar}\n`);
+  return jar;
+}
+
+// Synchronous forms: the download runs in a child Node process, so they can be used from the
+// synchronous API (and from the first use of PD4ML).
+function runSync(task, args) {
+  try {
+    const out = execFileSync(process.execPath, [__filename, '--run', task, JSON.stringify(args)], {
+      stdio: ['ignore', 'pipe', 'inherit'],
+      windowsHide: true,
+    });
+    return JSON.parse(out.toString('utf8'));
+  } catch (e) {
+    const message = e.stdout && e.stdout.length ? e.stdout.toString('utf8').trim() : e.message;
+    throw new InstallError(message);
+  }
+}
+
+/** Synchronous installAsync(): downloads a PD4ML build and returns the jar's path. */
+function install(version = 'latest', options = {}) {
+  return runSync('install', [version, options]);
+}
+
+/** The versions the repository lists (synchronous). */
+function availableVersions(repository = REPOSITORY) {
+  return runSync('versions', [repository]);
+}
+
+// -------------------------------------------------------------------------------- installation
+
+/** Where downloaded builds go: PD4ML_HOME, else the user's cache directory. */
+function defaultHome() {
+  if (process.env.PD4ML_HOME) return process.env.PD4ML_HOME;
+  if (process.platform === 'win32') {
+    return path.join(process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'), 'pd4ml-node');
+  }
+  return path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'pd4ml-node');
+}
+
+function readManifest(home) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(home, MANIFEST), 'utf8'));
+  } catch (e) {
+    return {};
+  }
+}
+
+/** The jar install() made the default, or null. */
+function installedJar(home = defaultHome()) {
+  const { jar } = readManifest(home);
+  const p = jar ? path.join(home, jar) : null;
+  return p && fs.existsSync(p) ? p : null;
+}
+
+/** The installed build's classpath: the PD4ML jar and its companion jars; empty if none. */
+function installedClasspath(home = defaultHome()) {
+  const jar = installedJar(home);
+  if (!jar) return [];
+  const libs = (readManifest(home).libs || []).map(l => path.join(home, l)).filter(p => fs.existsSync(p));
+  return [jar, ...libs];
+}
+
+/** The version install() made the default, or null. */
+function installedVersion(home = defaultHome()) {
+  return installedJar(home) ? readManifest(home).version || null : null;
+}
+
+/** Whether the first use of PD4ML may download a build (PD4ML_AUTO_INSTALL, default on). */
+function autoInstallEnabled() {
+  return !['0', 'false', 'no', 'off'].includes(String(process.env.PD4ML_AUTO_INSTALL || '1').trim().toLowerCase());
+}
+
+module.exports = {
+  REPOSITORY, BOUNCYCASTLE_VERSION,
+  versionKey, sortVersions, selectVersion,
+  install, installAsync, availableVersions, availableVersionsAsync,
+  defaultHome, installedJar, installedClasspath, installedVersion, autoInstallEnabled,
+};
+
+// the child process of runSync()
+if (require.main === module && process.argv[2] === '--run') {
+  const [task, json] = process.argv.slice(3);
+  const args = JSON.parse(json);
+  const work = task === 'install' ? installAsync(...args) : availableVersionsAsync(...args);
+  work.then(result => process.stdout.write(JSON.stringify(result)),
+    e => { process.stdout.write(e.message); process.exitCode = 1; });
+}

package/lib/java.js

@@ -0,0 +1,149 @@
+'use strict';
+// Java objects and classes as JavaScript proxies.
+//
+//   const map = new (Java.type('java.util.HashMap'))();
+//   map.put('k', 'v');                      // any Java method, by its Java name
+//   PageSize.A4.$get('width')               // a public field
+//   PageSize.A4.getWidth()                  // a method
+//   Units.MM.$enum                          // an enum constant's name
+//
+// Helpers are $-prefixed ($get, $set, $call, $class, $enum, $instanceOf) so they can never hide
+// a Java method of the same name. Objects are released in Java when the JavaScript object is
+// garbage collected.
+const util = require('util');
+const { Bridge, JavaFloat } = require('./bridge');
+
+const HANDLE = Symbol('pd4ml.handle');
+const BRIDGE = Symbol('pd4ml.bridge');
+
+function isJavaObject(v) {
+  return v !== null && (typeof v === 'object' || typeof v === 'function') && v[HANDLE] !== undefined;
+}
+
+function handleOf(v) { return v[HANDLE]; }
+
+function wrapObject(bridge, handle, className, enumName) {
+  const target = { [HANDLE]: handle, [BRIDGE]: bridge, className, enumName: enumName || null };
+  let proxy;
+  const javaToString = () => bridge.call(proxy, 'toString', []);
+  proxy = new Proxy(target, {
+    get(t, prop) {
+      if (prop === HANDLE || prop === BRIDGE) return t[prop];
+      if (typeof prop === 'symbol') {
+        if (prop === Symbol.toPrimitive) return () => javaToString();
+        if (prop === util.inspect.custom) return () => `JavaObject<${className}> ${t.enumName || javaToString()}`;
+        if (prop === Symbol.toStringTag) return 'JavaObject';
+        return undefined;
+      }
+      switch (prop) {
+        case 'then': return undefined; // not a thenable: `await obj` gives the object
+        case '$class': return className;
+        case '$enum': return t.enumName;
+        case '$get': return field => bridge.getField(proxy, field);
+        case '$set': return (field, value) => bridge.setField(proxy, field, value);
+        case '$call': return (method, ...args) => bridge.call(proxy, method, args);
+        case '$instanceOf': return cls => bridge.instanceOf(proxy, cls);
+        case 'toString': return javaToString;
+        case 'toJSON': return () => (t.enumName !== null ? t.enumName : javaToString());
+        default: return (...args) => bridge.call(proxy, prop, args);
+      }
+    },
+    set() {
+      throw new TypeError('set Java fields with obj.$set(name, value)');
+    },
+  });
+  bridge.track(proxy, handle);
+  return proxy;
+}
+
+// ------------------------------------------------------------------------------------ classes
+
+const descriptions = new WeakMap(); // bridge -> Map(class -> describe() result + constant cache)
+
+function described(bridge, name) {
+  let byClass = descriptions.get(bridge);
+  if (!byClass) {
+    byClass = new Map();
+    descriptions.set(bridge, byClass);
+  }
+  let d = byClass.get(name);
+  if (!d) {
+    const info = bridge.describe(name);
+    d = {
+      className: info.class,
+      fields: new Set(info.fields),
+      constants: new Set(info.constants),
+      methods: new Set(info.methods),
+      values: new Map(),
+    };
+    byClass.set(name, d);
+  }
+  return d;
+}
+
+/**
+ * A Java class: `type('java.util.Locale').getDefault()` (static methods), `PageSize.A4` (static
+ * fields), `new PageMargins(10, 10, 10, 10, Units.MM)` (constructors). Nested classes by '.'
+ * or '$' (`com.pd4ml.Constants.LayoutEngine`).
+ */
+function type(name) {
+  const target = function JavaClass() {};
+  return new Proxy(target, {
+    get(t, prop) {
+      if (typeof prop === 'symbol') {
+        if (prop === util.inspect.custom) return () => `JavaClass<${name}>`;
+        if (prop === Symbol.toStringTag) return 'JavaClass';
+        return undefined;
+      }
+      switch (prop) {
+        case 'then': return undefined;
+        case '$name': return name;
+        case '$new': return (...args) => Bridge.get().newObject(name, args);
+        case '$get': return field => Bridge.get().getField(name, field);
+        case '$set': return (field, value) => Bridge.get().setField(name, field, value);
+        case '$call': return (method, ...args) => Bridge.get().callStatic(name, method, args);
+        case 'toString': return () => name;
+        case 'prototype': return t.prototype;
+        default: break;
+      }
+      const bridge = Bridge.get();
+      const d = described(bridge, name);
+      if (d.fields.has(prop)) {
+        if (!d.constants.has(prop)) return bridge.getField(name, prop);
+        if (!d.values.has(prop)) d.values.set(prop, bridge.getField(name, prop));
+        return d.values.get(prop);
+      }
+      if (d.methods.has(prop)) return (...args) => bridge.callStatic(name, prop, args);
+      return undefined;
+    },
+    set(t, prop, value) {
+      Bridge.get().setField(name, prop, value);
+      return true;
+    },
+    has(t, prop) {
+      const d = described(Bridge.get(), name);
+      return d.fields.has(prop) || d.methods.has(prop);
+    },
+    construct(t, args) {
+      return Bridge.get().newObject(name, args);
+    },
+    apply() {
+      throw new TypeError(`${name} is a Java class: use new`);
+    },
+  });
+}
+
+/**
+ * A Java object implementing the interface `iface`, its methods calling `fn(method, args)` on
+ * this thread while PD4ML runs (`Java.proxy('com.pd4ml.ProgressListener', (m, a) => ...)`).
+ */
+function proxy(iface, fn) {
+  return Bridge.get().proxy(iface, fn);
+}
+
+/** A number passed to Java as a float/double: `Java.float(10)` (a plain 10 is an int). */
+function float(value) {
+  return new JavaFloat(value);
+}
+
+module.exports = { type, proxy, float, isJavaObject, handleOf, wrapObject };

package/lib/pd4ml.js

@@ -0,0 +1,192 @@
+'use strict';
+// PD4ML: com.pd4ml.PD4ML with Node I/O and the v42 layout engine by default.
+const fs = require('fs');
+const java = require('./java');
+const runtime = require('./runtime');
+const { Bridge, Output } = require('./bridge');
+
+const PD4MLClass = java.type('com.pd4ml.PD4ML');
+const DEFAULT_ENGINE = 'v42';
+let warnedNoEngines = false;
+
+/**
+ * An HTML to PDF/DOCX/RTF/image converter. Every method of the Java class com.pd4ml.PD4ML is
+ * available by its Java name (setPageSize, addStyle, useTTF...); these also take Node I/O:
+ * readHTML (a path, URL or Buffer), readHtmlString, writePDF/writeDOCX/writeRTF (a Buffer is
+ * returned, or written to a path, file descriptor or stream), renderAsImages and
+ * monitorProgressWith (a JavaScript function).
+ *
+ *     const pd = new PD4ML();
+ *     pd.setPageSize(PageSize.A4);
+ *     pd.readHtmlString('<h1>Hello</h1>');
+ *     const pdf = pd.writePDF();
+ */
+class PD4ML {
+  /**
+   * @param {object} [options]
+   * @param {string} [options.license] a license serial number or license file URL (default:
+   *   pd4ml.lic on the classpath or in the working directory, else evaluation mode)
+   * @param {number} [options.htmlWidth] the width in pixels the HTML is laid out in
+   * @param {string|object|false} [options.engine] 'v42', 'v40' or a LayoutEngine; default v42
+   *   where the build has layout engines, else the build's own; false: the Java default
+   */
+  constructor(options = {}) {
+    const { license, htmlWidth } = options;
+    let { engine } = options;
+    const args = [];
+    if (license !== undefined && license !== null) args.push(license);
+    if (htmlWidth !== undefined && htmlWidth !== null) args.push(htmlWidth);
+    /** The Java object (com.pd4ml.PD4ML). */
+    this.java = Bridge.get().newObject('com.pd4ml.PD4ML', args);
+    /** The layout engine chosen ('v42', 'v40'), or null for the build's own. */
+    this.engine = null;
+    if (engine === undefined || engine === null) {
+      if (runtime.hasLayoutEngines()) {
+        engine = DEFAULT_ENGINE;
+      } else {
+        engine = false;
+        if (!warnedNoEngines) {
+          warnedNoEngines = true;
+          process.emitWarning(`PD4ML ${runtime.version()} has no ${DEFAULT_ENGINE} layout engine (from 4.2): its own engine is used`);
+        }
+      }
+    }
+    if (engine !== false) this.useHtmlRenderer(engine);
+    return new Proxy(this, {
+      get(t, prop, receiver) {
+        if (typeof prop === 'symbol' || prop in t) return Reflect.get(t, prop, receiver);
+        if (prop === 'then') return undefined;
+        return (...a) => t.java.$call(prop, ...a);
+      },
+    });
+  }
+
+  // ---------------------------------------------------------------------------- layout engine
+
+  /**
+   * Chooses the layout engine: 'v42', 'v40' or a LayoutEngine, optionally with the HTML width
+   * and engine parameters (an object of strings).
+   */
+  useHtmlRenderer(engine = DEFAULT_ENGINE, htmlWidth = null, params = null) {
+    if (!runtime.hasLayoutEngines()) {
+      throw new Error(`PD4ML ${runtime.version()} has no layout engines to choose from (Constants.LayoutEngine is new in 4.2)`);
+    }
+    const e = typeof engine === 'string' ? java.type('com.pd4ml.Constants$LayoutEngine').valueOf(engine) : engine;
+    if (params) {
+      const strings = Object.fromEntries(Object.entries(params).map(([k, v]) => [k, String(v)]));
+      this.java.useHtmlRenderer(e, htmlWidth === null ? -1 : htmlWidth, strings);
+    } else if (htmlWidth !== null) {
+      this.java.useHtmlRenderer(e, htmlWidth);
+    } else {
+      this.java.useHtmlRenderer(e);
+    }
+    this.engine = e.$enum;
+  }
+
+  // ------------------------------------------------------------------------------------ input
+
+  /**
+   * Reads the document to convert.
+   * @param {string|URL|Buffer|Uint8Array|object} source a URL ('https://...', 'file:...'), a local
+   *   path, the document's bytes, or a Java URL/InputStream
+   * @param {string} [baseUrl] where relative links resolve (a URL or a local directory/file); for
+   *   a path or URL source, its own location
+   * @param {string} [encoding] the document's encoding when it does not declare one
+   */
+  readHTML(source, baseUrl = null, encoding = null) {
+    if (typeof source === 'string' || source instanceof URL
+        || (java.isJavaObject(source) && source.$class === 'java.net.URL')) {
+      const url = runtime.toUrl(source);
+      encoding === null ? this.java.readHTML(url) : this.java.readHTML(url, encoding);
+      return;
+    }
+    const content = java.isJavaObject(source) ? source : runtime.bytes(source);
+    const base = baseUrl === null ? null : runtime.toUrl(baseUrl);
+    if (baseUrl === null && encoding === null) {
+      this.java.readHTML(content);
+    } else if (encoding === null) {
+      this.java.readHTML(content, base);
+    } else {
+      this.java.readHTML(content, base, encoding);
+    }
+  }
+
+  /** Reads the document from a string of HTML. */
+  readHtmlString(html, baseUrl = null) {
+    this.readHTML(Buffer.from(String(html), 'utf8'), baseUrl, 'UTF-8');
+  }
+
+  // ----------------------------------------------------------------------------------- output
+
+  /**
+   * Writes the PDF.
+   * @param {string|number|object} [target] a file path, a file descriptor or a writable stream
+   *   (an HTTP response...); none: the PDF is returned as a Buffer
+   * @param {string|object} [spec] a PdfSpec (PdfSpec.PDFA_2B), one of its keywords ('pdf/a-2b',
+   *   see PdfSpec.listKeywords()), or 'PDF'/'PDFA'/'PDFUA'
+   */
+  writePDF(target = null, spec = null) {
+    const s = runtime.pdfSpec(spec);
+    const outs = [];
+    Bridge.get().call(this.java, 'writePDF', s === null ? [new Output()] : [new Output(), s], outs);
+    return runtime.deliver(outs[0] || Buffer.alloc(0), target);
+  }
+
+  /** Writes a DOCX document (see writePDF for `target`). */
+  writeDOCX(target = null) {
+    const outs = [];
+    Bridge.get().call(this.java, 'writeDOCX', [new Output()], outs);
+    return runtime.deliver(outs[0] || Buffer.alloc(0), target);
+  }
+
+  /** Writes an RTF document; `rtfWmf`: images as WMF (see writePDF for `target`). */
+  writeRTF(target = null, rtfWmf = false) {
+    const outs = [];
+    Bridge.get().call(this.java, 'writeRTF', [new Output(), rtfWmf], outs);
+    return runtime.deliver(outs[0] || Buffer.alloc(0), target);
+  }
+
+  /**
+   * renderAsImages(format): the pages as encoded images (Constants.PNG24...), an array of Buffers;
+   * renderAsImages(dir, name, format): image files written to a directory;
+   * renderAsImages(): Java BufferedImage objects.
+   */
+  renderAsImages(...args) {
+    if (args.length === 3 && typeof args[0] === 'string') {
+      const File = java.type('java.io.File');
+      fs.mkdirSync(args[0], { recursive: true });
+      return this.java.renderAsImages(new File(args[0]), args[1], args[2]);
+    }
+    return this.java.renderAsImages(...args);
+  }
+
+  /** The pages as 24-bit PNG images (Buffers). */
+  renderPng() {
+    return this.java.renderAsImages(java.type('com.pd4ml.Constants').PNG24);
+  }
+
+  // --------------------------------------------------------------------------------- progress
+
+  /**
+   * Reports conversion progress to a function (messageId, progress, note, msec) - it runs on
+   * this thread while PD4ML works - or to a Java ProgressListener.
+   */
+  monitorProgressWith(listener) {
+    const l = typeof listener === 'function'
+      ? java.proxy('com.pd4ml.ProgressListener', (method, a) => listener(Number(a[0]), Number(a[1]), a[2], Number(a[3])))
+      : listener;
+    this.java.monitorProgressWith(l);
+  }
+}
+
+PD4ML.DEFAULT_ENGINE = DEFAULT_ENGINE;
+
+// static Java members (PD4ML.getVersion()) on the class itself
+const PD4MLExport = new Proxy(PD4ML, {
+  get(t, prop, receiver) {
+    if (typeof prop === 'symbol' || prop in t) return Reflect.get(t, prop, receiver);
+    return PD4MLClass[prop];
+  },
+});
+
+module.exports = { PD4ML: PD4MLExport };

package/lib/pdf.js

@@ -0,0 +1,63 @@
+'use strict';
+// One-call conversion and PDF documents.
+//
+//   const pdf = htmlToPdf('report.html');          // a path, URL or Buffer
+//   const doc = openPdf(pdf);                       // a com.pd4ml.PdfDocument
+//   writePdf(doc, 'copy.pdf', { password: 'secret' });
+const fs = require('fs');
+const java = require('./java');
+const runtime = require('./runtime');
+const { Bridge, Output } = require('./bridge');
+const { PD4ML } = require('./pd4ml');
+
+/**
+ * Converts one document to PDF. `source` as for PD4ML#readHTML, `target` as for PD4ML#writePDF.
+ * Options: baseUrl, pageSize, pageMargins, spec, engine, htmlWidth.
+ */
+function htmlToPdf(source, target = null, options = {}) {
+  const pd = new PD4ML({ htmlWidth: options.htmlWidth, engine: options.engine });
+  if (options.pageSize) pd.setPageSize(options.pageSize);
+  if (options.pageMargins) pd.setPageMargins(options.pageMargins);
+  pd.readHTML(source, options.baseUrl === undefined ? null : options.baseUrl);
+  return pd.writePDF(target, options.spec === undefined ? null : options.spec);
+}
+
+/** PDF content from a path, a Buffer/typed array, or a string holding a PDF. */
+function pdfBytes(source) {
+  if (typeof source === 'string' && !source.startsWith('%PDF')) return fs.readFileSync(source);
+  return runtime.bytes(source);
+}
+
+/** A com.pd4ml.PdfDocument from a path, URL, Buffer or PDF string (+ password). */
+function openPdf(source, password = null) {
+  const PdfDocument = java.type('com.pd4ml.PdfDocument');
+  if ((typeof source === 'string' && /^[A-Za-z][A-Za-z0-9+.-]*:\/\//.test(source)) || source instanceof URL) {
+    return new PdfDocument(runtime.toUrl(source), password);
+  }
+  return new PdfDocument(pdfBytes(source), password);
+}
+
+/**
+ * Writes a PdfDocument (after append, overlay...): returned as a Buffer, or written to a path,
+ * fd or stream. Options: password (encrypts), permissions (Constants flags; default
+ * Constants.DefaultPermissions).
+ */
+function writePdf(document, target = null, options = {}) {
+  const outs = [];
+  if (!options.password) {
+    Bridge.get().call(document, 'write', [new Output()], outs);
+  } else {
+    const permissions = options.permissions === undefined ? java.type('com.pd4ml.Constants').DefaultPermissions : options.permissions;
+    Bridge.get().call(document, 'write', [new Output(), options.password, permissions], outs);
+  }
+  return runtime.deliver(outs[0] || Buffer.alloc(0), target);
+}
+
+/** PdfDocument.mergePDFs: two PDF documents appended into one. */
+function mergePdfs(first, second, target = null) {
+  const outs = [];
+  Bridge.get().callStatic('com.pd4ml.PdfDocument', 'mergePDFs', [pdfBytes(first), pdfBytes(second), new Output()], outs);
+  return runtime.deliver(outs[0] || Buffer.alloc(0), target);
+}
+
+module.exports = { htmlToPdf, openPdf, writePdf, mergePdfs };