@olenbetong/appframe-core 2.11.9 → 2.12.0

package/es/report/parameterDefaults.js

@@ -0,0 +1,77 @@
+/**
+ * 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";
+/**
+ * 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, parameter, signal) {
+    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());
+    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, parameters, literalDefaults, signal) {
+    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)];
+        }
+        catch {
+            return [parameter.name, null];
+        }
+    }));
+    let values = { ...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) {
+    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] ?? null;
+    if (typeof row === "object") {
+        let values = Object.values(row);
+        return values[0] ?? null;
+    }
+    return row;
+}

package/es/report/parameters.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Report parameters: mapping the metadata records onto something renderable,
+ * and the XML the parameter values are stored as on a saved filter.
+ */
+import type { ReportParameter, ReportParameterRecord, ReportParameterValue, ReportParameterValues } from "./types.js";
+/** True when a `DefaultValue` names a stored procedure rather than a literal. */
+export declare function isProcedureDefault(defaultValue: string | null | undefined): boolean;
+/** The choices of a parameter, one per line of its `Items` column. */
+export declare function parseParameterItems(items: string | null | undefined): string[];
+/** Maps a `sviw_WinClient_ReportsParameters` record onto a `ReportParameter`. */
+export declare function toReportParameter(record: ReportParameterRecord): ReportParameter;
+/** Maps and sorts a report's parameter records. */
+export declare function toReportParameters(records: ReportParameterRecord[]): ReportParameter[];
+/** Converts a raw value to the type a parameter expects. */
+export declare function coerceParameterValue(parameter: ReportParameter, value: ReportParameterValue | undefined): ReportParameterValue;
+/**
+ * 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 declare function getDefaultParameterValues(parameters: ReportParameter[]): ReportParameterValues;
+/**
+ * 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 declare function serializeParameters(parameters: ReportParameter[], values: ReportParameterValues): string;
+/**
+ * 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 declare function parseParameters(xml: string | null | undefined): Record<string, string>;
+/**
+ * Applies the values stored on a saved filter to a report's parameters, keeping
+ * the defaults for anything the filter does not mention.
+ */
+export declare function restoreParameterValues(parameters: ReportParameter[], xml: string | null | undefined): ReportParameterValues;

package/es/report/parameters.js

@@ -0,0 +1,188 @@
+/**
+ * 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";
+const PARAMETER_TYPES = ["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) {
+    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) {
+    if (!items)
+        return [];
+    return items
+        .split(/\r\n|\r|\n/)
+        .map((item) => item.trim())
+        .filter((item) => item !== "");
+}
+function toParameterType(dataType) {
+    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, hasLookup, hasItems) {
+    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) {
+    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) {
+    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, value) {
+    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) {
+    let values = {};
+    for (let parameter of parameters) {
+        values[parameter.name] = isProcedureDefault(parameter.defaultValue)
+            ? coerceParameterValue(parameter, null)
+            : coerceParameterValue(parameter, parameter.defaultValue);
+    }
+    return values;
+}
+function toXmlValue(parameter, value) {
+    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, values) {
+    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) {
+    if (!xml)
+        return {};
+    let values = {};
+    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, xml) {
+    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/es/report/parameters.test.d.ts

@@ -0,0 +1 @@
+export {};

package/es/report/parameters.test.js

@@ -0,0 +1,161 @@
+import { describe, expect, it } from "vitest";
+import { coerceParameterValue, getDefaultParameterValues, isProcedureDefault, parseParameterItems, parseParameters, restoreParameterValues, serializeParameters, toReportParameter, toReportParameters, } from "./parameters.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 = {}) {
+    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/es/report/recordSource.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 } from "./types.js";
+/** Resolves the XML entities the .NET serializer emits. */
+export declare function decodeXml(value: string): string;
+/** Escapes a value for use as XML text or as an attribute value. */
+export declare function encodeXml(value: string): string;
+/**
+ * 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 declare function readElement(xml: string, name: string): string | null;
+/** The text content of every `<name>` element, in document order. */
+export declare function readElements(xml: string, name: string): string[];
+/**
+ * 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 declare function parseRecordSource(xml: string | null | undefined): ReportRecordSource | null;

package/es/report/recordSource.js

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+const XML_ENTITIES = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    apos: "'",
+};
+/** Resolves the XML entities the .NET serializer emits. */
+export function decodeXml(value) {
+    return value.replace(/&(#x?[0-9a-f]+|[a-z]+);/gi, (match, entity) => {
+        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) {
+    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, name) {
+    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, name) {
+    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 = {
+    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) {
+    let block = /<SelectColumns>([\s\S]*?)<\/SelectColumns>/.exec(xml)?.[1] ?? "";
+    let columns = [];
+    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) {
+    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),
+    };
+}