@olenbetong/appframe-core 2.11.10 → 2.12.0

package/src/index.ts

@@ -13,6 +13,7 @@ export { downloadBlob } from "./downloadBlob.js";
 export type { DownloadItem, DownloadParameters } from "./downloadRequest.js";
 export { downloadRequest } from "./downloadRequest.js";
 export { expose } from "./expose.js";
+export * from "./filter/index.js";
 export { getLocalizedString } from "./getLocalizedString.js";
 export type { getUserImageOptions } from "./getUserImage.js";
 export { getUserImage } from "./getUserImage.js";
@@ -20,13 +21,14 @@ export { invariant } from "./invariant.js";
 export { localize } from "./localize.js";
 export { afLocalStorage as localStorage };
 export { getSessionData, logActivity, logError, startActivity, time } from "./log.js";
+export * from "./report/index.js";
 export { default as SessionHandler } from "./SessionHandler.js";
 export { UserSession };
 export type { AlertDialogButton, AlertDialogOptions, AlertOptions, ConfirmOptions } from "./alert.js";
 export { alert, ConfirmButtons, confirm, openAlertDialog, waitForDialog } from "./alert.js";
 export { getSettings, saveSettings } from "./settings.js";
 
-// biome-ignore lint/correctness/noInvalidUseBeforeDeclaration: this is injected build time
+// oxlint-disable-next-line no-use-before-define -- this is injected build time
 export const version = __VERSION__;
 
 declare global {

package/src/parseFunc.test.ts

@@ -8,11 +8,10 @@ function testFunction(arg1: string, arg2: string) {
 
 describe("parseFunc", () => {
 	test("should parse function", () => {
-		expect(parseFunc(testFunction)).toEqual({
-			name: "testFunction",
-			args: ["arg1", "arg2"],
-			body: "\n  console.log(arg1, arg2);\n",
-		});
+		const result = parseFunc(testFunction);
+		expect(result.name).toBe("testFunction");
+		expect(result.args).toEqual(["arg1", "arg2"]);
+		expect(result.body.trim()).toBe("console.log(arg1, arg2);");
 	});
 
 	test("should parse arrow function returning object literal", () => {
@@ -57,7 +56,7 @@ describe("parseFunc", () => {
 		expect(result.args).toEqual(["x", "y"]);
 		expect(result.body.trim()).toBe("return x * y;");
 
-		// biome-ignore lint/complexity/useArrowFunction: that would defeat the purpose of the test
+		// oxlint-disable-next-line prefer-arrow-callback -- that would defeat the purpose of the test
 		const secondResult = parseFunc(function (x, y) {
 			return x * y;
 		});

package/src/report/index.ts

@@ -0,0 +1,37 @@
+export { fetchParameterDefault, resolveParameterDefaults } from "./parameterDefaults.js";
+export {
+	coerceParameterValue,
+	getDefaultParameterValues,
+	isProcedureDefault,
+	parseParameterItems,
+	parseParameters,
+	restoreParameterValues,
+	serializeParameters,
+	toReportParameter,
+	toReportParameters,
+} from "./parameters.js";
+export { decodeXml, encodeXml, parseRecordSource, readElement, readElements } from "./recordSource.js";
+export {
+	downloadReport,
+	getReportExtension,
+	getReportFileName,
+	getReportMediaType,
+	getReportRequest,
+	openReport,
+	printReport,
+	renderReport,
+	type ReportRenderOptions,
+} from "./render.js";
+export { getReportFormats, toReport } from "./report.js";
+export type {
+	Report,
+	ReportFormat,
+	ReportParameter,
+	ReportParameterEditor,
+	ReportParameterRecord,
+	ReportParameterType,
+	ReportParameterValue,
+	ReportParameterValues,
+	ReportRecord,
+	ReportRecordSource,
+} from "./types.js";

package/src/report/parameterDefaults.ts

@@ -0,0 +1,101 @@
+/**
+ * Resolving report parameter defaults that name a stored procedure.
+ *
+ * A `DefaultValue` matching `^[a-z]stp_` names a procedure that produces the
+ * default rather than being the default itself. Executing it is a server
+ * concern, and the framework already exposes it through the `WebsiteCMS`
+ * `api/reporting/filters` route.
+ */
+
+import { isProcedureDefault } from "./parameters.js";
+import type { ReportParameter, ReportParameterValue, ReportParameterValues } from "./types.js";
+
+/** A result set as the reporting route serializes it. */
+type ProcedureResult = Record<string, unknown[]> | unknown[];
+
+/**
+ * Runs the stored procedure a parameter's default names and returns the value
+ * it produces — the first column of the first row, the way the Windows launcher
+ * reads it.
+ *
+ * Returns `null` when the parameter has no procedure default or the procedure
+ * produced no rows.
+ */
+export async function fetchParameterDefault(
+	reportId: string,
+	parameter: ReportParameter,
+	signal?: AbortSignal,
+): Promise<ReportParameterValue> {
+	if (!parameter.defaultValue || !isProcedureDefault(parameter.defaultValue)) return null;
+
+	let response = await fetch(`/api/reporting/filters/${encodeURIComponent(reportId)}/GetParameterDefaultValue`, {
+		body: JSON.stringify({ parameterName: parameter.name }),
+		credentials: "same-origin",
+		headers: {
+			"Content-Type": "application/json",
+			// The route rejects anything that is not an ajax request, as CSRF
+			// protection.
+			"X-Requested-With": "XMLHttpRequest",
+		},
+		method: "POST",
+		signal,
+	});
+
+	if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
+
+	let result = (await response.json()) as ProcedureResult;
+
+	return firstValue(result);
+}
+
+/**
+ * Resolves every procedure default of a report in parallel and merges the
+ * results over the literal defaults.
+ *
+ * A parameter whose procedure fails is left at its literal default rather than
+ * failing the whole form — the user can still type a value.
+ */
+export async function resolveParameterDefaults(
+	reportId: string,
+	parameters: ReportParameter[],
+	literalDefaults: ReportParameterValues,
+	signal?: AbortSignal,
+): Promise<ReportParameterValues> {
+	let dynamic = parameters.filter((parameter) => isProcedureDefault(parameter.defaultValue ?? ""));
+
+	if (dynamic.length === 0) return literalDefaults;
+
+	let resolved = await Promise.all(
+		dynamic.map(async (parameter) => {
+			try {
+				return [parameter.name, await fetchParameterDefault(reportId, parameter, signal)] as const;
+			} catch {
+				return [parameter.name, null] as const;
+			}
+		}),
+	);
+
+	let values: ReportParameterValues = { ...literalDefaults };
+
+	for (let [name, value] of resolved) {
+		if (value !== null) values[name] = value;
+	}
+
+	return values;
+}
+
+/** The first column of the first row of whichever result set came back. */
+function firstValue(result: ProcedureResult): ReportParameterValue {
+	let rows = Array.isArray(result) ? result : Object.values(result).find((value) => Array.isArray(value));
+	let row = rows?.[0];
+
+	if (row === undefined || row === null) return null;
+	if (Array.isArray(row)) return (row[0] as ReportParameterValue) ?? null;
+	if (typeof row === "object") {
+		let values = Object.values(row as Record<string, unknown>);
+
+		return (values[0] as ReportParameterValue) ?? null;
+	}
+
+	return row as ReportParameterValue;
+}

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;
+}