RQL 2.0: specification draft + TypeScript reference parser

[kriszyp]

Summary

Resurrects this project as RQL 2.0 — a specification and reference implementation of the query-language lineage that Harper's REST syntax descends from.

Philosophy (revised during review): the spec defines the ideal language — the cleanest coherent semantics for the syntax in production use — rather than reverse-engineering any single implementation. The reference implementation optimizes for correctness and clarity for direct users; it is deliberately language-neutral in its data model so reference implementations in other languages can follow. Harper keeps its own perf-tuned parser and converges over time; its known deviations are tracked in a divergence-ledger epic (HarperFast/harper#2440) linked from Appendix D, keeping the spec vendor-independent.

• specification/rql-2.0.md — draft spec: ABNF grammar, comparator/value semantics, element-scoped matching, the canonical parsed representation, Core/Extensions conformance profiles, v1 migration (Appendix A), compatibility aliases (Appendix B), implementation divergence ledgers (Appendix D → harper#2440), and a non-normative PostgREST dialect mapping (Appendix E).
• src/ — zero-dependency TypeScript reference parser producing the spec's canonical model: plain serializable data ({filter, sort, select, limit, offset}), no host-framework types.
• test/v2/ — 111 tests: the conformance suite (surface string → canonical representation), seeded from Harper's parser test suites plus new coverage.

Language highlights

• not(...) group/scope negation — pure sugar desugared by De Morgan onto leaf not_ flags and negated element scopes; Harper support filed as HarperFast/harper#2441.

• Small orthogonal core: 9 comparators (eq, lt, le, gt, ge, contains, starts_with, ends_with, in) with uniform not_ negation. ne/equals/not_equal/between/abbreviations are compatibility aliases with exact desugarings — one canonical form per meaning.

• Verbatim vs. interpreted values, not strict-vs-coercive comparators: a=3 binds the string "3"; a==3 binds the number 3. The distinction lives in the value literal, so there is exactly one equality.

• Element-scoped matching: conditions on list-valued properties match existentially, and conjunction doesn't distribute over that quantifier — so ratings=ge=3&=le=4 (one element in range) is semantically distinct from two separate conditions (any elements witness each). Chains and prop[cond&cond] sub-queries canonicalize to an ElementMatch node; between desugars into it.

• Operator model: comparators are infix-only with an open, execution-validated name set; call syntax (select/sort/limit) is a closed, parse-validated set of result-shaping functions. (In 1.x these were one category; see Appendix A.)

• Percent-encoding layering: paths split on literal . before per-segment decoding, so %2E expresses a literal dot in a property name.

• PostgREST dialect mapping (Appendix E) — every PostgREST filter operator maps into Core or an extension comparator, and both dialects' logical layers are the same Group tree (prefix vs infix). Recorded as evidence the canonical model is dialect-neutral, with the real gaps (projection aliasing/casting, nulls ordering, resource embedding) and semantic deltas (embedded-filter join defaults, SQL null tri-state) named rather than papered over.

Open questions for review

• §7 canonical serialization and §9 security bounds are TODO.
• Whether in should also demote to an alias of or-grouped eq (kept Core for idiom and index-scan affinity).
• Extensions profile (Appendix C) semantics are deferred to a future revision.
• Known parser gap: list values inside nested groups ((a=in=(1,2)&b=2)) throw a syntax error — the group sub-parser lacks value-mode scanning for parenthesized lists. Fails loudly, fix planned.

Test plan

• npm test — 111/111 passing (includes the ski-lengths element-scoping case, verbatim/interpreted distinction, %2E handling, alias desugaring equivalences)
• Cross-check corpus against Harper's parser to populate/verify the Appendix D divergence list systematically

🤖 Generated with Claude Code

🤖 Generated with Claude Code