@olenbetong/appframe-core 2.11.10 → 2.13.0

package/es/filter/tree.js

@@ -0,0 +1,185 @@
+import { getDefaultOperator, getOperatorArity, getValueType, normalizeOperator } from "./operators.js";
+/**
+ * Creates the default empty filter: a single `and` group with no conditions.
+ */
+export function createEmptyFilter() {
+    return createEmptyGroup("and");
+}
+export function createEmptyGroup(mode = "and") {
+    return { type: "group", mode, items: [] };
+}
+export function isGroup(item) {
+    return item.type === "group";
+}
+export function isExpression(item) {
+    return item.type === "expression";
+}
+/**
+ * Normalizes any filter value into a tree the editor can render, without
+ * changing its structure. An expression is wrapped in a group; a missing filter
+ * becomes the default layout.
+ */
+export function toFilterTree(filter) {
+    if (!filter)
+        return createEmptyFilter();
+    if (isExpression(filter))
+        return { type: "group", mode: "and", items: [filter] };
+    return filter;
+}
+/**
+ * True when the filter contains no expressions. An empty filter must not be
+ * saved or applied.
+ */
+export function isEmptyFilter(filter) {
+    return countExpressions(filter) === 0;
+}
+export function countExpressions(filter) {
+    if (!filter)
+        return 0;
+    if (isExpression(filter))
+        return 1;
+    return filter.items.reduce((total, item) => total + countExpressions(item), 0);
+}
+/**
+ * Removes incomplete expressions and empty groups from the whole tree. Returns
+ * null when nothing is left. Use before applying a filter to a data object so
+ * incomplete rows are not sent.
+ */
+export function pruneFilter(filter) {
+    if (!filter)
+        return null;
+    if (isExpression(filter)) {
+        return isCompleteExpression(filter) ? { type: "group", mode: "and", items: [filter] } : null;
+    }
+    let items = filter.items
+        .map((item) => (isGroup(item) ? pruneFilter(item) : isCompleteExpression(item) ? item : null))
+        .filter((item) => item !== null);
+    if (items.length === 0)
+        return null;
+    return { ...filter, items };
+}
+/**
+ * True when an expression has everything it needs to be sent to the server.
+ */
+export function isCompleteExpression(item) {
+    if (isGroup(item))
+        return item.items.some(isCompleteExpression);
+    if (!item.column || !item.operator)
+        return false;
+    let arity = getOperatorArity(normalizeOperator(item.operator));
+    if (arity === "none")
+        return true;
+    if (item.value === null || item.value === undefined || item.value === "")
+        return false;
+    if (arity === "pair") {
+        return Array.isArray(item.value) && item.value.length === 2 && item.value.every((v) => v !== "" && v != null);
+    }
+    if (arity === "list") {
+        return Array.isArray(item.value) && item.value.length > 0;
+    }
+    return true;
+}
+/**
+ * Creates an expression for a field, using the field's default operator and an
+ * empty value of the right shape.
+ */
+export function createExpression(field, operator) {
+    let op = operator ?? getDefaultOperator(field);
+    return {
+        type: "expression",
+        column: field.name,
+        operator: op,
+        value: createEmptyValue(op),
+        valueType: getValueType(field, op),
+    };
+}
+function createEmptyValue(operator) {
+    switch (getOperatorArity(operator)) {
+        case "none":
+            return null;
+        case "pair":
+            return ["", ""];
+        case "list":
+            return [];
+        default:
+            return "";
+    }
+}
+/**
+ * Returns a copy of the expression with a new operator, adjusting the value to
+ * the new operator's arity and the value type accordingly.
+ */
+export function changeOperator(expression, operator, field) {
+    let previousArity = getOperatorArity(normalizeOperator(expression.operator));
+    let arity = getOperatorArity(operator);
+    let value = expression.value;
+    if (arity !== previousArity) {
+        value = createEmptyValue(operator);
+    }
+    // A dynamic value stays valid across operators of the same arity.
+    let valueType = expression.valueType === "special" && arity === previousArity ? "special" : getValueType(field, operator);
+    return { ...expression, operator, value, valueType };
+}
+/** Returns the node at `path`, or null when the path does not exist. */
+export function getNodeAtPath(filter, path) {
+    let node = filter;
+    for (let index of path) {
+        if (!node || !isGroup(node))
+            return null;
+        node = node.items[index];
+    }
+    return node ?? null;
+}
+/**
+ * Returns a copy of the tree with `updater` applied to the node at `path`.
+ * Returning null removes the node. An unknown path leaves the tree untouched.
+ */
+export function updateNodeAtPath(filter, path, updater) {
+    if (path.length === 0) {
+        return updater(filter) ?? filter;
+    }
+    if (!isGroup(filter))
+        return filter;
+    let [index, ...rest] = path;
+    let child = filter.items[index];
+    if (!child)
+        return filter;
+    let items = [...filter.items];
+    if (rest.length === 0) {
+        let updated = updater(child);
+        if (updated === null) {
+            items.splice(index, 1);
+        }
+        else {
+            items[index] = updated;
+        }
+    }
+    else {
+        items[index] = updateNodeAtPath(child, rest, updater);
+    }
+    return { ...filter, items };
+}
+/** Returns a copy of the tree with `node` appended to the group at `path`. */
+export function insertNodeAtPath(filter, path, node) {
+    return updateNodeAtPath(filter, path, (target) => isGroup(target) ? { ...target, items: [...target.items, node] } : target);
+}
+/**
+ * Returns a copy of the tree with the node at `path` removed. The root is never
+ * removed; it is reset to the default layout instead.
+ */
+export function removeNodeAtPath(filter, path) {
+    if (path.length === 0)
+        return createEmptyFilter();
+    return updateNodeAtPath(filter, path, () => null);
+}
+/** Returns a copy of the tree with the mode of the group at `path` changed. */
+export function setGroupMode(filter, path, mode) {
+    return updateNodeAtPath(filter, path, (node) => (isGroup(node) ? { ...node, mode } : node));
+}
+/** Returns a copy of the tree with an empty group appended to the group at `path`. */
+export function addGroupAtPath(filter, path = []) {
+    let parent = getNodeAtPath(filter, path);
+    // A nested group is only useful when it combines differently to its parent.
+    let mode = parent && isGroup(parent) && parent.mode === "and" ? "or" : "and";
+    return insertNodeAtPath(filter, path, createEmptyGroup(mode));
+}

package/es/filter/tree.test.d.ts

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

package/es/filter/tree.test.js

@@ -0,0 +1,184 @@
+import { describe, expect, test } from "vitest";
+import { addGroupAtPath, changeOperator, countExpressions, createEmptyFilter, createExpression, getNodeAtPath, insertNodeAtPath, isCompleteExpression, isEmptyFilter, pruneFilter, removeNodeAtPath, setGroupMode, toFilterTree, updateNodeAtPath, } from "./tree.js";
+function expression(column, operator = "equals", value = "x") {
+    return { type: "expression", column, operator, value, valueType: "string" };
+}
+function group(mode, ...items) {
+    return { type: "group", mode, items };
+}
+describe("createEmptyFilter", () => {
+    test("creates a single empty and group", () => {
+        expect(createEmptyFilter()).toEqual({ type: "group", mode: "and", items: [] });
+    });
+});
+describe("toFilterTree", () => {
+    test("null becomes the default layout", () => {
+        expect(toFilterTree(null)).toEqual(createEmptyFilter());
+    });
+    test("a bare expression is wrapped in an and group", () => {
+        expect(toFilterTree(expression("Name"))).toEqual(group("and", expression("Name")));
+    });
+    test("nesting is preserved", () => {
+        let nested = group("and", expression("A"), group("or", expression("B"), expression("C")));
+        expect(toFilterTree(nested)).toBe(nested);
+    });
+});
+describe("isEmptyFilter", () => {
+    test("a fresh filter is empty", () => {
+        expect(isEmptyFilter(createEmptyFilter())).toBe(true);
+    });
+    test("null is empty", () => {
+        expect(isEmptyFilter(null)).toBe(true);
+    });
+    test("a filter with an expression is not empty", () => {
+        expect(isEmptyFilter(insertNodeAtPath(createEmptyFilter(), [], expression("A")))).toBe(false);
+    });
+});
+describe("isCompleteExpression", () => {
+    test("parameterless operators need no value", () => {
+        expect(isCompleteExpression(expression("A", "isnull", null))).toBe(true);
+        expect(isCompleteExpression(expression("A", "istrue", null))).toBe(true);
+    });
+    test("a missing column makes the expression incomplete", () => {
+        expect(isCompleteExpression(expression("", "equals", "x"))).toBe(false);
+    });
+    test("an empty value makes the expression incomplete", () => {
+        expect(isCompleteExpression(expression("A", "equals", ""))).toBe(false);
+        expect(isCompleteExpression(expression("A", "equals", null))).toBe(false);
+    });
+    test("between needs both values", () => {
+        expect(isCompleteExpression(expression("A", "between", ["1", "2"]))).toBe(true);
+        expect(isCompleteExpression(expression("A", "between", ["1", ""]))).toBe(false);
+        expect(isCompleteExpression(expression("A", "between", ["1"]))).toBe(false);
+    });
+    test("in list needs at least one value", () => {
+        expect(isCompleteExpression(expression("A", "inlist", ["1"]))).toBe(true);
+        expect(isCompleteExpression(expression("A", "inlist", []))).toBe(false);
+    });
+    test("PascalCase operators are recognised", () => {
+        expect(isCompleteExpression(expression("A", "IsNull", null))).toBe(true);
+    });
+});
+describe("pruneFilter", () => {
+    test("returns null when nothing is complete", () => {
+        let filter = insertNodeAtPath(createEmptyFilter(), [], expression("A", "equals", ""));
+        expect(pruneFilter(filter)).toBeNull();
+    });
+    test("drops incomplete expressions and empty groups", () => {
+        let filter = createEmptyFilter();
+        filter = insertNodeAtPath(filter, [], expression("A"));
+        filter = insertNodeAtPath(filter, [], expression("B", "equals", ""));
+        filter = addGroupAtPath(filter);
+        filter = insertNodeAtPath(filter, [2], expression("C", "equals", ""));
+        let pruned = pruneFilter(filter);
+        expect(pruned?.items).toHaveLength(1);
+        expect(countExpressions(pruned)).toBe(1);
+    });
+    test("keeps complete groups untouched", () => {
+        let filter = insertNodeAtPath(createEmptyFilter(), [], expression("A"));
+        expect(pruneFilter(filter)).toEqual(group("and", expression("A")));
+    });
+    test("prunes nested groups recursively", () => {
+        let filter = group("and", expression("A"), group("or", expression("B", "equals", ""), group("and", expression("C"))));
+        expect(pruneFilter(filter)).toEqual(group("and", expression("A"), group("or", group("and", expression("C")))));
+    });
+});
+describe("createExpression", () => {
+    test("uses the field's default operator and an empty value", () => {
+        expect(createExpression({ name: "Name", type: "string" })).toEqual({
+            type: "expression",
+            column: "Name",
+            operator: "contains",
+            value: "",
+            valueType: "string",
+        });
+    });
+    test("parameterless default operators get a null value", () => {
+        expect(createExpression({ name: "Active", type: "boolean" })).toMatchObject({
+            operator: "istrue",
+            value: null,
+            valueType: "null",
+        });
+    });
+    test("an explicit operator shapes the value", () => {
+        expect(createExpression({ name: "Amount", type: "number" }, "between")).toMatchObject({
+            value: ["", ""],
+            valueType: "number",
+        });
+        expect(createExpression({ name: "Amount", type: "number" }, "inlist")).toMatchObject({ value: [] });
+    });
+});
+describe("changeOperator", () => {
+    test("keeps the value when the arity is unchanged", () => {
+        let result = changeOperator(expression("A", "equals", "abc"), "contains", { type: "string" });
+        expect(result).toMatchObject({ operator: "contains", value: "abc" });
+    });
+    test("resets the value when the arity changes", () => {
+        let result = changeOperator(expression("A", "equals", "abc"), "between", { type: "string" });
+        expect(result.value).toEqual(["", ""]);
+    });
+    test("switching to a parameterless operator clears the value", () => {
+        let result = changeOperator(expression("A", "equals", "abc"), "isnull", { type: "string" });
+        expect(result).toMatchObject({ value: null, valueType: "null" });
+    });
+    test("a dynamic value survives a same-arity operator change", () => {
+        let dynamic = {
+            type: "expression",
+            column: "Created",
+            operator: "equals",
+            value: "ThisMonth",
+            valueType: "special",
+        };
+        let result = changeOperator(dynamic, "greaterthan", { type: "date" });
+        expect(result).toMatchObject({ valueType: "special", value: "ThisMonth" });
+    });
+});
+describe("path helpers", () => {
+    let nested = group("or", group("and", expression("A"), group("or", expression("B"), expression("C"))));
+    test("getNodeAtPath walks into nested groups", () => {
+        expect(getNodeAtPath(nested, [])).toBe(nested);
+        expect(getNodeAtPath(nested, [0, 0])).toEqual(expression("A"));
+        expect(getNodeAtPath(nested, [0, 1, 1])).toEqual(expression("C"));
+    });
+    test("getNodeAtPath returns null for an unknown path", () => {
+        expect(getNodeAtPath(nested, [5])).toBeNull();
+        expect(getNodeAtPath(nested, [0, 0, 0])).toBeNull();
+    });
+    test("insertNodeAtPath appends to a nested group", () => {
+        let result = insertNodeAtPath(nested, [0, 1], expression("D"));
+        expect(countExpressions(result)).toBe(4);
+        expect(getNodeAtPath(result, [0, 1, 2])).toEqual(expression("D"));
+    });
+    test("insertNodeAtPath ignores an unknown path", () => {
+        expect(insertNodeAtPath(nested, [5], expression("D"))).toBe(nested);
+    });
+    test("updateNodeAtPath replaces one node", () => {
+        let result = updateNodeAtPath(nested, [0, 1, 0], (node) => ({ ...node, value: "changed" }));
+        expect(getNodeAtPath(result, [0, 1, 0])).toMatchObject({ value: "changed" });
+        expect(getNodeAtPath(nested, [0, 1, 0])).toMatchObject({ value: "x" });
+    });
+    test("removeNodeAtPath removes a nested node", () => {
+        let result = removeNodeAtPath(nested, [0, 1, 0]);
+        expect(countExpressions(result)).toBe(2);
+    });
+    test("removing the root resets to the default layout", () => {
+        expect(removeNodeAtPath(nested, [])).toEqual(createEmptyFilter());
+    });
+    test("setGroupMode changes the mode of the group at the path", () => {
+        expect(setGroupMode(nested, [], "and").mode).toBe("and");
+        expect(getNodeAtPath(setGroupMode(nested, [0], "or"), [0]).mode).toBe("or");
+    });
+    test("setGroupMode leaves expressions alone", () => {
+        expect(setGroupMode(nested, [0, 0], "or")).toEqual(nested);
+    });
+    test("addGroupAtPath uses the opposite mode to its parent", () => {
+        let withGroup = addGroupAtPath(createEmptyFilter());
+        expect(getNodeAtPath(withGroup, [0]).mode).toBe("or");
+        expect(getNodeAtPath(addGroupAtPath(withGroup, [0]), [0, 0]).mode).toBe("and");
+    });
+    test("mutations do not modify the original filter", () => {
+        let filter = createEmptyFilter();
+        insertNodeAtPath(filter, [], expression("A"));
+        expect(countExpressions(filter)).toBe(0);
+    });
+});

package/es/filter/types.d.ts

@@ -0,0 +1,73 @@
+/**
+ * A group of filter items, combined with either `and` or `or`.
+ *
+ * This is the shape accepted by the `filterObject` / `whereObject` parameters
+ * on a data object. `@olenbetong/appframe-data` re-exports these types.
+ */
+export type FilterGroup = {
+    type: "group";
+    name?: string;
+    mode: "and" | "or";
+    items: Array<FilterGroup | FilterExpression>;
+};
+/** A single `column operator value` comparison. */
+export type FilterExpression = {
+    type: "expression";
+    column: string;
+    operator: string;
+    value: string | string[] | Date | number | null;
+    valueType: string;
+};
+/**
+ * The value types understood by the Appframe filter element converter.
+ *
+ * @see `appframe/Appframe.Web.Core/Filtering/FilterElementConverter.vb`
+ */
+export type FilterValueType = "string" | "number" | "boolean" | "uniqueidentifier" | "array" | "datetime" | "special" | "null";
+/**
+ * Canonical operator names. These are the lower-cased `eOperators` enum member
+ * names as emitted by the server, including the two aliases the server
+ * special-cases (`notequals` for `Not`, `notdatequals` for `NotDateEquals`).
+ *
+ * @see `appframe/Appframe3.Common.Data/Filtering/eOperators.vb`
+ */
+export type FilterOperator = "equals" | "notequals" | "greaterthan" | "greaterthanorequal" | "lessthan" | "lessthanorequal" | "beginswith" | "notbeginswith" | "endswith" | "notendswith" | "contains" | "notcontains" | "like" | "notlike" | "isnull" | "isnotnull" | "isblank" | "isnotblank" | "istrue" | "isfalse" | "inlist" | "notinlist" | "between" | "notbetween" | "dateequals" | "notdatequals" | "dategreaterthan" | "dategreaterthanorequal" | "datelessthan" | "datelessthanorequal" | "datebetween" | "datenotbetween";
+/**
+ * Dynamic ("special") filter values. These are resolved server-side into a
+ * relative date or the current user name, and are sent with
+ * `valueType: "special"`.
+ *
+ * @see `appframe/Appframe3.Common.Data/Filtering/eDynamicValue.vb`
+ */
+export type DynamicValue = "CurrentUser" | "Yesterday" | "Today" | "Tomorrow" | "ThisWeek" | "ThisMonth" | "ThisYear" | "LastWeek" | "LastMonth" | "LastYear" | "NextWeek" | "NextMonth" | "NextYear" | "UserYesterday" | "UserToday" | "UserTomorrow" | "UserThisWeek" | "UserThisMonth" | "UserThisYear" | "UserLastWeek" | "UserLastMonth" | "UserLastYear" | "UserNextWeek" | "UserNextMonth" | "UserNextYear";
+/**
+ * The simplified data types the filter builder groups fields into. Mirrors the
+ * normalized `DataType` column on `sviw_WebSiteCMS_FilterBuilder_ViewFields`.
+ */
+export type FilterFieldType = "string" | "number" | "boolean" | "date" | "datetime" | "uniqueidentifier";
+/**
+ * Metadata for one filterable field.
+ */
+export type FieldMetadata = {
+    /** Database field name, used as `FilterExpression.column`. */
+    name: string;
+    /** Display name. Falls back to `name` when not set. */
+    caption?: string;
+    type: FilterFieldType;
+    nullable?: boolean;
+    /** When true the field is hidden from the field picker. */
+    excludeFromFilter?: boolean;
+    /**
+     * Serialized record source for a lookup editor. When present the value
+     * editor should offer a list of values instead of free text.
+     */
+    valueListRecordSource?: string;
+    valueListValueMember?: string;
+};
+/** Access level a user has on a saved filter. */
+export type FilterAccessLevel = "Reader" | "Editor" | "Manager";
+/**
+ * The filter tree used by the filter builder. Groups can be nested to any depth
+ * and each group combines its items with either `and` or `or`.
+ */
+export type FilterTree = FilterGroup;

package/es/filter/types.js

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

package/es/index.d.ts

@@ -12,6 +12,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";
@@ -19,6 +20,7 @@ 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";

package/es/index.js

@@ -6,15 +6,17 @@ export { toLocalDateTime, toLocalISODate, toLocalISODateTime } from "./date.js";
 export { downloadBlob } from "./downloadBlob.js";
 export { downloadRequest } from "./downloadRequest.js";
 export { expose } from "./expose.js";
+export * from "./filter/index.js";
 export { getLocalizedString } from "./getLocalizedString.js";
 export { getUserImage } from "./getUserImage.js";
 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 { alert, ConfirmButtons, confirm, openAlertDialog, waitForDialog } from "./alert.js";
 export { getSettings, saveSettings } from "./settings.js";
-// biome-ignore lint/correctness/noInvalidUseBeforeDeclaration: this is injected build time
-export const version = "2.11.10";
+// oxlint-disable-next-line no-use-before-define -- this is injected build time
+export const version = "2.12.0";

package/es/parseFunc.test.js

@@ -5,11 +5,10 @@ function testFunction(arg1, arg2) {
 }
 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", () => {
         const arrow = () => ({ foo: "bar" });
@@ -44,7 +43,7 @@ describe("parseFunc", () => {
         expect(result.name).toBe("");
         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/es/report/index.d.ts

@@ -0,0 +1,6 @@
+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/es/report/index.js

@@ -0,0 +1,5 @@
+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, } from "./render.js";
+export { getReportFormats, toReport } from "./report.js";

package/es/report/parameterDefaults.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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 type { ReportParameter, ReportParameterValue, ReportParameterValues } from "./types.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 declare function fetchParameterDefault(reportId: string, parameter: ReportParameter, signal?: AbortSignal): Promise<ReportParameterValue>;
+/**
+ * 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 declare function resolveParameterDefaults(reportId: string, parameters: ReportParameter[], literalDefaults: ReportParameterValues, signal?: AbortSignal): Promise<ReportParameterValues>;

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