@osqd/jql 0.1.1

package/dist/cjs/types.d.ts

@@ -0,0 +1,236 @@
+/**
+ * The shapes a query is made of.
+ *
+ * A JQL query is a JSON document, so everything here describes JSON: no functions, no
+ * `RegExp` objects, no `Date` instances. That is the whole point of the language — a
+ * query that finds something can be written into a URL, a saved filter, a config file or
+ * a request body, sent to somebody else, and find the same thing there. A query that
+ * carried a function could do none of that.
+ *
+ * The types come in two strengths. `Query<T>` for a known `T` only accepts field paths
+ * that exist on `T`, with values of the right type, so a typo in a field name is a compile
+ * error rather than a filter that quietly matches nothing. `Query<unknown>` (and
+ * `Query<any>`) accepts any field, for data whose shape is not known until it arrives;
+ * the engine still refuses anything that is not JQL when the query is compiled.
+ */
+/** A JSON value, as a query document may contain one. */
+export type JsonValue = string | number | boolean | null | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+/**
+ * An instant relative to now, so a saved filter goes on meaning "the last hour".
+ *
+ * The duration is a count and a unit — `"90s"`, `"1h30m"`, `"7d"` — from `ms`, `s`, `m`,
+ * `h`, `d` and `w`. Months and years are left out because neither has a fixed length.
+ */
+export type RelativeDate = {
+    readonly $ago: string;
+} | {
+    readonly $ahead: string;
+};
+/**
+ * A date, written the only way JSON can write one.
+ *
+ * An ISO 8601 string, epoch milliseconds, `"now"`, or a `RelativeDate`. When a query
+ * compares against one, the value in the document is read as a date too: a `Date`, an ISO
+ * string or epoch milliseconds. The literal is what says "this is a date", so no value is
+ * ever read as a date unless the query asked for that.
+ */
+export interface DateLiteral {
+    readonly $date: string | number | RelativeDate;
+}
+/**
+ * A comparison with another field of the same item, rather than with a value.
+ *
+ * `{ "bytesOut": { "$gt": { "$field": "bytesIn" } } }`. It is still data — a path, not an
+ * expression — so a query holding one stores, travels and validates like any other.
+ */
+export interface FieldReference {
+    readonly $field: string;
+}
+/** The names `$type` accepts. `integer` is a `number` with no fractional part. */
+export type TypeName = "string" | "number" | "integer" | "bigint" | "boolean" | "null" | "array" | "object" | "date";
+/**
+ * A free-text search across a whole document, or across named fields.
+ *
+ * The string form searches every string (and, when the phrase has a digit in it, every
+ * number) anywhere in the document, case-insensitively. The object form narrows the
+ * fields and can turn case sensitivity on.
+ */
+export type TextSearch = string | {
+    readonly $search: string;
+    /** The fields to search. Absent means the whole document, or the vocabulary's text fields when it names some. */
+    readonly $fields?: readonly string[] | undefined;
+    /** Default `false`: a search box that cared about case would find less than people expect. */
+    readonly $caseSensitive?: boolean | undefined;
+};
+type Leaf = string | number | boolean | bigint | symbol | null | undefined | Date | RegExp | ((...args: never[]) => unknown);
+/** How deep path completion goes. Past this a path is still valid at run time; the types simply stop enumerating it. */
+type Depth = [never, 0, 1, 2, 3, 4, 5];
+/** The element type of an array, or the type itself. */
+export type ElementOf<T> = T extends readonly (infer E)[] ? E : T;
+/**
+ * Every dot path into `T`, seeing through arrays the way the engine does.
+ *
+ * `{ items: { id: number }[] }` yields `"items"`, `"items.id"` (any element's id),
+ * `"items.0"` and `"items.0.id"` (one element by position).
+ */
+export type Path<T, D extends number = 5> = [D] extends [never] ? never : T extends Leaf ? never : T extends readonly (infer E)[] ? `${number}` | ArrayPaths<E, D> | Path<E, D> : T extends ReadonlyMap<string, infer V> ? string | `${string}.${Path<V, Depth[D]>}` : {
+    [K in keyof T & string]: K | SubPath<K, NonNullable<T[K]>, D>;
+}[keyof T & string];
+type ArrayPaths<E, D extends number> = Path<E, Depth[D]> extends infer P extends string ? `${number}.${P}` : never;
+type SubPath<K extends string, V, D extends number> = Path<V, Depth[D]> extends infer P extends string ? `${K}.${P}` : never;
+/** The type found at a path, with arrays seen through. `unknown` when the path does not resolve. */
+export type PathValue<T, P extends string> = T extends readonly (infer E)[] ? P extends `${number}` ? E : P extends `${number}.${infer R}` ? PathValue<NonNullable<E>, R> : PathValue<NonNullable<E>, P> : T extends ReadonlyMap<string, infer V> ? P extends `${string}.${infer R}` ? PathValue<NonNullable<V>, R> : V : P extends keyof T ? T[P] : P extends `${infer K}.${infer R}` ? K extends keyof T ? PathValue<NonNullable<T[K]>, R> : unknown : unknown;
+type Scalar<V> = ElementOf<NonNullable<V>>;
+/** What a field may be compared to for equality. `null` also matches a missing field. */
+export type Literal<V> = unknown extends V ? JsonValue | DateLiteral : LiteralOf<NonNullable<V>> | null;
+type LiteralOf<V> = V extends Date ? DateLiteral : V extends readonly (infer E)[] ? readonly LiteralOf<E>[] | LiteralOf<E> : V extends string | number | boolean ? V : V extends bigint ? number : V extends object ? {
+    readonly [K in keyof V]: LiteralOf<V[K]>;
+} : V;
+/**
+ * What an ordering operator accepts for a value of type `V`. A `$date` is accepted for
+ * strings (ISO timestamps) and numbers (epoch milliseconds) as well as for `Date`s, because
+ * that is how dates are stored when they have been through JSON.
+ */
+type Bound<V> = unknown extends V ? number | string | DateLiteral : [Extract<Scalar<V>, number | bigint>] extends [never] ? [Extract<Scalar<V>, string>] extends [never] ? [Extract<Scalar<V>, Date>] extends [never] ? never : DateLiteral : string | DateLiteral : number | DateLiteral;
+/** Available only when the field can hold a string. */
+type StringOperand<V> = unknown extends V ? string | readonly string[] : [Extract<Scalar<V>, string>] extends [never] ? never : string | readonly string[];
+/** Available only when the field can hold an array. */
+type ArrayOnly<V, X> = unknown extends V ? X : [Extract<NonNullable<V>, readonly unknown[]>] extends [never] ? never : X;
+/** Available when the field can hold something with a length: an array or a string. */
+type HasLength<V, X> = unknown extends V ? X : [Extract<NonNullable<V>, readonly unknown[]>] extends [never] ? [Extract<Scalar<V>, string>] extends [never] ? never : X : X;
+/**
+ * An operator expression on one field.
+ *
+ * Several operators in one object must all hold. On an array field each operator is
+ * tested against the array and against each element separately, so `{ $gt: 5, $lt: 10 }`
+ * holds for `[1, 20]`. `$elemMatch` is for "one element satisfies all of these".
+ */
+export interface Condition<V = unknown> {
+    readonly $eq?: Literal<V> | FieldReference | undefined;
+    /** Also matches a document without the field. */
+    readonly $ne?: Literal<V> | FieldReference | undefined;
+    readonly $gt?: Bound<V> | FieldReference | undefined;
+    readonly $gte?: Bound<V> | FieldReference | undefined;
+    readonly $lt?: Bound<V> | FieldReference | undefined;
+    readonly $lte?: Bound<V> | FieldReference | undefined;
+    /** An empty list matches nothing. */
+    readonly $in?: readonly Literal<V>[] | undefined;
+    /** Also matches a document without the field. An empty list matches everything. */
+    readonly $nin?: readonly Literal<V>[] | undefined;
+    readonly $exists?: boolean | undefined;
+    readonly $type?: TypeName | readonly TypeName[] | undefined;
+    /** Any of the given substrings. */
+    readonly $contains?: StringOperand<V> | undefined;
+    readonly $startsWith?: StringOperand<V> | undefined;
+    readonly $endsWith?: StringOperand<V> | undefined;
+    /** A whole component: the value starts and ends on a boundary between runs of letters and digits. */
+    readonly $word?: StringOperand<V> | undefined;
+    /** A glob: `*` for any run, `?` for one character, `\\` to escape either. */
+    readonly $glob?: StringOperand<V> | undefined;
+    /** An ECMAScript pattern, as a string. */
+    readonly $regex?: ([Extract<Scalar<V>, string>] extends [never] ? (unknown extends V ? string : never) : string) | undefined;
+    /** `i` makes every string comparison in this object case-insensitive; `m`, `s`, `u` apply to `$regex`. */
+    readonly $options?: string | undefined;
+    /** `[divisor, remainder]`. Offered on a big integer too, which is a number everywhere else in the language. */
+    readonly $mod?: ([Extract<Scalar<V>, number | bigint>] extends [never] ? (unknown extends V ? readonly [number, number] : never) : readonly [number, number]) | undefined;
+    readonly $size?: ArrayOnly<V, number | Condition<number>> | undefined;
+    /** The length of the value itself: elements of an array, UTF-16 code units of a string. */
+    readonly $length?: HasLength<V, number | Condition<number>> | undefined;
+    readonly $all?: ArrayOnly<V, readonly Literal<Scalar<V>>[]> | undefined;
+    readonly $elemMatch?: ArrayOnly<V, Query<Scalar<V>>> | undefined;
+    readonly $not?: Condition<V> | undefined;
+}
+/** A literal to compare with, another field to compare with, or an operator expression. */
+export type FieldQuery<V> = Literal<V> | FieldReference | Condition<V>;
+/** The operators that combine whole queries. Valid at the top of any query. */
+export interface LogicalOperators<Q> {
+    /** Every one. An empty list matches everything. */
+    readonly $and?: readonly Q[] | undefined;
+    /** At least one. An empty list matches nothing. */
+    readonly $or?: readonly Q[] | undefined;
+    /** None of them. An empty list matches everything. */
+    readonly $nor?: readonly Q[] | undefined;
+    readonly $not?: Q | undefined;
+    readonly $text?: TextSearch | undefined;
+    /** Carried along and ignored, so a stored query can say why it exists. */
+    readonly $comment?: string | undefined;
+}
+/**
+ * A query over values of type `T`.
+ *
+ * For an object type, the keys are field paths. For a primitive element type — an array
+ * of numbers, say — the query is a condition on the element itself: `{ $gt: 3 }`.
+ * `Extra` adds the fields a vocabulary computes, which are not on `T` itself.
+ */
+export type Query<T = unknown, Extra extends object = {}> = unknown extends T ? LooseQuery : NonNullable<T> extends Leaf ? Condition<T> & LogicalOperators<Query<T, Extra>> : TypedQuery<NonNullable<T>, Extra>;
+type TypedQuery<T, Extra extends object> = {
+    readonly [P in Path<T>]?: FieldQuery<PathValue<T, P>> | undefined;
+} & {
+    readonly [K in keyof Extra & string]?: FieldQuery<Extra[K]> | undefined;
+} & LogicalOperators<Query<T, Extra>>;
+/** A query whose field names are not known in advance. The engine validates it when it compiles. */
+export type LooseQuery = LogicalOperators<LooseQuery> & {
+    readonly [path: string]: unknown;
+};
+declare const untypedBrand: unique symbol;
+/**
+ * A query that came from outside the type system: typed into a search box, read from a
+ * URL, received in a request body.
+ *
+ * Accepted wherever a typed query is, so `rows.jqlFilter(parseText(input))` compiles. It is
+ * branded rather than being a plain `LooseQuery` because a plain one would also accept
+ * every object literal — including `{ nme: "Ada" }` — and the typed queries would stop
+ * catching typos. For the same reason it has no index signature: one in any member of a
+ * union switches off the excess-property check for the whole union, and
+ * `users.jqlSearch({ missing: 1 })` compiled until a type test caught it. Cast to
+ * `LooseQuery` to read its fields. The brand exists only in the types; the engine
+ * validates the query itself when it compiles it, which is the check that matters for
+ * input from outside.
+ */
+export type UntypedQuery = LogicalOperators<LooseQuery> & {
+    readonly [untypedBrand]: true;
+};
+/** A compiled query: a plain predicate. Any function of this shape is accepted wherever a query is. */
+export type Matcher<T> = (value: T) => boolean;
+/** A query document, one that came from outside the types, or one already compiled. */
+export type QueryLike<T, Extra extends object = {}> = Query<T, Extra> | UntypedQuery | Matcher<T>;
+/** `1` or `"asc"` for ascending, `-1` or `"desc"` for descending. */
+export type SortDirection = 1 | -1 | "asc" | "desc";
+/** Keys in order of precedence: the first key sorts, the second breaks its ties, and so on. */
+export type Sort<T, Extra extends object = {}> = unknown extends T ? {
+    readonly [path: string]: SortDirection;
+} : {
+    readonly [P in Path<NonNullable<T>> | (keyof Extra & string)]?: SortDirection;
+};
+/** A field a request may name: a path into `T`, or a vocabulary field. */
+export type FieldName<T, Extra extends object = {}> = unknown extends T ? string : Path<NonNullable<T>> | (keyof Extra & string);
+/**
+ * A whole question about a collection, as one JSON document.
+ *
+ * The envelope a service accepts and a dashboard puts in its URL: which items, in which
+ * order, which page, and which fields of each.
+ */
+export interface Request<T = unknown, Extra extends object = {}> {
+    /** A query, one already compiled, or any predicate — the same as every other place a query is taken. */
+    readonly where?: QueryLike<T, Extra> | undefined;
+    readonly sort?: Sort<T, Extra> | undefined;
+    /** How many matches to pass over first. Default 0. */
+    readonly skip?: number | undefined;
+    /** The most to return. Absent means all of them. */
+    readonly limit?: number | undefined;
+    /** Paths to keep in each result. Absent returns the items themselves. */
+    readonly fields?: readonly FieldName<T, Extra>[] | undefined;
+    /**
+     * Paths to drop from each result, applied after `fields`.
+     *
+     * What a server redacts with: the values never leave the process, and the request that
+     * says so is data like the rest of it. The items themselves are not touched — a result
+     * with something dropped is a copy.
+     */
+    readonly omit?: readonly FieldName<T, Extra>[] | undefined;
+}
+/** Anything the collection helpers can read: arrays, array-likes, iterables, and maps (by value). */
+export type Source<T> = Iterable<T> | ArrayLike<T>;
+export {};

package/dist/cjs/vocabulary.d.ts

@@ -0,0 +1,106 @@
+import type { PathValue } from "./types.js";
+/**
+ * The names a query may use for one kind of document.
+ *
+ * Without one, a field name is a path and nothing more. With one, a collection gets the
+ * names people actually type — `ip` for `actor`, `ua` for `request.headers.user-agent` —
+ * and fields that are computed rather than stored, like BotHandler's `outcome`, which is
+ * derived from the action and never kept anywhere.
+ *
+ * The same vocabulary serves the JSON engine and the text front end. That is deliberate:
+ * two places that each kept their own list of field names would be two dialects within a
+ * week, and a filter typed into a search box has to mean exactly what the JSON it becomes
+ * means.
+ */
+/**
+ * How the text front end reads a value typed after `field:`. The JSON engine ignores it:
+ * a JSON query says what it means with its operator.
+ *
+ * - `text` — contains the value, ignoring case. The default, and right for prose.
+ * - `word` — contains it as a whole component (`1.2.3.4` does not find `1.2.3.45`). For identifiers.
+ * - `exact` — equals it, ignoring case. For closed sets like a verdict or a method.
+ * - `number` — compares: `>70`, `<=5`, `10..20`, `42`.
+ * - `date` — compares instants the same way: `>2026-01-01`.
+ * - `boolean` — `true`/`false`, `yes`/`no`, `1`/`0`.
+ */
+export type FieldKind = "text" | "word" | "exact" | "number" | "date" | "boolean";
+export interface FieldDefinition<T = unknown> {
+    /** Where the value lives. Default: the field's own name. */
+    readonly path?: string | undefined;
+    /** Computes the value instead. Called once per document the field is tested against; it must not throw. */
+    readonly get?: ((document: T) => unknown) | undefined;
+    /** Other names that mean this field. */
+    readonly aliases?: readonly string[] | undefined;
+    /** Default `"text"`. */
+    readonly kind?: FieldKind | undefined;
+    /** The values worth offering as completions, when the set is closed. Leave out for a field that takes anything. */
+    readonly values?: readonly string[] | undefined;
+}
+export interface VocabularyDefinition<T = unknown> {
+    readonly fields: Readonly<Record<string, FieldDefinition<T>>>;
+    /** The fields a bare search word looks in. Default: the whole document. */
+    readonly text?: readonly string[] | undefined;
+    /**
+     * Whether a name outside the vocabulary is refused. Default `false`, so any path still
+     * works alongside the named fields. Turn it on where the vocabulary is the whole
+     * contract — a public API whose documents may grow fields nobody promised to keep.
+     */
+    readonly strict?: boolean | undefined;
+}
+/** One field, with every name that reaches it already resolved. */
+export interface VocabularyField<T = unknown> {
+    readonly name: string;
+    readonly kind: FieldKind;
+    readonly path: string;
+    readonly get: ((document: T) => unknown) | undefined;
+    readonly aliases: readonly string[];
+    readonly values: readonly string[] | undefined;
+}
+/**
+ * A vocabulary ready to use.
+ *
+ * `Extra` is the type of the fields it names, so a typed query can use them: build one
+ * with `defineVocabulary<Doc>()({ … })` and the computed names type-check.
+ */
+export interface Vocabulary<T = unknown, Extra extends object = {}> {
+    /** Every name, aliases included, lower-cased, to the field it means. */
+    readonly lookup: ReadonlyMap<string, VocabularyField<T>>;
+    /** The canonical fields, in the order they were defined. */
+    readonly fields: readonly VocabularyField<T>[];
+    /** Every name a query may use, aliases included, sorted. For completions. */
+    readonly names: readonly string[];
+    readonly text: readonly string[] | undefined;
+    readonly strict: boolean;
+    /** Carries the computed field types. Never present at run time. */
+    readonly __extra?: Extra | undefined;
+}
+type ExtraOf<T, F> = {
+    [K in keyof F]: F[K] extends {
+        get: (document: T) => infer R;
+    } ? R : F[K] extends {
+        path: infer P extends string;
+    } ? PathValue<T, P> : K extends string ? PathValue<T, K> : unknown;
+};
+/**
+ * Builds a vocabulary, refusing one that would quietly misbehave.
+ *
+ * Two names that collide, a text field that is not a field, a field with both a path and a
+ * getter: each is a vocabulary that looks defined and means something other than what it
+ * says, so each is an error here rather than a surprise at query time.
+ *
+ * Curried so the document type can be given while the field names are inferred:
+ * `defineVocabulary<Request>()({ fields: { … } })`.
+ */
+export declare function defineVocabulary<T = unknown>(): <const D extends VocabularyDefinition<T>>(definition: D) => Vocabulary<T, ExtraOf<T, D["fields"]>>;
+/**
+ * Refuses anything that is not a vocabulary, where one was expected.
+ *
+ * Two mistakes land here, and both used to arrive as `Cannot read properties of undefined
+ * (reading 'get')` from somewhere inside the engine. `defineVocabulary` is curried, so
+ * `defineVocabulary({ fields: … })` — the empty parentheses forgotten — returns a *function*;
+ * and a definition passed straight through is an object with no `lookup` on it. Neither is
+ * caught by the types from JavaScript, and a `TypeError` is not a `JqlError`, so `validate`
+ * re-threw it: the one call whose job is to answer 400 rather than 500 answered 500.
+ */
+export declare function checkVocabulary<T>(value: T, at?: string): T;
+export {};

package/dist/cli.d.ts

@@ -0,0 +1,15 @@
+export interface Streams {
+    readonly out: (text: string) => void;
+    readonly err: (text: string) => void;
+    /** Where a `-` argument, or no file at all, reads from. */
+    readonly stdin: () => AsyncIterable<string>;
+}
+/** Runs the command. Returns the exit code rather than calling `process.exit`, so it can be tested in-process. */
+export declare function main(argv: readonly string[], io: Streams): Promise<number>;
+/**
+ * The command as a process: reads stdin, writes the streams, sets the exit code.
+ *
+ * Kept apart from `main` so the tests can call `main` with writers of their own and assert
+ * which stream each line went to — part of the contract, not an implementation detail.
+ */
+export declare function run(argv?: readonly string[]): Promise<void>;