@reportwright/engine 0.0.0-stage → 0.12.0

package/dist/types/src/engine/expr/evaluate.d.ts

@@ -0,0 +1,183 @@
+/** @param {string} src */
+export function compile(src: string): any;
+/**
+ * A value is: a literal, "=expression", or a text with {expression} parts.
+ * "{{" and "}}" give literal braces.
+ * @param {any} v
+ */
+export function parseValue(v: any): any;
+/** True when a value holds an expression. */
+export function isDynamic(v: any): boolean;
+/**
+ * Evaluate a property value. Expressions give raw values; templates give strings.
+ * @param {any} v @param {EvalCtx} ctx
+ */
+export function evalValue(v: any, ctx: EvalCtx): any;
+/** @param {any} v @param {string|null|undefined} fmt @param {EvalCtx} ctx */
+export function toText(v: any, fmt: string | null | undefined, ctx: EvalCtx): any;
+/** Check syntax only. Returns null or an error message. */
+export function checkValue(v: any): any;
+/** @param {any} n @param {EvalCtx} ctx @returns {any} */
+export function evaluate(n: any, ctx: EvalCtx): any;
+export function truthy(v: any): boolean;
+/** a + b on the decimal values. Past 2^49 a scaled integer leaves the fast path: the sum is then BigInt arithmetic. */
+export function decAdd(a: any, b: any): any;
+/** a * b on the decimal values. */
+export function decMul(a: any, b: any): number;
+export function cmpVal(a: any, b: any): 1 | 0 | -1;
+export function collator(ctx: any): any;
+/** @returns {number} for two keys (dates as their time), nulls last */
+export function sortCompare(a: any, b: any, ctx: any): number;
+/** A group key that merges values the sort calls equal ("ABC" and "abc" unless caseSensitive). */
+export function groupKeyText(key: any, ctx: any): string;
+/**
+ * True when a property value (a literal, an =expression or a {template}) reads only the current row, the parameters
+ * and the globals: no aggregate, scope, Lookup, Previous, Parent or report function. Streaming exports
+ * (engine/stream.js) evaluate such values one row at a time. rowNumber: RowNumber() / RowNumber(Nothing) is allowed
+ * too (the caller supplies ctx.rowNumber). A value that does not parse counts as row-local: it is #Error either way.
+ * @param {any} v @param {{ rowNumber?: boolean }} [o]
+ */
+export function streamable(v: any, { rowNumber }?: {
+    rowNumber?: boolean;
+}): any;
+/** streamable for a parsed expression. @param {any} ast @param {{ rowNumber?: boolean }} [o] */
+export function streamableAst(ast: any, { rowNumber }?: {
+    rowNumber?: boolean;
+}): boolean;
+/**
+ * A running Sum, Count, Avg, Min or Max: values added one at a time give the same result as the aggregate over the
+ * whole list (the same decimal addition, the same comparison, the same errors), in O(1) memory.
+ * @param {string} name lower case, one of FOLDS @param {EvalCtx} ctx
+ */
+export function aggregator(name: string, ctx: EvalCtx): {
+    /** @param {any} v one row's value (an array, a LookupSet's, adds each item) */
+    add(v: any): void;
+    value(): any;
+};
+/**
+ * Compile-on-call table of the report's functions. One per render: it also counts calls.
+ * @param {any} def @param {{n: number}} [count] shared by a render and its subreports
+ * @returns {{byName: Map<string, any>, count: {n: number}}}
+ */
+export function functionTable(def: any, count?: {
+    n: number;
+}): {
+    byName: Map<string, any>;
+    count: {
+        n: number;
+    };
+};
+/**
+ * Calls an expression makes that no render could answer: an unknown function (Frobnicate(1)), Code.X(…) with no report
+ * function X, or a method after "." that is not one of the .NET string methods. One message per name, with the
+ * nearest known name. Pure: walks the AST, evaluates nothing.
+ * @param {any} ast @param {Set<string>} custom the report's own function names, lower case
+ * @param {(name: string, known: string[]) => string | null} [suggest]
+ * @returns {string[]}
+ */
+export function callIssues(ast: any, custom: Set<string>, suggest?: (name: string, known: string[]) => string | null): string[];
+/** Errors in report functions: names, parameters, body syntax. */
+export function checkFunctions(list: any): any[];
+/** .NET composite formatting, String.Format("{0:N2} of {1,-8}", a, b): {index[,alignment][:format]}, {{ and }} */
+export function netFormat(f: any, args: any, ctx: any): string;
+/**
+ * A render's time limit (render(def, { timeoutMs })): ctx.clock = { until, n, over }. The clock is read every 1,024
+ * evaluations; once the limit has passed every evaluation throws at once, so even a quadratic report unwinds fast.
+ */
+export const OVER_TIME: "The report ran past its time limit.";
+/**
+ * Data-set row → its parent: the parent data set's row (nested data sets) or the raw object that held a
+ * [*]-spread array. Parent.* reads it when no list row supplies a parent.
+ */
+export const ROW_PARENT: WeakMap<object, any>;
+/** The aggregates a streaming export folds row by row (aggregator). */
+export const FOLDS: Set<string>;
+export namespace FUNCTIONS {
+    function format(ctx: any, v: any, f: any): any;
+    function upper(ctx: any, s: any): any;
+    function ucase(ctx: any, s: any): any;
+    function lower(ctx: any, s: any): string;
+    function lcase(ctx: any, s: any): string;
+    function left(ctx: any, s: any, n: any): string;
+    function right(ctx: any, s: any, n: any): string;
+    function mid(ctx: any, s: any, start: any, len: any): string;
+    function len(ctx: any, s: any): number;
+    function trim(ctx: any, s: any): string;
+    function replace(ctx: any, s: any, a: any, b: any, start: any, count: any): any;
+    function instr(ctx: any, s: any, sub: any): number;
+    function join(ctx: any, arr: any, sep: any): any;
+    function contains(ctx: any, hay: any, needle: any): boolean;
+    function inlist(ctx: any, v: any, ...list: any[]): boolean;
+    function cstr(ctx: any, v: any): any;
+    function javastr(ctx: any, v: any, kind: any): string;
+    function jsstr(ctx: any, v: any, digits: any): string;
+    function javaformat(ctx: any, f: any, ...args: any[]): string;
+    function cdbl(ctx: any, v: any): number;
+    function cnum(ctx: any, v: any): number;
+    function val(ctx: any, v: any): number;
+    function cint(ctx: any, v: any): number;
+    function cbool(ctx: any, v: any): boolean;
+    function cdate(ctx: any, v: any): Date;
+    function isnull(ctx: any, v: any): boolean;
+    function isnothing(ctx: any, v: any): boolean;
+    function coalesce(ctx: any, ...vs: any[]): any;
+    function round(ctx: any, v: any, d: any): number;
+    function roundhalfaway(ctx: any, v: any, d: any): number;
+    function abs(ctx: any, v: any): number;
+    function floor(ctx: any, v: any): number;
+    function ceiling(ctx: any, v: any): number;
+    function int(ctx: any, v: any): number;
+    function pow(ctx: any, a: any, b: any): number;
+    function sqrt(ctx: any, v: any): number;
+    function now(ctx: any): Date;
+    function today(ctx: any): Date;
+    function dateadd(ctx: any, i: any, n: any, d: any): Date;
+    function datediff(ctx: any, i: any, a: any, b: any, first: any): number;
+    function dateserial(ctx: any, y: any, m: any, d: any): Date;
+    function year(ctx: any, d: any): number;
+    function month(ctx: any, d: any): number;
+    function day(ctx: any, d: any): number;
+    function monthname(ctx: any, m: any, abbr: any): string;
+}
+/** Names shown in the designer's expression helper. */
+export const FUNCTION_NAMES: string[];
+export type EvalCtx = {
+    /**
+     * current row
+     */
+    fields?: Record<string, any> | null;
+    params: Record<string, any>;
+    globals: Record<string, any>;
+    /**
+     * rows for aggregates in the current scope
+     */
+    aggRows?: any[];
+    /**
+     * aggregate results for this render, per row array and call
+     */
+    aggCache?: WeakMap<any[], Map<any, any>>;
+    /**
+     * rows from scope start up to the current row
+     */
+    runningRows?: any[];
+    rowNumber?: number;
+    dataSets: Record<string, any[]>;
+    /**
+     * the render's time limit (see evaluate)
+     */
+    clock?: {
+        until: number;
+        n: number;
+        over: boolean;
+    };
+    locale?: string;
+    currency?: string;
+    /**
+     * how Infinity and NaN print: undefined (as SSRS), "blank" or "error"
+     */
+    nonFinite?: string;
+    /**
+     * digit grouping of numbers: undefined (the locale's rule, as Intl), "always" or "never"
+     */
+    grouping?: string;
+};

package/dist/types/src/engine/expr/format.d.ts

@@ -0,0 +1,122 @@
+/** A wall clock in the zone (as a UTC timestamp) → the instant; a time skipped by DST moves forward as Date does. */
+export function fromWall(w: any, tz: any): Date;
+/** 'mdy' | 'dmy' | 'ymd': the locale's numeric date order (from Intl). */
+export function dateOrder(locale: any): any;
+/**
+ * Read a value as a Date, or null. A date without a zone ("2026-03-01", "05/03/2026 14:30") is that wall clock in the
+ * report's zone; one with a zone ("…T02:00:00Z") is that instant.
+ * @param {any} v @param {{ locale?: string, timeZone?: string }} [opt]
+ */
+export function toDate(v: any, opt?: {
+    locale?: string;
+    timeZone?: string;
+}): Date;
+/** The locale's decimal and grouping separators (en-US: "." and ","; de-DE: "," and "."). */
+export function separators(locale: any): any;
+/**
+ * Text as a number the way the locale writes it: "1,234.5" (en-US), "1.234,56" / "12,5" (de-DE), with grouping
+ * (also a space or a narrow no-break space), a currency symbol, a leading or trailing sign, accounting parentheses
+ * "(1,234)" and a trailing %. NaN when it is not a number. A plain JS number text ("1e3", "-0.5") always reads.
+ * @param {string} text @param {string} [locale]
+ */
+export function parseNumber(text: string, locale?: string): number;
+/**
+ * Round half away from zero on the decimal value, like Intl, Excel and .NET format strings ("N2", "F0"): 1.005 → 1.01,
+ * 2.5 → 3. This is how displayed numbers round. VB's Round() rounds half to even instead: see roundHalfEven.
+ * @param {number} v @param {number} [digits] may be negative (1234 → 1200 with -2)
+ */
+export function roundHalfAway(v: number, digits?: number): number;
+/**
+ * VB / .NET Math.Round(x, digits): round half to even (MidpointRounding.ToEven, "banker's rounding"), 2.5 → 2,
+ * 3.5 → 4, on the decimal value (2.675 is the decimal 2.675, as a Decimal money field is in SSRS).
+ * @param {number} v @param {number} [digits] may be negative
+ */
+export function roundHalfEven(v: number, digits?: number): number;
+/**
+ * Format a value. Neutral defaults: no locale means en-US; no currency means the locale's own currency when the
+ * locale names a country ("en-IN" → ₹, as a .NET culture does), else none, and "C" then shows the number alone.
+ * @param {any} value
+ * @param {string|undefined|null} fmt
+ * @param {{locale?: string, currency?: string, timeZone?: string, nonFinite?: string, grouping?: string, fmtMemo?: Map<string, Map<any, string>>}} [opt] fmtMemo: a render's memo of formatted dates
+ */
+export function formatValue(value: any, fmt: string | undefined | null, opt?: {
+    locale?: string;
+    currency?: string;
+    timeZone?: string;
+    nonFinite?: string;
+    grouping?: string;
+    fmtMemo?: Map<string, Map<any, string>>;
+}): any;
+/**
+ * A value from data as text, without JavaScript's own spellings: a number in plain digits (1e21 →
+ * 1000000000000000000000, 1e-7 → 0.0000001), an array as its items joined by ", ", an object as compact JSON
+ * ({"nested":true}), never "[object Object]". Strings and booleans as String() gives them.
+ * @param {any} v @returns {string}
+ */
+export function plainText(v: any): string;
+export function standardDate(fmt: any, locale: any): any;
+/**
+ * .NET custom date format: runs of y M d H h m s f F t, 'quoted' and \escaped text; "%d" is the custom "d" alone.
+ * The parts are read on the wall clock of the time zone (tz; the host's when none is given).
+ * @param {Date} d @param {string} fmt @param {string} [locale] month and day names follow it @param {string} [tz]
+ */
+export function formatDate(d: Date, fmt: string, locale?: string, tz?: string): string;
+export function validTimeZone(tz: any): boolean;
+export function toWall(d: any, tz: any): any;
+export function zoneDate(y: any, m: any, d: any, tz: any, h?: number, mi?: number, sec?: number, ms?: number): Date;
+export function wallDate(d: any, tz: any): Date;
+export function isoDate(d: any, tz: any): string;
+export function shiftDec(x: any, e: any): number;
+export namespace REGION_CURRENCY {
+    let US: string;
+    let IN: string;
+    let GB: string;
+    let DE: string;
+    let FR: string;
+    let ES: string;
+    let IT: string;
+    let NL: string;
+    let BE: string;
+    let AT: string;
+    let PT: string;
+    let IE: string;
+    let FI: string;
+    let GR: string;
+    let JP: string;
+    let CN: string;
+    let CA: string;
+    let AU: string;
+    let NZ: string;
+    let CH: string;
+    let SG: string;
+    let AE: string;
+    let SA: string;
+    let BR: string;
+    let MX: string;
+    let ZA: string;
+    let KR: string;
+    let RU: string;
+    let ID: string;
+    let MY: string;
+    let PH: string;
+    let TH: string;
+    let VN: string;
+    let PK: string;
+    let BD: string;
+    let LK: string;
+    let NP: string;
+    let SE: string;
+    let NO: string;
+    let DK: string;
+    let PL: string;
+    let TR: string;
+    let IL: string;
+    let EG: string;
+    let NG: string;
+    let KE: string;
+    let HK: string;
+    let TW: string;
+}
+export function currencyOf(locale: string | undefined): any;
+export function english(locale: any): boolean;
+export const DAY_MS: 86400000;

package/dist/types/src/engine/expr/javafmt.d.ts

@@ -0,0 +1,26 @@
+/** Double.toString: shortest digits; "2.0"; 1.0E7 and 1.0E-4 outside [10^-3, 10^7) */
+export function javaDouble(x: any): string;
+/**
+ * Format a value with a "java:…" or "icu:…" format (see the top of this file). null and undefined give ''.
+ * @param {any} value @param {string} fmt @param {{ locale?: string, timeZone?: string }} [opt]
+ */
+export function formatJava(value: any, fmt: string, opt?: {
+    locale?: string;
+    timeZone?: string;
+}): any;
+/**
+ * String.valueOf(x) in Java, for string concatenation in JasperReports expressions: "null", true/false,
+ * Double.toString ("2.0"), Date.toString; kind "int" for an integral value (Integer, Long: "2").
+ * @param {any} v @param {string} [kind] @param {string} [tz]
+ */
+export function javaString(v: any, kind?: string, tz?: string): string;
+/** JavaScript's String(x), for string concatenation in BIRT expressions: "null", true/false, shortest digits. */
+export function jsString(v: any): string;
+/**
+ * java.util.Formatter (String.format) for the common conversions: %s %S %b %c %d %o %x %X %f %e %E %% %n, with flags
+ * - + space 0 , ( and width, precision and argument index (%2$s). %f rounds half up on the shortest decimal form, as
+ * Java does (String.format("%.2f", 1.005) is "1.01"). Digits and separators are the locale's.
+ * @param {string} f @param {any[]} args @param {string} [locale] @param {string} [tz]
+ */
+export function javaFormatString(f: string, args: any[], locale?: string, tz?: string): string;
+export function isJavaFormat(fmt: any): boolean;

package/dist/types/src/engine/expr/parser.d.ts

@@ -0,0 +1,29 @@
+/** @param {string} src */
+export function lex(src: string): ({
+    t: string;
+    v: number;
+    p: number;
+} | {
+    t: string;
+    v: string;
+    p: number;
+})[];
+/** @param {string} src */
+export function parse(src: string): any;
+/**
+ * Expression language: lexer + Pratt parser.
+ * No eval, no new Function. The AST is plain data.
+ */
+export class ExprError extends Error {
+    /** @param {string} msg @param {number} [pos] @param {string} [src] */
+    constructor(msg: string, pos?: number, src?: string);
+    pos: number;
+    src: string;
+}
+/** The longest string a function or a format may build, checked before it is built (capText). */
+export const MAX_TEXT: 1000000;
+export function capText(fname: string, n: number): void;
+export const MAX_PATTERN: 1000;
+export const MAX_DIGITS: 340;
+export function capPattern(fname: any, pat: any): void;
+export function capDigits(fname: any, n: any): void;

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

@@ -0,0 +1,107 @@
+/** @param {Uint8Array} b @returns {keyof MIME | null} */
+export function sniff(b: Uint8Array): ("png" | "jpeg" | "gif" | "webp" | "svg") | null;
+/**
+ * A data URI for bytes or bare base64; anything else (a URL, a data URI) comes back as it was.
+ * @param {unknown} v
+ * @returns {unknown}
+ */
+export function toDataUri(v: unknown): unknown;
+/**
+ * The parts of a data URI: one rule for every caller (the size cap and the decoder must agree).
+ * Base64 when the last parameter is exactly "base64".
+ * @param {string} uri
+ */
+export function splitDataUri(uri: string): {
+    meta: string;
+    b64: boolean;
+    body: string;
+};
+/** Decoded size of a data URI, without decoding it (an upper bound). @param {string} uri */
+export function dataUriBytes(uri: string): number;
+/**
+ * The first bytes of a data URI (enough for any image header), or all of it with max = Infinity.
+ * @param {string} uri
+ * @returns {Uint8Array | null}
+ */
+export function dataUriHead(uri: string, max?: number): Uint8Array | null;
+/** All the bytes of a data URI (callers check the size first). @param {string} uri */
+export function dataUriBytesOf(uri: string): Uint8Array<ArrayBufferLike>;
+/** An SVG length in px; null for a percentage or nonsense. @param {string|undefined} v */
+export function svgLength(v: string | undefined): number;
+/**
+ * The tags of an XML text, in order: one pass with indexOf and a quote-aware scan, so the time is linear in
+ * the length whatever the input (no regular expression that can backtrack). Comments, CDATA, <?…?> and
+ * <!…> are skipped; an unfinished construct ends the scan.
+ * @param {string} text
+ * @returns {Generator<{ close: boolean, name: string, attrs: string, self: boolean }>}
+ */
+export function xmlTags(text: string): Generator<{
+    close: boolean;
+    name: string;
+    attrs: string;
+    self: boolean;
+}>;
+/** name="value" / name='value' pairs, in one linear pass. @param {string} s @returns {Record<string,string>} */
+export function xmlAttrs(s: string): Record<string, string>;
+/** Attributes of the root <svg> tag. @param {string} text */
+export function svgRootAttrs(text: string): Record<string, string>;
+/** Natural size of an SVG in px: width/height, else the viewBox. @param {string} text */
+export function svgSize(text: string): {
+    w: number;
+    h: number;
+};
+/**
+ * Type and natural size (px) of image bytes, from the header.
+ * @param {Uint8Array} b
+ * @returns {{ type: string, w: number, h: number } | { type: string } | null}
+ */
+export function imageInfoOf(b: Uint8Array): {
+    type: string;
+    w: number;
+    h: number;
+} | {
+    type: string;
+} | null;
+/**
+ * PNG size as pdf-lib's decoder (UPNG) will see it: it walks every chunk and keeps the LAST IHDR, and an
+ * animated PNG (acTL/fcTL/fdAT) allocates a buffer per frame from the frame's own size. So walk the chunks
+ * exactly as it does, and report animation, rather than trusting the bytes after the signature.
+ * @param {Uint8Array} b
+ */
+export function pngInfo(b: Uint8Array): {
+    type: string;
+} | {
+    suspect?: boolean;
+    type: string;
+    w: number;
+    h: number;
+};
+/** Type and natural size (px) of a data URI image. @param {string} uri */
+export function imageInfo(uri: string): {
+    type: string;
+};
+/**
+ * Resolve an image source to what the page model carries: a data URI, a URL, or null (left out).
+ * @param {unknown} v evaluated src
+ * @param {string} who for warnings
+ * @param {{ images?: Record<string, string>, budget?: { seen: Set<string>, bytes: number, memo?: Map<unknown, unknown> }, warn: (m: string) => void }} c
+ * @returns {string | null}
+ */
+export function resolveImageSrc(v: unknown, who: string, c: {
+    images?: Record<string, string>;
+    budget?: {
+        seen: Set<string>;
+        bytes: number;
+        memo?: Map<unknown, unknown>;
+    };
+    warn: (m: string) => void;
+}): string | null;
+export namespace IMAGE_LIMITS {
+    let bytes: number;
+    let total: number;
+    let pixels: number;
+    let svgBytes: number;
+    let svgShapes: number;
+}
+/** 1 image pixel = 0.75 pt (96 dpi, as in CSS). */
+export const PX: 0.75;