@rebasepro/client 0.10.0 → 0.10.1-canary.14e53ae

package/src/offline-query.test.ts

@@ -0,0 +1,249 @@
+import {
+    compareValues,
+    isExactlyEvaluable,
+    looseEquals,
+    matchesLogical,
+    matchesOperator,
+    matchesParams,
+    matchesWhere,
+    resolvePagination,
+    runLocalQuery,
+    sortRows
+} from "./offline-query";
+import { EntityRelation } from "@rebasepro/types";
+import type { FindParams } from "./transport";
+
+type Row = Record<string, unknown>;
+
+/**
+ * The local evaluator is what lets a row written offline appear in the
+ * filtered lists it belongs to, so every divergence from the Postgres driver's
+ * semantics shows up as a list that is subtly wrong only when the network is.
+ * These pin the cases where SQL and JavaScript disagree.
+ */
+describe("local query engine", () => {
+    describe("operators", () => {
+        it("compares numbers written as strings by the wire as numbers", () => {
+            // The wire format carries no types, so `["<", "10"]` arrives as a
+            // string. Comparing it as text would order "10" before "9".
+            expect(matchesOperator(9, "<", "10")).toBe(true);
+            expect(matchesOperator("9", "<", 10)).toBe(true);
+            expect(matchesOperator(10, "<", "9")).toBe(false);
+        });
+
+        it("treats a comparison against NULL as unknown, not as false-or-true", () => {
+            // `WHERE status != 'done'` does not return rows with a NULL status.
+            expect(matchesOperator(null, "!=", "done")).toBe(false);
+            expect(matchesOperator(undefined, "!=", "done")).toBe(false);
+            expect(matchesOperator(null, "<", 5)).toBe(false);
+            expect(matchesOperator(null, ">", 5)).toBe(false);
+            expect(matchesOperator(null, "in", ["a"])).toBe(false);
+            expect(matchesOperator(null, "not-in", ["a"])).toBe(false);
+        });
+
+        it("tests null with the operators meant for it", () => {
+            expect(matchesOperator(null, "is-null", null)).toBe(true);
+            expect(matchesOperator(undefined, "is-null", null)).toBe(true);
+            expect(matchesOperator(0, "is-null", null)).toBe(false);
+            expect(matchesOperator("", "is-not-null", null)).toBe(true);
+            expect(matchesOperator(null, "is-not-null", null)).toBe(false);
+        });
+
+        it("matches dates against instants and ISO strings alike", () => {
+            const row = new Date("2026-07-01T00:00:00Z");
+            expect(matchesOperator(row, ">=", new Date("2026-06-01T00:00:00Z"))).toBe(true);
+            expect(matchesOperator(row, "<", "2026-08-01T00:00:00Z")).toBe(true);
+            expect(matchesOperator(row, "==", new Date("2026-07-01T00:00:00Z"))).toBe(true);
+        });
+
+        it("compares a relation by the id it points at", () => {
+            const relation = new EntityRelation("u1", "users");
+            expect(matchesOperator(relation, "==", "u1")).toBe(true);
+            expect(matchesOperator(relation, "in", ["u1", "u2"])).toBe(true);
+            expect(matchesOperator(relation, "==", "u2")).toBe(false);
+        });
+
+        it("handles list membership and array columns", () => {
+            expect(matchesOperator("editor", "in", ["admin", "editor"])).toBe(true);
+            expect(matchesOperator("viewer", "not-in", ["admin", "editor"])).toBe(true);
+            expect(matchesOperator(["a", "b"], "array-contains", "b")).toBe(true);
+            expect(matchesOperator(["a", "b"], "array-contains", "c")).toBe(false);
+            expect(matchesOperator(["a", "b"], "array-contains-any", ["c", "b"])).toBe(true);
+            expect(matchesOperator("not-an-array", "array-contains", "a")).toBe(false);
+        });
+
+        it("reads LIKE patterns as SQL does, wildcards and escapes included", () => {
+            expect(matchesOperator("post-1", "like", "post-%")).toBe(true);
+            expect(matchesOperator("Post-1", "like", "post-%")).toBe(false);
+            expect(matchesOperator("Post-1", "ilike", "post-%")).toBe(true);
+            expect(matchesOperator("abc", "like", "a_c")).toBe(true);
+            expect(matchesOperator("abbc", "like", "a_c")).toBe(false);
+            expect(matchesOperator("50%", "like", "50\\%")).toBe(true);
+            expect(matchesOperator("500", "like", "50\\%")).toBe(false);
+            expect(matchesOperator("a.c", "like", "a.c")).toBe(true);
+            // A regex metacharacter in the pattern is a literal, not a wildcard.
+            expect(matchesOperator("abc", "like", "a.c")).toBe(false);
+            expect(matchesOperator("Post-1", "not-ilike", "post-%")).toBe(false);
+            expect(matchesOperator("other", "not-like", "post-%")).toBe(true);
+        });
+
+        it("accepts REST short-codes wherever canonical operators are accepted", () => {
+            // Filters that came off the wire carry `eq`/`gte`, not `==`/`>=`.
+            expect(matchesWhere({ status: "active" }, { status: ["eq" as "==", "active"] })).toBe(true);
+            expect(matchesWhere({ age: 20 }, { age: ["gte" as ">=", 18] })).toBe(true);
+        });
+
+        it("keeps an unknown operator from silently dropping rows", () => {
+            // Better a list that is too broad than one that quietly hides rows
+            // because this build predates an operator.
+            expect(matchesOperator("x", "spaceship" as never, "y")).toBe(true);
+        });
+    });
+
+    describe("where clauses", () => {
+        const row: Row = { status: "active", age: 30, tags: ["a"] };
+
+        it("ANDs across fields and across tuples on one field", () => {
+            expect(matchesWhere(row, { status: ["==", "active"], age: [">=", 18] })).toBe(true);
+            expect(matchesWhere(row, { status: ["==", "active"], age: [">=", 40] })).toBe(false);
+            expect(matchesWhere(row, { age: [[">=", 18], ["<", 65]] })).toBe(true);
+            expect(matchesWhere(row, { age: [[">=", 18], ["<", 25]] })).toBe(false);
+        });
+
+        it("is vacuously true with no clause", () => {
+            expect(matchesWhere(row, undefined)).toBe(true);
+            expect(matchesWhere(row, {})).toBe(true);
+        });
+    });
+
+    describe("logical trees", () => {
+        const row: Row = { status: "draft", author: "me" };
+
+        it("evaluates nested and/or", () => {
+            expect(matchesLogical(row, {
+                type: "or",
+                conditions: [
+                    { column: "status", operator: "==", value: "published" },
+                    { column: "author", operator: "==", value: "me" }
+                ]
+            })).toBe(true);
+
+            expect(matchesLogical(row, {
+                type: "and",
+                conditions: [
+                    { column: "status", operator: "==", value: "draft" },
+                    {
+                        type: "or",
+                        conditions: [
+                            { column: "author", operator: "==", value: "you" },
+                            { column: "author", operator: "==", value: "me" }
+                        ]
+                    }
+                ]
+            })).toBe(true);
+
+            expect(matchesLogical(row, {
+                type: "or",
+                conditions: [{ column: "status", operator: "==", value: "published" }]
+            })).toBe(false);
+        });
+    });
+
+    describe("ordering", () => {
+        it("puts nulls last ascending and first descending, as Postgres does", () => {
+            const rows: Row[] = [{ id: 1, n: 2 }, { id: 2, n: null }, { id: 3, n: 1 }];
+            expect(sortRows([...rows], ["n", "asc"]).map((r) => r.id)).toEqual([3, 1, 2]);
+            expect(sortRows([...rows], ["n", "desc"]).map((r) => r.id)).toEqual([2, 1, 3]);
+        });
+
+        it("breaks ties on id so paging cannot shuffle equal rows between pages", () => {
+            const rows: Row[] = [{ id: "c", n: 1 }, { id: "a", n: 1 }, { id: "b", n: 1 }];
+            expect(sortRows(rows, ["n", "asc"]).map((r) => r.id)).toEqual(["a", "b", "c"]);
+        });
+
+        it("orders dates chronologically, not lexicographically", () => {
+            const rows: Row[] = [
+                { id: 1, at: new Date("2026-01-02T00:00:00Z") },
+                { id: 2, at: new Date("2025-12-31T00:00:00Z") }
+            ];
+            expect(sortRows(rows, ["at", "asc"]).map((r) => r.id)).toEqual([2, 1]);
+        });
+    });
+
+    describe("pagination", () => {
+        it("resolves page over offset the way the server does", () => {
+            expect(resolvePagination()).toEqual({ limit: 20, offset: 0 });
+            expect(resolvePagination({ limit: 10, offset: 30 })).toEqual({ limit: 10, offset: 30 });
+            expect(resolvePagination({ limit: 10, page: 3 })).toEqual({ limit: 10, offset: 20 });
+            // `page` wins over `offset`, and the first page is not negative.
+            expect(resolvePagination({ limit: 10, page: 1, offset: 99 })).toEqual({ limit: 10, offset: 0 });
+        });
+    });
+
+    describe("runLocalQuery", () => {
+        const rows: Row[] = [
+            { id: "a", n: 3, status: "draft" },
+            { id: "b", n: 1, status: "draft" },
+            { id: "c", n: 2, status: "published" }
+        ];
+
+        it("filters, sorts and paginates, reporting the unpaginated total", () => {
+            const result = runLocalQuery(rows, {
+                where: { status: ["==", "draft"] },
+                orderBy: ["n", "asc"],
+                limit: 1
+            });
+            expect(result.data.map((r) => r.id)).toEqual(["b"]);
+            expect(result.meta).toEqual({ total: 2, limit: 1, offset: 0, hasMore: true });
+        });
+
+        it("reports no more rows on the last page", () => {
+            const result = runLocalQuery(rows, { orderBy: ["n", "asc"], limit: 2, offset: 2 });
+            expect(result.data.map((r) => r.id)).toEqual(["a"]);
+            expect(result.meta).toMatchObject({ total: 3, offset: 2, hasMore: false });
+        });
+
+        it("approximates search as a substring scan over string and number fields", () => {
+            expect(runLocalQuery(rows, { searchString: "publi" }).data.map((r) => r.id)).toEqual(["c"]);
+            expect(runLocalQuery(rows, { searchString: "PUBLI" }).data.map((r) => r.id)).toEqual(["c"]);
+            expect(runLocalQuery(rows, { searchString: "   " }).data).toHaveLength(3);
+        });
+
+        it("combines where, logical and search with AND", () => {
+            const params: FindParams = {
+                where: { status: ["==", "draft"] },
+                logical: { type: "or", conditions: [{ column: "n", operator: "==", value: 3 }] }
+            };
+            expect(runLocalQuery(rows, params).data.map((r) => r.id)).toEqual(["a"]);
+            expect(matchesParams({ id: "b", n: 1, status: "draft" }, params)).toBe(false);
+        });
+    });
+
+    describe("isExactlyEvaluable", () => {
+        it("admits what it cannot answer as well as the server would", () => {
+            expect(isExactlyEvaluable(undefined)).toBe(true);
+            expect(isExactlyEvaluable({ where: { a: ["==", 1] }, orderBy: ["a", "asc"] })).toBe(true);
+            // Real full-text search is not a substring scan…
+            expect(isExactlyEvaluable({ searchString: "x" })).toBe(false);
+            // …and related rows live in collections this query never loaded.
+            expect(isExactlyEvaluable({ include: ["author"] })).toBe(false);
+            expect(isExactlyEvaluable({ include: [] })).toBe(true);
+        });
+    });
+
+    describe("primitives", () => {
+        it("compareValues returns undefined rather than an order across NULL", () => {
+            expect(compareValues(null, 1)).toBeUndefined();
+            expect(compareValues(1, undefined)).toBeUndefined();
+            expect(compareValues(1, 2)).toBeLessThan(0);
+            expect(compareValues("b", "a")).toBeGreaterThan(0);
+        });
+
+        it("looseEquals treats null and undefined as the same absence", () => {
+            expect(looseEquals(null, undefined)).toBe(true);
+            expect(looseEquals(null, 0)).toBe(false);
+            expect(looseEquals(true, "true")).toBe(true);
+            expect(looseEquals(1, "1")).toBe(true);
+        });
+    });
+});

package/src/offline-query.ts

@@ -0,0 +1,356 @@
+import {
+    EntityRelation,
+    FilterValues,
+    FindResult,
+    LogicalCondition,
+    FilterCondition,
+    OrderByTuple,
+    WhereFilterOp,
+    toCanonicalOp
+} from "@rebasepro/types";
+import { FindParams } from "./transport";
+
+/**
+ * A local evaluator for `FindParams`, so cached rows can answer a query the
+ * client has never sent to the server — and so a row written offline shows up
+ * in every filtered list it belongs to, not just in unfiltered ones.
+ *
+ * This mirrors the Postgres driver's semantics rather than JavaScript's:
+ *
+ * - Comparing against NULL is *unknown*, not false-or-true. `status != "done"`
+ *   excludes rows where `status` is null, exactly as SQL does — a JS `!==`
+ *   would have included them.
+ * - `ORDER BY` puts nulls last ascending and first descending, which is the
+ *   Postgres default.
+ * - The wire format carries no types, so values arriving as strings are
+ *   compared numerically against numeric columns and as instants against
+ *   date columns. `["==", "3"]` matches the number `3`, as it does server-side.
+ *
+ * Two things it deliberately approximates, both flagged by
+ * {@link isExactlyEvaluable}: `searchString` becomes a case-insensitive
+ * substring scan over the row's string fields (the server runs real full-text
+ * search over the collection's configured columns), and `include` cannot be
+ * evaluated at all, because the related rows live in collections this query
+ * knows nothing about.
+ */
+
+const collator = typeof Intl !== "undefined" && typeof Intl.Collator === "function"
+    ? new Intl.Collator(undefined, { numeric: false, sensitivity: "variant" })
+    : undefined;
+
+/** The server's page size when the caller does not ask for one. */
+export const DEFAULT_PAGE_SIZE = 20;
+
+function isNullish(value: unknown): boolean {
+    return value === null || value === undefined;
+}
+
+/**
+ * Reduce a value to something comparable. Relations compare by the id they
+ * point at — the column holds a foreign key, so that is what the server
+ * compares too.
+ */
+function toComparable(value: unknown): unknown {
+    if (value instanceof Date) return value.getTime();
+    if (value instanceof EntityRelation) return value.id;
+    if (value && typeof value === "object") {
+        const record = value as Record<string, unknown>;
+        // A reference/relation that lost its prototype somewhere still
+        // compares by id.
+        if (typeof record.__type === "string" && "id" in record) return record.id;
+    }
+    return value;
+}
+
+/**
+ * Three-way compare with SQL's type coercion but not its collation. Returns
+ * `undefined` when the two values are not ordered relative to each other,
+ * which is how NULL propagates through a comparison.
+ */
+export function compareValues(a: unknown, b: unknown): number | undefined {
+    const left = toComparable(a);
+    const right = toComparable(b);
+    if (isNullish(left) || isNullish(right)) return undefined;
+
+    if (typeof left === "boolean" || typeof right === "boolean") {
+        const l = left === true || left === "true" || left === 1 ? 1 : 0;
+        const r = right === true || right === "true" || right === 1 ? 1 : 0;
+        return l - r;
+    }
+
+    // A numeric string on either side means the wire dropped the type; compare
+    // as numbers so `["<", "10"]` does not order "10" before "9" as text.
+    const leftNum = typeof left === "number" ? left : numericOrNaN(left);
+    const rightNum = typeof right === "number" ? right : numericOrNaN(right);
+    if (!Number.isNaN(leftNum) && !Number.isNaN(rightNum)) {
+        return leftNum < rightNum ? -1 : leftNum > rightNum ? 1 : 0;
+    }
+
+    // One side is a date-shaped string and the other an instant.
+    if (typeof left === "number" || typeof right === "number") {
+        const leftTime = toTime(left);
+        const rightTime = toTime(right);
+        if (leftTime !== undefined && rightTime !== undefined) {
+            return leftTime < rightTime ? -1 : leftTime > rightTime ? 1 : 0;
+        }
+    }
+
+    const leftStr = String(left);
+    const rightStr = String(right);
+    if (collator) return collator.compare(leftStr, rightStr);
+    return leftStr < rightStr ? -1 : leftStr > rightStr ? 1 : 0;
+}
+
+function numericOrNaN(value: unknown): number {
+    if (typeof value === "number") return value;
+    if (typeof value === "string" && value.trim() !== "") {
+        const n = Number(value);
+        return Number.isNaN(n) ? NaN : n;
+    }
+    if (typeof value === "bigint") return Number(value);
+    return NaN;
+}
+
+function toTime(value: unknown): number | undefined {
+    if (typeof value === "number") return value;
+    if (typeof value === "string") {
+        const t = Date.parse(value);
+        return Number.isNaN(t) ? undefined : t;
+    }
+    return undefined;
+}
+
+/** Equality with the wire's type erasure allowed for, but never across NULL. */
+export function looseEquals(a: unknown, b: unknown): boolean {
+    const left = toComparable(a);
+    const right = toComparable(b);
+    if (isNullish(left) || isNullish(right)) return isNullish(left) && isNullish(right);
+    if (left === right) return true;
+    const cmp = compareValues(left, right);
+    return cmp === 0;
+}
+
+/**
+ * Translate a SQL `LIKE` pattern to an anchored regular expression.
+ * `%` matches any run of characters, `_` exactly one, and a backslash escapes
+ * either of them.
+ */
+function likeToRegExp(pattern: string, caseInsensitive: boolean): RegExp {
+    let source = "^";
+    for (let i = 0; i < pattern.length; i++) {
+        const char = pattern[i];
+        if (char === "\\" && i + 1 < pattern.length) {
+            source += pattern[i + 1].replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            i++;
+        } else if (char === "%") {
+            source += "[\\s\\S]*";
+        } else if (char === "_") {
+            source += "[\\s\\S]";
+        } else {
+            source += char.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        }
+    }
+    return new RegExp(source + "$", caseInsensitive ? "i" : "");
+}
+
+function asArray(value: unknown): unknown[] {
+    if (Array.isArray(value)) return value;
+    if (value === undefined) return [];
+    return [value];
+}
+
+/** Evaluate one canonical operator against one row value. */
+export function matchesOperator(rowValue: unknown, op: WhereFilterOp, filterValue: unknown): boolean {
+    switch (op) {
+        case "is-null":
+            return isNullish(rowValue);
+        case "is-not-null":
+            return !isNullish(rowValue);
+        case "==":
+            return looseEquals(rowValue, filterValue);
+        case "!=":
+            // SQL: `x != v` is unknown when x is NULL, so the row drops out.
+            if (isNullish(rowValue)) return false;
+            return !looseEquals(rowValue, filterValue);
+        case "<":
+        case "<=":
+        case ">":
+        case ">=": {
+            const cmp = compareValues(rowValue, filterValue);
+            if (cmp === undefined) return false;
+            if (op === "<") return cmp < 0;
+            if (op === "<=") return cmp <= 0;
+            if (op === ">") return cmp > 0;
+            return cmp >= 0;
+        }
+        case "in":
+            if (isNullish(rowValue)) return false;
+            return asArray(filterValue).some((v) => looseEquals(rowValue, v));
+        case "not-in":
+            if (isNullish(rowValue)) return false;
+            return !asArray(filterValue).some((v) => looseEquals(rowValue, v));
+        case "array-contains": {
+            if (!Array.isArray(rowValue)) return false;
+            return rowValue.some((v) => looseEquals(v, filterValue));
+        }
+        case "array-contains-any": {
+            if (!Array.isArray(rowValue)) return false;
+            const wanted = asArray(filterValue);
+            return rowValue.some((v) => wanted.some((w) => looseEquals(v, w)));
+        }
+        case "like":
+        case "not-like":
+        case "ilike":
+        case "not-ilike": {
+            if (isNullish(rowValue)) return false;
+            const insensitive = op === "ilike" || op === "not-ilike";
+            const negated = op === "not-like" || op === "not-ilike";
+            const matched = likeToRegExp(String(filterValue), insensitive).test(String(rowValue));
+            return negated ? !matched : matched;
+        }
+        default:
+            // An operator this build does not know must not silently drop rows.
+            return true;
+    }
+}
+
+function isTuple(value: unknown): value is [WhereFilterOp, unknown] {
+    return Array.isArray(value) && value.length === 2 && typeof value[0] === "string"
+        && toCanonicalOp(value[0]) !== undefined;
+}
+
+/** Evaluate a `where` clause: every field, and every tuple on a field, AND-ed. */
+export function matchesWhere(row: Record<string, unknown>, where: FilterValues<string> | undefined): boolean {
+    if (!where) return true;
+    for (const [field, condition] of Object.entries(where)) {
+        if (condition === undefined) continue;
+        const tuples: [WhereFilterOp, unknown][] = isTuple(condition)
+            ? [condition]
+            : Array.isArray(condition)
+                ? (condition as unknown[]).filter(isTuple) as [WhereFilterOp, unknown][]
+                : [];
+        for (const [rawOp, value] of tuples) {
+            const op = toCanonicalOp(rawOp) ?? rawOp;
+            if (!matchesOperator(row[field], op, value)) return false;
+        }
+    }
+    return true;
+}
+
+/** Evaluate a nested and/or tree. */
+export function matchesLogical(
+    row: Record<string, unknown>,
+    condition: LogicalCondition | FilterCondition | undefined
+): boolean {
+    if (!condition) return true;
+    if ("type" in condition) {
+        const children = condition.conditions ?? [];
+        if (children.length === 0) return true;
+        return condition.type === "or"
+            ? children.some((c) => matchesLogical(row, c))
+            : children.every((c) => matchesLogical(row, c));
+    }
+    const op = toCanonicalOp(condition.operator) ?? condition.operator;
+    return matchesOperator(row[condition.column], op as WhereFilterOp, condition.value);
+}
+
+/**
+ * Approximate the server's full-text search with a case-insensitive substring
+ * scan over the row's own string fields. Narrower than the real thing (no
+ * stemming, no configured search columns), and it never matches a field the
+ * cached row does not carry — a local list may therefore be missing rows the
+ * server would have returned, which is why {@link isExactlyEvaluable} refuses
+ * to call a search query exact.
+ */
+export function matchesSearch(row: Record<string, unknown>, searchString: string | undefined): boolean {
+    if (!searchString) return true;
+    const needle = searchString.trim().toLowerCase();
+    if (!needle) return true;
+    for (const value of Object.values(row)) {
+        if (typeof value === "string" && value.toLowerCase().includes(needle)) return true;
+        if (typeof value === "number" && String(value).includes(needle)) return true;
+    }
+    return false;
+}
+
+/** Does this row belong in the result set for `params`, ignoring pagination? */
+export function matchesParams(row: Record<string, unknown>, params?: FindParams): boolean {
+    if (!params) return true;
+    return matchesWhere(row, params.where)
+        && matchesLogical(row, params.logical)
+        && matchesSearch(row, params.searchString);
+}
+
+/**
+ * Sort in place, Postgres-style: nulls last ascending, first descending, with
+ * the row id as a tiebreak so paging through an unsorted-but-equal run does
+ * not shuffle rows between pages.
+ */
+export function sortRows<M extends Record<string, unknown>>(rows: M[], orderBy?: OrderByTuple): M[] {
+    if (!orderBy) return rows;
+    const [field, direction = "asc"] = orderBy;
+    const sign = direction === "desc" ? -1 : 1;
+    return rows.sort((a, b) => {
+        const av = a[field];
+        const bv = b[field];
+        const aNull = isNullish(toComparable(av));
+        const bNull = isNullish(toComparable(bv));
+        if (aNull || bNull) {
+            if (aNull && bNull) return tiebreak(a, b);
+            // NULLS LAST ascending, NULLS FIRST descending.
+            return (aNull ? 1 : -1) * (direction === "desc" ? -1 : 1);
+        }
+        const cmp = compareValues(av, bv);
+        if (cmp === undefined || cmp === 0) return tiebreak(a, b);
+        return cmp * sign;
+    });
+}
+
+function tiebreak(a: Record<string, unknown>, b: Record<string, unknown>): number {
+    const cmp = compareValues(a.id, b.id);
+    return cmp ?? 0;
+}
+
+/** Resolve `page`/`offset`/`limit` the way the server does. */
+export function resolvePagination(params?: FindParams): { limit: number; offset: number } {
+    const limit = params?.limit ?? DEFAULT_PAGE_SIZE;
+    const offset = params?.page != null
+        ? Math.max(0, (params.page - 1) * limit)
+        : (params?.offset ?? 0);
+    return { limit, offset };
+}
+
+/**
+ * Can a locally evaluated answer to `params` be trusted to match the server's,
+ * assuming the cache holds every row of the collection?
+ *
+ * `include` pulls in rows from other collections that this evaluator never
+ * sees, and `searchString` is only approximated — both make the local answer a
+ * best effort rather than an equivalent one.
+ */
+export function isExactlyEvaluable(params?: FindParams): boolean {
+    if (!params) return true;
+    if (params.include && params.include.length > 0) return false;
+    if (params.searchString) return false;
+    return true;
+}
+
+/** Run a full query — filter, sort, paginate — over a set of rows. */
+export function runLocalQuery<M extends Record<string, unknown>>(
+    rows: M[],
+    params?: FindParams
+): FindResult<M> {
+    const matched = rows.filter((row) => matchesParams(row, params));
+    sortRows(matched, params?.orderBy);
+    const { limit, offset } = resolvePagination(params);
+    const page = matched.slice(offset, offset + limit);
+    return {
+        data: page,
+        meta: {
+            total: matched.length,
+            limit,
+            offset,
+            hasMore: offset + page.length < matched.length
+        }
+    };
+}