pd4ml 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,88 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# pd4ml — PD4ML for Node.js
+
+HTML and CSS to **PDF**, **PDF/A**, **PDF/UA**, **ZUGFeRD/Factur-X**, **DOCX**, **RTF** and page
+**images**, with the full public [PD4ML](https://pd4ml.com) API (Java package `com.pd4ml`)
+available to Node.js applications. New converters use PD4ML's **v42 layout engine** by default.
+
+```
+npm install pd4ml
+```
+
+The package is on npm (<https://www.npmjs.com/package/pd4ml>); its contents and releases are also
+on GitHub (<https://github.com/zxfr/pd4ml-node>).
+
+```js
+const { PD4ML, PageSize, PageMargins, Units, PdfSpec } = require('pd4ml');
+
+const pd = new PD4ML();                                     // v42 layout engine
+pd.setPageSize(PageSize.A4);
+pd.setPageMargins(new PageMargins(15, 15, 15, 15, Units.MM));
+pd.readHTML('invoice.html');                                // a path, URL or Buffer
+pd.writePDF('invoice.pdf', PdfSpec.PDFA_3B);                // a path, fd or stream; no target: a Buffer
+```
+
+The first use downloads the most recent PD4ML build (see *Installation* below). TypeScript
+declarations of the whole API are included.
+
+## Requirements
+
+- Node.js 18 or later.
+- Java 8 or later (17 or 21 recommended), found through `PD4ML_JAVA`, `JAVA_HOME` or the `PATH`.
+
+## Installation
+
+The package contains the Node module only; PD4ML itself comes from the PD4ML Maven repository
+(<https://pd4ml.com/maven2>):
+
+- **Automatically.** If no PD4ML build is installed or configured, the first use of PD4ML
+  downloads the most recent 4.x release, with the Bouncy Castle jars (for encryption and
+  signing). Every file is verified against its SHA-1 checksum and stored in a per-user cache
+  directory (`%LOCALAPPDATA%\pd4ml-node`, `~/.cache/pd4ml-node`, or `PD4ML_HOME`).
+- **Ahead of time**, better for servers and container images: `npx pd4ml install`. Run it again
+  to update to a newer release.
+
+`PD4ML_AUTO_INSTALL=0` turns the automatic download off. `npx pd4ml list` shows the available
+versions, `npx pd4ml install 4.0.23fx2` installs a specific one, and `PD4ML_CLASSPATH` /
+`PD4ML_CLASSPATH_FILE` point the module at any other build.
+
+## How it works
+
+PD4ML runs in a small Java bridge process started on first use, one per Node process (or one
+shared server: `npx pd4ml serve`, `PD4ML_BRIDGE=tcp://127.0.0.1:8723`). The API is synchronous:
+`pd.writePDF()` returns the PDF. Like any CPU-bound call, a conversion blocks the event loop
+while it runs; servers under concurrent load convert in worker threads.
+
+- Java methods keep their Java names; the PD4ML classes are exported under their own names
+  (`PageSize.A4`, `new PageMargins(...)`, `PdfSpec.getInstance('pdf/a-2b')`), any other Java class
+  through `Java.type(name)`.
+- Helpers on Java objects start with `$`: `$get(field)`, `$set(field, value)`, `$class`, `$enum`.
+- `Java.float(10)` passes a number as a Java float; Java's `byte[]` is a `Buffer`.
+- Java exceptions are `JavaError`s (`e.isInstanceOf('java.io.IOException')`).
+
+## Command line
+
+```
+npx pd4ml convert page.html page.pdf [--spec pdf/a-2b] [--engine v40]    # also .docx, .rtf, .png
+npx pd4ml version
+```
+
+## Documentation
+
+- **User guide**: [docs/guide.md](docs/guide.md) — prerequisites, installation, how it works,
+  use cases with code, tips, troubleshooting.
+- **API reference**: [docs/api.md](docs/api.md) — every class and method, generated from PD4ML.
+- The PD4ML manual: <https://pd4ml.com/docs/>.
+- Licensing: without a license, PD4ML runs in evaluation mode and watermarks its output. See
+  <https://pd4ml.com/docs/#3.-licensing>.
+
+## Development
+
+```
+npm test                                   # node --test; PD4ML_NETWORK_TESTS=1 adds the download test
+npm run gen-types                          # index.d.ts and docs/api.md from PD4ML's classes (javap)
+npm run build-bridge                       # lib/pd4ml-bridge.jar from java/src
+node tools/dist.js                         # branch dist (pushed as github.com/zxfr/pd4ml-node main) + pd4ml-<version>.tgz
+```
+
+The tests use `./pd4ml.classpath` (a PD4ML development build) when present, else the installed
+build; they include every JavaScript snippet of the guide.

package/bin/pd4ml.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+'use strict';
+// The pd4ml command: install/list PD4ML builds, show the version, run a bridge server, convert.
+const { spawn } = require('child_process');
+const path = require('path');
+const pd4ml = require('..');
+const installer = require('../lib/installer');
+const { Bridge } = require('../lib/bridge');
+
+const USAGE = `usage: pd4ml <command> [options]
+
+  install [VERSION] [--snapshots] [--jakarta] [--home DIR] [--force] [--no-bouncycastle]
+                      download a PD4ML build (default: the most recent 4.* release), or update to it
+  list [--snapshots] [--jakarta]
+                      the versions in the PD4ML repository (* the installed one)
+  version             the PD4ML version the module runs (downloads it on first use)
+  serve [--port N]    run a bridge server (default port 8723) for PD4ML_BRIDGE=tcp://127.0.0.1:N
+  convert INPUT OUTPUT [--format pdf|docx|rtf|png] [--page-size A4] [--landscape]
+          [--margins 10,10,10,10] [--width PX] [--engine v42|v40] [--spec pdf/a-2b]
+          [--footer HTML] [--bookmarks]
+                      convert a file or URL; the format follows OUTPUT's extension by default
+
+  PD4ML_CLASSPATH / PD4ML_CLASSPATH_FILE / PD4ML_HOME / PD4ML_JAVA choose the build and Java.
+  https://pd4ml.com/docs/`;
+
+const FLAGS = new Set(['snapshots', 'jakarta', 'force', 'no-bouncycastle', 'landscape', 'bookmarks']);
+
+function parse(argv) {
+  const positional = [];
+  const named = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) { positional.push(a); continue; }
+    const eq = a.indexOf('=');
+    const name = eq > 0 ? a.slice(2, eq) : a.slice(2);
+    if (eq > 0) named[name] = a.slice(eq + 1);
+    else if (!FLAGS.has(name) && i + 1 < argv.length && !argv[i + 1].startsWith('--')) named[name] = argv[++i];
+    else named[name] = true;
+  }
+  return { positional, named };
+}
+
+function convert({ positional, named }) {
+  if (positional.length !== 2) throw new Error('convert: INPUT and OUTPUT expected');
+  const [input, output] = positional;
+  const format = String(named.format || path.extname(output).slice(1)).toLowerCase();
+  const pd = new pd4ml.PD4ML({ htmlWidth: named.width ? Number(named.width) : undefined, engine: named.engine });
+  if (named['page-size']) {
+    const size = pd4ml.PageSize.getInstance(String(named['page-size']).toLowerCase());
+    if (!size) throw new Error(`unknown page size '${named['page-size']}'`);
+    pd.setPageSize(named.landscape ? size.rotate() : size);
+  } else if (named.landscape) {
+    pd.setPageSize(pd4ml.PageSize.A4.rotate());
+  }
+  if (named.margins) {
+    let mm = String(named.margins).split(',').map(s => Number(s.trim()));
+    if (mm.length === 1) mm = [mm[0], mm[0], mm[0], mm[0]];
+    if (mm.length !== 4 || mm.some(Number.isNaN)) throw new Error('--margins: one or four values (mm)');
+    pd.setPageMargins(new pd4ml.PageMargins(mm[0], mm[1], mm[2], mm[3], pd4ml.Units.MM));
+  }
+  if (named.footer) pd.setPageFooter(String(named.footer), 30, '1+');
+  if (named.bookmarks) pd.generateBookmarksFromHeadings(true);
+  pd.readHTML(input);
+  switch (format) {
+    case 'pdf': pd.writePDF(output, named.spec || null); break;
+    case 'docx': pd.writeDOCX(output); break;
+    case 'rtf': pd.writeRTF(output); break;
+    case 'png': {
+      const pages = pd.renderPng();
+      if (pages.length === 1) {
+        require('fs').writeFileSync(output, pages[0]);
+      } else {
+        const stem = output.replace(/\.png$/i, '');
+        pages.forEach((p, i) => require('fs').writeFileSync(`${stem}-${i + 1}.png`, p));
+      }
+      break;
+    }
+    default: throw new Error(`unknown format '${format}' (pdf, docx, rtf, png)`);
+  }
+}
+
+function main(argv) {
+  const [command, ...rest] = argv;
+  if (!command || ['-h', '--help', 'help'].includes(command)) {
+    console.log(USAGE);
+    return command ? 0 : 2;
+  }
+  const args = parse(rest);
+  const n = args.named;
+  switch (command) {
+    case 'install':
+      console.log(installer.install(args.positional[0] || 'latest', {
+        snapshots: !!n.snapshots, jakarta: !!n.jakarta, home: n.home, force: !!n.force, bouncycastle: !n['no-bouncycastle'],
+      }));
+      return 0;
+    case 'list': {
+      const installed = installer.installedVersion();
+      for (const v of installer.sortVersions(installer.availableVersions())) {
+        if (!n.snapshots && v.endsWith('-SNAPSHOT')) continue;
+        if (v.includes('-jakarta') !== !!n.jakarta) continue;
+        console.log((v === installed ? '* ' : '  ') + v);
+      }
+      return 0;
+    }
+    case 'version':
+      console.log(pd4ml.version());
+      return 0;
+    case 'serve': {
+      const port = Number(n.port || 8723);
+      const cmd = Bridge.command(undefined, port);
+      console.error(`PD4ML bridge on tcp://127.0.0.1:${port} (Ctrl+C to stop)`);
+      const child = spawn(cmd[0], cmd.slice(1), { stdio: 'inherit' });
+      child.on('exit', code => process.exit(code === null ? 1 : code));
+      return null;
+    }
+    case 'convert':
+      convert(args);
+      return 0;
+    default:
+      console.error(`pd4ml: unknown command '${command}'\n\n${USAGE}`);
+      return 2;
+  }
+}
+
+try {
+  const code = main(process.argv.slice(2));
+  if (code !== null) process.exitCode = code;
+} catch (e) {
+  console.error('pd4ml: ' + e.message);
+  process.exitCode = 1;
+}