@olenbetong/appframe-core 2.11.9 → 2.12.0

package/src/report/parameters.test.ts

@@ -0,0 +1,218 @@
+import { describe, expect, it } from "vitest";
+
+import {
+	coerceParameterValue,
+	getDefaultParameterValues,
+	isProcedureDefault,
+	parseParameterItems,
+	parseParameters,
+	restoreParameterValues,
+	serializeParameters,
+	toReportParameter,
+	toReportParameters,
+} from "./parameters.js";
+import type { ReportParameterRecord } from "./types.js";
+
+const lookupRecordSource = `<?xml version="1.0" encoding="utf-16"?>
+<afRecordSource>
+  <ViewName>aviw_Accounting_Departments</ViewName>
+  <SelectColumns>
+    <afSelectColumn><Name>DepartmentID</Name><Size>5</Size></afSelectColumn>
+    <afSelectColumn><Name>Description</Name><Size>300</Size></afSelectColumn>
+  </SelectColumns>
+  <WhereClause>Archived = 0</WhereClause>
+  <FilterString />
+  <MaxRecords>0</MaxRecords>
+</afRecordSource>`;
+
+function record(overrides: ReportParameterRecord = {}): ReportParameterRecord {
+	return { Name: "Period", Label: "Periode", DataType: "Integer", SortOrder: 0, ...overrides };
+}
+
+describe("isProcedureDefault", () => {
+	it("recognizes a stored procedure name", () => {
+		expect(isProcedureDefault("astp_Reports_CurrentPeriod")).toBe(true);
+		expect(isProcedureDefault("sstp_System_Something")).toBe(true);
+	});
+
+	it("treats a literal as a literal", () => {
+		expect(isProcedureDefault("202601")).toBe(false);
+		expect(isProcedureDefault("stp_NotNamespaced")).toBe(false);
+		expect(isProcedureDefault(null)).toBe(false);
+	});
+});
+
+describe("parseParameterItems", () => {
+	it("splits on line breaks and drops blank lines", () => {
+		expect(parseParameterItems("Ja\r\nNei\r\n")).toEqual(["Ja", "Nei"]);
+	});
+
+	it("returns nothing for an empty column", () => {
+		expect(parseParameterItems(null)).toEqual([]);
+	});
+});
+
+describe("toReportParameter", () => {
+	it("falls back to the name when there is no label", () => {
+		expect(toReportParameter(record({ Label: "  " })).label).toBe("Period");
+	});
+
+	it("picks an editor from the data type", () => {
+		expect(toReportParameter(record({ DataType: "Integer" })).editor).toBe("number");
+		expect(toReportParameter(record({ DataType: "Double" })).editor).toBe("number");
+		expect(toReportParameter(record({ DataType: "Date" })).editor).toBe("date");
+		expect(toReportParameter(record({ DataType: "Boolean" })).editor).toBe("boolean");
+		expect(toReportParameter(record({ DataType: "String" })).editor).toBe("text");
+	});
+
+	it("falls back to text for an unknown data type", () => {
+		let parameter = toReportParameter(record({ DataType: "Guid" }));
+
+		expect(parameter.type).toBe("String");
+		expect(parameter.editor).toBe("text");
+	});
+
+	it("prefers a fixed item list over the data type", () => {
+		let parameter = toReportParameter(record({ DataType: "String", Items: "Ja\r\nNei" }));
+
+		expect(parameter.editor).toBe("select");
+		expect(parameter.items).toEqual(["Ja", "Nei"]);
+	});
+
+	it("prefers a lookup over an item list", () => {
+		let parameter = toReportParameter(
+			record({ RecordSource: lookupRecordSource, ValueMember: "DepartmentID", Items: "Ja\r\nNei" }),
+		);
+
+		expect(parameter.editor).toBe("lookup");
+		expect(parameter.recordSource?.viewName).toBe("aviw_Accounting_Departments");
+		expect(parameter.recordSource?.whereClause).toBe("Archived = 0");
+		expect(parameter.valueMember).toBe("DepartmentID");
+		expect(parameter.displayMember).toBe("Description");
+	});
+
+	it("uses the first selected column when the record source has no value member", () => {
+		let parameter = toReportParameter(record({ RecordSource: lookupRecordSource, ValueMember: null }));
+
+		expect(parameter.valueMember).toBe("DepartmentID");
+		expect(parameter.displayMember).toBe("Description");
+	});
+
+	it("ignores a value member without a record source", () => {
+		let parameter = toReportParameter(record({ ValueMember: "DepartmentID" }));
+
+		expect(parameter.editor).toBe("number");
+		expect(parameter.valueMember).toBeNull();
+	});
+});
+
+describe("toReportParameters", () => {
+	it("sorts by sort order and drops nameless records", () => {
+		let parameters = toReportParameters([
+			record({ Name: "B", Label: "B", SortOrder: 2 }),
+			record({ Name: "", Label: "" }),
+			record({ Name: "A", Label: "A", SortOrder: 1 }),
+		]);
+
+		expect(parameters.map((parameter) => parameter.name)).toEqual(["A", "B"]);
+	});
+});
+
+describe("coerceParameterValue", () => {
+	let integer = toReportParameter(record({ DataType: "Integer" }));
+	let double = toReportParameter(record({ DataType: "Double" }));
+	let boolean = toReportParameter(record({ DataType: "Boolean" }));
+	let text = toReportParameter(record({ DataType: "String" }));
+
+	it("parses numbers", () => {
+		expect(coerceParameterValue(integer, "202601")).toBe(202601);
+		expect(coerceParameterValue(integer, "not a number")).toBeNull();
+		expect(coerceParameterValue(double, "1,5")).toBe(1.5);
+	});
+
+	it("parses the booleans the designer writes", () => {
+		expect(coerceParameterValue(boolean, "True")).toBe(true);
+		expect(coerceParameterValue(boolean, "Ja")).toBe(true);
+		expect(coerceParameterValue(boolean, "0")).toBe(false);
+	});
+
+	it("treats an empty value as unset, except for booleans", () => {
+		expect(coerceParameterValue(text, "")).toBeNull();
+		expect(coerceParameterValue(boolean, "")).toBe(false);
+	});
+});
+
+describe("getDefaultParameterValues", () => {
+	it("uses literal defaults", () => {
+		let parameters = toReportParameters([record({ DefaultValue: "202601" })]);
+
+		expect(getDefaultParameterValues(parameters)).toEqual({ Period: 202601 });
+	});
+
+	it("leaves stored procedure defaults unset", () => {
+		let parameters = toReportParameters([record({ DefaultValue: "astp_Reports_CurrentPeriod" })]);
+
+		expect(getDefaultParameterValues(parameters)).toEqual({ Period: null });
+	});
+});
+
+describe("serializeParameters", () => {
+	it("writes the shape the Windows client reads", () => {
+		let parameters = toReportParameters([
+			record({ Name: "Period", DataType: "Integer", SortOrder: 0 }),
+			record({ Name: "Hide0", DataType: "Boolean", SortOrder: 1 }),
+		]);
+
+		expect(serializeParameters(parameters, { Period: 202601, Hide0: true })).toBe(
+			[
+				'<Parameters Version="1">',
+				'  <Parameter Name="Period" Type="Integer">202601</Parameter>',
+				'  <Parameter Name="Hide0" Type="Boolean">True</Parameter>',
+				"</Parameters>",
+			].join("\n"),
+		);
+	});
+
+	it("escapes values", () => {
+		let parameters = toReportParameters([record({ Name: "Text", DataType: "String" })]);
+
+		expect(serializeParameters(parameters, { Text: "a & <b>" })).toContain(">a &amp; &lt;b&gt;<");
+	});
+});
+
+describe("parseParameters", () => {
+	it("reads the values back", () => {
+		let xml = '<Parameters Version="1"><Parameter Name="Period" Type="Integer">202601</Parameter></Parameters>';
+
+		expect(parseParameters(xml)).toEqual({ Period: "202601" });
+	});
+
+	it("reads an empty value written as a self-closing element", () => {
+		let xml = '<Parameters Version="1"><Parameter Name="Period" Type="Integer" /></Parameters>';
+
+		expect(parseParameters(xml)).toEqual({ Period: "" });
+	});
+
+	it("returns nothing for a filter without parameters", () => {
+		expect(parseParameters(null)).toEqual({});
+	});
+});
+
+describe("restoreParameterValues", () => {
+	it("keeps the defaults for parameters the filter does not mention", () => {
+		let parameters = toReportParameters([
+			record({ Name: "Period", DataType: "Integer", DefaultValue: "202601", SortOrder: 0 }),
+			record({ Name: "Hide0", DataType: "Boolean", DefaultValue: "True", SortOrder: 1 }),
+		]);
+		let xml = '<Parameters Version="1"><Parameter Name="Period" Type="Integer">202512</Parameter></Parameters>';
+
+		expect(restoreParameterValues(parameters, xml)).toEqual({ Period: 202512, Hide0: true });
+	});
+
+	it("ignores parameters the report no longer has", () => {
+		let parameters = toReportParameters([record({ Name: "Period", DataType: "Integer" })]);
+		let xml = '<Parameters Version="1"><Parameter Name="Gone" Type="String">x</Parameter></Parameters>';
+
+		expect(restoreParameterValues(parameters, xml)).toEqual({ Period: null });
+	});
+});

package/src/report/parameters.ts

@@ -0,0 +1,230 @@
+/**
+ * Report parameters: mapping the metadata records onto something renderable,
+ * and the XML the parameter values are stored as on a saved filter.
+ */
+
+import { encodeXml, parseRecordSource, readElement } from "./recordSource.js";
+import type {
+	ReportParameter,
+	ReportParameterEditor,
+	ReportParameterRecord,
+	ReportParameterType,
+	ReportParameterValue,
+	ReportParameterValues,
+} from "./types.js";
+
+const PARAMETER_TYPES: ReportParameterType[] = ["String", "Integer", "Double", "Date", "Boolean"];
+
+/**
+ * A default value naming a stored procedure, e.g. `astp_Reports_CurrentPeriod`.
+ *
+ * The Windows launcher executes the procedure and uses the first column of the
+ * first row. The web client cannot execute an arbitrary procedure, so these are
+ * resolved through the report endpoint instead.
+ */
+const PROCEDURE_DEFAULT = /^[a-z]stp_/i;
+
+/** True when a `DefaultValue` names a stored procedure rather than a literal. */
+export function isProcedureDefault(defaultValue: string | null | undefined): boolean {
+	return typeof defaultValue === "string" && PROCEDURE_DEFAULT.test(defaultValue.trim());
+}
+
+/** The choices of a parameter, one per line of its `Items` column. */
+export function parseParameterItems(items: string | null | undefined): string[] {
+	if (!items) return [];
+
+	return items
+		.split(/\r\n|\r|\n/)
+		.map((item) => item.trim())
+		.filter((item) => item !== "");
+}
+
+function toParameterType(dataType: string | null | undefined): ReportParameterType {
+	let match = PARAMETER_TYPES.find((type) => type.toLowerCase() === dataType?.trim().toLowerCase());
+
+	// The designer only offers the five known types, but an unknown one is still
+	// editable as text.
+	return match ?? "String";
+}
+
+/**
+ * The editor a parameter should use. A lookup or a fixed item list wins over the
+ * data type, which is what the Windows launcher does as well.
+ */
+function toParameterEditor(type: ReportParameterType, hasLookup: boolean, hasItems: boolean): ReportParameterEditor {
+	if (hasLookup) return "lookup";
+	if (hasItems) return "select";
+
+	switch (type) {
+		case "Integer":
+		case "Double":
+			return "number";
+		case "Date":
+			return "date";
+		case "Boolean":
+			return "boolean";
+		default:
+			return "text";
+	}
+}
+
+/** Maps a `sviw_WinClient_ReportsParameters` record onto a `ReportParameter`. */
+export function toReportParameter(record: ReportParameterRecord): ReportParameter {
+	let name = record.Name ?? "";
+	let type = toParameterType(record.DataType);
+	let items = parseParameterItems(record.Items);
+	let recordSource = parseRecordSource(record.RecordSource);
+	let valueMember = record.ValueMember ?? null;
+
+	if (recordSource && !valueMember) {
+		valueMember = recordSource.columns[0]?.name ?? null;
+	}
+
+	/*
+	 * The designer has no display member: the Windows lookup grid shows every
+	 * selected column. On the web a combobox shows one, so the first column that
+	 * is not the value is used.
+	 */
+	let displayMember = recordSource?.columns.find((column) => column.name !== valueMember)?.name ?? null;
+	let hasLookup = Boolean(recordSource && valueMember);
+
+	return {
+		name,
+		label: record.Label?.trim() || name,
+		description: record.Description?.trim() || null,
+		type,
+		editor: toParameterEditor(type, hasLookup, items.length > 0),
+		defaultValue: record.DefaultValue ?? null,
+		items,
+		recordSource: hasLookup ? recordSource : null,
+		valueMember: hasLookup ? valueMember : null,
+		displayMember: hasLookup ? displayMember : null,
+		sortOrder: record.SortOrder ?? 0,
+		lookupWidth: record.LookupWidth ?? null,
+		lookupHeight: record.LookupHeight ?? null,
+	};
+}
+
+/** Maps and sorts a report's parameter records. */
+export function toReportParameters(records: ReportParameterRecord[]): ReportParameter[] {
+	return records
+		.filter((record) => record.Name)
+		.map(toReportParameter)
+		.sort((a, b) => a.sortOrder - b.sortOrder || a.label.localeCompare(b.label));
+}
+
+/** Converts a raw value to the type a parameter expects. */
+export function coerceParameterValue(
+	parameter: ReportParameter,
+	value: ReportParameterValue | undefined,
+): ReportParameterValue {
+	if (value === null || value === undefined || value === "") {
+		return parameter.type === "Boolean" ? false : null;
+	}
+
+	switch (parameter.type) {
+		case "Boolean":
+			return typeof value === "boolean" ? value : /^(true|1|ja|yes)$/i.test(String(value));
+		case "Integer": {
+			let parsed = Number.parseInt(String(value), 10);
+
+			return Number.isNaN(parsed) ? null : parsed;
+		}
+		case "Double": {
+			// Norwegian keyboards produce a comma, which `Number` does not accept.
+			let parsed = Number(String(value).replace(",", "."));
+
+			return Number.isNaN(parsed) ? null : parsed;
+		}
+		default:
+			return String(value);
+	}
+}
+
+/**
+ * The initial values for a set of parameters.
+ *
+ * Defaults naming a stored procedure are left unset: they have to be resolved
+ * server-side, and the caller fills them in once they are.
+ */
+export function getDefaultParameterValues(parameters: ReportParameter[]): ReportParameterValues {
+	let values: ReportParameterValues = {};
+
+	for (let parameter of parameters) {
+		values[parameter.name] = isProcedureDefault(parameter.defaultValue)
+			? coerceParameterValue(parameter, null)
+			: coerceParameterValue(parameter, parameter.defaultValue);
+	}
+
+	return values;
+}
+
+function toXmlValue(parameter: ReportParameter, value: ReportParameterValue): string {
+	if (value === null || value === undefined) return "";
+	// The Windows client writes booleans the way .NET does.
+	if (typeof value === "boolean") return value ? "True" : "False";
+
+	return String(value);
+}
+
+/**
+ * Serializes parameter values the way the Windows filter builder does, so that
+ * a filter saved on the web is readable in the Windows client and the other way
+ * around.
+ *
+ * ```xml
+ * <Parameters Version="1">
+ *   <Parameter Name="Period" Type="Integer">202601</Parameter>
+ * </Parameters>
+ * ```
+ */
+export function serializeParameters(parameters: ReportParameter[], values: ReportParameterValues): string {
+	let entries = parameters.map((parameter) => {
+		let value = toXmlValue(parameter, values[parameter.name] ?? null);
+
+		return `  <Parameter Name="${encodeXml(parameter.name)}" Type="${parameter.type}">${encodeXml(value)}</Parameter>`;
+	});
+
+	return `<Parameters Version="1">\n${entries.join("\n")}\n</Parameters>`;
+}
+
+/**
+ * Reads the values back out of the XML stored on a saved filter. Values are
+ * returned as strings and coerced against the report's own parameters by
+ * `restoreParameterValues`, since the XML may name parameters the report no
+ * longer has.
+ */
+export function parseParameters(xml: string | null | undefined): Record<string, string> {
+	if (!xml) return {};
+
+	let values: Record<string, string> = {};
+
+	for (let match of xml.matchAll(/<Parameter\s+([^>]*?)\/?>(?:([\s\S]*?)<\/Parameter>)?/g)) {
+		let name = /Name\s*=\s*"([^"]*)"/.exec(match[1])?.[1];
+		if (!name) continue;
+
+		values[name] = readElement(match[0], "Parameter") ?? "";
+	}
+
+	return values;
+}
+
+/**
+ * Applies the values stored on a saved filter to a report's parameters, keeping
+ * the defaults for anything the filter does not mention.
+ */
+export function restoreParameterValues(
+	parameters: ReportParameter[],
+	xml: string | null | undefined,
+): ReportParameterValues {
+	let stored = parseParameters(xml);
+	let values = getDefaultParameterValues(parameters);
+
+	for (let parameter of parameters) {
+		if (parameter.name in stored) {
+			values[parameter.name] = coerceParameterValue(parameter, stored[parameter.name]);
+		}
+	}
+
+	return values;
+}

package/src/report/recordSource.ts

@@ -0,0 +1,123 @@
+/**
+ * Reading the `afRecordSource` XML the Windows designer stores on reports and
+ * on report parameters.
+ *
+ * A record source is a serialized .NET object, so the document is machine
+ * generated and its shape is fixed. Only a handful of elements matter here, and
+ * parsing them with a reader rather than `DOMParser` keeps this module usable
+ * outside a browser.
+ */
+
+import type { ReportRecordSource, ReportRecordSourceColumn } from "./types.js";
+
+const XML_ENTITIES: Record<string, string> = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: '"',
+	apos: "'",
+};
+
+/** Resolves the XML entities the .NET serializer emits. */
+export function decodeXml(value: string) {
+	return value.replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, (match, entity: string) => {
+		if (entity.startsWith("#x") || entity.startsWith("#X")) {
+			return String.fromCodePoint(Number.parseInt(entity.slice(2), 16));
+		}
+
+		if (entity.startsWith("#")) {
+			return String.fromCodePoint(Number.parseInt(entity.slice(1), 10));
+		}
+
+		return XML_ENTITIES[entity.toLowerCase()] ?? match;
+	});
+}
+
+/** Escapes a value for use as XML text or as an attribute value. */
+export function encodeXml(value: string) {
+	return value
+		.replace(/&/g, "&amp;")
+		.replace(/</g, "&lt;")
+		.replace(/>/g, "&gt;")
+		.replace(/"/g, "&quot;")
+		.replace(/'/g, "&apos;");
+}
+
+/**
+ * The text content of the first `<name>` element, or `null` when the element is
+ * missing or self-closing (`<FilterString />`, which the serializer writes for
+ * an empty value).
+ */
+export function readElement(xml: string, name: string): string | null {
+	let match = new RegExp(`<${name}(?:\\s[^>]*)?>([\\s\\S]*?)</${name}>`).exec(xml);
+
+	if (!match) return null;
+
+	let value = decodeXml(match[1]).trim();
+
+	return value === "" ? null : value;
+}
+
+/** The text content of every `<name>` element, in document order. */
+export function readElements(xml: string, name: string): string[] {
+	let matches = xml.matchAll(new RegExp(`<${name}(?:\\s[^>]*)?>([\\s\\S]*?)</${name}>`, "g"));
+
+	return [...matches].map((match) => decodeXml(match[1]).trim());
+}
+
+/**
+ * The CLR types the designer writes on a select column. Anything else — and a
+ * column with no `DataType` at all, which is what it writes for strings — is
+ * treated as text.
+ */
+const COLUMN_TYPES: Record<string, ReportRecordSourceColumn["type"]> = {
+	Byte: "number",
+	Decimal: "number",
+	Double: "number",
+	Int16: "number",
+	Int32: "number",
+	Int64: "number",
+	Single: "number",
+	Boolean: "boolean",
+	DateTime: "date",
+};
+
+/** The columns of a `<SelectColumns>` block, in document order. */
+function readSelectColumns(xml: string): ReportRecordSourceColumn[] {
+	let block = /<SelectColumns>([\s\S]*?)<\/SelectColumns>/.exec(xml)?.[1] ?? "";
+	let columns: ReportRecordSourceColumn[] = [];
+
+	for (let match of block.matchAll(/<afSelectColumn>([\s\S]*?)<\/afSelectColumn>/g)) {
+		let name = readElement(match[1], "Name");
+		if (!name) continue;
+
+		columns.push({ name, type: COLUMN_TYPES[readElement(match[1], "DataType") ?? ""] ?? "string" });
+	}
+
+	return columns;
+}
+
+/**
+ * Reads the parts of an `afRecordSource` a web client can act on: the view, the
+ * selected columns and the design-time filter.
+ *
+ * Returns `null` for anything that is not a record source, so a missing or
+ * empty `RecordSource` column simply means "no lookup".
+ */
+export function parseRecordSource(xml: string | null | undefined): ReportRecordSource | null {
+	if (!xml || !xml.includes("<afRecordSource")) return null;
+
+	let viewName = readElement(xml, "ViewName");
+	if (!viewName) return null;
+
+	let maxRecords = readElement(xml, "MaxRecords");
+
+	return {
+		viewName,
+		columns: readSelectColumns(xml),
+		whereClause: readElement(xml, "WhereClause"),
+		filterString: readElement(xml, "FilterString"),
+		// The designer writes 0 for "no limit"; the web data API spells that -1.
+		maxRecords: maxRecords === null || maxRecords === "0" ? null : Number(maxRecords),
+	};
+}