@olenbetong/appframe-core 2.15.2 → 2.16.0

package/src/filter/columnValues.test.ts

@@ -0,0 +1,164 @@
+import type { FieldMetadata, FilterExpression, FilterGroup } from "./types.js";
+import { describe, expect, test } from "vitest";
+
+import { describeFilter } from "./describeFilter.js";
+import {
+	getColumnsForField,
+	getDynamicValuesForField,
+	getOperatorArity,
+	getOperatorsForField,
+	supportsColumnValue,
+} from "./operators.js";
+import { changeOperator, isCompleteExpression, needsFilterString } from "./tree.js";
+
+const fields: FieldMetadata[] = [
+	{ name: "Date", caption: "Dato", type: "date" },
+	{ name: "DeliveryDate", caption: "Leveringsdato", type: "datetime" },
+	{ name: "Amount", caption: "Beløp", type: "number" },
+	{ name: "Quantity", type: "number" },
+	{ name: "Hidden", type: "number", excludeFromFilter: true },
+	{ name: "Name", type: "string" },
+	{ name: "Active", type: "boolean" },
+	{ name: "Archived", type: "boolean" },
+];
+
+function expression(partial: Partial<FilterExpression>): FilterExpression {
+	return {
+		type: "expression",
+		column: "DeliveryDate",
+		operator: "greaterthan",
+		value: "",
+		valueType: "datetime",
+		...partial,
+	};
+}
+
+function group(...items: FilterExpression[]): FilterGroup {
+	return { type: "group", mode: "and", items };
+}
+
+describe("getColumnsForField", () => {
+	test("offers the other fields of the same type, dates and datetimes together", () => {
+		expect(getColumnsForField(fields[1]!, fields).map((field) => field.name)).toEqual(["Date"]);
+		expect(getColumnsForField(fields[2]!, fields).map((field) => field.name)).toEqual(["Quantity"]);
+	});
+
+	test("offers nothing for booleans", () => {
+		expect(getColumnsForField(fields[6]!, fields)).toEqual([]);
+	});
+});
+
+describe("supportsColumnValue", () => {
+	test("allows comparisons and ranges, not text checks or lists", () => {
+		expect(supportsColumnValue("greaterthan")).toBe(true);
+		expect(supportsColumnValue("between")).toBe(true);
+		expect(supportsColumnValue("contains")).toBe(false);
+		expect(supportsColumnValue("inlist")).toBe(false);
+	});
+});
+
+describe("getDynamicValuesForField", () => {
+	test("includes the dates only the Windows editor had", () => {
+		expect(getDynamicValuesForField({ type: "date" })).toEqual(
+			expect.arrayContaining(["Now", "DayAfterTomorrow", "TwoWeeksAway"]),
+		);
+	});
+});
+
+describe("needsFilterString", () => {
+	test("is false for values the framework reads", () => {
+		expect(needsFilterString(group(expression({ value: "Today", valueType: "special" })))).toBe(false);
+		expect(needsFilterString(group(expression({ operator: "between", value: ["2026-01-01", "2026-02-01"] })))).toBe(
+			false,
+		);
+	});
+
+	test("is true for a column value", () => {
+		expect(needsFilterString(group(expression({ value: "Date", valueType: "column" })))).toBe(true);
+	});
+
+	test("is true for a date only the Windows editor had", () => {
+		expect(needsFilterString(group(expression({ value: "TwoWeeksAway", valueType: "special" })))).toBe(true);
+	});
+
+	test("is true for a range with an end that is not a plain value", () => {
+		let range = expression({
+			operator: "between",
+			value: [{ valueType: "special", value: "Tomorrow" }, "2026-02-01"],
+		});
+
+		expect(needsFilterString({ type: "group", mode: "or", items: [group(range)] })).toBe(true);
+	});
+});
+
+describe("isCompleteExpression", () => {
+	test("needs a value at both ends of a range", () => {
+		let complete = expression({ operator: "between", value: [{ valueType: "column", value: "Date" }, "2026-02-01"] });
+		let missing = expression({ operator: "between", value: [{ valueType: "column", value: "" }, "2026-02-01"] });
+
+		expect(isCompleteExpression(complete)).toBe(true);
+		expect(isCompleteExpression(missing)).toBe(false);
+	});
+});
+
+describe("changeOperator", () => {
+	test("keeps a column across comparisons", () => {
+		let changed = changeOperator(expression({ value: "Date", valueType: "column" }), "lessthan", fields[1]!);
+
+		expect(changed).toMatchObject({ value: "Date", valueType: "column" });
+	});
+
+	test("drops a column for an operator that cannot use one", () => {
+		let changed = changeOperator(
+			expression({ column: "Name", value: "Other", valueType: "column" }),
+			"contains",
+			fields[5]!,
+		);
+
+		expect(changed).toMatchObject({ value: "", valueType: "string" });
+	});
+});
+
+describe("describeFilter", () => {
+	test("names the compared column by its caption", () => {
+		expect(describeFilter(group(expression({ value: "Date", valueType: "column" })), { fields })).toBe(
+			"[Leveringsdato] After [Dato]",
+		);
+	});
+
+	test("describes each end of a range", () => {
+		let range = expression({
+			operator: "between",
+			value: [
+				{ valueType: "special", value: "Tomorrow" },
+				{ valueType: "special", value: "TwoWeeksAway" },
+			],
+		});
+
+		expect(describeFilter(group(range), { fields })).toBe("[Leveringsdato] Between Tomorrow - Two weeks away");
+	});
+});
+
+describe("period operators", () => {
+	test("are offered for dates and take no value", () => {
+		let operators = getOperatorsForField({ type: "datetime" });
+
+		expect(operators).toContain("islastweek");
+		expect(operators).toContain("ispriorthisyear");
+		expect(getOperatorsForField({ type: "number" })).not.toContain("islastweek");
+		expect(getOperatorArity("islastweek")).toBe("none");
+	});
+
+	test("need a filter string", () => {
+		let period = expression({ operator: "islastweek", value: null, valueType: "null" });
+
+		expect(isCompleteExpression(period)).toBe(true);
+		expect(needsFilterString(group(period))).toBe(true);
+	});
+
+	test("are described without a value", () => {
+		let period = expression({ operator: "islastweek", value: null, valueType: "null" });
+
+		expect(describeFilter(group(period), { fields })).toBe("[Leveringsdato] Is last week");
+	});
+});

package/src/filter/describeFilter.ts

@@ -1,6 +1,6 @@
 import type { FilterExpression, FilterGroup } from "./types.js";
 import { getDynamicValueLabel, getOperatorArity, getOperatorLabel, normalizeOperator } from "./operators.js";
-import { isExpression } from "./tree.js";
+import { isExpression, isRangeEnd } from "./tree.js";
 import type { DynamicValue, FieldMetadata } from "./types.js";
 
 export type DescribeFilterOptions = {
@@ -50,26 +50,32 @@ function describeExpression(expression: FilterExpression, fields: Map<string, Fi
 
 	if (arity === "none") return `[${caption}] ${label}`;
 
-	return `[${caption}] ${label} ${formatValue(expression, arity)}`;
+	return `[${caption}] ${label} ${formatValue(expression, arity, fields)}`;
 }
 
-function formatValue(expression: FilterExpression, arity: ReturnType<typeof getOperatorArity>): string {
+function formatValue(
+	expression: FilterExpression,
+	arity: ReturnType<typeof getOperatorArity>,
+	fields: Map<string, FieldMetadata>,
+): string {
 	let { value, valueType } = expression;
 
-	if (valueType === "special" && typeof value === "string") {
-		return getDynamicValueLabel(value as DynamicValue);
-	}
-
 	if (Array.isArray(value)) {
-		let formatted = value.map((item) => formatScalar(item, valueType));
+		let formatted = value.map((item: unknown) =>
+			isRangeEnd(item) ? formatScalar(item.value, item.valueType, fields) : formatScalar(item, valueType, fields),
+		);
 
 		return arity === "pair" ? formatted.join(" - ") : `(${formatted.join(", ")})`;
 	}
 
-	return formatScalar(value, valueType);
+	return formatScalar(value, valueType, fields);
 }
 
-function formatScalar(value: unknown, valueType: string): string {
+function formatScalar(value: unknown, valueType: string, fields: Map<string, FieldMetadata>): string {
+	if (valueType === "special" && typeof value === "string") return getDynamicValueLabel(value as DynamicValue);
+	if (valueType === "column" && typeof value === "string") {
+		return `[${fields.get(value.toLowerCase())?.caption ?? value}]`;
+	}
 	if (value === null || value === undefined) return "";
 	if (value instanceof Date) return value.toISOString().slice(0, 10);
 	if (typeof value === "number" || typeof value === "boolean") return String(value);

package/src/filter/index.ts

@@ -2,6 +2,7 @@ export { type ConvertRequest, convertFilter, type FilterConversionResult } from
 export { describeFilter, type DescribeFilterOptions } from "./describeFilter.js";
 export { toFieldMetadata, toFieldMetadataList, toFilterFieldType, type ViewFieldRecord } from "./fields.js";
 export {
+	getColumnsForField,
 	getDefaultOperator,
 	getDynamicValueLabel,
 	getDynamicValuesForField,
@@ -11,7 +12,9 @@ export {
 	getValueType,
 	normalizeOperator,
 	type OperatorArity,
+	PERIOD_OPERATORS,
 	RELATIVE_DATE_VALUES,
+	supportsColumnValue,
 } from "./operators.js";
 export { coerceToStandardLayout, isStandardLayout } from "./standardLayout.js";
 export {
@@ -43,6 +46,8 @@ export {
 	isEmptyFilter,
 	isExpression,
 	isGroup,
+	isRangeEnd,
+	needsFilterString,
 	pruneFilter,
 	removeNodeAtPath,
 	setGroupMode,
@@ -58,6 +63,7 @@ export type {
 	FilterFieldType,
 	FilterGroup,
 	FilterOperator,
+	FilterRangeEnd,
 	FilterTree,
 	FilterValueType,
 } from "./types.js";

package/src/filter/operators.ts

@@ -8,6 +8,27 @@ import type { DynamicValue, FieldMetadata, FilterFieldType, FilterOperator, Filt
  */
 const PARAMETERLESS_OPERATORS: FilterOperator[] = ["isnull", "isnotnull", "istrue", "isfalse", "isblank", "isnotblank"];
 
+/**
+ * Whole-period checks for dates, such as "Is last week", in the order of the
+ * Windows filter editor. They take no value. The framework has no operator for
+ * them, so a filter using one is sent as a filter string (`needsFilterString`).
+ */
+export const PERIOD_OPERATORS: FilterOperator[] = [
+	"isbeyondthisyear",
+	"islaterthisyear",
+	"islaterthismonth",
+	"isnextweek",
+	"islaterthisweek",
+	"istomorrow",
+	"istoday",
+	"isyesterday",
+	"isearlierthisweek",
+	"islastweek",
+	"isearlierthismonth",
+	"isearlierthisyear",
+	"ispriorthisyear",
+];
+
 /** Operators whose value is a two element `[from, to]` array. */
 const PAIR_OPERATORS: FilterOperator[] = ["between", "notbetween", "datebetween", "datenotbetween"];
 
@@ -18,7 +39,7 @@ const LIST_OPERATORS: FilterOperator[] = ["inlist", "notinlist"];
 export type OperatorArity = "none" | "single" | "pair" | "list";
 
 export function getOperatorArity(operator: FilterOperator): OperatorArity {
-	if (PARAMETERLESS_OPERATORS.includes(operator)) return "none";
+	if (PARAMETERLESS_OPERATORS.includes(operator) || PERIOD_OPERATORS.includes(operator)) return "none";
 	if (PAIR_OPERATORS.includes(operator)) return "pair";
 	if (LIST_OPERATORS.includes(operator)) return "list";
 	return "single";
@@ -63,6 +84,19 @@ const OPERATOR_LABELS: Record<FilterOperator, string> = {
 	datelessthanorequal: "Up to",
 	datebetween: "Between",
 	datenotbetween: "Not between",
+	isbeyondthisyear: "Is beyond this year",
+	islaterthisyear: "Is later this year",
+	islaterthismonth: "Is later this month",
+	isnextweek: "Is next week",
+	islaterthisweek: "Is later this week",
+	istomorrow: "Is tomorrow",
+	istoday: "Is today",
+	isyesterday: "Is yesterday",
+	isearlierthisweek: "Is earlier this week",
+	islastweek: "Is last week",
+	isearlierthismonth: "Is earlier this month",
+	isearlierthisyear: "Is earlier this year",
+	ispriorthisyear: "Is prior to this year",
 };
 
 /** Comparison operator labels used for date and time fields. */
@@ -104,8 +138,8 @@ const STRING_CHECKS: FilterOperator[] = [
  * presents them.
  */
 const OPERATORS_BY_TYPE: Record<FilterFieldType, FilterOperator[]> = {
-	date: [...EQUALITY, ...LIST_CHECKS, ...RANGE, ...COMPARISONS],
-	datetime: [...EQUALITY, ...LIST_CHECKS, ...RANGE, ...COMPARISONS],
+	date: [...EQUALITY, ...LIST_CHECKS, ...RANGE, ...COMPARISONS, ...PERIOD_OPERATORS],
+	datetime: [...EQUALITY, ...LIST_CHECKS, ...RANGE, ...COMPARISONS, ...PERIOD_OPERATORS],
 	number: [...EQUALITY, ...LIST_CHECKS, ...RANGE, ...COMPARISONS],
 	boolean: ["istrue", "isfalse"],
 	string: [...EQUALITY, ...STRING_CHECKS, ...LIST_CHECKS, ...RANGE, ...COMPARISONS],
@@ -175,7 +209,10 @@ export function getValueType(field: Pick<FieldMetadata, "type">, operator: Filte
 export const RELATIVE_DATE_VALUES: DynamicValue[] = [
 	"Yesterday",
 	"Today",
+	"Now",
 	"Tomorrow",
+	"DayAfterTomorrow",
+	"TwoWeeksAway",
 	"ThisWeek",
 	"ThisMonth",
 	"ThisYear",
@@ -191,7 +228,10 @@ const DYNAMIC_VALUE_LABELS: Record<DynamicValue, string> = {
 	CurrentUser: "Current user",
 	Yesterday: "Yesterday",
 	Today: "Today",
+	Now: "Now",
 	Tomorrow: "Tomorrow",
+	DayAfterTomorrow: "Day after tomorrow",
+	TwoWeeksAway: "Two weeks away",
 	ThisWeek: "This week",
 	ThisMonth: "This month",
 	ThisYear: "This year",
@@ -231,6 +271,37 @@ export function getDynamicValuesForField(field: Pick<FieldMetadata, "type">): Dy
 	return [];
 }
 
+/** Operators that can compare a field with another column. */
+const COLUMN_OPERATORS: FilterOperator[] = [...EQUALITY, ...RANGE, ...COMPARISONS];
+
+/** Whether an operator can take another column as its value. */
+export function supportsColumnValue(operator: FilterOperator): boolean {
+	return COLUMN_OPERATORS.includes(operator);
+}
+
+/** Dates and datetimes compare with each other; other types only with their own. */
+function getComparableType(type: FilterFieldType): FilterFieldType {
+	return type === "datetime" ? "date" : type;
+}
+
+/**
+ * The columns a field can be compared with: the other fields of the same type,
+ * as in the Windows filter editor. Booleans have only true and false checks,
+ * so they get none.
+ */
+export function getColumnsForField(
+	field: Pick<FieldMetadata, "name" | "type">,
+	fields: FieldMetadata[],
+): FieldMetadata[] {
+	if (field.type === "boolean") return [];
+
+	let type = getComparableType(field.type);
+
+	return fields.filter(
+		(other) => other.name !== field.name && !other.excludeFromFilter && getComparableType(other.type) === type,
+	);
+}
+
 /**
  * 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"),

package/src/filter/tree.ts

@@ -1,5 +1,19 @@
-import { getDefaultOperator, getOperatorArity, getValueType, normalizeOperator } from "./operators.js";
-import type { FieldMetadata, FilterExpression, FilterGroup, FilterOperator, FilterTree } from "./types.js";
+import {
+	getDefaultOperator,
+	getOperatorArity,
+	getValueType,
+	normalizeOperator,
+	PERIOD_OPERATORS,
+	supportsColumnValue,
+} from "./operators.js";
+import type {
+	FieldMetadata,
+	FilterExpression,
+	FilterGroup,
+	FilterOperator,
+	FilterRangeEnd,
+	FilterTree,
+} from "./types.js";
 
 /**
  * Path to a node in a filter tree, as a list of item indexes from the root
@@ -111,7 +125,14 @@ export function isCompleteExpression(item: FilterNode): boolean {
 	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);
+		return (
+			Array.isArray(item.value) &&
+			item.value.length === 2 &&
+			item.value.every((v: unknown) => {
+				let end = isRangeEnd(v) ? v.value : v;
+				return end !== "" && end != null;
+			})
+		);
 	}
 
 	if (arity === "list") {
@@ -121,6 +142,35 @@ export function isCompleteExpression(item: FilterNode): boolean {
 	return true;
 }
 
+/** Whether a range value end is a `FilterRangeEnd` rather than a plain value. */
+export function isRangeEnd(value: unknown): value is FilterRangeEnd {
+	return typeof value === "object" && value !== null && !(value instanceof Date) && "valueType" in value;
+}
+
+/** Dynamic values the framework has no `eDynamicValue` member for. */
+const DYNAMIC_VALUES_WITHOUT_FRAMEWORK_SUPPORT = new Set<string>(["Now", "DayAfterTomorrow", "TwoWeeksAway"]);
+
+function needsConversion(valueType: string, value: unknown): boolean {
+	if (valueType === "column") return true;
+
+	return valueType === "special" && typeof value === "string" && DYNAMIC_VALUES_WITHOUT_FRAMEWORK_SUPPORT.has(value);
+}
+
+/**
+ * True when the filter holds something the framework's data API cannot read
+ * from a filter object: another column, a range end that is not a plain value,
+ * one of the dates only the Windows editor offers, or a whole-period check. Such a filter must be
+ * converted with `convertFilter` and sent as a filter string.
+ */
+export function needsFilterString(filter: FilterNode | null | undefined): boolean {
+	if (!filter) return false;
+	if (isGroup(filter)) return filter.items.some(needsFilterString);
+	if (PERIOD_OPERATORS.includes(normalizeOperator(filter.operator))) return true;
+	if (needsConversion(filter.valueType, filter.value)) return true;
+
+	return Array.isArray(filter.value) && filter.value.some((item: unknown) => isRangeEnd(item));
+}
+
 /**
  * Creates an expression for a field, using the field's default operator and an
  * empty value of the right shape.
@@ -163,13 +213,20 @@ export function changeOperator(
 	let arity = getOperatorArity(operator);
 	let value = expression.value;
 
-	if (arity !== previousArity) {
+	// A column only makes sense for comparisons, not for text checks such as
+	// "contains".
+	let holdsColumn =
+		expression.valueType === "column" ||
+		(Array.isArray(value) && value.some((item: unknown) => isRangeEnd(item) && item.valueType === "column"));
+
+	if (arity !== previousArity || (holdsColumn && !supportsColumnValue(operator))) {
 		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);
+	// A dynamic value or a column stays valid across operators of the same arity.
+	let keepsValueType =
+		(expression.valueType === "special" || expression.valueType === "column") && value === expression.value;
+	let valueType = keepsValueType ? expression.valueType : getValueType(field, operator);
 
 	return { ...expression, operator, value, valueType };
 }

package/src/filter/types.ts

@@ -16,14 +16,30 @@ export type FilterExpression = {
 	type: "expression";
 	column: string;
 	operator: string;
-	value: string | string[] | Date | number | null;
+	value: string | string[] | Date | number | null | Array<string | FilterRangeEnd>;
 	valueType: string;
 };
 
 /**
- * The value types understood by the Appframe filter element converter.
+ * One end of a range whose ends are not both plain values, such as a fixed
+ * date and another column. Plain ends may stay plain values next to it; they
+ * then take the expression's `valueType`.
+ *
+ * The framework's data API cannot read these, so a filter holding one is sent
+ * as a filter string. See `needsFilterString`.
+ */
+export type FilterRangeEnd = {
+	valueType: FilterValueType;
+	value: string | number | null;
+};
+
+/**
+ * The value types understood by the Appframe filter element converter, plus
+ * `column`, which compares with another column. Only the `api/filter/convert`
+ * endpoint reads `column`, so a filter using it is sent as a filter string.
  *
  * @see `appframe/Appframe.Web.Core/Filtering/FilterElementConverter.vb`
+ * @see `lib/FilterConversion/FilterObjectReader.cs`
  */
 export type FilterValueType =
 	| "string"
@@ -33,12 +49,15 @@ export type FilterValueType =
 	| "array"
 	| "datetime"
 	| "special"
+	| "column"
 	| "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`).
+ * special-cases (`notequals` for `Not`, `notdatequals` for `NotDateEquals`),
+ * plus the whole-period checks (`islastweek` and so on), which only the
+ * `api/filter/convert` endpoint reads.
  *
  * @see `appframe/Appframe3.Common.Data/Filtering/eOperators.vb`
  */
@@ -74,20 +93,40 @@ export type FilterOperator =
 	| "datelessthan"
 	| "datelessthanorequal"
 	| "datebetween"
-	| "datenotbetween";
+	| "datenotbetween"
+	| "isbeyondthisyear"
+	| "islaterthisyear"
+	| "islaterthismonth"
+	| "isnextweek"
+	| "islaterthisweek"
+	| "istomorrow"
+	| "istoday"
+	| "isyesterday"
+	| "isearlierthisweek"
+	| "islastweek"
+	| "isearlierthismonth"
+	| "isearlierthisyear"
+	| "ispriorthisyear";
 
 /**
  * Dynamic ("special") filter values. These are resolved server-side into a
  * relative date or the current user name, and are sent with
  * `valueType: "special"`.
  *
+ * `Now`, `DayAfterTomorrow` and `TwoWeeksAway` are offered by the Windows
+ * filter editor but have no `eDynamicValue` member, so a filter using them is
+ * sent as a filter string.
+ *
  * @see `appframe/Appframe3.Common.Data/Filtering/eDynamicValue.vb`
  */
 export type DynamicValue =
 	| "CurrentUser"
 	| "Yesterday"
 	| "Today"
+	| "Now"
 	| "Tomorrow"
+	| "DayAfterTomorrow"
+	| "TwoWeeksAway"
 	| "ThisWeek"
 	| "ThisMonth"
 	| "ThisYear"