@osqd/jql 0.1.1

package/docs/design/decisions.md

@@ -0,0 +1,198 @@
+# Decisions
+
+The trades that shaped JQL, each with what it cost.
+
+← [Documentation](../index.md)
+
+---
+
+Each entry is **the decision / why / the cost**, so a future change can weigh what it is undoing.
+
+## The language is JSON, not text
+
+**The decision.** A query is a JSON document. The search-box syntax exists, but it compiles into
+the JSON and has no semantics of its own.
+
+**Why.** A query that is data can be stored, put in a URL, sent to another service, diffed,
+generated by a program and validated by a schema. BotHandler's text filter could do the first
+two and none of the rest, and every project that wanted filtering would have grown its own
+text dialect. With one JSON form, the text is one way of writing it, and a filter typed into a
+dashboard means exactly what the JSON a service receives means.
+
+**The cost.** JSON is verbose to write by hand, which is why the text syntax is kept. And the
+two forms can express different things: the text syntax cannot write `$elemMatch` or `$size`.
+
+## The conventional operator names, not new ones
+
+**The decision.** `$eq`, `$gt`, `$in`, `$exists`, `$elemMatch` and the rest keep the names and
+the array behaviour that document-database query languages have used for years, rather than a
+vocabulary of our own. Where this language departs from that convention it does so on purpose:
+object equality ignores key order, ordering never coerces across types, `$options: "i"` reaches
+every string comparison in its condition, and there are string operators that need no pattern
+at all.
+
+**Why.** A reader who has met one query document can read this one without the documentation
+open, and the names carry their meaning with them. The departures are each a place where the
+convention rests on something JSON does not carry — key order, a database's own type ordering —
+or where the only tool it offers is a pattern, which is the one thing unsafe to accept from a
+stranger.
+
+**The cost.** Familiar names invite the assumption that every behaviour is familiar too, and
+the places where it is not are exactly the subtle ones. That is why each is stated positively
+in the specification where the operator is defined, rather than left as a difference the reader
+has to know to look for.
+
+## The engine refuses; the text parser never does
+
+**The decision.** `compile` throws on anything it does not understand — an unknown operator, an
+`undefined` value, a `RegExp` object, a flag it does not know. `parseText` never throws.
+
+**Why.** A query that looks restrictive and is not is the failure this family of projects
+exists to prevent: a misspelt `$gtt` that is ignored makes a filter that lets everything
+through, and nothing about the result says so. JSON is written by a program that can be told
+it is wrong. A search box is written by a person halfway through typing, for whom an exception
+on every keystroke would be useless.
+
+**The cost.** A service accepting JSON queries has to handle refusals — which it should, and
+`validate` makes that one line.
+
+## `undefined` is an error, not "no condition"
+
+**The decision.** `{ id: user.id }` where `user.id` is `undefined` is refused.
+
+**Why.** Dropping the key — what most JavaScript query libraries do, because `JSON.stringify`
+would — turns a condition on nothing into a query that matches everything. It is the single
+most common way a filter silently stops filtering.
+
+**The cost.** Code that builds queries from optional values has to leave the key out
+deliberately.
+
+## Compiled to closures, not to generated code
+
+**The decision.** A query compiles to a tree of small closures. There is no `new Function`.
+
+**Why.** Generated code would be faster still. It would also be refused by any page with a
+Content-Security-Policy worth having — including this project's own dashboards, whose build
+fails on a `new Function` — and it would put a code generator on the path of every query that
+arrives from outside.
+
+**The cost.** Closures shared by every query make some call sites megamorphic, so a nested path
+costs about 1.2× a hand-written loop rather than 1×. [Performance](performance.md) has the
+numbers.
+
+## No implicit cache
+
+**The decision.** The helpers compile the query they are given on every call. There is no cache
+keyed on the query object.
+
+**Why.** A cache keyed on identity serves a stale predicate the moment somebody edits a query
+object they have already used — a filter that looks updated and is not. A cache keyed on the
+serialised query costs a `JSON.stringify` per call, which is most of what compiling costs.
+Compiling a small query takes well under a microsecond.
+
+**The cost.** Calling a helper with a fresh query literal in a tight loop over tiny arrays pays
+for compiling each time. `compile` once is the answer, and the performance page says so.
+
+## The array methods are opt-in
+
+**The decision.** `Array.prototype.jqlSearch` and the rest exist only after
+`import "@osqd/jql/global"`, and their types come from the same import.
+
+**Why.** Patching a built-in is the application's decision, never a library's. A package that
+depends on JQL must not change every array in the program that imports it. And if the types
+arrived without the methods, the compiler would promise something that fails at run time.
+
+**The cost.** One extra import line in each application that wants them.
+
+## A `Map` is read by value
+
+**The decision.** Every helper treats a `Map` as a collection of its values. `filterMap` and
+`findEntry` keep the keys.
+
+**Why.** "The user whose name is Ada" is a question about the users, not about the keys they are
+filed under. Treating a `Map` as the `[key, value]` pairs its iterator yields would make every
+query on one start with `"1."`.
+
+**The cost.** `find(map, …)` does not say which key it found; `findEntry` does.
+
+## Case-insensitive means lower-casing, not regex folding
+
+**The decision.** "Ignoring case" is defined as comparing after Unicode default lower-case
+mapping, with no locale.
+
+**Why.** It is the definition every language has a function for, so another implementation can
+match it exactly. A regex `i` flag folds case differently between engines and between modes of
+one engine.
+
+**The cost.** Lower-casing allocates a string for mixed-case input. A regex would not.
+
+## A reference, not an expression language
+
+**The decision.** Comparing one field with another is `{ "$field": "path" }` — a reference and
+nothing else. There is no arithmetic, no function, no `$expr`.
+
+**Why.** "Bytes out greater than bytes in" is the question people actually have, and it needs
+a path rather than a language. An expression language would be the end of queries being data
+you can reason about: it would need its own grammar, its own evaluation rules, its own limits
+for untrusted callers, and every one of those is a place for a query to do something its
+reader did not expect.
+
+**The cost.** Questions that genuinely need arithmetic — "more than twice as many" — cannot be
+asked. A computed field in a vocabulary answers them at the cost of being defined in code
+rather than in the query.
+
+## Relative dates resolve when the query compiles
+
+**The decision.** `{ "$date": { "$ago": "1h" } }` is resolved once, against a clock the caller
+may supply, not per comparison.
+
+**Why.** A window that moved during a scan would judge two items a second apart against
+different hours, and no result could be explained afterwards. Supplying the clock is also what
+makes a relative filter testable without waiting an hour.
+
+**The cost.** A compiled query keeps the instant it was compiled at, so a long-lived matcher
+goes stale; moving the window means compiling again, which costs well under a microsecond. A
+streaming rule that must always mean "the last five minutes" has to compile per batch, and the
+documentation says so.
+
+## Grouping is a function, not a request key
+
+**The decision.** `group()` counts the matches by a field. The request envelope —
+`where`, `sort`, `skip`, `limit`, `fields`, `omit` — does not gain a `group` key.
+
+**Why.** Every other request returns items; a grouped one returns rows of a different shape,
+and putting it in the envelope would mean every caller of `search` has to know which shape
+came back. The counting itself was being rewritten in each dashboard, so that is what moved.
+
+**The cost.** A dashboard asking for both a page and its groups makes two calls over the same
+data. Both take a compiled predicate, so the query is written and compiled once.
+
+## Added operators carry a prefix
+
+**The decision.** A project may add operators, and their names must begin `$x` and a capital.
+No standard name will ever start that way.
+
+**Why.** A stored filter outlives the process that wrote it. `{ "$cidr": … }` in a saved
+filter looks like JQL and is not, and the reader who finds out is the one whose engine refused
+it. `$xCidr` says what it is on sight, and leaves the language free to add `$cidr` one day
+without colliding.
+
+**The cost.** The names are uglier, and a project that adds many of them is writing a dialect —
+which the prefix at least makes obvious.
+
+## Canonical, not equivalent
+
+**The decision.** `canonical` rewrites a query into one shape per *spelling*; it does not
+decide whether two queries are equivalent.
+
+**Why.** Equivalence has no cheap answer — `{ "$gt": 3 }` and `{ "$gte": 4 }` agree on every
+integer and differ at 3.5 — and an answer that is right most of the time is worse than none
+for deduplicating the things people save.
+
+**The cost.** Two saved filters that ask the same question in genuinely different ways are
+still two filters. The documentation says exactly what equal and unequal fingerprints mean.
+
+## Related
+
+- [Performance](performance.md) — what the engine's own choices cost, measured
+- [The specification](../reference/specification.md) — the language these decisions produced

package/docs/design/performance.md

@@ -0,0 +1,102 @@
+# Performance
+
+How fast JQL is, how that is measured, and what makes it so.
+
+← [Documentation](../index.md)
+
+---
+
+## The numbers
+
+Every figure is a **ratio** against the loop somebody would have written by hand for the same
+answer, measured in the same process seconds apart. A number of milliseconds is a statement
+about the machine that produced it; a ratio holds still across machines and moves only when the
+engine does. From `npm run bench`, 100 000 documents, median of seven calibrated rounds:
+
+| Case | JQL ÷ hand-written |
+| --- | --- |
+| `{ id: … }` — find by id, walking everything | 1.02–1.11× |
+| `{ age: { $gte, $lt }, active: true }` | 1.30–1.47× |
+| `{ "address.city": … }` | 1.07–1.21× |
+| `{ id: { $in: [100 ids] } }` against a hand-built `Set` | 0.96–1.03× |
+| `{ tags: "billing" }` — a value in an array | 1.14–1.26× |
+| `{ name: { $contains, $options: "i" } }` | 1.12–1.18× |
+| `$or` of a nested path and a range | 1.07–1.27× |
+| `{ name: { $glob: "Person 1*" } }` against a hand-written `startsWith` | 0.78–0.91× |
+| `{ notes: { $length: { $gt: 20 } } }` | 1.79–2.36× |
+| `{ visits: { $gt: { $field: "purchases" } } }` | 2.15–2.86× |
+| `$text` over the whole document, against checking four known fields | 2.29–2.43× |
+| `search` top 10 by a field, against filter-sort-slice | 0.39–0.51× |
+
+`$text` is the one that stays above 2×, because it does more than the hand-written loop: it
+walks every value in the document rather than the four fields the loop already knows about.
+Give it `$fields`, or a vocabulary with `text` fields, and it reads only those.
+
+A `{ "$field": … }` comparison will not reach parity either: it reads two fields per item and
+compares values whose types neither side knew when the query compiled, where the hand-written
+`p.visits > p.purchases` is one machine comparison. It is still a filter over a million items
+in a few milliseconds.
+
+A glob is *faster* than the loop it replaces, because a pattern is taken apart once into the
+narrowest matcher that fits it — `startsWith` for `prefix*`, `includes` for `*middle*`, a run
+of `indexOf` calls for the rest — and only a pattern holding `?` walks character by
+character.
+
+For comparison, the same queries through the two most used query-document matchers for
+JavaScript, measured once on the same machine (sift 17.1.3, mingo 7.2.4), took 2× to 130× as
+long as JQL. The widest gap is `$in`, where JQL looks each item up in a set rather than
+comparing it with every value in the list. These are not in the benchmark suite, because the
+guard measures JQL against the code it replaces, not against other libraries.
+
+## What makes it fast
+
+- **Everything that depends only on the query happens once**, in `compile`: validation, field
+  resolution, path splitting, a `Set` for `$in`, lower-casing for `$options: "i"`, compiling
+  patterns. What runs per document is only the part that depends on the document.
+- **The headline case is written out.** `{ id: 2 }` compiles to one closure with the read, the
+  comparison and the array fallback inline — the loop you would have written.
+- **One read per field.** `{ age: { $gte: 30, $lt: 50 } }` reads `age` once and compares twice.
+- **Nested paths are read straight** — two property reads for `address.city` — and walked with
+  the fan-out machinery only when an array is actually in the way.
+- **Cheapest first.** The parts of an `$and` are reordered so equality runs before a pattern
+  and a pattern before a text walk; the first to fail decides the answer.
+- **Early exits everywhere.** `find`, `some`, `every` and an unsorted `search` stop as soon as
+  the answer is known, including on generators, which are not consumed past it.
+- **A bounded heap for top-k.** `search` with a sort and a limit keeps only the best
+  `skip + limit` items: O(n log k), and memory for k.
+- **Arrays are walked by index**, not through the iterator protocol, which allocates per step.
+
+## Compile once in a hot loop
+
+Every helper compiles the query it is given. Compiling a small query takes well under a
+microsecond, which is nothing against a large array and everything against a tiny one:
+
+```ts
+// Compiles a thousand times.
+for (const batch of batches) batch.jqlFilter({ status: "open" });
+
+// Compiles once.
+const open = compile<Order>({ status: "open" });
+for (const batch of batches) batch.filter(open);
+```
+
+There is deliberately no cache that would do this for you; [Decisions](decisions.md#no-implicit-cache)
+says why.
+
+## The guard
+
+`npm run bench:guard` fails when a case's ratio passes its budget. The budgets sit at about
+twice the top of each measured range: tight enough to catch a real regression, loose enough
+that noise never fires them, because a guard that fires on noise gets raised until it guards
+nothing. When one fails, either something got slower, or the budget is wrong for a change that
+was worth making — in which case raise it and say why in the commit.
+
+The differential test (`tests/differential.test.ts`) is the other half: every fast path above is
+a second implementation of something the specification already says, so thousands of random
+documents and queries are run through the engine and through a deliberately naive reference,
+and the two must agree.
+
+## Related
+
+- [Decisions](decisions.md) — the closures-not-codegen and no-cache trades
+- [Library API](../reference/api.md) — `compile`, `search`

package/docs/guides/adopting.md

@@ -0,0 +1,81 @@
+# Adopting JQL in a project
+
+How a project in this family moves its filtering onto JQL.
+
+← [Documentation](../index.md)
+
+---
+
+JQL exists so that every project here filters data the same way: one language for a
+dashboard's search box, a service's query parameter, a saved filter and an export. Moving a
+project onto it has three parts.
+
+## 1. Write the vocabulary
+
+The vocabulary is the one place that says what the project's data is called. BotHandler's feed
+filter, for instance, becomes:
+
+```ts
+const ENTRY_VOCABULARY = defineVocabulary<DashboardEntry>()({
+  fields: {
+    path: { aliases: ["url"] },
+    actor: { aliases: ["ip"], kind: "word", get: (entry) => withLabel(entry.actor) },
+    ua: { path: "userAgent", aliases: ["useragent", "agent"] },
+    verdict: { kind: "exact", values: ["confirmed-bot", "verified-bot", "suspected-bot", "human", "unknown"] },
+    class: { path: "botClass", aliases: ["botclass"] },
+    action: {},
+    outcome: { get: outcome, kind: "exact", values: ["allow", "mitigate", "deny", "pending"] },
+    rule: {},
+    detector: { get: (entry) => entry.evidence.map((item) => item.detector) },
+    identity: {},
+    method: { kind: "exact" },
+    certain: { kind: "boolean" },
+    bypass: {},
+    id: { path: "requestId", aliases: ["request"], kind: "word" },
+    score: { kind: "number" },
+  },
+  text: ["method", "path", "actor", "ua", "verdict", "class", "identity", "action", "rule", "id"],
+});
+```
+
+Computed fields (`outcome`, `detector`, an actor's name given after the fact) are `get`
+functions, looked up when the query runs — which is what lets a name given to an actor reach
+requests that arrived before it was given.
+
+## 2. Swap the matcher
+
+Where the project parsed text and matched it itself:
+
+```ts
+const filter = parseFilter(input);
+rows.filter((row) => matches(filter, row, searchableText(row), labelOf(row.actor)));
+```
+
+it now parses into JQL and compiles:
+
+```ts
+const test = compile(parseText(input, { vocabulary: ENTRY_VOCABULARY }), { vocabulary: ENTRY_VOCABULARY });
+rows.filter(test);
+```
+
+The text syntax is BotHandler's, and `tests/text.test.ts` in this repository is BotHandler's
+feed-search suite run through JQL, so the answers are the same.
+
+## 3. Take JSON wherever text was the only option
+
+Anything that accepted a filter as text — an export endpoint, a saved filter, a URL — can now
+also accept the JSON document. Store the JSON rather than the text when you can: the text is
+for people typing, the JSON is what the query *is*, and a stored JSON query survives a change
+to the text syntax.
+
+## What to test
+
+- Port the project's own filter cases and run them through `compile(parseText(…))`.
+- Keep a case per computed field, because those are the ones the project wrote itself.
+- If the project has a service that receives queries, test that an invalid one is answered
+  with a 400 and the refusal's sentence, not a 500.
+
+## Related
+
+- [Text syntax](../reference/text-syntax.md) — what people can type
+- [TypeScript](typescript.md#vocabularies) — vocabularies in full

package/docs/guides/pushdown.md

@@ -0,0 +1,147 @@
+# Pushing a query into a store
+
+Letting a backend answer the part of a query it can, and filtering the rest here.
+
+← [Documentation](../index.md)
+
+---
+
+A store can usually answer part of a question — a field it has an index on, an operator it
+has natively — and nothing of the rest. `plan` splits a query along that line:
+
+```ts
+import { plan, filter } from "@osqd/jql";
+
+const split = plan(query, capabilities);
+const rows = await store.find(split.pushed ?? {});          // the store answers what it can
+const answer = split.remaining === undefined ? rows : filter(rows, split.remaining);
+```
+
+## The contract
+
+> `pushed` ∧ `remaining` ≡ the query
+
+That is the whole feature, and it is why the split happens 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`, one operator inside a
+condition — cannot be split without changing what is asked, so a conjunct is pushed whole or
+kept whole.
+
+Two consequences worth knowing:
+
+- **The pushed half is never narrower than the query.** A caller that ran only `pushed` would
+  get too many rows, never too few. Too many can be filtered down; too few cannot be
+  recovered.
+- **`complete` says when the second pass can be skipped**, and it is the only thing worth
+  checking before doing so.
+
+`kept` says, per clause, why it stayed — "the store cannot filter on `total`", "the store
+cannot answer a negation". That is what to print when somebody asks why a query is slow.
+
+## Capabilities
+
+```ts
+const capabilities = {
+  fields: ["status", "customer.country"],   // or "all"
+  operators: ["$eq", "$in", "$gt", "$lt"],  // JQL's names, or "all"
+  or: true,                                 // default false
+  not: false,                               // default false
+  // A last word, for a store whose limits depend on the values rather than the operators.
+  accepts: (field, condition) => !("$regex" in condition),
+};
+```
+
+Fields are named as **the store** names them: a vocabulary alias is resolved to its path
+first. A vocabulary field that is *computed* is never pushed whatever the capabilities say —
+the store has no way to run a function that lives here.
+
+**What is pushed stands on its own.** Vocabulary names are rewritten to the paths the store
+knows, and relative dates are resolved to instants, so a target needs no vocabulary and both
+halves of the split are judged against the same moment. What stays here keeps the names it
+was written with, because this engine understands them.
+
+## MongoDB, the first target
+
+```ts
+import { plan } from "@osqd/jql";
+import { MONGO_CAPABILITIES, toMongoFilter } from "@osqd/jql/mongo";
+
+const split = plan(query, MONGO_CAPABILITIES);
+const filter = toMongoFilter(split.pushed);
+const rows = await collection.find(filter).toArray();
+```
+
+The operator names line up for the most part, so most of the translation is a copy. The
+interesting part is the handful that do not:
+
+| JQL | MongoDB |
+| --- | --- |
+| `$contains`, `$startsWith`, `$endsWith`, `$glob` | an escaped, anchored `RegExp` |
+| `$eq`/`$in` with `$options: "i"` | an anchored case-insensitive `RegExp` |
+| `{ "$date": … }`, including `{ "$ago": … }` | a `Date` |
+| `$type: "number"` | `$type: ["double", "int", "long", "decimal"]` |
+| `$not` over a query | `$nor: [ … ]` |
+| `$word`, `$length`, `{ "$field": … }`, `$text` | **not in `MONGO_CAPABILITIES`** |
+
+Some of MongoDB's own operators answer exactly for some values and not for others, which a
+list of names cannot say — so the capabilities carry an `accepts` function as well, and it
+keeps back: equality against an embedded document (MongoDB compares its keys in order, JQL
+does not), the case-insensitive form of any comparison whose operand is not a single string
+(a pattern stands in for one string and nothing deeper), `$type: "integer"` (JQL means "a
+number with no fractional part", MongoDB means the `int` storage type), `$type: "bigint"` (a
+run-time type JSON cannot carry, where a driver hands back an ordinary number for a stored
+`long`), and `$regex` carrying a flag MongoDB does not take.
+
+One difference is not about operators at all, and no capability can express it: **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, while JQL sees an array through at every
+level (specification §3). For such a document the two answer differently, in either
+direction, and `plan` cannot know — the shape is in the data, not in the query. If a
+collection stores arrays of arrays of documents, do not treat `complete` as permission to
+skip the second pass over those fields.
+
+The last row is the point. Those four have no exact MongoDB filter, so they are not in the
+capabilities, so `plan` keeps them here and `toMongoFilter` 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 target is promising
+
+`pushed ∧ remaining ≡ query` holds only if the store answers `pushed` **the way JQL would**.
+That is an assumption about the store, not something this library can check, and it is where
+a target goes quietly wrong.
+
+This target is the easy case, because so many of the operators mean the same thing on both
+sides: the translation was checked against an independent implementation of that store's
+matching rules over 100 000 comparisons on generated queries — the string operators, globs, case-insensitive equality
+and membership, `$not`, and the type names — with no disagreement.
+
+Two places to be careful in any target, found while doing that:
+
+- **Coercion.** JQL compares like with like: `$mod` against a boolean or a `null` matches
+  nothing. A store that reads `false` as `0` will answer a pushed `$mod` with rows JQL would
+  not have returned. If a store coerces, leave the operator out of its capabilities.
+- **Missing values under a path that crosses an array.** JQL says an empty array reaches
+  *missing*, so `{ "items.sku": null }` matches a document whose `items` is `[]`. Stores
+  differ here, and the difference is invisible until somebody's page is short a row.
+
+Where a store's answer might differ at all, the operator does not belong in its
+capabilities. A clause kept here costs a second pass; a clause pushed to a store that reads
+it differently costs the right answer.
+
+## Writing another target
+
+1. Write the capabilities: the fields and operators it can answer **exactly**, with the
+   semantics above. Leave out anything you would have to approximate, and anything whose
+   behaviour on an odd value — a boolean where a number is expected, a missing field under an
+   array — you have not checked.
+2. Write the translation for those operators, and throw for anything else — it should never
+   arrive, and if it does you want to know.
+3. Test the contract on data: for a spread of queries and capability sets, the store's filter
+   and the remaining predicate together must match exactly what the whole query matches.
+   `tests/plan.test.ts` does this and is worth copying.
+
+## Related
+
+- [Library API](../reference/api.md) — `plan`, and the collection helpers for the second pass
+- [The specification](../reference/specification.md#14-splitting-a-query) — the rule that makes the split safe

package/docs/guides/typescript.md

@@ -0,0 +1,115 @@
+# TypeScript
+
+Typed queries, the array methods, and vocabularies.
+
+← [Documentation](../index.md)
+
+---
+
+## Typed queries
+
+`Query<T>` knows the shape of `T`. Paths are checked, values are checked, and an operator is
+offered only where it makes sense:
+
+```ts
+import type { Query } from "@osqd/jql";
+
+interface User {
+  id: number;
+  name: string;
+  joined: Date;
+  roles: ("admin" | "editor")[];
+  address: { city: string };
+  sessions: { device: string; minutes: number }[];
+}
+
+const ok: Query<User> = {
+  "address.city": "London",                                   // paths into objects
+  "sessions.device": "mobile",                                // paths through arrays
+  roles: "admin",                                             // a value matches any element
+  joined: { $gte: { $date: "2026-01-01" } },                  // dates, the JSON way
+  sessions: { $elemMatch: { minutes: { $gt: 30 } } },
+};
+
+const wrong: Query<User> = {
+  nme: "Ada",                  // error: no such field
+  id: "1",                     // error: id is a number
+  "address.cty": "London",     // error: no such path
+  name: { $size: 3 },          // error: $size is for arrays
+  roles: "owner",              // error: not a role
+};
+```
+
+Every one of those errors is a query that would otherwise have compiled, run, and silently
+matched nothing. Paths are enumerated five levels deep; deeper ones still work at run time but
+are not offered.
+
+For data whose shape is not known — `unknown`, `any`, parsed JSON — `Query<unknown>` accepts any
+field. The engine still validates the query itself when it compiles it.
+
+## The array methods infer the type
+
+```ts
+import "@osqd/jql/global";
+
+users.jqlSearch({ "address.city": "London" });   // User | undefined
+Array.jqlSearch(users, { id: 1 });               // the same, from any iterable
+users.jqlSearch({ missing: 1 });                 // error: User has no field `missing`
+[1, 2, 3].jqlFilter({ $gt: 1 });                 // a condition on the number itself
+```
+
+The methods and their types come from one import, `@osqd/jql/global`, on purpose: if the main
+entry added `jqlSearch` to the type of every array without adding it to every array, the
+compiler would promise a method that fails at run time.
+
+## Queries from outside the types
+
+A query typed into a search box or read from a URL has no static type. `parseText` returns an
+`UntypedQuery`, and `untyped(json)` marks any other one, so it can be passed where a typed
+query is expected:
+
+```ts
+import { untyped } from "@osqd/jql";
+import { parseText } from "@osqd/jql/text";
+
+users.jqlFilter(parseText(searchBox.value));
+users.jqlFilter(untyped(JSON.parse(request.body)));
+```
+
+It is a brand rather than a loose object type because a loose type would also accept every
+object literal, and `users.jqlSearch({ nme: "Ada" })` would stop being an error. What checks an
+untyped query is the engine, when it compiles it — see
+[Queries from outside](untrusted-input.md).
+
+## Vocabularies
+
+A vocabulary gives a collection the names people use, and fields that are computed rather than
+stored:
+
+```ts
+import { defineVocabulary, type Query } from "@osqd/jql";
+
+const vocabulary = defineVocabulary<User>()({
+  fields: {
+    city: { path: "address.city", kind: "exact" },
+    minutes: { get: (user) => user.sessions.reduce((sum, s) => sum + s.minutes, 0), kind: "number" },
+  },
+  text: ["city"],
+});
+
+users.jqlFilter({ city: "London", minutes: { $gt: 60 } }, { vocabulary });
+```
+
+The field names type-check: `defineVocabulary` is curried so that `T` is given and the fields
+are inferred, and passing the vocabulary in the options adds its names to what the query may
+use, with the type of each computed field. Aliases are for the text syntax and untyped queries;
+the types know the fields.
+
+The same vocabulary drives the [text syntax](../reference/text-syntax.md#field-kinds), which is
+the reason it exists: one list of names for the search box and for the JSON, so the two cannot
+drift apart.
+
+## Related
+
+- [Library API](../reference/api.md) — every export
+- [The specification](../reference/specification.md) — what the queries mean