@osqd/jql 0.1.1

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