@osqd/jql 0.1.1

package/dist/cjs/core.d.ts

@@ -0,0 +1,117 @@
+import { JqlError } from "./errors.js";
+import { type Reach } from "./internal/path.js";
+import { type Limits } from "./limits.js";
+import type { Matcher, QueryLike, UntypedQuery } from "./types.js";
+import { type Vocabulary } from "./vocabulary.js";
+/**
+ * The engine: a query document in, a predicate out.
+ *
+ * **Compile once, test many.** Everything that depends only on the query — validating it,
+ * resolving field names, splitting paths, building sets for `$in`, lower-casing for `$options:
+ * "i"`, compiling patterns — happens here, once. What comes back is a tree of small closures
+ * that does only the part that depends on the document. Filtering a million items with one
+ * query parses that query once, not a million times.
+ *
+ * **No code generation.** Emitting JavaScript source and calling `new Function` would be
+ * faster still, and it would also be refused by every page with a Content-Security-Policy
+ * worth having — including the dashboards in this project, whose build fails on a
+ * `new Function`. Closures run everywhere.
+ *
+ * **Cheapest first.** The parts of an `$and` are reordered so an equality test runs before a
+ * pattern and a pattern before a free-text walk, because the first part to fail decides the
+ * answer and the rest never run. Every operator is a pure test, so the order changes the
+ * cost and never the result.
+ *
+ * **No implicit cache.** A cache keyed on the query object would hand back a stale predicate
+ * the moment somebody edited the object they had already queried with — a filter that looks
+ * updated and is not. Compiling a small query costs about as much as testing a handful of
+ * documents, so the helpers compile per call, and a hot loop calls `compile` once and keeps
+ * the result.
+ */
+export interface CompileOptions<Extra extends object = {}> {
+    /** The field names, aliases and computed fields a query may use. Its fields become names a typed query may use. */
+    readonly vocabulary?: Vocabulary<never, Extra> | undefined;
+    /** How much of a query to accept. Default `DEFAULT_LIMITS`; use `UNTRUSTED_LIMITS` for queries from outside. */
+    readonly limits?: Partial<Limits> | undefined;
+    /**
+     * Where "now" comes from, for the relative dates in `{ "$date": { "$ago": "1h" } }`.
+     * Default the system clock, read **once**, when the query compiles.
+     *
+     * Read once because a window that moved while a scan was in progress would judge two
+     * items a second apart against different hours. It also means a long-lived compiled
+     * query keeps the instant it was compiled at: recompile to move the window, which costs
+     * well under a microsecond.
+     */
+    readonly now?: (() => number) | undefined;
+    /**
+     * Operators this project adds to the language, such as an address-in-network test that
+     * no amount of JSON could express.
+     *
+     * **A query using one is no longer portable JQL**, which is why their names must begin
+     * `$x`: somebody reading a stored filter can see at a glance that it needs more than a
+     * standard engine, and a future version of the language cannot collide with one.
+     */
+    readonly operators?: readonly OperatorDefinition[] | undefined;
+}
+/** An operator a project adds to the language. Its name must match `$x` followed by a capital: `$xCidr`. */
+export interface OperatorDefinition {
+    readonly name: string;
+    /**
+     * Builds the test, once, when the query compiles. Throw `JqlError` for an operand this
+     * operator cannot use; the message reaches whoever wrote the query.
+     */
+    readonly compile: (operand: unknown, at: string) => (value: unknown) => boolean;
+    /** Roughly what it costs against the others, so an `$and` can run the cheap parts first. Default 4. */
+    readonly cost?: number | undefined;
+    /** Whether it is also tried against each element of an array value. Default true, like the built-in operators. */
+    readonly elementwise?: boolean | undefined;
+}
+/** The operators that combine queries. */
+export declare const QUERY_OPERATORS: readonly string[];
+/** The operators that test a field. At the top of a query they test the item itself. */
+export declare const FIELD_OPERATORS: readonly string[];
+/**
+ * Operators whose meaning `$options: "i"` changes.
+ *
+ * Not in the barrel — this is the language's own list (specification §5.5), shared with
+ * `explain`, which has to know which pieces of a condition the flag travels with.
+ */
+export declare const CASE_AWARE: Set<string>;
+/**
+ * Compiles a query into a predicate.
+ *
+ * Throws `JqlError` for anything that is not a valid query, naming where in the query the
+ * problem is. A function passed in is returned as it is, so every helper that takes a
+ * query also takes a predicate somebody already has.
+ */
+export declare function compile<T = unknown, Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): Matcher<T>;
+/** Whether one value matches a query. For a one-off; in a loop, `compile` once instead. */
+export declare function matches<T, Extra extends object = {}>(value: T, query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): boolean;
+/**
+ * Checks a query, and hands back the predicate when it is a good one.
+ *
+ * What a service calls on a query it has just received, so it can answer 400 with the
+ * sentence rather than 500 with a stack. The predicate comes with it because the caller
+ * needs one next, and the two ways of getting it separately are both worse: compiling
+ * again costs a second compile, and — the reason this returns it rather than only a
+ * verdict — it is compiled from a second set of options, which is how a query gets
+ * checked against the untrusted limits and then run without them.
+ */
+export declare function validate<T = unknown>(query: unknown, options?: CompileOptions<object>): {
+    valid: true;
+    test: Matcher<T>;
+} | {
+    valid: false;
+    error: JqlError;
+};
+/**
+ * Marks a query from outside the type system — parsed JSON, a URL parameter — as one to be
+ * checked when it is compiled rather than by the compiler. Returns the same object.
+ */
+export declare function untyped(query: unknown): UntypedQuery;
+/**
+ * How a field name is reached, by the same rules a query uses. For sorting and projection,
+ * which must name fields exactly as the query beside them does. Not part of the public
+ * surface.
+ */
+export declare function reachField(name: string, vocabulary: Vocabulary<unknown, object> | undefined, at: string): Reach;

package/dist/cjs/errors.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The one way a query is refused.
+ *
+ * A query that looks right and matches nothing is the failure this library exists to
+ * prevent: a misspelt operator, a field value that is `undefined` because a variable was,
+ * a regex that does not compile. Each of those used to be a filter that silently let
+ * everything through or nothing through, and nobody could tell which from the result. So
+ * `compile` refuses, with a sentence saying what was wrong and where in the query it was.
+ */
+export declare class JqlError extends Error {
+    /**
+     * Where in the query the problem is, written the way you would reach it in code:
+     * `$or[1].age.$gt`. Empty for the query as a whole.
+     */
+    readonly at: string;
+    constructor(message: string, at?: string);
+}

package/dist/cjs/explain.d.ts

@@ -0,0 +1,30 @@
+import { type CompileOptions } from "./core.js";
+import type { QueryLike } from "./types.js";
+/**
+ * Why one item does or does not match a query.
+ *
+ * A filter that returns nothing tells you nothing about which part of it was wrong. This
+ * takes the query apart and answers for each piece separately, with the values it actually
+ * read, so an operator looking at a row and a saved filter that disagree can see the clause
+ * that decided it.
+ *
+ * **It runs the real engine on every piece.** Each clause is compiled on its own and tested,
+ * rather than interpreted here by a second reading of the language — a second reading would
+ * be a second set of semantics, and the one thing worse than a filter you cannot explain is
+ * an explanation that does not match what the filter did. The cost is one small compile per
+ * clause, which is why this is for one item at a time and `compile` is for the collection.
+ */
+export interface Explanation {
+    /** Whether this clause holds for the item. */
+    readonly matched: boolean;
+    /** Where the clause is in the query, written as it would be reached in code: `$or[1].age.$gt`. */
+    readonly at: string;
+    /** The clause itself, as the JSON fragment that was evaluated. */
+    readonly clause: unknown;
+    /** One sentence: what was read, or how the parts came out. */
+    readonly because: string;
+    /** The clauses this one is made of. */
+    readonly parts?: readonly Explanation[];
+}
+/** Explains one item against one query. */
+export declare function explain<T, Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, item: T, options?: CompileOptions<Extra>): Explanation;

package/dist/cjs/global.d.ts

@@ -0,0 +1,90 @@
+import type { CompileOptions } from "./core.js";
+import type { FieldName, QueryLike, Request, Source } from "./types.js";
+export { install, uninstall } from "./array.js";
+declare global {
+    interface ReadonlyArray<T> {
+        /** The first item matching the query, or `undefined`. */
+        jqlSearch<Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): T | undefined;
+        /** Every item matching the query, as a new array. */
+        jqlFilter<Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): T[];
+        /** How many items match. */
+        jqlCount<Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): number;
+        /** Whether any item matches. */
+        jqlSome<Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): boolean;
+        /** Whether every item matches. True when there are none. */
+        jqlEvery<Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): boolean;
+        /** The position of the first match, or -1. */
+        jqlFindIndex<Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): number;
+        /** The matches and the rest. */
+        jqlPartition<Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): [T[], T[]];
+        /** A whole request: `where`, `sort`, `skip`, `limit`, `fields`, `omit`. */
+        jqlQuery<Extra extends object = {}>(request: Request<T, NoInfer<Extra>> & {
+            readonly fields: readonly FieldName<T, NoInfer<Extra>>[];
+        }, options?: CompileOptions<Extra>): Record<string, unknown>[];
+        /** With `omit`, each result is a copy without those paths — which is `Partial<T>`, not `T`. */
+        jqlQuery<Extra extends object = {}>(request: Request<T, NoInfer<Extra>> & {
+            readonly omit: readonly FieldName<T, NoInfer<Extra>>[];
+        }, options?: CompileOptions<Extra>): Partial<T>[];
+        jqlQuery<Extra extends object = {}>(request?: Request<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): T[];
+    }
+    interface Array<T> {
+        jqlSearch<Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): T | undefined;
+        jqlFilter<Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): T[];
+        jqlCount<Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): number;
+        jqlSome<Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): boolean;
+        jqlEvery<Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): boolean;
+        jqlFindIndex<Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): number;
+        jqlPartition<Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): [T[], T[]];
+        jqlQuery<Extra extends object = {}>(request: Request<T, NoInfer<Extra>> & {
+            readonly fields: readonly FieldName<T, NoInfer<Extra>>[];
+        }, options?: CompileOptions<Extra>): Record<string, unknown>[];
+        jqlQuery<Extra extends object = {}>(request: Request<T, NoInfer<Extra>> & {
+            readonly omit: readonly FieldName<T, NoInfer<Extra>>[];
+        }, options?: CompileOptions<Extra>): Partial<T>[];
+        jqlQuery<Extra extends object = {}>(request?: Request<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): T[];
+    }
+    interface ArrayConstructor {
+        /** The first item of any array, array-like, iterable or `Map` (by value) matching the query. */
+        jqlSearch<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): V | undefined;
+        jqlSearch<T, Extra extends object = {}>(source: Source<T>, query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): T | undefined;
+        jqlFilter<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): V[];
+        jqlFilter<T, Extra extends object = {}>(source: Source<T>, query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): T[];
+        jqlCount<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): number;
+        jqlCount<T, Extra extends object = {}>(source: Source<T>, query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): number;
+        jqlSome<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): boolean;
+        jqlSome<T, Extra extends object = {}>(source: Source<T>, query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): boolean;
+        jqlEvery<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): boolean;
+        jqlEvery<T, Extra extends object = {}>(source: Source<T>, query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): boolean;
+        jqlFindIndex<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): number;
+        jqlFindIndex<T, Extra extends object = {}>(source: Source<T>, query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): number;
+        jqlPartition<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): [V[], V[]];
+        jqlPartition<T, Extra extends object = {}>(source: Source<T>, query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): [T[], T[]];
+        jqlQuery<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, request: Request<V, NoInfer<Extra>> & {
+            readonly fields: readonly FieldName<V, NoInfer<Extra>>[];
+        }, options?: CompileOptions<Extra>): Record<string, unknown>[];
+        jqlQuery<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, request: Request<V, NoInfer<Extra>> & {
+            readonly omit: readonly FieldName<V, NoInfer<Extra>>[];
+        }, options?: CompileOptions<Extra>): Partial<V>[];
+        jqlQuery<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, request?: Request<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): V[];
+        jqlQuery<T, Extra extends object = {}>(source: Source<T>, request: Request<T, NoInfer<Extra>> & {
+            readonly fields: readonly FieldName<T, NoInfer<Extra>>[];
+        }, options?: CompileOptions<Extra>): Record<string, unknown>[];
+        jqlQuery<T, Extra extends object = {}>(source: Source<T>, request: Request<T, NoInfer<Extra>> & {
+            readonly omit: readonly FieldName<T, NoInfer<Extra>>[];
+        }, options?: CompileOptions<Extra>): Partial<T>[];
+        jqlQuery<T, Extra extends object = {}>(source: Source<T>, request?: Request<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): T[];
+    }
+    interface Map<K, V> {
+        /** The first value matching the query. */
+        jqlSearch<Extra extends object = {}>(query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): V | undefined;
+        /** The entries whose value matches, as a new `Map`. */
+        jqlFilter<Extra extends object = {}>(query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): Map<K, V>;
+        jqlCount<Extra extends object = {}>(query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): number;
+    }
+    interface Set<T> {
+        jqlSearch<Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): T | undefined;
+        /** The members that match, as a new `Set`. */
+        jqlFilter<Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): Set<T>;
+        jqlCount<Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): number;
+    }
+}

package/dist/cjs/group.d.ts

@@ -0,0 +1,47 @@
+import { type CompileOptions } from "./core.js";
+import type { QueryLike, Source } from "./types.js";
+/**
+ * Counting the matches by one field.
+ *
+ * Every dashboard in this family ends up doing this: a thousand requests become a dozen
+ * actors you can read down, a feed becomes counts per verdict, per rule, per path. Each
+ * one used to write the tally loop itself, which is where the disagreements crept in —
+ * whether an item with two tags counts twice, what happens to the items with no value at
+ * all, and what order the groups come back in. It is one answer now.
+ *
+ * One pass over the source, one `Map` of counts, and the items kept only when asked for.
+ */
+export interface Grouped<T> {
+    /** The value that names the group. `null` covers everything that cannot name one — see below. */
+    readonly key: unknown;
+    readonly count: number;
+    /** Present only when `items` asked for them. */
+    readonly items?: readonly T[] | undefined;
+}
+export interface GroupOptions<T, Extra extends object = {}> extends CompileOptions<Extra> {
+    /** Which items to count. Absent counts them all. */
+    readonly where?: QueryLike<T, NoInfer<Extra>> | undefined;
+    /** How many groups to return. Absent returns all of them. */
+    readonly limit?: number | undefined;
+    /** Keep the items too: `true` for all of them, a number for the first few. Default: counts only. */
+    readonly items?: boolean | number | undefined;
+    /** `"count"` (default) puts the largest group first; `"key"` orders by the value itself. */
+    readonly sort?: "count" | "key" | undefined;
+}
+/**
+ * Groups the matching items by the value at `by`, largest group first.
+ *
+ * Three rules worth knowing, each because leaving it unsaid is how two dashboards came to
+ * disagree about the same feed:
+ *
+ * - **An item counts once in each group it belongs to.** A path that reaches an array —
+ *   tags, say — puts the item in a group per distinct tag, and a repeated value inside one
+ *   item counts once.
+ * - **Everything that cannot name a group shares `null`**: a missing field, a `null`, a value
+ *   that is an object, and an empty list. That is the "no rule matched" heading, and it is a
+ *   real answer rather than a silently dropped row — which is the point, because it is what
+ *   makes the counts add up to the number of rows there are.
+ * - **Ties break by the key**, so the same data always comes back in the same order.
+ */
+export declare function group<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, by: string, options?: GroupOptions<V, Extra>): Grouped<V>[];
+export declare function group<T, Extra extends object = {}>(source: Source<T>, by: string, options?: GroupOptions<T, Extra>): Grouped<T>[];

package/dist/cjs/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `@osqd/jql` — the JSON Query Language and its engine.
+ *
+ * The query methods on `Array`, `Map` and `Set` are in `@osqd/jql/global`, and the
+ * search-box syntax is in `@osqd/jql/text`. Neither is loaded from here.
+ */
+export { compile, matches, untyped, validate, FIELD_OPERATORS, QUERY_OPERATORS } from "./core.js";
+export { count, every, filter, filterMap, filterRecord, find, findEntry, findIndex, partition, some } from "./collections.js";
+export { search } from "./search.js";
+export { group } from "./group.js";
+export { explain } from "./explain.js";
+export { canonical, fingerprint } from "./canonical.js";
+export { plan } from "./plan.js";
+export { countAsync, everyAsync, filterAsync, filterStream, findAsync, searchAsync, someAsync } from "./async.js";
+export { defineVocabulary } from "./vocabulary.js";
+export { JqlError } from "./errors.js";
+export { DEFAULT_LIMITS, UNTRUSTED_LIMITS } from "./limits.js";
+export type { CompileOptions, OperatorDefinition } from "./core.js";
+export type { AsyncSource } from "./async.js";
+export type { Capabilities, Kept, Plan } from "./plan.js";
+export type { Grouped, GroupOptions } from "./group.js";
+export type { Explanation } from "./explain.js";
+export type { Limits } from "./limits.js";
+export type { FieldDefinition, FieldKind, Vocabulary, VocabularyDefinition, VocabularyField } from "./vocabulary.js";
+export type { Condition, DateLiteral, ElementOf, FieldName, FieldReference, FieldQuery, JsonValue, Literal, LogicalOperators, LooseQuery, Matcher, Path, PathValue, Query, QueryLike, RelativeDate, Request, Sort, SortDirection, Source, TextSearch, TypeName, UntypedQuery, } from "./types.js";

package/dist/cjs/internal/closest.d.ts

@@ -0,0 +1,9 @@
+/**
+ * "Did you mean" for names that almost exist.
+ *
+ * An unknown operator is refused either way; naming the one that was probably meant turns
+ * a lookup in the documentation into a one-character fix.
+ */
+export declare function closest(word: string, candidates: Iterable<string>): string | undefined;
+/** The suffix of an error sentence that offers the likely name, or nothing. */
+export declare function didYouMean(word: string, candidates: Iterable<string>): string;

package/dist/cjs/internal/duration.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Durations, for the relative dates a saved filter is written with.
+ *
+ * `"1h"`, `"30m"`, `"1h30m"`, `"7d"`. Written as one or more counts with a unit, largest
+ * first by convention but in any order, because a filter is typed by a person and
+ * `"30m1h"` means what it says.
+ *
+ * Months and years are deliberately absent: neither has a fixed length, so `"1mo"` would
+ * mean something slightly different in February, and a filter whose window changes size
+ * with the calendar is one nobody can reason about. Use days or weeks.
+ */
+/** The unit names, for an error that says what is accepted. */
+export declare const DURATION_UNITS: string[];
+/** A duration in milliseconds, or `undefined` when the text is not one. */
+export declare function parseDuration(text: string): number | undefined;

package/dist/cjs/internal/equal.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Equality between a document value and a query literal.
+ *
+ * Built once per literal rather than called generically, because the literal is known at
+ * compile time and the document value is the only thing that changes: a primitive
+ * literal becomes one `===`, and only an object or array literal pays for a walk.
+ *
+ * The rules, which the specification states and every implementation must share:
+ * objects are equal when they have the same keys with equal values, **in any order**
+ * (JSON does not promise key order, so a comparison that depended on it would depend on
+ * whoever serialised the query); a key whose value is `undefined` counts as absent;
+ * arrays are equal element by element, in order; a `$date` literal equals any value that
+ * reads as the same instant.
+ */
+export type Equals = (value: unknown) => boolean;
+/**
+ * The same whole number as a big integer, when a literal is one and could be written either
+ * way.
+ *
+ * Settled once, when the query compiles, so the comparison stays a single `===` against a
+ * value prepared in advance. Only a whole number gets one: nothing is a big integer and a
+ * fraction, and a string or a boolean can never be one either.
+ */
+export declare function alsoBig(literal: unknown): bigint | undefined;
+export declare function equalsLiteral(literal: unknown, now: number, ignoreCase?: boolean): Equals;
+/**
+ * Equality between two values that both came out of a document, for `$field` references.
+ *
+ * The same rules as equality with a literal — same type, arrays in order, objects in any
+ * key order — but neither side is known when the query compiles, so nothing can be
+ * prepared. Missing is not equal to anything, including itself: a reference that reaches
+ * nothing matches nothing.
+ */
+export declare function valuesEqual(a: unknown, b: unknown): boolean;

package/dist/cjs/internal/glob.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Glob matching: `*`, `?`, and `\` to escape either of them.
+ *
+ * What people mean when they reach for a pattern in a search box — `/api/*`,
+ * `*.example.com` — and the reason it is not `$regex` with the sharp edges filed off: this
+ * runs without a regular-expression engine, so it is available when patterns are turned
+ * off for untrusted callers, and it cannot backtrack exponentially.
+ *
+ * No character classes. `[a-z]` is a literal `[a-z]`, because half a class syntax is worse
+ * than none: somebody would write `[!abc]` expecting negation and get a match against those
+ * four characters instead, with nothing to say so.
+ *
+ * **A pattern is taken apart once and becomes the narrowest matcher that fits it.** Nearly
+ * every real glob is a prefix, a suffix, something in the middle, or a run of literals
+ * separated by stars, and each of those is one or two native string calls per value. Only a
+ * pattern with `?` in it walks character by character, and only that walk pays for splitting
+ * the text into characters — which, measured against `startsWith`, was four times the cost of
+ * the whole comparison.
+ */
+export type GlobMatcher = (text: string) => boolean;
+export declare function compileGlob(pattern: string): GlobMatcher;
+/**
+ * The same glob as the body of a regular expression, for a target that speaks patterns
+ * rather than running the matcher — a store this query is being pushed down to.
+ *
+ * It shares the tokenizer with the matcher on purpose: an escape read one way here and
+ * another way there would mean a query that found different things depending on which half
+ * of the system answered it.
+ */
+export declare function compileGlobPattern(pattern: string, quoteLiteral: (text: string) => string): string;

package/dist/cjs/internal/order.d.ts

@@ -0,0 +1,24 @@
+/**
+ * One total order over every value a document can hold.
+ *
+ * A sort has to put *something* first when one item's field is a number and another's is
+ * a string, or missing. The order is fixed and written down in the specification, so two
+ * implementations sort a shared result the same way:
+ *
+ *   missing and null < numbers < strings < objects < booleans < dates
+ *
+ * Strings compare by UTF-16 code unit, not by locale. A locale-aware sort would put a
+ * shared link's rows in a different order for each reader, which is worse than an order
+ * that is merely unidiomatic for some of them. Objects compare equal to one another, so
+ * their order is the order they arrived in.
+ */
+export declare function compareValues(a: unknown, b: unknown): number;
+/**
+ * The value an item sorts by, from everything its path reached.
+ *
+ * A path that reaches an array — or fans out over one — reaches several values. Ascending
+ * sorts by the smallest of them and descending by the largest: an order
+ * by "tags" puts first whatever has the tag that sorts first. Arrays nested past sixteen
+ * levels are passed over, so an array that contains itself ends the walk.
+ */
+export declare function sortValue(values: readonly unknown[], descending: boolean, depth?: number): unknown;

package/dist/cjs/internal/path.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Reaching a field inside a document.
+ *
+ * A path is dot-separated: `address.city`, `items.id`, `items.0.id`. Three rules:
+ *
+ * - **An array is seen through.** `items.id` reaches the `id` of every element, and a
+ *   condition on it holds when it holds for any of them.
+ * - **A numeric segment on an array is a position.** `items.0.id` is the first element's.
+ * - **A `Map` is read by key**, so a document that keeps a lookup table in a `Map` can be
+ *   queried the same way as one that keeps it in an object.
+ *
+ * Only own properties are read. `{ constructor: { $exists: true } }` would otherwise match
+ * every object ever made, and `__proto__` would reach somewhere a query has no business
+ * being. The check costs a `hasOwn` call, so it is paid only for the handful of names
+ * `Object.prototype` and `Map.prototype` actually have — every other name is read
+ * directly. `Map.prototype` is on the list because a `Map` document read directly would
+ * answer `size` or `get` with its own method rather than with the entry of that name.
+ */
+/**
+ * Calls `test` with each value the path reaches, stopping at the first `true`.
+ *
+ * A path that reaches nothing calls `test(undefined)` once, so "missing" is a value a
+ * condition can ask about: that is how `{ field: null }` and `$exists: false` see it.
+ */
+export type Reach = (document: unknown, test: (value: unknown) => boolean) => boolean;
+/** A single-valued read, for paths that cannot fan out. Absent when the path can. */
+export type Read = (document: unknown) => unknown;
+/** What a probe returns when the path met an array before its last segment, and so may reach several values. */
+export declare const FANOUT: unique symbol;
+/**
+ * A straight read of a multi-segment path: the one value it reaches, or `FANOUT` if an
+ * array stood in the way and only `Reach` can answer.
+ *
+ * The point is the common case. `address.city` on a record with no arrays on the way has
+ * exactly one value, and reading it directly lets the engine test it the way a hand-written
+ * `p.address.city === "x"` would — one read, one comparison — instead of through a walk and
+ * a callback. A missing or primitive step reads as `undefined`, the same as `Reach` sees it.
+ */
+export type Probe = (document: unknown) => unknown;
+/** Whether a name could be found on a plain object's prototype, and so must always be asked for carefully. */
+export declare function needsGuard(key: string): boolean;
+/**
+ * What a plain object's prototype is, for the cheapest plainness test there is.
+ *
+ * `document.__proto__ === PLAIN` is a map check — about as fast as reading a field — where
+ * `Object.getPrototypeOf` is a call and `Object.hasOwn` is a second lookup. Reading it is
+ * safe in both directions: a document carrying its own `__proto__` field (which is what
+ * `JSON.parse` makes of one) simply fails the test and takes the careful path, and so does
+ * anything with a prototype of its own.
+ */
+export declare const PLAIN: Object;
+/**
+ * One field of one value: own properties and `Map` entries, nothing else.
+ *
+ * Ownership is checked **before** the read, not after, and for every name rather than for a
+ * list of known-inherited ones. The list was only ever `Object.prototype` and
+ * `Map.prototype`, so a document that was a class instance answered `{ role: "admin" }` from
+ * its prototype — and `{ secret: … }` by *running* an inherited getter, which is a query
+ * executing code the document's author wrote. Asking first is also why no accessor outside
+ * the item can run at all.
+ */
+export declare function readOwn(value: object, key: string): unknown;
+/**
+ * The value at a single-segment path.
+ *
+ * The overwhelmingly common case — `{ id: 2 }` — so it is written out: a direct property
+ * read, with the `Map` check paid only when the read found nothing, which a plain object
+ * with the field never does.
+ */
+export declare function readKey(key: string): Read;
+/** The whole document, for queries that are conditions on the value itself. */
+export declare const readSelf: Read;
+/**
+ * Builds the walk for a multi-segment path.
+ *
+ * A loop while the path meets only objects, which is nearly always, and the recursive
+ * fan-out only from the first array it meets. `address.city` on a record with no arrays in
+ * it costs two property reads and one call.
+ */
+export declare function reachPath(keys: readonly string[]): Reach;
+/** Builds the straight read for a multi-segment path. */
+export declare function probePath(keys: readonly string[]): Probe;
+/** The same, from a value some other accessor produced. */
+export declare function probeFrom(read: Read, keys: readonly string[]): Probe;
+/** Continues a walk from a value some other accessor produced. */
+export declare function reachFrom(read: Read, keys: readonly string[]): Reach;
+/**
+ * How many segments a path may have.
+ *
+ * The same number as the document depth above, and for the same reason: a path longer than
+ * the deepest document a walk will follow can reach nothing anyway, so refusing it costs a
+ * query nothing real. What it buys is two things. A field name is the one part of a query
+ * whose size the node count does not bound — `{"a.a.a…": 1}` is a single node however long
+ * it is — and each segment becomes an object and a step in a walk, so a field name pasted
+ * from somewhere could turn a small query into a large one.
+ *
+ * And it makes the same path mean the same thing everywhere. Projection walked its own tree
+ * of segments and stopped at sixty-four, silently, so a query matched on a path that
+ * `fields` then dropped from the result: the filter and the projection disagreed about a
+ * path they were both given.
+ */
+export declare const MAX_PATH_SEGMENTS = 512;
+/**
+ * Splits a field name into segments, refusing the ones that can reach nothing.
+ *
+ * Returns the reason as a sentence for the caller to raise, so this module stays free of
+ * the error type and its location bookkeeping.
+ */
+export declare function splitPath(path: string): string[] | string;

package/dist/cjs/internal/record.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Writing a field onto a result object.
+ *
+ * `target[key] = value` looks harmless until the key is `__proto__`. Assignment goes
+ * through the setter inherited from `Object.prototype`, which *replaces the object's
+ * prototype* instead of adding a property — so the field the caller asked for is missing
+ * and the object answers to names nobody put on it.
+ *
+ * It is reachable from data rather than from code: `JSON.parse('{"__proto__": …}')` makes
+ * an own `__proto__` property, so any document read from a file, a request body or a store
+ * can carry one. Projecting such a document used to lose that field and hand back a result
+ * whose prototype was whatever the document said, which the projection's own test could not
+ * see because the property it was looking for was genuinely there — on the prototype.
+ *
+ * Defining the property puts it where it was meant to go. Every other key takes the plain
+ * assignment, so the guard costs one comparison on the path that builds results.
+ */
+export declare function setField(target: Record<string, unknown>, key: string, value: unknown): void;

package/dist/cjs/internal/values.d.ts

@@ -0,0 +1,41 @@
+import type { DateLiteral, FieldReference, TypeName } from "../types.js";
+/** An object literal or a JSON-parsed object: what a query document is made of. */
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** `{ $date: … }` and nothing else. */
+export declare function isDateLiteral(value: unknown): value is DateLiteral;
+/** `{ $field: "path" }` and nothing else: a comparison with another field of the same item. */
+export declare function isFieldReference(value: unknown): value is FieldReference;
+/**
+ * The instant a `$date` literal stands for, in epoch milliseconds, or `NaN`.
+ *
+ * `now` is passed in rather than read here, because a query holding `{ "$ago": "1h" }` has
+ * to resolve against one instant for the whole run: reading the clock per comparison would
+ * let the window move while a scan is in progress, so two items a second apart could be
+ * judged against different hours. It is also what makes a relative filter testable without
+ * waiting.
+ */
+export declare function resolveDate(value: unknown, now: number): number;
+/**
+ * An instant from a string, read the same way on every machine.
+ *
+ * JavaScript reads a date-only string as midnight **UTC** and a timestamp with no offset as
+ * **local time** — so `"2026-01-01T12:00:00"` was a different instant in Tokyo and in London,
+ * and a query and a document that both held one answered differently depending on where the
+ * process happened to be running. That is the failure the language already rules out for
+ * `"12/31/2020"`: the same query meaning two things. A missing offset is UTC here, which is
+ * the rule the date-only form already follows.
+ */
+export declare function instant(text: string): number;
+export declare function toTime(value: unknown): number;
+/** The type names `$type` knows, in one list, so the error for a wrong one can offer the right one. */
+export declare const TYPE_NAMES: readonly TypeName[];
+/** Whether a document value is of the named type. A missing value is of no type. */
+export declare function isOfType(value: unknown, type: TypeName): boolean;
+/**
+ * A readable name for a value in an error sentence.
+ *
+ * Specific about what it was given, because "a query is an object, not an object" — which
+ * is what a `Map`, a `Set` and a class instance all used to produce — tells the reader
+ * nothing at all about the thing they passed.
+ */
+export declare function describe(value: unknown): string;