@olenbetong/appframe-core 2.11.10 → 2.13.0

package/es/filter/describeFilter.js

@@ -0,0 +1,60 @@
+import { getDynamicValueLabel, getOperatorArity, getOperatorLabel, normalizeOperator } from "./operators.js";
+import { isExpression } from "./tree.js";
+/**
+ * Builds a human-readable description of a filter, without contacting the
+ * server. Use this for read-only summaries; the authoritative filter string is
+ * produced by `api/filter/convert`, since only the server can generate the
+ * DevExpress criteria syntax.
+ */
+export function describeFilter(filter, options = {}) {
+    if (!filter)
+        return "";
+    let fieldsByName = new Map((options.fields ?? []).map((field) => [field.name.toLowerCase(), field]));
+    return describe(filter, fieldsByName, 0);
+}
+function describe(item, fields, depth) {
+    if (isExpression(item))
+        return describeExpression(item, fields);
+    let parts = item.items.map((child) => describe(child, fields, depth + 1)).filter((part) => part !== "");
+    if (parts.length === 0)
+        return "";
+    if (parts.length === 1)
+        return parts[0];
+    let separator = item.mode === "or" ? " OR " : " AND ";
+    let joined = parts.join(separator);
+    return depth === 0 ? joined : `(${joined})`;
+}
+function describeExpression(expression, fields) {
+    if (!expression.column || !expression.operator)
+        return "";
+    let field = fields.get(expression.column.toLowerCase());
+    let caption = field?.caption ?? expression.column;
+    let operator = normalizeOperator(expression.operator);
+    let label = getOperatorLabel(operator, field?.type);
+    let arity = getOperatorArity(operator);
+    if (arity === "none")
+        return `[${caption}] ${label}`;
+    return `[${caption}] ${label} ${formatValue(expression, arity)}`;
+}
+function formatValue(expression, arity) {
+    let { value, valueType } = expression;
+    if (valueType === "special" && typeof value === "string") {
+        return getDynamicValueLabel(value);
+    }
+    if (Array.isArray(value)) {
+        let formatted = value.map((item) => formatScalar(item, valueType));
+        return arity === "pair" ? formatted.join(" - ") : `(${formatted.join(", ")})`;
+    }
+    return formatScalar(value, valueType);
+}
+function formatScalar(value, valueType) {
+    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);
+    if (valueType === "number" || valueType === "boolean")
+        return String(value);
+    return `'${String(value)}'`;
+}

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

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

package/es/filter/describeFilter.test.js

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "vitest";
+import { describeFilter } from "./describeFilter.js";
+import { createEmptyFilter } from "./tree.js";
+const fields = [
+    { name: "PersonID", caption: "Person ID", type: "string" },
+    { name: "Created", caption: "Created", type: "date" },
+    { name: "Amount", caption: "Amount", type: "number" },
+];
+function expression(column, operator, value, valueType = "string") {
+    return { type: "expression", column, operator, value, valueType };
+}
+describe("describeFilter", () => {
+    test("empty filters describe as an empty string", () => {
+        expect(describeFilter(null)).toBe("");
+        expect(describeFilter(createEmptyFilter())).toBe("");
+    });
+    test("uses the field caption when available", () => {
+        let filter = expression("PersonID", "contains", "silv");
+        expect(describeFilter(filter, { fields })).toBe("[Person ID] Contains 'silv'");
+    });
+    test("falls back to the column name when the field is unknown", () => {
+        expect(describeFilter(expression("Unknown", "equals", "x"), { fields })).toBe("[Unknown] Equal to 'x'");
+    });
+    test("parameterless operators render without a value", () => {
+        expect(describeFilter(expression("PersonID", "isnull", null, "null"), { fields })).toBe("[Person ID] Is null");
+    });
+    test("numbers are not quoted", () => {
+        expect(describeFilter(expression("Amount", "greaterthan", 100, "number"), { fields })).toBe("[Amount] Greater than 100");
+    });
+    test("date fields use the relative operator wording", () => {
+        expect(describeFilter(expression("Created", "greaterthan", "2026-01-01", "datetime"), { fields })).toBe("[Created] After '2026-01-01'");
+    });
+    test("dynamic values render as their label", () => {
+        expect(describeFilter(expression("Created", "equals", "ThisMonth", "special"), { fields })).toBe("[Created] Equal to This month");
+    });
+    test("between renders a range", () => {
+        expect(describeFilter(expression("Amount", "between", ["1", "9"], "number"), { fields })).toBe("[Amount] Between 1 - 9");
+    });
+    test("in list renders a parenthesised list", () => {
+        expect(describeFilter(expression("PersonID", "inlist", ["a", "b"]), { fields })).toBe("[Person ID] In list ('a', 'b')");
+    });
+    test("groups are joined by their mode and nested groups are parenthesised", () => {
+        let filter = {
+            type: "group",
+            mode: "or",
+            items: [
+                {
+                    type: "group",
+                    mode: "and",
+                    items: [expression("PersonID", "equals", "a"), expression("Amount", "greaterthan", 5, "number")],
+                },
+                { type: "group", mode: "and", items: [expression("PersonID", "equals", "b")] },
+            ],
+        };
+        expect(describeFilter(filter, { fields })).toBe("([Person ID] Equal to 'a' AND [Amount] Greater than 5) OR [Person ID] Equal to 'b'");
+    });
+    test("empty groups are omitted", () => {
+        let filter = {
+            type: "group",
+            mode: "or",
+            items: [
+                { type: "group", mode: "and", items: [expression("PersonID", "equals", "a")] },
+                { type: "group", mode: "and", items: [] },
+            ],
+        };
+        expect(describeFilter(filter, { fields })).toBe("[Person ID] Equal to 'a'");
+    });
+});

package/es/filter/fields.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Field metadata for the filter builder.
+ *
+ * `sviw_WebSiteCMS_FilterBuilder_ViewFields` normalizes the SQL data types into
+ * the handful of types the builder groups fields by, so the mapping here is
+ * mostly a rename. The loading lives in `useFilterFields` in
+ * `@olenbetong/appframe-react`.
+ */
+import type { FieldMetadata, FilterFieldType } from "./types.js";
+/** A raw `sviw_WebSiteCMS_FilterBuilder_ViewFields` record. */
+export type ViewFieldRecord = {
+    FieldName?: string | null;
+    /** Already normalized by the view; anything unexpected is treated as text. */
+    DataType?: string | null;
+    DBObjectID?: string | null;
+    Nullable?: boolean | number | null;
+    ExcludeFromFilter?: boolean | number | null;
+    ValueListRecordSource?: string | null;
+};
+/** The builder type for a normalized `DataType`. Unknown types are filtered as text. */
+export declare function toFilterFieldType(dataType: string | null | undefined): FilterFieldType;
+/** Maps a view field record onto the metadata the builder renders. */
+export declare function toFieldMetadata(record: ViewFieldRecord): FieldMetadata;
+/**
+ * Maps and sorts view field records. Fields the view marks as excluded are
+ * dropped rather than hidden, since nothing else can use them.
+ */
+export declare function toFieldMetadataList(records: ViewFieldRecord[]): FieldMetadata[];

package/es/filter/fields.js

@@ -0,0 +1,37 @@
+/**
+ * Field metadata for the filter builder.
+ *
+ * `sviw_WebSiteCMS_FilterBuilder_ViewFields` normalizes the SQL data types into
+ * the handful of types the builder groups fields by, so the mapping here is
+ * mostly a rename. The loading lives in `useFilterFields` in
+ * `@olenbetong/appframe-react`.
+ */
+const FIELD_TYPES = ["string", "number", "boolean", "date", "datetime", "uniqueidentifier"];
+/** The builder type for a normalized `DataType`. Unknown types are filtered as text. */
+export function toFilterFieldType(dataType) {
+    let normalized = dataType?.trim().toLowerCase();
+    return FIELD_TYPES.find((type) => type === normalized) ?? "string";
+}
+function toBoolean(value) {
+    return value === true || value === 1;
+}
+/** Maps a view field record onto the metadata the builder renders. */
+export function toFieldMetadata(record) {
+    return {
+        name: record.FieldName ?? "",
+        type: toFilterFieldType(record.DataType),
+        nullable: toBoolean(record.Nullable),
+        excludeFromFilter: toBoolean(record.ExcludeFromFilter),
+        valueListRecordSource: record.ValueListRecordSource || undefined,
+    };
+}
+/**
+ * Maps and sorts view field records. Fields the view marks as excluded are
+ * dropped rather than hidden, since nothing else can use them.
+ */
+export function toFieldMetadataList(records) {
+    return records
+        .map(toFieldMetadata)
+        .filter((field) => field.name !== "" && !field.excludeFromFilter)
+        .sort((a, b) => a.name.localeCompare(b.name));
+}

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

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

package/es/filter/fields.test.js

@@ -0,0 +1,49 @@
+import { describe, expect, test } from "vitest";
+import { toFieldMetadata, toFieldMetadataList, toFilterFieldType } from "./fields.js";
+describe("toFilterFieldType", () => {
+    test("passes through the types the view normalizes to", () => {
+        expect(toFilterFieldType("boolean")).toBe("boolean");
+        expect(toFilterFieldType("datetime")).toBe("datetime");
+        expect(toFilterFieldType("uniqueidentifier")).toBe("uniqueidentifier");
+    });
+    test("an unknown or missing type is filtered as text", () => {
+        expect(toFilterFieldType("geography")).toBe("string");
+        expect(toFilterFieldType(null)).toBe("string");
+    });
+});
+describe("toFieldMetadata", () => {
+    test("maps a record", () => {
+        let field = toFieldMetadata({
+            FieldName: "PersonID",
+            DataType: "string",
+            Nullable: true,
+            ExcludeFromFilter: false,
+            ValueListRecordSource: "<afRecordSource />",
+        });
+        expect(field).toEqual({
+            name: "PersonID",
+            type: "string",
+            nullable: true,
+            excludeFromFilter: false,
+            valueListRecordSource: "<afRecordSource />",
+        });
+    });
+    test("bit columns arrive as numbers", () => {
+        expect(toFieldMetadata({ FieldName: "A", Nullable: 1 }).nullable).toBe(true);
+        expect(toFieldMetadata({ FieldName: "A", Nullable: 0 }).nullable).toBe(false);
+    });
+    test("an empty record source is dropped rather than kept as an empty string", () => {
+        expect(toFieldMetadata({ FieldName: "A", ValueListRecordSource: "" }).valueListRecordSource).toBeUndefined();
+    });
+});
+describe("toFieldMetadataList", () => {
+    test("sorts by name and drops excluded and unnamed fields", () => {
+        let fields = toFieldMetadataList([
+            { FieldName: "Name", DataType: "string" },
+            { FieldName: "Age", DataType: "number" },
+            { FieldName: "CDL", DataType: "boolean", ExcludeFromFilter: true },
+            { FieldName: "", DataType: "string" },
+        ]);
+        expect(fields.map((field) => field.name)).toEqual(["Age", "Name"]);
+    });
+});

package/es/filter/index.d.ts

@@ -0,0 +1,8 @@
+export { type ConvertRequest, convertFilter, type FilterConversionResult } from "./convertFilter.js";
+export { describeFilter, type DescribeFilterOptions } from "./describeFilter.js";
+export { toFieldMetadata, toFieldMetadataList, toFilterFieldType, type ViewFieldRecord } from "./fields.js";
+export { getDefaultOperator, getDynamicValueLabel, getDynamicValuesForField, getOperatorArity, getOperatorLabel, getOperatorsForField, getValueType, normalizeOperator, type OperatorArity, RELATIVE_DATE_VALUES, } from "./operators.js";
+export { coerceToStandardLayout, isStandardLayout } from "./standardLayout.js";
+export { canDeleteSavedFilter, canEditSavedFilter, canRenameSavedFilter, canSetCrossDomain, canShareSavedFilter, findSavedFilter, NO_FILTER_ID, partitionSavedFilters, type SavedFilter, type SavedFilterRecord, toSavedFilter, toSavedFilters, } from "./savedFilters.js";
+export { addGroupAtPath, changeOperator, countExpressions, createEmptyFilter, createEmptyGroup, createExpression, type FilterNode, type FilterPath, getNodeAtPath, insertNodeAtPath, isCompleteExpression, isEmptyFilter, isExpression, isGroup, pruneFilter, removeNodeAtPath, setGroupMode, toFilterTree, updateNodeAtPath, } from "./tree.js";
+export type { DynamicValue, FieldMetadata, FilterAccessLevel, FilterExpression, FilterFieldType, FilterGroup, FilterOperator, FilterTree, FilterValueType, } from "./types.js";

package/es/filter/index.js

@@ -0,0 +1,7 @@
+export { convertFilter } from "./convertFilter.js";
+export { describeFilter } from "./describeFilter.js";
+export { toFieldMetadata, toFieldMetadataList, toFilterFieldType } from "./fields.js";
+export { getDefaultOperator, getDynamicValueLabel, getDynamicValuesForField, getOperatorArity, getOperatorLabel, getOperatorsForField, getValueType, normalizeOperator, RELATIVE_DATE_VALUES, } from "./operators.js";
+export { coerceToStandardLayout, isStandardLayout } from "./standardLayout.js";
+export { canDeleteSavedFilter, canEditSavedFilter, canRenameSavedFilter, canSetCrossDomain, canShareSavedFilter, findSavedFilter, NO_FILTER_ID, partitionSavedFilters, toSavedFilter, toSavedFilters, } from "./savedFilters.js";
+export { addGroupAtPath, changeOperator, countExpressions, createEmptyFilter, createEmptyGroup, createExpression, getNodeAtPath, insertNodeAtPath, isCompleteExpression, isEmptyFilter, isExpression, isGroup, pruneFilter, removeNodeAtPath, setGroupMode, toFilterTree, updateNodeAtPath, } from "./tree.js";

package/es/filter/operators.d.ts

@@ -0,0 +1,37 @@
+import type { DynamicValue, FieldMetadata, FilterFieldType, FilterOperator, FilterValueType } from "./types.js";
+/** How many values an operator needs. */
+export type OperatorArity = "none" | "single" | "pair" | "list";
+export declare function getOperatorArity(operator: FilterOperator): OperatorArity;
+/**
+ * Returns the localized label for an operator. Date fields get the
+ * "After"/"Before" wording instead of "Greater than"/"Less than".
+ */
+export declare function getOperatorLabel(operator: FilterOperator, fieldType?: FilterFieldType): string;
+/**
+ * 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 declare function getOperatorsForField(field: Pick<FieldMetadata, "type" | "nullable">): FilterOperator[];
+export declare function getDefaultOperator(field: Pick<FieldMetadata, "type">): FilterOperator;
+/**
+ * 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 declare function getValueType(field: Pick<FieldMetadata, "type">, operator: FilterOperator): FilterValueType;
+/** Relative date values offered in the date value editor, in menu order. */
+export declare const RELATIVE_DATE_VALUES: DynamicValue[];
+export declare function getDynamicValueLabel(value: DynamicValue): string;
+/**
+ * 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 declare function getDynamicValuesForField(field: Pick<FieldMetadata, "type">): DynamicValue[];
+/**
+ * Normalizes an operator string coming from the server or from another filter
+ * producer (`AfGrid` emits PascalCase names) to the canonical lower-case form.
+ */
+export declare function normalizeOperator(operator: string): FilterOperator;

package/es/filter/operators.js

@@ -0,0 +1,235 @@
+import { getLocalizedString } from "../getLocalizedString.js";
+/**
+ * Operators that take no value at all.
+ *
+ * `eOperators.ParameterLessChecks` plus the blank checks.
+ */
+const PARAMETERLESS_OPERATORS = ["isnull", "isnotnull", "istrue", "isfalse", "isblank", "isnotblank"];
+/** Operators whose value is a two element `[from, to]` array. */
+const PAIR_OPERATORS = ["between", "notbetween", "datebetween", "datenotbetween"];
+/** Operators whose value is an array of values. */
+const LIST_OPERATORS = ["inlist", "notinlist"];
+export function getOperatorArity(operator) {
+    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 = {
+    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 = {
+    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, fieldType) {
+    let isDate = fieldType === "date" || fieldType === "datetime";
+    let label = (isDate ? DATE_OPERATOR_LABELS[operator] : undefined) ?? OPERATOR_LABELS[operator];
+    return getLocalizedString(label ?? operator);
+}
+const EQUALITY = ["equals", "notequals"];
+const LIST_CHECKS = ["inlist", "notinlist"];
+const RANGE = ["between", "notbetween"];
+const COMPARISONS = ["greaterthan", "greaterthanorequal", "lessthan", "lessthanorequal"];
+const STRING_CHECKS = [
+    "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 = {
+    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.
+ *
+ * Text defaults to `contains` because a substring search is what people
+ * reach for when they type into a filter box without picking an operator —
+ * `beginswith` silently misses matches in the middle of the value.
+ */
+const DEFAULT_OPERATOR_BY_TYPE = {
+    date: "equals",
+    datetime: "equals",
+    number: "equals",
+    boolean: "istrue",
+    string: "contains",
+    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) {
+    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) {
+    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, operator) {
+    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 = [
+    "Yesterday",
+    "Today",
+    "Tomorrow",
+    "ThisWeek",
+    "ThisMonth",
+    "ThisYear",
+    "LastWeek",
+    "LastMonth",
+    "LastYear",
+    "NextWeek",
+    "NextMonth",
+    "NextYear",
+];
+const DYNAMIC_VALUE_LABELS = {
+    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) {
+    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) {
+    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 = {
+    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) {
+    let normalized = operator.toLowerCase().replace(/[\s,]/g, "");
+    return OPERATOR_ALIASES[normalized] ?? normalized;
+}

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

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

package/es/filter/operators.test.js

@@ -0,0 +1,107 @@
+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" });
+        expect(operators).toEqual(getOperatorsForField({ type: "string" }));
+    });
+});
+describe("getDefaultOperator", () => {
+    test.each([
+        ["string", "contains"],
+        ["uniqueidentifier", "beginswith"],
+        ["number", "equals"],
+        ["date", "equals"],
+        ["datetime", "equals"],
+        ["boolean", "istrue"],
+    ])("%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"],
+    ])("%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"],
+    ])("%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([]);
+    });
+});