@osqd/jql 0.1.1

package/dist/collections.d.ts

@@ -0,0 +1,34 @@
+import { type CompileOptions } from "./core.js";
+import type { QueryLike, Source } from "./types.js";
+/** The first item that matches, or `undefined`. Stops at the first match. */
+export declare function find<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): V | undefined;
+export declare function find<T, Extra extends object = {}>(source: Source<T>, query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): T | undefined;
+/** The position of the first item that matches, or -1. For a `Map`, the position in insertion order. */
+export declare function findIndex<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): number;
+export declare function findIndex<T, Extra extends object = {}>(source: Source<T>, query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): number;
+/** Every item that matches, in order, as a new array. */
+export declare function filter<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): V[];
+export declare function filter<T, Extra extends object = {}>(source: Source<T>, query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): T[];
+/** How many items match. Counts in place rather than building the list it would count. */
+export declare function count<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): number;
+export declare function count<T, Extra extends object = {}>(source: Source<T>, query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): number;
+/** Whether any item matches. Stops at the first. */
+export declare function some<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): boolean;
+export declare function some<T, Extra extends object = {}>(source: Source<T>, query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): boolean;
+/** Whether every item matches. True for an empty collection. Stops at the first that does not. */
+export declare function every<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): boolean;
+export declare function every<T, Extra extends object = {}>(source: Source<T>, query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): boolean;
+/** The matches and the rest, in one pass. */
+export declare function partition<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): [V[], V[]];
+export declare function partition<T, Extra extends object = {}>(source: Source<T>, query: QueryLike<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): [T[], T[]];
+/** The entries of a `Map` whose value matches, as a new `Map` with the same keys. */
+export declare function filterMap<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): Map<K, V>;
+/**
+ * The properties of a plain object whose value matches, as a new object.
+ *
+ * Own enumerable properties only — the same ones `Object.entries` sees.
+ */
+export declare function filterRecord<V, Extra extends object = {}>(source: Readonly<Record<string, V>>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): Record<string, V>;
+/** The first value of a plain object that matches, with its key. */
+export declare function findEntry<V, Extra extends object = {}>(source: Readonly<Record<string, V>>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): [string, V] | undefined;
+export declare function findEntry<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, query: QueryLike<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): [K, V] | undefined;

package/dist/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/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/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;