@osqd/jql 0.1.1

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

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