@olenbetong/appframe-core 2.11.10 → 2.13.0

package/src/filter/standardLayout.ts

@@ -0,0 +1,65 @@
+import { isExpression, isGroup } from "./tree.js";
+import type { FilterExpression, FilterGroup, FilterTree } from "./types.js";
+
+/**
+ * The "standard layout" is the simplified shape the Windows filter editor can
+ * render in its flow view: an outer `or` group whose items are `and` groups of
+ * expressions. Anything else falls back to the advanced (DevExpress) editor
+ * there, and to the nested tree editor on the web.
+ *
+ * @see `afFilterEditor.CanRenderFilter`
+ */
+export function isStandardLayout(filter: FilterGroup | FilterExpression | null | undefined): boolean {
+	if (!filter || isExpression(filter) || filter.mode !== "or") return false;
+
+	return filter.items.every((item) => isGroup(item) && item.mode === "and" && item.items.every(isExpression));
+}
+
+/**
+ * Coerces an arbitrary filter tree into the standard layout.
+ *
+ * An `or` group's items each become their own `and` group. Anything else is
+ * flattened into a single `and` group. This loses nesting, so only use it when
+ * the consumer cannot handle a nested tree.
+ */
+export function coerceToStandardLayout(filter: FilterGroup | FilterExpression | null | undefined): FilterTree {
+	if (!filter) return { type: "group", mode: "or", items: [{ type: "group", mode: "and", items: [] }] };
+
+	if (isExpression(filter)) {
+		return { type: "group", mode: "or", items: [{ type: "group", mode: "and", items: [filter] }] };
+	}
+
+	if (filter.mode === "or") {
+		let groups = filter.items.map((item) => {
+			let expressions: FilterExpression[] = [];
+			collectExpressions(item, expressions);
+
+			return { type: "group", mode: "and", items: expressions } satisfies FilterGroup;
+		});
+
+		return {
+			type: "group",
+			mode: "or",
+			items: groups.length > 0 ? groups : [{ type: "group", mode: "and", items: [] }],
+		};
+	}
+
+	let expressions: FilterExpression[] = [];
+	collectExpressions(filter, expressions);
+
+	return { type: "group", mode: "or", items: [{ type: "group", mode: "and", items: expressions }] };
+}
+
+/**
+ * Collects every expression in a (possibly nested) filter, in document order.
+ */
+function collectExpressions(item: FilterGroup | FilterExpression, into: FilterExpression[]) {
+	if (isExpression(item)) {
+		into.push(item);
+		return;
+	}
+
+	for (let child of item.items) {
+		collectExpressions(child, into);
+	}
+}

package/src/filter/tree.test.ts

@@ -0,0 +1,258 @@
+import type { FilterExpression, FilterGroup } from "./types.js";
+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: string, operator = "equals", value: FilterExpression["value"] = "x"): FilterExpression {
+	return { type: "expression", column, operator, value, valueType: "string" };
+}
+
+function group(mode: "and" | "or", ...items: Array<FilterGroup | FilterExpression>): FilterGroup {
+	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: FilterExpression = {
+			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 as FilterExpression), 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]) as FilterGroup).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]) as FilterGroup).mode).toBe("or");
+		expect((getNodeAtPath(addGroupAtPath(withGroup, [0]), [0, 0]) as FilterGroup).mode).toBe("and");
+	});
+
+	test("mutations do not modify the original filter", () => {
+		let filter = createEmptyFilter();
+		insertNodeAtPath(filter, [], expression("A"));
+
+		expect(countExpressions(filter)).toBe(0);
+	});
+});

package/src/filter/tree.ts

@@ -0,0 +1,238 @@
+import { getDefaultOperator, getOperatorArity, getValueType, normalizeOperator } from "./operators.js";
+import type { FieldMetadata, FilterExpression, FilterGroup, FilterOperator, FilterTree } from "./types.js";
+
+/**
+ * Path to a node in a filter tree, as a list of item indexes from the root
+ * group. The root itself is the empty path.
+ *
+ * @example
+ * ```ts
+ * // The second condition of the first group
+ * let path: FilterPath = [0, 1];
+ * ```
+ */
+export type FilterPath = number[];
+
+export type FilterNode = FilterGroup | FilterExpression;
+
+/**
+ * Creates the default empty filter: a single `and` group with no conditions.
+ */
+export function createEmptyFilter(): FilterTree {
+	return createEmptyGroup("and");
+}
+
+export function createEmptyGroup(mode: FilterGroup["mode"] = "and"): FilterGroup {
+	return { type: "group", mode, items: [] };
+}
+
+export function isGroup(item: FilterNode): item is FilterGroup {
+	return item.type === "group";
+}
+
+export function isExpression(item: FilterNode): item is FilterExpression {
+	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: FilterNode | null | undefined): FilterTree {
+	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: FilterNode | null | undefined): boolean {
+	return countExpressions(filter) === 0;
+}
+
+export function countExpressions(filter: FilterNode | null | undefined): number {
+	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: FilterNode | null | undefined): FilterGroup | null {
+	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 is FilterNode => 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: FilterNode): boolean {
+	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: FieldMetadata, operator?: FilterOperator): FilterExpression {
+	let op = operator ?? getDefaultOperator(field);
+
+	return {
+		type: "expression",
+		column: field.name,
+		operator: op,
+		value: createEmptyValue(op),
+		valueType: getValueType(field, op),
+	};
+}
+
+function createEmptyValue(operator: FilterOperator): FilterExpression["value"] {
+	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: FilterExpression,
+	operator: FilterOperator,
+	field: Pick<FieldMetadata, "type">,
+): FilterExpression {
+	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: FilterNode, path: FilterPath): FilterNode | null {
+	let node: FilterNode | undefined = 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<T extends FilterNode>(
+	filter: T,
+	path: FilterPath,
+	updater: (node: FilterNode) => FilterNode | null,
+): T {
+	if (path.length === 0) {
+		return (updater(filter) as T | null) ?? filter;
+	}
+
+	if (!isGroup(filter)) return filter;
+
+	let [index, ...rest] = path;
+	let child = filter.items[index as number];
+	if (!child) return filter;
+
+	let items = [...filter.items];
+
+	if (rest.length === 0) {
+		let updated = updater(child);
+
+		if (updated === null) {
+			items.splice(index as number, 1);
+		} else {
+			items[index as number] = updated;
+		}
+	} else {
+		items[index as number] = updateNodeAtPath(child, rest, updater);
+	}
+
+	return { ...filter, items };
+}
+
+/** Returns a copy of the tree with `node` appended to the group at `path`. */
+export function insertNodeAtPath<T extends FilterNode>(filter: T, path: FilterPath, node: FilterNode): T {
+	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<T extends FilterNode>(filter: T, path: FilterPath): T {
+	if (path.length === 0) return createEmptyFilter() as T;
+
+	return updateNodeAtPath(filter, path, () => null);
+}
+
+/** Returns a copy of the tree with the mode of the group at `path` changed. */
+export function setGroupMode<T extends FilterNode>(filter: T, path: FilterPath, mode: FilterGroup["mode"]): T {
+	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<T extends FilterNode>(filter: T, path: FilterPath = []): T {
+	let parent = getNodeAtPath(filter, path);
+	// A nested group is only useful when it combines differently to its parent.
+	let mode: FilterGroup["mode"] = parent && isGroup(parent) && parent.mode === "and" ? "or" : "and";
+
+	return insertNodeAtPath(filter, path, createEmptyGroup(mode));
+}

package/src/filter/types.ts

@@ -0,0 +1,146 @@
+/**
+ * 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;