@reportwright/engine 0.13.0 → 0.13.2-rc.1

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

@@ -15,8 +15,8 @@ export function render(def0: any, opts?: import("../../src/engine/index.js").Ren
  *   pdfa?: boolean | { icc?: Uint8Array, [k: string]: unknown } }} PdfOptions
  */
 /**
- * Page model → PDF bytes: exportPdf(model, { fonts, title, ... }). fonts: the FontStore render() used (default: the
- * one over @reportwright/fonts). Fonts are subset with harfbuzz-subset.wasm from @reportwright/fonts (when it can't be
+ * Page model → PDF bytes: exportPdf(model, { fonts, title, ... }). fonts: optional, any FontStore (render()'s saves
+ * loading the fonts again; default: the one over @reportwright/fonts); the fonts the model uses are loaded into it. Fonts are subset with harfbuzz-subset.wasm from @reportwright/fonts (when it can't be
  * loaded the full font is embedded); `subset: false` embeds every font in full, a function replaces the subsetter.
  * The 0.7 form exportPdf(model, fontStore, options) still works in 0.8 (deprecated).
  * @param {any} model  render() output
@@ -49,33 +49,7 @@ 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, maxElements?: number },
- *   window?: number, parallel?: number, maxRows?: number, id?: string, presorted?: boolean, signal?: AbortSignal,
- *   spill?: false | { dir?: string, maxMB?: number }, sorter?: (cmp: (a: any, b: any) => number) => any }} 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, each thread costs memory), maxRows (rows read,
- *   5,000,000), id (the file ID). presorted: the rows come in the report's order (its sort, its groups together), so
- *   they are not sorted, only checked as they pass (a row out of order stops the export). spill: where a sort's runs go
- *   (Node: the system temp folder, 2 GB at most; false sorts in memory); in a browser a sort is in memory.
- *   timeoutMs: the whole export's time limit, waits for the sink included (504, code 'ETIMEDOUT'). signal: an
- *   AbortSignal that stops the export at its next wait (rejects with the signal's reason, an AbortError); sqlRows gets
- *   it as its third argument ({ signal }) so a database cursor can cancel its query.
- */
-/**
- * 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<{
+export function exportPdfStream(def: any, options: any, sink: any): Promise<{
     streamed: boolean;
     pages: number;
     warnings: string[];
@@ -161,6 +135,7 @@ export type PdfOptions = Omit<NonNullable<Parameters<typeof exportPdfFull>[2]>,
         [k: string]: unknown;
     };
 };
+export type RenderOptions = import("../../src/engine/index.js").RenderOptions;
 /**
  * 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, each thread costs memory), maxRows (rows read,
@@ -189,7 +164,6 @@ export type PdfStreamOptions = RenderOptions & Omit<PdfOptions, "fonts"> & {
     };
     sorter?: (cmp: (a: any, b: any) => number) => any;
 };
-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';
 import { exportDocx as exportDocxFull } from '../../src/exporters/docx.js';

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

@@ -1,7 +1,7 @@
 /**
  * Render a report definition to a page model (pages, regions), the input of every exporter. Throws ReportError for a
  * definition that cannot render at all; everything else is a warning in the model.
- * @param {any} def0 the report definition (pagewright/report@1), or a saved report's JSON
+ * @param {any} def0 the report definition (reportwright/report@1), or a saved report's JSON
  * @param {RenderOptions} [opts]
  * @returns {Promise<any>} the page model
  */

package/dist/types/src/engine/schema/validate.d.ts

@@ -11,11 +11,13 @@ export function validate(def: any): {
     warnings: any[];
     exprErrors: any[];
     checkOnly: any[];
+    renderSays?: undefined;
 } | {
     errors: any[];
     warnings: string[];
     exprErrors: any[];
     checkOnly: any[];
+    renderSays: string[];
 };
-export const SCHEMA_ID: "pagewright/report@1";
-export const SCHEMA_ALIAS: "reportwright/report@1";
+export const SCHEMA_ID: "reportwright/report@1";
+export const SCHEMA_ALIAS: "pagewright/report@1";

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

@@ -43,6 +43,11 @@ export function fontCss(key: any): {
     weight: number;
     style: string;
 };
+/**
+ * The font keys a page model draws with (text runs, form fields, figures), for an exporter whose store render() did
+ * not fill (N40): load them first. @param {any} model @returns {string[]}
+ */
+export function modelFontKeys(model: any): string[];
 /** The bundled fallback faces for `key` (one per script), for CSS font-family lists. */
 export function fallbackKeys(key: any): string[];
 /**

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

@@ -106,12 +106,13 @@ export class TextMeasurer {
      * character), exactly as before. Others also break between CJK characters (kinsoku applied), never
      * inside a grapheme cluster (a conjunct, a letter and its marks), and remember their direction.
      * @param {string} text @param {string} key @param {number} size @param {number} maxWidth
-     * @returns {{text: string, width: number, dir?: 'ltr'|'rtl'}[]}
+     * @returns {{text: string, width: number, dir?: 'ltr'|'rtl', end?: boolean}[]}
      */
     wrap(text: string, key: string, size: number, maxWidth: number): {
         text: string;
         width: number;
         dir?: "ltr" | "rtl";
+        end?: boolean;
     }[];
     /** @param {string} para @param {string} key @param {number} size @param {number} maxWidth @param {'ltr'|'rtl'} dir @param {number} sp @param {any[]} out */
     wrapComplex(para: string, key: string, size: number, maxWidth: number, dir: "ltr" | "rtl", sp: number, out: any[]): void;

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

@@ -1,5 +1,5 @@
 /**
- * A standard font as a fontkit-like object (unitsPerEm 1000). Loaded on first use: the metrics are about 130 KB.
+ * 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<{
@@ -11,7 +11,7 @@ export function standardFont(key: string): Promise<{
     descent: any;
     capHeight: any;
     xHeight: any;
-    italicAngle: number;
+    italicAngle: any;
     underlinePosition: any;
     underlineThickness: any;
     bbox: {
@@ -22,7 +22,7 @@ export function standardFont(key: string): Promise<{
     };
     /** WinAnsi for the text fonts (Symbol and ZapfDingbats use their own built-in encodings) */
     winAnsi: boolean;
-    widths: any[];
+    widths: any;
     /** @param {number} cp */
     hasGlyphForCodePoint: (cp: number) => boolean;
     /** @param {number} cp */
@@ -31,11 +31,11 @@ export function standardFont(key: string): Promise<{
 }>;
 /**
  * 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, as @pdf-lib/standard-fonts (pdf-lib's
- * own dependency) ships them; 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.
- */
+ * 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>;

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

@@ -61,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] */

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/importers/xml.d.ts

@@ -25,10 +25,14 @@ export namespace XML_LIMITS {
     let maxElements: number;
     let maxAttributes: number;
 }
+/**
+ * pos: where its start tag begins in the input (a character offset)
+ */
 export type XmlElement = {
     name: string;
     ns: string;
     attrs: Record<string, string>;
     children: XmlElement[];
     text: string;
+    pos?: number;
 };

package/examples/stream-1m.mjs

@@ -54,7 +54,7 @@ async function* rows() {
 const grouped = flag('grouped');
 const total = (label) => [{ height: 15, style: { fontWeight: 'bold' }, cells: [{ value: label }, { value: '=CountRows()' }, null, null, null, { value: '=Sum(Fields.amount)', style: { format: 'N2', textAlign: 'right' } }, null] }];
 const def = {
-  $schema: 'pagewright/report@1', name: 'Ledger', locale: 'en-IN', page: { size: 'A4', margins: [36, 36, 36, 36] },
+  $schema: 'reportwright/report@1', name: 'Ledger', locale: 'en-IN', page: { size: 'A4', margins: [36, 36, 36, 36] },
   // the rows come from opts.sqlRows below (a cursor); the query text is not run
   dataSources: [{ name: 'db', type: 'sql', connection: 'ledger', query: 'select * from transactions order by id' }],
   dataSets: [{ name: 'Tx', source: 'db', fields: [{ name: 'id', type: 'number' }, { name: 'account', type: 'string' }, { name: 'region', type: 'string' }, { name: 'type', type: 'string' },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reportwright/engine",
-  "version": "0.13.0",
+  "version": "0.13.2-rc.1",
   "publishConfig": {
     "access": "public"
   },
@@ -67,13 +67,12 @@
   "dependencies": {
     "pdf-lib": "1.17.1",
     "@pdf-lib/fontkit": "1.1.1",
-    "@pdf-lib/standard-fonts": "1.0.0",
     "bwip-js": "4.11.4",
     "fflate": "0.8.3",
     "bidi-js": "1.0.3"
   },
   "peerDependencies": {
-    "@reportwright/fonts": "0.13.0"
+    "@reportwright/fonts": "0.13.2-rc.1"
   },
   "peerDependenciesMeta": {
     "@reportwright/fonts": {

package/report.d.ts

@@ -1,4 +1,4 @@
-// Types for a ReportWright report definition (pagewright/report@1), the JSON that render() takes.
+// Types for a ReportWright report definition (reportwright/report@1), the JSON that render() takes.
 // GENERATED from src/engine/schema/report.schema.js by scripts/gen-report-types.mjs: do not edit by hand.
 // The same schema is published as @reportwright/engine/schema.json, and validate() checks against it.
 // Any value marked Expr may be a literal or an expression string starting with "=" (e.g. "=Fields.amount").
@@ -595,13 +595,13 @@ export interface DataSet {
   sort?: SortSpec[];
   [key: string]: unknown;
 }
-/** A ReportWright report definition (pagewright/report@1).
+/** A ReportWright report definition (reportwright/report@1).
  * @example
- * {"$schema":"pagewright/report@1","name":"Invoice","page":{"size":"A4","margins":[36,36,36,36]},"dataSources":[{"name":"orders","type":"json","data":{"rows":[{"customer":"Asha Rao","amount":1200.5}]}}],"dataSets":[{"name":"Rows","source":"orders","path":"$.rows"}],"sections":{"body":{"items":[{"type":"textbox","name":"Title","x":0,"y":0,"w":300,"h":24,"value":"Invoice","style":{"fontSize":18,"fontWeight":"bold"}},{"type":"table","name":"Lines","x":0,"y":40,"w":400,"h":40,"dataSet":"Rows","columns":[{"width":250},{"width":150}],"header":[{"height":18,"cells":[{"value":"Customer","colSpan":1},{"value":"Amount"}]}],"detail":[{"height":18,"cells":[{"value":"=Fields.customer"},{"value":"=Fields.amount","style":{"format":"C2"}}]}],"footer":[{"height":18,"cells":[{"value":"Total","colSpan":2}]}]}]}}}
+ * {"$schema":"reportwright/report@1","name":"Invoice","page":{"size":"A4","margins":[36,36,36,36]},"dataSources":[{"name":"orders","type":"json","data":{"rows":[{"customer":"Asha Rao","amount":1200.5}]}}],"dataSets":[{"name":"Rows","source":"orders","path":"$.rows"}],"sections":{"body":{"items":[{"type":"textbox","name":"Title","x":0,"y":0,"w":300,"h":24,"value":"Invoice","style":{"fontSize":18,"fontWeight":"bold"}},{"type":"table","name":"Lines","x":0,"y":40,"w":400,"h":40,"dataSet":"Rows","columns":[{"width":250},{"width":150}],"header":[{"height":18,"cells":[{"value":"Customer","colSpan":1},{"value":"Amount"}]}],"detail":[{"height":18,"cells":[{"value":"=Fields.customer"},{"value":"=Fields.amount","style":{"format":"C2"}}]}],"footer":[{"height":18,"cells":[{"value":"Total","colSpan":2}]}]}]}}}
  */
 export interface Report {
-  /** pagewright/report@1; reportwright/report@1 is the same format under the new name. */
-  $schema: 'pagewright/report@1' | 'reportwright/report@1';
+  /** reportwright/report@1; pagewright/report@1 (deprecated, the name before the rename) is the same format. */
+  $schema: 'reportwright/report@1' | 'pagewright/report@1';
   name?: string;
   description?: string;
   locale?: string;

package/schema.json

@@ -2279,14 +2279,14 @@
       "additionalProperties": true
     },
     "Report": {
-      "description": "A ReportWright report definition (pagewright/report@1).",
+      "description": "A ReportWright report definition (reportwright/report@1).",
       "type": "object",
       "properties": {
         "$schema": {
-          "description": "pagewright/report@1; reportwright/report@1 is the same format under the new name.",
+          "description": "reportwright/report@1; pagewright/report@1 (deprecated, the name before the rename) is the same format.",
           "enum": [
-            "pagewright/report@1",
-            "reportwright/report@1"
+            "reportwright/report@1",
+            "pagewright/report@1"
           ]
         },
         "name": {
@@ -2404,7 +2404,7 @@
       ],
       "examples": [
         {
-          "$schema": "pagewright/report@1",
+          "$schema": "reportwright/report@1",
           "name": "Invoice",
           "page": {
             "size": "A4",