query-lang 1.0.0

Query-based incremental compilation framework.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88

# query-lang v1.0.0 — API Freeze

**The surface is now stable.** v1.0.0 freezes the public API introduced in 0.2.0 under Semantic Versioning. There are no code changes from 0.2.0 — this release marks the contract as fixed and completes the roadmap.

## What is query-lang?

An incremental computation engine — the model behind Rust's own `salsa` and rust-analyzer, distilled to a small, dependency-free core. You describe a set of queries once; the engine stores the base facts (**inputs**), caches the computed results (**derived queries**), records what each result was read from, and recomputes only what a change actually affects. The whole public surface is one trait and four types — [`System`](https://docs.rs/query-lang/latest/query_lang/trait.System.html), [`Database`](https://docs.rs/query-lang/latest/query_lang/struct.Database.html), [`Revision`](https://docs.rs/query-lang/latest/query_lang/struct.Revision.html), [`Stats`](https://docs.rs/query-lang/latest/query_lang/struct.Stats.html), and [`QueryError`](https://docs.rs/query-lang/latest/query_lang/enum.QueryError.html). It is `#![forbid(unsafe_code)]`, `no_std`-compatible, wires no first-party dependency, and never panics on a query cycle.

## The stability promise

As of 1.0.0 the public API is frozen. Within the `1.x` series:

- `System` (its associated types and `compute`), `Database` (`new` / `set` / `get` / `revision` / `stats` / `system`), `Revision`, `Stats`, and `QueryError` will not change in a breaking way. A breaking change means a new major version.
- The **resolution semantics** are part of the contract, not an implementation detail: a `set` with an unchanged value does not advance the revision or invalidate dependents; a derived query recomputes only on a real miss or a changed dependency; and *early cutoff* holds — when a recomputed value equals its predecessor, dependents are validated rather than recomputed. Code may rely on these, and on `Stats` reflecting them.
- `QueryError` is `#[non_exhaustive]`, so a newly distinguished failure is an additive minor change. Match it with a wildcard arm.
- The `serde` representations are fixed within `1.x`: a `Revision` serializes as its underlying integer, and `Stats` as an object with `computed` / `validated` / `hits` fields.
- MSRV (Rust 1.85) is a compatibility surface: raising it is a documented minor change, never a patch.

Not promised: the concrete `Revision` numbering (only its order and monotonicity are contractual), the internal cache representation, and the exact `Debug` output of a `Database`.

Full details in [`docs/API.md`](https://github.com/jamesgober/query-lang/blob/main/docs/API.md#stability).

## Since 0.2.0

Nothing functional. 0.2.0 delivered the engine; 1.0.0 promises not to break it. If you are already on `query-lang = "0.2"`, moving to `"1"` is a no-op recompile.

## Performance

Unchanged from 0.2.0. Latest local Criterion means, Windows x86_64 and Linux (WSL2 Ubuntu), Rust stable, release build:

| Benchmark | What it measures | Time |
|---|---|-----:|
| `chain/cache_hit` | Re-resolving an already-current query (a hit). | 19–38 ns |
| `chain/cold_build/256` | First resolution of a 256-deep query chain. | ~55 µs |
| `chain/edit_rebuild/256` | Editing the leaf input, rebuilding a 256-deep chain. | ~46 µs |
| `wide/edit_one_of/256` | Editing one input of a 256-wide sum (one branch recomputes, 255 validate). | ~42 µs |

The engine's own per-query overhead is a `BTreeMap` lookup and a revision compare — the figures are dominated by that bookkeeping, since the benchmarked queries do trivial work. Numbers vary by CPU; run `cargo bench --bench bench` on your target for a baseline.

## Verification

Run on Windows x86_64 with testing on Linux (WSL2 Ubuntu), Rust stable and the 1.85 MSRV; the same commands run in the CI matrix across Linux, macOS, and Windows:

```bash
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo clippy --all-targets --all-features -- -D warnings
cargo clippy --no-default-features --all-targets -- -D warnings
cargo test
cargo test --all-features
cargo build --no-default-features
cargo build --examples
cargo +1.85 build --all-features
RUSTDOCFLAGS="-D warnings" cargo doc --no-deps --all-features
cargo deny check
cargo audit
```

All green. Counts at this tag:

- Default features: 28 unit + 6 integration + 4 property + 31 doctests. The doctests include every `rust` example in `README.md` and `docs/API.md`, wired into `cargo test` so the published examples cannot drift from the API.
- `--all-features`: adds 3 `serde` serialization tests exercising the `Revision` and `Stats` derivations.

## Installation

```toml
[dependencies]
query-lang = "1"

# With serde:
query-lang = { version = "1", features = ["serde"] }

# no_std:
query-lang = { version = "1", default-features = false }
```

MSRV: Rust 1.85.

## Documentation

- [README](https://github.com/jamesgober/query-lang/blob/main/README.md)
- [API Reference](https://github.com/jamesgober/query-lang/blob/main/docs/API.md)
- [CHANGELOG](https://github.com/jamesgober/query-lang/blob/main/CHANGELOG.md)

---

**Full diff:** [`v0.2.0...v1.0.0`](https://github.com/jamesgober/query-lang/compare/v0.2.0...v1.0.0).
**Changelog:** [`CHANGELOG.md`](https://github.com/jamesgober/query-lang/blob/main/CHANGELOG.md#100---2026-07-11).