@procedures/client 0.8.0 → 0.9.0

package/dist/procedures/collection/query.js

@@ -0,0 +1,854 @@
+/**
+ * The query language of the collection storages: a selector, an order, a skip, a limit, the query
+ * policy that limits them, and the two forms of a patch.
+ *
+ * A selector is JSON: a subset of the query selectors of MongoDB. It goes over the wire as it is,
+ * so the procedure `collections.<name>.find` and `query()` of each storage take the same selector.
+ * A storage that can run a selector itself (for example a database) gives the same result as
+ * `queryEntries()` of this module, which is the reference.
+ *
+ * This module is the one copy of the language (roadmap CLI-34). The language is a part of the wire
+ * contract of the core. `@procedures/collections` and the storage packages import it from
+ * `@procedures/client/query`, an entry without other imports.
+ *
+ * The rules:
+ * - A key of a selector is a field path, for example `"meta.kind"`. A number in a path is an
+ *   index of an array, for example `"tags.0"`.
+ * - A path through an array of objects looks into each object: `"items.name"` gives the name of
+ *   each item.
+ * - The value of a field path is a literal or an object of operators. A literal is a test for
+ *   equality. A field whose value is an array also matches when one element is equal.
+ * - The literal `null` also matches a missing field.
+ * - The operators are `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$exists`,
+ *   `$not`, `$regex` with `$options`, `$size`, `$all` and `$elemMatch`. The top of a selector also
+ *   takes `$and`, `$or` and `$nor`. Another operator is an error, not a condition that is ignored.
+ * - `$gt`, `$gte`, `$lt` and `$lte` compare only values of one type: numbers with numbers, strings
+ *   with strings, and booleans with booleans.
+ * - Two objects are equal when they have the same keys with equal values. The order of the keys
+ *   does not change the result.
+ * - A key whose value is `undefined` is not in the selector, as in JSON.
+ * - A query policy limits the operators, the size and the depth of a selector, the lists, the
+ *   regular expressions and the limit. The default policy does not permit `$regex`.
+ */
+/** Each operator of the query language. A policy with these operators permits `$regex`. */
+export const QUERY_OPERATORS = Object.freeze([
+    "$eq",
+    "$ne",
+    "$gt",
+    "$gte",
+    "$lt",
+    "$lte",
+    "$in",
+    "$nin",
+    "$exists",
+    "$not",
+    "$regex",
+    "$size",
+    "$all",
+    "$elemMatch",
+    "$and",
+    "$or",
+    "$nor",
+]);
+/** The operators of the default policy: each operator except `$regex`. */
+export const DEFAULT_QUERY_OPERATORS = Object.freeze(QUERY_OPERATORS.filter((operator) => operator !== "$regex"));
+/** The limits of a policy that gives no limit of its own. `$regex` is off. */
+export const DEFAULT_QUERY_POLICY = Object.freeze({
+    operators: DEFAULT_QUERY_OPERATORS,
+    maxRegexLength: 128,
+    regexFlags: "imsu",
+    maxClauses: 64,
+    maxDepth: 6,
+    maxListLength: 256,
+});
+/** The limit of the procedure `find` for a call without a limit, when its policy gives no `maxLimit`. */
+export const DEFAULT_FIND_LIMIT = 1000;
+//
+// ═══ The values ═══
+//
+/** True for an object that is not an array and not null. */
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** The keys of an object whose values are not `undefined`, as JSON keeps them. */
+function definedKeys(value) {
+    return Object.keys(value).filter((key) => value[key] !== undefined);
+}
+/** The defined entries of an object, as JSON keeps them. */
+function definedEntries(value) {
+    return Object.entries(value).filter(([, entry]) => entry !== undefined);
+}
+/** The rank of the type of a value in the order: null, numbers, strings, objects, arrays, booleans. */
+function rankOf(value) {
+    if (value === null || value === undefined)
+        return 0;
+    switch (typeof value) {
+        case "number":
+            return 1;
+        case "string":
+            return 2;
+        case "object":
+            return Array.isArray(value) ? 4 : 3;
+        case "boolean":
+            return 5;
+        default:
+            return 6;
+    }
+}
+/** The order of two primitive values of one type. */
+function order(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/**
+ * This function compares two JSON values in the order of the queries: `null` and a missing value
+ * first, then numbers, strings, objects, arrays and booleans. Numbers compare by value, and strings
+ * by their UTF-16 code units. Arrays compare element by element. Objects compare by their sorted
+ * keys, then by the values of the keys.
+ *
+ * @returns A negative number when `a` comes first, a positive number when `b` comes first, or 0
+ */
+export function compareStorageValues(a, b) {
+    const rankA = rankOf(a);
+    const rankB = rankOf(b);
+    if (rankA !== rankB)
+        return rankA < rankB ? -1 : 1;
+    switch (rankA) {
+        case 1:
+            return order(a, b);
+        case 2:
+            return order(a, b);
+        case 5:
+            return order(a, b);
+        case 4: {
+            const left = a;
+            const right = b;
+            for (let index = 0; index < Math.min(left.length, right.length); index++) {
+                const result = compareStorageValues(left[index], right[index]);
+                if (result !== 0)
+                    return result;
+            }
+            return order(left.length, right.length);
+        }
+        case 3: {
+            const left = a;
+            const right = b;
+            const leftKeys = definedKeys(left).sort(order);
+            const rightKeys = definedKeys(right).sort(order);
+            for (let index = 0; index < Math.min(leftKeys.length, rightKeys.length); index++) {
+                const leftKey = leftKeys[index];
+                const rightKey = rightKeys[index];
+                if (leftKey !== rightKey)
+                    return order(leftKey, rightKey);
+                const result = compareStorageValues(left[leftKey], right[rightKey]);
+                if (result !== 0)
+                    return result;
+            }
+            return order(leftKeys.length, rightKeys.length);
+        }
+        default:
+            return 0;
+    }
+}
+/** True when two JSON values are equal. The order of the keys of an object does not count. */
+function equal(a, b) {
+    return compareStorageValues(a, b) === 0;
+}
+const INDEX = /^(?:0|[1-9][0-9]*)$/;
+/** This function finds the values at a path. A path through an array of objects looks into each object. */
+function lookup(item, path) {
+    const found = { values: [], missing: false };
+    walk(item, path, 0, found);
+    return found;
+}
+function walk(value, path, index, found) {
+    if (index === path.length) {
+        if (value === undefined)
+            found.missing = true;
+        else
+            found.values.push(value);
+        return;
+    }
+    const key = path[index];
+    if (Array.isArray(value)) {
+        if (INDEX.test(key)) {
+            const position = Number(key);
+            if (position < value.length)
+                walk(value[position], path, index + 1, found);
+            else
+                found.missing = true;
+            return;
+        }
+        let objects = 0;
+        for (const element of value) {
+            if (!isObject(element))
+                continue;
+            objects++;
+            walk(element, path, index, found);
+        }
+        if (objects === 0)
+            found.missing = true;
+        return;
+    }
+    if (isObject(value) && Object.hasOwn(value, key))
+        walk(value[key], path, index + 1, found);
+    else
+        found.missing = true;
+}
+/** The values that a comparison examines: each value, and each element of a value that is an array. */
+function candidates(found) {
+    const result = [];
+    for (const value of found.values) {
+        result.push(value);
+        if (Array.isArray(value))
+            result.push(...value);
+    }
+    return result;
+}
+/** The segments of a field path, or undefined after a problem. */
+function pathOf(key, at, problems) {
+    const segments = key.split(".");
+    if (segments.some((segment) => segment === "")) {
+        problems.push(`${at}: the field path "${key}" has an empty part`);
+        return undefined;
+    }
+    if (segments.some((segment) => segment.startsWith("$"))) {
+        problems.push(`${at}: the field path "${key}" has a part that starts with $`);
+        return undefined;
+    }
+    return segments;
+}
+/** The limits of a policy: each limit that the policy does not give has its default. */
+function limitsOf(policy) {
+    return {
+        operators: new Set(policy?.operators ?? DEFAULT_QUERY_OPERATORS),
+        maxRegexLength: policy?.maxRegexLength ?? 128,
+        regexFlags: policy?.regexFlags ?? "imsu",
+        maxClauses: policy?.maxClauses ?? 64,
+        maxDepth: policy?.maxDepth ?? 6,
+        maxListLength: policy?.maxListLength ?? 256,
+        maxLimit: policy?.maxLimit ?? Number.POSITIVE_INFINITY,
+    };
+}
+const KNOWN = new Set(QUERY_OPERATORS);
+/** False, with a problem, when the language does not know the operator, or the policy does not permit it. */
+function permitted(operator, at, compilation) {
+    if (!KNOWN.has(operator)) {
+        compilation.problems.push(`${at}: the operator ${operator} is not known`);
+        return false;
+    }
+    if (!compilation.limits.operators.has(operator)) {
+        const hint = operator === "$regex" ? ". A host turns it on with a queryPolicy whose operators include $regex" : "";
+        compilation.problems.push(`${at}: the query policy does not permit the operator ${operator}${hint}`);
+        return false;
+    }
+    compilation.clauses++;
+    return true;
+}
+/** False, with a problem, when the nesting goes deeper than the policy permits. */
+function withinDepth(depth, at, compilation) {
+    if (depth <= compilation.limits.maxDepth)
+        return true;
+    compilation.problems.push(`${at}: the selector is nested deeper than the ${compilation.limits.maxDepth} levels of the query policy`);
+    return false;
+}
+/**
+ * True when a pattern repeats a group that repeats without a bound, for example `(a+)+` or
+ * `(a|b*)*`. Such a pattern can take an exponential time on a long text.
+ */
+function repeatsRepetition(pattern) {
+    // For each open group: true when it holds a repetition without a bound
+    const groups = [];
+    let lastGroupRepeats = false;
+    let inClass = false;
+    for (let index = 0; index < pattern.length; index++) {
+        const char = pattern[index];
+        if (char === "\\") {
+            index++;
+            lastGroupRepeats = false;
+            continue;
+        }
+        if (inClass) {
+            if (char === "]")
+                inClass = false;
+            continue;
+        }
+        if (char === "[") {
+            inClass = true;
+            lastGroupRepeats = false;
+            continue;
+        }
+        if (char === "(") {
+            groups.push(false);
+            lastGroupRepeats = false;
+            continue;
+        }
+        if (char === ")") {
+            lastGroupRepeats = groups.pop() ?? false;
+            // A group that holds a repetition makes each group around it hold one too
+            if (lastGroupRepeats && groups.length > 0)
+                groups[groups.length - 1] = true;
+            continue;
+        }
+        const unbounded = char === "*" || char === "+" || (char === "{" && /^\{\d*,\}/.test(pattern.slice(index)));
+        if (unbounded) {
+            if (lastGroupRepeats)
+                return true;
+            if (groups.length > 0)
+                groups[groups.length - 1] = true;
+        }
+        if (char !== "?")
+            lastGroupRepeats = false;
+    }
+    return false;
+}
+const LOGICAL = new Set(["$and", "$or", "$nor"]);
+const REGEX_FLAGS = /^(?!.*(.).*\1)[imsu]*$/;
+const NEVER = () => false;
+const ALWAYS = () => true;
+/** True for an object of operators: each defined key starts with `$`. */
+function isOperatorObject(value) {
+    if (!isObject(value))
+        return false;
+    const keys = definedKeys(value);
+    return keys.length > 0 && keys.every((key) => key.startsWith("$"));
+}
+/** The test of equality with a literal. `null` also matches a missing field. */
+function equalTo(literal) {
+    return (found) => (literal === null && found.missing) || candidates(found).some((value) => equal(value, literal));
+}
+/** True when two values have one type of the comparisons: number, string or boolean. */
+function comparable(value, operand) {
+    const type = typeof operand;
+    return typeof value === type && (type === "number" || type === "string" || type === "boolean");
+}
+/** The test of a comparison operator. */
+function compareTo(operator, operand, at, compilation) {
+    if (operand === null) {
+        // Only null is equal to null: $gte and $lte match null and a missing field
+        return operator === "$gte" || operator === "$lte" ? equalTo(null) : NEVER;
+    }
+    if (typeof operand !== "number" && typeof operand !== "string" && typeof operand !== "boolean") {
+        compilation.problems.push(`${at}.${operator} takes a number, a string, a boolean or null`);
+        return NEVER;
+    }
+    const accept = operator === "$gt" ? (result) => result > 0 : operator === "$gte" ? (result) => result >= 0 : operator === "$lt" ? (result) => result < 0 : (result) => result <= 0;
+    return (found) => candidates(found).some((value) => comparable(value, operand) && accept(compareStorageValues(value, operand)));
+}
+/** The tests of a list operator: `$in`, `$nin` or `$all`. */
+function listOf(operator, operand, at, compilation) {
+    if (!Array.isArray(operand)) {
+        compilation.problems.push(`${at}.${operator} takes a list`);
+        return undefined;
+    }
+    if (operand.length > compilation.limits.maxListLength) {
+        compilation.problems.push(`${at}.${operator} has ${operand.length} values, more than the ${compilation.limits.maxListLength} of the query policy`);
+        return undefined;
+    }
+    return operand.map((value, index) => {
+        if (isOperatorObject(value)) {
+            compilation.problems.push(`${at}.${operator}[${index}] is an object of operators: ${operator} takes values`);
+            return NEVER;
+        }
+        return equalTo(value);
+    });
+}
+/** The test of an object of operators on one field. */
+function compileOperators(operators, at, compilation, depth) {
+    const tests = [];
+    const options = operators["$options"];
+    if (options !== undefined && operators["$regex"] === undefined)
+        compilation.problems.push(`${at}.$options needs $regex`);
+    for (const [operator, operand] of definedEntries(operators)) {
+        // $options goes with $regex
+        if (operator === "$options")
+            continue;
+        if (!permitted(operator, at, compilation))
+            continue;
+        switch (operator) {
+            case "$eq":
+                tests.push(equalTo(operand));
+                break;
+            case "$ne": {
+                const test = equalTo(operand);
+                tests.push((found) => !test(found));
+                break;
+            }
+            case "$gt":
+            case "$gte":
+            case "$lt":
+            case "$lte":
+                tests.push(compareTo(operator, operand, at, compilation));
+                break;
+            case "$in":
+            case "$nin": {
+                const list = listOf(operator, operand, at, compilation);
+                if (!list)
+                    break;
+                tests.push(operator === "$in" ? (found) => list.some((test) => test(found)) : (found) => !list.some((test) => test(found)));
+                break;
+            }
+            case "$all": {
+                const list = listOf(operator, operand, at, compilation);
+                if (!list)
+                    break;
+                // An empty $all matches nothing, as in MongoDB
+                tests.push((found) => list.length > 0 && list.every((test) => test(found)));
+                break;
+            }
+            case "$exists":
+                if (typeof operand !== "boolean") {
+                    compilation.problems.push(`${at}.$exists takes true or false`);
+                    break;
+                }
+                tests.push((found) => (found.values.length > 0) === operand);
+                break;
+            case "$size":
+                if (typeof operand !== "number" || !Number.isInteger(operand) || operand < 0) {
+                    compilation.problems.push(`${at}.$size takes a whole number, 0 or more`);
+                    break;
+                }
+                tests.push((found) => found.values.some((value) => Array.isArray(value) && value.length === operand));
+                break;
+            case "$regex": {
+                const regex = regexOf(operand, options, at, compilation);
+                if (regex)
+                    tests.push((found) => candidates(found).some((value) => typeof value === "string" && regex.test(value)));
+                break;
+            }
+            case "$not": {
+                if (!isOperatorObject(operand)) {
+                    compilation.problems.push(`${at}.$not takes an object of operators`);
+                    break;
+                }
+                if (!withinDepth(depth + 1, `${at}.$not`, compilation))
+                    break;
+                const test = compileOperators(operand, `${at}.$not`, compilation, depth + 1);
+                tests.push((found) => !test(found));
+                break;
+            }
+            case "$elemMatch":
+                tests.push(elementMatch(operand, at, compilation, depth + 1));
+                break;
+            default:
+                // $and, $or and $nor are operators of a selector, not of a field
+                compilation.problems.push(`${at}: the operator ${operator} goes at the top of a selector, not on a field`);
+        }
+    }
+    return tests.length === 1 ? tests[0] : (found) => tests.every((test) => test(found));
+}
+/** The regular expression of `$regex` and `$options`, or undefined after a problem. */
+function regexOf(pattern, flags, at, compilation) {
+    const { limits, problems } = compilation;
+    if (typeof pattern !== "string") {
+        problems.push(`${at}.$regex takes a string`);
+        return undefined;
+    }
+    if (pattern.length > limits.maxRegexLength) {
+        problems.push(`${at}.$regex has ${pattern.length} characters, more than the ${limits.maxRegexLength} of the query policy`);
+        return undefined;
+    }
+    if (flags !== undefined && (typeof flags !== "string" || !REGEX_FLAGS.test(flags))) {
+        problems.push(`${at}.$options takes the flags i, m, s and u, each one time`);
+        return undefined;
+    }
+    const refused = typeof flags === "string" ? [...flags].filter((flag) => !limits.regexFlags.includes(flag)) : [];
+    if (refused.length > 0) {
+        problems.push(`${at}.$options has the flag ${refused.join(", ")}, and the query policy permits only "${limits.regexFlags}"`);
+        return undefined;
+    }
+    if (repeatsRepetition(pattern)) {
+        problems.push(`${at}.$regex repeats a group that repeats without a bound: such a pattern can take an exponential time`);
+        return undefined;
+    }
+    try {
+        return new RegExp(pattern, typeof flags === "string" ? flags : "");
+    }
+    catch (error) {
+        problems.push(`${at}.$regex is not a regular expression: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+}
+/** The test of `$elemMatch`: an element of an array matches the operators, or the selector of objects. */
+function elementMatch(operand, at, compilation, depth) {
+    if (!isObject(operand)) {
+        compilation.problems.push(`${at}.$elemMatch takes an object`);
+        return NEVER;
+    }
+    if (!withinDepth(depth, `${at}.$elemMatch`, compilation))
+        return NEVER;
+    const keys = definedKeys(operand);
+    if (isOperatorObject(operand) && !keys.some((key) => LOGICAL.has(key))) {
+        const test = compileOperators(operand, `${at}.$elemMatch`, compilation, depth);
+        return (found) => found.values.some((value) => Array.isArray(value) && value.some((element) => element !== undefined && test({ values: [element], missing: false })));
+    }
+    const matcher = compileInto(operand, `${at}.$elemMatch`, compilation, depth);
+    return (found) => found.values.some((value) => Array.isArray(value) && value.some((element) => isObject(element) && matcher(element)));
+}
+/** The test of the condition of one field path: an object of operators, or a literal. */
+function compileCondition(condition, at, compilation, depth) {
+    if (isObject(condition)) {
+        const keys = definedKeys(condition);
+        const operators = keys.filter((key) => key.startsWith("$"));
+        if (operators.length > 0 && operators.length < keys.length) {
+            compilation.problems.push(`${at} mixes operators and fields: write the fields as a literal, or use only operators`);
+            return NEVER;
+        }
+        if (operators.length > 0)
+            return compileOperators(condition, at, compilation, depth);
+    }
+    compilation.clauses++;
+    return equalTo(condition);
+}
+/** The matcher of a selector. Each problem goes to the compilation. */
+function compileInto(selector, at, compilation, depth) {
+    if (!isObject(selector)) {
+        compilation.problems.push(`${at} must be an object`);
+        return () => false;
+    }
+    const parts = [];
+    for (const [key, condition] of definedEntries(selector)) {
+        if (key.startsWith("$")) {
+            if (!LOGICAL.has(key)) {
+                compilation.problems.push(`${at}: the operator ${key} is not known`);
+                continue;
+            }
+            if (!permitted(key, at, compilation))
+                continue;
+            if (!Array.isArray(condition) || condition.length === 0) {
+                compilation.problems.push(`${at}.${key} takes a list of one or more selectors`);
+                continue;
+            }
+            if (!withinDepth(depth + 1, `${at}.${key}`, compilation))
+                continue;
+            const matchers = condition.map((part, index) => compileInto(part, `${at}.${key}[${index}]`, compilation, depth + 1));
+            if (key === "$and")
+                parts.push((item) => matchers.every((matcher) => matcher(item)));
+            else if (key === "$or")
+                parts.push((item) => matchers.some((matcher) => matcher(item)));
+            else
+                parts.push((item) => !matchers.some((matcher) => matcher(item)));
+            continue;
+        }
+        const path = pathOf(key, at, compilation.problems);
+        if (!path)
+            continue;
+        const test = compileCondition(condition, `${at}.${key}`, compilation, depth);
+        parts.push((item) => test(lookup(item, path)));
+    }
+    if (parts.length === 0)
+        return ALWAYS;
+    if (parts.length === 1)
+        return parts[0];
+    return (item) => parts.every((part) => part(item));
+}
+/** This function compiles a selector, and gives the matcher and each problem. */
+function compile(selector, policy) {
+    const compilation = { limits: limitsOf(policy), problems: [], clauses: 0 };
+    const matcher = compileInto(selector, "selector", compilation, 0);
+    if (compilation.clauses > compilation.limits.maxClauses) {
+        compilation.problems.push(`selector: it has ${compilation.clauses} clauses, more than the ${compilation.limits.maxClauses} of the query policy`);
+    }
+    return { matcher, problems: compilation.problems };
+}
+/**
+ * This function gives the problems of a selector: each part that the language does not know, and
+ * each part that the policy does not permit. An empty list means that the selector is correct.
+ *
+ * @param policy - The query policy. The default policy does not permit `$regex`.
+ */
+export function selectorProblems(selector, policy) {
+    return compile(selector, policy).problems;
+}
+/**
+ * This function makes a test from a selector. The test gives true for each item that the selector
+ * matches. Compile a selector one time for many items.
+ *
+ * @param policy - The query policy. The default policy does not permit `$regex`.
+ * @throws TypeError when the selector has a problem (refer to `selectorProblems`)
+ */
+export function compileSelector(selector, policy) {
+    const { matcher, problems } = compile(selector, policy);
+    if (problems.length > 0)
+        throw new TypeError(`The selector is not correct: ${problems.join(". ")}`);
+    return matcher;
+}
+/**
+ * This function tells if a selector matches an item.
+ *
+ * @throws TypeError when the selector has a problem
+ */
+export function matchesSelector(selector, item, policy) {
+    return compileSelector(selector, policy)(item);
+}
+//
+// ═══ The options ═══
+//
+const OPTION_KEYS = new Set(["sort", "skip", "limit"]);
+/**
+ * This function gives the problems of the options of a query. An empty list means that the
+ * options are correct. A policy with a `maxLimit` refuses a larger limit.
+ */
+export function queryOptionsProblems(options, policy) {
+    if (options === undefined)
+        return [];
+    if (!isObject(options))
+        return ["the options of a query must be an object"];
+    const problems = [];
+    for (const key of definedKeys(options)) {
+        if (!OPTION_KEYS.has(key))
+            problems.push(`the option ${key} is not known: use sort, skip and limit`);
+    }
+    const sort = options["sort"];
+    const skip = options["skip"];
+    const limit = options["limit"];
+    if (sort !== undefined) {
+        if (!isObject(sort)) {
+            problems.push("sort must be an object of field paths with 1 or -1");
+        }
+        else {
+            for (const [key, direction] of definedEntries(sort)) {
+                pathOf(key, "sort", problems);
+                if (direction !== 1 && direction !== -1)
+                    problems.push(`sort.${key} must be 1 or -1`);
+            }
+        }
+    }
+    if (skip !== undefined && (typeof skip !== "number" || !Number.isSafeInteger(skip) || skip < 0)) {
+        problems.push("skip must be a whole number, 0 or more");
+    }
+    if (limit !== undefined && (typeof limit !== "number" || !Number.isSafeInteger(limit) || limit < 1)) {
+        problems.push("limit must be a whole number, 1 or more");
+    }
+    else if (typeof limit === "number") {
+        const maxLimit = limitsOf(policy).maxLimit;
+        if (limit > maxLimit)
+            problems.push(`limit must be at most ${maxLimit}, the maxLimit of the query policy`);
+    }
+    return problems;
+}
+/** The key of an item for one sort key: the least value for ascending, the most for descending. */
+function sortKeyOf(item, path, direction) {
+    const found = lookup(item, path);
+    const values = [];
+    for (const value of found.values) {
+        if (Array.isArray(value))
+            values.push(...value);
+        else
+            values.push(value);
+    }
+    if (found.missing)
+        values.push(null);
+    if (values.length === 0)
+        return null;
+    let best = values[0];
+    for (let index = 1; index < values.length; index++) {
+        const result = compareStorageValues(values[index], best);
+        if (direction === 1 ? result < 0 : result > 0)
+            best = values[index];
+    }
+    return best;
+}
+/**
+ * This function runs a query on entries, as the reference of each storage: the selector, then the
+ * order, then the skip and the limit. The result has the entries themselves, not copies.
+ *
+ * - Without `sort`, the result has the order of the entries.
+ * - A sort key on an array field uses its least element for ascending, and its most element for
+ *   descending. A missing field sorts as `null`.
+ * - A query without a limit gets the `maxLimit` of the policy, when it has one.
+ *
+ * @param policy - The query policy. The default policy does not permit `$regex`.
+ * @throws TypeError when the selector or the options have a problem
+ */
+export function queryEntries(entries, selector = {}, options = {}, policy) {
+    const matches = compileSelector(selector, policy);
+    const problems = queryOptionsProblems(options, policy);
+    if (problems.length > 0)
+        throw new TypeError(`The options of the query are not correct: ${problems.join(". ")}`);
+    let result = [];
+    for (const [id, value] of entries) {
+        if (matches(value))
+            result.push([id, value]);
+    }
+    const keys = definedEntries(options.sort ?? {}).map(([key, direction]) => ({
+        path: key.split("."),
+        direction: direction,
+    }));
+    if (keys.length > 0) {
+        const rows = result.map((entry, index) => ({ entry, index, keys: keys.map((key) => sortKeyOf(entry[1], key.path, key.direction)) }));
+        rows.sort((a, b) => {
+            for (let index = 0; index < keys.length; index++) {
+                const delta = compareStorageValues(a.keys[index], b.keys[index]) * keys[index].direction;
+                if (delta !== 0)
+                    return delta;
+            }
+            return a.index - b.index;
+        });
+        result = rows.map((row) => row.entry);
+    }
+    const skip = options.skip ?? 0;
+    const maxLimit = limitsOf(policy).maxLimit;
+    const limit = options.limit ?? (Number.isFinite(maxLimit) ? maxLimit : undefined);
+    if (skip === 0 && limit === undefined)
+        return result;
+    return result.slice(skip, limit === undefined ? undefined : skip + limit);
+}
+//
+// ═══ The patch ═══
+//
+const PATCH_OPERATIONS = new Set(["$set", "$unset"]);
+/** True for the operations form of a patch: an object whose defined keys each start with `$`. */
+export function isPatchOperations(fields) {
+    return isOperatorObject(fields);
+}
+/**
+ * This function gives the problems of the fields of a patch. An empty list means that the patch
+ * is correct: a JSON Merge Patch, or the operations `$set` and `$unset`. A patch that mixes the two
+ * forms is not correct.
+ */
+export function patchProblems(fields) {
+    if (!isObject(fields))
+        return ["the fields of a patch must be an object"];
+    const keys = definedKeys(fields);
+    const operations = keys.filter((key) => key.startsWith("$"));
+    if (operations.length === 0)
+        return [];
+    if (operations.length < keys.length) {
+        return ["the patch mixes operations and fields: give { $set, $unset }, or only fields (a JSON Merge Patch)"];
+    }
+    const problems = [];
+    const paths = [];
+    for (const operation of operations) {
+        if (!PATCH_OPERATIONS.has(operation))
+            problems.push(`the patch operation ${operation} is not known: use $set and $unset`);
+    }
+    const set = fields["$set"];
+    if (set !== undefined) {
+        if (!isObject(set))
+            problems.push("$set takes an object of field paths and values");
+        else
+            for (const key of definedKeys(set))
+                if (pathOf(key, "$set", problems))
+                    paths.push(key);
+    }
+    const unset = fields["$unset"];
+    if (unset !== undefined) {
+        if (!Array.isArray(unset) || !unset.every((path) => typeof path === "string"))
+            problems.push("$unset takes a list of field paths");
+        else
+            for (const key of unset)
+                if (pathOf(key, "$unset", problems))
+                    paths.push(key);
+    }
+    for (let first = 0; first < paths.length; first++) {
+        for (let second = first + 1; second < paths.length; second++) {
+            const a = paths[first];
+            const b = paths[second];
+            if (a === b || b.startsWith(`${a}.`) || a.startsWith(`${b}.`))
+                problems.push(`the field paths ${a} and ${b} of the patch overlap`);
+        }
+    }
+    return problems;
+}
+/** This function sets a key as an own property, also the key `__proto__`. */
+function put(target, key, value) {
+    Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+}
+/** A shallow copy of an object, with its own keys, also `__proto__`. */
+function copyOf(value) {
+    const result = {};
+    for (const key of Object.keys(value))
+        put(result, key, value[key]);
+    return result;
+}
+/**
+ * This function applies a JSON Merge Patch (RFC 7386) to a value, and gives the new value. It does
+ * not change the value or the patch, but the new value can share parts with them.
+ *
+ * - Each field of the patch replaces the field of the value.
+ * - An object field of the patch merges into an object field of the value.
+ * - A `null` field removes the field.
+ * - A value that is not an object becomes an empty object first.
+ */
+export function mergePatch(value, fields) {
+    const result = isObject(value) ? copyOf(value) : {};
+    for (const key of Object.keys(fields)) {
+        const field = fields[key];
+        if (field === undefined)
+            continue;
+        if (field === null)
+            delete result[key];
+        else
+            put(result, key, isObject(field) ? mergePatch(Object.hasOwn(result, key) ? result[key] : undefined, field) : field);
+    }
+    return result;
+}
+/** The container at a path with a new value at its end: a copy of each object and array on the path. */
+function setIn(container, path, index, value) {
+    const key = path[index];
+    const last = index === path.length - 1;
+    const where = path.slice(0, index).join(".") || "the item";
+    if (Array.isArray(container)) {
+        if (!INDEX.test(key))
+            throw new TypeError(`The patch cannot set ${path.join(".")}: ${where} is an array`);
+        const position = Number(key);
+        if (position > container.length) {
+            throw new TypeError(`The patch cannot set ${path.join(".")}: ${where} has ${container.length} elements`);
+        }
+        const copy = container.slice();
+        copy[position] = last ? value : setIn(copy[position] ?? {}, path, index + 1, value);
+        return copy;
+    }
+    if (!isObject(container))
+        throw new TypeError(`The patch cannot set ${path.join(".")}: ${where} is not an object`);
+    const copy = copyOf(container);
+    const child = Object.hasOwn(copy, key) ? copy[key] : undefined;
+    put(copy, key, last ? value : setIn(child ?? {}, path, index + 1, value));
+    return copy;
+}
+/** The container without the value at a path: a copy of each object and array on the path. */
+function unsetIn(container, path, index) {
+    const key = path[index];
+    const last = index === path.length - 1;
+    if (Array.isArray(container)) {
+        if (!INDEX.test(key) || Number(key) >= container.length)
+            return container;
+        const copy = container.slice();
+        // An element of an array becomes null, as in MongoDB: the other elements keep their places
+        copy[Number(key)] = last ? null : unsetIn(copy[Number(key)], path, index + 1);
+        return copy;
+    }
+    if (!isObject(container) || !Object.hasOwn(container, key))
+        return container;
+    const copy = copyOf(container);
+    if (last)
+        delete copy[key];
+    else
+        put(copy, key, unsetIn(copy[key], path, index + 1));
+    return copy;
+}
+/**
+ * This function applies a patch to a value, and gives the new value: a JSON Merge Patch, or the
+ * operations `$set` and `$unset`. It does not change the value or the patch.
+ *
+ * - `$set` sets each field path, also to `null`. A missing or null part of a path becomes an object.
+ * - `$unset` removes each field path. An element of an array becomes `null`.
+ * - A value that is not an object becomes an empty object first.
+ *
+ * @throws TypeError when the patch has a problem (refer to `patchProblems`), or when a path of
+ *   `$set` goes through a value that is not an object, or past the end of an array
+ */
+export function applyPatch(value, fields) {
+    const problems = patchProblems(fields);
+    if (problems.length > 0)
+        throw new TypeError(`The patch is not correct: ${problems.join(". ")}`);
+    if (!isPatchOperations(fields))
+        return mergePatch(value, fields);
+    let result = isObject(value) ? value : {};
+    for (const [key, field] of definedEntries(fields.$set ?? {}))
+        result = setIn(result, key.split("."), 0, field);
+    for (const key of fields.$unset ?? [])
+        result = unsetIn(result, key.split("."), 0);
+    return result === value ? copyOf(value) : result;
+}
+//# sourceMappingURL=query.js.map