@lpdfio/lpdf 0.31.0 → 0.33.0

package/README.md

@@ -47,6 +47,8 @@ An ES module or a TypeScript file imports the same names, and gets the same clas
 import { L, NoAttr } from '@lpdfio/lpdf'
 ```
 
+A render runs on a worker thread, one at a time, and doesn't hold up the event loop. It stops with an `LpdfRenderError` after 5 seconds; `L.engine({ timeout: 60 })` sets another limit in seconds, and `timeout: 0` sets none. It also stops once it needs more than 1024 MB of memory; `L.engine({ maxMemoryMb: 2048 })` sets another cap, from 1 to 4096 MB.
+
 ## Requirements
 
 - Node.js 20+

package/dist/L.d.ts

@@ -1,4 +1,5 @@
 import type { DocumentAssets, DocumentTokens, PdfDocument } from './kit';
+import type { EngineOptions } from './_shared';
 import { PdfEngine } from './engine';
 /** Pass as `attrs` when a node has no attributes. Equivalent to `null`. */
 export declare const NoAttr: null;
@@ -25,8 +26,13 @@ export declare const NoAttr: null;
  * ```
  */
 export declare const L: Readonly<{
-    /** Create a new {@link PdfEngine} instance. Call `.setLicenseKey()` to configure. */
-    engine: () => PdfEngine;
+    /**
+     * Create a new {@link PdfEngine} instance. Call `.setLicenseKey()` to configure.
+     *
+     * @param options - `timeout`: the seconds a render may run, 5 when left out, no limit at 0. `maxMemoryMb`: the
+     *   megabytes a render may allocate, 1024 when left out, from 1 to 4096.
+     */
+    engine: (options?: EngineOptions) => PdfEngine;
     /** Convert a `PdfDocument` tree to an lpdf XML string. */
     toXml: (doc: PdfDocument) => string;
     document: (attrs: import("./kit").DocumentAttr | null, nodes?: import("./kit").LpdfSectionNode[]) => PdfDocument;

package/dist/L.js

@@ -32,8 +32,13 @@ exports.NoAttr = null;
  * ```
  */
 exports.L = Object.freeze({
-    /** Create a new {@link PdfEngine} instance. Call `.setLicenseKey()` to configure. */
-    engine: () => new engine_1.PdfEngine(),
+    /**
+     * Create a new {@link PdfEngine} instance. Call `.setLicenseKey()` to configure.
+     *
+     * @param options - `timeout`: the seconds a render may run, 5 when left out, no limit at 0. `maxMemoryMb`: the
+     *   megabytes a render may allocate, 1024 when left out, from 1 to 4096.
+     */
+    engine: (options) => new engine_1.PdfEngine(options),
     /** Convert a `PdfDocument` tree to an lpdf XML string. */
     toXml: (doc) => (0, kit_to_xml_1.kitToXml)(doc),
     // ── Kit ───────────────────────────────────────────────────────────────────

package/dist/_shared.d.ts

@@ -1,15 +1,35 @@
 /**
  * Shared types used by both the Node.js and browser entry points.
  */
-/** Construction-time configuration for {@link PdfEngine}. Node has no infra options. */
+import type { EncryptionArguments } from './render-job';
+/** Construction-time configuration for `PdfEngine`, `L.engine()` and `initLpdf`. */
 export interface EngineOptions {
+    /**
+     * The seconds a render may run before it rejects with an `LpdfRenderError` that names the limit: 5 when left out,
+     * no limit at 0. A render runs on a worker, which is stopped at the limit and replaced for the next render.
+     */
+    timeout?: number;
+    /**
+     * The megabytes of memory a render may allocate: 1024 when left out, a whole number from 1 to 4096. A render that
+     * needs more rejects with an `LpdfRenderError` that names the cap. What the engine holds before the render, such as
+     * the fonts it loaded, doesn't count.
+     */
+    maxMemoryMb?: number;
 }
+/** The megabytes a render may allocate when `maxMemoryMb` is left out. */
+export declare const DEFAULT_MAX_MEMORY_MB = 1024;
+/**
+ * The megabytes a render may allocate, from the `maxMemoryMb` of the engine's options: 1024 when left out.
+ *
+ * @throws {RangeError} when `maxMemoryMb` is not a whole number from 1 to 4096.
+ */
+export declare function maxMemoryMb(value: number | undefined): number;
 export interface RenderOptions {
     /**
      * Optional ISO 8601 creation timestamp (e.g. `"2024-06-01T12:00:00"`).
      * When provided, written as `/CreationDate` in the PDF info dictionary.
      * Omitting this keeps builds reproducible (no embedded timestamp).
-     * Required for a document whose `output` asks for `pdfa`, which writes it as both dates of the file.
+     * Required for a document whose `output` asks for `pdfa`, `pdfua` or `pdfx`, which writes it as both dates of the file.
      */
     createdOn?: string;
     /**
@@ -41,7 +61,7 @@ export interface RenderOptions {
  * and, when there is a password, 32 bytes from the platform's secure generator for AES-256 to cut its key, salts
  * and IVs from, fresh for each render.
  */
-export declare function encryptionArguments(options: RenderOptions, randomBytes: (count: number) => Uint8Array): [string | null, string | null, boolean, Uint8Array];
+export declare function encryptionArguments(options: RenderOptions, randomBytes: (count: number) => Uint8Array): EncryptionArguments;
 /** The value of an attribute in a document tree: a string, a number or a boolean, as the schema types it. */
 export type AttrValue = string | number | boolean;
 /**

package/dist/_shared.js

@@ -1,12 +1,28 @@
 "use strict";
-/**
- * Shared types used by both the Node.js and browser entry points.
- */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_MAX_MEMORY_MB = void 0;
+exports.maxMemoryMb = maxMemoryMb;
 exports.encryptionArguments = encryptionArguments;
 exports.buildAttrs = buildAttrs;
 exports.assertFinite = assertFinite;
 exports.assertFiniteIn = assertFiniteIn;
+/** The megabytes a render may allocate when `maxMemoryMb` is left out. */
+exports.DEFAULT_MAX_MEMORY_MB = 1024;
+/** The most `maxMemoryMb` may be: 32-bit WebAssembly addresses 4 GB at most. */
+const MAX_MEMORY_MB = 4096;
+/**
+ * The megabytes a render may allocate, from the `maxMemoryMb` of the engine's options: 1024 when left out.
+ *
+ * @throws {RangeError} when `maxMemoryMb` is not a whole number from 1 to 4096.
+ */
+function maxMemoryMb(value) {
+    if (value === undefined)
+        return exports.DEFAULT_MAX_MEMORY_MB;
+    if (!Number.isInteger(value) || value < 1 || value > MAX_MEMORY_MB) {
+        throw new RangeError(`maxMemoryMb must be a whole number of megabytes from 1 to ${MAX_MEMORY_MB}, not ${value}`);
+    }
+    return value;
+}
 /** The random bytes AES-256 needs from the host, one 256-bit key's worth. The engine makes none itself. */
 const ENTROPY_BYTES = 32;
 /**