lighthouse-graphql 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a15bb4d92716a08d5d248c5155b9cf336407a7988fed6e00c825b07bea4a206b
-  data.tar.gz: 421fca84187c5030f38c2cdd07ed26f9909747944f788cfd9662e67b6e322e2d
+  metadata.gz: 5dd6b5839f6520df6489135c1a37382ce4f7889d136140f652443ad5a3cd1a81
+  data.tar.gz: 60fdb10b55abe72a1dc3df89705b904b424344e5bffa611e695a46fa8767ddc7
 SHA512:
-  metadata.gz: 388112925823baa63d0a7a4436bb1df4511f4a4c13b01001dd72b351156b78982ca4eab136a131c9c25b997915bff26099fa2a485bc4df74bfef390138e37c3a
-  data.tar.gz: e2f90e9654cfcdc2d26e084f68476ac59f56eb708683b3b4817cfc41006843363feb0f9a08b838bdcdd888395bc8f13ae29394d28b0bc37566c26dad63657cac
+  metadata.gz: 0f2aff4008f41238a6ebca9c598add10069e7f0c4c8c5578bc1041f3da50f36b859b9ce1c91a29576442562a42afca20845b8fb3704b19d374570381a3588262
+  data.tar.gz: b985fc24dfb2d0196c96f84cb0423d0b21e38659a0bc1cd4db13dc3818a8939fd2340006d85605cb5a50fde37f638d177ba90bf5af26e2cc3b9a3a0c2043986a

data/CHANGELOG.md

@@ -6,6 +6,143 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-18
+
+### Added
+
+- `Lighthouse::GraphQL::Type`, a concern that hands a graphql-ruby type class to Lighthouse, in
+  graphql-ruby's `app/graphql/types` structure. A field of an object type with no resolving
+  directive resolves with the method of its snake_case name on `Types::<Type>Type`, when that class
+  includes the concern and defines it (`Post.readingTime` → `Types::PostType#reading_time`). As in
+  graphql-ruby, the method has `object` (the parent), `context`, the `dataload*` helpers, and the
+  field's arguments as keywords. The SDL still declares the fields; the ones the class does not
+  define are read off the object as before. A type class that does not include the concern is left
+  alone. The class is looked up in the new `types` namespace (default `['Types']`), and must inherit
+  from `base_types[:object]` when one is given.
+- `@model(class:)`, as PHP Lighthouse's: maps an object type to the ActiveRecord model of another
+  name. Every directive taking `model:` (`@all`, `@find`, `@paginate`, `@create`, `@update`, the
+  `@can*` family...) on a field returning the type gets it, unless it names its own; unions,
+  interfaces and `@node` resolve the model's records to the type; the schema does not build unless
+  it is a model; and a type class's methods only run on its records (another parent is reported
+  through `on_error`).
+- Unions and interfaces resolve each value to its object type as PHP Lighthouse does: a Hash's
+  `__typename`, else the type named after the value's class or a superclass (STI), else the type
+  whose `@model` names its model. A union's type class (`Types::SearchResultType` including the
+  concern) can take over with graphql-ruby's `self.resolve_type(object, context)`, an interface's
+  with `definition_methods { def resolve_type }`, and `@union(resolveType:)` /
+  `@interface(resolveType:)` name a class in the SDL. A value nothing resolves, or one resolved
+  outside the union, raises `Lighthouse::DefinitionError` naming the ways out.
+- Custom scalars read and write their values through their class: `Types::DateTimeType` (a
+  `GraphQL::Schema::Scalar` including the concern), or the class `@scalar(class:)` names, with
+  graphql-ruby's `coerce_input` / `coerce_result`. A `GraphQL::CoercionError` makes the argument
+  invalid with its message. A scalar with no class passes its values through, as before.
+- `@method` passes the field's arguments to the method: as snake_case keywords when it takes
+  keywords, otherwise positionally in SDL order, as PHP Lighthouse does.
+- `base_types[:union]`, `[:interface]` and `[:scalar]`, like `[:object]`, are the bases the type
+  classes of their kind must inherit from.
+- `docs/types.md`: unions, interfaces and scalars.
+- `@field(resolver: "Class@method")`, as PHP Lighthouse's: the method replaces `call` on a plain
+  class (as a class method, else an instance method), or `resolve` on a resolver class, whose
+  `ready?` / `authorized?` still run.
+- `ResolveInfo`, PHP Lighthouse's `$resolveInfo`: `resolve_info` in `Resolvers::` / `Mutations::`
+  classes, classes `@field` names and type class methods, and a fourth argument for a plain callable
+  that takes one. It has the field, its parent type, object, arguments, context and path, and
+  `enhance_builder(relation, scopes: [])`, which applies the field's `@builder` classes and argument
+  directives (`@eq`, `@where`, `@orderBy`, `@whereConditions`, ...) to a query the class builds.
+- `@with(relation:, scopes:)` and `@withCount(relation:, scopes:)` eager-load a relation, or its
+  count (kept on the parent as `<relation>_count`), before the field resolves; `@lazyLoad(relations:)`
+  eager-loads relations of the records a field returns. All three load across every parent in the
+  response at once, through the Dataloader, and take nested relations (`"posts.comments"`).
+- Relay global object identification: `@globalId` encodes a field (base64 of `Type:id`) and decodes
+  an argument or input field (`decode: ARRAY | TYPE | ID`); `@node` makes a type implement `Node` and
+  adds `Query.node(id:)`, which finds the record through the type's model or `@node(resolver:)`. The
+  new `global_id` setting takes your own encoder. `docs/relay.md`.
+- A union's or interface's class may answer `[type, value]`, as graphql-ruby allows.
+- File uploads: the `Upload` scalar (Lighthouse's own for `scalar Upload`), the GraphQL multipart
+  request specification in `Lighthouse::GraphQL::Controller`, and `@upload(disk:, path:)`, which
+  stores the file through the new `upload_store` setting (an ActiveStorage blob by default) and
+  passes its signed id. `docs/uploads.md`.
+- Filters: `@whereNull`, `@whereNotNull`, `@whereBetween`, `@whereNotBetween`, `@whereJsonContains`
+  (PostgreSQL, MySQL, SQLite), `@scope`, `@nest` (the filters of an input's fields) and `@limit`
+  (a LIMIT, or a per-parent cut of a relation's records); `@whereAuth(relation:)` keeps the
+  signed-in user's records.
+- Argument directives: `@trim`, `@drop`, `@hash` (BCrypt) and `@bind(class:)`, which replaces an id
+  with its record(s) or fails validation. Rewriting ones (`@globalId`, `@trim`, `@drop`) run before
+  `@guard`, `@can*` and `@validator`; effectful ones (`@hash`, `@bind`, `@upload`) after them.
+- `@builder` on an argument or input field, as PHP Lighthouse's: the method gets the argument's
+  value whenever the client sends it, `null` included. `method: "Class@method"` names the builder
+  without `class:`, and `value:` on a field passes a fixed value in place of the arguments.
+- `@limit(builder: true)` puts the LIMIT on the field's query; `@limit` must be on an `Int` argument,
+  and is accepted on the field itself, as PHP Lighthouse allows.
+- `@hasManyThrough` and `@hasOneThrough`, PHP Lighthouse's names, as aliases of `@hasMany` and
+  `@hasOne`, which resolve `has_many` / `has_one :through`.
+- `ResolveInfo#lookahead`: graphql-ruby's Lookahead for a field resolved by a class (a `Resolvers::`
+  class, `@field`, a type class method). It never reaches the arguments, so `@cache` keys are unchanged.
+- `@throttle` logs a warning when the cache store is a `:null_store`, which counts nothing.
+- `@enum(value:)` for an enum value's internal value; `@namespaced` to group fields; `@throttle` to
+  rate-limit a field per user or IP (the controller concern now puts `:remote_ip` in the context);
+  `@async` to run a mutation in an ActiveJob and answer `true`; `@hide(env:)` / `@show(env:)` to leave
+  fields out by environment (the schema cache key now includes it).
+
+### Changed
+
+- Generators build on graphql-ruby's instead of copying them. `lighthouse:install` runs
+  `graphql:install --no-relay --skip-graphiql --skip-query-logs` for the base classes every
+  graphql-ruby app has (`Types::Base*`, `Resolvers::BaseResolver`, `Mutations::BaseMutation`), then
+  replaces what it wrote that an SDL-first app does differently: the schema class (built from the
+  SDL, naming every base in `base_types`), the controller, no `Types::QueryType` /
+  `MutationType`, and a `BaseMutation` that is a `GraphQL::Schema::Mutation`. It writes
+  `Subscriptions::BaseSubscription` itself, graphql-ruby having none. Files the app had are kept.
+- `docs/generators.md`: every generator, and which of graphql-ruby's fit a Lighthouse app
+  (`graphql:object`, `:scalar`, `:union`, `:interface` for type classes; `graphql:mutation` and
+  `graphql:detailed_trace` not as they are).
+
+- `@field(resolver:)` on a field of a type other than `Query` and `Mutation` looks the class up in
+  the resolvers namespace first, nested names included: `@field(resolver: "Posts::TagsCount")`
+  resolves to `Resolvers::Posts::TagsCount`. Then it tries `resolver_namespaces`, as before, so
+  full names and classes outside `Resolvers::` resolve as they did. A class `Resolvers::X` now
+  wins over one that `resolver_namespaces` would find for the same name.
+
+### Fixed
+
+- A wrapping directive (`@globalId`, `@guard`, `@cache`, ...) on a field of a type whose objects are
+  Hashes read nothing: the wrapped default reader only called methods. It now reads the Hash's
+  keys, as the default reader does.
+
+- A field returning a union or an interface no longer raises `undefined method 'resolve_type' for
+  an instance of Proc`. Lighthouse's field dispatcher replaced the schema's default resolve with a
+  Proc, which graphql-ruby also asks for `resolve_type` and scalar coercion; it now hands both on.
+
+- `@field(resolver:)` on a `Query` or `Mutation` field finds a nested name in the resolvers /
+  mutations namespaces, as documented: `"Feeds::Home"` resolves to `Resolvers::Feeds::Home`,
+  then to `Feeds::Home`. It used to try only `Feeds::Home`, so the field resolved to `null`.
+  The field's `complexity` is looked up the same way.
+
+### Documentation
+
+- `docs/resolvers.md`: fields of types other than `Query` and `Mutation` resolved with `@field`,
+  whose class receives the parent record as `object`. The example app resolves `Post.tagsCount`
+  (batched through the dataloader), `Post.excerpt(length:)` and `Query.popularTags` this way.
+  It resolves `Post.readingTime` and the `ReadingTime` type, which is not a model, with
+  `Types::PostType` and `Types::ReadingTimeType`, `Query.search` (a union of `Post` and `User`)
+  and `Query.latestActivity` (an `Authored` interface) by the default, `DateTime` with
+  `Types::DateTimeType`, and `Post.summary(words:)` with `@method`. `Tag` is a Relay node with
+  global ids; `User.latestPostTitle` uses `@with`, `Tag.usage` `@withCount`, `User.posts`
+  `@lazyLoad`, `Query.counts` `@field(resolver: "Statistics@counts")`, and `Query.myPosts`
+  `resolve_info.enhance_builder`. `Mutation.updateAvatar` takes a multipart upload with `@upload`
+  (the example now loads ActiveStorage). `Mutation.schedulePublish` is `@async` on Solid Queue,
+  `Query.searchPosts` is `@throttle`d, and `Query.posts` filters `metadata` with `@whereJsonContains`;
+  the example's suite runs on PostgreSQL and MySQL too (`DATABASE_URL`, a new CI job), with Redis.
+
+### Removed
+
+- `rails g lighthouse:type`: it was graphql-ruby's `graphql:object` (and `:scalar`, `:union`,
+  `:interface`) with an `include`. Generate the class with graphql-ruby, then add
+  `include Lighthouse::GraphQL::Type`.
+- `lighthouse:query` and `lighthouse:mutation` no longer write `Resolvers::BaseResolver` /
+  `Mutations::BaseMutation` when they are missing: graphql-ruby's install writes them, which
+  `lighthouse:install` runs. They say so instead.
+
 ## [0.4.0] - 2026-10-17
 
 ### Added
@@ -324,7 +461,8 @@ 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.4.0...HEAD
+[Unreleased]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.5.0...HEAD
+[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
 [0.2.1]: https://github.com/Vaz-Innovation/lighthouse-graphql/compare/v0.2.0...v0.2.1

data/README.md

@@ -78,10 +78,13 @@ Then let the generator set the app up:
 bin/rails generate lighthouse:install
 ```
 
-It creates the initializer, a starter schema in `graphql/schema.graphql`, the
-`AppSchema` class, a `GraphqlController` with its `POST /graphql` route, 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`).
+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
+`bin/rails generate lighthouse:install --help` for its options (`--schema`,
+`--sdl-folder`, `--skip-controller`, `--skip-ide`), and see
+[docs/generators.md](docs/generators.md) for every generator, graphql-ruby's included.
 
 ### IDE support
 
@@ -130,7 +133,7 @@ Prefer to wire it by hand? These are the steps the generator performs.
      options: {
        base_types: {
          resolver: Resolvers::BaseResolver,              # graphql-ruby's base classes, which
-         mutation: Mutations::BaseMutation,              # rails g lighthouse:install writes
+         mutation: Mutations::BaseMutation,              # rails g lighthouse:install has graphql-ruby write
          subscription: Subscriptions::BaseSubscription
          # object: Types::BaseObject, ...
        }

data/docs/configuration.md

@@ -38,6 +38,7 @@ different contracts, so they live apart ([resolvers.md](resolvers.md)):
 | `events` | `['Events']` | Classes `@event(dispatch:)` names ([events.md](events.md)) |
 | `subscriptions` | `['Subscriptions']` | `Subscriptions::BaseSubscription` classes (a `GraphQL::Schema::Subscription`; the base includes `Lighthouse::GraphQL::Subscription`) for `Subscription` fields, and `@subscription(class:)` ([subscriptions.md](subscriptions.md)) |
 | `analyzers` | `['Analyzers']` | `GraphQL::Analysis::Analyzer` classes (optionally including `Lighthouse::GraphQL::ComplexityAnalyzer`) that `@complexity(resolver:)` names ([security.md](security.md)) |
+| `types` | `['Types']` | `Types::<Name>Type` classes including `Lighthouse::GraphQL::Type`: an object type's, whose methods resolve the fields of the SDL type `<Name>` ([resolvers.md](resolvers.md#type-classes)); a union's or interface's, which picks its values' types; a scalar's, which coerces its values ([types.md](types.md)). Also where `@union`, `@interface` and `@scalar` look classes up |
 
 ```ruby
 config.namespaces = { queries: ['Api::Resolvers'] }   # the other kinds keep their defaults
@@ -47,8 +48,9 @@ config.namespaces = { queries: ['Api::Resolvers'] }   # the other kinds keep the
 
 An ordered list of namespaces tried for **models** named by a directive
 (`@all(model: "User")`) and for `@field(resolver:)` on types other than `Query`
-and `Mutation`. Fully-qualified names (containing `::`) are used as-is. Defaults
-to `['App::Graphql']`.
+and `Mutation`, after the resolvers namespace
+([resolvers.md](resolvers.md#fields-of-other-types)). Fully-qualified names
+(containing `::`) are used as-is. Defaults to `['App::Graphql']`.
 
 ```ruby
 config.resolver_namespaces = ['App::Graphql', 'Resolvers']
@@ -115,6 +117,28 @@ initializer.
 config.convert_empty_strings_to_null = true
 ```
 
+### `global_id`
+
+Encodes and decodes Relay global ids for [`@globalId` and `@node`](relay.md): any
+object with `encode(type, id)` returning the global id, and `decode(global_id)`
+returning `[type, id]`. Defaults to `Lighthouse::GraphQL::GlobalId`, the base64 of
+`Type:id`, as PHP Lighthouse's.
+
+```ruby
+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/directives.md

@@ -129,6 +129,7 @@ See [relationships.md](relationships.md) for the full guide.
 | `@belongsTo` | inverse of has-one/has-many |
 | `@belongsToMany` | many-to-many: a list, or paginated with `type:` |
 | `@morphTo`, `@morphOne`, `@morphMany`, `@morphToMany` | the polymorphic variants |
+| `@hasManyThrough`, `@hasOneThrough` | PHP Lighthouse's names for `@hasMany` / `@hasOne` on a `has_many` / `has_one :through` |
 
 ```graphql
 type User {
@@ -142,6 +143,28 @@ type User {
 The relation name defaults to the field name (snake_cased). Override with
 `@hasMany(relation: "authored_posts")`.
 
+### `@with`, `@withCount` and `@lazyLoad`
+
+Eager loading for fields the relationship directives do not resolve, each across
+every parent in the response at once. See
+[relationships.md](relationships.md#eager-loading-for-other-fields).
+
+```graphql
+type User {
+  "@with loads the relation before the field resolves, for a method that reads it."
+  taskSummary: String! @with(relation: "tasks") @method(name: "task_summary")
+
+  "@withCount sets posts_count on the user; the field's resolver reads it."
+  activity: String! @withCount(relation: "posts", scopes: ["published"]) @method
+
+  "@lazyLoad loads relations of the records the field returns."
+  posts: [Post!]! @hasMany @lazyLoad(relations: ["tags", "comments.author"])
+}
+```
+
+`relation` / `relations` may be nested with dots. `scopes` narrow the loaded or
+counted records. `@with`'s `relation` defaults to the field's name.
+
 ---
 
 ## Field directives
@@ -162,10 +185,16 @@ type Contact {
 ```
 
 On `Query` and `Mutation` the name is looked up in the queries / mutations
-namespaces, elsewhere in [`resolver_namespaces`](configuration.md). The class may
+namespaces, a nested name too (`Feeds::Home` is `Resolvers::Feeds::Home`), and
+then as written. On any other type it is looked up in the resolvers namespace the
+same way (`Posts::TagsCount` is `Resolvers::Posts::TagsCount`), then in
+[`resolver_namespaces`](configuration.md). There, the class's `object` is the parent: the
+record the field belongs to (see
+[resolvers.md](resolvers.md#fields-of-other-types)). The class may
 be a `GraphQL::Schema::Resolver` (graphql-ruby's contract), or a plain callable —
 a class-level `call`, an instance `#call`, or an instance `#resolve`, each
-receiving `(object, args, context)`:
+receiving `(object, args, context)`, and the [`ResolveInfo`](resolvers.md#resolveinfo)
+as a fourth argument when it takes one:
 
 ```ruby
 module Resolvers
@@ -177,6 +206,17 @@ module Resolvers
 end
 ```
 
+A method after `@` replaces `call`, as PHP Lighthouse's `Class@method`: it is called
+on the class when the class has it, else on an instance. On a
+`GraphQL::Schema::Resolver` it replaces `resolve`, and `ready?` / `authorized?`
+still run.
+
+```graphql
+type Query {
+  usersTotal: Int @field(resolver: "Statistics@users_total")   # Resolvers::Statistics.users_total
+}
+```
+
 ### `@rename`
 
 Read a differently-named attribute off the parent object. This is the explicit
@@ -191,15 +231,157 @@ type User {
 ### `@method`
 
 Resolve a field by calling a method on the parent object (PHP-parity). Great for
-exposing a computed method or predicate without a custom resolver.
+exposing a computed method or predicate without a custom resolver. `name:`
+defaults to the field's snake_case name.
 
 ```graphql
 type Conversation {
   labels: [String!]! @method(name: "label_list")
   canReply: Boolean @method(name: "can_reply?")
+  summary(words: Int = 20): String! @method
 }
 ```
 
+The field's arguments reach the method: as snake_case keywords when it takes
+keywords (`def summary(words:)`), otherwise positionally, in the order the SDL
+declares them, as PHP Lighthouse passes them (`def summary(words)`). The SDL's
+defaults apply, and a method taking no parameters is called without them.
+
+## Relay
+
+### `@globalId` and `@node`
+
+`@globalId` encodes a field's value as a Relay global id (base64 of `Type:id`), and
+decodes an argument or input field (`decode: ARRAY | TYPE | ID`). `@node` on a type
+makes it implement `Node` and adds `Query.node(id:)`, which finds the type's model
+record, or calls `@node(resolver:)`. See [relay.md](relay.md).
+
+```graphql
+type User @node {
+  id: ID! @globalId
+}
+
+type Query {
+  user(id: ID! @globalId(decode: ID) @eq): User @find
+}
+```
+
+## Execution
+
+### `@namespaced`
+
+A field that only groups others: it resolves to `true`, and the fields of its type
+resolve with their own directives. On `Query` or `Mutation`.
+
+```graphql
+type Query { post: PostQueries! @namespaced }
+type PostQueries {
+  find(id: ID! @eq): Post @find
+  list: [Post!]! @paginate
+}
+```
+
+### `@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.
+
+```graphql
+type Mutation {
+  login(email: String!, password: String!): User @throttle(maxAttempts: 5)
+}
+```
+
+### `@async`
+
+Runs a mutation in a job and answers `true` at once. `@guard`, the `@can*` family,
+`@validator` and the argument directives run in the request, so the client still
+gets their errors; what resolves the field runs in
+`Lighthouse::GraphQL::AsyncMutationJob` (ActiveJob), with the arguments and the
+context values ActiveJob can serialize (records too, through GlobalID). The field
+must be a `Mutation` field returning `Boolean`, and the schema a named constant.
+
+```graphql
+type Mutation {
+  importFeed(url: String!): Boolean! @guard @async(queue: "imports")
+}
+```
+
+### `@hide` and `@show`
+
+Leave a field out of the schema by environment (`Rails.env`): `@hide(env:)` removes
+it in the environments listed, `@show(env:)` keeps it only in those.
+
+```graphql
+type Query {
+  debugInfo: String @show(env: ["development", "test"])
+  legacyFeed: [Post!]! @hide(env: ["production"]) @all
+}
+```
+
+## Type directives
+
+### `@model`
+
+Maps an object type to the ActiveRecord model whose records it resolves, when the
+names differ, as PHP Lighthouse's. Every directive that takes `model:` (`@all`,
+`@find`, `@first`, `@paginate`, `@create`, `@update`, `@upsert`, `@delete`, the
+`@can*` family...) on a field returning the type gets it, unless it names its own; a
+union or interface resolves the model's records to the type; `@node` finds them. The
+schema does not build unless the class is an ActiveRecord model.
+
+```graphql
+type Article @model(class: "Post") { id: ID! title: String! }
+
+type Query {
+  articles: [Article!]! @paginate          # pages through Post
+  article(id: ID! @eq): Article @find
+}
+```
+
+### `@enum`
+
+The internal value of an enum value: what a resolver gets for it in an argument,
+and what a result answers with it for.
+
+```graphql
+enum Role {
+  ADMIN @enum(value: "admin")
+  MEMBER @enum(value: "member")
+}
+
+type Query { users(role: Role @eq): [User!]! @all }   # filters on "admin"
+```
+
+They go on a union, an interface or a scalar, and name the class that resolves or
+coerces its values. Without them, Lighthouse uses the type's class
+(`Types::<Name>Type` including `Lighthouse::GraphQL::Type`), or its default. See
+[types.md](types.md).
+
+### `@union` and `@interface`
+
+Name the class that picks the object type of each value: `resolve_type(object,
+context)` or `call(object, context)`, returning a type name or a type class.
+Looked up in the types namespace (nested names too), then as written.
+
+```graphql
+union SearchResult @union(resolveType: "SearchResultResolver") = Post | User
+interface Authored @interface(resolveType: "AuthoredResolver") { id: ID! }
+```
+
+### `@scalar`
+
+Names the class that reads and writes the scalar's values: `coerce_input(value,
+context)` and `coerce_result(value, context)`, as a `GraphQL::Schema::Scalar`.
+
+```graphql
+scalar DateTime @scalar(class: "Types::DateTimeType")
+```
+
 ---
 
 ## Authentication & Authorization
@@ -263,7 +445,40 @@ type Query {
 ```
 
 Builders are looked up in their own namespace, `Builders::` (app/graphql/builders)
-— they are not resolvers. See [resolvers.md](resolvers.md#builders).
+— they are not resolvers. See [resolvers.md](resolvers.md#builders). The class is
+`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
+`(relation, value, context)` whenever the client sends that argument, an explicit
+`null` included, and not when it is left out:
+
+```graphql
+type Query {
+  posts(since: DateTime @builder(method: "Recent@since")): [Post!]! @all
+  latest: [Post!]! @all @builder(class: "Recent", value: 5)
+}
+```
+
+```ruby
+class Builders::Recent
+  def self.call(relation, count, _context) = relation.order(created_at: :desc).limit(count)
+  def self.since(relation, time, _context) = time ? relation.where(created_at: time..) : relation
+end
+```
+
+### `@whereAuth`
+
+Keep only the records the signed-in user owns, through a relation of the model: a
+`belongs_to`, a `has_many`, a `:through`. A guest gets none. It applies where
+`@builder` does (`@all`, `@paginate`, `@first`, `@count`, `enhance_builder`).
+
+```graphql
+type Query {
+  myPosts: [Post!]! @paginate @whereAuth(relation: "author")
+  myTeams: [Team!]! @all @whereAuth(relation: "members")
+}
+```
 
 ```ruby
 module Builders
@@ -292,6 +507,10 @@ Full guide: [filtering-and-ordering.md](filtering-and-ordering.md).
 | `@like` | `column LIKE %value%` |
 | `@whereKey` | `primary key = value` (`IN` for a list) |
 | `@where(operator:)` | generic operator (`GT`, `GTE`, `IN`, `IS_NULL`, `CONTAINS`, …) |
+| `@whereNull` / `@whereNotNull` | `true`: `column IS NULL` / `IS NOT NULL`; `false`: the opposite |
+| `@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 |
 
 ```graphql
@@ -307,6 +526,41 @@ type Query {
 
 The column defaults to the snake_cased argument name; override with `key:`.
 
+```graphql
+type Query {
+  posts(
+    unpublished: Boolean @whereNull(key: "published_at")
+    createdAt: DateRange @whereBetween(key: "created_at")
+    tagged: [String!] @whereJsonContains(key: "tags")
+    trending: Boolean @scope
+    filter: PostFilter @nest
+    limit: Int @limit
+  ): [Post!]! @all
+}
+
+input DateRange { from: DateTime! to: DateTime! }
+input PostFilter { title: String @like, authorId: ID @eq(key: "author_id") }
+```
+
+### `@nest`
+
+On an argument whose type is an input object, applies the filters of the input's
+fields (at any depth, for those that carry `@nest` too), as if they were the
+field's own arguments.
+
+### `@limit`
+
+On an `Int` argument, caps how many results the field returns at the client's
+value; `null` leaves them alone. A query not run yet gets a `LIMIT`; the records of
+a relation, loaded for every parent at once, are cut per parent. A negative value is
+an error.
+
+`@limit(builder: true)` puts the `LIMIT` on the field's query instead, with the
+other argument directives. Use it on root fields: on a relation batched for many
+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.
+
 ### `@whereConditions` / `@whereHasConditions`
 
 Give clients a structured, dynamic `WHERE` builder (AND/OR/operators, and HAS for
@@ -319,6 +573,35 @@ type Query {
 }
 ```
 
+### `@trim`, `@hash`, `@drop`, `@bind` and `@upload`
+
+Rewrite an argument's or input field's value before the field resolves, in the
+order the SDL lists them:
+
+| Directive | The resolver gets |
+| --- | --- |
+| `@trim` | the string without leading and trailing whitespace. On a field: every string it takes, nested inputs included |
+| `@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)) |
+
+```graphql
+type Mutation {
+  signUp(email: String! @trim, password: String! @hash, captcha: String @drop): User! @create
+  assign(task: ID! @bind(class: "Task"), user: ID! @bind(class: "User", with: ["roles"])): Task!
+  updateAvatar(avatar: Upload! @upload(path: "avatars")): User! @update @inject(context: "current_user.id", name: "id")
+}
+```
+
+`@bind` fails the field with a validation error on the argument (`The selected task
+is invalid.`) when no record matches, unless `optional: true`, which passes `null`.
+
+`@globalId`, `@trim` and `@drop` only rewrite values: they run first, so `@guard`,
+the `@can*` family and `@validator` see the result. `@hash`, `@bind` and `@upload`
+run once those have let the call through: a validator sees the password before it
+is hashed, and nothing is stored or looked up for a refused call.
+
 ### `@convertEmptyStringsToNull`
 
 Replaces incoming empty strings `""` with `null`, before any resolver sees them —