@lpdfio/lpdf 0.32.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,9 +1,29 @@
 /**
  * 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"`).
@@ -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;
 /**

package/dist/attrs.d.ts

@@ -76,6 +76,20 @@ export interface ColumnAttr {
      * line; in a column it takes the full width.
      */
     width?: string;
+    /**
+     * true lays out the texts that the text with data-source repeats one page at a time, straight
+     * from the data, for logs and lists of tens of thousands of lines and more. The pages are the
+     * ones the same column would have without bulk, but where a page would end inside a text of four
+     * lines or more: without bulk the text splits there, and with bulk it moves whole to the next
+     * page. The column holds texts only, and they follow rules: a text holds plain words with no
+     * span, link, bookmark, footnote or reference, sets no widows or orphans and has no data-source
+     * inside it, and a text without max-lines holds one line and ends in an ellipsis. The column sits
+     * directly in the layout, has no data-source of its own and one text with it, has no height, and
+     * neither it nor anything in it has paginate. Its document has no table of contents, no reference
+     * to a bookmark, no pdfua and no pdfa of level a, and its section's columns are not balanced.
+     * Breaking a rule is an error that names it. Default false.
+     */
+    bulk?: boolean;
 }
 /**
  * Children side by side, continuing on the next line when they run out of width. A child with width
@@ -236,6 +250,20 @@ export interface GridAttr {
     width?: string;
     colWidth?: string;
     cols?: number;
+    /**
+     * true lays out the cells that the child with data-source repeats one page at a time, straight
+     * from the data, for sheets of tens of thousands of labels or cards and more. The pages are the
+     * ones the same grid would have without bulk. The cells follow rules, and so do the grid's other
+     * children: a cell is a text, or a column that holds texts, a text holds plain words with no
+     * span, link, bookmark, footnote or reference, and sets no widows or orphans, a text without
+     * max-lines holds one line and ends in an ellipsis, and nothing in a cell has data-source. A row
+     * of cells never splits across pages. The grid sits directly in the layout, has no data-source of
+     * its own and one child with it, has no height, and neither it nor anything in it has paginate.
+     * Its document has no table of contents, no reference to a bookmark, no pdfua and no pdfa of
+     * level a, and its section's columns are not balanced. Breaking a rule is an error that names it.
+     * Default false.
+     */
+    bulk?: boolean;
 }
 /**
  * A list of items, each with a marker: a bullet drawn as a shape, or a number the engine gives. The
@@ -350,6 +378,21 @@ export interface ListAttr {
      * line; in a column it takes the full width.
      */
     width?: string;
+    /**
+     * true lays out the items that the li with data-source repeats one page at a time, straight from
+     * the data, for logs and lists of tens of thousands of items and more. The pages are the ones the
+     * same list would have without bulk, but where a page would end inside an item, between its texts
+     * or inside a text of four lines or more: without bulk the item splits there, and with bulk it
+     * moves whole to the next page. A number list numbers the items as it does without bulk. The list
+     * has one level, and its items follow rules: an li holds texts only, a text holds plain words
+     * with no span, link, bookmark, footnote or reference, and sets no widows or orphans, a text
+     * without max-lines holds one line and ends in an ellipsis, and nothing in an item has
+     * data-source. The list sits directly in the layout, has no data-source of its own and one li
+     * with it, has no height, and neither it nor anything in it has paginate. Its document has no
+     * table of contents, no reference to a bookmark, no pdfua and no pdfa of level a, and its
+     * section's columns are not balanced. Breaking a rule is an error that names it. Default false.
+     */
+    bulk?: boolean;
 }
 /**
  * One item of a list: a box that holds what a layout holds, such as a text, an image, a table or
@@ -617,9 +660,10 @@ export interface CodeSpanAttr {
 export interface ImgAttr {
     name: string;
     /**
-     * What the image shows, which a screen reader reads in a PDF/UA document; alt="" marks it as
-     * decoration, which a reader skips. A PDF/UA document needs it on every image of the layout. A
-     * document without pdfua ignores it.
+     * What the image shows, which a screen reader reads in a tagged document, one with pdfua or a
+     * pdfa of level a; alt="" marks it as decoration, which a reader skips. A PDF/UA document needs
+     * it on every image of the layout; at PDF/A level a without pdfua, an image without it is
+     * decoration. A document that is not tagged ignores it.
      */
     alt?: string;
     height?: string;
@@ -728,9 +772,11 @@ export interface BarcodeAttr {
      */
     width?: string;
     /**
-     * What the barcode is for, which a screen reader reads in a PDF/UA document in place of its data,
-     * which means nothing read aloud: "QR code to pay this invoice". alt="" marks it as decoration. A
-     * PDF/UA document needs it on every barcode of the layout. A document without pdfua ignores it.
+     * What the barcode is for, which a screen reader reads in a tagged document, one with pdfua or a
+     * pdfa of level a, in place of its data, which means nothing read aloud: "QR code to pay this
+     * invoice". alt="" marks it as decoration. A PDF/UA document needs it on every barcode of the
+     * layout; at PDF/A level a without pdfua, a barcode without it is decoration. A document that is
+     * not tagged ignores it.
      */
     alt?: string;
     paginate?: string;
@@ -790,10 +836,11 @@ export interface TextAttr {
      */
     width?: string;
     /**
-     * Makes the text a heading, h1 to h6, which a PDF/UA document tags as one: a screen reader lists
-     * the headings and moves between them. A text without role is a paragraph. A PDF/UA document's
-     * headings start at h1 and go down one level at a time. It changes nothing a page shows: set the
-     * size and the weight as on any text. A document without pdfua ignores it.
+     * Makes the text a heading, h1 to h6, which a tagged document, one with pdfua or a pdfa of level
+     * a, tags as one: a screen reader lists the headings and moves between them. A text without role
+     * is a paragraph. A PDF/UA document's headings start at h1 and go down one level at a time. It
+     * changes nothing a page shows: set the size and the weight as on any text. A document that is
+     * not tagged ignores it.
      */
     role?: string;
     /**
@@ -1134,6 +1181,20 @@ export interface TableAttr {
     height?: string;
     paginate?: string;
     debug?: boolean;
+    /**
+     * true lays out the rows that the tr with data-source repeats one page at a time, straight from
+     * the data, for reports of tens of thousands of rows and more. The pages are the ones the same
+     * table would have without bulk. The rows follow rules, and so do the thead and the other rows:
+     * each td holds one text or none, a text holds plain words with no span, link, bookmark, footnote
+     * or reference, and sets no widows or orphans, a text without max-lines holds one line and ends
+     * in an ellipsis, a td has no rowspan, a row no keep, and nothing in a row has data-source. A row
+     * never splits across pages. The table sits directly in the layout, has no data-source of its own
+     * and one tr with it, sets its cols in fr, pt or %, has no height, and neither it nor anything in
+     * it has paginate. Its document has no table of contents, no reference to a bookmark, no pdfua
+     * and no pdfa of level a, and its section's columns are not balanced. Breaking a rule is an error
+     * that names it. Default false.
+     */
+    bulk?: boolean;
     /**
      * Puts the element, and everything in it, in an optional content group, which the viewer shows or
      * hides. print: printed, and not shown on screen. screen: shown on screen, and not printed. The
@@ -1220,21 +1281,50 @@ export interface BookmarkAttr {
  * Pins content to the top or bottom edge of pages, outside the normal flow, for headers and
  * footers. It reserves that space on every page it appears on. Only allowed directly inside layout.
  * Where it is written among the flow does not matter: pin chooses the edge, and regions on one edge
- * stack in the order written.
+ * stack in the order written. With pin set to inset, it is a block at a spot inside the section's
+ * columns instead, such as a picture or a box across two columns of a newsletter: top and height
+ * place it, col and colspan say which columns it covers, and those columns flow around it, filling
+ * above it and carrying on below it.
  */
 export interface RegionAttr {
     /**
      * Which edge the region sticks to. top and bottom work. left and right pass validation but are
-     * not implemented yet.
+     * not implemented yet. inset places the region inside the columns, where top, height, col and
+     * colspan say.
      */
     pin: string;
     /**
-     * Which pages show the region: each, first, last, odd, even, or a range such as 2-last. Defaults
-     * to each.
+     * Which pages show the region: each, first, last, odd, even, or a range such as 2-last. odd and
+     * even follow the number printed on the page, so in a section that starts on page 4 even shows on
+     * its first page. first, last and ranges count the section's own pages, whatever their numbers.
+     * Defaults to each. An inset on last goes on the last page of the flow filled without it; if it
+     * then pushes text on to a new page, it stays where it is, one page before the end.
      */
     page?: string;
     w?: string;
     debug?: boolean;
+    /**
+     * For pin set to inset: the column the inset starts in, counted from 1 at the left. Defaults to
+     * 1. With colspan, it may not run past the section's columns. An error on any other pin.
+     */
+    col?: number;
+    /**
+     * For pin set to inset: how many columns the inset covers, from col. It is as wide as those
+     * columns and the gaps between them. Defaults to 1. An error on any other pin.
+     */
+    colspan?: number;
+    /**
+     * For pin set to inset, and required with it: how far below the top of the columns the inset
+     * starts, under the headers. An error on any other pin.
+     */
+    top?: string;
+    /**
+     * For pin set to inset, and required with it: how tall the inset is. Content taller than it is
+     * clipped at its foot, and the inset is never cut across pages: one whose top and height reach
+     * below the room the headers and footers leave, on a page it is on, is an error. Footnotes give
+     * way to it. An error on any other pin.
+     */
+    height?: string;
 }
 /**
  * Markdown as the content of a section, where a layout would go. It holds only Markdown: optional
@@ -1534,6 +1624,12 @@ export interface MarkdownTdAttr {
  * of its text. Layers cannot be nested.
  */
 export interface LayerAttr {
+    /**
+     * Which pages of the section show the layer: each, first, last, odd, even, or a range such as
+     * 2-last. odd and even follow the number printed on the page, so in a section that starts on page
+     * 4 even shows on its first page. first, last and ranges count the section's own pages, whatever
+     * their numbers. Defaults to each.
+     */
     page?: string;
     /**
      * How opaque everything in the layer is, from 0 to 1. To fade one element, put it in a layer of
@@ -1560,10 +1656,11 @@ export interface LayerAttr {
      */
     color?: string;
     /**
-     * In a PDF/UA document, what the layer shows, which a screen reader reads as one figure at the
-     * layer's place in the document: a layer before the layout before it, one after the layout after
-     * it. Without alt a layer is decoration, as a header is, and a screen reader skips it with all
-     * its text: a watermark, a running title, a logo's letters. A document without pdfua ignores it.
+     * In a tagged document, one with pdfua or a pdfa of level a, what the layer shows, which a screen
+     * reader reads as one figure at the layer's place in the document: a layer before the layout
+     * before it, one after the layout after it. Without alt a layer is decoration, as a header is,
+     * and a screen reader skips it with all its text: a watermark, a running title, a logo's letters.
+     * A document that is not tagged ignores it.
      */
     alt?: string;
     /**
@@ -1952,12 +2049,14 @@ export interface FileAttr {
     ref?: string;
     /**
      * The type of the file, such as text/xml, application/pdf or text/csv. Defaults to
-     * application/octet-stream, which says only that it is a file.
+     * application/octet-stream, which says only that it is a file, and to text/xml for the invoice of
+     * a Factur-X e-invoice.
      */
     mime?: string;
     /**
      * How the file relates to the document: source, data, alternative, supplement or unspecified, the
-     * default. An e-invoice's XML is data.
+     * default. The invoice of a Factur-X e-invoice defaults to data for the MINIMUM and BASIC WL
+     * profiles, and to alternative for the others, as the Factur-X spec asks.
      */
     relationship?: string;
     /** A line about the file, which a reader shows beside its name. */
@@ -2029,3 +2128,75 @@ export interface GradientToken {
      */
     stops?: GradientStop[];
 }
+/**
+ * One set of lines of a ruling, cut by a step or by a count in each direction: x for the lines that
+ * run down the page, y for the lines that run across it. A direction with neither has no lines, so
+ * step-y alone is ruled paper and step both is squared paper. A step and a count in the same
+ * direction is an error. Each set is drawn after the one before it, so a heavier set paints over a
+ * finer one.
+ */
+export interface RulingLines {
+    /**
+     * The distance between two lines in both directions, a length such as 5mm. step-x and step-y take
+     * its place in their direction. A cell narrower than 2.5pt is an error.
+     */
+    step?: string;
+    /**
+     * The distance between two lines that run down the page, from left to right, a length such as
+     * 10mm.
+     */
+    stepX?: string;
+    /**
+     * The distance between two lines that run across the page, from top to bottom, a length such as
+     * 8mm: ruled paper.
+     */
+    stepY?: string;
+    /**
+     * Cuts the space into this many equal parts in both directions, from 1 to 100, so the lines land
+     * on its edges whatever its size. count-x and count-y take its place in their direction. A part
+     * narrower than 2.5pt is an error.
+     */
+    count?: number;
+    /** Cuts the space into this many equal columns, from 1 to 100. */
+    countX?: number;
+    /** Cuts the space into this many equal rows, from 1 to 100. */
+    countY?: number;
+    /**
+     * The color of the lines: hex, cmyk(), rgb(), hsl() or a color token. Defaults to line-muted.
+     */
+    color?: string;
+    /**
+     * The thickness of the lines, a length or a name from the border row of the tokens. Defaults to
+     * 0.4pt.
+     */
+    thickness?: string;
+}
+/**
+ * Lines on every page of a section, for paper to write or draw on, or a grid to place things by:
+ * ruled paper, squared paper, or a page cut into equal parts. A section names it with
+ * ruling="name", and the lines are drawn under everything else on its pages, over the background.
+ * They are decoration, which a screen reader skips.
+ */
+export interface RulingToken {
+    /**
+     * The space the lines fill and a count divides. page, the default, is the whole page up to its
+     * trim edge. margin is the area inside the margin of the section's layout or markdown. A step
+     * starts at its top left corner, and the lines stop at its edges.
+     */
+    origin?: 'page' | 'margin';
+    /**
+     * Whether the lines on the edges of that space are drawn: the first one, and the last one where a
+     * step lands on the far edge. A count of 12 draws 13 lines with them and 11 without. Defaults to
+     * true.
+     */
+    edges?: boolean;
+    /**
+     * Puts the lines in an optional content group, as ocg does on an element: print, printed and not
+     * shown on screen, or screen, shown on screen and not printed, such as a grid to place things by.
+     */
+    ocg?: 'print' | 'screen';
+    /**
+     * The sets of lines, at least one, drawn in this order: a later set paints over an earlier one.
+     */
+    lines: RulingLines[];
+}