@osqd/jql 0.1.1

package/docs/guides/untrusted-input.md

@@ -0,0 +1,86 @@
+# Queries from outside
+
+Accepting a query from a URL, a request body or somebody else's saved filter.
+
+← [Documentation](../index.md)
+
+---
+
+A JQL query is data, which is why it can travel. It is also why a query can arrive from
+somebody you do not trust. Five things to do with one.
+
+## 1. Compile it with the untrusted limits
+
+```ts
+import { UNTRUSTED_LIMITS, validate } from "@osqd/jql";
+
+const checked = validate<Order>(JSON.parse(body), { limits: UNTRUSTED_LIMITS });
+if (!checked.valid) return respond(400, { error: checked.error.message });
+const matches = orders.filter(checked.test);
+```
+
+`validate` returns the predicate it compiled, rather than only a verdict, so the query that
+was checked is the query that runs. Calling `compile` again afterwards works, but it is the
+one place where the limits can quietly differ between the check and the run.
+
+`UNTRUSTED_LIMITS` caps nesting at 16 levels and the query at 512 fields and operators, and
+**turns `$regex` off**. No engine can tell a pattern that backtracks for a minute — `(a+)+$`
+against a long run of `a`s — from one that does not without running it. The string operators
+(`$contains`, `$startsWith`, `$endsWith`, `$word`) answer almost everything a pattern would,
+in linear time, and stay available.
+
+Every limit refuses rather than truncates: a query cut short answers a different question from
+the one that was asked, and nobody could tell.
+
+## 2. Answer the refusal, do not crash on it
+
+`validate` never throws for an invalid query, and its error names the place:
+`at $or[1].age.$gtt: "$gtt" is not an operator; did you mean "$gt"?`. That sentence is safe to
+return to the caller — it quotes only the query they sent.
+
+## 3. Bound what arrives before it is parsed
+
+The limits apply to the parsed query. The body itself is yours to bound: a `$in` of a million
+ids is a legitimate query and costs a million set entries, so cap the request size where you
+read it. `$in` lists are deliberately not counted against `maxNodes`, because looking up an
+item in one costs the same however long it is.
+
+## 4. Say which operators are on the menu
+
+```ts
+const limits = { ...UNTRUSTED_LIMITS, allowOperators: ["$eq", "$ne", "$in", "$gt", "$gte", "$lt", "$lte", "$and", "$or"] };
+```
+
+`UNTRUSTED_LIMITS` turns `$regex` off, because no engine can tell a pattern that backtracks
+for a minute from one that does not. Which of the *rest* an endpoint wants is a decision only
+that endpoint can make: `$text` walks a whole document, `$elemMatch` carries a query of its
+own, and an endpoint that needs neither should say so once, here, rather than find out later
+which of them somebody used.
+
+An operator outside the list is refused by name. A name in the list that is not an operator
+is refused too — an allowlist with a typo would allow nothing while looking like it allowed
+something.
+
+## 5. Give it a strict vocabulary for a public API
+
+```ts
+const vocabulary = defineVocabulary<Order>()({ fields: { status: {}, total: {}, placed: {} }, strict: true });
+```
+
+With `strict`, a query may name only those fields. Documents tend to grow fields nobody promised
+to keep, and a public query language that can reach every one of them turns every internal
+field into part of the API.
+
+## What a query cannot do
+
+A JQL query is JSON, so it cannot carry code: there is no `$where`, no `$function`, nothing
+that is evaluated. Paths read only an item's own fields, so `constructor`, `__proto__` and
+inherited members are unreachable, and nothing a query does writes to anything. The text
+syntax never throws for anything anybody types, and caps its input at 8 KB and 16 levels
+of brackets — no deeper than the tightest limit the engine is asked to compile under, so the
+box cannot produce a query the engine would refuse.
+
+## Related
+
+- [Library API](../reference/api.md#limits) — the limits in full
+- [The specification](../reference/specification.md#10-limits) — what the standard says about caps

package/docs/index.md

@@ -0,0 +1,102 @@
+# Documentation
+
+Everything about JQL, one page per question.
+
+← [README](../README.md)
+
+---
+
+## What JQL is
+
+JQL is a query language whose queries are **JSON documents**:
+
+```json
+{ "status": "open", "customer.country": "GB", "total": { "$gte": 100 } }
+```
+
+That single decision is the whole idea. A filter that is *data* rather than code can be saved
+in a database, put in a URL, sent to another service, shown to a person, checked before it is
+run, and split so that a store answers the half it is able to. A function can only be called.
+
+`@osqd/jql` is the engine that runs them: zero dependencies, ESM and CommonJS, Node 20 or
+newer.
+
+## What it does
+
+| | |
+| --- | --- |
+| **Filters a collection** | arrays, `Set`s, `Map`s, iterables, async streams, plain objects |
+| **Answers a whole request** | filter, sort, page and choose fields, in one document |
+| **Reads a search box** | what people type compiles into the same JQL, and back out again |
+| **Accepts queries from strangers** | caps on cost, an operator allowlist, and a field allowlist |
+| **Pushes into a store** | splits a query so a database answers the part it can |
+| **Explains itself** | which clause decided a row, and the values it read |
+| **Refuses what it does not understand** | a misspelt operator throws, rather than quietly matching nothing |
+
+That last row is the rule the rest is built on: **a query that is not understood is refused,
+never run as something that looks like it worked.**
+
+## Quick start
+
+```sh
+npm install @osqd/jql
+```
+
+```js
+import { filter, search } from "@osqd/jql";
+
+const orders = [
+  { id: "o-1", status: "open", total: 170, tags: ["fragile"], customer: { country: "GB" } },
+  { id: "o-2", status: "paid", total: 22.5, tags: ["gift"], customer: { country: "GB" } },
+  { id: "o-3", status: "open", total: 30, tags: [], customer: { country: "US" } },
+];
+
+// Two keys mean "and", and a dot reaches inside a nested object.
+filter(orders, { status: "open", "customer.country": "GB" });   // [o-1]
+
+// A value matches any element of an array; operators go where a value would.
+filter(orders, { tags: "gift", total: { $lt: 100 } });          // [o-2]
+
+// Filter, sort, page and pick fields — one document, one call.
+search(orders, { where: { status: "open" }, sort: { total: -1 }, fields: ["id", "total"] });
+// [ { id: "o-1", total: 170 }, { id: "o-3", total: 30 } ]
+
+// And a query that is wrong says so.
+filter(orders, { total: { $gtt: 100 } });
+// JqlError: at total.$gtt: "$gtt" is not an operator; did you mean "$gt"?
+```
+
+Where to go from here:
+
+- **Another five minutes** — [Quick start](start/quick-start.md): the array methods,
+  `compile`, the search box, and queries from outside.
+- **About three hours** — [the course](course/index.md): sixteen lessons that build one real
+  integration, teaching every capability in the order that makes each one make sense, with
+  something to run at every step.
+- **A specific question** — the reference pages below, which answer "how does X work?"
+  rather than "what do I do next?".
+
+## Reference
+
+| Page | Answers |
+| --- | --- |
+| [The specification](reference/specification.md) | What exactly does a query mean? The standard, independent of any implementation |
+| [Text syntax](reference/text-syntax.md) | What can people type into a search box, and what JSON does it become? |
+| [Library API](reference/api.md) | Which functions does the TypeScript package export? |
+| [The command](reference/cli.md) | How do I filter JSON lines from a shell? |
+
+## Guides
+
+| Page | Answers |
+| --- | --- |
+| [TypeScript](guides/typescript.md) | How do typed queries, the array methods and vocabularies fit together? |
+| [Queries from outside](guides/untrusted-input.md) | How do I accept a query from a URL or a request body safely? |
+| [Pushing a query into a store](guides/pushdown.md) | How does a backend answer the part of a query it can? |
+| [Adopting JQL in a project](guides/adopting.md) | How does a project in this family move its filtering onto JQL? |
+
+## Design
+
+| Page | Answers |
+| --- | --- |
+| [Decisions](design/decisions.md) | Why is it shaped this way, and what did that cost? |
+| [Performance](design/performance.md) | How fast is it, how is that measured, and what makes it so? |

package/docs/reference/api.md

@@ -0,0 +1,266 @@
+# Library API
+
+Every export of the TypeScript implementation.
+
+← [Documentation](../index.md) · [Reference](index.md)
+
+---
+
+Three entry points, so nothing is loaded that is not used:
+
+| Import | Holds | Side effects |
+| --- | --- | --- |
+| `@osqd/jql` | the engine, the collection helpers, `search`, vocabularies, types | none |
+| `@osqd/jql/text` | `parseText`, `suggest` — the search-box syntax | none; does not load the engine |
+| `@osqd/jql/global` | the methods on `Array`, `Map` and `Set`, and their types | installs them on import |
+
+Every function that takes a query also takes an already compiled predicate or any function
+`(item) => boolean`, and an options object `{ vocabulary?, limits? }`.
+
+## `@osqd/jql`
+
+### Compiling
+
+| Export | Does |
+| --- | --- |
+| `compile(query, options?)` | Validates the query and returns a predicate. Throws `JqlError` for anything that is not valid JQL |
+| `matches(item, query, options?)` | One item, one query. For a one-off; compile once for a loop |
+| `validate(query, options?)` | `{ valid: true, test }` — the compiled predicate — or `{ valid: false, error }`, without throwing |
+| `untyped(json)` | Marks a query from outside the type system so typed helpers accept it. Returns the same object |
+| `explain(query, item, options?)` | Why one item does or does not match, clause by clause |
+| `canonical(query, options?)` | The query in one shape per meaning |
+| `fingerprint(query, options?)` | Sixteen hex characters naming that shape |
+| `plan(query, capabilities, options?)` | Splits a query into what a store can answer and what stays here — see [Pushing a query into a store](../guides/pushdown.md) |
+| `FIELD_OPERATORS`, `QUERY_OPERATORS` | The operator names, for editors and completions |
+
+`compile` and everything built on it take `{ vocabulary, limits, now, operators }`:
+`now` supplies the instant relative dates resolve against (read once, when the query
+compiles), and `operators` adds operators of your own — see [below](#operators-of-your-own).
+
+### Collections
+
+Each takes an array, an array-like, any iterable, or a `Map` (whose **values** are the items).
+
+| Export | Returns |
+| --- | --- |
+| `find(source, query)` | the first match, or `undefined`; stops at it |
+| `findIndex(source, query)` | its position, or -1 |
+| `filter(source, query)` | every match, as a new array |
+| `count(source, query)` | how many match, without building the list |
+| `some(source, query)` / `every(source, query)` | whether any / all match; both stop early |
+| `partition(source, query)` | `[matches, rest]`, in one pass |
+| `filterMap(map, query)` | a new `Map` of the entries whose value matches |
+| `filterRecord(object, query)` | a new object of the properties whose value matches |
+| `findEntry(mapOrObject, query)` | the first `[key, value]` whose value matches |
+| `group(source, by, options?)` | the matches counted by one field, largest group first |
+
+`group` takes `{ where, limit, items, sort, vocabulary }`. An item counts once in each group
+it belongs to, so a path reaching an array puts it in one group per distinct value; everything
+that cannot name a group — a missing field, a `null`, an object, an **empty list** — shares
+the key `null`, so the rows counted always add up to the rows there are. Ask
+for `items: true` (or a number) to keep the items as well as the count.
+
+### Requests
+
+`search(source, request, options?)` runs a whole [request](specification.md#8-requests):
+`where`, `sort`, `skip`, `limit`, `fields`, `omit`. Without a sort it stops as soon as the page is
+full; with a sort and a limit it keeps only the best `skip + limit` in a bounded heap. With
+`fields` each result is a new object holding only those paths.
+
+`omit` drops paths from each result after `fields` has chosen them, which is how a server
+redacts: the values never leave the process, and the request that says so is data like the
+rest. Results are copies, and anything not on the way to a dropped field is shared with the
+item rather than duplicated.
+
+`where` takes a compiled predicate as well as a query, which is how a page and its total are
+asked for without compiling — or writing — the query twice:
+
+```ts
+const matching = compile<Order>(query);
+const page = search(orders, { where: matching, sort: { placed: -1 }, skip, limit });
+const total = count(orders, matching);
+```
+
+### Sources that arrive over time
+
+For a log read line by line, a cursor, a stream of events. Each takes an `AsyncIterable` — or
+any ordinary collection, so one call site serves both.
+
+| Export | Returns |
+| --- | --- |
+| `findAsync(source, query)` | the first match; stops reading at it |
+| `filterAsync(source, query)` | every match |
+| `countAsync`, `someAsync`, `everyAsync` | the same answers as their synchronous namesakes |
+| `filterStream(source, query)` | an async generator of the matches; stops when the caller does |
+| `searchAsync(source, request)` | a whole request |
+
+Without a sort, `searchAsync` stops as soon as the page is full, so an endless source still
+answers. With a sort it must read everything, and holds only `skip + limit` items while it
+does.
+
+### Why one item matched
+
+```ts
+const why = explain({ verdict: "bot", score: { $gt: 80 } }, row);
+// { matched: false, at: "", because: "1 of 2 parts hold", parts: [
+//   { matched: true,  at: "verdict", because: 'verdict is "bot"' },
+//   { matched: false, at: "score",   because: "score is 70" } ] }
+```
+
+Each clause is compiled and run by the real engine, so an explanation cannot disagree with
+the filter it explains. That costs a small compile per clause, which is why it is for one
+item — a row somebody clicked — rather than for a collection.
+
+### Saved filters: one shape, one name
+
+```ts
+canonical({ b: 2, a: 1, $comment: "note" });   // { a: { $eq: 1 }, b: { $eq: 2 } }
+fingerprint({ a: 1, b: 2 }) === fingerprint({ b: { $eq: 2 }, a: 1 });   // true
+```
+
+Equal fingerprints mean the same query. Different ones mean only that the queries are written
+differently — `{ $gt: 3 }` and `{ $gte: 4 }` agree on every integer, and nothing here notices.
+The rules are in the [specification](specification.md#13-canonical-form-optional), so another
+implementation can agree about which saved filters are duplicates.
+
+A fingerprint is **stable across versions**, so it is safe as a cache key and as the way a
+stored filter is recognised. A set of them is written down in the tests: changing what a query
+is named would miss every cache and duplicate every saved filter in silence, so it takes a
+deliberate change to those values and a line in the changelog.
+
+### Operators of your own
+
+```ts
+const cidr: OperatorDefinition = {
+  name: "$xCidr",                       // the $x prefix is required
+  compile: (operand, at) => {
+    if (typeof operand !== "string") throw new JqlError("takes a network as a string", at);
+    return (value) => typeof value === "string" && inNetwork(value, operand);
+  },
+};
+
+filter(requests, { ip: { $xCidr: "203.0.113.0/24" } }, { operators: [cidr] });
+```
+
+**A query using one is not portable JQL.** The `$x` prefix is what says so at a glance, and
+an engine that was not given the operator refuses the query by name rather than ignoring the
+clause. `cost` orders it against the built-in operators, and `elementwise: false` stops it
+being tried against the elements of an array.
+
+### Vocabularies
+
+`defineVocabulary<T>()({ fields, text?, strict? })` names the fields a query may use:
+
+```ts
+const vocabulary = defineVocabulary<Request>()({
+  fields: {
+    ip: { path: "client.address", aliases: ["actor"], kind: "word" },
+    ua: { path: "headers.user-agent" },
+    outcome: { get: (request) => outcomeOf(request), kind: "exact", values: ["allow", "deny"] },
+  },
+  text: ["ip", "ua"],
+});
+```
+
+| Field option | Meaning |
+| --- | --- |
+| `path` | where the value lives; default the field's own name |
+| `get` | computes the value instead; it must not throw |
+| `aliases` | other names for the field |
+| `kind` | how the text syntax reads a value: `text`, `word`, `exact`, `number`, `date`, `boolean` |
+| `values` | the closed set of values, for completion |
+
+In a projection the two kinds of field differ, because only one of them has somewhere of its
+own to go: a field with a `path` is projected into the document's shape
+(`ip` gives `{ client: { address } }`), while a computed field comes back under its own name
+(`outcome` gives `{ outcome }`).
+
+`text` lists the fields a bare search word looks in. `strict: true` refuses any name that is
+not in the vocabulary. Names are matched without regard to case. Two names for one field, a
+field with both `path` and `get`, and a `text` entry that names nothing are refused when the
+vocabulary is defined.
+
+### Limits
+
+`DEFAULT_LIMITS` and `UNTRUSTED_LIMITS` — see [Queries from outside](../guides/untrusted-input.md).
+
+| Limit | Default | Untrusted |
+| --- | --- | --- |
+| `maxDepth` | 32 | 16 |
+| `maxNodes` | 10 000 | 512 |
+| `maxPatternLength` | 1 024 | 0 |
+| `maxGlobLength` | 1 024 | 256 |
+| `maxTextDepth` | 16 | 8 |
+| `allowRegex` | `true` | `false` |
+| `allowOperators` | `"all"` | `"all"` |
+
+`allowOperators` is an allowlist: give it the operator names a query may use and the rest are
+refused by name. `$options` and `$comment` are exempt, and `$field` counts as an operator,
+because comparing two fields is a capability of its own. A name that is not an operator is
+itself refused — an allowlist with a typo in it would allow nothing and look like it allowed
+something.
+
+```ts
+const publicLimits = { ...UNTRUSTED_LIMITS, allowOperators: ["$eq", "$ne", "$in", "$gt", "$gte", "$lt", "$lte", "$and", "$or"] };
+```
+
+### Errors
+
+`JqlError` is the one error the engine throws. `error.at` is where in the query the problem is
+(`$or[1].age.$gt`), and the message starts with it: `at $or[1].age.$gt: "$gtt" is not an
+operator; did you mean "$gt"?`.
+
+## `@osqd/jql/text`
+
+| Export | Does |
+| --- | --- |
+| `parseText(input, { vocabulary?, fields? })` | the search-box syntax to a JQL query; never throws |
+| `toText(query, { vocabulary?, fields? })` | the reverse: `{ text, complete, unexpressed }` |
+| `suggest(input, caret, vocabulary?)` | completions for the token under the caret, and the span they replace |
+| `MAX_TEXT_CHARS`, `MAX_TEXT_DEPTH`, `TEXT_OPERATORS` | the caps and the operator words |
+
+`toText` is how a stored JSON filter gets back into a search box. It is deliberately not
+total — `$elemMatch`, `$glob`, `$size`, `$length` and `{ "$field": … }` have no spelling —
+so it returns the text *and* what it left out. The text is exact for what it says; a caller
+that ignores `unexpressed` is showing somebody a filter wider than the one that is running,
+and `complete` makes that check one line.
+
+## `@osqd/jql/mongo`
+
+| Export | Does |
+| --- | --- |
+| `MONGO_CAPABILITIES` | what a MongoDB `find` filter can answer, for `plan` |
+| `toMongoFilter(query, options?)` | translates the pushed part into a MongoDB filter |
+
+What `plan` pushes already carries the names the store knows and instants rather than
+durations, so `toMongoFilter(split.pushed)` needs no vocabulary. Its `vocabulary` option is
+for translating a query that did not come from `plan`.
+
+See [Pushing a query into a store](../guides/pushdown.md).
+
+## `@osqd/jql/cli`
+
+`main(argv, streams)` returns the exit code, and `run()` wires it to the process. The command
+itself is [`jql`](cli.md).
+
+## `@osqd/jql/global`
+
+Importing it adds, non-enumerably:
+
+| On | Methods |
+| --- | --- |
+| every array | `jqlSearch`, `jqlFilter`, `jqlCount`, `jqlSome`, `jqlEvery`, `jqlFindIndex`, `jqlPartition`, `jqlQuery` |
+| `Array` itself | the same, taking the source first: `Array.jqlSearch(iterable, query)` |
+| every `Map` | `jqlSearch` (a value), `jqlFilter` (a `Map`), `jqlCount` |
+| every `Set` | `jqlSearch`, `jqlFilter` (a `Set`), `jqlCount` |
+
+It also exports `install()` and `uninstall()`. `install` refuses to replace a method of the
+same name that something else defined, and is a no-op when the methods are already there —
+including when another copy of JQL in the same process installed them, which npm produces
+whenever two dependencies want different versions. The copy that got there first keeps the
+field. `uninstall` removes JQL's methods and nothing else's.
+
+## Related
+
+- [The specification](specification.md) — what the queries mean
+- [TypeScript](../guides/typescript.md) — the types behind these signatures

package/docs/reference/cli.md

@@ -0,0 +1,103 @@
+# The command
+
+`jql` — filtering JSON lines from a shell.
+
+← [Documentation](../index.md) · [Reference](index.md)
+
+---
+
+The shape this library is for arrives as one JSON value per line — a log, an export, a
+`kubectl` dump — more often than it arrives as an array in a program. The command is the
+same engine over a stream, and everything it does is a public export used the way the
+documentation says to use it.
+
+```sh
+npx jql '{"status":"open"}' orders.jsonl
+jql --text 'status:open total:>100' orders.jsonl
+kubectl logs -f app | jql --text 'level:error' --fields ts,msg
+```
+
+## Usage
+
+```
+jql [options] <query> [file...]
+```
+
+`<query>` is a JQL query as JSON, or the [search-box syntax](text-syntax.md) with `--text`.
+Files hold one JSON value per line; with none, or with `-`, it reads standard input.
+
+| Option | Does |
+| --- | --- |
+| `--text` | read the query as search-box text rather than JSON |
+| `--sort <field:order>` | order by a field, `asc` or `desc`; repeatable, the first key breaks ties last |
+| `--skip <n>` / `--limit <n>` | pass over the first n matches / stop after n |
+| `--fields <a,b>` | keep only these paths in each result |
+| `--omit <a,b>` | drop these paths from each result |
+| `--count` | print how many matched instead of the matches |
+| `--group <field>` | print how many matched by that field, largest first; `--limit` then says how many groups, and `--sort`, `--skip`, `--fields`, `--omit` and `--count` are refused rather than ignored |
+| `--explain` | say on stderr why the first line did or did not match |
+| `--canonical` | print the query in its canonical form and stop |
+| `--untrusted` | compile with the untrusted limits: `$regex` off, tighter caps |
+| `--pretty` | print each result over several lines |
+| `-h, --help` / `-v, --version` | |
+
+Both `--name value` and `--name=value` work.
+
+## The two rules it is built on
+
+**stdout is the artifact.** Matching lines and nothing else, so `jql … > kept.jsonl`
+produces a file worth having. Counts, warnings and explanations go to stderr.
+
+A matching line is written back **byte for byte as it arrived** — spacing, key order and all
+— so filtering a file cannot change the data in it. That matters for numbers JavaScript
+cannot hold exactly: a thirty-digit identifier read and written again comes back as
+`1.2345678901234568e+29`, and `1e400` comes back as `null`. Asking for the result to be
+reshaped (`--fields`, `--omit`, `--group`) or laid out again (`--pretty`) is asking for
+something other than the line, and then it is written out as JSON. A leading byte-order mark
+is dropped rather than treated as data.
+
+**A value is validated, never coerced.** `--limit all` is an error, not a limit that quietly
+stops limiting — `Number("all")` is `NaN`, every comparison against it is false, and the
+failure would be silent in both directions. An option that cannot apply is refused for the
+same reason: `--group` prints groups, so `--fields` beside it is an error rather than a flag
+that goes nowhere.
+
+**Everything streams except `--group`.** A filter, a sort with a limit and a count all read
+one line at a time and hold only the page they are building, so a file larger than memory is
+fine. Counting by a field is the exception: a group's total is not known until the last line,
+so the matching items are held while the tally is built.
+
+## Exit codes
+
+| Code | Means |
+| --- | --- |
+| 0 | it ran; no matches is an answer, not a failure |
+| 1 | a file could not be read, or nothing in the input was JSON |
+| 2 | bad arguments, or a query the engine refuses |
+
+A line that is not JSON is reported on stderr and skipped; the lines around it are still
+answered. If *every* line was unreadable, that is a failure rather than an empty result.
+
+## Examples
+
+```sh
+# the ten slowest requests, as a table of two fields
+jql --text 'path:/api' --sort durationMs:desc --limit 10 --fields path,durationMs access.jsonl
+
+# how many of each verdict, for what the query matched
+jql --group verdict '{"score":{"$gte":70}}' feed.jsonl
+
+# why a line is not matching the filter you thought it would
+jql --explain --text 'status:open total:>500' orders.jsonl > /dev/null
+
+# a filter from somewhere you do not trust
+jql --untrusted "$UNTRUSTED_QUERY" events.jsonl
+
+# a redacted copy
+jql --omit customer.email,customer.phone '{}' orders.jsonl > shareable.jsonl
+```
+
+## Related
+
+- [Text syntax](text-syntax.md) — what `--text` takes
+- [Library API](api.md) — the exports the command is built from

package/docs/reference/index.md

@@ -0,0 +1,12 @@
+# Reference
+
+The language, its text form, and the library.
+
+← [Documentation](../index.md)
+
+---
+
+- [The specification](specification.md) — what a query means; the standard every implementation follows
+- [Text syntax](text-syntax.md) — the search-box form, and the JSON each piece becomes
+- [Library API](api.md) — every export of `@osqd/jql` and its entry points
+- [The command](cli.md) — `jql`, for filtering JSON lines from a shell