@getaster/data 0.0.0-stage → 0.1.0-preview.0

package/dist/criteria/ast.d.ts

@@ -0,0 +1,79 @@
+import type { Value } from "../schema/model.ts";
+/**
+ * A date relative to when a query runs: today, or now, taken to the start
+ * of its week (Monday) or month if asked, then moved by whole units. It stays
+ * symbolic in a query or a published filter and is resolved at each fetch,
+ * so "due this week" is still right next week.
+ */
+export interface RelativeDate {
+    readonly relative: "today" | "now";
+    readonly days?: number;
+    readonly weeks?: number;
+    readonly months?: number;
+    readonly startOf?: "week" | "month";
+}
+/**
+ * Compiled to `$filter`, and evaluated locally with the same OData semantics.
+ * Comparisons are property against literal, or property against property of
+ * the same type, so local evaluation can match the server exactly.
+ */
+export type Criteria = {
+    readonly op: "and" | "or";
+    readonly args: readonly Criteria[];
+} | {
+    readonly op: "not";
+    readonly arg: Criteria;
+} | {
+    readonly op: "eq" | "ne" | "gt" | "ge" | "lt" | "le";
+    readonly field: string;
+    /** A relative date on a date field; resolved (`resolveRelative`) before compiling or evaluating. */
+    readonly value: Value | RelativeDate;
+} | {
+    readonly op: "eq" | "ne" | "gt" | "ge" | "lt" | "le";
+    readonly field: string;
+    /** Another property of the same type, compared with `field`. */
+    readonly other: string;
+} | {
+    readonly op: "in";
+    readonly field: string;
+    readonly values: readonly Value[];
+} | {
+    readonly op: "contains" | "startswith" | "endswith";
+    readonly field: string;
+    readonly value: string;
+    /** Compare through `tolower()` on both sides. */
+    readonly caseInsensitive?: boolean;
+}
+/**
+ * Over a to-many navigation (`answers`): some related record matches
+ * `where`, or every one does (so `all` of none holds). `where` names the
+ * related records' properties.
+ */
+ | {
+    readonly op: "any" | "all";
+    readonly field: string;
+    readonly where: Criteria;
+}
+/**
+ * Through a single-valued navigation (`project`): the related record
+ * matches `where`, which names its properties. Compiles to a path
+ * (`project/health eq 'behind'`); with no related record its properties
+ * are null, as on the server.
+ */
+ | {
+    readonly op: "via";
+    readonly field: string;
+    readonly where: Criteria;
+};
+export interface SortKey {
+    readonly field: string;
+    readonly descending?: boolean;
+}
+/** The query a collection is a window over. */
+export interface Query {
+    readonly set: string;
+    readonly filter?: Criteria;
+    /** The key properties are appended as tie-breakers, as the server does. */
+    readonly orderBy?: readonly SortKey[];
+    readonly select?: readonly string[];
+}

package/dist/criteria/ast.js

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

package/dist/criteria/compile.d.ts

@@ -0,0 +1,37 @@
+import type { EntitySet, EntityType, Field, Schema, Value } from "../schema/model.ts";
+import type { Criteria, Query, SortKey } from "./ast.ts";
+import { CriteriaError } from "./values.ts";
+export { CriteriaError };
+/** The OData URL literal for `value` as a `field`-typed value. */
+export declare function formatLiteral(value: Value, field: Field): string;
+/** The right-hand property of a property comparison: it must have `left`'s type. */
+export declare function otherOf(type: EntityType, name: string, left: Field, set?: EntitySet): Field;
+/** The `$filter` text (not percent-encoded). Throws `CriteriaError`. `any` and `all` need the schema. */
+export declare function toFilter(criteria: Criteria, type: EntityType, set?: EntitySet, schema?: Schema): string;
+/** `sort` with the key properties appended ascending, skipping keys already sorted on. */
+export declare function withKeyTieBreakers(sort: readonly SortKey[], type: EntityType): readonly SortKey[];
+/**
+ * A sort key's field. A key can be a path through single-valued
+ * navigations (`person/name`), which needs the schema to follow.
+ */
+export declare function checkSortable(key: SortKey, type: EntityType, set?: EntitySet, schema?: Schema): Field;
+/** The `$orderby` text, key tie-breakers included. */
+export declare function toOrderBy(sort: readonly SortKey[], type: EntityType, schema?: Schema): string;
+export declare function isPath(field: string): boolean;
+/** The field at the end of `nav/.../field`, through single-valued navigations only. */
+export declare function resolvePath(path: string, type: EntityType, schema: Schema | undefined): Field;
+/** `$filter`, `$orderby` and `$select` as `a=b&c=d` with encoded values, no leading `?`. */
+export declare function toQueryString(query: Query, schema: Schema): string;
+/** One aggregate over a property (OData Data Aggregation `with`). */
+export interface Aggregate {
+    readonly field: string;
+    readonly method: "sum" | "min" | "max" | "average" | "countdistinct";
+    readonly as: string;
+}
+/**
+ * `$apply` text: the filter, then grouping by `groupBy` (or none) with the
+ * row count as `count` and each aggregate under its alias.
+ */
+export declare function toApply(type: EntityType, filter: Criteria | undefined, groupBy: readonly string[], aggregates: readonly Aggregate[], set?: EntitySet, schema?: Schema): string;
+/** Queries built afresh are equal when they say the same thing. */
+export declare function sameQuery(a: Query, b: Query): boolean;

package/dist/criteria/compile.js

@@ -0,0 +1,233 @@
+import { assertLiteral, CriteriaError, plain } from "./values.js";
+export { CriteriaError };
+/** The OData URL literal for `value` as a `field`-typed value. */
+export function formatLiteral(value, field) {
+    if (value === null)
+        return "null";
+    assertLiteral(value, field);
+    switch (field.type) {
+        case "Edm.String":
+            return `'${value.replaceAll("'", "''")}'`;
+        case "Edm.Single":
+        case "Edm.Double": {
+            const n = value;
+            if (Number.isNaN(n))
+                return "NaN";
+            if (n === Infinity)
+                return "INF";
+            if (n === -Infinity)
+                return "-INF";
+            return Object.is(n, -0) ? "0" : String(n);
+        }
+        case "Edm.Duration":
+            return `duration'${value}'`;
+        default:
+            return String(value);
+    }
+}
+function fieldOf(type, name, set) {
+    const f = type.field(name);
+    if (!f)
+        throw new CriteriaError(`unknown field '${name}' on ${type.name}`);
+    if (set?.nonFilterable.has(name))
+        throw new CriteriaError(`field '${name}' is not filterable`);
+    return f;
+}
+/** The right-hand property of a property comparison: it must have `left`'s type. */
+export function otherOf(type, name, left, set) {
+    const f = fieldOf(type, name, set);
+    if (f.type !== left.type)
+        throw new CriteriaError(`can't compare ${left.name} (${left.type}) with ${f.name} (${f.type})`);
+    return f;
+}
+const TOP = { schema: undefined, prefix: "", depth: 0 };
+// `and` binds tighter than `or`; every other node is atomic or self-delimiting.
+function render(c, type, set, nested, at = TOP) {
+    const p = at.prefix;
+    switch (c.op) {
+        case "and":
+        case "or": {
+            if (c.args.length === 0)
+                return c.op === "and" ? "true" : "false";
+            if (c.args.length === 1)
+                return render(c.args[0], type, set, nested, at);
+            const text = c.args.map((a) => render(a, type, set, true, at)).join(` ${c.op} `);
+            return nested ? `(${text})` : text;
+        }
+        case "not":
+            return `not (${render(c.arg, type, set, false, at)})`;
+        case "any":
+        case "all": {
+            const nav = type.navigation(c.field);
+            if (!nav)
+                throw new CriteriaError(`unknown navigation '${c.field}' on ${type.name}`);
+            if (!nav.collection)
+                throw new CriteriaError(`'${c.field}' on ${type.name} isn't a collection; ${c.op} needs one`);
+            if (!at.schema)
+                throw new CriteriaError(`${c.op} over '${c.field}' needs the schema to follow it`);
+            const target = at.schema.set(nav.target);
+            const v = `x${at.depth}`;
+            return `${p}${nav.name}/${c.op}(${v}:${render(c.where, target.type, target, false, { schema: at.schema, prefix: `${v}/`, depth: at.depth + 1 })})`;
+        }
+        case "via": {
+            const nav = type.navigation(c.field);
+            if (!nav)
+                throw new CriteriaError(`unknown navigation '${c.field}' on ${type.name}`);
+            if (nav.collection)
+                throw new CriteriaError(`'${c.field}' on ${type.name} is a collection; via follows a single record, any and all a collection`);
+            if (!at.schema)
+                throw new CriteriaError(`via '${c.field}' needs the schema to follow it`);
+            const target = at.schema.set(nav.target);
+            return render(c.where, target.type, target, nested, { ...at, prefix: `${p}${nav.name}/` });
+        }
+        case "eq":
+        case "ne":
+        case "gt":
+        case "ge":
+        case "lt":
+        case "le": {
+            const f = fieldOf(type, c.field, set);
+            if ("other" in c)
+                return `${p}${f.name} ${c.op} ${p}${otherOf(type, c.other, f, set).name}`;
+            const value = plain(c.value);
+            if (c.op === "eq" || c.op === "ne")
+                return `${p}${f.name} ${c.op} ${formatLiteral(value, f)}`;
+            if (value === null)
+                throw new CriteriaError(`${c.op} ${f.name}: null is not orderable`);
+            return `${p}${f.name} ${c.op} ${formatLiteral(value, f)}`;
+        }
+        case "in": {
+            const f = fieldOf(type, c.field, set);
+            if (c.values.length === 0)
+                return "false";
+            return `${p}${f.name} in (${c.values.map((v) => formatLiteral(v, f)).join(",")})`;
+        }
+        case "contains":
+        case "startswith":
+        case "endswith": {
+            const f = fieldOf(type, c.field, set);
+            if (f.type !== "Edm.String")
+                throw new CriteriaError(`${c.op} needs a string field, ${f.name} is ${f.type}`);
+            if (typeof c.value !== "string")
+                throw new CriteriaError(`${c.op} ${f.name}: expected a string`);
+            return c.caseInsensitive
+                ? `${c.op}(tolower(${p}${f.name}),${formatLiteral(c.value.toLowerCase(), f)})`
+                : `${c.op}(${p}${f.name},${formatLiteral(c.value, f)})`;
+        }
+    }
+}
+/** The `$filter` text (not percent-encoded). Throws `CriteriaError`. `any` and `all` need the schema. */
+export function toFilter(criteria, type, set, schema) {
+    return render(criteria, type, set, false, { ...TOP, schema });
+}
+/** `sort` with the key properties appended ascending, skipping keys already sorted on. */
+export function withKeyTieBreakers(sort, type) {
+    const seen = new Set(sort.map((k) => k.field));
+    return [...sort, ...type.key.filter((k) => !seen.has(k)).map((field) => ({ field }))];
+}
+/**
+ * A sort key's field. A key can be a path through single-valued
+ * navigations (`person/name`), which needs the schema to follow.
+ */
+export function checkSortable(key, type, set, schema) {
+    if (isPath(key.field)) {
+        const nav = key.field.split("/")[0];
+        if (set?.nonSortable.has(nav))
+            throw new CriteriaError(`'${key.field}' is not sortable: ${nav} is not`);
+        return resolvePath(key.field, type, schema);
+    }
+    const f = type.field(key.field);
+    if (!f)
+        throw new CriteriaError(`unknown field '${key.field}' on ${type.name}`);
+    if (f.type === "Edm.Binary")
+        throw new CriteriaError(`field '${key.field}' cannot be sorted`);
+    if (set?.nonSortable.has(key.field))
+        throw new CriteriaError(`field '${key.field}' is not sortable`);
+    return f;
+}
+/** The `$orderby` text, key tie-breakers included. */
+export function toOrderBy(sort, type, schema) {
+    return withKeyTieBreakers(sort, type)
+        .map((k) => (checkSortable(k, type, undefined, schema), `${k.field}${k.descending ? " desc" : ""}`))
+        .join(",");
+}
+export function isPath(field) {
+    return field.includes("/");
+}
+/** The field at the end of `nav/.../field`, through single-valued navigations only. */
+export function resolvePath(path, type, schema) {
+    if (!schema)
+        throw new CriteriaError(`'${path}' is a path; following it needs the schema`);
+    const steps = path.split("/");
+    let at = type;
+    for (const step of steps.slice(0, -1)) {
+        const nav = at.navigation(step);
+        if (!nav)
+            throw new CriteriaError(`unknown navigation '${step}' on ${at.name}`);
+        if (nav.collection)
+            throw new CriteriaError(`'${step}' on ${at.name} is a collection; a path can only follow single records`);
+        at = schema.set(nav.target).type;
+    }
+    const name = steps.at(-1);
+    const f = at.field(name);
+    if (!f)
+        throw new CriteriaError(`unknown field '${name}' on ${at.name}`);
+    if (f.type === "Edm.Binary")
+        throw new CriteriaError(`field '${path}' cannot be sorted`);
+    return f;
+}
+/** `$filter`, `$orderby` and `$select` as `a=b&c=d` with encoded values, no leading `?`. */
+export function toQueryString(query, schema) {
+    const set = schema.set(query.set);
+    const type = set.type;
+    const parts = [];
+    if (query.filter)
+        parts.push(`$filter=${encodeURIComponent(toFilter(query.filter, type, set, schema))}`);
+    const orderBy = query.orderBy ?? [];
+    for (const k of orderBy)
+        checkSortable(k, type, set, schema);
+    parts.push(`$orderby=${encodeURIComponent(toOrderBy(orderBy, type, schema))}`);
+    if (query.select && query.select.length > 0) {
+        for (const s of query.select) {
+            if (!type.field(s))
+                throw new CriteriaError(`unknown field '${s}' on ${type.name}`);
+        }
+        parts.push(`$select=${encodeURIComponent(query.select.join(","))}`);
+    }
+    return parts.join("&");
+}
+/**
+ * `$apply` text: the filter, then grouping by `groupBy` (or none) with the
+ * row count as `count` and each aggregate under its alias.
+ */
+export function toApply(type, filter, groupBy, aggregates, set, schema) {
+    for (const g of groupBy)
+        fieldOf(type, g, set);
+    const aliases = new Set(["count", ...groupBy]);
+    for (const a of aggregates) {
+        const field = fieldOf(type, a.field, set);
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(a.as) || aliases.has(a.as))
+            throw new CriteriaError(`Invalid or duplicate aggregate alias ${a.as}`);
+        aliases.add(a.as);
+        switch (a.method) {
+            case "sum":
+            case "average":
+                if (!["Edm.Byte", "Edm.SByte", "Edm.Int16", "Edm.Int32", "Edm.Int64", "Edm.Single", "Edm.Double", "Edm.Decimal"].includes(field.type))
+                    throw new CriteriaError(`${a.method} requires a numeric field`);
+                break;
+            case "min":
+            case "max":
+            case "countdistinct":
+                break;
+            default:
+                throw new CriteriaError(`Unknown aggregate method ${String(a.method)}`);
+        }
+    }
+    const values = ["$count as count", ...aggregates.map((a) => `${a.field} with ${a.method} as ${a.as}`)].join(",");
+    const step = groupBy.length ? `groupby((${groupBy.join(",")}),aggregate(${values}))` : `aggregate(${values})`;
+    return filter ? `filter(${render(filter, type, set, false, { ...TOP, schema })})/${step}` : step;
+}
+/** Queries built afresh are equal when they say the same thing. */
+export function sameQuery(a, b) {
+    return a === b || JSON.stringify(a) === JSON.stringify(b);
+}

package/dist/criteria/evaluate.d.ts

@@ -0,0 +1,20 @@
+import type { Entity, EntityType, Field, Value } from "../schema/model.ts";
+import type { Criteria, SortKey } from "./ast.ts";
+/** The type of the records a navigation leads to, for `any`, `all` and `via`. */
+export type Related = (from: EntityType, navigation: string) => EntityType | undefined;
+/**
+ * Whether `entity` satisfies `criteria`, with the server's `$filter`
+ * semantics (null and unknown both exclude). `any` and `all` read the
+ * related records from the entity, as a list, and `via` the related record,
+ * typed by `related`. A test of a field in `unknown` (hidden on the record)
+ * is unknown, whatever value the entity holds, so `eq null` and `ne` can't
+ * decide on it either.
+ */
+export declare function matches(criteria: Criteria, entity: Entity, type: EntityType, related?: Related, unknown?: ReadonlySet<string>): boolean;
+/**
+ * Ascending total order for sorting: null first, a NaN after every number and
+ * equal to other NaNs. Descending sorts reverse all of it.
+ */
+export declare function compareValues(a: Value, b: Value, field: Field): number;
+/** Orders entities as `$orderby=<sort>` (key tie-breakers appended) does. */
+export declare function sortComparator(sort: readonly SortKey[], type: EntityType): (a: Entity, b: Entity) => number;

package/dist/criteria/evaluate.js

@@ -0,0 +1,171 @@
+import { checkSortable, otherOf, withKeyTieBreakers } from "./compile.js";
+import { assertLiteral, CriteriaError, isNaNValue, ordering, plain } from "./values.js";
+function fieldOf(type, name) {
+    const f = type.field(name);
+    if (!f)
+        throw new CriteriaError(`unknown field '${name}' on ${type.name}`);
+    return f;
+}
+function lower(s) {
+    // Matches Rust `str::to_lowercase`: full Unicode mapping with final-sigma handling.
+    return s.toLowerCase();
+}
+function evalNode(c, e, type, related, unknownFields) {
+    switch (c.op) {
+        case "and": {
+            let unknown = false;
+            for (const a of c.args) {
+                const t = evalNode(a, e, type, related, unknownFields);
+                if (t === false)
+                    return false;
+                if (t === null)
+                    unknown = true;
+            }
+            return unknown ? null : true;
+        }
+        case "or": {
+            let unknown = false;
+            for (const a of c.args) {
+                const t = evalNode(a, e, type, related, unknownFields);
+                if (t === true)
+                    return true;
+                if (t === null)
+                    unknown = true;
+            }
+            return unknown ? null : false;
+        }
+        case "not": {
+            const t = evalNode(c.arg, e, type, related, unknownFields);
+            return t === null ? null : !t;
+        }
+        case "any":
+        case "all": {
+            if (unknownFields?.has(c.field))
+                return null;
+            const target = related?.(type, c.field);
+            if (!target)
+                throw new CriteriaError(`${c.op} over '${c.field}' needs the related records' type`);
+            const rows = e[c.field];
+            if (!Array.isArray(rows))
+                throw new CriteriaError(`'${c.field}' isn't loaded as a list of records`);
+            // OData lambdas: a row whose test is unknown counts as not matching.
+            return c.op === "any"
+                ? rows.some((r) => evalNode(c.where, r, target, related) === true)
+                : rows.every((r) => evalNode(c.where, r, target, related) === true);
+        }
+        case "via": {
+            const target = related?.(type, c.field);
+            if (!target)
+                throw new CriteriaError(`via '${c.field}' needs the related record's type`);
+            const record = e[c.field];
+            if (record === undefined || (record !== null && typeof record !== "object"))
+                throw new CriteriaError(`'${c.field}' isn't loaded as a record`);
+            // No related record: its properties are all null, as on the server.
+            return evalNode(c.where, (record ?? {}), target, related);
+        }
+        case "eq":
+        case "ne":
+        case "gt":
+        case "ge":
+        case "lt":
+        case "le": {
+            const f = fieldOf(type, c.field);
+            if (unknownFields?.has(c.field) || ("other" in c && unknownFields?.has(c.other)))
+                return null;
+            let right;
+            if ("other" in c) {
+                right = e[otherOf(type, c.other, f).name] ?? null;
+            }
+            else {
+                right = plain(c.value);
+                assertLiteral(right, f);
+            }
+            const v = e[c.field] ?? null;
+            if (c.op === "eq" || c.op === "ne") {
+                // P2 5.1.1.1.1-2: null equals only null; `ne` is the exact negation.
+                const equal = v === null || right === null ? v === right : ordering(v, right, f) === 0;
+                return c.op === "eq" ? equal : !equal;
+            }
+            // P2 5.1.1.1.3: any null operand gives false, not unknown, so `not` of it is true.
+            if (v === null || right === null)
+                return false;
+            const o = ordering(v, right, f);
+            if (o === undefined)
+                return false;
+            return c.op === "gt" ? o > 0 : c.op === "ge" ? o >= 0 : c.op === "lt" ? o < 0 : o <= 0;
+        }
+        case "in": {
+            const f = fieldOf(type, c.field);
+            if (unknownFields?.has(c.field))
+                return null;
+            const v = e[c.field] ?? null;
+            for (const x of c.values)
+                assertLiteral(x, f);
+            // `in` is eq-based: a null needle matches a null member, and the result is never unknown.
+            if (v === null)
+                return c.values.includes(null);
+            return c.values.some((x) => x !== null && ordering(v, x, f) === 0);
+        }
+        case "contains":
+        case "startswith":
+        case "endswith": {
+            const f = fieldOf(type, c.field);
+            if (f.type !== "Edm.String")
+                throw new CriteriaError(`${c.op} needs a string field, ${f.name} is ${f.type}`);
+            if (typeof c.value !== "string")
+                throw new CriteriaError(`${c.op} ${f.name}: expected a string`);
+            if (unknownFields?.has(c.field))
+                return null;
+            const v = e[c.field] ?? null;
+            // Functions of a null argument are null, and `not` of null stays null (row excluded).
+            if (v === null)
+                return null;
+            if (typeof v !== "string")
+                throw new CriteriaError(`${f.name}: expected a string, got ${JSON.stringify(v)}`);
+            const h = c.caseInsensitive ? lower(v) : v;
+            const n = c.caseInsensitive ? lower(c.value) : c.value;
+            return c.op === "contains" ? h.includes(n) : c.op === "startswith" ? h.startsWith(n) : h.endsWith(n);
+        }
+    }
+}
+/**
+ * Whether `entity` satisfies `criteria`, with the server's `$filter`
+ * semantics (null and unknown both exclude). `any` and `all` read the
+ * related records from the entity, as a list, and `via` the related record,
+ * typed by `related`. A test of a field in `unknown` (hidden on the record)
+ * is unknown, whatever value the entity holds, so `eq null` and `ne` can't
+ * decide on it either.
+ */
+export function matches(criteria, entity, type, related, unknown) {
+    return evalNode(criteria, entity, type, related, unknown) === true;
+}
+/**
+ * Ascending total order for sorting: null first, a NaN after every number and
+ * equal to other NaNs. Descending sorts reverse all of it.
+ */
+export function compareValues(a, b, field) {
+    if (a === null || b === null)
+        return a === b ? 0 : a === null ? -1 : 1;
+    const o = ordering(a, b, field);
+    if (o !== undefined)
+        return o;
+    const an = isNaNValue(a);
+    const bn = isNaNValue(b);
+    return an === bn ? 0 : an ? 1 : -1;
+}
+/** Orders entities as `$orderby=<sort>` (key tie-breakers appended) does. */
+export function sortComparator(sort, type) {
+    const keys = withKeyTieBreakers(sort, type).map((k) => ({
+        name: k.field,
+        field: checkSortable(k, type),
+        dir: k.descending ? -1 : 1,
+    }));
+    return (a, b) => {
+        for (const k of keys) {
+            const c = compareValues(a[k.name] ?? null, b[k.name] ?? null, k.field);
+            if (c !== 0)
+                return c * k.dir;
+        }
+        return 0;
+    };
+}

package/dist/criteria/filter-draft.d.ts

@@ -0,0 +1,79 @@
+import { type ReadonlySignal } from "@preact/signals-core";
+import type { Criteria } from "./ast.ts";
+import type { EntityType, Field, Schema } from "../schema/model.ts";
+/** An editable boolean group. A synthetic root does not add a redundant AND. */
+export interface FilterGroup {
+    readonly kind: "group";
+    readonly id: string;
+    readonly op: string;
+    readonly children: readonly FilterNode[];
+    readonly synthetic?: boolean;
+}
+/** A typed comparison; text remains unparsed while a person edits. */
+export interface FilterCondition {
+    readonly kind: "condition";
+    readonly id: string;
+    readonly field: string;
+    readonly op: string;
+    readonly mode: "value" | "field" | "relative";
+    readonly text: string;
+    readonly other: string;
+    readonly caseInsensitive: boolean;
+}
+/** A related-record condition scoped to a navigation's entity type. */
+export interface FilterRelated {
+    readonly kind: "related";
+    readonly id: string;
+    readonly field: string;
+    readonly op: string;
+    readonly children: readonly FilterNode[];
+}
+export type FilterNode = FilterGroup | FilterCondition | FilterRelated;
+export interface FilterProblem {
+    readonly id: string;
+    readonly message: string;
+}
+export interface FilterResult {
+    readonly valid: boolean;
+    readonly criteria: Criteria | undefined;
+    readonly problems: readonly FilterProblem[];
+}
+export interface FilterChange {
+    readonly field?: string;
+    readonly op?: string;
+    readonly mode?: FilterCondition["mode"];
+    readonly text?: string;
+    readonly other?: string;
+    readonly caseInsensitive?: boolean;
+}
+/** Typed operators offered by both metadata-driven query controls and filter drafts. */
+export declare function filterOperators(field: Field | undefined): readonly string[];
+/** A query draft independent of database clause records. Only apply changes its committed criteria. */
+export declare class FilterDraft {
+    #private;
+    readonly schema: Schema;
+    readonly set: string;
+    readonly root: ReadonlySignal<FilterGroup>;
+    readonly applied: ReadonlySignal<Criteria | undefined>;
+    readonly dirty: ReadonlySignal<boolean>;
+    readonly result: ReadonlySignal<FilterResult>;
+    constructor(schema: Schema, set: string, criteria?: Criteria);
+    /** Replaces the applied value and draft together; no query or record write is performed. */
+    reset(criteria?: Criteria): void;
+    /** Discards draft edits and restores the applied expression. */
+    cancel(): void;
+    /** Clears only the draft. Call apply to commit the cleared expression. */
+    clear(): void;
+    /** Commits a complete valid draft atomically; returns false for any invalid clause. */
+    apply(): boolean;
+    /** Changes a clause without dropping incompatible values or unsupported fields. */
+    change(id: string, change: FilterChange): void;
+    /** Adds a condition, boolean group or related-record group. Returns its stable draft ID. */
+    add(parent: string, kind?: FilterNode["kind"]): string;
+    /** Removes a clause and its descendants. The root remains available for adding conditions. */
+    remove(id: string): void;
+    /** Entity type in scope at a clause; undefined while an ancestor navigation is invalid. */
+    typeFor(id: string): EntityType | undefined;
+}
+/** A readable bracketed expression using metadata titles; this is not executable text. */
+export declare function describeCriteria(criteria: Criteria | undefined, type: EntityType): string;