lighthouse-graphql 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5dd6b5839f6520df6489135c1a37382ce4f7889d136140f652443ad5a3cd1a81
-  data.tar.gz: 60fdb10b55abe72a1dc3df89705b904b424344e5bffa611e695a46fa8767ddc7
+  metadata.gz: eec6f789caae61cc196024238623ebc042783884cf8ebb53b19bb0e3f6d2cf3f
+  data.tar.gz: 61bdd5cef3df0d2c4ac9701501576c96a9c207d81b5f2f976d22e5fee14df9ba
 SHA512:
-  metadata.gz: 0f2aff4008f41238a6ebca9c598add10069e7f0c4c8c5578bc1041f3da50f36b859b9ce1c91a29576442562a42afca20845b8fb3704b19d374570381a3588262
-  data.tar.gz: b985fc24dfb2d0196c96f84cb0423d0b21e38659a0bc1cd4db13dc3818a8939fd2340006d85605cb5a50fde37f638d177ba90bf5af26e2cc3b9a3a0c2043986a
+  metadata.gz: 11c76fea28a691e29eea4910674585891907cefbeef72e9efc7519b8f812cd26f39d6895c90a46c91259b53c0dc64e3a0437add651d9eed07e5cd74807f245f2
+  data.tar.gz: 530507331c8736355448b67e1cf6ac354a0745351038fc9e7f8535df47f30299e2cf4ea203bee15482bc3fbcf3b8f9d0e5d7e72c61f263f0d9759016ae210a10

data/CHANGELOG.md

@@ -6,6 +6,215 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-10-18
+
+The schema is written by PHP Lighthouse's rules now: one entrypoint that imports
+the other files, every type defined once, and `extend type` to add to it.
+`@orderBy`, `@whereConditions` and `@whereHasConditions` generate and apply what
+PHP Lighthouse's do. In development, the IDE helper files are rewritten
+automatically.
+
+**Upgrading from 0.6:**
+
+1. Replace `config.sdl_folder = ...` with `config.schema_path = Rails.root.join('graphql/schema.graphql').to_s`
+   (that is the default), and `get_schema(sdl_folder:)` with `get_schema(schema_path:)`.
+2. Import every other file from `graphql/schema.graphql`. `#import **/*.graphql` imports
+   every file below its folder, which matches what was loaded before.
+3. Turn a second `type Query { ... }` (or `type Mutation`, or any type defined in two files)
+   into `extend type Query { ... }`. A type defined twice now fails the build.
+4. Write `orderBy:` arguments as `orderBy: _ @orderBy(columns: [...])`, and drop the
+   `OrderByClause` inputs and the `SortOrder` enum you declared. `order` is required in a
+   clause, and `{ field:, direction: }` clauses are no longer accepted.
+5. `SQLOperator` has PHP Lighthouse's values. Replace `NIN` with `NOT_IN`, and
+   `CONTAINS` / `STARTS_WITH` / `ENDS_WITH` with `LIKE` and a `%` pattern
+   (`value: "%Rails%"`, `"Rails%"`, `"%Rails"`). `@where(operator:)` keeps its operators.
+6. A `HAS` condition is on the related records' columns (`…HasCondition`, a `String`
+   column), as in PHP Lighthouse, no longer on the parent's column enum.
+
+### Added
+
+- **`#import`.** The schema's entrypoint, `config.schema_path`, imports other files by a
+  path relative to the importing file. Globs (`#import blog/*.graphql`) work too. An
+  imported file can import more files, and each file is read once.
+- **Type extensions merged as PHP Lighthouse merges them.** `extend type`, `input`,
+  `interface`, `enum`, `union` and `scalar` add to their definition, and the
+  directives on their fields work as on the type's own. `extend type Query` alone
+  defines `Query`.
+- **`@orderBy` generates its types.** `orderBy: _ @orderBy(columns: [...])` gets
+  `[<Type><Field><Arg>OrderByClause!]`, a column enum (`@enum(value:)` per column)
+  and `SortOrder`. `columnsEnum:` reuses an enum, and without columns the shared
+  `OrderByClause` takes any column.
+- **`@orderBy(relations:)`.** Clients order by `COUNT` of a relation, or by
+  `AVG`/`MIN`/`MAX`/`SUM` of one of its columns
+  (`{ posts: { aggregate: COUNT }, order: DESC }`). Records without related ones
+  are ordered too, and this works on batched relationship pages.
+- **`@orderBy(column:, direction:)` on a field.** It always orders the result, after
+  the client's clauses.
+- **`@whereConditions` and `@whereHasConditions`, as in PHP Lighthouse.** They have
+  PHP Lighthouse's `SQLOperator` (`LIKE`, `NOT_LIKE`, `NOT_IN`, `BETWEEN`,
+  `NOT_BETWEEN`, ...), and `HAS` with `operator:` / `amount:`
+  (`{ relation: "posts", operator: LT, amount: 1 }`: the records with none). The
+  `…Relation` / `…HasCondition` inputs filter on the related table, and
+  `handler:` names a class that applies the conditions instead.
+- **JSON columns.** `@whereConditions`, `@whereHasConditions` and `@orderBy` take a path into a
+  JSON column, `meta->author->name` or `meta->tags->0`, on PostgreSQL, MySQL and SQLite.
+  Numbers compare and sort as numbers, booleans compare as booleans, and `IS_NULL` holds
+  for a JSON `null` too.
+- **`config.ide_helper`.** `schema-directives.graphql` and
+  `programmatic-types.graphql` are rewritten on boot and on every reload. By
+  default this happens in development when the app has a `graphql.config.yml`.
+- `Contracts::FieldBuilder`, and `Contracts::ArgManipulator` as `ASTBuilder` calls
+  it, for custom directives.
+- The guide [docs/schema-organisation.md](docs/schema-organisation.md).
+
+### Changed
+
+- **Breaking:** The schema is read from `config.schema_path` and its imports, not from every
+  file in `config.sdl_folder`, which is removed. `lighthouse:install` takes `--schema-path`
+  instead of `--sdl-folder`.
+- **Breaking:** A type defined twice fails the build: "Duplicate definition X found when parsing
+  the schema", pointing at `extend`. PHP Lighthouse keeps the last definition.
+- **Breaking:** An argument typed `_` that no directive replaces fails the build. It used to
+  become a scalar.
+- **Breaking:** `@orderBy` clauses need `order`, take only `{ column:, order: }`, and a
+  column outside an enum must be an identifier.
+- **Breaking:** `SQLOperator`'s values are PHP Lighthouse's (see above).
+- **Breaking:** `@builder` and `@whereAuth` on a field apply after the argument directives,
+  as PHP Lighthouse's field builder directives do. An `order` a builder adds now breaks the
+  ties of the client's `orderBy` instead of preceding it. They also apply on relationship
+  fields (`@hasMany`, ...), where they used to be ignored, and on `@aggregate`, which now
+  gets the argument directives too.
+
+### Fixed
+
+- A schema that stops building while you edit it keeps its `programmatic-types.graphql`.
+  If there is none yet, the file declares the `_` placeholder alone, so the IDE never
+  reports `Unknown type "_"`. When an import is missing, the IDE helper reads every
+  `.graphql` file in the folder, as the IDE does.
+- `programmatic-types.graphql` no longer repeats the types `schema-directives.graphql`
+  defines (`Mixed`, `CanAction`, `PaginateType`, ...). graphql-js, which the VS Code
+  and JetBrains GraphQL plugins use, rejected the schema.
+- `@whereConditions` applied only to an argument named `where`. It and `@whereHasConditions`
+  are argument directives like the others now: any name, in SDL order.
+- An error in a `@whereConditions` value (an unknown relation or operator) is the client's
+  error. It used to be swallowed and leave the query unfiltered.
+
+## [0.6.0] - 2026-10-18
+
+Lighthouse now uses what the Rails app and graphql-ruby already have instead of settings and
+files of its own: the app's cache, its controllers' rate limiting, its ActiveStorage, and
+everything graphql-ruby's `graphql:install` writes, which `lighthouse:install` now builds on.
+Several defaults change.
+
+**Upgrading from 0.5:**
+
+1. Remove `config.cache_store =` and `config.upload_store =` from
+   `config/initializers/lighthouse.rb`. Configure the app's `config.cache_store` instead, and
+   `config.action_controller.cache_store` if rate limits should be counted somewhere else.
+2. `@throttle` counts per IP now. Add `by: "current_user.id"` where a field counted per user.
+3. Past a `@throttle` limit the request is answered with a 429, as Rails' `rate_limit` answers it.
+   To fail only the field, as before, give `with:` a controller method that raises a
+   `GraphQL::ExecutionError`.
+4. `@upload` checks `public:` against the ActiveStorage service. On a public service, add
+   `public: true`. Where `public: true` meets a private service, name a public one with `disk:`.
+5. `rails g lighthouse:query` and `lighthouse:mutation` are gone. Resolve a root field with a
+   method of `Types::QueryType` / `MutationType`, with `rails g graphql:mutation`, or with a
+   `Resolvers::` / `Mutations::` class written by hand, which convention still finds. An app
+   installed with 0.5 keeps working as it is: `AppSchema = get_schema(...)` is still supported.
+
+### Added
+
+- `@throttle(by:)`: who the client is, as `rate_limit`'s `by:`. It is a path in the context, read
+  as `@inject` reads one (`by: "current_user.id"`).
+- `@throttle(with:)`: a controller method to call past the limit, as `rate_limit`'s `with:`. One
+  that renders or redirects ends the request with its response, as a `before_action` that renders
+  does. One that returns lets the call through, and one that raises a `GraphQL::ExecutionError`
+  fails only the field.
+- `@throttle` refusals are instrumented as `rate_limit.action_controller`, with `rate_limit`'s
+  payload (`request`, `count`, `to`, `within`, `by`, `name`, `scope`, `cache_key`).
+- `base_types` takes graphql-ruby's code-first root types and Node interface. The SDL's root type
+  of a kind is built on `query_type:` / `mutation_type:` / `subscription_type:` (`Types::QueryType`),
+  so the `field`s the class declares (graphql-ruby's Relay `node` and `nodes`, what
+  `graphql:mutation` adds to `Types::MutationType`) are the schema's too, beside the SDL's, and
+  resolve as in graphql-ruby. With no such root type in the SDL, the class is the root. `node:`
+  (`Types::NodeType`) is the SDL's `Node` interface, which `@node` types implement, so
+  graphql-ruby's Relay and `@node` share one `Node`.
+- A root field with no resolving directive resolves with the method of its name on the root type
+  class, when the class includes `Lighthouse::GraphQL::Type` (`Query.latestPosts` →
+  `Types::QueryType#latest_posts`), before the conventional `Resolvers::` / `Mutations::` class.
+- A schema that implements graphql-ruby's `id_from_object` / `object_from_id` has one kind of
+  global id: `@globalId` encodes an object's own id with `id_from_object`, and decodes an
+  argument with `object_from_id`.
+- `lighthouse:install --subscriptions` writes `Subscriptions::BaseSubscription` and names it in
+  `base_types`; without it, the install writes no subscription base.
+
+### Changed
+
+- `@cache`, `@clearCache` and Automatic Persisted Queries use the app's `Rails.cache`
+  (`config.cache_store`), as PHP Lighthouse uses Laravel's cache. Outside Rails they use an
+  in-memory store.
+- `@throttle` is Rails' `rate_limit` on one field, and counts as it does:
+  - It counts in the controller's `cache_store` (`config.action_controller.cache_store`,
+    `Rails.cache` unless set), under `rate_limit`'s key, `rate-limit:<scope>:<name>:<by>`.
+    Counts kept under the old `lighthouse:throttle:` keys start over.
+  - `name:` is `rate_limit`'s. Each field counts under its own name (`Query.x`) by default, apart
+    from the controller's `rate_limit`, or together with it when both use the same name.
+    `prefix:` is `rate_limit`'s `scope:`, the controller's path by default.
+  - The client is its IP, as `rate_limit`'s default `by:`, no longer the signed-in user.
+  - Past the limit it does what `rate_limit` does by default: it raises
+    `ActionController::TooManyRequests`, which Rails answers with a 429
+    (`head :too_many_requests` on Rails 7.2). The field used to fail on its own, with the rest of
+    the operation answered; that remains the behavior without Action Pack.
+- `lighthouse:install` builds on graphql-ruby's `graphql:install`, run with whichever of its
+  options the app chose (`--relay`, `--batch`, `--skip-mutation-root-type`, `--schema`,
+  `--directory`, `--api`), or run first with its defaults when the app has none. It writes no
+  schema class of its own: graphql-ruby's `class AppSchema < GraphQL::Schema` becomes
+  `class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(options: { base_types: ... })`,
+  naming every class graphql-ruby wrote, and keeps the rest of the class (`use
+  GraphQL::Dataloader`, `max_depth`, `id_from_object`, ...). It takes out what Lighthouse replaces:
+  the `query(...)` / `mutation(...)` root types the SDL's are built on, the `resolve_type` stub,
+  and the example `test_field`. Its base object, interface, union and scalar include
+  `Lighthouse::GraphQL::Type`, so every type class is Lighthouse's without an `include` of its
+  own. With `--batch`, the schema uses `GraphQL::Dataloader` too. Its `Mutations::BaseMutation`, a
+  `RelayClassicMutation`, is kept; graphql-ruby's controller, unchanged since its install, becomes
+  one with `Lighthouse::GraphQL::Controller`. `Types::QueryType` and `MutationType` are kept.
+- An SDL Mutation field that declares its arguments one by one resolves by convention to a
+  `GraphQL::Schema::RelayClassicMutation` subclass as to a plain mutation, its arguments as
+  keywords. It used to fail looking for `input:`.
+- A subscriptions backend the app's schema class `use`s in its body
+  (`use GraphQL::Subscriptions::ActionCableSubscriptions`) delivers the SDL's Subscription fields.
+  graphql-ruby adds its subscription extension only to a root type of the class's own.
+- `Lighthouse::GraphQL::Controller` puts the controller in the context (`:lighthouse_controller`)
+  for `@throttle`. In development, an error Rails answers with a status of its own
+  (`config.action_dispatch.rescue_responses`, such as a 429 or a 404) now gets that status, as in
+  production, instead of being rendered as a JSON 500.
+- `@upload` stores files on the app's ActiveStorage only, with PHP Lighthouse's rules. `disk:`
+  names a service of `config/storage.yml` (`config.active_storage.service` without it), and
+  `path:` starts the blob's key. ActiveStorage sets visibility per service, so `public:` must now
+  agree with the service's: `public: true` on a private service, or the default `false` on a
+  public one, fails instead of being ignored. An unknown service, or a value that is not a file,
+  fails naming the argument. The file is rewound before it is stored, so a `@validator` may read
+  it first.
+- The `Upload` scalar's errors are PHP Lighthouse's: a value that is not a file names the GraphQL
+  multipart request specification and what was sent instead.
+
+### Removed
+
+- `Config.cache_store`: configure the app's `config.cache_store` instead, and
+  `config.action_controller.cache_store` (or a controller's `self.cache_store =`) for `@throttle`.
+  `Config.persisted_queries_store` stays, defaulting to `Rails.cache`.
+- `Config.upload_store`: to store files elsewhere, declare an ActiveStorage service and name it
+  with `@upload(disk:)`, as a Laravel app declares a disk.
+- `rails g lighthouse:query` and `lighthouse:mutation`: graphql-ruby has no resolver generator,
+  and `graphql:mutation` works in a Lighthouse app now. See Upgrading.
+
+### Fixed
+
+- On graphql-ruby 2.5, a schema using `@limit`, `@bind` or `@upload` without one of their optional
+  arguments did not build (`Expected value to not be null`): graphql 2.5 does not apply the default
+  of a non-null directive argument. Those arguments (`builder`, `column`, `with`, `optional`,
+  `path`, `public`) are nullable now, with the same defaults.
+
 ## [0.5.0] - 2026-10-18
 
 ### Added
@@ -461,7 +670,9 @@ had been running inside a private monorepo as a path gem before being extracted.
 - Config-driven extension seams: `Lighthouse.configure`, `resolver_namespaces`,
   `on_error`, and `DirectiveRegistry.register` for app-defined directives.
 
-[Unreleased]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.2.1...v0.3.0

data/README.md

@@ -72,34 +72,46 @@ It depends on `graphql ~> 2.5` and `activesupport`. For federation you also need
 On graphql 2.5, keep the `json` gem below 3: graphql 2.5 calls `JSON.generate`
 with an option json 3 removed (graphql 2.6 no longer does).
 
-Then let the generator set the app up:
+Then let the generators set the app up:
 
 ```shell
+bin/rails generate graphql:install      # graphql-ruby's, with the options you choose (optional)
 bin/rails generate lighthouse:install
 ```
 
-It runs graphql-ruby's own `graphql:install` for the base classes every graphql-ruby
-app has, then writes Lighthouse's on top: the initializer, a starter schema in
-`graphql/schema.graphql`, the `AppSchema` class built from it, a `GraphqlController`
-with its `POST /graphql` route, and a `graphql.config.yml` for your IDE. Run
+`lighthouse:install` builds on graphql-ruby's own install, and runs `graphql:install`
+with its defaults when the app has none. It adapts what graphql-ruby wrote: the
+schema class becomes Lighthouse's, built from the SDL on graphql-ruby's root types
+and base classes, and the rest of its body stays; the base object, interface, union
+and scalar include `Lighthouse::GraphQL::Type`; the controller serves the schema
+through `Lighthouse::GraphQL::Controller`. It adds the initializer, a starter schema
+in `graphql/schema.graphql` and a `graphql.config.yml` for your IDE. Run
 `bin/rails generate lighthouse:install --help` for its options (`--schema`,
-`--sdl-folder`, `--skip-controller`, `--skip-ide`), and see
+`--schema-path`, `--subscriptions`, `--skip-controller`, `--skip-ide`), and see
 [docs/generators.md](docs/generators.md) for every generator, graphql-ruby's included.
 
+### Schema files
+
+As in PHP Lighthouse, the schema is read from one entrypoint,
+`graphql/schema.graphql`, which `#import`s the other files
+(`#import user.graphql`, `#import blog/*.graphql`). A type is defined once, and the
+other files add to it with `extend type Query`. See
+[docs/schema-organisation.md](docs/schema-organisation.md).
+
 ### IDE support
 
 Lighthouse's directives and the types it generates (Paginator/Connection types,
-`whereConditions` inputs, …) are defined in Ruby, so your IDE can't see them in
-your `.graphql` files. Write them out for it:
+`@whereConditions` and `@orderBy` inputs, the `_` placeholder, …) are defined in
+Ruby, so your IDE can't see them in your `.graphql` files. Lighthouse writes them
+to `schema-directives.graphql` and `programmatic-types.graphql` in the app root:
+in development on every boot and reload, or with:
 
 ```shell
 bin/rails lighthouse:ide_helper
 ```
 
-This writes `schema-directives.graphql` and `programmatic-types.graphql` to the app
-root; the generated `graphql.config.yml` already points the GraphQL plugins for
-JetBrains IDEs and VS Code at them. Rerun it after changing your schema or
-registering a directive. See [docs/getting-started.md](docs/getting-started.md#ide-support).
+The generated `graphql.config.yml` already points the GraphQL plugins for
+JetBrains IDEs and VS Code at them. See [docs/getting-started.md](docs/getting-started.md#ide-support).
 
 ## Quick start
 
@@ -123,22 +135,26 @@ Prefer to wire it by hand? These are the steps the generator performs.
    }
    ```
 
-2. **Build the schema** (typically in `app/graphql/your_schema.rb`):
+2. **Build the schema**: graphql-ruby's schema class (`app/graphql/app_schema.rb`),
+   inheriting from the schema Lighthouse builds instead of `GraphQL::Schema`:
 
    ```ruby
-   require 'lighthouse-graphql'
-
-   AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
-     sdl_folder: Rails.root.join('graphql').to_s,
+   class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(
      options: {
-       base_types: {
-         resolver: Resolvers::BaseResolver,              # graphql-ruby's base classes, which
-         mutation: Mutations::BaseMutation,              # rails g lighthouse:install has graphql-ruby write
-         subscription: Subscriptions::BaseSubscription
-         # object: Types::BaseObject, ...
+       base_types: {                                     # the classes graphql-ruby's install writes
+         query_type: Types::QueryType,
+         mutation_type: Types::MutationType,
+         node: Types::NodeType,
+         resolver: Resolvers::BaseResolver,
+         mutation: Mutations::BaseMutation,
+         object: Types::BaseObject
+         # interface: Types::BaseInterface, union:, scalar:, enum:, input_object: ...
        }
      }
    )
+     use GraphQL::Dataloader   # Lighthouse batches relationships through it
+     max_depth(15)
+   end
    ```
 
 3. **Execute** it from your controller exactly like any graphql-ruby schema:

data/docs/best-practices.md

@@ -92,7 +92,9 @@ app's GraphQL setup easy to find.
 
 ## Split your SDL
 
-Lighthouse concatenates every `*.graphql` file under your `sdl_folder`. Organize
-by domain (`users.graphql`, `orders.graphql`, …) and keep a small
-`_directives.graphql` only for directives you declare yourself (built-ins are
-injected automatically).
+Lighthouse reads `graphql/schema.graphql` and the files it `#import`s
+([schema-organisation.md](schema-organisation.md)). Organize
+by domain (`users.graphql`, `orders.graphql`, …), each with its types and the
+fields it adds with `extend type Query` / `extend type Mutation`. Keep a small
+`directives.graphql`, imported too, only for directives you declare yourself
+(built-ins are injected automatically).

data/docs/caching.md

@@ -41,9 +41,10 @@ such as a Relay connection object, is reported through
 [`on_error`](configuration.md#on_error) and returned uncached. So cache list
 fields, not connection fields.
 
-The store is [`Config.cache_store`](configuration.md#cache_store), `Rails.cache`
-by default. Note that Rails uses a `:null_store` in development and test unless
-you enable caching (`bin/rails dev:cache`).
+The store is your app's cache, `Rails.cache` (`config.cache_store`), as PHP
+Lighthouse uses Laravel's: Lighthouse keeps no store of its own. Note that Rails
+uses a `:null_store` in development and test unless you enable caching
+(`bin/rails dev:cache`).
 
 A cached value is still authorized and validated on every request: `@cache` runs
 inside `@guard`, `@can*` and `@validator`, never around them.

data/docs/configuration.md

@@ -9,7 +9,7 @@ reusable and publishable.
 require 'lighthouse-graphql'
 
 Lighthouse.configure do |config|
-  config.sdl_folder = Rails.root.join('graphql').to_s
+  config.schema_path = Rails.root.join('graphql/schema.graphql').to_s
   config.namespaces = { queries: ['Resolvers'], mutations: ['Mutations'] }
   config.resolver_namespaces = ['App::Graphql']
   config.on_error = ->(error, _context) { Rails.error.report(error) }
@@ -18,11 +18,25 @@ end
 
 ## Options
 
-### `sdl_folder`
+### `schema_path`
 
-Where Lighthouse loads `*.graphql` files from. Defaults to `RAILS_ROOT/graphql`
-in a Rails app, `nil` otherwise (pass SDL explicitly via `SchemaFactory` when not
-on Rails).
+The schema's entrypoint, as PHP Lighthouse's `schema_path`. Lighthouse reads
+this file and the files it imports (`#import user.graphql`, `#import blog/*.graphql`).
+A type is defined once, and other files add to it with `extend type`. See
+[schema-organisation.md](schema-organisation.md). Defaults to
+`RAILS_ROOT/graphql/schema.graphql` in a Rails app, and `nil` otherwise. Outside
+Rails, pass the path, or the SDL itself (`SchemaFactory.build_base_schema(sdl:)`).
+
+`get_schema(schema_path: ...)` overrides it for one schema.
+
+### `ide_helper`
+
+Rewrite `schema-directives.graphql` and `programmatic-types.graphql` in the
+app's root on boot and on every reload, for the IDE
+([schema-organisation.md](schema-organisation.md#ide-support)). A file whose
+content is unchanged is left alone. `nil` (the default) turns it on in
+development when the app has a `graphql.config.yml`, which `lighthouse:install`
+writes. Set `true` or `false` to decide yourself.
 
 ### `namespaces`
 
@@ -70,15 +84,6 @@ reporter in production:
 config.on_error = ->(error, _ctx) { Sentry.capture_exception(error) }
 ```
 
-### `cache_store`
-
-The store behind [`@cache` / `@clearCache`](caching.md). Defaults to
-`Rails.cache` (an in-memory store outside Rails).
-
-```ruby
-config.cache_store = ActiveSupport::Cache::RedisCacheStore.new(url: ENV['REDIS_URL'])
-```
-
 ### `pagination_default_count`, `pagination_max_count`
 
 Defaults for paginated fields: the `first` used when a client leaves it out (so
@@ -99,7 +104,7 @@ Options for large schemas and high traffic, all off by default. See
 config.schema_cache = Rails.env.production?            # cache the built schema in tmp/cache
 config.watch_sdl = Rails.env.development?              # reload when a .graphql file changes
 config.persisted_queries = true                        # Apollo's Automatic Persisted Queries
-config.persisted_queries_store = Rails.cache           # where APQ keeps queries (default: cache_store)
+config.persisted_queries_store = Rails.cache           # where APQ keeps queries (default: Rails.cache)
 config.persisted_queries_ttl = 1.week.to_i             # how long they live there
 config.persisted_queries_manifest = Rails.root.join('persisted-queries.json')  # trusted operations
 config.persisted_queries_only = Rails.env.production?  # run nothing else
@@ -128,17 +133,6 @@ returning `[type, id]`. Defaults to `Lighthouse::GraphQL::GlobalId`, the base64
 config.global_id = SignedGlobalIds
 ```
 
-### `upload_store`
-
-Stores the file an [`@upload`](uploads.md) argument carries: any object with
-`call(file, disk:, path:, public:)`, whose return value the argument then holds.
-Defaults to `Lighthouse::GraphQL::UploadStore`, which makes an ActiveStorage blob and
-returns its signed id.
-
-```ruby
-config.upload_store = ->(file, path: '/', **) { S3Uploader.put(file, prefix: path) }
-```
-
 ### `queue_broadcasts`, `broadcast_queue`
 
 Whether [`@broadcast`](directives.md#broadcast) triggers its subscription in an

data/docs/custom-directives.md

@@ -29,7 +29,8 @@ Include the marker module(s) your directive fulfils:
 | `Contracts::FieldResolver` | provide a field's resolver | `#define_resolver(type)` (or `#resolve_field`) |
 | `Contracts::FieldMiddleware` | wrap an existing resolver (e.g. `@auth`) | `#wrap_resolver(next)` |
 | `Contracts::FieldManipulator` | reshape the schema for a field | `manipulate_field_definition(...)` |
-| `Contracts::ArgManipulator` | reshape the schema for an argument | `manipulate_argument_definition(...)` |
+| `Contracts::ArgManipulator` | reshape the schema for an argument, as `@orderBy` and `@whereConditions` generate their types | `#manipulate_arg_definition(document_ast, field_node, type_node)` returning the argument node |
+| `Contracts::FieldBuilder` | constrain a field's query, whatever the client sends | `#handle_field_builder(relation)` |
 | `Contracts::ArgBuilder` | compose a query constraint from an argument | `#handle_builder(relation, value)` |
 
 A directive class also answers two class-level questions: its name and its SDL

data/docs/directives.md

@@ -78,7 +78,7 @@ type Query {
 ```
 
 - **The query.** It is the model's (`model:`, else the return type), narrowed by
-  `scopes:`, [`@builder`](#builder) and the field's argument filters. On a nested
+  `scopes:`, the field's argument filters and [`@builder`](#builder). On a nested
   field it pages the parent's association of the same name: `User.posts @paginate`
   pages the user's posts.
 - **`first`.** It defaults to `defaultCount`, else
@@ -283,16 +283,23 @@ type PostQueries {
 
 ### `@throttle`
 
-Rate-limits a field per client: at most `maxAttempts` calls every `decayMinutes`
-(default 60 a minute), counted in [`cache_store`](configuration.md#cache_store). A
-client is the signed-in user, else the context's `:remote_ip`, which the controller
-concern sets. Past the limit the field fails with `Rate limit for Query.x exceeded.
-Try again later.` before anything else runs. `name:` makes fields count together,
-`prefix:` separates groups.
+Rails' `rate_limit` on one field: at most `maxAttempts` calls (its `to:`) every
+`decayMinutes` (its `within:`, default 60 a minute), counted before anything else runs.
+It takes `rate_limit`'s options, and counts as `rate_limit` does: in the controller's
+`cache_store`, under the same key, and instrumented as `rate_limit.action_controller`.
+See [security.md](security.md#rate-limiting).
+
+| Argument | `rate_limit`'s | Default |
+| --- | --- | --- |
+| `by:` | `by:`, who the client is: a path in the context, as [`@inject`](resolvers.md#spread-and-inject)'s (`"current_user.id"`) | the client's IP |
+| `with:` | `with:`, the controller's method to call past the limit | `rate_limit`'s: a 429 (it raises `ActionController::TooManyRequests`) |
+| `name:` | `name:`; fields, and the controller's own `rate_limit`, of the same name count together | the field (`Query.x`) |
+| `prefix:` | `scope:` | the controller's path |
 
 ```graphql
 type Mutation {
   login(email: String!, password: String!): User @throttle(maxAttempts: 5)
+  createTag(name: String!): Tag! @throttle(maxAttempts: 20, by: "current_user.id", with: "too_many_requests") @guard @create
 }
 ```
 
@@ -449,7 +456,12 @@ Builders are looked up in their own namespace, `Builders::` (app/graphql/builder
 `class:` with `method:` (default `call`), or PHP Lighthouse's `method: "Class@method"`.
 
 On a field, the method gets `(relation, args, context)`, or the directive's
-`value:` in place of the arguments. On an argument or an input field, it gets
+`value:` in place of the arguments. As in PHP Lighthouse, a field's `@builder`
+(with `@whereAuth` and `@orderBy(column:)`) applies after the argument
+directives, in SDL order. An `order` it adds therefore breaks the ties of the
+client's `orderBy`. It applies on every field that queries records: `@all`,
+`@paginate`, `@find`, `@first`, `@count`, `@aggregate`, the relationship
+directives and `resolve_info.enhance_builder`. On an argument or an input field, it gets
 `(relation, value, context)` whenever the client sends that argument, an explicit
 `null` included, and not when it is left out:
 
@@ -511,7 +523,7 @@ Full guide: [filtering-and-ordering.md](filtering-and-ordering.md).
 | `@whereBetween` / `@whereNotBetween` | `column BETWEEN` / `NOT BETWEEN` the input's two fields, in order |
 | `@whereJsonContains` | a JSON column contains the value (every value of a list); `key: "meta->tags"` points into it |
 | `@scope(name:)` | calls the model scope with the value (`name:` defaults to the argument's) |
-| `@orderBy` | sort by one or more columns |
+| `@orderBy` | sort by the client's clauses (columns, relations' aggregates); on a field, a fixed order |
 
 ```graphql
 type Query {
@@ -519,7 +531,7 @@ type Query {
     status: String @eq
     nameSearch: String @like
     minAge: Int @where(operator: "GTE", key: "age")
-    orderBy: [OrderByClause!] @orderBy
+    orderBy: _ @orderBy(columns: ["name", "created_at"])
   ): [User!]! @all
 }
 ```
@@ -561,18 +573,71 @@ parents it would cut them all together, as PHP Lighthouse warns. PHP Lighthouse
 also allows `@limit` on the field itself, where it only marks the field the argument
 limits; it is accepted there and changes nothing.
 
+### `@orderBy`
+
+```graphql
+directive @orderBy(
+  columns: [String!]               # argument: the columns the client may order by
+  columnsEnum: String              # argument: an enum of them instead (one of the two)
+  relations: [OrderByRelation!]    # argument: { relation:, columns:, columnsEnum: } to order by an aggregate
+  column: String                   # field: the column to order by
+  direction: OrderByDirection = ASC
+) on ARGUMENT_DEFINITION | FIELD_DEFINITION
+```
+
+On an argument written as `_`, Lighthouse generates the clause input
+(`<Type><Field><Arg>OrderByClause`, or `…RelationOrderByClause` with
+`relations:`) and the column enum. Without `columns:`, `columnsEnum:` or
+`relations:`, the argument takes the shared `OrderByClause`, which allows any
+column. A column can be a JSON path, `meta->rank`, in `@orderBy` and in
+`@whereConditions` ([JSON columns](filtering-and-ordering.md#json-columns)). On a field, `@orderBy(column:, direction:)` orders the result after
+the client's clauses.
+
+```graphql
+type Query {
+  posts(orderBy: _ @orderBy(columns: ["posted_at", "title"])): [Post!]! @all
+  users(orderBy: _ @orderBy(relations: [{ relation: "posts" }])): [User!]! @all
+  latestPosts: [Post!]! @all @orderBy(column: "posted_at", direction: DESC)
+}
+
+# { posts(orderBy: [{ column: POSTED_AT, order: DESC }]) { title } }
+# { users(orderBy: [{ posts: { aggregate: COUNT }, order: DESC }]) { name } }
+```
+
+Guide: [filtering-and-ordering.md](filtering-and-ordering.md#ordering).
+
 ### `@whereConditions` / `@whereHasConditions`
 
-Give clients a structured, dynamic `WHERE` builder (AND/OR/operators, and HAS for
-related records). Lighthouse generates the input and enum types for you. See
-[filtering-and-ordering.md](filtering-and-ordering.md#complex-where-conditions).
+```graphql
+directive @whereConditions(columns: [String!], columnsEnum: String, handler: String) on ARGUMENT_DEFINITION
+directive @whereHasConditions(relation: String, columns: [String!], columnsEnum: String, handler: String) on ARGUMENT_DEFINITION
+```
+
+These give clients a dynamic `WHERE` builder, with conditions joined by `AND`
+and `OR`, PHP Lighthouse's `SQLOperator` operators, and `HAS` checks on
+relations. On an argument written as `_`, Lighthouse generates the input
+(`<Type><Field><Arg>WhereConditions` / `…WhereHasConditions`), its `…Relation`
+and `…HasCondition` inputs, and the column enum. Without `columns:` or
+`columnsEnum:`, the argument takes the shared `WhereConditions`, which allows
+any column.
+
+`@whereHasConditions` keeps the records with a related record matching the
+conditions. The relation is `relation:`, or the argument's name without `has`.
+`handler:` names a `Builders::` class whose `call(relation, conditions)` applies
+the conditions instead.
 
 ```graphql
 type Query {
   people(where: _ @whereConditions(columns: ["age", "type"])): [Person!]! @all
+  users(hasPosts: _ @whereHasConditions(columns: ["title"])): [User!]! @all
 }
+
+# { people(where: { AND: [{ column: AGE, operator: GT, value: 37 }, { column: TYPE, value: "Actor" }] }) { name } }
+# { users(hasPosts: { column: TITLE, operator: LIKE, value: "%Rails%" }) { name } }
 ```
 
+Guide: [filtering-and-ordering.md](filtering-and-ordering.md#complex-where-conditions).
+
 ### `@trim`, `@hash`, `@drop`, `@bind` and `@upload`
 
 Rewrite an argument's or input field's value before the field resolves, in the
@@ -584,7 +649,7 @@ order the SDL lists them:
 | `@drop` | nothing: the argument is removed |
 | `@hash` | the value hashed with BCrypt (the `bcrypt` gem, as `has_secure_password`) |
 | `@bind(class:, column: "id", with: [], optional: false)` | the model record(s) the value identifies, eager-loading `with`; or what a class's `call(value, context)` returns |
-| `@upload(disk:, path: "/")` | what [`upload_store`](configuration.md#upload_store) answers for the uploaded file: the signed id of an ActiveStorage blob, by default ([uploads.md](uploads.md)) |
+| `@upload(disk:, path: "/", public: false)` | the signed id of the ActiveStorage blob the file was stored as, on the app's service `disk` names ([uploads.md](uploads.md)) |
 
 ```graphql
 type Mutation {

data/docs/federation.md

@@ -29,7 +29,7 @@ class Types::BaseObject < GraphQL::Schema::Object
 end
 
 BaseAppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
-  sdl_folder: Rails.root.join('graphql').to_s,
+  schema_path: Rails.root.join('graphql/schema.graphql').to_s,
   options: { federation: true, base_types: { object: Types::BaseObject, resolver: Resolvers::BaseResolver } }
 )