graphql_declarative 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0a17bf0e5ca0e7227a7c7d8a0f2a711806f79b292722cff80bf28625f731447d
+  data.tar.gz: 12d41cd6eaa0d7346f070a00654b3652f8de47774d2761a2b28bdcd7c758fa26
+SHA512:
+  metadata.gz: fadd5e9d895f3ef0a4d329022f1697d57e5cbe2bef52a32be95135a1a75dd956a7dd167149f4b9cdcc51f08ccc8c037a643ea092ca7e887270d33bc278e0eb51
+  data.tar.gz: 3b04b9ed28fbdaf9487f8f45417792fedb8632704fd02515bc6d85bf88e1b486fc43598f3414653a09b64758c2c559194d981fab424d9736dd8d7d320f585be8

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/standardrb/standard
+ruby_version: 3.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Raja Rajan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,225 @@
+# graphql_declarative
+
+Declarative filtering, sorting, cursor pagination and preloading for
+[graphql-ruby](https://github.com/rmosolgo/graphql-ruby) resolvers.
+
+In a large GraphQL API, every list endpoint re-implements the same four concerns
+by hand. Four hand-written concerns per endpoint, across a hundred endpoints, is
+where N+1s and pagination bugs come from — each endpoint is a fresh chance to get
+it wrong.
+
+Two of those bugs are not tedium. They are correctness failures that most
+implementations ship, and both are invisible in a test suite with static
+fixtures.
+
+## Before
+
+```ruby
+class Resolvers::Courses < GraphQL::Schema::Resolver
+  type Types::Course.connection_type, null: false
+
+  argument :title_contains,    String,  required: false
+  argument :enrollment_status, String,  required: false
+  argument :sort_by,           String,  required: false
+
+  def resolve(title_contains: nil, enrollment_status: nil, sort_by: nil, first: 25, after: nil)
+    scope = Course.where(school_id: context[:school_id])
+    scope = scope.where("title LIKE ?", "%#{title_contains}%") if title_contains
+    scope = scope.joins(:enrollments)
+                 .where(enrollments: {status: enrollment_status}) if enrollment_status
+    scope = scope.order(sort_by || :id)
+    scope = scope.offset(Base64.decode64(after).to_i) if after
+    scope.limit(first).includes(:author)
+  end
+end
+```
+
+Four bugs: the `joins` corrupts pagination, the offset cursor breaks under
+concurrent writes, `order(sort_by)` interpolates user input, and `includes(:author)`
+is hardcoded so any new association in the query reintroduces an N+1.
+
+## After
+
+```ruby
+class Types::CourseFilter < GraphqlDeclarative::FilterInput
+  filter :title,             :string, ops: [:contains]
+  filter :enrollment_status, :string, through: :enrollments, column: :status
+end
+
+class Resolvers::Courses < GraphqlDeclarative::Resolver
+  type Types::Course.connection_type, null: false
+
+  filterable_by Types::CourseFilter
+  sortable_by   :title, :created_at
+  paginate      default_page_size: 25, max_page_size: 100
+  preload_from_selection
+
+  def base_scope
+    Course.where(school_id: context[:school_id])
+  end
+end
+```
+
+No `resolve`. You declare what is allowed; the gem builds the query.
+
+## Correctness 1: association filters must not join the paginated relation
+
+`joins` multiplies rows. A course with 3 matching enrollments occupies 3 rows, so
+`LIMIT 25` returns fewer than 25 distinct courses, and a cursor taken from the
+last row points into the middle of a duplicate run — page 2 skips records that
+were never shown. `DISTINCT` fixes the count but breaks `ORDER BY` on a joined
+column and still cannot produce a stable cursor.
+
+Four courses with 3, 1, 2 and 1 active enrollments, page size 2:
+
+| | page 1 | page 2 | `count` |
+|---|---|---|---|
+| `joins` | `[A, A]` | skips records | `7` |
+| this gem | `[A, B]` | `[C, D]` | `4` |
+
+`through:` filters are resolved into an id subquery, so the paginated relation is
+never joined:
+
+```sql
+SELECT "courses".* FROM "courses"
+WHERE "courses"."published" = TRUE
+  AND "courses"."id" IN (SELECT "courses"."id" FROM "courses"
+                         INNER JOIN "enrollments" ON "enrollments"."course_id" = "courses"."id"
+                         WHERE "enrollments"."status" = 'active')
+  AND ("courses"."title" > 'B' OR ("courses"."title" = 'B' AND "courses"."id" > 3))
+ORDER BY "courses"."title" ASC, "courses"."id" ASC
+LIMIT 3
+```
+
+Proof: [`spec/pagination_through_associations_spec.rb`](spec/pagination_through_associations_spec.rb).
+Three specs assert the contract; three more assert the broken `joins` behaviour on
+purpose, so the bug stays demonstrable and cannot silently return.
+
+## Correctness 2: cursors must be keys, not offsets
+
+graphql-ruby's `GraphQL::Pagination::RelationConnection#cursor_for` encodes
+`offset.to_s` ([relation_connection.rb:47](https://github.com/rmosolgo/graphql-ruby/blob/master/lib/graphql/pagination/relation_connection.rb)).
+If a row is inserted or deleted before the current page while a client is
+paginating, every later cursor points one place off — records repeat or vanish.
+
+This gem encodes the tuple `(sort_value, id)` and seeks:
+
+```sql
+sort_col > :v OR (sort_col = :v AND id > :i)
+```
+
+Row-value comparison is deliberately avoided; SQLite and MySQL support varies.
+
+Proof: [`spec/stability_spec.rb`](spec/stability_spec.rb) — paginate, insert a row
+before the current page, then fetch page 2. The keyset walk returns each record
+exactly once; the offset walk repeats one.
+
+## Preloading
+
+`preload_from_selection` walks the query's selection set and preloads the
+associations the query actually asked for, so the preload list cannot drift from
+the query the way a hardcoded `includes` does.
+
+Page of 25, from 2,000 courses / 200 authors / 6,000 enrollments, selecting
+`author { name }` and `enrollments { status }`:
+
+| | queries | time |
+|---|---|---|
+| no preloading | 51 | 5.3 ms |
+| preload derived from the selection set | 3 | 2.0 ms |
+
+Reproduce with `ruby bench/query_count.rb`.
+
+## Safety
+
+Column, table and association identifiers come only from `filter` declarations
+and the `sortable_by` whitelist — never from user input. Values are always bind
+parameters, `LIKE` metacharacters are escaped with an explicit `ESCAPE` clause,
+and there is no `Arel.sql` on an interpolated string anywhere in the gem.
+`sortable_by` rejects anything not declared, so `sortBy: "title; DROP TABLE courses"`
+raises rather than reaching SQL.
+
+## Installation
+
+```ruby
+gem "graphql_declarative"
+```
+
+Requires Ruby >= 3.0, graphql ~> 2.0, ActiveRecord >= 6.1. Tested against
+PostgreSQL, MySQL and SQLite.
+
+## API
+
+### `FilterInput`
+
+```ruby
+filter :title,       :string,   ops: [:eq, :contains, :starts_with, :ends_with, :in]
+filter :created_at,  :datetime, ops: [:gte, :lte]
+filter :author_name, :string,   through: :author, column: :name
+```
+
+`:eq` generates the bare argument name (`title:`); every other op suffixes it
+(`title_contains:`, `created_at_gte:`). `through:` names an association;
+`column:` defaults to the filter name.
+
+Multiple filters on the same association intersect **within one subquery** — one
+child row must satisfy all predicates for that association.
+
+### `Resolver`
+
+| Declaration | Adds |
+|---|---|
+| `filterable_by FilterClass` | `filter:` argument |
+| `sortable_by :a, :b` | `sort_by:` and `sort_direction:` enums |
+| `paginate default_page_size:, max_page_size:` | `first:` and `after:` |
+| `preload author: :profile` | static preload, always applied |
+| `preload_from_selection` | preload derived from the query |
+
+Pipeline order, which is load-bearing:
+
+```
+base_scope -> Filter -> Sort -> cursor seek -> LIMIT n+1 -> Preloader -> Connection
+```
+
+Preload runs after `LIMIT` — preloading before the page is bounded loads the
+whole filtered set. Sort runs before the seek, because the seek predicate is
+built from the sort column.
+
+## Limitations in v0.1.0
+
+Stated plainly, because each one is a place this gem will not protect you:
+
+- **Forward pagination only.** `last:`/`before:` raise a clear error rather than
+  being silently ignored.
+- **Sortable columns must be `NOT NULL`.** A `NULL` sort value never compares
+  true, so rows carrying it would vanish mid-pagination. Declaring a nullable
+  column raises — but at first use, not at boot, so a misdeclared resolver ships
+  green and fails on the first request that selects it.
+- **Single-column primary keys only.** Composite keys raise.
+- **Top-level `AND` only.** No nested `AND`/`OR`/`NOT` filter trees.
+- **No `totalCount`.** It is an unbounded second query.
+- **Cursors do not record the sort they were issued under.** Changing `sort_by`
+  mid-pagination gives wrong results rather than an error.
+- **A malformed cursor id casts silently.** A garbage id may yield a
+  valid-looking page instead of a "malformed cursor" error.
+- **The id subquery is built from the model, not from `base_scope`.** In a
+  multi-tenant app the subquery scans across tenants before the outer query
+  intersects it back down. Correct, but not free.
+- No polymorphic associations, STI-aware filtering, custom scalar filters, or
+  Rails generators.
+
+## Development
+
+```
+bin/setup
+bundle exec rspec
+bundle exec standardrb
+ruby bench/query_count.rb
+```
+
+`SPEC.md` is the design document: component contracts, the pipeline invariants,
+and a decision log recording why each tradeoff was made.
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/SPEC.md

@@ -0,0 +1,336 @@
+# graphql_declarative — technical spec
+
+Status: draft for v0.1.0 · Target: graphql-ruby ~> 2.6, ActiveRecord >= 6.1, Ruby >= 3.0
+
+---
+
+## 1. Problem
+
+Every list endpoint in a graphql-ruby app re-implements the same four concerns by
+hand: filtering, sorting, pagination, and preloading. Four hand-written concerns
+per endpoint, multiplied across a large API, is where N+1s and pagination bugs
+come from — each endpoint is a fresh chance to get it wrong.
+
+Two of those bugs are not just tedium, they are *correctness* failures that most
+implementations ship:
+
+**(a) Filtering on an association corrupts pagination.** `joins` multiplies rows.
+A course with 3 matching enrollments occupies 3 rows, so `LIMIT 25` returns fewer
+than 25 distinct courses and a cursor taken from the last row points into the
+middle of a duplicate run — page 2 skips records that were never shown.
+`DISTINCT` fixes the count but breaks `ORDER BY` on a joined column and still
+cannot produce a stable cursor.
+
+**(b) graphql-ruby's own cursors are offsets.** `GraphQL::Pagination::RelationConnection#cursor_for`
+(relation_connection.rb:47) encodes `offset.to_s`. If a row is inserted or deleted
+before the current page while a client is paginating, every subsequent cursor
+points one place off — records repeat or vanish. This is invisible in tests with
+static fixtures and shows up in production.
+
+## 2. What this gem is
+
+A resolver *declares* its list behaviour; the gem executes it.
+
+- Filtering, sorting, pagination and preloading declared, not hand-written
+- Association filters resolved through id subqueries, so pagination stays correct
+- **Keyset** cursors `(sort_value, id)`, not offsets
+- Preload set derived from the query's actual selection set, so it cannot drift
+  from what the query asks for
+
+## 3. Non-goals for v0.1.0
+
+Explicitly out. Each is a scope trap; adding one costs a session.
+
+- Nested boolean filter trees (`AND` / `OR` / `NOT` groups). Top-level `AND` only.
+- Backward pagination (`last:` / `before:`). Forward only. `has_previous_page`
+  returns `false` and this is documented, not hidden.
+- `totalCount`. It is a second query and an unbounded one; callers who want it
+  can add it.
+- Polymorphic associations, STI-aware filtering, custom scalar filters.
+- Rails generators, railties, engine integration.
+- Databases other than PostgreSQL, MySQL and SQLite.
+
+---
+
+## 4. Public API
+
+```ruby
+class Types::CourseFilter < GraphqlDeclarative::FilterInput
+  filter :title,       :string,   ops: [:eq, :contains, :starts_with]
+  filter :published,   :boolean
+  filter :created_at,  :datetime, ops: [:gte, :lte]
+  filter :author_name, :string,   through: :author,      column: :name
+  filter :enrollment_status, :string, through: :enrollments, column: :status
+end
+
+class Resolvers::Courses < GraphqlDeclarative::Resolver
+  type Types::Course.connection_type, null: false
+
+  filterable_by Types::CourseFilter
+  sortable_by   :title, :created_at
+  paginate      default_page_size: 25, max_page_size: 100
+
+  preload author: :profile      # always
+  preload_from_selection        # plus whatever the query selects
+
+  def base_scope
+    Course.where(school_id: context[:school_id])
+  end
+end
+```
+
+The resolver defines `base_scope` and nothing else. `resolve` is provided.
+
+### Generated arguments
+
+`filterable_by` adds one argument `filter:` of the given input type.
+`sortable_by` adds `sort_by:` (enum of the whitelisted fields) and `sort_direction:`
+(enum `ASC`/`DESC`, default `ASC`). `paginate` adds `first:` and `after:`.
+
+Argument naming inside the filter input, from `filter :title, :string, ops: [...]`:
+
+| op            | argument            | SQL                                  |
+|---------------|---------------------|--------------------------------------|
+| `eq`          | `title`             | `title = ?`                          |
+| `contains`    | `title_contains`    | `title LIKE '%' || ? || '%'`         |
+| `starts_with` | `title_starts_with` | `title LIKE ? || '%'`                |
+| `ends_with`   | `title_ends_with`   | `title LIKE '%' || ?`                |
+| `in`          | `title_in`          | `title IN (?)`                       |
+| `gt/gte/lt/lte` | `created_at_gte`  | `created_at >= ?`                    |
+
+`eq` generates the bare name, never `title_eq`.
+
+---
+
+## 5. Execution pipeline
+
+`Resolver#resolve` runs exactly this order. The order is load-bearing.
+
+```
+base_scope
+  -> Filter.apply        (direct predicates; association filters as id subqueries)
+  -> Sort.apply          (whitelisted column + :id tiebreaker)
+  -> Cursor seek         (WHERE clause from `after:`)
+  -> LIMIT page_size + 1 (the +1 is how has_next_page is known without COUNT)
+  -> Preloader           (on the bounded page only)
+  -> KeysetConnection
+```
+
+Two invariants:
+
+1. **Preload runs last, after `LIMIT`.** Preloading before the page is bounded
+   preloads the whole filtered set.
+2. **Sort is applied before the cursor seek** because the seek predicate is built
+   from the sort column. A cursor is only meaningful against the sort it was
+   issued under; see §6.4.
+
+---
+
+## 6. Component contracts
+
+### 6.1 `FilterInput`
+
+Subclass of `GraphQL::Schema::InputObject`.
+
+```ruby
+Definition = Struct.new(:name, :type, :ops, :through, :column, keyword_init: true)
+
+def self.filter(name, type, ops: nil, through: nil, column: nil)
+def self.definitions  # => {Symbol => Definition}
+```
+
+- `ops` defaults per type (`DEFAULT_OPS`); `boolean` is `[:eq]` only.
+- `through:` names an association on the model; `column:` the column on that
+  association's table. `column:` defaults to `name`.
+- `definitions` must be inherited-safe: a subclass sees its parent's definitions.
+  Use `Class#inherited` to `dup` the hash, or walk `superclass`.
+- Raise `GraphqlDeclarative::Error` at class-definition time for an unknown type
+  or an op not valid for that type. Fail at boot, not per-request.
+
+### 6.2 `Filter`
+
+```ruby
+Filter.apply(scope, filter_class, args) # => ActiveRecord::Relation
+```
+
+- `args` is the `filter:` input as a Hash with symbol keys; `nil` → return `scope`.
+- Direct filters chain `where` on `scope`.
+- **Association filters never touch `scope` as a join.** Group all `through:`
+  filters by association, build ONE subquery per association, then constrain:
+
+```ruby
+ids = model.joins(assoc).where(assoc_table => predicates).select(:id)
+scope.where(id: ids)
+```
+
+  Grouping matters: two filters on the same has_many must intersect within one
+  subquery. Two chained subqueries mean "a child matching A and a child matching
+  B" — different, and usually not what the caller meant. Document the chosen
+  semantic: **one child must satisfy all predicates for that association.**
+- Unknown keys in `args` are a programmer error → raise, do not ignore.
+- Never interpolate a column name from input. Column identifiers come only from
+  `definitions`; values go through bind params.
+
+### 6.3 `Sort`
+
+```ruby
+Sort.apply(scope, allowed:, field:, direction: :asc) # => ActiveRecord::Relation
+```
+
+- `field` must be in `allowed` or raise. `direction` must be `:asc`/`:desc`.
+- Always append `:id` as the final ordering term, in the same direction.
+  A non-total order makes keyset pagination non-deterministic — two rows with
+  equal sort values can come back in either order between requests, and the
+  cursor cannot distinguish them.
+- Sorting on a `through:` column is out of scope for v0.1.0. Raise a clear error
+  rather than silently joining and reintroducing (a).
+
+### 6.4 `Cursor`
+
+```ruby
+Cursor.encode(sort_value:, id:)  # => String (Base64, urlsafe, unpadded)
+Cursor.decode(str)               # => {sort_value:, id:}
+Cursor.seek(scope, column:, direction:, sort_value:, id:)
+```
+
+- Payload is JSON `{"v" => sort_value, "i" => id}`, Base64-urlsafe encoded.
+  Opaque to clients by contract; do not document the encoding as stable.
+- Seek predicate, ASC:
+
+```sql
+(sort_col, id) > (:v, :i)
+-- portable form, since SQLite/MySQL row-value support varies:
+sort_col > :v OR (sort_col = :v AND id > :i)
+```
+
+  DESC flips both comparisons. Encode the sort value as-is and cast on decode
+  using the column type — a datetime cursor round-tripping through JSON loses
+  sub-second precision otherwise, which silently drops or repeats rows.
+- `NULL` sort values: `NULL` never compares true, so rows with a null sort value
+  vanish mid-pagination. v0.1.0 requires sortable columns to be `NOT NULL` and
+  raises otherwise. Document this; it is the honest limit.
+- A malformed or undecodable cursor raises `GraphqlDeclarative::Error`, it does
+  not silently reset to page 1.
+
+### 6.5 `KeysetConnection < GraphQL::Pagination::Connection`
+
+Returned directly from `resolve`; graphql-ruby uses a `Connection` instance as-is
+rather than re-wrapping it.
+
+- `nodes` — the fetched page, at most `page_size`.
+- `has_next_page` — true iff the `LIMIT page_size + 1` query returned the extra
+  row. No `COUNT`.
+- `has_previous_page` — always `false` in v0.1.0 (forward-only). Documented.
+- `cursor_for(item)` — `Cursor.encode(sort_value: item[sort_column], id: item.id)`.
+- `page_size` — `[first || default_page_size, max_page_size].min`. A `first:`
+  above `max_page_size` is clamped, not an error.
+
+### 6.6 `Preloader`
+
+```ruby
+Preloader.from_lookahead(lookahead, model) # => Hash suitable for .preload
+```
+
+- Walk `lookahead.selections`. graphql-ruby 2.6 `Lookahead` exposes
+  `selections`, `selection(name)`, `field`, `name`, `selects?`.
+- Unwrap connection plumbing first: descend through `edges` → `node`, and
+  through `nodes`, before matching field names against associations.
+- A selection maps to a preload only if `model.reflect_on_association(name)`
+  is non-nil. Plain columns are ignored.
+- Recurse to build nested hashes: `{author: [:profile], enrollments: []}`.
+- Merge with the static `preload` declarations; static wins on conflict.
+- Cap recursion depth (default 3) so a deep query cannot generate an enormous
+  preload tree.
+
+### 6.7 `Resolver`
+
+```ruby
+class << self
+  def filterable_by(filter_class)
+  def sortable_by(*fields)
+  def paginate(default_page_size: 25, max_page_size: 100)
+  def preload(*args)
+  def preload_from_selection
+end
+
+def base_scope  # subclass must implement
+```
+
+- Class-level config must be inheritance-safe (same rule as `FilterInput`).
+- `resolve(**args)` implements §5 and returns a `KeysetConnection`.
+- If `sortable_by` is absent, sort by `:id` ascending.
+- `base_scope` returning something that is not an `ActiveRecord::Relation` raises.
+
+---
+
+## 7. Errors and security
+
+- One error class: `GraphqlDeclarative::Error < StandardError`.
+- Configuration errors (unknown op, unsortable field, missing `base_scope`) raise
+  at class-definition or boot time wherever possible.
+- Request errors (bad cursor, unknown filter key) raise
+  `GraphQL::ExecutionError` so they surface as GraphQL errors, not 500s.
+- **No identifier ever comes from user input.** Column and association names come
+  only from `definitions` and the `sortable_by` whitelist. Values are always bind
+  parameters. There is no `Arel.sql` on an interpolated string anywhere in the gem.
+- Multi-tenancy is the caller's job via `base_scope`; the gem never adds or
+  removes scoping conditions.
+
+---
+
+## 8. Test plan
+
+| File | Covers |
+|---|---|
+| `spec/pagination_through_associations_spec.rb` | **Written.** The (a) contract + 3 specs asserting the naive `joins` bug |
+| `spec/filter_input_spec.rb` | Argument generation per op, defaults, inheritance, config-time errors |
+| `spec/filter_spec.rb` | Direct predicates; one subquery per association; two filters on one association intersect |
+| `spec/sort_spec.rb` | Whitelist enforcement, `:id` tiebreaker appended, direction |
+| `spec/cursor_spec.rb` | Round-trip incl. datetime precision, seek predicate ASC/DESC, malformed cursor raises |
+| `spec/connection_spec.rb` | `has_next_page` via the +1 row, `page_size` clamping |
+| `spec/preloader_spec.rb` | Selection-set walk, `edges`/`node` unwrapping, columns ignored, depth cap |
+| `spec/integration_spec.rb` | A real schema, a real query, assert query **count** — this is the N+1 proof |
+| `spec/stability_spec.rb` | Insert a row before the current page mid-pagination; keyset holds, offset would not |
+
+`stability_spec.rb` is the executable proof of (b). Reference it in the README
+next to the pagination spec.
+
+---
+
+## 9. Milestones
+
+**M1 — filtering.** `FilterInput`, `Filter`, their specs, and swapping the
+`filtered` stub in the pagination spec to the real `Filter.apply`. The three
+contract specs going green against a real association filter is M1's definition
+of done.
+
+**M2 — ordering and paging.** `Sort`, `Cursor`, `KeysetConnection`,
+`stability_spec.rb`.
+
+**M3 — preloading and assembly.** `Preloader`, `Resolver`, `integration_spec.rb`
+asserting query count.
+
+**M4 — release.** README (problem → before/after → the two correctness sections →
+install → API reference), reproducible benchmark in `bench/`, CI green on Ruby
+3.2/3.3, v0.1.0 to RubyGems.
+
+## 10. Definition of done
+
+- [ ] All spec files in §8 exist and pass
+- [ ] CI green on 3.2 and 3.3
+- [ ] README leads with the problem, and cites both correctness specs by path
+- [ ] `bench/` produces the query-count table in the README, reproducibly
+- [ ] Published as 0.1.0
+- [ ] Non-goals from §3 stated plainly in the README
+
+## 11. Decision log
+
+| Decision | Why | Reconsider if |
+|---|---|---|
+| id subquery, not `DISTINCT` | `DISTINCT` breaks `ORDER BY` on joined columns and gives no stable cursor | never |
+| Keyset, not offset cursors | offsets shift under concurrent writes | never |
+| Forward-only pagination | `before:`/`last:` doubles the cursor logic for little use | users ask |
+| One subquery per association | "one child satisfies all predicates" is the intuitive reading | users ask for the other |
+| Sortable columns must be `NOT NULL` | `NULL` sort values vanish from keyset pagination | v0.2 with NULLS FIRST/LAST |
+| No `totalCount` | unbounded second query | opt-in only |
+| Preload after `LIMIT` | preloading before bounding loads the whole filtered set | never |

data/bench/query_count.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# Reproducible query-count benchmark backing the numbers in README.md.
+#   ruby bench/query_count.rb
+#
+# Measures the SQL a page costs with and without selection-set-driven preloading,
+# counting real statements via ActiveSupport::Notifications.
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "graphql_declarative"
+require "active_record"
+require "benchmark"
+
+ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
+ActiveRecord::Base.logger = nil
+ActiveRecord::Schema.verbose = false
+ActiveRecord::Schema.define do
+  create_table(:authors) { |t| t.string :name, null: false }
+  create_table :courses do |t|
+    t.string :title, null: false
+    t.references :author
+  end
+  create_table :enrollments do |t|
+    t.references :course
+    t.string :status
+  end
+end
+
+class Author < ActiveRecord::Base; has_many :courses; end
+class Enrollment < ActiveRecord::Base; belongs_to :course; end
+
+class Course < ActiveRecord::Base
+  belongs_to :author, optional: true
+  has_many :enrollments
+end
+
+AUTHORS = 200
+COURSES = 2_000
+PAGE = 25
+
+authors = Array.new(AUTHORS) { |i| Author.create!(name: "Author #{i}") }
+COURSES.times do |i|
+  c = Course.create!(title: format("Course %05d", i), author: authors[i % AUTHORS])
+  3.times { |j| c.enrollments.create!(status: j.zero? ? "active" : "cancelled") }
+end
+
+def count_queries
+  n = 0
+  sub = ActiveSupport::Notifications.subscribe("sql.active_record") do |*, payload|
+    n += 1 unless /SCHEMA|TRANSACTION/.match?(payload[:name].to_s)
+  end
+  yield
+  n
+ensure
+  ActiveSupport::Notifications.unsubscribe(sub)
+end
+
+def touch(courses)
+  courses.each do |c|
+    c.author&.name
+    c.enrollments.map(&:status)
+  end
+end
+
+scope = Course.where(id: Course.joins(:enrollments).where(enrollments: {status: "active"}).select(:id))
+
+puts "#{COURSES} courses / #{AUTHORS} authors / #{COURSES * 3} enrollments, page of #{PAGE}"
+puts "query is: courses(first: #{PAGE}) { author { name } enrollments { status } }"
+puts
+
+[["no preloading (the N+1 baseline)", -> { touch(scope.order(:id).limit(PAGE).to_a) }],
+  ["preload derived from the selection set", -> { touch(scope.order(:id).limit(PAGE).preload(:author, :enrollments).to_a) }]].each do |label, run|
+  run.call # warm
+  queries = count_queries { run.call }
+  ms = Benchmark.realtime { 5.times { run.call } } / 5 * 1000
+  puts format("  %-40s %4d queries   %6.1f ms", label, queries, ms)
+end