@reportwright/engine 0.12.1 → 0.13.1

package/dist/types/src/engine/text/standard-metrics.d.ts

@@ -0,0 +1,190 @@
+export namespace ENCODINGS {
+    let WinAnsi: number[];
+    let Symbol: number[];
+    let ZapfDingbats: number[];
+}
+/** PostScript name → the font's metrics (units per em 1000); widths: the advance of each code in its encoding */
+export const METRICS: {
+    Helvetica: {
+        encoding: string;
+        familyName: string;
+        ascent: number;
+        descent: number;
+        capHeight: number;
+        xHeight: number;
+        italicAngle: number;
+        underlinePosition: number;
+        underlineThickness: number;
+        bbox: number[];
+        widths: number[];
+    };
+    'Helvetica-Bold': {
+        encoding: string;
+        familyName: string;
+        ascent: number;
+        descent: number;
+        capHeight: number;
+        xHeight: number;
+        italicAngle: number;
+        underlinePosition: number;
+        underlineThickness: number;
+        bbox: number[];
+        widths: number[];
+    };
+    'Helvetica-Oblique': {
+        encoding: string;
+        familyName: string;
+        ascent: number;
+        descent: number;
+        capHeight: number;
+        xHeight: number;
+        italicAngle: number;
+        underlinePosition: number;
+        underlineThickness: number;
+        bbox: number[];
+        widths: number[];
+    };
+    'Helvetica-BoldOblique': {
+        encoding: string;
+        familyName: string;
+        ascent: number;
+        descent: number;
+        capHeight: number;
+        xHeight: number;
+        italicAngle: number;
+        underlinePosition: number;
+        underlineThickness: number;
+        bbox: number[];
+        widths: number[];
+    };
+    'Times-Roman': {
+        encoding: string;
+        familyName: string;
+        ascent: number;
+        descent: number;
+        capHeight: number;
+        xHeight: number;
+        italicAngle: number;
+        underlinePosition: number;
+        underlineThickness: number;
+        bbox: number[];
+        widths: number[];
+    };
+    'Times-Bold': {
+        encoding: string;
+        familyName: string;
+        ascent: number;
+        descent: number;
+        capHeight: number;
+        xHeight: number;
+        italicAngle: number;
+        underlinePosition: number;
+        underlineThickness: number;
+        bbox: number[];
+        widths: number[];
+    };
+    'Times-Italic': {
+        encoding: string;
+        familyName: string;
+        ascent: number;
+        descent: number;
+        capHeight: number;
+        xHeight: number;
+        italicAngle: number;
+        underlinePosition: number;
+        underlineThickness: number;
+        bbox: number[];
+        widths: number[];
+    };
+    'Times-BoldItalic': {
+        encoding: string;
+        familyName: string;
+        ascent: number;
+        descent: number;
+        capHeight: number;
+        xHeight: number;
+        italicAngle: number;
+        underlinePosition: number;
+        underlineThickness: number;
+        bbox: number[];
+        widths: number[];
+    };
+    Courier: {
+        encoding: string;
+        familyName: string;
+        ascent: number;
+        descent: number;
+        capHeight: number;
+        xHeight: number;
+        italicAngle: number;
+        underlinePosition: number;
+        underlineThickness: number;
+        bbox: number[];
+        widths: number[];
+    };
+    'Courier-Bold': {
+        encoding: string;
+        familyName: string;
+        ascent: number;
+        descent: number;
+        capHeight: number;
+        xHeight: number;
+        italicAngle: number;
+        underlinePosition: number;
+        underlineThickness: number;
+        bbox: number[];
+        widths: number[];
+    };
+    'Courier-Oblique': {
+        encoding: string;
+        familyName: string;
+        ascent: number;
+        descent: number;
+        capHeight: number;
+        xHeight: number;
+        italicAngle: number;
+        underlinePosition: number;
+        underlineThickness: number;
+        bbox: number[];
+        widths: number[];
+    };
+    'Courier-BoldOblique': {
+        encoding: string;
+        familyName: string;
+        ascent: number;
+        descent: number;
+        capHeight: number;
+        xHeight: number;
+        italicAngle: number;
+        underlinePosition: number;
+        underlineThickness: number;
+        bbox: number[];
+        widths: number[];
+    };
+    Symbol: {
+        encoding: string;
+        familyName: string;
+        ascent: number;
+        descent: number;
+        capHeight: number;
+        xHeight: number;
+        italicAngle: number;
+        underlinePosition: number;
+        underlineThickness: number;
+        bbox: number[];
+        widths: number[];
+    };
+    ZapfDingbats: {
+        encoding: string;
+        familyName: string;
+        ascent: number;
+        descent: number;
+        capHeight: number;
+        xHeight: number;
+        italicAngle: number;
+        underlinePosition: number;
+        underlineThickness: number;
+        bbox: number[];
+        widths: number[];
+    };
+};

package/dist/types/src/engine/text/standard.d.ts

@@ -0,0 +1,42 @@
+/**
+ * A standard font as a fontkit-like object (unitsPerEm 1000). The tables (about 22 KB) load on first use.
+ * @param {string} key a PostScript name of STANDARD_FACES
+ */
+export function standardFont(key: string): Promise<{
+    standard: boolean;
+    postscriptName: string;
+    familyName: any;
+    unitsPerEm: number;
+    ascent: any;
+    descent: any;
+    capHeight: any;
+    xHeight: any;
+    italicAngle: any;
+    underlinePosition: any;
+    underlineThickness: any;
+    bbox: {
+        minX: any;
+        minY: any;
+        maxX: any;
+        maxY: any;
+    };
+    /** WinAnsi for the text fonts (Symbol and ZapfDingbats use their own built-in encodings) */
+    winAnsi: boolean;
+    widths: any;
+    /** @param {number} cp */
+    hasGlyphForCodePoint: (cp: number) => boolean;
+    /** @param {number} cp */
+    glyphForCodePoint: (cp: number) => any;
+    getGlyph: (id: number) => any;
+}>;
+/**
+ * The 14 standard PDF fonts (Helvetica, Times, Courier in four faces each, Symbol, ZapfDingbats): every PDF reader has
+ * them, so a PDF names them and embeds nothing. Their metrics are Adobe's AFM files, generated into standard-metrics.js
+ * (scripts/gen-standard-metrics.mjs, from @pdf-lib/standard-fonts); this wraps one in the part of fontkit's font API
+ * the engine and the PDF exporters read, so layout measures with the widths the PDF's /Widths array gives. A glyph ID
+ * here is the character's code in the font's encoding (WinAnsi; Symbol and ZapfDingbats have their own), one byte;
+ * 0 = not in the encoding. */
+/** [family, PostScript name, weight, style] */
+export const STANDARD_FACES: (string | number)[][];
+export const STANDARD_KEYS: Set<string>;
+export function isStandard(key: string): boolean;

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

@@ -21,3 +21,17 @@ export function exportDocx(model: any, opt?: {
     figures?: boolean;
     xmlChunk?: number;
 }): Promise<Uint8Array>;
+/**
+ * The .docx of pages as they come (an array, or an async iterable: exportDocxStream's pages, a window at a time), its
+ * zip bytes handed to put as they are made (awaited: back-pressure). Each page's XML goes into word/document.xml's
+ * deflater once the page is converted, so neither the pages nor the document XML are held whole; the parts that name
+ * the pictures follow the document. model: the model, or a paged plan's info (width, height; locale, name).
+ * @param {Iterable<any>|AsyncIterable<any>} pages @param {{ width: number, height: number, locale?: string, name?: string }} model
+ * @param {NonNullable<Parameters<typeof exportDocx>[1]>} opt @param {(bytes: Uint8Array) => any} put
+ */
+export function writeDocx(pages: Iterable<any> | AsyncIterable<any>, model: {
+    width: number;
+    height: number;
+    locale?: string;
+    name?: string;
+}, opt: NonNullable<Parameters<typeof exportDocx>[1]>, put: (bytes: Uint8Array) => any): Promise<void>;

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

@@ -0,0 +1,27 @@
+/**
+ * Report definition → .docx written to sink as its pages are laid out.
+ * @param {any} def @param {any} opts render()'s options and exportDocx's (fontStore, fetchImage, figures, rasterize, lang,
+ *   title), plus timeoutMs or deadline, signal, window (rows laid out at once), maxRows, sorter, sqlRows as exportPdfStream
+ * @param {Sink} sink not closed
+ * @returns {Promise<StreamResult>}
+ */
+export function exportDocxStream(def: any, opts: any, sink: Sink): Promise<StreamResult>;
+/**
+ * Report definition → .xlsx written to sink as its rows come.
+ * @param {any} def @param {any} opts render()'s options and exportXlsx's (currency, title, formulas, fontStore,
+ *   fetchImage), plus timeoutMs or deadline, signal, maxRows, sorter, sqlRows as exportPdfStream
+ * @param {Sink} sink not closed
+ * @returns {Promise<StreamResult>}
+ */
+export function exportXlsxStream(def: any, opts: any, sink: Sink): Promise<StreamResult>;
+export type Sink = {
+    write(u8: Uint8Array): any;
+    once?: (ev: string, cb: () => void) => any;
+};
+export type StreamResult = {
+    streamed: boolean;
+    pages?: number;
+    rows?: number;
+    warnings: string[];
+    why?: string;
+};

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

@@ -9,8 +9,10 @@
  *   tagged?: { lang?: string }, drillBase?: string, onWarning?: (message: string) => void, timeoutMs?: number,
  *   creationDate?: Date }} [opt]
  *   subset: a HarfBuzz subsetter (see subset.js). Without it, fonts embed in full.
- *   pdfa: make a PDF/A-2b file (needs an sRGB ICC profile). prepare: last change before saving
- *   (the server adds a signature placeholder there). save: extra pdf-lib save options.
+ *   pdfa: a PDF/A-2b file (2a with tagged): true uses the sRGB profile of @reportwright/fonts, or pass { icc } (this
+ *   function itself needs icc; the engine package fills it in). prepare: last change to the pdf-lib PDFDocument before
+ *   saving (the server adds a signature placeholder there). save: pdf-lib save options. These, encrypt and PDF/A without
+ *   a profile take the whole-model path in exportPdfStream; a PDF/A file with a profile streams.
  *   encrypt: { userPassword, ownerPassword, permissions } — AES-256 (see encrypt.js); not with pdfa or prepare.
  *   tagged: an accessible PDF (PDF/UA-1, see pdfua.js): structure tree, marked content, artifacts, language, title
  *   shown; with pdfa it is PDF/A-2a. Off, the file is exactly what it was.
@@ -42,4 +44,4 @@ export function exportPdf(model: any, fontStore: import("../engine/text/fonts.js
     timeoutMs?: number;
     creationDate?: Date;
 }): any;
-import { PDFDocument } from 'pdf-lib';
+import { PDFDocument } from '../engine/lazylibs.js';

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

@@ -0,0 +1,23 @@
+/** The font dictionary's entries (pdf-lib's context.obj takes them as they are: strings become names). @param {any} f a standard font */
+export function standardFontEntries(f: any): {
+    FirstChar: number;
+    LastChar: number;
+    Widths: any;
+    Encoding?: string;
+    Type: string;
+    Subtype: string;
+    BaseFont: any;
+};
+/** The same dictionary as PDF syntax. @param {any} f */
+export function standardFontDict(f: any): string;
+/** A literal string's body: one byte per character, escaped. @param {any} f a standard font @param {string} text */
+export function standardLiteral(f: any, text: string): string;
+/**
+ * A page whose standard-font text is redrawn in the embedded stand-ins (PDF/A, PDF/UA), at the standard font's glyph
+ * positions. The page and the items it changes are copies; families gets the standard families it found.
+ * @param {any} pg @param {(key: string) => any} fontOf the loaded fonts by key @param {Set<string>} families
+ */
+export function embeddedPage(pg: any, fontOf: (key: string) => any, families: Set<string>): any;
+/** The warnings for the standard families a PDF/A or PDF/UA file drew in their stand-ins (a family's name is its regular face's key). @param {Set<string>} families */
+export function embeddedWarnings(families: Set<string>): string[];
+export function standIns(store: import("../engine/text/fonts.js").FontStore): string[];

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

@@ -1,16 +1,16 @@
 /**
- * @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.
+ * p, or signal's reason as soon as it aborts (p goes on, unwatched).
+ * @template T @param {Promise<T>} p @param {AbortSignal} [signal] @returns {Promise<T>}
  */
+export function raced<T>(p: Promise<T>, signal?: AbortSignal): Promise<T>;
 /**
  * @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
+ *   id?: string, signal?: AbortSignal }} 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.
+ *   signal: stops a wait for the sink (back-pressure) when it aborts.
  */
 export function createPdfStream(sink: Sink, opt: {
     fontStore: import("../engine/text/fonts.js").FontStore;
@@ -19,6 +19,7 @@ export function createPdfStream(sink: Sink, opt: {
         glyphs?: Iterable<number>;
     }) => Promise<Uint8Array>;
     id?: string;
+    signal?: AbortSignal;
 }): {
     /** @param {string} key @returns {string} the font's resource name (F1…) */
     fontName: (key: string) => string;
@@ -60,6 +61,8 @@ export function createPdfStream(sink: Sink, opt: {
      * @param {string} dict @param {Uint8Array} [stream]
      */
     object(dict: string, stream?: Uint8Array): Promise<number>;
+    /** Bytes held for the cross-reference: the open blocks, the deflated ones, the late entries (a Map's ~40 each). */
+    readonly xrefBytes: number;
     /** An object number to write later (objectAt). */
     reserve: () => number;
     /** Write a reserved object. @param {number} n @param {string} dict @param {Uint8Array} [stream] */
@@ -127,6 +130,9 @@ export function createPdfStream(sink: Sink, opt: {
  * opts: render()'s options and exportPdf's (fontStore, subset, title, author, creationDate, drillBase…). Tagged
  * (PDF/UA-1) and PDF/A files stream too; encrypted and signed files, save options and PDF/A without a colour profile
  * take the whole-model path (the result's why says which).
+ * timeoutMs (or deadline) bounds the whole export, waits for the sink included; signal (an AbortSignal) stops it at its
+ * next wait (a row batch, the sink, a sort, a page). Stopped or failed: it rejects (the signal's reason, an AbortError;
+ * a timeout: status 504, code 'ETIMEDOUT'), the rows' cursors are closed, a sort's temporary files removed.
  * @param {any} def @param {any} opts @param {Sink} sink
  * @returns {Promise<{ streamed: boolean, pages: number, warnings: string[], why?: string }>}
  */
@@ -158,12 +164,13 @@ export function paintPage(pg: any, H: number, env: 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]
+ * @param {any} w @param {any} fontStore @param {{ drillBase?: string, pageRef?: (i: number) => any, tags?: any, embedAll?: boolean }} [o]
  */
 export function paintEnv(w: any, fontStore: any, o?: {
     drillBase?: string;
     pageRef?: (i: number) => any;
     tags?: any;
+    embedAll?: boolean;
 }): {
     shared: {
         font: (f: any) => any;
@@ -180,6 +187,8 @@ export function paintEnv(w: any, fontStore: any, o?: {
     reserve: () => any;
     drillBase: string;
     tags: any;
+    /** PDF/A, PDF/UA: standard fonts drawn in embedded stand-ins; the families that were @type {Set<string>|null} */
+    embedded: Set<string> | null;
 };
 /**
  * write may return a promise (awaited: back-pressure), or false with a 'drain' event to wait for (a Node Writable).

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

@@ -17,6 +17,8 @@ export function createStreamTagger(w: any, { maxElements }?: {
 }): {
     /** structure elements so far */
     readonly count: number;
+    /** elements of the page being drawn, held until it ends */
+    readonly held: number;
     /** a new page (window: the paged window it came from; row ids are its own) @param {number} window */
     page(window: number): void;
     /**

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

@@ -1,20 +1,32 @@
 /** At the server's start: remove the spill folders of processes that are gone (pw-spill-<pid>-…) and old-style ones. */
 export function sweepAtBoot(root?: any): void;
-export function spillSorter({ run, runBytes, frame, maxMB, totalMB, dir: root, staleMs }?: {
+/**
+ * A sorter factory for planStream (engine/stream.js): sorter(cmp) → { push, drain, close }. The engine closes it
+ * when the rows end, fail or are abandoned (a client that left): its files go then.
+ * Memory, whatever the row count (N44): one run in memory while reading (runMB of records, about, and at most run
+ * records), and while merging at most mergeMB of batches (frame records a run): past that many runs, groups of runs
+ * are first merged into longer ones on disk (one more pass over those records), so the merge never holds a batch from
+ * every run of a large sort.
+ * @param {{ runMB?: number, mergeMB?: number, run?: number, runBytes?: number, frame?: number, maxMB?: number, totalMB?: number, dir?: string, staleMs?: number }} [o]
+ */
+export function spillSorter({ runMB, mergeMB, run, runBytes, frame, maxMB, totalMB, dir: root, staleMs }?: {
+    runMB?: number;
+    mergeMB?: number;
     run?: number;
     runBytes?: number;
     frame?: number;
     maxMB?: number;
     totalMB?: number;
-    dir?: any;
+    dir?: string;
     staleMs?: number;
 }): (cmp: (a: any, b: any) => number) => {
     /** @param {any} r */
     push(r: any): Promise<void>;
     drain(): AsyncGenerator<any, void, unknown>;
     close(): Promise<void>;
-    /** Tests: the runs written so far. */
+    /** Tests: the runs on disk now, and the merges of groups of runs before the last. */
     readonly runs: number;
+    readonly passes: number;
 };
 export function canSpill(): boolean;
 export function spillShared(): any;

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

@@ -1,3 +1,17 @@
+/**
+ * The tables of a single-face sfnt (TrueType or CFF) as a Map of tag to bytes. A collection (ttcf) gives an empty map.
+ * @param {Uint8Array} bytes
+ */
+export function sfntTables(bytes: Uint8Array): Map<any, any>;
+/** A sfnt from its tables: directory, 4-byte padding, table checksums and the head checkSumAdjustment. */
+export function buildSfnt(version: any, tables: any): Uint8Array<ArrayBuffer>;
+/**
+ * The name table with the given strings replaced (nameID to text). Each replaced string is written in its record's own
+ * encoding: UTF-16BE for Windows and Unicode, one byte per character for Macintosh.
+ * @param {Uint8Array} name
+ * @param {Map<number, string>} strings
+ */
+export function setNameStrings(name: Uint8Array, strings: Map<number, string>): Uint8Array<ArrayBuffer>;
 /** @param {() => Promise<ArrayBuffer|Uint8Array>} loadWasm */
 export function createSubsetter(loadWasm: () => Promise<ArrayBuffer | Uint8Array>): (font: Uint8Array, codePoints: Iterable<number>, opt?: {
     glyphs?: Iterable<number>;

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

@@ -0,0 +1,22 @@
+/**
+ * @param {{ name: string, title: string, columns: number[], timeZone: string|null, locale: string|null, currency: string|null, rows: () => AsyncGenerator<any> }} plan
+ * @param {(bytes: Uint8Array) => any} put the zip's bytes as they come (awaited: back-pressure)
+ * @param {{ currency?: string, title?: string, formulas?: boolean, maxRows?: number, timeZone?: string }} [opt]
+ */
+export function writeXlsxStream(plan: {
+    name: string;
+    title: string;
+    columns: number[];
+    timeZone: string | null;
+    locale: string | null;
+    currency: string | null;
+    rows: () => AsyncGenerator<any>;
+}, put: (bytes: Uint8Array) => any, opt?: {
+    currency?: string;
+    title?: string;
+    formulas?: boolean;
+    maxRows?: number;
+    timeZone?: string;
+}): Promise<void>;
+export const EXCEL_ROWS: 1048576;
+export const EXCEL_COLS: 16384;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reportwright/engine",
-  "version": "0.12.1",
+  "version": "0.13.1",
   "publishConfig": {
     "access": "public"
   },
@@ -57,7 +57,8 @@
     "schema.json",
     "README.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "THIRD-PARTY-NOTICES.md"
   ],
   "engines": {
     "node": ">=20.9"
@@ -71,7 +72,7 @@
     "bidi-js": "1.0.3"
   },
   "peerDependencies": {
-    "@reportwright/fonts": "0.12.1"
+    "@reportwright/fonts": "0.13.1"
   },
   "peerDependenciesMeta": {
     "@reportwright/fonts": {

package/report.d.ts

@@ -344,6 +344,7 @@ export interface FormField extends ItemBase {
   type: 'field';
   kind?: 'text' | 'multiline' | 'checkbox' | 'choice';
   fieldName?: Expr<string>;
+  label?: Expr<string>;
   value?: Expr;
   options?: Expr;
   required?: boolean;

package/schema.json

@@ -1259,6 +1259,9 @@
             "fieldName": {
               "x-ts": "Expr<string>"
             },
+            "label": {
+              "x-ts": "Expr<string>"
+            },
             "value": {
               "x-ts": "Expr"
             },