@reportwright/engine 0.11.0 → 0.12.0

package/dist/pdfstreamworker.js

@@ -0,0 +1,38 @@
+// @ts-check
+// A paint worker of a streaming PDF (pdfstream.js, opts.parallel): it lays out the windows of rows it is sent
+// (engine/paged.js jobs, with the pages already counted) and paints their pages with the same painter and names as the
+// writer, then sends back each page's compressed content stream and what it used (fonts, glyphs, opacities). Node only.
+import { render, FontStore, __streamPaint } from './index.js';
+const { createPdfStream, paintPage, paintEnv, latin1 } = __streamPaint;
+
+const proc = /** @type {any} */ (globalThis).process;
+const { parentPort, workerData } = proc.getBuiltinModule('node:worker_threads');
+const zlib = proc.getBuiltinModule('node:zlib');
+const bytes = new Map(workerData.fonts);
+const fontStore = new FontStore(async (k) => {
+  const b = bytes.get(k);
+  if (!b) throw new Error(`The font "${k}" was not sent to the paint worker`);
+  return b;
+});
+
+parentPort.on('message', async (/** @type {any} */ job) => {
+  try {
+    const t0 = Date.now();
+    const m = await render(job.def, { ...job.opts, fontStore, sources: { __rows: { rows: job.rows } }, pageWindow: job.pageWindow });
+    // a writer of its own for the names and glyphs (nothing is written): the pages' links name pages by placeholder
+    const rec = createPdfStream({ write() {} }, { fontStore });
+    const env = paintEnv(rec, fontStore, { drillBase: job.drillBase, pageRef: (i) => `@@P${i}@@` });
+    const pages = [], transfer = [];
+    for (let k = 0; k < Math.min(job.keep, m.pages.length); k++) {
+      const pg = m.pages[k];
+      const { content, annots } = paintPage(pg, pg.height ?? job.height, env);
+      const z = new Uint8Array(zlib.deflateSync(latin1(content), { level: 9 })); // as pdfpaint.js's deflate
+      transfer.push(z.buffer);
+      pages.push({ deflated: z, annots, width: pg.width, height: pg.height, firstRow: pg.firstRow, rowHead: pg.rowHead, headLevel: pg.headLevel });
+    }
+    parentPort.postMessage({ id: job.id, count: m.pages.length, nextFirst: m.pages[job.keep]?.firstRow, pages, used: rec.used(),
+      shaped: [...env.shaped].map(([k, g]) => [k, [...g]]), bookmarks: m.bookmarks, headings: m.headings, warnings: m.warnings, ms: Date.now() - t0 }, transfer);
+  } catch (e) {
+    parentPort.postMessage({ id: job.id, error: { message: String(/** @type {any} */ (e)?.message || e), status: /** @type {any} */ (e)?.status, timeout: /** @type {any} */ (e)?.timeout } });
+  }
+});

package/dist/types/packages/engine/entry.d.ts

@@ -48,11 +48,43 @@ export function exportDocx(model: any, options?: NonNullable<Parameters<typeof e
 export function exportPptx(model: any, options?: NonNullable<Parameters<typeof exportPptxFull>[1]> & {
     fonts?: FontStore;
 }, ...args: any[]): Promise<Uint8Array>;
+/**
+ * @typedef {RenderOptions & Omit<PdfOptions, 'fonts'> & { fonts?: FontStore, tagged?: { lang?: string },
+ *   window?: number, parallel?: number, maxRows?: number, id?: string }} PdfStreamOptions
+ *   render()'s options and exportPdf's, plus: window (rows laid out at once, 1000), parallel (Node: worker threads
+ *   that lay out and paint pages, opt-in; the file is the same), maxRows (rows read, 5,000,000), id (the file ID).
+ */
+/**
+ * Report definition → PDF written to a sink as it is made, for reports too large to hold as a page model: a flowing
+ * table (and its groups) is laid out a window of rows at a time and each page leaves memory once written. Other
+ * reports are rendered whole and written by exportPdf in one piece (the result says why). sink: a Node Writable
+ * (fs.createWriteStream) or anything with write(bytes) that may return a promise (back-pressure); it is not closed.
+ * @param {any} def the report definition
+ * @param {PdfStreamOptions} options
+ * @param {{ write(bytes: Uint8Array): any, once?: (ev: string, cb: () => void) => any }} sink
+ * @returns {Promise<{ streamed: boolean, pages: number, warnings: string[], why?: string }>}
+ */
+export function exportPdfStream(def: any, options: PdfStreamOptions, sink: {
+    write(bytes: Uint8Array): any;
+    once?: (ev: string, cb: () => void) => any;
+}): Promise<{
+    streamed: boolean;
+    pages: number;
+    warnings: string[];
+    why?: string;
+}>;
 export { validate } from "../../src/engine/schema/validate.js";
 export { exportHtml } from "../../src/exporters/html.js";
 export { exportCsv } from "../../src/exporters/csv.js";
 export { needsExportData } from "../../src/exporters/regions.js";
 export { pageToSvg } from "../../src/exporters/svg.js";
+export namespace __streamPaint {
+    export { createPdfStream };
+    export { paintPage };
+    export { paintEnv };
+    export { latin1 };
+}
+export { planPaged } from "../../src/engine/paged.js";
 export type PdfOptions = Omit<NonNullable<Parameters<typeof exportPdfFull>[2]>, "subset" | "pdfa"> & {
     fonts?: FontStore;
     subset?: false | NonNullable<Parameters<typeof exportPdfFull>[2]>["subset"];
@@ -61,6 +93,20 @@ export type PdfOptions = Omit<NonNullable<Parameters<typeof exportPdfFull>[2]>,
         [k: string]: unknown;
     };
 };
+/**
+ * render()'s options and exportPdf's, plus: window (rows laid out at once, 1000), parallel (Node: worker threads
+ * that lay out and paint pages, opt-in; the file is the same), maxRows (rows read, 5,000,000), id (the file ID).
+ */
+export type PdfStreamOptions = RenderOptions & Omit<PdfOptions, "fonts"> & {
+    fonts?: FontStore;
+    tagged?: {
+        lang?: string;
+    };
+    window?: number;
+    parallel?: number;
+    maxRows?: number;
+    id?: string;
+};
 export type RenderOptions = import("../../src/engine/index.js").RenderOptions;
 import { FontStore } from '../../src/engine/index.js';
 import { exportXlsx as exportXlsxFull } from '../../src/exporters/xlsx.js';
@@ -68,6 +114,10 @@ import { exportDocx as exportDocxFull } from '../../src/exporters/docx.js';
 import { exportPptx as exportPptxFull } from '../../src/exporters/pptx.js';
 import { fontFile } from '../../src/engine/text/fonts.js';
 import { createSubsetter } from '../../src/exporters/subset.js';
+import { createPdfStream } from '../../src/exporters/pdfstream.js';
+import { paintPage } from '../../src/exporters/pdfstream.js';
+import { paintEnv } from '../../src/exporters/pdfstream.js';
+import { latin1 } from '../../src/exporters/pdfpaint.js';
 import { exportPdf as exportPdfFull } from '../../src/exporters/pdf.js';
 export { fontFile, createSubsetter };
 export { render, FontStore, ITEMS, parameterOptions, resolveParameters } from "../../src/engine/index.js";

package/dist/types/src/engine/data/stream.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The keys a JSONPath walks to reach the rows, when the splitter can follow it: $, $.a.b, $['a b'], with a [*] at the
+ * end at most. Null for any other path (indexes, spreads in the middle): read the whole body instead.
+ * @param {string} [path] @returns {string[]|null}
+ */
+export function splitPath(path?: string): string[] | null;
+/**
+ * The rows of a JSON body at a path, in batches, without holding the body: the bytes are scanned for the array the
+ * path names, and its elements are parsed (JSON.parse, a batch at a time) as they complete. A body whose shape the path
+ * does not meet that way (an object where the rows should be, a path with indexes) is read whole and taken through
+ * jsonPathRows, exactly as a whole-body read would: maxWholeBytes caps that case. Every cap counts the text actually read
+ * (characters), not a declared length: the body before the rows (maxWholeBytes), one row (maxElementBytes, so one huge
+ * string or a row that never ends cannot grow without bound) and the nesting (maxDepth).
+ * @param {any} body @param {string|undefined} path
+ * @param {{ maxElementBytes?: number, maxWholeBytes?: number, maxDepth?: number, batch?: number }} [o]
+ * @returns {AsyncGenerator<any[]>}
+ */
+export function jsonRows(body: any, path: string | undefined, { maxElementBytes, maxWholeBytes, maxDepth, batch }?: {
+    maxElementBytes?: number;
+    maxWholeBytes?: number;
+    maxDepth?: number;
+    batch?: number;
+}): AsyncGenerator<any[]>;
+/**
+ * CSV records as they arrive: the same reading as parseCsv (a quote opens a quoted field only at the start of a field;
+ * inside, a doubled quote is a quote and separators and line breaks are data; text after the closing quote is kept;
+ * \n, \r\n and \r end a record), across chunk boundaries.
+ * @param {any} body @param {{ sep: string, quote: string, maxFieldBytes?: number }} o @returns {AsyncGenerator<string[][]>}
+ */
+export function csvRecords(body: any, { sep, quote, maxFieldBytes }: {
+    sep: string;
+    quote: string;
+    maxFieldBytes?: number;
+}, batch?: number): AsyncGenerator<string[][]>;
+/**
+ * CSV rows as objects, as parseCsv gives them (startRow, the header row's names, blank lines dropped), in batches.
+ * headerRow: false needs every row's width first: not read this way (null).
+ * @param {any} body @param {{ separator?: string, quote?: string, headerRow?: boolean, startRow?: number }} src
+ * @param {(v: any, d: string, what: string) => string} csvChar @param {number} [maxFieldBytes]
+ */
+export function csvRows(body: any, src: {
+    separator?: string;
+    quote?: string;
+    headerRow?: boolean;
+    startRow?: number;
+}, csvChar: (v: any, d: string, what: string) => string, maxFieldBytes?: number): AsyncGenerator<{
+    [k: string]: string;
+}[], void, unknown>;

package/dist/types/src/engine/index.d.ts

@@ -216,6 +216,21 @@ export type RenderOptions = {
      * internal: the images drawn so far, shared with subreports
      */
     imageBudget?: any;
+    /**
+     * internal (paged.js): these pages are a window of a longer report: numbered from offset + 1 of total ('…' when not known
+     * yet); final: the window holds the report's last page; first: the report's first row; rowOffset: the rows before this
+     * window; cont: per group level, the group the window's first row continues (its first row), or null
+     */
+    pageWindow?: {
+        offset: number;
+        total?: number | null;
+        final: boolean;
+        first?: any;
+        rowOffset?: number;
+        cont?: ({
+            first: any;
+        } | null)[];
+    };
 };
 import { FontStore } from './text/fonts.js';
 import { TextMeasurer } from './text/measure.js';

package/dist/types/src/engine/paged.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @param {any} def0 @param {any} opts render() options, and maxRows/sorter/sqlRows as planStream takes them;
+ *   window: rows per window (tests)
+ * @returns {Promise<{ why: string } | { why?: undefined, pages: () => AsyncGenerator<any>, info: { width: number, height: number, bookmarks: any[], headings: any[], warnings: string[], pages: number } }>}
+ */
+export function planPaged(def0: any, opts?: any): Promise<{
+    why: string;
+} | {
+    why?: undefined;
+    pages: () => AsyncGenerator<any>;
+    info: {
+        width: number;
+        height: number;
+        bookmarks: any[];
+        headings: any[];
+        warnings: string[];
+        pages: number;
+    };
+}>;

package/dist/types/src/engine/stream.d.ts

@@ -0,0 +1,54 @@
+/**
+ * An in-memory sorter (the browser, the CLI): the server passes one that spills runs to disk (server/spill.js).
+ * @param {(a: any, b: any) => number} cmp
+ */
+export function memorySorter(cmp: (a: any, b: any) => number): {
+    push(r: any): void;
+    drain(): AsyncGenerator<any, void, unknown>;
+    close(): Promise<void>;
+};
+/**
+ * @param {any} def0 the report definition
+ * @param {{ format: 'csv'|'xlsx', parameters?: object, timeZone?: string, now?: Date, state?: any, loadReport?: (id: string) => Promise<any>,
+ *   reportId?: string, fetch?: typeof fetch, baseUrl?: string, sql?: (src: any, p: any) => Promise<object[]>,
+ *   sqlRows?: (src: any, p: any) => AsyncIterable<object[]>, sources?: Record<string, any>, sorter?: (cmp: (a: any, b: any) => number) => any,
+ *   deadline?: number, timeoutMs?: number, maxRows?: number, maxJsonRowBytes?: number, maxJsonWholeBytes?: number }} opts
+ * @returns {Promise<{ why: string } | { why?: undefined, name: string, columns: number[], title: string, timeZone: string|null, locale: string|null, currency: string|null, warnings: string[], rows: () => AsyncGenerator<any>, records: () => AsyncGenerator<any>, grouped: () => AsyncGenerator<any>, stats: { rows: number } }>}
+ */
+export function planStream(def0: any, opts: {
+    format: "csv" | "xlsx";
+    parameters?: object;
+    timeZone?: string;
+    now?: Date;
+    state?: any;
+    loadReport?: (id: string) => Promise<any>;
+    reportId?: string;
+    fetch?: typeof fetch;
+    baseUrl?: string;
+    sql?: (src: any, p: any) => Promise<object[]>;
+    sqlRows?: (src: any, p: any) => AsyncIterable<object[]>;
+    sources?: Record<string, any>;
+    sorter?: (cmp: (a: any, b: any) => number) => any;
+    deadline?: number;
+    timeoutMs?: number;
+    maxRows?: number;
+    maxJsonRowBytes?: number;
+    maxJsonWholeBytes?: number;
+}): Promise<{
+    why: string;
+} | {
+    why?: undefined;
+    name: string;
+    columns: number[];
+    title: string;
+    timeZone: string | null;
+    locale: string | null;
+    currency: string | null;
+    warnings: string[];
+    rows: () => AsyncGenerator<any>;
+    records: () => AsyncGenerator<any>;
+    grouped: () => AsyncGenerator<any>;
+    stats: {
+        rows: number;
+    };
+}>;

package/dist/types/src/exporters/pdfa.d.ts

@@ -20,6 +20,17 @@ export function makePdfA(doc: import("pdf-lib").PDFDocument, { icc, title, autho
  * @param {Date} when
  */
 export function setInfoDates(doc: import("pdf-lib").PDFDocument, when: Date): void;
+/**
+ * The XMP metadata packet: title, author, dates, and the PDF/A and PDF/UA identifiers when asked.
+ * @param {{ title: string, author?: string, stamp: string, pdfa?: string|null, ua?: boolean }} o
+ */
+export function xmpPacket({ title, author, stamp, pdfa, ua }: {
+    title: string;
+    author?: string;
+    stamp: string;
+    pdfa?: string | null;
+    ua?: boolean;
+}): string;
 /**
  * PDF/UA-1 without PDF/A: XMP metadata with the title and the PDF/UA identifier (the Info dictionary says the same).
  * @param {import('pdf-lib').PDFDocument} doc

package/dist/types/src/exporters/pdfpaint.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Draw one run of shaped glyphs by ID, where the engine placed them: a TJ array whose numbers move each
+ * glyph from where the font's own advance (the W array) leaves it to the shaper's position; marks that sit
+ * higher or lower use the text rise. /ActualText gives copy and search the characters: for a left-to-right
+ * run the whole run in reading order; a right-to-left run (drawn in visual order, which readers reorder
+ * themselves) reads through ToUnicode, glyph by glyph, and only a cluster ToUnicode cannot spell gets a span
+ * (`spans`, from glyphText); glyphs that stand for nothing (`texts`: '') go last. A span per joined letter, and
+ * the dots of joined letters drawn among the letters, made pdftotext split words ("الج ميل", "الت قن ية").
+ * @param {Content} c @param {Set<number>} [spans] @param {Map<number, string>} [texts]
+ */
+export function drawRun(c: Content, run: any, x: any, y: any, size: any, pf: any, color: any, spans?: Set<number>, texts?: Map<number, string>): void;
+/**
+ * The text each shaped glyph stands for, for the font's ToUnicode map: the character whose own (character-map)
+ * glyph it is; the characters of its cluster that have no glyph of their own there (a conjunct, a joined
+ * Arabic form, a reph) go to ONE glyph, the first that is not a mark, and the cluster's other glyphs (dots,
+ * marks) stand for nothing, so a reader gets each character once. A glyph keeps its first text: a
+ * right-to-left cluster that would read differently with the texts already set goes into `spans` (drawRun
+ * gives it /ActualText). Left-to-right runs always get one span for the whole run.
+ * @param {any} run @param {any} font fontkit font @param {Map<number, string>} out
+ * @param {WeakMap<any, Set<number>>} [spans]
+ */
+export function glyphText(run: any, font: any, out: Map<number, string>, spans?: WeakMap<any, Set<number>>): void;
+/**
+ * Text inside its clip box needs no clip: the lines' advances within it across, the font's ascent and descent
+ * within it down. A cell's text almost always fits, and a clip per cell is most of a table page's operators.
+ */
+export function insideClip(it: any, m: any): any;
+/** one byte per char: the content stream holds the glyph bytes of literal strings as chars 0–255 */
+export function latin1(s: any): any;
+/**
+ * zlib (Flate) compression: Node's zlib on its thread pool (pages compress in parallel, off the main thread), else
+ * the platform's CompressionStream (browsers; in Node it is the same zlib behind web streams, slower), else fflate.
+ */
+export function deflate(bytes: any): Promise<any>;
+export function col(c: any): any;
+export namespace BLACK {
+    let color: import("pdf-lib").RGB;
+    let opacity: number;
+    let rgb: string;
+}
+export function n2(v: any): number;
+export function n3(v: any): number;
+export function n4(v: any): number;
+export function hex4(id: any): any;
+export const KAPPA: number;
+export function cleanText(t: any): any;
+/**
+ * A page's operators as text. The graphics state is tracked, so a colour, line width, dash, opacity or font
+ * that is already set is not set again; q/Q save and restore it as the PDF does.
+ */
+export class Content {
+    constructor(shared: any);
+    shared: any;
+    _s: string;
+    bt: boolean;
+    tx: number;
+    ty: number;
+    st: {
+        fill: string;
+        stroke: string;
+        lw: number;
+        dash: string;
+        ca: number;
+        CA: number;
+        font: string;
+        size: number;
+    };
+    /** @type {any[]} */ saved: any[];
+    /** straight lines waiting to be drawn after the text around them: { key, stroke, w, dash, segs: [x1, y1, x2, y2][] } */
+    lines: any;
+    tagged: boolean;
+    set s(v: string);
+    /**
+     * The operators so far. Any other drawing reads or appends to it, so the lines waiting are drawn first: the text
+     * of a table's cells stays in one text object (relative moves, which compress to little) instead of one per cell.
+     */
+    get s(): string;
+    /**
+     * A straight line. Untagged, it waits until something other than text is drawn (table borders between cell
+     * texts); collinear segments that touch, in the same stroke, become one (a row's border is one line).
+     * ponytail: lines move after the text drawn just after them; both are thin and do not cover each other.
+     */
+    line(stroke: any, w: any, dash: any, x1: any, y1: any, x2: any, y2: any): void;
+    flushLines(): void;
+    q(): void;
+    Q(): void;
+    /**
+     * A line of plain text at (x, y). Lines follow one another in one text object, each placed relative to the
+     * last (in whole hundredths, so nothing drifts): most of a table page is these.
+     * @param {string} str the glyphs, as a literal string's escaped body (array: a TJ array's body)
+     */
+    text(pf: any, size: any, color: any, x: any, y: any, str: string, array?: boolean): void;
+    /** end the open text object, if any: anything but text needs that (and draws the lines waiting) */
+    et(): void;
+    lineWidth(w: any): void;
+    setLineWidth(w: any): void;
+    /** the graphics state that sets these opacities, or undefined when they are set already */
+    gsFor(ca: any, CA: any): any;
+    alpha(ca: any, CA: any): void;
+    setAlpha(ca: any, CA: any): void;
+    /** set up to fill with fill and/or stroke with stroke (width w, dash); the lines waiting are drawn first */
+    paint(fill: any, stroke: any, w?: number, dash?: any): void;
+    setPaint(fill: any, stroke: any, w?: number, dash?: any): void;
+    font(pf: any, size: any): void;
+    setFont(pf: any, size: any): void;
+}
+export const NODE_ZLIB: any;

package/dist/types/src/exporters/pdfstream.d.ts

@@ -0,0 +1,198 @@
+/**
+ * @typedef {{ write(u8: Uint8Array): any, once?: (ev: string, cb: () => void) => any }} Sink
+ *   write may return a promise (awaited: back-pressure), or false with a 'drain' event to wait for (a Node Writable).
+ * @typedef {{ title: string, page: number, top?: number, level?: number }} OutlineEntry
+ *   page: 1-based; top: the destination's y in PDF space (from the bottom), else the page fits the window.
+ */
+/**
+ * @param {Sink} sink
+ * @param {{ fontStore: import('../engine/text/fonts.js').FontStore, fonts?: string[],
+ *   subset?: (font: Uint8Array, codePoints: Iterable<number>, opt?: { glyphs?: Iterable<number> }) => Promise<Uint8Array>,
+ *   id?: string }} opt
+ *   fonts: font keys to name now (F1, F2… in this order); any other font is named on first use.
+ *   subset: subset.js's subsetter; without it fonts embed in full. id: the file ID (32 hex digits), else random.
+ */
+export function createPdfStream(sink: Sink, opt: {
+    fontStore: import("../engine/text/fonts.js").FontStore;
+    fonts?: string[];
+    subset?: (font: Uint8Array, codePoints: Iterable<number>, opt?: {
+        glyphs?: Iterable<number>;
+    }) => Promise<Uint8Array>;
+    id?: string;
+}): {
+    /** @param {string} key @returns {string} the font's resource name (F1…) */
+    fontName: (key: string) => string;
+    /**
+     * The text's glyphs, one per character (as the engine measured it: no layout features), as hex for <…> Tj, with
+     * the glyphs recorded for the subset, W and ToUnicode.
+     * @param {string} key @param {string} text
+     */
+    encode(key: string, text: string): string;
+    /**
+     * The same glyphs as a literal string's body, two bytes each, escaped (as pdf.js draws plain text): ( … ) Tj.
+     * @param {string} key @param {string} text
+     */
+    literal(key: string, text: string): string;
+    /**
+     * Shaped glyphs drawn by ID (conjuncts, joined forms): [glyph ID, the text it stands for ('' for none)].
+     * @param {string} key @param {Iterable<[number, string]>} glyphs
+     */
+    addGlyphs(key: string, glyphs: Iterable<[number, string]>): void;
+    /**
+     * A name in the shared Resources dictionary for a value (an indirect ref "12 0 R" or an inline dictionary).
+     * @param {'ExtGState'|'XObject'|'Pattern'|'Shading'|'ColorSpace'} kind @param {string} value
+     */
+    resource(kind: "ExtGState" | "XObject" | "Pattern" | "Shading" | "ColorSpace", value: string, name?: any): string;
+    /**
+     * The ExtGState name for fill and stroke opacity, named by its values (the same name in every writer: pages
+     * painted elsewhere, parallel.js, use it too). @param {number} ca @param {number} CA
+     */
+    gs: (ca: number, CA: number) => string;
+    /** What this writer's pages used, for another writer to take over (pages painted elsewhere). */
+    used: () => {
+        fonts: (string | number[] | [number, string][])[][];
+        gs: string[];
+    };
+    /** Take over what pages painted elsewhere used (used() of their writer). @param {any} u */
+    take(u: any): void;
+    /**
+     * Write an object now (an image: its dictionary and its stream, already filtered). @returns {Promise<number>} its number
+     * @param {string} dict @param {Uint8Array} [stream]
+     */
+    object(dict: string, stream?: Uint8Array): Promise<number>;
+    /** An object number to write later (objectAt). */
+    reserve: () => number;
+    /** Write a reserved object. @param {number} n @param {string} dict @param {Uint8Array} [stream] */
+    objectAt: (n: number, dict: string, stream?: Uint8Array) => Promise<void>;
+    /**
+     * Write a reserved object whose text may be long (an array of every row's element): head, the parts as they come,
+     * tail; written out in place, never held whole. @param {number} n @param {string} head @param {Iterable<string>} parts @param {string} tail
+     */
+    bigObject(n: number, head: string, parts: Iterable<string>, tail: string): Promise<void>;
+    /** The object number of page i (0-based), written or not: links and outline entries may point ahead. @param {number} i */
+    pageRef(i: number): number;
+    /**
+     * The total page count, drawn at the end: a Form XObject whose origin is the text's baseline at the box's left;
+     * draw it with `q 1 0 0 1 x y cm /<name> Do Q`. align: within width.
+     * @param {{ font: string, size: number, width: number, align?: 'left'|'center'|'right', color?: string }} o
+     */
+    totalPages(o: {
+        font: string;
+        size: number;
+        width: number;
+        align?: "left" | "center" | "right";
+        color?: string;
+    }): string;
+    /**
+     * Write a page: its content stream (deflated) and its dictionary, now. Nothing of it stays but two offsets.
+     * @param {{ width: number, height: number, content?: string | Uint8Array, deflated?: Uint8Array, annots?: (string | { ref: number, dict: string })[], extra?: string }} p
+     *   deflated: the content stream already compressed (zlib), as pages painted elsewhere come.
+     *   content: the page's operators (a string holds bytes 0–255, as pdf.js's Content makes). annots: annotation
+     *   dictionaries (with a reserved number: { ref, dict }). extra: more entries for the page dictionary (/StructParents 3).
+     */
+    addPage(p: {
+        width: number;
+        height: number;
+        content?: string | Uint8Array;
+        deflated?: Uint8Array;
+        annots?: (string | {
+            ref: number;
+            dict: string;
+        })[];
+        extra?: string;
+    }): Promise<void>;
+    /**
+     * The end of the file: totals, fonts, resources, page tree, outline, catalog, Info, xref, trailer.
+     * @param {{ outline?: OutlineEntry[], info?: { title?: string, author?: string, subject?: string, creationDate?: Date }, catalog?: string }} [o]
+     *   catalog: more entries for the catalog (the structure tree, metadata, output intents).
+     * @returns {Promise<{ pages: number, bytes: number }>}
+     */
+    finish(o?: {
+        outline?: OutlineEntry[];
+        info?: {
+            title?: string;
+            author?: string;
+            subject?: string;
+            creationDate?: Date;
+        };
+        catalog?: string;
+    }): Promise<{
+        pages: number;
+        bytes: number;
+    }>;
+};
+/**
+ * A report to PDF bytes written to sink as its pages are laid out (planPaged: a flowing table, one window of rows at a
+ * time), else rendered whole and exported by exportPdf, the same file it always was, written to sink in one piece.
+ * opts: render()'s options and exportPdf's (fontStore, subset, title, author, creationDate, drillBase…). Tagged,
+ * PDF/A, encrypted and signed files take the whole-model path.
+ * @param {any} def @param {any} opts @param {Sink} sink
+ * @returns {Promise<{ streamed: boolean, pages: number, warnings: string[], why?: string }>}
+ */
+export function exportPdfStream(def: any, opts: any, sink: Sink): Promise<{
+    streamed: boolean;
+    pages: number;
+    warnings: string[];
+    why?: string;
+}>;
+/**
+ * The pages of a paged plan (planPaged) as a PDF written to sink, page by page.
+ * @param {any} plan @param {any} opts fontStore, subset, title, author, creationDate, drillBase @param {Sink} sink
+ * @returns {Promise<{ pages: number, warnings: string[] }>}
+ */
+export function writePagedPdf(plan: any, opts: any, sink: Sink): Promise<{
+    pages: number;
+    warnings: string[];
+}>;
+/**
+ * A page of the model as its content stream's operators and its link annotations, drawn with the shared painter
+ * (pdfpaint.js) as exportPdf draws it. env (paintEnv): the writer's names and glyph records, the page refs links jump
+ * to, the tagger when tagged. Pages painted in parallel (parallel.js) use a writer of their own and the same names.
+ * @param {any} pg @param {number} H @param {any} env
+ * @returns {{ content: string, annots: any[] }}
+ */
+export function paintPage(pg: any, H: number, env: any): {
+    content: string;
+    annots: any[];
+};
+/**
+ * What paintPage draws with: a writer's resource names and glyph records (w), the fonts, shaped glyphs' texts.
+ * @param {any} w @param {any} fontStore @param {{ drillBase?: string, pageRef?: (i: number) => any, tags?: any }} [o]
+ */
+export function paintEnv(w: any, fontStore: any, o?: {
+    drillBase?: string;
+    pageRef?: (i: number) => any;
+    tags?: any;
+}): {
+    shared: {
+        font: (f: any) => any;
+        gs: (ca: any, CA: any) => any;
+        image: () => never;
+    };
+    pf: (key: string) => any;
+    font: (key: string) => any;
+    shaped: Map<string, Map<number, string>>;
+    shapedOf: (key: string) => Map<number, string>;
+    vmetrics: (key: string) => any;
+    literal: (key: string, text: string) => any;
+    pageRef: (i: number) => any;
+    reserve: () => any;
+    drillBase: string;
+    tags: any;
+};
+/**
+ * write may return a promise (awaited: back-pressure), or false with a 'drain' event to wait for (a Node Writable).
+ */
+export type Sink = {
+    write(u8: Uint8Array): any;
+    once?: (ev: string, cb: () => void) => any;
+};
+/**
+ * page: 1-based; top: the destination's y in PDF space (from the bottom), else the page fits the window.
+ */
+export type OutlineEntry = {
+    title: string;
+    page: number;
+    top?: number;
+    level?: number;
+};

package/dist/types/src/exporters/pdfstreamtags.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The structure tree of a streamed, tagged PDF (PDF/UA-1, and PDF/A-2a with it): pdfua.js's tree for the shapes that
+ * stream (engine/paged.js), written as the pages are. Document > P / H1–H6 (text boxes), Table > TR > TH/TD (the table's
+ * header rows TH with Scope Column the first time, an artifact where they repeat; empty cells as empty TD; spans as
+ * ColSpan), Link > OBJR inside the element whose text it covers; page header and footer, borders and boxes artifacts.
+ * Each page's rows (TR, TD), its parent-tree array and its links' elements are written when the page ends; what stays
+ * is one number per row (the Table's kids) and two per page and link (the parent tree), written at the end.
+ */
+/**
+ * @param {any} w the PDF writer (pdfstream.js createPdfStream)
+ */
+export function createStreamTagger(w: any): {
+    /** a new page (window: the paged window it came from; row ids are its own) @param {number} window */
+    page(window: number): void;
+    /**
+     * The marked content that opens item it: a structure element's MCID, or an artifact; null for a link.
+     * @param {any} it
+     */
+    open(it: any): string;
+    /**
+     * A link annotation of the page: its Link element (in the element of the text it covers, else the Document).
+     * @returns {number} the annotation's StructParent
+     * @param {any} it @param {number} annot the annotation's object number
+     */
+    link(it: any, annot: number): number;
+    /**
+     * The page is drawn: its elements and parent-tree array are written. @returns {Promise<string>} the page's entries
+     * @param {number} pageRef
+     */
+    end(pageRef: number): Promise<string>;
+    /**
+     * The tree's top: Table, Document, the parent tree, the root. @returns {Promise<string>} the catalog's entries
+     * @param {{ lang?: string }} o
+     */
+    finish({ lang }?: {
+        lang?: string;
+    }): Promise<string>;
+};