@reportwright/engine 0.0.0-stage → 0.11.0

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

@@ -0,0 +1,75 @@
+/**
+ * A FontStore over the @reportwright/fonts package (install it next to the engine). Throws when it isn't installed.
+ * In a bundled browser app, pass `fontsUrl`: the URL (or, in Node, the path) of a copy of the package's public/fonts
+ * folder; each font is read from there, and a missing one is an error.
+ * @param {{ fontsUrl?: string }} [opts]
+ * @returns {FontStore}
+ */
+export function defaultFontStore(opts?: {
+    fontsUrl?: string;
+}): FontStore;
+/**
+ * @typedef {Omit<NonNullable<Parameters<typeof exportPdfFull>[2]>, 'subset' | 'pdfa'> & {
+ *   fonts?: FontStore, subset?: false | NonNullable<Parameters<typeof exportPdfFull>[2]>['subset'],
+ *   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
+ * 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
+ * @param {PdfOptions} [options]
+ * @returns {Promise<Uint8Array>}
+ */
+export function exportPdf(model: any, options?: PdfOptions, ...args: any[]): Promise<Uint8Array>;
+/**
+ * Page model → .xlsx bytes: exportXlsx(model, { fonts, currency, formulas, ... }) (needs render(def, { exportData: true })).
+ * The 0.7 form exportXlsx(model, ExcelJS, options) still works in 0.8 (deprecated; ExcelJS is not used).
+ * @param {any} model @param {NonNullable<Parameters<typeof exportXlsxFull>[1]> & { fonts?: FontStore }} [options]
+ * @returns {Promise<Uint8Array>}
+ */
+export function exportXlsx(model: any, options?: NonNullable<Parameters<typeof exportXlsxFull>[1]> & {
+    fonts?: FontStore;
+}, ...args: any[]): Promise<Uint8Array>;
+/**
+ * Page model → .docx bytes: exportDocx(model, { fonts, ... }) (needs render(def, { exportData: true })).
+ * @param {any} model @param {NonNullable<Parameters<typeof exportDocxFull>[1]> & { fonts?: FontStore }} [options]
+ * @returns {Promise<Uint8Array>}
+ */
+export function exportDocx(model: any, options?: NonNullable<Parameters<typeof exportDocxFull>[1]> & {
+    fonts?: FontStore;
+}, ...args: any[]): Promise<Uint8Array>;
+/**
+ * Page model → .pptx bytes: exportPptx(model, { fonts, ... }).
+ * @param {any} model @param {NonNullable<Parameters<typeof exportPptxFull>[1]> & { fonts?: FontStore }} [options]
+ * @returns {Promise<Uint8Array>}
+ */
+export function exportPptx(model: any, options?: NonNullable<Parameters<typeof exportPptxFull>[1]> & {
+    fonts?: FontStore;
+}, ...args: any[]): Promise<Uint8Array>;
+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 type PdfOptions = Omit<NonNullable<Parameters<typeof exportPdfFull>[2]>, "subset" | "pdfa"> & {
+    fonts?: FontStore;
+    subset?: false | NonNullable<Parameters<typeof exportPdfFull>[2]>["subset"];
+    pdfa?: boolean | {
+        icc?: Uint8Array;
+        [k: string]: unknown;
+    };
+};
+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';
+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 { exportPdf as exportPdfFull } from '../../src/exporters/pdf.js';
+export { fontFile, createSubsetter };
+export { render, FontStore, ITEMS, parameterOptions, resolveParameters } from "../../src/engine/index.js";
+export { blankReport, blankDashboard } from "../../src/engine/schema/template.js";
+export { tableFor, matrixFor } from "../../src/designer/tableGen.js";

package/dist/types/src/designer/tableGen.d.ts

@@ -0,0 +1,119 @@
+/** "dueDate" → "Due date", "customer_name" → "Customer name"; all-caps names stay. */
+export function labelOf(name: any): any;
+/**
+ * One format per field, the same in detail rows, subtotals, totals and charts:
+ * ids, years and month numbers plain (0); counts N0; money N2 (C2 when the report has a currency); dates 12 Jan 2026;
+ * other numbers N0 when every sample value is whole, else N2. Without sample rows the name decides.
+ * @param {{ name: string, type?: string }} f @param {any[]} [rows] @param {{ currency?: string }} [opt]
+ */
+export function formatFor(f: {
+    name: string;
+    type?: string;
+}, rows?: any[], { currency }?: {
+    currency?: string;
+}): "0" | "dd MMM yyyy" | "C2" | "N0" | "N2";
+/** A compact axis format for values up to `max`: 300M, 2,730M, 50K (none below 20 of the unit: 15,000 stays as it is). */
+export function compactFormat(max: any): string | number;
+/**
+ * @param {{ name: string, fields?: { name: string, type?: string }[] }} ds
+ * @param {{ layout?: 'list'|'grouped'|'summary', groupBy?: string, width?: number, rows?: any[], fields?: string[], currency?: string }} opt
+ *   fields: which fields, in order (default all); rows: sample rows, to pick number formats; currency: the symbol for money cells
+ */
+export function tableFor(ds: {
+    name: string;
+    fields?: {
+        name: string;
+        type?: string;
+    }[];
+}, opt?: {
+    layout?: "list" | "grouped" | "summary";
+    groupBy?: string;
+    width?: number;
+    rows?: any[];
+    fields?: string[];
+    currency?: string;
+}): {
+    type: string;
+    dataSet: any;
+    w: number;
+    h: number;
+    repeatHeader: boolean;
+    columns: any;
+    header: {
+        height: number;
+        style: {
+            fontWeight: string;
+            backgroundColor: string;
+            borderBottom: string;
+        };
+        cells: any;
+    }[];
+    detail: {
+        height: number;
+        style: {
+            borderBottom: string;
+        };
+        cells: any;
+    }[];
+    footer: {
+        height: number;
+        style: {
+            fontWeight: string;
+            borderTop: string;
+        };
+        cells: any;
+    }[];
+};
+/**
+ * @param {{ name: string, fields?: { name: string, type?: string }[] }} ds
+ * @param {{ rows: string, columns: string, value: string, agg?: string, width?: number, sample?: any[], currency?: string }} opt
+ */
+export function matrixFor(ds: {
+    name: string;
+    fields?: {
+        name: string;
+        type?: string;
+    }[];
+}, { rows, columns, value, agg, width, sample, currency }: {
+    rows: string;
+    columns: string;
+    value: string;
+    agg?: string;
+    width?: number;
+    sample?: any[];
+    currency?: string;
+}): {
+    type: string;
+    dataSet: string;
+    w: number;
+    h: number;
+    corner: any;
+    rowGroups: {
+        name: any;
+        expr: string;
+        sort: string;
+        total: string;
+    }[];
+    columnGroups: {
+        name: string;
+        expr: string;
+        sort: string;
+        total: string;
+    }[];
+    values: {
+        value: string;
+        format: string;
+    }[];
+};
+/**
+ * The fields Instant visuals starts with: the text field with the fewest distinct values (2 to 24; never an id, a
+ * code or a field unique on almost every row), a second such field when there is one, and the first additive number
+ * (an amount, not an id or a rate). No rows yet: by name and type only. A 180 × 180 pivot of Id by Borrower helps nobody.
+ * @param {{ name: string, type?: string }[]} fields @param {any[]} rows
+ * @returns {string[]}
+ */
+export function instantPicks(fields: {
+    name: string;
+    type?: string;
+}[], rows?: any[]): string[];
+export function isCode(name: any): boolean;

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

@@ -0,0 +1,50 @@
+/** True for an address no data source may reach by default. @param {string} host a hostname as URL gives it */
+export function privateHost(host: string): boolean;
+/**
+ * Check one URL the default fetch would request: scheme, credentials, and a literal address. Anything it cannot
+ * read is refused (fail closed). A name is checked again, as resolved, by the Node transport's lookup.
+ * @param {string} input @param {string[]} allow lower-case host names
+ * @returns {URL}
+ */
+export function checkUrl(input: string, allow: string[]): URL;
+/**
+ * The request for a redirect hop, or an error: https → http is refused; another origin keeps only CROSS_ORIGIN_KEEP;
+ * 303 (and 301/302 after a non-GET) becomes a GET without a body.
+ * @param {URL} from @param {URL} to @param {any} req @param {number} status
+ */
+export function redirectRequest(from: URL, to: URL, req: any, status: number): any;
+/**
+ * The guarded default fetch (see the top of this file). In Node every hop goes through nodeRequest (address pinned);
+ * in a browser through `base` with redirects by hand (literal addresses checked; a browser has no DNS to ask).
+ * @param {{ allowHosts?: string[] }} opt @param {typeof fetch} base
+ * @returns {typeof fetch}
+ */
+export function guardedFetch(opt: {
+    allowHosts?: string[];
+}, base: typeof fetch): typeof fetch;
+/**
+ * Any fetch with the engine's time limit and byte cap.
+ * @param {typeof fetch} f @param {{ fetchTimeoutMs?: number, maxFetchBytes?: number, deadline?: number }} opt
+ * @returns {typeof fetch}
+ */
+export function boundedFetch(f: typeof fetch, opt: {
+    fetchTimeoutMs?: number;
+    maxFetchBytes?: number;
+    deadline?: number;
+}): typeof fetch;
+/**
+ * A URL safe to print: no userinfo, and the query and fragment shown as ?… / #… (their values can hold keys and tokens).
+ * @param {string} s
+ */
+export function redactUrl(s: string): string;
+/**
+ * A failed request as an error that says why: the cause code (DNS, refused, reset, TLS, timeout) and the redacted URL.
+ * An error that already carries a status (a refused address, a redirect) passes through.
+ * @param {any} e @param {any} input
+ */
+export function fetchFailure(e: any, input: any): any;
+export namespace FETCH_DEFAULTS {
+    let timeoutMs: number;
+    let maxBytes: number;
+    let hops: number;
+}

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

@@ -0,0 +1,120 @@
+/** Minimal JSONPath: $, $.a.b, $.a[0].b, $.a[*].b, $['a b'] */
+export function jsonPath(obj: any, path: any): any;
+/**
+ * jsonPath that also says, for each result of a [*] spread, which object held the spread collection
+ * (for $.books[*].positions[*], the book of each position): Parent.* in the data set's rows.
+ * @returns {{rows: any, parents: any[]|null}}
+ */
+export function jsonPathRows(obj: any, path: any): {
+    rows: any;
+    parents: any[] | null;
+};
+/**
+ * A raw value as the field's type. Numbers in text are read the locale's way ("12,5" and "1.234,56" in de-DE, "1,234.5"
+ * and "(1,234)" in en-US); dates without a zone are the wall clock of the report's zone. A value that does not read
+ * is null, and opt.bad hears of it (the data set warns once).
+ * @param {any} v @param {string} type @param {{ locale?: string, timeZone?: string, bad?: (v: any) => void }} [opt]
+ */
+export function coerce(v: any, type: string, opt?: {
+    locale?: string;
+    timeZone?: string;
+    bad?: (v: any) => void;
+}): any;
+/**
+ * Guess field names and types from sample rows. A string that looks like an ISO date (2024-01-31, 2024-01-31T10:00Z)
+ * becomes a date field; dates: false (a data set's detectDates: false) keeps it text. To keep one field as text,
+ * declare the data set's fields with that one as type "string".
+ * @param {any[]} rows @param {{ dates?: boolean }} [opt]
+ */
+export function detectFields(rows: any[], { dates }?: {
+    dates?: boolean;
+}): {
+    name: any;
+    type: any;
+}[];
+/** One-character CSV option: "tab" and "\\t" mean a tab. */
+export function csvChar(v: any, dflt: any, what: any): any;
+/**
+ * Parse CSV text into objects. One forward scan, O(n): 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.
+ * @param {string} text
+ * @param {{separator?: string, quote?: string, headerRow?: boolean, startRow?: number}} [opts]
+ *   startRow: 1-based record where the header (or the data, without a header row) starts.
+ */
+export function parseCsv(text: string, opts?: {
+    separator?: string;
+    quote?: string;
+    headerRow?: boolean;
+    startRow?: number;
+}): {
+    [k: string]: string;
+}[];
+/**
+ * Load every data source used by the report.
+ * @param {any} def
+ * @param {{params: object, fetch?: typeof fetch, baseUrl?: string, reportId?: string,
+ *   sql?: (src: any, params: Record<string, any>) => Promise<object[]>, sqlPreview?: boolean}} opt
+ *   sql: runs a SQL source directly (server renders). Without it the server runs the saved report's
+ *   query: the browser sends the report id and source name, never SQL.
+ */
+export function loadSources(def: any, opt: {
+    params: object;
+    fetch?: typeof fetch;
+    baseUrl?: string;
+    reportId?: string;
+    sql?: (src: any, params: Record<string, any>) => Promise<object[]>;
+    sqlPreview?: boolean;
+}): Promise<{}>;
+/**
+ * The response of a rest (JSON) or csv source, unread, for a streaming render: the same URL, headers, body and proxy as
+ * loadSources. init.pwStream asks the server's fetch for its streaming size cap (safeFetch) instead of the whole-body one.
+ * @param {any} src @param {any} ctx @param {{ fetch?: typeof fetch, baseUrl?: string }} opt
+ * @returns {Promise<Response>}
+ */
+export function sourceResponse(src: any, ctx: any, opt: {
+    fetch?: typeof fetch;
+    baseUrl?: string;
+}): Promise<Response>;
+/**
+ * A response whose Content-Type names a charset other than UTF-8 is re-encoded to UTF-8 as it streams, so every reader
+ * (text, the CSV and JSON splitters) gets the text the server meant. TextDecoder knows the labels; an unknown one is an error.
+ * @param {Response} res
+ */
+export function utf8Response(res: Response): Response;
+/**
+ * Build typed rows for every data set.
+ * @param {any} def @param {Record<string, any>} sources @param {any} baseCtx
+ */
+export function buildDataSets(def: any, sources: Record<string, any>, baseCtx: any): Record<string, any[]>;
+/**
+ * Rows a region bound to a data set should show: for a nested data set inside a list (or group) bound to its
+ * parent, only the current parent rows' children; anywhere else, all rows.
+ * @param {any[]} rows @param {any} ctx
+ */
+export function related(rows: any[], ctx: any): any;
+/**
+ * Filters run in the order listed. Row filters (=, <, in, like, Between …) test each row; set filters
+ * (TopN, BottomN, TopPercent, BottomPercent) rank all rows left by the filters before them.
+ * @param {any[]} rows @param {any[]|undefined} filters
+ */
+export function applyFilters(rows: any[], filters: any[] | undefined, baseCtx: any): any[];
+export function rowFilter(f: any, c: any): boolean;
+/** Compare two rows' sort keys as applySort does (nulls last, or lowest with nullOrder "low"; the report's collation);
+ *  0 when equal (the caller keeps the rows' order). @param {any[]} sort */
+export function compareKeys(ka: any, kb: any, sort: any[], ctx: any): number;
+/** @param {any[]} rows @param {any[]|undefined} sort */
+export function applySort(rows: any[], sort: any[] | undefined, baseCtx: any): any[];
+/**
+ * The raw rows of a source at a data set path: XPath for an XML source, JSONPath otherwise (the designer's Detect and Use).
+ * @param {any} raw @param {string} [path]
+ */
+export function sourceRows(raw: any, path?: string): any[];
+/** Source types whose data is fetched (an xml or csv source with inline data is not). */
+export const FETCHED_TYPES: string[];
+export const SET_OPS: Set<string>;
+export function sortKeys(sort: any[], c: any): any[];
+export function sourceUrl(url: any, params: any): string;
+import { evaluate } from '../expr/evaluate.js';
+import { compile } from '../expr/evaluate.js';
+import { isXmlDoc } from './xml.js';
+export { evaluate, compile, isXmlDoc };

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

@@ -0,0 +1,35 @@
+/** ReportWright field type of an Edm type. @param {string} [edm] */
+export function odataFieldType(edm?: string): "string" | "number" | "boolean" | "date";
+/**
+ * Entity sets of a $metadata (CSDL) document, with their properties (base types included) and navigation properties.
+ * @param {string} text
+ * @returns {{ name: string, type: string, properties: { name: string, type: string }[], navigation: string[] }[]}
+ */
+export function odataMetadata(text: string): {
+    name: string;
+    type: string;
+    properties: {
+        name: string;
+        type: string;
+    }[];
+    navigation: string[];
+}[];
+/** An OData literal for a value of an Edm type (or of the value's own JS type). */
+export function odataLiteral(v: any, type: any): string;
+/**
+ * The query string of an OData source. `value(x)` evaluates a filter value, top or skip ({Parameters.x}, =expr or text).
+ * A filter whose value is empty (an unset parameter) is left out, so it means "all".
+ * @param {any} src @param {(v: any) => any} value
+ */
+export function odataQuery(src: any, value: (v: any) => any): string;
+/** The entity set's URL: the service root + the entity set + the query. @param {string} root @param {any} src @param {(v: any) => any} value */
+export function odataUrl(root: string, src: any, value: (v: any) => any): string;
+/** One page of a response: its rows (v4 value, v2 d.results / d) and the next link, if any. @param {any} json */
+export function odataPage(json: any): {
+    rows: any;
+    next: string;
+};
+/** Rows without OData annotations, numbers and dates read by the source's property types. */
+export function odataClean(rows: any, types?: {}): any;
+export const ODATA_MAX_PAGES: 100;
+export const ODATA_DEFAULT_PAGES: 10;

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

@@ -0,0 +1,108 @@
+/**
+ * An XML source's value: the root element and the source's prefix → namespace URI map.
+ * @param {string} text @param {{ namespaces?: Record<string, string> }} [src]
+ */
+export function xmlDocument(text: string, src?: {
+    namespaces?: Record<string, string>;
+}): {
+    $xml: import("../../importers/xml.js").XmlElement;
+    $ns: {
+        [x: string]: string;
+    };
+};
+/** A SOAP response's Body content (its first element), or the Fault's message as an error. @param {string} text */
+export function soapBody(text: string, src?: {}): {
+    $xml: import("../../importers/xml.js").XmlElement;
+    $ns: {
+        [x: string]: string;
+    };
+};
+/** @param {string} path @returns {{ abs: boolean, steps: Step[] }} */
+export function compileXPath(path: string): {
+    abs: boolean;
+    steps: Step[];
+};
+/** The text of an element and all its descendants, trimmed (XPath's string value). @param {XmlElement} el */
+export function stringValue(el: XmlElement): string;
+/**
+ * Evaluate a path: elements, or strings for @attr / text().
+ * @param {{ $xml: XmlElement, $ns: Record<string, string> }} doc
+ * @param {string} path
+ * @param {XmlElement} [context] for a relative path (a field of a row); a relative path without one starts at the root
+ * @returns {(XmlElement|string)[]}
+ */
+export function selectXml(doc: {
+    $xml: XmlElement;
+    $ns: Record<string, string>;
+}, path: string, context?: XmlElement): (XmlElement | string)[];
+/** A field's value: the first result of a path relative to the row element, as text. */
+export function xmlValue(doc: any, el: any, path: any): string;
+/**
+ * A row object from an element: its attributes, each child element (text for a leaf, an object for a child with
+ * children of its own, a list when the name repeats), and its own text under its name when it has no child elements.
+ * @param {XmlElement} el
+ */
+export function xmlObject(el: XmlElement): Record<string, any>;
+/**
+ * Every repeating element in the document (an element whose parent has more than one child of that name), as the
+ * response explorer shows lists: { path, rows, objects, fields, spreads }. One linear walk; fields from the first 50 rows.
+ * @param {{ $xml: XmlElement }} doc
+ */
+export function xmlRowPaths(doc: {
+    $xml: XmlElement;
+}): {
+    path: string;
+    rows: number;
+    objects: boolean;
+    fields: string[];
+    spreads: number;
+}[];
+/** The likeliest rows: the most rows, then the shallowest. */
+export function bestXmlRows(doc: any): {
+    path: string;
+    rows: number;
+    objects: boolean;
+    fields: string[];
+    spreads: number;
+};
+/**
+ * Row elements and row objects for a data set path ("$" or empty: the likeliest repeating element).
+ * @param {{ $xml: XmlElement, $ns: Record<string, string> }} doc @param {string} [path]
+ */
+export function xmlRows(doc: {
+    $xml: XmlElement;
+    $ns: Record<string, string>;
+}, path?: string): {
+    els: import("../../importers/xml.js").XmlElement[];
+    rows: Record<string, any>[];
+} | {
+    els: any;
+    rows: {
+        value: string | import("../../importers/xml.js").XmlElement;
+    }[];
+};
+export const XPATH_MAX: 512;
+export function isXmlDoc(v: any): boolean;
+export function xmlEscape(s: any): string;
+export { XmlError };
+export type XmlElement = import("../../importers/xml.js").XmlElement;
+export type Test = {
+    kind: "name";
+    prefix: string;
+    local: string;
+} | {
+    kind: "self";
+} | {
+    kind: "parent";
+} | {
+    kind: "attr";
+    local: string;
+} | {
+    kind: "text";
+};
+export type Step = {
+    desc: boolean;
+    test: Test;
+    preds: any[];
+};
+import { XmlError } from '../../importers/xml.js';