@osqd/jql 0.1.1

package/dist/cjs/limits.d.ts

@@ -0,0 +1,64 @@
+/**
+ * How much of a query the engine will take.
+ *
+ * Queries arrive from places the caller does not control — a URL, a request body, a
+ * saved filter somebody else wrote — and every limit here is a way such a query could
+ * otherwise cost more than the data it filters. Each one refuses with a `JqlError` rather
+ * than truncating, because a query that was quietly cut short answers a different
+ * question from the one that was asked.
+ *
+ * The defaults are far past anything a person writes and far short of anything that
+ * hurts. The caps are exported so a caller can say what it accepts in its own
+ * documentation and refuse a query before it is even parsed.
+ */
+export interface Limits {
+    /** How deep operators may nest. Default 32: recursion over pasted input must stop well short of the stack. */
+    readonly maxDepth: number;
+    /** How many operators and fields a query may hold in total. Default 10 000. `$in` lists do not count: they cost one set lookup each. */
+    readonly maxNodes: number;
+    /** The longest `$regex` pattern. Default 1024. */
+    readonly maxPatternLength: number;
+    /**
+     * The longest `$glob`. Default 1024, and 256 for untrusted input.
+     *
+     * A glob cannot backtrack exponentially, but matching one holding `?` is the length of the
+     * pattern times the length of the value — so a megabyte of `?` against a megabyte of text
+     * is hours per document. It has a cap of its own because `$regex` is turned *off* for
+     * untrusted callers while `$glob` stays on, which is exactly when the cap has to hold.
+     */
+    readonly maxGlobLength: number;
+    /** How deep `$text` looks into a document. Default 16: past that a document is a graph, not a record. */
+    readonly maxTextDepth: number;
+    /**
+     * Which operators a query may use. Default `"all"`.
+     *
+     * An allowlist, because a public endpoint's answer to "what may a caller ask?" should be
+     * a list it wrote rather than everything the language grows later. `$text` walks a whole
+     * document and `$elemMatch` carries a query of its own; an endpoint that needs neither can
+     * say so once, here, instead of discovering later which of them somebody found.
+     *
+     * Names are checked when the query compiles: an operator outside the list is refused by
+     * name, never ignored. `$options` and `$comment` are exempt — they modify and annotate
+     * rather than ask anything — and `$field` counts as an operator, because comparing two
+     * fields is a capability in its own right.
+     */
+    readonly allowOperators: readonly string[] | "all";
+    /**
+     * Whether `$regex` is accepted at all. Default `true`.
+     *
+     * Turn it off for queries from untrusted callers. No engine can tell a pattern that
+     * backtracks for a minute from one that does not without running it, and the string
+     * operators (`$contains`, `$startsWith`, `$endsWith`, `$word`) answer almost every
+     * question a pattern would, in linear time.
+     */
+    readonly allowRegex: boolean;
+}
+/** The defaults, frozen, so they can be spread and never edited in place. */
+export declare const DEFAULT_LIMITS: Readonly<Limits>;
+/**
+ * What an untrusted query gets: no patterns, and a tighter size.
+ *
+ * Public so a service taking queries from a URL can use the same answer as every other
+ * service in the project, rather than each one picking its own numbers.
+ */
+export declare const UNTRUSTED_LIMITS: Readonly<Limits>;

package/dist/cjs/operators.d.ts

@@ -0,0 +1,81 @@
+/**
+ * What each field operator means, as a test on one value.
+ *
+ * Every builder here runs once, when a query is compiled, and returns the smallest
+ * closure that answers its question: the operand is validated, normalised and, where it
+ * helps, turned into a `Set` or a lower-cased copy before any document is seen. The
+ * returned test only ever does the part that depends on the document.
+ *
+ * None of these knows about arrays or paths. Whether a test is also tried against each
+ * element of an array, and how a field is reached, is `core.ts`'s business — so each
+ * operator's meaning is written exactly once.
+ */
+export type Test = (value: unknown) => boolean;
+export declare const NEVER: Test;
+/**
+ * Equality with one literal.
+ *
+ * `null` also matches a missing field, because "has no value" is what
+ * people mean by it far more often than "has the value null". `$exists` is there for
+ * the times the difference matters.
+ */
+export declare function equalsTest(literal: unknown, ignoreCase: boolean, at: string, now: number): Test;
+/** Membership. A `Set` for the primitives, and a walk only for the object and array literals. */
+export declare function inTest(list: unknown, ignoreCase: boolean, at: string, now: number): Test;
+type Ordering = "$gt" | "$gte" | "$lt" | "$lte";
+/**
+ * An ordering comparison.
+ *
+ * Only like with like: a number against numbers (and bigints), a string against strings
+ * in code-unit order, a `$date` against anything that reads as a date. Nothing is
+ * coerced, so `"10"` is not greater than `9` — a comparison that converted would give a
+ * different answer depending on which side happened to be a string, and a query that
+ * means different things on different documents is not one anybody can reason about.
+ */
+export declare function orderTest(operator: Ordering, bound: unknown, at: string, now: number): Test;
+type StringOperator = "$contains" | "$startsWith" | "$endsWith" | "$word" | "$glob";
+/**
+ * The string operators, each taking one value or a list meaning "any of these".
+ *
+ * A list is there because "the path starts with any of `/health`, `/metrics`" is a single
+ * thought, and spelling it as an `$or` of three conditions makes it three.
+ */
+export declare function stringTest(operator: StringOperator, operand: unknown, ignoreCase: boolean, at: string, maxGlobLength?: number): Test;
+/**
+ * The value as a whole component of the text: bounded on each side by the start or end of
+ * the text, or by a character that is not a letter or digit.
+ *
+ * Ported from BotHandler's actor matching, where it replaced a substring test that let
+ * `1.2.3.4` match `1.2.3.45` and `11.2.3.4` — so excluding one address excluded its
+ * neighbours too. A side of the value that is itself a separator has chosen its own
+ * boundary: `203.0.113.` finds the whole network.
+ */
+export declare function containsWord(actual: string, wanted: string): boolean;
+export declare function parseOptions(options: unknown, at: string): string;
+export declare function regexTest(pattern: unknown, flags: string, limits: {
+    allowRegex: boolean;
+    maxPatternLength: number;
+}, at: string): Test;
+export declare function typeTest(operand: unknown, at: string): Test;
+export declare function modTest(operand: unknown, at: string): Test;
+/** `$all`: every literal is equal to the value or to one of its elements. An empty list matches nothing. */
+export declare function allTest(list: unknown, ignoreCase: boolean, at: string, now: number): Test;
+/**
+ * The order of two values that both came out of a document, or `undefined` when they
+ * cannot be compared.
+ *
+ * Only like with like, as everywhere else in the language: numbers with numbers, strings
+ * with strings, dates with dates. Nothing is read as a date here, because neither side is
+ * a query saying it is one — `{ "$field": … }` compares what the item holds.
+ */
+export declare function orderOf(a: unknown, b: unknown): number | undefined;
+/**
+ * Refuses a literal JSON cannot carry.
+ *
+ * A `RegExp`, a `Date`, a function or `undefined` in a query would work in the process
+ * that wrote it and mean something else — or nothing — once the query was serialised.
+ * The language is the JSON, so the engine holds to it even when handed an object that
+ * could have been more.
+ */
+export declare function checkLiteral(value: unknown, at: string, depth?: number): void;
+export {};

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/dist/cjs/plan.d.ts

@@ -0,0 +1,79 @@
+import { type CompileOptions } from "./core.js";
+import type { QueryLike, UntypedQuery } from "./types.js";
+/**
+ * Splitting a query between a store and this engine.
+ *
+ * A backend can usually answer part of a question — an index on a field, an operator it has
+ * natively — and nothing of the rest. The shape that works is the one HackerPot's stores
+ * already use: push what the store can do, keep what it cannot, and make sure the two
+ * together are exactly the question that was asked.
+ *
+ * That last part is the whole contract, and it is why this splits only on **conjunctions**.
+ * A query's keys all have to hold, and so do the parts of an `$and`, so each one can go to
+ * either side independently. Anything else — a branch of an `$or`, an operator inside a
+ * condition — cannot be split without widening or narrowing what is asked, so a conjunct is
+ * pushed whole or not at all:
+ *
+ *     pushed ∧ remaining ≡ query
+ *
+ * The store filters with `pushed` and this engine filters what comes back with `remaining`.
+ * Neither side is ever wider than the query, so a caller that runs only `pushed` gets too
+ * many items rather than too few — but `complete` says when that is safe, and it is the only
+ * thing worth checking before skipping the second pass.
+ */
+export interface Capabilities {
+    /**
+     * The fields the store can filter on, as the store names them — a path, after any
+     * vocabulary alias is resolved. `"all"` for a store that can filter on anything.
+     *
+     * A vocabulary field that is *computed* is never pushed whatever this says: the store has
+     * no way to run a function that lives here.
+     */
+    readonly fields?: readonly string[] | "all" | undefined;
+    /** The operators the store can answer, or `"all"`. Names are JQL's, not the store's. */
+    readonly operators?: readonly string[] | "all" | undefined;
+    /** Whether the store can answer `$or`. Default `false`: plenty of key-value stores cannot. */
+    readonly or?: boolean | undefined;
+    /** Whether it can answer a negation — `$not`, `$nor`, `$ne`, `$nin`, `$exists: false`. Default `false`. */
+    readonly not?: boolean | undefined;
+    /**
+     * A last word on one field's condition, for a store whose limits depend on the values
+     * rather than only on the operator names.
+     *
+     * MongoDB is the example this exists for: it answers `$eq` exactly, but not `$eq` against
+     * an embedded document (its equality is key-order sensitive where JQL's is not), and not
+     * the case-insensitive form of one. Without a say on the values, a target has to choose
+     * between dropping `$eq` altogether and pushing a clause that comes back with the wrong
+     * rows.
+     *
+     * The condition is given as written, with a bare value shown as `{ $eq: value }`, and the
+     * field under the name the store knows. Returning `false` keeps the clause here.
+     */
+    readonly accepts?: ((field: string, condition: Readonly<Record<string, unknown>>) => boolean) | undefined;
+}
+export interface Kept {
+    /** Where the conjunct is in the query. */
+    readonly at: string;
+    /** The conjunct itself. */
+    readonly clause: unknown;
+    /** Why the store cannot answer it. */
+    readonly why: string;
+}
+export interface Plan {
+    /** What the store should filter by, or `undefined` when it can answer nothing. */
+    readonly pushed: UntypedQuery | undefined;
+    /** What this engine must still filter, or `undefined` when the store answers everything. */
+    readonly remaining: UntypedQuery | undefined;
+    /** True when `remaining` is `undefined`: the store's answer needs no second pass. */
+    readonly complete: boolean;
+    /** One entry per conjunct that stayed here, and why. */
+    readonly kept: readonly Kept[];
+}
+/**
+ * Splits a query into the part a store can answer and the part that stays here.
+ *
+ * Relative dates in the pushed part are resolved to instants, so what the store receives is
+ * self-contained: `{ "$ago": "1h" }` means nothing to a backend, and resolving it here keeps
+ * both halves of the split judged against the same moment.
+ */
+export declare function plan<T, Extra extends object = {}>(query: QueryLike<T, NoInfer<Extra>>, capabilities: Capabilities, options?: CompileOptions<Extra>): Plan;

package/dist/cjs/search.d.ts

@@ -0,0 +1,42 @@
+import { type CompileOptions } from "./core.js";
+import type { FieldName, Request, Source } from "./types.js";
+type Items<T> = Source<T> | ReadonlyMap<unknown, T>;
+/**
+ * Runs a request. With `fields`, each result is a new object holding only those paths.
+ *
+ * A `Map` is read by value, like everywhere else in this library, so its overloads come
+ * first: a `Map` also satisfies `Iterable<[key, value]>`, and without them the types would
+ * describe a request over the pairs while the code ran one over the values.
+ */
+export declare function search<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>[];
+export declare function search<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>[];
+export declare function search<K, V, Extra extends object = {}>(source: ReadonlyMap<K, V>, request?: Request<V, NoInfer<Extra>>, options?: CompileOptions<Extra>): V[];
+export declare function search<T, Extra extends object = {}>(source: Items<T>, request: Request<T, NoInfer<Extra>> & {
+    readonly fields: readonly FieldName<T, NoInfer<Extra>>[];
+}, options?: CompileOptions<Extra>): Record<string, unknown>[];
+export declare function search<T, Extra extends object = {}>(source: Items<T>, request: Request<T, NoInfer<Extra>> & {
+    readonly omit: readonly FieldName<T, NoInfer<Extra>>[];
+}, options?: CompileOptions<Extra>): Partial<T>[];
+export declare function search<T, Extra extends object = {}>(source: Items<T>, request?: Request<T, NoInfer<Extra>>, options?: CompileOptions<Extra>): T[];
+/**
+ * Everything about a request that does not depend on where the items come from.
+ *
+ * Pulled out so the asynchronous helpers run the same paging, the same heap and the same
+ * projection as the synchronous ones. Two copies of "the best twenty, skipping forty"
+ * would be two chances to page differently.
+ */
+export declare function planRequest<T>(request: Request<T, object>, options: CompileOptions<object>): {
+    collect: () => Collector<T>;
+    test: ((item: T) => boolean) | undefined;
+    shape: (items: T[]) => unknown[];
+};
+/** Gathers the page as items arrive. `offer` returns true once nothing further can change the answer. */
+export interface Collector<T> {
+    offer(item: T, index: number): boolean;
+    finish(): T[];
+}
+export {};

package/dist/cjs/targets/mongo.d.ts

@@ -0,0 +1,55 @@
+import type { Capabilities } from "../plan.js";
+import type { Vocabulary } from "../vocabulary.js";
+/**
+ * JQL as a MongoDB filter.
+ *
+ * The first target, because it is the one where the two languages nearly agree: most of
+ * JQL's operators *are* MongoDB's, with the same array semantics, so the translation is
+ * mostly a copy and the interesting part is the handful that differ.
+ *
+ * The translation is checked by *running* it, not by comparing its shape: `tests/helpers/mongo.ts`
+ * is a second reading of MongoDB's matching rules, taken from its documented behaviour rather
+ * than from this engine, and the split test runs both halves of every generated query through
+ * it and through the engine and compares the answers.
+ *
+ * That check found the one difference no capability can express: **an array held directly
+ * inside another array**. A path segment in MongoDB applies to an array's elements but not to
+ * the elements of *those* arrays; JQL sees an array through at every level. Which rows come
+ * back then differs, in either direction, and nothing in the query says so — the shape is in
+ * the data. It is written down in specification §3 and in the pushdown guide, because a
+ * caller with such a collection must not read `complete` as permission to skip the second
+ * pass.
+ *
+ * What it will not do is guess. Every operator MongoDB cannot answer exactly —
+ * `$word`, `$length`, a `{ "$field": … }` reference, `$text` — is left out of
+ * `MONGO_CAPABILITIES`, so `plan()` keeps those clauses here and this function never sees
+ * them. A translation that was *nearly* right would be the worst of both: fewer rows than
+ * the query asked for, from a store that looked like it had answered.
+ */
+/**
+ * What a MongoDB `find` filter can answer, in JQL's own names.
+ *
+ * Give it to `plan()` and it splits a query into the filter to send and the predicate to
+ * apply to what comes back.
+ */
+export declare const MONGO_CAPABILITIES: Capabilities;
+export interface MongoOptions {
+    /**
+     * Resolves a vocabulary's names and aliases to the paths the collection stores.
+     *
+     * Only needed for a query that did not come from `plan()`: what `plan` pushes already
+     * carries the stored names.
+     */
+    readonly vocabulary?: Vocabulary<never, object> | undefined;
+    /** Where "now" comes from, for a relative date. Default the system clock, read once. */
+    readonly now?: (() => number) | undefined;
+}
+/** A MongoDB filter document. Values may be `Date` and `RegExp` objects, which a driver expects. */
+export type MongoFilter = Record<string, unknown>;
+/**
+ * Translates a JQL query into a MongoDB filter.
+ *
+ * Give it only what `plan(query, MONGO_CAPABILITIES)` pushed. Anything else is refused by
+ * name rather than approximated.
+ */
+export declare function toMongoFilter(query: unknown, options?: MongoOptions): MongoFilter;

package/dist/cjs/text/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@osqd/jql/text` — the search-box syntax, compiled into JQL.
+ *
+ * A separate entry because a service that only ever receives JSON queries has no reason
+ * to load a tokenizer.
+ */
+export { parseText, MAX_TEXT_CHARS, MAX_TEXT_DEPTH, TEXT_OPERATORS } from "./parse.js";
+export { suggest } from "./suggest.js";
+export { toText } from "./write.js";
+export type { TextOptions } from "./parse.js";
+export type { Suggestions } from "./suggest.js";
+export type { TextForm, Unexpressed } from "./write.js";

package/dist/cjs/text/parse.d.ts

@@ -0,0 +1,91 @@
+import type { UntypedQuery } from "../types.js";
+import { type Vocabulary } from "../vocabulary.js";
+/**
+ * The search-box syntax, compiled into a JQL document.
+ *
+ * Ported from BotHandler's feed filter, where it was its own language with its own
+ * matcher. Here it has no matcher at all: it produces the JSON query that means the same
+ * thing, and the engine runs that. So a filter typed into a box and the JSON a service
+ * receives cannot drift apart — there is only one set of semantics, and the text is a way
+ * of writing it.
+ *
+ * ```text
+ * actor:203.0.113.4 -path:/health          that address, except its health checks
+ * verdict:human $or verdict:unknown        either verdict
+ * $not path:/health                        the same as -path:/health, spelled out
+ * action:$in(block, drop)                  one of a set
+ * action:$notin(allow, tag)                none of a set
+ * score:>70   score:>=70   score:10..20    numeric comparisons and a range
+ * at:>2026-09-01                           a date comparison
+ * at:>-1h                                  the last hour, and it stays the last hour
+ * has:rule    -has:rule                    the field is set, or is not
+ * (verdict:human $or score:<20) $and $not path:/health
+ * "GET /api/v2/orders"                     a phrase, spaces and all
+ * ```
+ *
+ * **Adjacent terms mean AND**, which is what narrowing means. `$or` binds more loosely than
+ * `$and`, and `$not` more tightly than either — the conventional precedence. Operators
+ * carry a `$` because a bare `or` is a word that appears in User-Agents and paths, and a
+ * language where an ordinary search word silently becomes an operator is a language that
+ * lies about what it matched.
+ *
+ * **Nothing here throws for anything anybody types.** It backs live search boxes, so
+ * half-typed input is the normal state rather than an error: an unclosed bracket, a dangling
+ * `$or`, a `$in(` with nothing after it all parse to the best reading available. A
+ * *vocabulary* that is not one is the exception — that is a mistake in the calling code
+ * rather than in the box, and it is refused by name instead of failing later, deeper, as a
+ * `TypeError` nobody can place. That is the opposite of the JSON
+ * engine's rule, and on purpose: JSON is written by a program that can be told it is wrong,
+ * a search box by a person who has not finished typing.
+ */
+export interface TextOptions {
+    /** The field names the text may use, and how each one reads a value. */
+    readonly vocabulary?: Vocabulary<never, object> | undefined;
+    /**
+     * What a name before a colon may be.
+     *
+     * - `"vocabulary"` — only a vocabulary field; anything else is searched for as text,
+     *   because a path or a User-Agent can contain a colon. The default when a vocabulary is given.
+     * - `"any"` — any name that looks like a path (`address.city:London`), read as text.
+     *   The default without a vocabulary, since there is nothing else to go on. A URL then
+     *   has to be quoted: `"http://example.com"`.
+     */
+    readonly fields?: "vocabulary" | "any" | undefined;
+}
+/**
+ * The longest input this will read.
+ *
+ * Parsing is linear, so length is not a cliff the way nesting is, but this runs on every
+ * keystroke and on whatever arrives in a URL. Eight kilobytes is past any query a person
+ * writes. Longer input is cut, not refused, because refusing would be the one way this
+ * function could fail.
+ */
+export declare const MAX_TEXT_CHARS = 8192;
+/**
+ * How deep brackets may nest.
+ *
+ * Past anything anyone types, and deliberately no deeper than the tightest limit the engine
+ * is asked to compile under (`UNTRUSTED_LIMITS` allows sixteen levels): a box that produced
+ * a query the engine would refuse would be a box that lies about what it accepts.
+ */
+export declare const MAX_TEXT_DEPTH = 16;
+/** The name that asks whether a field is set, rather than naming one. */
+export declare const EXISTS_TERM = "has";
+/** The operator words the text syntax understands. */
+export declare const TEXT_OPERATORS: readonly string[];
+/**
+ * Parses search-box text into a JQL query. Never throws; an empty input is `{}`, which
+ * matches everything. The result is an `UntypedQuery`, so it can be handed to a typed
+ * collection: what the text names is only known once somebody has typed it.
+ */
+export declare function parseText(input: string, options?: TextOptions): UntypedQuery;
+export declare const SET_TERM: RegExp;
+/**
+ * A comparison written out in full, on a field nothing is known about.
+ *
+ * Without a vocabulary every field reads as text, and `score:>70` would search for the
+ * characters ">70" — which nobody typing it means. An operator or a range with a number
+ * on it is unambiguous, so it compares. A bare `70` stays text, because on an unknown
+ * field it is as likely to be part of an identifier as a quantity.
+ */
+export declare const EXPLICIT_COMPARISON: RegExp;

package/dist/cjs/text/suggest.d.ts

@@ -0,0 +1,16 @@
+import { type Vocabulary } from "../vocabulary.js";
+/**
+ * What to offer for the token the caret is in.
+ *
+ * Returns the completions and the span they replace, so a caller can put one in without
+ * disturbing the rest of the input. A token that already names a field with a closed set
+ * of values completes the value; anything else completes the field name. Every name
+ * offered comes from the vocabulary the parser reads, so nothing offered is something the
+ * language would not accept.
+ */
+export interface Suggestions {
+    readonly options: readonly string[];
+    readonly from: number;
+    readonly to: number;
+}
+export declare function suggest(input: string, caret: number, vocabulary?: Vocabulary<never, object>): Suggestions;

package/dist/cjs/text/write.d.ts

@@ -0,0 +1,34 @@
+import { type TextOptions } from "./parse.js";
+/**
+ * A query, written back as something somebody can type.
+ *
+ * A dashboard that stores filters as JSON still has to put one in a search box when
+ * somebody opens it to edit. That is this, and it is deliberately **not** total: the text
+ * syntax has no spelling for `$elemMatch`, `$size`, `$glob` or a `{ "$field": … }`
+ * reference, and inventing one per operator would turn a box people can type into a
+ * language they have to learn.
+ *
+ * So the honest answer is two things: the text, and what was left out of it. **The text is
+ * exact for what it says** — parsed back with the same vocabulary it means precisely the
+ * clauses it carries, which the tests hold it to — but a caller that ignores `unexpressed`
+ * is showing somebody a filter wider than the one that is running. `complete` is there so
+ * that check is one line.
+ */
+export interface Unexpressed {
+    /** Where the clause is in the query: `$or[1].tags`. */
+    readonly at: string;
+    /** The clause itself, as it was written. */
+    readonly clause: unknown;
+    /** Why the text cannot say it. */
+    readonly why: string;
+}
+export interface TextForm {
+    /** The query as text. Parsing it back gives exactly the clauses it carries. */
+    readonly text: string;
+    /** True when the text says everything the query does. */
+    readonly complete: boolean;
+    /** The clauses with no spelling in the text syntax, in the order they were met. */
+    readonly unexpressed: readonly Unexpressed[];
+}
+/** Writes a query as search-box text, and says what it could not write. */
+export declare function toText(query: unknown, options?: TextOptions): TextForm;