lighthouse-graphql 0.1.1 → 0.2.0

data/docs/caching.md

@@ -0,0 +1,161 @@
+# Caching
+
+Two independent layers, matching PHP Lighthouse:
+
+- **Application cache.** `@cache` stores a field's resolved value in the Rails
+  cache (`Rails.cache`), so later requests skip the resolver.
+- **HTTP cache.** `@cacheControl` computes the `Cache-Control` header a response
+  may carry, so browsers, CDNs and proxies can reuse it.
+
+## `@cache`
+
+```graphql
+directive @cache(maxAge: Int, private: Boolean = false) on FIELD_DEFINITION
+```
+
+```graphql
+type Query {
+  highestKnownPrime: Int! @field(resolver: "Primes") @cache
+  temperature: Int! @cache(maxAge: 300)
+  myTodos: [Todo!]! @cache(private: true)
+}
+```
+
+- **`maxAge`** is in seconds. Without it, an entry lives until `@clearCache`
+  invalidates it or the store evicts it.
+- **`private: true`** keeps one entry per authenticated user (by `id`). Guests
+  share one.
+- **The key** covers the parent type, the parent's key, the field and its
+  arguments. The parent's key is the field marked `@cacheKey`, else its first
+  `ID` field; root types have none.
+
+```graphql
+type GithubProfile {
+  username: String @cacheKey
+  repos: [Repository!]! @cache    # one entry per username
+}
+```
+
+Lists and relations are stored as arrays. A value the store cannot serialize,
+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`).
+
+A cached value is still authorized and validated on every request: `@cache` runs
+inside `@guard`, `@can*` and `@validator`, never around them.
+
+## `@clearCache`
+
+```graphql
+directive @clearCache(type: String!, idSource: ClearCacheIdSource, field: String) repeatable on FIELD_DEFINITION
+
+input ClearCacheIdSource {
+  argument: String   # path of an argument, e.g. "input.id"
+  field: String      # path in the result, e.g. "*.id"
+}
+```
+
+Put it on a mutation. It invalidates entries once the mutation has resolved
+successfully; a failed mutation clears nothing.
+
+```graphql
+type Mutation {
+  # Every cached field of every Post.
+  importPosts: Boolean @clearCache(type: "Post")
+
+  # The cached fields of the post whose id the argument holds.
+  updatePost(input: UpdatePostInput! @spread): Post! @update
+    @clearCache(type: "Post", idSource: { argument: "input.id" })
+
+  # One field of each post the mutation returned.
+  retitlePosts(ids: [ID!]!, title: String!): [Post!]!
+    @clearCache(type: "Post", idSource: { field: "*.id" }, field: "title")
+
+  # A root field.
+  publishPost(id: ID!): Post @clearCache(type: "Query", field: "latestPosts")
+}
+```
+
+### How invalidation works
+
+PHP Lighthouse clears entries through cache tags. Rails cache stores have no tags,
+and `delete_matched` is not available everywhere (Solid Cache and Memcached lack
+it). So Lighthouse **versions** keys instead:
+
+1. Each entry's key embeds four version tokens: the type, the type and id, the
+   type and field, and the type, id and field.
+2. `@clearCache` replaces the token it targets, so the entries built on the old
+   one are never read again. They expire or are evicted on their own.
+3. If a token is evicted, a new one is written, which causes misses, never stale
+   reads.
+
+This works on any store, and clearing a type also clears its per-id entries.
+Each cached read costs one `read_multi` for the tokens.
+
+## `@cacheControl`
+
+```graphql
+directive @cacheControl(maxAge: Int! = 0, scope: CacheControlScope! = PUBLIC, inheritMaxAge: Boolean! = false)
+  on FIELD_DEFINITION | OBJECT | INTERFACE | UNION
+```
+
+Lighthouse walks the fields a query selects, fragments included, and derives one
+header. These are PHP Lighthouse's rules, after Apollo's:
+
+- `max-age` is the **lowest** `maxAge` among the contributing fields. 0 gives
+  `no-cache`.
+- The response is `private` if any selected field is `PRIVATE`.
+- **Defaults:**
+  - A root field without the directive is `maxAge: 0, PRIVATE`.
+  - Any other field returning an object, interface or union is 0, unless its
+    type carries `@cacheControl`.
+  - Scalar fields inherit their parent and don't contribute.
+  - A directive on the field overrides one on its type, and its omitted arguments
+    take the directive's defaults (0, `PUBLIC`).
+- `inheritMaxAge: true` takes the parent field's `maxAge`.
+- Mutations are never cacheable.
+
+```graphql
+type Query {
+  publicCompanies: [Company!]! @cacheControl(maxAge: 15)
+  me: User! @guard @cacheControl(maxAge: 5, scope: PRIVATE)
+}
+
+type Company @cacheControl(maxAge: 40) {
+  users: [User!]! @hasMany @cacheControl(maxAge: 25)
+}
+```
+
+`{ publicCompanies { users { id } } }` gets `max-age=15, public`;
+`{ me { id } }` gets `max-age=5, private`.
+
+### Sending the header
+
+The controller from `rails generate lighthouse:install` already does this:
+
+```ruby
+result = AppSchema.execute(params[:query], ...)
+Lighthouse::GraphQL::CacheControl.apply(response, result)   # no-op without @cacheControl
+render json: result
+```
+
+`Lighthouse::GraphQL::CacheControl.header(result)` returns the value without
+setting it.
+
+Things to know:
+
+- Shared caches only store `GET` responses, and the generated route is
+  `POST /graphql`. Add `get '/graphql', to: 'graphql#execute'` and send cacheable
+  queries over `GET`, ideally as [persisted queries](performance.md#persisted-queries),
+  whose hash fits in a URL.
+- The pagination types Lighthouse generates (`paginatorInfo`, `data`, `pageInfo`,
+  `edges`, `node`) inherit their parent field's `maxAge`, as in PHP Lighthouse,
+  so a paginated field is as cacheable as its `@cacheControl` says.
+- With a `public` max-age, Rack's ETag middleware adds an `ETag`, so clients can
+  revalidate with `If-None-Match`.
+- Rails normalizes `no-cache, private` to `no-cache`. `no-cache` already forces
+  every cache to revalidate, so nothing is stored stale.

data/docs/configuration.md

@@ -10,6 +10,7 @@ require 'lighthouse-graphql'
 
 Lighthouse.configure do |config|
   config.sdl_folder = Rails.root.join('graphql').to_s
+  config.namespaces = { queries: ['Queries'], mutations: ['Mutations'] }
   config.resolver_namespaces = ['App::Graphql', 'Resolvers']
   config.on_error = ->(error, _context) { Rails.error.report(error) }
 end
@@ -23,12 +24,28 @@ 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).
 
+### `namespaces`
+
+Where each kind of class a schema names is looked up, by kind — they have
+different contracts, so they live apart ([resolvers.md](resolvers.md)):
+
+| Kind | Default | Holds |
+| --- | --- | --- |
+| `queries` | `['Queries']` | `GraphQL::Schema::Resolver` classes for `Query` fields |
+| `mutations` | `['Mutations']` | `GraphQL::Schema::Mutation` classes for `Mutation` fields |
+| `builders` | `['Builders']` | `@builder` classes |
+| `validators` | `['Validators']` | `@validator` contracts |
+
+```ruby
+config.namespaces = { queries: ['Api::Queries'] }   # the other kinds keep their defaults
+```
+
 ### `resolver_namespaces`
 
-An ordered list of namespaces tried when resolving a **class name** referenced by
-a directive argument — `@field(resolver: "ContactPerson")`, `@all(model: "User")`,
-`@builder(class: "ContactsBuilder")`. Fully-qualified names (containing `::`) are
-used as-is. Defaults to `['App::Graphql']`.
+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']`.
 
 ```ruby
 config.resolver_namespaces = ['App::Graphql', 'Resolvers']
@@ -48,6 +65,52 @@ 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
+it is no longer required), and the largest `first` allowed. A directive's
+`defaultCount` / `maxCount` override them; `maxCount: null` lifts the cap.
+
+```ruby
+config.pagination_default_count = 25
+config.pagination_max_count = 100
+```
+
+### `schema_cache`, `schema_cache_path`, `watch_sdl`, `persisted_queries*`
+
+Options for large schemas and high traffic, all off by default. See
+[performance.md](performance.md).
+
+```ruby
+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_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
+```
+
+### `transactional_mutations`
+
+Whether `@create` / `@update` / `@createMany` / `@updateMany` run in a database
+transaction. Defaults to `true`.
+
+### `authenticated_user`, `policy_user`, `authorizer`
+
+The authentication and authorization seams behind `@guard` and the `@can*`
+family. The authorizer is `->(user, record, ability, args = [])`, Pundit by
+default. See [authorization.md](authorization.md#configuration).
+
 ## Extending the registry
 
 Register app-defined directives (see [custom-directives.md](custom-directives.md))
@@ -57,6 +120,22 @@ from the same initializer:
 Lighthouse::DirectiveRegistry.register(App::Graphql::Directives::StartsWith)
 ```
 
+Directives implemented inside another class — no class of their own to
+register — contribute their SDL definition with `register_definition`, so it is
+injected into the schema and written by `bin/rails lighthouse:ide_helper`:
+
+```ruby
+Lighthouse::DirectiveRegistry.default.register_definition(
+  'tenant', 'directive @tenant(column: String) on FIELD_DEFINITION'
+)
+```
+
+Types a definition refers to (an enum argument, say) are registered with
+`register_type_definition('TenantMode', 'enum TenantMode { STRICT LOOSE }')`, or
+returned by the directive class's `type_definitions` (`{ name => sdl }`). They
+are injected only alongside a directive that uses them, and only if the schema
+doesn't define them itself.
+
 ## Federation reference resolvers
 
 Custom federation entity resolvers are registered with

data/docs/custom-directives.md

@@ -40,8 +40,12 @@ def self.directive_name = 'upcase'
 def self.definition = 'directive @upcase on FIELD_DEFINITION'
 ```
 
+If the definition refers to types of its own (an enum argument, say), return
+them from `def self.type_definitions = { 'Mode' => 'enum Mode { A B }' }`.
+
 Lighthouse injects that `definition` into the schema automatically, so apps never
-hand-declare your directive.
+hand-declare your directive, and `bin/rails lighthouse:ide_helper` writes it out
+for the IDE (see [IDE support](getting-started.md#ide-support)).
 
 ## Example 1 — an argument filter
 

data/docs/directives.md

@@ -24,21 +24,27 @@ type Query {
 }
 ```
 
-The model defaults to the field's return type (`User`). Override with
-`@all(model: "Account")`. Combine with [argument filters](filtering-and-ordering.md)
-and [`@orderBy`](#orderby) to constrain the result.
+It returns a plain list. The model defaults to the field's return type (`User`).
+Override it with `@all(model: "Account")`, and narrow it with model scopes:
+`@all(scopes: ["active"])`. Combine with
+[argument filters](filtering-and-ordering.md) and [`@orderBy`](#orderby) to
+constrain the result.
 
 ### `@find`
 
-Return a single record, typically by id. Pair it with an argument filter such as
-[`@eq`](#eq) so Lighthouse knows what to match on.
+Return the single record the field's argument filters select. More than one match
+is an error (`The query returned more than one result.`); none returns `null`.
 
 ```graphql
 type Query {
   user(id: ID! @eq): User @find
+  userByEmail(email: String! @eq): User @find
 }
 ```
 
+A lookup by `id` alone is batched through the Dataloader. An `id` argument without
+a filter directive still selects by primary key. `scopes:` applies model scopes.
+
 ### `@first`
 
 Like `@all`, but returns the **first** matching record instead of a list. Useful
@@ -46,31 +52,43 @@ with filters to fetch one record by criteria.
 
 ```graphql
 type Query {
-  latestPost(authorId: ID! @eq): Post @first
+  latestPost(authorId: ID! @eq): Post @first(scopes: ["published"])
 }
 ```
 
 ### `@paginate`
 
-Return a paginated list. Lighthouse rewrites the field to a Paginator type and
-adds pagination arguments.
+Return one page of a model's records. Lighthouse rewrites the field and adds the
+pagination arguments, exactly as PHP Lighthouse does:
+
+| `type:` | Arguments | Returns |
+| --- | --- | --- |
+| `PAGINATOR` (default) | `first: Int!`, `page: Int` | `PostPaginator! { paginatorInfo: PaginatorInfo!, data: [Post!]! }` |
+| `SIMPLE` | `first: Int!`, `page: Int` | `PostSimplePaginator! { paginatorInfo: SimplePaginatorInfo!, data }`, with no total, so one query fewer |
+| `CONNECTION` | `first: Int!`, `after: String` | `PostConnection! { pageInfo: PageInfo!, edges: [PostEdge!]! }`, Relay style |
 
 ```graphql
 type Query {
-  posts: [Post!]! @paginate
+  posts(title: String @like): [Post!]! @paginate(defaultCount: 20, maxCount: 100)
 }
 ```
 
-becomes, in effect:
-
 ```graphql
-type Query {
-  posts(first: Int, after: String): PostConnection
-}
+{ posts(first: 10, page: 2) { paginatorInfo { total lastPage hasMorePages } data { title } } }
 ```
 
-Use `@paginate(type: "CONNECTION")` for Relay-style cursor connections, or the
-default offset-based paginator otherwise.
+- **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
+  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
+  [`Config.pagination_default_count`](configuration.md#pagination_default_count--pagination_max_count).
+  Without either, clients must pass it.
+- **`maxCount`.** It caps `first`, overriding `Config.pagination_max_count`;
+  `maxCount: null` means unlimited.
+- **The total** is only counted when the client selects `paginatorInfo` or
+  `pageInfo`.
+- **Cursors** are base64 of the item's position.
 
 ### `@count`
 
@@ -79,6 +97,7 @@ Return the number of records — of a model, or of a relation on the parent obje
 ```graphql
 type Query {
   userCount: Int! @count(model: "User")
+  activeUserCount: Int! @count(model: "User", scopes: ["active"])
 }
 
 type Account {
@@ -92,7 +111,7 @@ Compute an aggregate (`SUM`, `AVG`, `MIN`, `MAX`, `COUNT`) over a column.
 
 ```graphql
 type Account {
-  totalRevenue: Float @aggregate(relation: "orders", column: "amount", function: SUM)
+  totalRevenue: Float @aggregate(relation: "orders", column: "amount", function: "SUM")
 }
 ```
 
@@ -105,10 +124,11 @@ See [relationships.md](relationships.md) for the full guide.
 
 | Directive | Association |
 | --- | --- |
-| `@hasMany` | one-to-many (returns a connection) |
+| `@hasMany` | one-to-many: a list, or paginated with `type:` |
 | `@hasOne` | one-to-one |
 | `@belongsTo` | inverse of has-one/has-many |
-| `@belongsToMany` | many-to-many |
+| `@belongsToMany` | many-to-many: a list, or paginated with `type:` |
+| `@morphTo`, `@morphOne`, `@morphMany`, `@morphToMany` | the polymorphic variants |
 
 ```graphql
 type User {
@@ -128,8 +148,11 @@ The relation name defaults to the field name (snake_cased). Override with
 
 ### `@field`
 
-Delegate a field to a custom resolver class — your escape hatch for anything the
-built-in directives don't cover.
+Delegate a field to a class — your escape hatch for anything the built-in
+directives don't cover. On `Query` and `Mutation` you usually don't need it:
+a field without a resolving directive resolves to `Queries::<FieldName>` /
+`Mutations::<FieldName>`, graphql-ruby resolver and mutation classes. See
+[resolvers.md](resolvers.md).
 
 ```graphql
 type Contact {
@@ -137,10 +160,11 @@ type Contact {
 }
 ```
 
-The resolver is resolved against your configured
-[`resolver_namespaces`](configuration.md). It may be a class with a class-level
-`call`, an instance `#call`, or an instance `#resolve`, each receiving
-`(object, args, context)`:
+On `Query` and `Mutation` the name is looked up in the queries / mutations
+namespaces, elsewhere in [`resolver_namespaces`](configuration.md). 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)`:
 
 ```ruby
 module Resolvers
@@ -189,25 +213,27 @@ Require an authenticated user before the field resolves; otherwise raise
 
 ```graphql
 type Query {
-  me: User @field(resolver: "Resolvers::CurrentUser") @guard
+  me: User @guard
 }
 ```
 
-### `@can`
+### `@canFind`, `@canModel`, `@canQuery`, `@canResolved`, `@canRoot`
 
-Authorize a field with a policy ability (Pundit by default; configurable). By
-default it authorizes the resolved record. `repeatable`.
+Authorize a field with a policy ability (Pundit by default; configurable) — each
+directive authorizes something different: the models an argument identifies, the
+model class, the models the field's filters select, the resolved value, or the
+parent object. All `repeatable`; shared arguments `ability`, `injectArgs`, `args`,
+`action`, `returnValue`.
 
 ```graphql
-type Query {
-  contact(id: ID!): Contact
-    @field(resolver: "Resolvers::ContactResolver")
-    @can(ability: "show")
+type Mutation {
+  createPost(input: CreatePostInput! @spread): Post @create @canModel(ability: "create")
+  updatePost(id: ID!, title: String): Post @update @canFind(ability: "update", find: "id")
 }
 ```
 
-`@can(ability:, find:, model:, root:)` — see [authorization.md](authorization.md)
-for the `find`/`model`/`root` modes.
+See [authorization.md](authorization.md). (`@can` was removed in favour of this
+family — it has a migration table.)
 
 ### `@auth`
 
@@ -231,13 +257,16 @@ Apply a custom method to the query builder before the field resolves. Repeatable
 
 ```graphql
 type Query {
-  contacts: [Contact!]! @paginate @builder(class: "Resolvers::ContactsBuilder")
+  contacts: [Contact!]! @paginate @builder(class: "Unassigned")
 }
 ```
 
+Builders are looked up in their own namespace, `Builders::` (app/graphql/builders)
+— they are not resolvers. See [resolvers.md](resolvers.md#builders).
+
 ```ruby
-module Resolvers
-  class ContactsBuilder
+module Builders
+  class Unassigned
     def self.call(relation, args, _ctx)
       args[:unassigned] ? relation.left_joins(:assignments).where(assignments: { id: nil }) : relation
     end
@@ -260,6 +289,7 @@ Full guide: [filtering-and-ordering.md](filtering-and-ordering.md).
 | `@in` | `column IN (values)` |
 | `@notIn` | `column NOT IN (values)` |
 | `@like` | `column LIKE %value%` |
+| `@whereKey` | `primary key = value` (`IN` for a list) |
 | `@where(operator:)` | generic operator (`GT`, `GTE`, `IN`, `IS_NULL`, `CONTAINS`, …) |
 | `@orderBy` | sort by one or more columns |
 
@@ -290,6 +320,55 @@ type Query {
 
 ---
 
+## Mutation directives
+
+`@create`, `@createMany`, `@update`, `@updateMany`, `@upsert` and `@upsertMany`
+save the model a field returns through ActiveRecord, with its validations, in a
+transaction. Input on its associations runs as
+[nested mutations](mutations.md#nested-mutations). `@delete` destroys the records
+its filter arguments (`@whereKey`, `@eq`, …) select. `@spread` flattens an input
+argument into the attributes, `@rename` maps an argument to another attribute,
+and `@inject(context:, name:)` sets server-side attributes.
+
+```graphql
+type Mutation {
+  createPost(input: CreatePostInput! @spread): Post!
+    @create @inject(context: "current_user.id", name: "author_id")
+  updatePost(id: ID!, title: String): Post! @update
+}
+```
+
+See [mutations.md](mutations.md).
+
+---
+
+## Validation
+
+`@validator` runs a contract (Dry::Validation by default) before a field
+resolves — on a field, or on an input type wherever it is used. Model validations
+need no directive. See [validation.md](validation.md).
+
+```graphql
+input CreateUserInput @validator { email: String password: String }
+```
+
+---
+
+## Caching
+
+`@cache(maxAge:, private:)` keeps a field's value in `Rails.cache`, keyed with the
+help of `@cacheKey`; `@clearCache(type:, idSource:, field:)` invalidates it from a
+mutation. `@cacheControl(maxAge:, scope:, inheritMaxAge:)` computes the response's
+HTTP `Cache-Control` header. See [caching.md](caching.md).
+
+```graphql
+type Query {
+  temperature: Int! @cache(maxAge: 300) @cacheControl(maxAge: 300)
+}
+```
+
+---
+
 ## Adding your own
 
 Every directive above is a small class registered with

data/docs/getting-started.md

@@ -18,6 +18,39 @@ Runtime dependencies (`graphql ~> 2.5`, `activesupport`) come with the gem. If y
 want federation, add `apollo-federation` to your app — it is intentionally **not**
 a hard dependency of Lighthouse so non-federated apps stay lean.
 
+## The install generator
+
+```shell
+bin/rails generate lighthouse:install
+```
+
+does steps 1–5 below for you:
+
+| File | What it is |
+| --- | --- |
+| `config/initializers/lighthouse.rb` | Every [configuration](configuration.md) option, commented out at its default |
+| `graphql/schema.graphql` | A starter schema (`user` via `@find`, `users` via `@paginate`) that assumes a `User` model — skipped when the folder already holds `.graphql` files |
+| `app/graphql/app_schema.rb` | The executable schema, with `GraphQL::Dataloader` enabled |
+| `app/controllers/graphql_controller.rb` | The endpoint, plus a `post '/graphql'` route |
+| `graphql.config.yml` | IDE configuration — see [IDE support](#ide-support) |
+
+| Option | Effect |
+| --- | --- |
+| `--schema=ApiSchema` | Name of the schema constant (default `AppSchema`) |
+| `--sdl-folder=app/schema` | Where the `.graphql` files live (default `graphql`); sets `config.sdl_folder` |
+| `--skip-controller` | No controller or route — for apps that already serve GraphQL |
+| `--skip-ide` | No `graphql.config.yml` or `.gitignore` entries |
+
+Rerunning it is safe: the route and `.gitignore` entries are only added once, and
+an existing schema class or controller is kept (pass `--force` to replace it).
+
+It coexists with graphql-ruby's own tooling. The generators live under
+`lighthouse:` and the rake task is `lighthouse:ide_helper`, next to graphql-ruby's
+`graphql:*` generators and `graphql:schema:*` tasks. `graphql:install` writes the
+same controller and route; whichever runs second finds the route already in place,
+and Lighthouse keeps a controller graphql-ruby generated. In that case, have the
+controller call `AppSchema.execute(...)` to serve the Lighthouse schema.
+
 ## 1. Write your schema (SDL)
 
 By default Lighthouse loads every `*.graphql` file under `RAILS_ROOT/graphql`,
@@ -124,6 +157,47 @@ end
 
 See [configuration.md](configuration.md) for all options.
 
+## IDE support
+
+Your IDE validates and autocompletes `.graphql` files against the schema it can
+see. Lighthouse's directive definitions and the types its manipulation phase
+generates live in Ruby, so without help the IDE flags `@paginate` as unknown and
+can't resolve `UserPaginator`. PHP Lighthouse solves this with an IDE helper
+command; so does Lighthouse for Rails:
+
+```shell
+bin/rails lighthouse:ide_helper              # writes to Rails.root
+OUTPUT=tmp/ide bin/rails lighthouse:ide_helper
+```
+
+It writes two files:
+
+- **`schema-directives.graphql`** — a definition for every registered directive,
+  built-in or [your own](custom-directives.md), except those your SDL already
+  declares (so the IDE never sees a duplicate).
+- **`programmatic-types.graphql`** — the types Lighthouse adds to the executable
+  schema: `<Type>Paginator`, `<Type>SimplePaginator`, `<Type>Connection`/`Edge`,
+  `PaginatorInfo`, `SimplePaginatorInfo`, `PageInfo`, the `whereConditions`
+  inputs and enums, and the `_` placeholder scalar.
+
+Point your IDE's [graphql-config](https://the-guild.dev/graphql/config) at them
+next to your SDL — the install generator writes this `graphql.config.yml`:
+
+```yaml
+schema:
+  - graphql/**/*.graphql
+  - schema-directives.graphql
+  - programmatic-types.graphql
+```
+
+It works with the GraphQL plugin for JetBrains IDEs and the GraphQL extension for
+VS Code. The files are derived from your schema, so the generator adds them to
+`.gitignore`; rerun the task after changing the schema or registering a directive.
+
+> The IDE reads fields as you wrote them: `users: [User!]! @paginate` still looks
+> like a list to it, although clients query `users { data { … } }`. Field
+> rewrites are not something an extra file can express.
+
 ## Casing: camelCase ↔ snake_case
 
 GraphQL conventionally uses `camelCase` field names; Rails uses `snake_case`
@@ -144,9 +218,19 @@ type User {
 }
 ```
 
+## Custom queries and mutations
+
+When a field needs Ruby, write a graphql-ruby resolver or mutation class named
+after it — `Query.latestPosts` resolves to `Queries::LatestPosts`
+(`app/graphql/queries/latest_posts.rb`), `Mutation.publishPost` to
+`Mutations::PublishPost`. `bin/rails generate lighthouse:query LatestPosts`
+scaffolds one. See [resolvers.md](resolvers.md).
+
 ## Next steps
 
 - [Directives reference](directives.md) — the full vocabulary.
+- [Queries, mutations & builders](resolvers.md), [Mutations](mutations.md),
+  [Validation](validation.md), [Caching](caching.md).
 - [Relationships](relationships.md) — wiring associations.
 - [Filtering & ordering](filtering-and-ordering.md) — query constraints.
 - [Apollo Federation](federation.md) — become a subgraph.