@olenbetong/appframe-core 2.11.9 → 2.12.0

package/src/filter/operators.test.ts

@@ -0,0 +1,136 @@
+import { describe, expect, test } from "vitest";
+
+import {
+	getDefaultOperator,
+	getDynamicValuesForField,
+	getOperatorArity,
+	getOperatorLabel,
+	getOperatorsForField,
+	getValueType,
+	normalizeOperator,
+} from "./operators.js";
+
+describe("getOperatorsForField", () => {
+	test("boolean fields only get truth checks", () => {
+		expect(getOperatorsForField({ type: "boolean" })).toEqual(["istrue", "isfalse"]);
+	});
+
+	test("boolean fields never get null checks", () => {
+		expect(getOperatorsForField({ type: "boolean", nullable: true })).toEqual(["istrue", "isfalse"]);
+	});
+
+	test("nullable fields get null checks last", () => {
+		let operators = getOperatorsForField({ type: "number", nullable: true });
+
+		expect(operators.slice(-2)).toEqual(["isnull", "isnotnull"]);
+	});
+
+	test("string fields get the string comparison operators", () => {
+		let operators = getOperatorsForField({ type: "string" });
+
+		expect(operators).toContain("contains");
+		expect(operators).toContain("beginswith");
+		expect(operators).toContain("isblank");
+	});
+
+	test("number fields do not get string comparison operators", () => {
+		let operators = getOperatorsForField({ type: "number" });
+
+		expect(operators).not.toContain("contains");
+		expect(operators).not.toContain("beginswith");
+	});
+
+	test("unknown field types fall back to the string operators", () => {
+		let operators = getOperatorsForField({ type: "something" as never });
+
+		expect(operators).toEqual(getOperatorsForField({ type: "string" }));
+	});
+});
+
+describe("getDefaultOperator", () => {
+	test.each([
+		["string", "beginswith"],
+		["number", "equals"],
+		["date", "equals"],
+		["datetime", "equals"],
+		["boolean", "istrue"],
+	] as const)("%s defaults to %s", (type, expected) => {
+		expect(getDefaultOperator({ type })).toBe(expected);
+	});
+});
+
+describe("getOperatorArity", () => {
+	test.each([
+		["isnull", "none"],
+		["istrue", "none"],
+		["isblank", "none"],
+		["between", "pair"],
+		["datenotbetween", "pair"],
+		["inlist", "list"],
+		["notinlist", "list"],
+		["equals", "single"],
+		["contains", "single"],
+	] as const)("%s has arity %s", (operator, expected) => {
+		expect(getOperatorArity(operator)).toBe(expected);
+	});
+});
+
+describe("getOperatorLabel", () => {
+	test("date fields get the relative wording for comparisons", () => {
+		expect(getOperatorLabel("greaterthan", "date")).toBe("After");
+		expect(getOperatorLabel("lessthanorequal", "datetime")).toBe("Up to");
+	});
+
+	test("number fields get the numeric wording", () => {
+		expect(getOperatorLabel("greaterthan", "number")).toBe("Greater than");
+	});
+
+	test("non-comparison operators are unaffected by the field type", () => {
+		expect(getOperatorLabel("inlist", "date")).toBe("In list");
+		expect(getOperatorLabel("inlist", "number")).toBe("In list");
+	});
+});
+
+describe("getValueType", () => {
+	test("parameterless operators send a null value type", () => {
+		expect(getValueType({ type: "string" }, "isnull")).toBe("null");
+		expect(getValueType({ type: "boolean" }, "istrue")).toBe("null");
+	});
+
+	test.each([
+		["string", "string"],
+		["number", "number"],
+		["date", "datetime"],
+		["datetime", "datetime"],
+		["uniqueidentifier", "uniqueidentifier"],
+	] as const)("%s fields send %s", (type, expected) => {
+		expect(getValueType({ type }, "equals")).toBe(expected);
+	});
+});
+
+describe("normalizeOperator", () => {
+	test.each([
+		["Equals", "equals"],
+		["BeginsWith", "beginswith"],
+		["NotDateEquals", "notdatequals"],
+		["Not", "notequals"],
+		["Tweens", "notbetween"],
+		["Not, Date", "notdatequals"],
+	])("%s normalizes to %s", (input, expected) => {
+		expect(normalizeOperator(input)).toBe(expected);
+	});
+});
+
+describe("getDynamicValuesForField", () => {
+	test("date fields get relative dates", () => {
+		expect(getDynamicValuesForField({ type: "date" })).toContain("ThisMonth");
+	});
+
+	test("string fields only get the current user", () => {
+		expect(getDynamicValuesForField({ type: "string" })).toEqual(["CurrentUser"]);
+	});
+
+	test("number fields get none", () => {
+		expect(getDynamicValuesForField({ type: "number" })).toEqual([]);
+	});
+});

package/src/filter/operators.ts

@@ -0,0 +1,252 @@
+import { getLocalizedString } from "../getLocalizedString.js";
+import type { DynamicValue, FieldMetadata, FilterFieldType, FilterOperator, FilterValueType } from "./types.js";
+
+/**
+ * Operators that take no value at all.
+ *
+ * `eOperators.ParameterLessChecks` plus the blank checks.
+ */
+const PARAMETERLESS_OPERATORS: FilterOperator[] = ["isnull", "isnotnull", "istrue", "isfalse", "isblank", "isnotblank"];
+
+/** Operators whose value is a two element `[from, to]` array. */
+const PAIR_OPERATORS: FilterOperator[] = ["between", "notbetween", "datebetween", "datenotbetween"];
+
+/** Operators whose value is an array of values. */
+const LIST_OPERATORS: FilterOperator[] = ["inlist", "notinlist"];
+
+/** How many values an operator needs. */
+export type OperatorArity = "none" | "single" | "pair" | "list";
+
+export function getOperatorArity(operator: FilterOperator): OperatorArity {
+	if (PARAMETERLESS_OPERATORS.includes(operator)) return "none";
+	if (PAIR_OPERATORS.includes(operator)) return "pair";
+	if (LIST_OPERATORS.includes(operator)) return "list";
+	return "single";
+}
+
+/**
+ * Operator labels, keyed by operator. Comparison operators have a different
+ * label for dates than for numbers, matching the Windows filter editor.
+ *
+ * @see `appframe/Appframe3.Win/Controls/afFilterEditor/Utils/FilterLineControlUtils.vb`
+ */
+const OPERATOR_LABELS: Record<FilterOperator, string> = {
+	equals: "Equal to",
+	notequals: "Not equal to",
+	greaterthan: "Greater than",
+	greaterthanorequal: "Greater than or equal to",
+	lessthan: "Less than",
+	lessthanorequal: "Less than or equal to",
+	beginswith: "Begins with",
+	notbeginswith: "Does not begin with",
+	endswith: "Ends with",
+	notendswith: "Does not end with",
+	contains: "Contains",
+	notcontains: "Does not contain",
+	like: "Like",
+	notlike: "Not like",
+	isnull: "Is null",
+	isnotnull: "Is not null",
+	isblank: "Is empty",
+	isnotblank: "Is not empty",
+	istrue: "Is true",
+	isfalse: "Is false",
+	inlist: "In list",
+	notinlist: "Not in list",
+	between: "Between",
+	notbetween: "Not between",
+	dateequals: "Equal to",
+	notdatequals: "Not equal to",
+	dategreaterthan: "After",
+	dategreaterthanorequal: "On or after",
+	datelessthan: "Before",
+	datelessthanorequal: "Up to",
+	datebetween: "Between",
+	datenotbetween: "Not between",
+};
+
+/** Comparison operator labels used for date and time fields. */
+const DATE_OPERATOR_LABELS: Partial<Record<FilterOperator, string>> = {
+	greaterthan: "After",
+	greaterthanorequal: "On or after",
+	lessthan: "Before",
+	lessthanorequal: "Up to",
+};
+
+/**
+ * Returns the localized label for an operator. Date fields get the
+ * "After"/"Before" wording instead of "Greater than"/"Less than".
+ */
+export function getOperatorLabel(operator: FilterOperator, fieldType?: FilterFieldType): string {
+	let isDate = fieldType === "date" || fieldType === "datetime";
+	let label = (isDate ? DATE_OPERATOR_LABELS[operator] : undefined) ?? OPERATOR_LABELS[operator];
+
+	return getLocalizedString(label ?? operator);
+}
+
+const EQUALITY: FilterOperator[] = ["equals", "notequals"];
+const LIST_CHECKS: FilterOperator[] = ["inlist", "notinlist"];
+const RANGE: FilterOperator[] = ["between", "notbetween"];
+const COMPARISONS: FilterOperator[] = ["greaterthan", "greaterthanorequal", "lessthan", "lessthanorequal"];
+const STRING_CHECKS: FilterOperator[] = [
+	"contains",
+	"notcontains",
+	"beginswith",
+	"notbeginswith",
+	"endswith",
+	"notendswith",
+	"isblank",
+	"isnotblank",
+];
+
+/**
+ * Operators offered per field type, in the order the Windows filter editor
+ * presents them.
+ */
+const OPERATORS_BY_TYPE: Record<FilterFieldType, FilterOperator[]> = {
+	date: [...EQUALITY, ...LIST_CHECKS, ...RANGE, ...COMPARISONS],
+	datetime: [...EQUALITY, ...LIST_CHECKS, ...RANGE, ...COMPARISONS],
+	number: [...EQUALITY, ...LIST_CHECKS, ...RANGE, ...COMPARISONS],
+	boolean: ["istrue", "isfalse"],
+	string: [...EQUALITY, ...STRING_CHECKS, ...LIST_CHECKS, ...RANGE, ...COMPARISONS],
+	uniqueidentifier: [...EQUALITY, ...STRING_CHECKS, ...LIST_CHECKS, ...RANGE, ...COMPARISONS],
+};
+
+/** Default operator per field type. */
+const DEFAULT_OPERATOR_BY_TYPE: Record<FilterFieldType, FilterOperator> = {
+	date: "equals",
+	datetime: "equals",
+	number: "equals",
+	boolean: "istrue",
+	string: "beginswith",
+	uniqueidentifier: "beginswith",
+};
+
+/**
+ * Returns the operators available for a field. Nullable fields additionally get
+ * the null checks. Boolean fields never get null checks, since `istrue` and
+ * `isfalse` already cover the parameterless cases.
+ */
+export function getOperatorsForField(field: Pick<FieldMetadata, "type" | "nullable">): FilterOperator[] {
+	let operators = [...(OPERATORS_BY_TYPE[field.type] ?? OPERATORS_BY_TYPE.string)];
+
+	if (field.nullable && field.type !== "boolean") {
+		operators.push("isnull", "isnotnull");
+	}
+
+	return operators;
+}
+
+export function getDefaultOperator(field: Pick<FieldMetadata, "type">): FilterOperator {
+	return DEFAULT_OPERATOR_BY_TYPE[field.type] ?? "equals";
+}
+
+/**
+ * The `valueType` to send for a field/operator combination.
+ *
+ * Parameterless operators send `"null"`, list and range operators send
+ * `"array"`, everything else sends the field's own value type.
+ */
+export function getValueType(field: Pick<FieldMetadata, "type">, operator: FilterOperator): FilterValueType {
+	if (getOperatorArity(operator) === "none") return "null";
+
+	switch (field.type) {
+		case "number":
+			return "number";
+		case "boolean":
+			return "boolean";
+		case "date":
+		case "datetime":
+			return "datetime";
+		case "uniqueidentifier":
+			return "uniqueidentifier";
+		default:
+			return "string";
+	}
+}
+
+/** Relative date values offered in the date value editor, in menu order. */
+export const RELATIVE_DATE_VALUES: DynamicValue[] = [
+	"Yesterday",
+	"Today",
+	"Tomorrow",
+	"ThisWeek",
+	"ThisMonth",
+	"ThisYear",
+	"LastWeek",
+	"LastMonth",
+	"LastYear",
+	"NextWeek",
+	"NextMonth",
+	"NextYear",
+];
+
+const DYNAMIC_VALUE_LABELS: Record<DynamicValue, string> = {
+	CurrentUser: "Current user",
+	Yesterday: "Yesterday",
+	Today: "Today",
+	Tomorrow: "Tomorrow",
+	ThisWeek: "This week",
+	ThisMonth: "This month",
+	ThisYear: "This year",
+	LastWeek: "Last week",
+	LastMonth: "Last month",
+	LastYear: "Last year",
+	NextWeek: "Next week",
+	NextMonth: "Next month",
+	NextYear: "Next year",
+	UserYesterday: "Yesterday",
+	UserToday: "Today",
+	UserTomorrow: "Tomorrow",
+	UserThisWeek: "This week",
+	UserThisMonth: "This month",
+	UserThisYear: "This year",
+	UserLastWeek: "Last week",
+	UserLastMonth: "Last month",
+	UserLastYear: "Last year",
+	UserNextWeek: "Next week",
+	UserNextMonth: "Next month",
+	UserNextYear: "Next year",
+};
+
+export function getDynamicValueLabel(value: DynamicValue): string {
+	return getLocalizedString(DYNAMIC_VALUE_LABELS[value] ?? value);
+}
+
+/**
+ * Returns the dynamic ("special") values that can be used with a field. Date
+ * fields get the relative dates; string fields can be compared to the current
+ * user name.
+ */
+export function getDynamicValuesForField(field: Pick<FieldMetadata, "type">): DynamicValue[] {
+	if (field.type === "date" || field.type === "datetime") return [...RELATIVE_DATE_VALUES];
+	if (field.type === "string") return ["CurrentUser"];
+
+	return [];
+}
+
+/**
+ * Aliases for names `eOperators.ToString()` can produce that are not operators
+ * in their own right. `Not` is the bare negation flag (i.e. "not equal to"),
+ * `Tweens` shares its numeric value with `NotBetween`, and combined flags are
+ * rendered as a comma separated list.
+ *
+ * @see `FilterElementConverter.FilterExpressionToDictionary`
+ */
+const OPERATOR_ALIASES: Record<string, FilterOperator> = {
+	not: "notequals",
+	tweens: "notbetween",
+	notdate: "notdatequals",
+	// The enum member is `NotDateEquals`, but the wire format drops an "e".
+	notdateequals: "notdatequals",
+};
+
+/**
+ * Normalizes an operator string coming from the server or from another filter
+ * producer (`AfGrid` emits PascalCase names) to the canonical lower-case form.
+ */
+export function normalizeOperator(operator: string): FilterOperator {
+	let normalized = operator.toLowerCase().replace(/[\s,]/g, "");
+
+	return OPERATOR_ALIASES[normalized] ?? (normalized as FilterOperator);
+}

package/src/filter/savedFilters.test.ts

@@ -0,0 +1,145 @@
+import { describe, expect, test } from "vitest";
+
+import {
+	canDeleteSavedFilter,
+	canEditSavedFilter,
+	canRenameSavedFilter,
+	canShareSavedFilter,
+	findSavedFilter,
+	NO_FILTER_ID,
+	partitionSavedFilters,
+	type SavedFilterRecord,
+	toSavedFilter,
+	toSavedFilters,
+} from "./savedFilters.js";
+
+function record(overrides: SavedFilterRecord = {}): SavedFilterRecord {
+	return {
+		PrimKey: "11111111-1111-1111-1111-111111111111",
+		FilterID: 1,
+		DBObjectID: "aviw_Test_View",
+		FilterName: "My filter",
+		FilterCriteria: "[Name] = 'a'",
+		AccessLevel: "Manager",
+		CreatedByUser: "true",
+		CreatedBy: "bvh",
+		Domain: "OB",
+		CrossDomain: false,
+		IsPersonallyShared: 0,
+		HideFilterCriteria: 0,
+		...overrides,
+	};
+}
+
+describe("toSavedFilter", () => {
+	test("maps a record", () => {
+		let filter = toSavedFilter(record());
+
+		expect(filter).toMatchObject({
+			filterId: 1,
+			name: "My filter",
+			criteria: "[Name] = 'a'",
+			dbObjectId: "aviw_Test_View",
+			accessLevel: "Manager",
+			createdByUser: true,
+			crossDomain: false,
+		});
+	});
+
+	test("CreatedByUser is a string, not a bit", () => {
+		expect(toSavedFilter(record({ CreatedByUser: "false" })).createdByUser).toBe(false);
+		expect(toSavedFilter(record({ CreatedByUser: "False" })).createdByUser).toBe(false);
+		expect(toSavedFilter(record({ CreatedByUser: "true" })).createdByUser).toBe(true);
+	});
+
+	test("bit columns arrive as numbers", () => {
+		let filter = toSavedFilter(record({ CrossDomain: 1, IsPersonallyShared: 1, HideFilterCriteria: 1 }));
+
+		expect(filter.crossDomain).toBe(true);
+		expect(filter.isPersonallyShared).toBe(true);
+		expect(filter.hideCriteria).toBe(true);
+	});
+
+	test("an unknown access level falls back to Reader", () => {
+		expect(toSavedFilter(record({ AccessLevel: null })).accessLevel).toBe("Reader");
+	});
+
+	test("empty optional strings become null", () => {
+		let filter = toSavedFilter(record({ OptionalHeaderText: "", OptionalComment: "" }));
+
+		expect(filter.headerText).toBeNull();
+		expect(filter.comment).toBeNull();
+	});
+
+	test("dates are parsed", () => {
+		expect(toSavedFilter(record({ Created: "2026-01-02T03:04:05Z" })).created).toBeInstanceOf(Date);
+		expect(toSavedFilter(record({ Created: null })).created).toBeNull();
+	});
+});
+
+describe("toSavedFilters", () => {
+	test("drops the synthetic No Filter row", () => {
+		let filters = toSavedFilters([record({ FilterID: NO_FILTER_ID, FilterName: "No Filter" }), record()]);
+
+		expect(filters).toHaveLength(1);
+		expect(filters[0].name).toBe("My filter");
+	});
+
+	test("sorts by name", () => {
+		let filters = toSavedFilters([
+			record({ FilterID: 1, FilterName: "Beta" }),
+			record({ FilterID: 2, FilterName: "Alpha" }),
+		]);
+
+		expect(filters.map((filter) => filter.name)).toEqual(["Alpha", "Beta"]);
+	});
+});
+
+describe("partitionSavedFilters", () => {
+	test("splits on createdByUser", () => {
+		let filters = toSavedFilters([
+			record({ FilterID: 1, FilterName: "Mine", CreatedByUser: "true" }),
+			record({ FilterID: 2, FilterName: "Theirs", CreatedByUser: "false" }),
+		]);
+
+		let { mine, shared } = partitionSavedFilters(filters);
+
+		expect(mine.map((filter) => filter.name)).toEqual(["Mine"]);
+		expect(shared.map((filter) => filter.name)).toEqual(["Theirs"]);
+	});
+});
+
+describe("permissions", () => {
+	test("a reader can neither edit nor share", () => {
+		let filter = toSavedFilter(record({ AccessLevel: "Reader", CreatedByUser: "false" }));
+
+		expect(canEditSavedFilter(filter)).toBe(false);
+		expect(canShareSavedFilter(filter)).toBe(false);
+	});
+
+	test("an editor can edit but not share", () => {
+		let filter = toSavedFilter(record({ AccessLevel: "Editor", CreatedByUser: "false" }));
+
+		expect(canEditSavedFilter(filter)).toBe(true);
+		expect(canShareSavedFilter(filter)).toBe(false);
+	});
+
+	test("renaming and deleting need ownership, not manager access", () => {
+		let managed = toSavedFilter(record({ AccessLevel: "Manager", CreatedByUser: "false" }));
+
+		expect(canShareSavedFilter(managed)).toBe(true);
+		expect(canRenameSavedFilter(managed)).toBe(false);
+		expect(canDeleteSavedFilter(managed)).toBe(false);
+		expect(canRenameSavedFilter(toSavedFilter(record()))).toBe(true);
+	});
+});
+
+describe("findSavedFilter", () => {
+	test("finds by id and tolerates null", () => {
+		let filters = toSavedFilters([record({ FilterID: 7, FilterName: "Seven" })]);
+
+		expect(findSavedFilter(filters, 7)?.name).toBe("Seven");
+		expect(findSavedFilter(filters, 8)).toBeUndefined();
+		expect(findSavedFilter(filters, null)).toBeUndefined();
+	});
+});