@lpdfio/lpdf 0.31.0 → 0.33.0

package/dist/render-error.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LpdfRenderError = exports.ENGINE_CRASHED = void 0;
+/** What a render that crashes the engine rejects with, the same in every SDK of Lpdf. */
+exports.ENGINE_CRASHED = 'The engine crashed during the render. This is a bug in Lpdf, or the render ran out of memory before its cap ' +
+    'stopped it: please report it with the document at https://github.com/lpdfio/lpdf/issues.';
+/**
+ * Thrown when the lpdf engine returns a layout or parse error, a render runs past its timeout or its memory cap, or
+ * the engine crashes.
+ */
+class LpdfRenderError extends Error {
+    constructor(message, cause) {
+        super(message);
+        this.name = 'LpdfRenderError';
+        if (cause !== undefined)
+            this.cause = cause;
+    }
+}
+exports.LpdfRenderError = LpdfRenderError;

package/dist/render-job.d.ts

@@ -0,0 +1,67 @@
+/** The engine's render calls, as wasm-bindgen exposes them in both builds. */
+export interface WasmRenderEngine {
+    render_pdf(xml: string, json_data: string | null, user_password: string | null, owner_password: string | null, skip_encryption: boolean, entropy: Uint8Array): Uint8Array;
+    render_tree_pdf(json: string, user_password: string | null, owner_password: string | null, skip_encryption: boolean, entropy: Uint8Array): Uint8Array;
+    stamp(pdf: Uint8Array, stamps: string): Uint8Array;
+    load_font(name: string, bytes: Uint8Array): void;
+    load_image(name: string, bytes: Uint8Array): void;
+    load_file(name: string, bytes: Uint8Array): void;
+    load_profile(name: string, bytes: Uint8Array): void;
+    load_markdown_styles(src: string, xml: string): void;
+    set_created_on(iso: string): void;
+    set_now(unix: bigint): void;
+    set_max_memory_mb(mb: number): void;
+    free(): void;
+}
+/** The user password, the owner password, `skipEncryption` and the entropy, in the order the render calls take them. */
+export type EncryptionArguments = [string | null, string | null, boolean, Uint8Array];
+/**
+ * One render: the document and every file it needs, already read, since a worker reads nothing itself. A stamp runs as
+ * a render does, with the PDF and the JSON of its stamps as its document and their PNGs as its images.
+ */
+export interface RenderJob {
+    licenseKey: string;
+    /** The host's clock in Unix seconds, for the key's expiry. */
+    now: bigint;
+    /** The megabytes the render may allocate. */
+    maxMemoryMb: number;
+    createdOn: string | undefined;
+    fonts: Map<string, Uint8Array>;
+    images: Map<string, Uint8Array>;
+    files: Map<string, Uint8Array>;
+    profiles: Map<string, Uint8Array>;
+    markdownStyles: Map<string, string>;
+    /** An XML document with its data as JSON, a document tree as JSON, or a PDF to stamp. */
+    document: {
+        xml: string;
+        data: string | null;
+    } | {
+        tree: string;
+    } | {
+        pdf: Uint8Array;
+        stamps: string;
+    };
+    encryption: EncryptionArguments;
+}
+/**
+ * What the worker sends back: the PDF, or the engine's error. `broken` says that the engine trapped, after which its
+ * memory can't be trusted, so the worker is replaced before the next render. A crash of the engine has the error every
+ * SDK gives for one, and the engine's own as its `cause`.
+ */
+export type RenderReply = {
+    pdf: Uint8Array;
+} | {
+    error: string;
+    broken: boolean;
+    cause?: string;
+};
+/**
+ * Runs a render on an engine of its own, which is freed after it, and returns the PDF or the error. It never throws: a
+ * failure is the reply.
+ */
+export declare function runRenderJob(createEngine: (licenseKey: string) => WasmRenderEngine, job: RenderJob): RenderReply;
+/**
+ * The buffers a reply moves to the other thread instead of copying: the PDF's, when the PDF has a buffer of its own.
+ * A view into a larger buffer, such as the engine's memory, is copied.
+ */
+export declare function transferList(reply: RenderReply): ArrayBuffer[];

package/dist/render-job.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runRenderJob = runRenderJob;
+exports.transferList = transferList;
+/**
+ * A render as a worker runs it: everything the engine needs, sent in one message, and the reply that comes back.
+ * Shared by the Node worker and the browser's.
+ */
+const render_error_1 = require("./render-error");
+/**
+ * Runs a render on an engine of its own, which is freed after it, and returns the PDF or the error. It never throws: a
+ * failure is the reply.
+ */
+function runRenderJob(createEngine, job) {
+    let engine;
+    let reply;
+    try {
+        engine = createEngine(job.licenseKey);
+        // Without a clock the engine cannot check the key's expiry, and an expired key renders as though it were
+        // current.
+        engine.set_now(job.now);
+        engine.set_max_memory_mb(job.maxMemoryMb);
+        if (job.createdOn)
+            engine.set_created_on(job.createdOn);
+        for (const [name, bytes] of job.fonts)
+            engine.load_font(name, bytes);
+        for (const [name, bytes] of job.images)
+            engine.load_image(name, bytes);
+        for (const [name, bytes] of job.files)
+            engine.load_file(name, bytes);
+        for (const [name, bytes] of job.profiles)
+            engine.load_profile(name, bytes);
+        for (const [src, text] of job.markdownStyles)
+            engine.load_markdown_styles(src, text);
+        const { document } = job;
+        const pdf = 'xml' in document
+            ? engine.render_pdf(document.xml, document.data, ...job.encryption)
+            : 'tree' in document
+                ? engine.render_tree_pdf(document.tree, ...job.encryption)
+                : engine.stamp(document.pdf, document.stamps);
+        reply = { pdf };
+    }
+    catch (e) {
+        // A trap, or the stack running out inside the engine, which some browsers report as a RangeError, leaves the
+        // engine part way through a call: its memory can't be trusted. Either is a crash of the engine.
+        const crashed = e instanceof WebAssembly.RuntimeError || e instanceof RangeError;
+        reply = crashed
+            ? { error: render_error_1.ENGINE_CRASHED, broken: true, cause: `${e.name}: ${e.message}` }
+            : { error: e instanceof Error ? e.message : String(e), broken: false };
+    }
+    // An engine left part way through a call is still borrowed, and wasm-bindgen's free() throws "attempted to take
+    // ownership of Rust value while it was borrowed". Such an engine goes with its worker; the reply keeps the
+    // engine's own error.
+    if ('pdf' in reply || !reply.broken) {
+        try {
+            engine?.free();
+        }
+        catch {
+            if ('error' in reply)
+                reply = { ...reply, broken: true };
+        }
+    }
+    return reply;
+}
+/**
+ * The buffers a reply moves to the other thread instead of copying: the PDF's, when the PDF has a buffer of its own.
+ * A view into a larger buffer, such as the engine's memory, is copied.
+ */
+function transferList(reply) {
+    if (!('pdf' in reply))
+        return [];
+    const { buffer, byteLength } = reply.pdf;
+    return buffer instanceof ArrayBuffer && buffer.byteLength === byteLength ? [buffer] : [];
+}

package/dist/render-queue.d.ts

@@ -0,0 +1,52 @@
+import type { RenderJob, RenderReply } from './render-job';
+/** The seconds a render may run when `timeout` is left out. A timeout of 0 means no limit. */
+export declare const DEFAULT_TIMEOUT = 5;
+/** A worker as the queue drives it, in Node or in the browser. */
+export interface RenderWorker {
+    /** Sends it a render. */
+    post(job: RenderJob): void;
+    /** Stops it, whatever it is doing. */
+    terminate(): void;
+    /** In Node: whether the worker keeps the process running, which it does only while it renders. */
+    hold?(busy: boolean): void;
+}
+/** What a worker tells the queue. */
+export interface RenderWorkerEvents {
+    /** The render it was sent ended, with a PDF or an error. */
+    replied(reply: RenderReply): void;
+    /** The worker failed outside a render, or stopped. */
+    failed(message: string): void;
+}
+/** Starts a worker that reports to `events`. */
+export type StartRenderWorker = (events: RenderWorkerEvents) => RenderWorker;
+/**
+ * The seconds a render may run, from the `timeout` of the engine's options: 5 when left out, no limit at 0.
+ *
+ * @throws {RangeError} when `timeout` is negative or not a finite number.
+ */
+export declare function renderTimeout(timeout: number | undefined): number;
+/**
+ * Renders one at a time on one worker, kept warm between renders with the engine loaded. A render that runs past its
+ * timeout ends the worker, since a running WebAssembly call can't be stopped any other way, and the next render
+ * starts a new one.
+ */
+export declare class RenderQueue {
+    private readonly _start;
+    private _worker;
+    private _running;
+    private readonly _waiting;
+    constructor(_start: StartRenderWorker);
+    /**
+     * Renders `job` once the renders before it have ended. Its timeout counts from when it starts.
+     *
+     * @param timeout - The seconds it may run, 0 for no limit.
+     * @returns The PDF; rejects with an `LpdfRenderError` when the engine refuses the document or the render runs
+     *   past its timeout.
+     */
+    render(job: RenderJob, timeout: number): Promise<Uint8Array>;
+    private _next;
+    private _startWorker;
+    private _dropWorker;
+    private _settle;
+    private _timedOut;
+}

package/dist/render-queue.js

@@ -0,0 +1,116 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RenderQueue = exports.DEFAULT_TIMEOUT = void 0;
+exports.renderTimeout = renderTimeout;
+const render_error_1 = require("./render-error");
+/** The seconds a render may run when `timeout` is left out. A timeout of 0 means no limit. */
+exports.DEFAULT_TIMEOUT = 5;
+// The longest delay setTimeout takes: a longer one fires at once. A limit of 24 days is no limit for a render.
+const MAX_DELAY_MS = 2 ** 31 - 1;
+/**
+ * The seconds a render may run, from the `timeout` of the engine's options: 5 when left out, no limit at 0.
+ *
+ * @throws {RangeError} when `timeout` is negative or not a finite number.
+ */
+function renderTimeout(timeout) {
+    if (timeout === undefined)
+        return exports.DEFAULT_TIMEOUT;
+    if (!Number.isFinite(timeout) || timeout < 0) {
+        throw new RangeError(`timeout must be a number of seconds, 0 for no limit, not ${timeout}`);
+    }
+    return timeout;
+}
+function seconds(count) {
+    return count === 1 ? '1 second' : `${count} seconds`;
+}
+/**
+ * Renders one at a time on one worker, kept warm between renders with the engine loaded. A render that runs past its
+ * timeout ends the worker, since a running WebAssembly call can't be stopped any other way, and the next render
+ * starts a new one.
+ */
+class RenderQueue {
+    constructor(_start) {
+        this._start = _start;
+        this._waiting = [];
+    }
+    /**
+     * Renders `job` once the renders before it have ended. Its timeout counts from when it starts.
+     *
+     * @param timeout - The seconds it may run, 0 for no limit.
+     * @returns The PDF; rejects with an `LpdfRenderError` when the engine refuses the document or the render runs
+     *   past its timeout.
+     */
+    render(job, timeout) {
+        return new Promise((resolve, reject) => {
+            this._waiting.push({ job, timeout, resolve, reject });
+            this._next();
+        });
+    }
+    _next() {
+        if (this._running)
+            return;
+        const pending = this._waiting.shift();
+        if (!pending) {
+            this._worker?.hold?.(false);
+            return;
+        }
+        this._running = pending;
+        try {
+            const worker = this._worker ?? (this._worker = this._startWorker());
+            worker.hold?.(true);
+            if (pending.timeout > 0) {
+                pending.timer = setTimeout(() => this._timedOut(pending), Math.min(pending.timeout * 1000, MAX_DELAY_MS));
+            }
+            worker.post(pending.job);
+        }
+        catch (e) {
+            // A worker that can't be started or sent the render fails this render, and the next one tries a new worker.
+            this._dropWorker();
+            this._settle({ error: `The render worker failed: ${e instanceof Error ? e.message : String(e)}`, broken: true });
+        }
+    }
+    _startWorker() {
+        // A worker that was ended still delivers what it sent before, and its exit: only the current one counts.
+        const worker = this._start({
+            replied: reply => {
+                if (worker !== this._worker)
+                    return;
+                if ('error' in reply && reply.broken)
+                    this._dropWorker();
+                this._settle(reply);
+            },
+            failed: message => {
+                if (worker !== this._worker)
+                    return;
+                this._dropWorker();
+                this._settle({ error: message, broken: true });
+            },
+        });
+        return worker;
+    }
+    _dropWorker() {
+        this._worker?.terminate();
+        this._worker = undefined;
+    }
+    _settle(reply) {
+        const pending = this._running;
+        if (!pending)
+            return;
+        this._running = undefined;
+        clearTimeout(pending.timer);
+        if ('pdf' in reply) {
+            pending.resolve(reply.pdf);
+        }
+        else {
+            pending.reject(new render_error_1.LpdfRenderError(reply.error, reply.cause));
+        }
+        this._next();
+    }
+    _timedOut(pending) {
+        if (pending !== this._running)
+            return;
+        this._dropWorker();
+        this._settle({ error: `The render timed out after ${seconds(pending.timeout)}.`, broken: true });
+    }
+}
+exports.RenderQueue = RenderQueue;

package/dist/render-worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/render-worker.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * The Node worker a `PdfEngine` renders on: it loads the engine once and runs each render it is sent.
+ */
+const node_worker_threads_1 = require("node:worker_threads");
+const render_job_1 = require("./render-job");
+// require() path is relative to the compiled output at dist/render-worker.js, as engine.ts's is.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const wasm = require('./wasm/lpdf.js');
+// The file runs only as a worker, where parentPort is the port to the thread that started it.
+const port = node_worker_threads_1.parentPort;
+port.on('message', (job) => {
+    const reply = (0, render_job_1.runRenderJob)(licenseKey => new wasm.LpdfEngine(licenseKey), job);
+    port.postMessage(reply, (0, render_job_1.transferList)(reply));
+});

package/dist/stamp.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Stamps: PNG images drawn over the pages of an existing PDF, by `stamp` on the engine. Shared by the Node.js and
+ * browser entry points.
+ */
+/**
+ * One stamp: a PNG, the pages it goes on, and the box it is drawn in on each. The box is placed as a layer element
+ * is, and the image is fitted in it without distortion.
+ */
+export interface StampAttr {
+    /** The PNG's bytes. An image given to several stamps is embedded in the PDF once. */
+    image: Uint8Array;
+    /** The pages: a page scope, such as `3`, `1-2`, `last`, `each`, `odd` or `1,3,5-last`. A page the PDF doesn't have is an error. */
+    page: string;
+    /**
+     * Where the box goes, in `pt`, `mm` or `in`: its top-left corner, from the page's top-left corner as a viewer shows
+     * it, or with `anchor`, signed offsets from that point of the page. Required without `anchor`.
+     */
+    x?: string;
+    y?: string;
+    /**
+     * The point of the page the box is placed from, and the point of the box that goes there: `top-left`,
+     * `top-center`, `top-right`, `center-left`, `center`, `center-right`, `bottom-left`, `bottom-center` or
+     * `bottom-right`.
+     */
+    anchor?: string;
+    /** The size of the box, in `pt`, `mm` or `in`. */
+    width: string;
+    height: string;
+    /** Where the image sits across the box, in the room it leaves: `start`, `center` (the default) or `end`. */
+    align?: string;
+    /** Where the image sits down the box, in the room it leaves: `start`, `center` (the default) or `end`. */
+    justify?: string;
+    /**
+     * How the image is sized in the box, keeping its proportions: `fit` (the default) shrinks an image larger than the
+     * box and keeps a smaller one at its natural size, from the resolution the PNG records, or a pixel to a point;
+     * `fill` takes the largest size that fits.
+     */
+    scale?: string;
+    /** How many times its natural size `fit` may grow an image, never past the box: 1, the default, or more. */
+    maxGrow?: number;
+}
+/**
+ * The stamps as the engine takes them: the JSON of the stamps, each naming its image, and the images by name. The same
+ * bytes, given to several stamps, go under one name.
+ *
+ * @throws {TypeError} when a stamp's `image` is not the PNG's bytes.
+ */
+export declare function stampRequest(stamps: StampAttr[]): {
+    stamps: string;
+    images: Map<string, Uint8Array>;
+};

package/dist/stamp.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Stamps: PNG images drawn over the pages of an existing PDF, by `stamp` on the engine. Shared by the Node.js and
+ * browser entry points.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stampRequest = stampRequest;
+/**
+ * The stamps as the engine takes them: the JSON of the stamps, each naming its image, and the images by name. The same
+ * bytes, given to several stamps, go under one name.
+ *
+ * @throws {TypeError} when a stamp's `image` is not the PNG's bytes.
+ */
+function stampRequest(stamps) {
+    const images = new Map();
+    const names = new Map();
+    const list = stamps.map(({ image, maxGrow, ...rest }, i) => {
+        if (!(image instanceof Uint8Array)) {
+            throw new TypeError(`stamp ${i + 1}: image must be the PNG's bytes, a Uint8Array`);
+        }
+        let name = names.get(image);
+        if (name === undefined) {
+            name = `stamp-${names.size}`;
+            names.set(image, name);
+            images.set(name, image);
+        }
+        return { ...rest, image: name, ...(maxGrow === undefined ? {} : { 'max-grow': maxGrow }) };
+    });
+    return { stamps: JSON.stringify(list), images };
+}

package/dist/wasm/lpdf-web.js

@@ -67,6 +67,19 @@ export class LpdfEngine {
         const len1 = WASM_VECTOR_LEN;
         wasm.lpdfengine_load_markdown_styles(this.__wbg_ptr, ptr0, len0, ptr1, len1);
     }
+    /**
+     * Register the bytes of an ICC colour profile, for the `<profile>` of a document's `<assets>` whose `ref`, or with
+     * no ref whose name, is `name`: the press profile a PDF/X document names in `<output profile>`.
+     * @param {string} name
+     * @param {Uint8Array} bytes
+     */
+    load_profile(name, bytes) {
+        const ptr0 = passStringToWasm0(name, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passArray8ToWasm0(bytes, wasm.__wbindgen_malloc);
+        const len1 = WASM_VECTOR_LEN;
+        wasm.lpdfengine_load_profile(this.__wbg_ptr, ptr0, len0, ptr1, len1);
+    }
     /**
      * @param {string} license_key
      */
@@ -222,6 +235,20 @@ export class LpdfEngine {
         const len0 = WASM_VECTOR_LEN;
         wasm.lpdfengine_set_font_metrics(this.__wbg_ptr, ptr0, len0);
     }
+    /**
+     * Set the memory a render may allocate, in megabytes: 1024 when it isn't set. A render that needs more stops
+     * with an error that names the cap. What the engine holds before the render, such as its loaded fonts, doesn't
+     * count.
+     *
+     * Returns an error when `mb` is 0 or above 4096, the most 32-bit WebAssembly addresses.
+     * @param {number} mb
+     */
+    set_max_memory_mb(mb) {
+        const ret = wasm.lpdfengine_set_max_memory_mb(this.__wbg_ptr, mb);
+        if (ret[1]) {
+            throw takeFromExternrefTable0(ret[0]);
+        }
+    }
     /**
      * Set the current Unix timestamp (seconds) for license expiry checking.
      * Must be called before `render_pdf` when using a time-limited token.
@@ -231,6 +258,32 @@ export class LpdfEngine {
     set_now(unix) {
         wasm.lpdfengine_set_now(this.__wbg_ptr, unix);
     }
+    /**
+     * Draw PNG stamps over the pages of an existing PDF, and return the file with them added as an incremental
+     * update: the input, byte for byte, then the images and the pages they change. The original bytes stay as they
+     * were, so an owner password and its permissions stay, and so does a digital signature's revision.
+     *
+     * `stamps` is a JSON list of stamps, each with an `image`, the name of a PNG loaded with `load_image`, a `page`
+     * scope, a box (`x`, `y`, `anchor`, `width`, `height`, placed as a layer element is) and how the image sits in it
+     * (`align`, `justify`, `scale`, `max-grow`). Without a valid license key, each stamped page gets the attribution
+     * line of a render in its top-right corner.
+     * @param {Uint8Array} pdf
+     * @param {string} stamps
+     * @returns {Uint8Array}
+     */
+    stamp(pdf, stamps) {
+        const ptr0 = passArray8ToWasm0(pdf, wasm.__wbindgen_malloc);
+        const len0 = WASM_VECTOR_LEN;
+        const ptr1 = passStringToWasm0(stamps, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len1 = WASM_VECTOR_LEN;
+        const ret = wasm.lpdfengine_stamp(this.__wbg_ptr, ptr0, len0, ptr1, len1);
+        if (ret[3]) {
+            throw takeFromExternrefTable0(ret[2]);
+        }
+        var v3 = getArrayU8FromWasm0(ret[0], ret[1]).slice();
+        wasm.__wbindgen_free(ret[0], ret[1] * 1, 1);
+        return v3;
+    }
 }
 if (Symbol.dispose) LpdfEngine.prototype[Symbol.dispose] = LpdfEngine.prototype.free;
 
@@ -279,7 +332,7 @@ export function check_license(token, now_unix) {
  * in multiple target languages.
  *
  * `options_json` accepts the same shape as `codegen_wasm`:
- * - `target`: `"js"`, `"dotnet"`, `"php"`, or `"python"` (required)
+ * - `target`: `"js"`, `"dotnet"`, `"php"`, `"python"` or `"java"` (required)
  * - `indent`: `2` or `4` (optional, default `4`)
  * @param {string} xml
  * @param {string} options_json
@@ -312,7 +365,7 @@ export function codegen_fragment_wasm(xml, options_json) {
  * Generate SDK source code from an Lpdf XML string.
  *
  * `options_json` is a JSON object with:
- * - `target`: `"js"` (required)
+ * - `target`: `"js"`, `"dotnet"`, `"php"`, `"python"` or `"java"` (required)
  * - `indent`: `2` or `4` (optional, default `4`)
  *
  * Returns the generated source code as a string.
@@ -505,6 +558,9 @@ function __wbg_get_imports() {
         __wbg___wbindgen_throw_6b64449b9b9ed33c: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
+        __wbg_getRandomValues_cc7f052a444bb2ce: function() { return handleError(function (arg0, arg1) {
+            globalThis.crypto.getRandomValues(getArrayU8FromWasm0(arg0, arg1));
+        }, arguments); },
         __wbindgen_cast_0000000000000001: function(arg0, arg1) {
             // Cast intrinsic for `Ref(String) -> Externref`.
             const ret = getStringFromWasm0(arg0, arg1);
@@ -530,6 +586,12 @@ const LpdfEngineFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_lpdfengine_free(ptr >>> 0, 1));
 
+function addToExternrefTable0(obj) {
+    const idx = wasm.__externref_table_alloc();
+    wasm.__wbindgen_externrefs.set(idx, obj);
+    return idx;
+}
+
 function getArrayU8FromWasm0(ptr, len) {
     ptr = ptr >>> 0;
     return getUint8ArrayMemory0().subarray(ptr / 1, ptr / 1 + len);
@@ -548,6 +610,15 @@ function getUint8ArrayMemory0() {
     return cachedUint8ArrayMemory0;
 }
 
+function handleError(f, args) {
+    try {
+        return f.apply(this, args);
+    } catch (e) {
+        const idx = addToExternrefTable0(e);
+        wasm.__wbindgen_exn_store(idx);
+    }
+}
+
 function isLikeNone(x) {
     return x === undefined || x === null;
 }