@olenbetong/appframe-core 2.11.9 → 2.12.0

package/src/report/render.test.ts

@@ -0,0 +1,230 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { fetchParameterDefault, resolveParameterDefaults } from "./parameterDefaults.js";
+import {
+	getReportExtension,
+	getReportFileName,
+	getReportRequest,
+	printReport,
+	type ReportRenderOptions,
+	renderReport,
+} from "./render.js";
+import type { ReportParameter } from "./types.js";
+
+function options(overrides: Partial<ReportRenderOptions> = {}): ReportRenderOptions {
+	return { format: "PDF", reportId: "arpt_Test_Report", timezone: 2, ...overrides };
+}
+
+function parameter(overrides: Partial<ReportParameter> & Pick<ReportParameter, "name">): ReportParameter {
+	return {
+		label: overrides.name,
+		description: null,
+		type: "String",
+		editor: "text",
+		defaultValue: null,
+		items: [],
+		recordSource: null,
+		valueMember: null,
+		displayMember: null,
+		sortOrder: 0,
+		lookupWidth: null,
+		lookupHeight: null,
+		...overrides,
+	};
+}
+
+afterEach(() => {
+	vi.unstubAllGlobals();
+});
+
+// A `Request` needs an absolute URL, which the route paths are resolved into
+// against the document. There is no document in the node test environment.
+beforeEach(() => {
+	vi.stubGlobal("location", { href: "https://stage.example.com/report" });
+});
+
+describe("getReportExtension", () => {
+	it("uses the extensions the route accepts, not the format names", () => {
+		expect(getReportExtension("TEXT")).toBe("txt");
+		expect(getReportExtension("IMAGE")).toBe("xbm");
+		expect(getReportExtension("XLSX")).toBe("xlsx");
+	});
+});
+
+describe("getReportFileName", () => {
+	it("defaults to the report id", () => {
+		expect(getReportFileName(options())).toBe("arpt_Test_Report.pdf");
+	});
+
+	it("replaces characters that would change the route path", () => {
+		expect(getReportFileName(options({ fileName: "Ordre 12/34?a.b" }))).toBe("Ordre 12-34-a-b.pdf");
+	});
+
+	it("falls back to the report id when nothing usable is left", () => {
+		expect(getReportFileName(options({ fileName: "..." }))).toBe("arpt_Test_Report.pdf");
+	});
+});
+
+describe("getReportRequest", () => {
+	it("is a GET with the filter in the query when there is nothing to post", () => {
+		let request = getReportRequest(options({ filter: "[ID] = 1" }));
+
+		expect(request.method).toBe("GET");
+		expect(request.url).toContain("/api/report/arpt_Test_Report/arpt_Test_Report.pdf");
+		expect(new URL(request.url, "http://x").searchParams.get("Filter")).toBe("[ID] = 1");
+	});
+
+	it("posts parameters as name/value entries, dropping empty ones", async () => {
+		let request = getReportRequest(options({ filter: "[ID] = 1", parameters: { A: 1, B: "", C: null, D: true } }));
+
+		expect(request.method).toBe("POST");
+		await expect(request.json()).resolves.toEqual({
+			filter: "[ID] = 1",
+			parameters: [
+				{ name: "A", value: 1 },
+				{ name: "D", value: "true" },
+			],
+		});
+	});
+
+	it("always sends a filter alongside parameters, because the route reads it unguarded", async () => {
+		let request = getReportRequest(options({ parameters: { A: 1 } }));
+
+		await expect(request.json()).resolves.toMatchObject({ filter: "" });
+	});
+
+	it("sends the header and maps hideFilterString onto the route's misnamed key", async () => {
+		let request = getReportRequest(options({ headerText: "Q1", hideFilterString: true }));
+
+		await expect(request.json()).resolves.toMatchObject({
+			optionalheader: "Q1",
+			showfiltercriteria: "true",
+		});
+	});
+
+	it("passes the domain and timezone in the query", () => {
+		let params = new URL(getReportRequest(options({ domain: "OB" })).url, "http://x").searchParams;
+
+		expect(params.get("Domain")).toBe("OB");
+		expect(params.get("timezone")).toBe("2");
+	});
+});
+
+describe("renderReport", () => {
+	it("turns the route's JSON error body into an error", async () => {
+		vi.stubGlobal(
+			"fetch",
+			vi.fn().mockResolvedValue(
+				new Response(JSON.stringify({ error: "No permissions" }), {
+					headers: { "Content-Type": "application/json" },
+				}),
+			),
+		);
+
+		await expect(renderReport(options())).rejects.toThrow("No permissions");
+	});
+
+	it("resolves with the rendered file", async () => {
+		vi.stubGlobal(
+			"fetch",
+			vi.fn().mockResolvedValue(new Response("%PDF-", { headers: { "Content-Type": "application/pdf" } })),
+		);
+
+		await expect(renderReport(options())).resolves.toBeInstanceOf(Blob);
+	});
+});
+
+describe("printReport", () => {
+	it("opens the report when there is no document to print it in", async () => {
+		let openMock = vi.fn().mockReturnValue({});
+		vi.stubGlobal(
+			"fetch",
+			vi.fn().mockResolvedValue(new Response("%PDF-", { headers: { "Content-Type": "application/pdf" } })),
+		);
+		vi.stubGlobal("open", openMock);
+
+		await printReport(options());
+
+		expect(openMock).toHaveBeenCalledWith(expect.stringContaining("blob:"), "_blank", "noopener");
+	});
+});
+
+describe("fetchParameterDefault", () => {
+	it("ignores a literal default", async () => {
+		let fetchMock = vi.fn();
+		vi.stubGlobal("fetch", fetchMock);
+
+		await expect(fetchParameterDefault("r", parameter({ name: "P", defaultValue: "201701" }))).resolves.toBeNull();
+		expect(fetchMock).not.toHaveBeenCalled();
+	});
+
+	it("reads the first column of the first row of the result set", async () => {
+		vi.stubGlobal(
+			"fetch",
+			vi.fn().mockResolvedValue(
+				new Response(JSON.stringify({ Table: [{ Period: 202601, Other: 1 }] }), {
+					headers: { "Content-Type": "application/json" },
+				}),
+			),
+		);
+
+		await expect(
+			fetchParameterDefault("r", parameter({ name: "P", defaultValue: "astp_Test_DefaultPeriod" })),
+		).resolves.toBe(202601);
+	});
+
+	it("handles a result set of arrays", async () => {
+		vi.stubGlobal(
+			"fetch",
+			vi
+				.fn()
+				.mockResolvedValue(
+					new Response(JSON.stringify([[202601]]), { headers: { "Content-Type": "application/json" } }),
+				),
+		);
+
+		await expect(
+			fetchParameterDefault("r", parameter({ name: "P", defaultValue: "astp_Test_DefaultPeriod" })),
+		).resolves.toBe(202601);
+	});
+});
+
+describe("resolveParameterDefaults", () => {
+	it("returns the literal defaults untouched when nothing is dynamic", async () => {
+		let fetchMock = vi.fn();
+		vi.stubGlobal("fetch", fetchMock);
+		let literal = { P: 1 };
+
+		await expect(resolveParameterDefaults("r", [parameter({ name: "P", defaultValue: "1" })], literal)).resolves.toBe(
+			literal,
+		);
+		expect(fetchMock).not.toHaveBeenCalled();
+	});
+
+	it("merges resolved values over the literal defaults", async () => {
+		vi.stubGlobal(
+			"fetch",
+			vi.fn().mockResolvedValue(
+				new Response(JSON.stringify({ Table: [{ Value: 202601 }] }), {
+					headers: { "Content-Type": "application/json" },
+				}),
+			),
+		);
+
+		await expect(
+			resolveParameterDefaults(
+				"r",
+				[parameter({ name: "Period", defaultValue: "astp_Test_DefaultPeriod" }), parameter({ name: "Other" })],
+				{ Other: "x" },
+			),
+		).resolves.toEqual({ Other: "x", Period: 202601 });
+	});
+
+	it("leaves a parameter alone when its procedure fails", async () => {
+		vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("boom")));
+
+		await expect(
+			resolveParameterDefaults("r", [parameter({ name: "Period", defaultValue: "astp_Test_DefaultPeriod" })], {}),
+		).resolves.toEqual({});
+	});
+});

package/src/report/render.ts

@@ -0,0 +1,269 @@
+/**
+ * Rendering a report through the framework's report route.
+ *
+ * The route is a CMS code module owned by the Appframe framework
+ * (`WebsiteCMS.Reports`), registered on
+ * `api/report/{ReportID}/{FileName}.{Extension}`. Everything here builds
+ * requests for it — there is no report endpoint of our own.
+ */
+
+import { downloadRequest, type DownloadItem } from "../downloadRequest.js";
+import type { ReportFormat, ReportParameterValues } from "./types.js";
+
+/**
+ * The file extension each format is requested with. The route only accepts
+ * `(pdf|csv|xlsx?|html|xbm|mht|rtf|txt)`, which is why `TEXT` is `txt` and
+ * `IMAGE` is `xbm` rather than the format name.
+ */
+const REPORT_EXTENSIONS: Record<ReportFormat, string> = {
+	CSV: "csv",
+	HTML: "html",
+	IMAGE: "xbm",
+	MHT: "mht",
+	PDF: "pdf",
+	RTF: "rtf",
+	TEXT: "txt",
+	XLS: "xls",
+	XLSX: "xlsx",
+};
+
+/** The media type each format is served as, for previewing a rendered report. */
+const REPORT_MEDIA_TYPES: Record<ReportFormat, string> = {
+	CSV: "text/csv",
+	HTML: "text/html",
+	IMAGE: "image/x-xbitmap",
+	MHT: "message/rfc822",
+	PDF: "application/pdf",
+	RTF: "text/enriched",
+	TEXT: "text/plain",
+	XLS: "application/vnd.ms-excel",
+	XLSX: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+};
+
+export type ReportRenderOptions = {
+	reportId: string;
+	format: ReportFormat;
+	/** File name without an extension. Defaults to the report ID. */
+	fileName?: string;
+	/** The filter string the report is run with. */
+	filter?: string | null;
+	/** Parameter values by name. Only non-empty values are sent. */
+	parameters?: ReportParameterValues | null;
+	/** Text for the report's optional header band. */
+	headerText?: string | null;
+	/** Hides the filter string printed on the report. */
+	hideFilterString?: boolean;
+	/** Runs the report in another domain than the current one. */
+	domain?: string | null;
+	/** Timezone offset in hours or minutes. Defaults to the browser's. */
+	timezone?: number | null;
+	signal?: AbortSignal;
+};
+
+/** The extension a format is requested with. */
+export function getReportExtension(format: ReportFormat): string {
+	return REPORT_EXTENSIONS[format];
+}
+
+/** The media type a format is served as. */
+export function getReportMediaType(format: ReportFormat): string {
+	return REPORT_MEDIA_TYPES[format];
+}
+
+/**
+ * Characters that must not reach the file name, because it is a path segment of
+ * the route: separators, the extension delimiter, the query and fragment
+ * delimiters, and control characters.
+ */
+// oxlint-disable-next-line no-control-regex -- control characters are the point
+const UNSAFE_FILE_NAME_CHARACTERS = /[\\/:*?"<>|.#&+%\u0000-\u001f]/g;
+
+/**
+ * The name a rendered report is downloaded as, including its extension.
+ *
+ * The file name is part of the route rather than a query parameter, so anything
+ * that would change the path is replaced.
+ */
+export function getReportFileName(options: Pick<ReportRenderOptions, "reportId" | "format" | "fileName">): string {
+	let name = (options.fileName ?? options.reportId).trim();
+	let safe = name.replace(UNSAFE_FILE_NAME_CHARACTERS, "-").replace(/-{2,}/g, "-").replace(/^-|-$/g, "").trim();
+
+	return `${safe === "" ? options.reportId : safe}.${getReportExtension(options.format)}`;
+}
+
+/**
+ * The route is always on the same origin, but a `Request` needs an absolute
+ * URL, so the path is resolved against the document when there is one.
+ */
+function toRequestUrl(path: string): string {
+	let base = globalThis.location?.href;
+
+	return base ? new URL(path, base).toString() : path;
+}
+
+/**
+ * The request that renders a report.
+ *
+ * A report without parameters is a plain `GET`, so it can be opened directly in
+ * a new tab. As soon as there are parameters or a header the options go in a
+ * JSON body, which the route only reads from a `POST`.
+ *
+ * `filter` is always sent alongside `parameters`: the route reads the filter out
+ * of the body *guarded by the presence of `parameters`*, and reads it with an
+ * indexer that throws when the key is missing.
+ */
+export function getReportRequest(options: ReportRenderOptions): Request {
+	let { domain, filter, headerText, hideFilterString, parameters, reportId, signal, timezone } = options;
+	let fileName = getReportFileName(options);
+	let url = `/api/report/${encodeURIComponent(reportId)}/${encodeURIComponent(fileName)}`;
+	let query = new URLSearchParams();
+	let entries = toParameterEntries(parameters);
+	let needsBody = entries.length > 0 || Boolean(headerText) || hideFilterString === true;
+
+	if (domain) query.set("Domain", domain);
+	query.set("timezone", String(timezone ?? -new Date().getTimezoneOffset() / 60));
+
+	if (!needsBody) {
+		if (filter) query.set("Filter", filter);
+
+		return new Request(toRequestUrl(`${url}?${query}`), { credentials: "same-origin", signal });
+	}
+
+	let body: Record<string, unknown> = {
+		filter: filter ?? "",
+		parameters: entries,
+	};
+
+	if (headerText) body.optionalheader = headerText;
+	// The route assigns `showfiltercriteria` straight to the report's
+	// `HideFilterString`, so despite its name it *hides* the filter string.
+	if (hideFilterString === true) body.showfiltercriteria = "true";
+
+	return new Request(toRequestUrl(`${url}?${query}`), {
+		body: JSON.stringify(body),
+		credentials: "same-origin",
+		headers: { "Content-Type": "application/json", "X-Requested-With": "XMLHttpRequest" },
+		method: "POST",
+		signal,
+	});
+}
+
+/**
+ * Renders a report and resolves with the rendered file.
+ *
+ * The route answers with a JSON body carrying an `error` when rendering fails,
+ * rather than with a failing status, so a JSON response is turned into an error
+ * here.
+ */
+export async function renderReport(options: ReportRenderOptions): Promise<Blob> {
+	let response = await fetch(getReportRequest(options));
+	let contentType = response.headers.get("content-type") ?? "";
+
+	if (contentType.includes("application/json")) {
+		let data = (await response.json()) as { error?: string };
+
+		throw new Error(data.error ?? "Failed to render report");
+	}
+
+	if (!response.ok) throw new Error(`${response.status} ${response.statusText}`);
+
+	return response.blob();
+}
+
+/** Renders a report and saves it, reporting progress as it downloads. */
+export function downloadReport(
+	options: ReportRenderOptions & { onProgress?: (progress: DownloadItem) => void },
+): Promise<void> {
+	return downloadRequest(getReportRequest(options), {
+		fileName: getReportFileName(options),
+		onProgress: options.onProgress,
+		signal: options.signal,
+	});
+}
+
+/**
+ * Renders a report and opens it in a new tab.
+ *
+ * The blob is rendered first rather than pointing a tab at the route, so a
+ * failure surfaces as an error here instead of as a tab showing JSON, and so
+ * reports with parameters — which have to be posted — can be previewed too.
+ */
+export async function openReport(options: ReportRenderOptions): Promise<void> {
+	let blob = await renderReport(options);
+	// The route serves some formats as types a browser downloads rather than
+	// displays; the format's own media type is what decides how it opens.
+	let url = URL.createObjectURL(blob.type ? blob : new Blob([blob], { type: getReportMediaType(options.format) }));
+	let opened = globalThis.open(url, "_blank", "noopener");
+
+	if (!opened) {
+		URL.revokeObjectURL(url);
+		throw new Error("The report could not be opened. Allow pop-ups for this site and try again.");
+	}
+
+	// Revoking immediately would cancel the load in some browsers, and never
+	// revoking keeps the whole rendered report in memory.
+	globalThis.setTimeout(() => URL.revokeObjectURL(url), 60_000);
+}
+
+/**
+ * Renders a report and opens the browser's print dialog for it.
+ *
+ * The report is loaded into an offscreen iframe rather than a new tab, so the
+ * print dialog opens over the launcher and the user is not left with a stray
+ * tab afterwards. Browsers that will not print an embedded document fall back
+ * to opening it, which leaves the user one keystroke from printing.
+ */
+export async function printReport(options: ReportRenderOptions): Promise<void> {
+	let document_ = globalThis.document;
+	if (!document_?.body) return openReport(options);
+
+	let blob = await renderReport(options);
+	let url = URL.createObjectURL(blob.type ? blob : new Blob([blob], { type: getReportMediaType(options.format) }));
+	let frame = document_.createElement("iframe");
+	// Hidden with `visibility` rather than `display: none`: a frame that is not
+	// laid out has nothing to print in some browsers.
+	frame.setAttribute("aria-hidden", "true");
+	frame.style.cssText =
+		"position:fixed;inset-block-start:0;inset-inline-start:0;inline-size:1px;block-size:1px;border:0;visibility:hidden";
+
+	let cleanUp = () => {
+		frame.remove();
+		URL.revokeObjectURL(url);
+	};
+
+	try {
+		await new Promise<void>((resolve, reject) => {
+			frame.addEventListener("load", () => resolve(), { once: true });
+			frame.addEventListener("error", () => reject(new Error("The report could not be loaded for printing")), {
+				once: true,
+			});
+			frame.src = url;
+			document_.body.append(frame);
+		});
+
+		frame.contentWindow?.focus();
+		frame.contentWindow?.print();
+	} catch {
+		cleanUp();
+
+		return openReport(options);
+	}
+
+	// The print dialog is modal but not awaitable, and revoking the URL or
+	// removing the frame while it is open cancels the job.
+	globalThis.setTimeout(cleanUp, 60_000);
+}
+
+/**
+ * Parameters in the shape the route expects — `{ name, value }` objects.
+ *
+ * Empty values are dropped: the route skips them anyway, and a report falls back
+ * to its own default when a parameter is not sent.
+ */
+function toParameterEntries(parameters: ReportParameterValues | null | undefined) {
+	if (!parameters) return [];
+
+	return Object.entries(parameters)
+		.filter(([, value]) => value !== null && value !== undefined && value !== "")
+		.map(([name, value]) => ({ name, value: typeof value === "boolean" ? String(value) : value }));
+}

package/src/report/report.test.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from "vitest";
+
+import { parseRecordSource } from "./recordSource.js";
+import { getReportFormats, toReport } from "./report.js";
+
+const recordSource = `<?xml version="1.0" encoding="utf-16"?>
+<afRecordSource>
+  <ViewName>aviw_Personnel_PersonsReportingToMe</ViewName>
+  <SelectColumns>
+    <afSelectColumn><Name>PersonID</Name></afSelectColumn>
+    <afSelectColumn><Name>Name</Name></afSelectColumn>
+  </SelectColumns>
+  <WhereClause />
+  <FilterString>[Level] = 1</FilterString>
+  <MaxRecords>0</MaxRecords>
+</afRecordSource>`;
+
+describe("parseRecordSource", () => {
+	it("reads the view, columns and design-time filter", () => {
+		expect(parseRecordSource(recordSource)).toEqual({
+			viewName: "aviw_Personnel_PersonsReportingToMe",
+			columns: [
+				{ name: "PersonID", type: "string" },
+				{ name: "Name", type: "string" },
+			],
+			whereClause: null,
+			filterString: "[Level] = 1",
+			maxRecords: null,
+		});
+	});
+
+	it("maps the CLR type of a column onto a field type", () => {
+		let xml = recordSource.replace(
+			"<afSelectColumn><Name>Name</Name></afSelectColumn>",
+			"<afSelectColumn><Name>Level</Name><DataType>Int32</DataType></afSelectColumn>",
+		);
+
+		expect(parseRecordSource(xml)?.columns).toEqual([
+			{ name: "PersonID", type: "string" },
+			{ name: "Level", type: "number" },
+		]);
+	});
+
+	it("decodes entities", () => {
+		let xml = recordSource.replace("[Level] = 1", "[Name] Like &apos;%a &amp; b%&apos;");
+
+		expect(parseRecordSource(xml)?.filterString).toBe("[Name] Like '%a & b%'");
+	});
+
+	it("returns nothing for anything that is not a record source", () => {
+		expect(parseRecordSource(null)).toBeNull();
+		expect(parseRecordSource("")).toBeNull();
+		expect(parseRecordSource("<afRecordSource></afRecordSource>")).toBeNull();
+	});
+});
+
+describe("getReportFormats", () => {
+	it("offers the spreadsheet formats from the CSV flag", () => {
+		expect(getReportFormats({ FormatPDF: true, FormatCSV: true })).toEqual(["PDF", "XLSX", "XLS", "CSV"]);
+	});
+
+	it("accepts bits as numbers", () => {
+		expect(getReportFormats({ FormatPDF: 1, FormatHTML: 0 })).toEqual(["PDF"]);
+	});
+
+	it("offers nothing for a report with no formats", () => {
+		expect(getReportFormats({})).toEqual([]);
+	});
+});
+
+describe("toReport", () => {
+	it("resolves the view and the initial filter from the record source", () => {
+		let report = toReport({
+			ReportID: "arpt_Personnel_Persons",
+			ShortID: 1234,
+			Title: "  Persons  ",
+			RecordSource: recordSource,
+			FormatPDF: true,
+			HasTitle: 1,
+			HasHeader: 0,
+		});
+
+		expect(report).toEqual({
+			reportId: "arpt_Personnel_Persons",
+			shortId: 1234,
+			title: "Persons",
+			description: null,
+			viewName: "aviw_Personnel_PersonsReportingToMe",
+			initialFilter: "[Level] = 1",
+			hasTitle: true,
+			hasHeader: false,
+			formats: ["PDF"],
+			timeout: null,
+		});
+	});
+
+	it("survives a report without a record source", () => {
+		let report = toReport({ ReportID: "arpt_Test" });
+
+		expect(report.viewName).toBeNull();
+		expect(report.initialFilter).toBeNull();
+		expect(report.shortId).toBeNull();
+	});
+});

package/src/report/report.ts

@@ -0,0 +1,51 @@
+/**
+ * Mapping a `sviw_WinClient_MyReports` record onto the report model, including
+ * which output formats the report offers.
+ */
+
+import { parseRecordSource } from "./recordSource.js";
+import type { Report, ReportFormat, ReportRecord } from "./types.js";
+
+function isSet(value: boolean | number | null | undefined) {
+	return value === true || value === 1;
+}
+
+/**
+ * The formats a report may be rendered to, in the order the launcher offers
+ * them.
+ *
+ * `FormatCSV` covers the whole spreadsheet family: the Windows launcher enables
+ * "save as XLS" and "save as XLSX" from the same flag, because they all come out
+ * of the same DevExpress export.
+ */
+export function getReportFormats(record: ReportRecord): ReportFormat[] {
+	let formats: ReportFormat[] = [];
+
+	if (isSet(record.FormatPDF)) formats.push("PDF");
+	if (isSet(record.FormatCSV)) formats.push("XLSX", "XLS", "CSV");
+	if (isSet(record.FormatHTML)) formats.push("HTML");
+	if (isSet(record.FormatRTF)) formats.push("RTF");
+	if (isSet(record.FormatMHT)) formats.push("MHT");
+	if (isSet(record.FormatTEXT)) formats.push("TEXT");
+	if (isSet(record.FormatIMAGE)) formats.push("IMAGE");
+
+	return formats;
+}
+
+/** Maps a report record onto the model the launcher renders. */
+export function toReport(record: ReportRecord): Report {
+	let recordSource = parseRecordSource(record.RecordSource);
+
+	return {
+		reportId: record.ReportID ?? "",
+		shortId: record.ShortID ?? null,
+		title: record.Title?.trim() || null,
+		description: record.Description?.trim() || null,
+		viewName: recordSource?.viewName ?? null,
+		initialFilter: recordSource?.filterString ?? null,
+		hasTitle: isSet(record.HasTitle),
+		hasHeader: isSet(record.HasHeader),
+		formats: getReportFormats(record),
+		timeout: record.Timeout ?? null,
+	};
+}