lighthouse-graphql 0.5.0 → 0.6.0

data/docs/getting-started.md

@@ -24,22 +24,25 @@ a hard dependency of Lighthouse so non-federated apps stay lean.
 bin/rails generate lighthouse:install
 ```
 
-does steps 1–5 below for you. It runs graphql-ruby's `graphql:install` first, for
-the base classes every graphql-ruby app has (`Types::Base*`, `Resolvers::BaseResolver`,
-`Mutations::BaseMutation`), then puts Lighthouse's own on top:
+does steps 1–5 below for you. It builds on graphql-ruby's own install,
+`rails g graphql:install`, with whichever of its options the app chose (`--relay`,
+`--batch`, `--api`, ...). When the app has no graphql-ruby schema class yet, it runs
+`graphql:install` first, with graphql-ruby's defaults. Then it adapts what
+graphql-ruby wrote, and adds Lighthouse's own:
 
 | File | What it is |
 | --- | --- |
+| `app/graphql/app_schema.rb` | graphql-ruby's schema class, now built by Lighthouse from the SDL on every class graphql-ruby wrote (`base_types`). The rest of the class is graphql-ruby's |
+| `app/graphql/types/query_type.rb`, `mutation_type.rb` | graphql-ruby's root types, which the SDL's `Query` and `Mutation` are built on. Their example `test_field` goes; Relay's `node` / `nodes` stay |
+| `app/graphql/types/base_*.rb`, `resolvers/base_resolver.rb`, `mutations/base_mutation.rb` | graphql-ruby's base classes. `BaseObject`, `BaseInterface`, `BaseUnion` and `BaseScalar` include `Lighthouse::GraphQL::Type` |
+| `app/controllers/graphql_controller.rb` | graphql-ruby's controller, replaced by one including `Lighthouse::GraphQL::Controller` |
 | `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, built from the SDL, with `GraphQL::Dataloader` enabled and the base classes in `base_types` |
-| `app/graphql/{types,resolvers,mutations,subscriptions}/base_*.rb` | graphql-ruby's base classes, and Lighthouse's `Subscriptions::BaseSubscription` |
-| `app/controllers/graphql_controller.rb` | The endpoint, plus a `post '/graphql'` route |
 | `graphql.config.yml` | IDE configuration — see [IDE support](#ide-support) |
 
-`--schema=ApiSchema`, `--sdl-folder=app/schema`, `--skip-controller` and
-`--skip-ide` change what it writes. Rerunning it is safe, and a schema class or
-controller the app had before is kept (pass `--force` to replace it).
+`--schema=ApiSchema`, `--sdl-folder=app/schema`, `--subscriptions`,
+`--skip-controller` and `--skip-ide` change what it does. Rerunning it changes
+nothing, and a controller the app changed is kept.
 [generators.md](generators.md) has the details, every generator Lighthouse has, and
 which of graphql-ruby's `graphql:*` generators fit a Lighthouse app.
 
@@ -71,25 +74,34 @@ field's return type name (`User`), or you can be explicit with
 
 Lighthouse builds on graphql-ruby, and follows its convention: each kind of class
 inherits from a base class in its own namespace, where what they all share goes
-once. graphql-ruby's `graphql:install` writes them, and `lighthouse:install` runs it;
-by hand, run it yourself, then add the subscription base, which graphql-ruby has
-none of, and make the mutation base a `GraphQL::Schema::Mutation` (the SDL declares a
-mutation's arguments, where graphql-ruby's `RelayClassicMutation` takes one `input:`):
+once. graphql-ruby's `graphql:install` writes them, and `lighthouse:install` builds
+on them. By hand, run graphql-ruby's install with its defaults:
 
 ```shell
-bin/rails generate graphql:install --no-relay --skip-graphiql
+bin/rails generate graphql:install
 ```
 
+Then include `Lighthouse::GraphQL::Type` in the base object, interface, union and
+scalar, so every type class that inherits from them lends its methods to the SDL
+type of its name (see [type classes](resolvers.md#type-classes)):
+
 ```ruby
-# app/graphql/mutations/base_mutation.rb       — Mutation fields (Mutations::PublishPost)
-module Mutations
-  class BaseMutation < GraphQL::Schema::Mutation   # graphql-ruby writes RelayClassicMutation
-    argument_class Types::BaseArgument
+# app/graphql/types/base_object.rb
+module Types
+  class BaseObject < GraphQL::Schema::Object
+    include Lighthouse::GraphQL::Type
+    edge_type_class(Types::BaseEdge)
+    connection_type_class(Types::BaseConnection)
     field_class Types::BaseField
-    object_class Types::BaseObject
+    # include ApolloFederation::Object   # if you use federation
   end
 end
+```
+
+Add the subscription base, which graphql-ruby has none of, if the schema has a
+`Subscription` type (`lighthouse:install --subscriptions` writes it):
 
+```ruby
 # app/graphql/subscriptions/base_subscription.rb — Subscription fields
 module Subscriptions
   class BaseSubscription < GraphQL::Schema::Subscription
@@ -98,62 +110,85 @@ module Subscriptions
 end
 ```
 
-Delete the `Types::QueryType` and `Types::MutationType` it writes: the SDL declares
-the root types. The `Types::Base*` classes are the SDL's types' bases: the place to
-mix in Apollo Federation or custom field and argument behavior.
-
-```ruby
-# app/graphql/types/base_object.rb
-module Types
-  class BaseObject < GraphQL::Schema::Object
-    field_class Types::BaseField
-    # include ApolloFederation::Object   # if you use federation
-  end
-end
-```
+graphql-ruby's `Mutations::BaseMutation` stays a `RelayClassicMutation`. A
+`Mutation` field that declares its arguments one by one calls it as a plain
+mutation, with those arguments as keywords; one with a single `input:` argument
+goes through `RelayClassicMutation`'s own `input:` handling.
 
 ## 3. Build the schema
 
+graphql-ruby's schema class becomes Lighthouse's: it inherits from the schema
+`get_schema` builds from the SDL, instead of `GraphQL::Schema`.
+
 ```ruby
 # app/graphql/app_schema.rb
-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: {
+      query_type: Types::QueryType,
+      mutation_type: Types::MutationType,
+      node: Types::NodeType,
       resolver: Resolvers::BaseResolver,
       mutation: Mutations::BaseMutation,
       subscription: Subscriptions::BaseSubscription,
       object: Types::BaseObject,
-      # interface:, union:, enum:, input_object:, scalar: ...
+      interface: Types::BaseInterface,
+      union: Types::BaseUnion,
+      scalar: Types::BaseScalar,
+      enum: Types::BaseEnum,
+      input_object: Types::BaseInputObject
     }
   }
 )
+  # Lighthouse batches relationship loads through graphql-ruby's Dataloader.
+  use GraphQL::Dataloader
+
+  max_depth(15)
+  max_query_string_tokens(5000)
+  validate_max_errors(100)
+
+  # Relay-style Object Identification, as graphql-ruby's install writes it:
+  def self.id_from_object(object, type_definition, query_ctx)
+    object.to_gid_param
+  end
+
+  def self.object_from_id(global_id, query_ctx)
+    GlobalID.find(global_id)
+  end
+end
 ```
 
+The SDL is read from `config.sdl_folder` (`get_schema(sdl_folder: ...)` overrides
+it). The class body is graphql-ruby's, so plugins and settings go there as in any
+graphql-ruby schema (`use ...`, `max_complexity(...)`), but for `query(...)` and
+`mutation(...)`, which the SDL's root types replace, and `resolve_type`, which
+Lighthouse answers (see [types.md](types.md)).
+
 `object:` and the other SDL kinds go to graphql-ruby, which builds the SDL's types
-from them. `resolver:`, `mutation:` and `subscription:` are Lighthouse's: every
-class a `Query`, `Mutation` or `Subscription` field resolves to must inherit from
-its kind's base, and a `Subscription` field with no class of its own resolves with
-the subscription base. See [resolvers.md](resolvers.md#base-classes).
+from them. `query_type:` and `mutation_type:` are the classes the SDL's `Query` and
+`Mutation` are built on, so their own `field`s (Relay's `node` / `nodes`) are the
+schema's too; `node:` is the SDL's `Node` interface (see [relay.md](relay.md)).
+`resolver:`, `mutation:` and `subscription:` are Lighthouse's: every class a
+`Query`, `Mutation` or `Subscription` field resolves to must inherit from its kind's
+base, and a `Subscription` field with no class of its own resolves with the
+subscription base. See [resolvers.md](resolvers.md#base-classes).
 
-`get_schema` returns a `GraphQL::Schema` subclass you can use directly, or
-subclass further (e.g. to add federation, tracing, a Dataloader):
+A constant works as well, with the settings passed as options or set on it:
 
 ```ruby
-class AppSchema < AppSchema   # or build a Base*Schema and subclass it
-  use GraphQL::Dataloader
-end
+AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
+  options: { base_types: { object: Types::BaseObject }, using: { GraphQL::Dataloader => {} } }
+)
 ```
 
-> Lighthouse uses graphql-ruby's `Dataloader` to batch relationship loads. Add
-> `use GraphQL::Dataloader` to your schema to get N+1-free relationships.
+> Lighthouse uses graphql-ruby's `Dataloader` to batch relationship loads. Keep
+> `use GraphQL::Dataloader` in your schema to get N+1-free relationships.
 
 ## 4. Serve it
 
-`rails g lighthouse:install` writes the controller. It includes
-`Lighthouse::GraphQL::Controller`, a concern that serves the schema:
+`rails g lighthouse:install` replaces graphql-ruby's controller (when the app has
+not changed it) with one including `Lighthouse::GraphQL::Controller`, a concern that
+serves the schema:
 
 ```ruby
 class GraphqlController < ApplicationController
@@ -286,7 +321,9 @@ When a field needs Ruby, write a graphql-ruby resolver or mutation class named
 after it — `Query.latestPosts` resolves to `Resolvers::LatestPosts`
 (`app/graphql/resolvers/latest_posts.rb`, a `Resolvers::BaseResolver`),
 `Mutation.publishPost` to `Mutations::PublishPost` (a `Mutations::BaseMutation`).
-`bin/rails generate lighthouse:query LatestPosts` scaffolds one. See
+A method of the root type class comes first, as in graphql-ruby: `Query.latestPosts`
+calls `Types::QueryType#latest_posts` when it defines one. `bin/rails generate
+graphql:mutation PublishPost` writes a code-first mutation. See
 [resolvers.md](resolvers.md).
 
 ## Next steps

data/docs/performance.md

@@ -61,8 +61,8 @@ Lighthouse.configure { |config| config.watch_sdl = Rails.env.development? }
 Rails' reloader watches Ruby files, not `.graphql` ones, so without this an SDL
 edit only shows up after restarting the server. With it, the SDL folder joins
 `config.watchable_dirs`, and an edit reloads the app, and with it the schema, on
-the next request, like a Ruby change. This relies on the schema constant living
-in an autoloaded file, as the generated `app/graphql/app_schema.rb` does.
+the next request, like a Ruby change. This relies on the schema class living
+in an autoloaded file, as `app/graphql/app_schema.rb` does.
 
 ## Persisted queries
 

data/docs/relationships.md

@@ -39,12 +39,13 @@ aliases, so an SDL written for it builds unchanged.
 
 The relationship directives load through graphql-ruby's **Dataloader** and
 ActiveRecord's preloader, one query per association per batch. Enable the
-Dataloader on your schema (the install generator does):
+Dataloader on your schema (graphql-ruby's install does, and with `--batch`
+`lighthouse:install` adds it beside GraphQL::Batch):
 
 ```ruby
-AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
-  options: { using: { GraphQL::Dataloader => {} } }
-)
+class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(options: { base_types: { object: Types::BaseObject } })
+  use GraphQL::Dataloader
+end
 ```
 
 A query for 100 posts and their authors then issues two queries, not 101. A

data/docs/relay.md

@@ -6,6 +6,11 @@ does, with two directives: `@globalId` encodes and decodes the ids, and `@node`
 makes a type findable by them. For Relay's cursor pagination, see
 [`@paginate(type: CONNECTION)`](directives.md#paginate).
 
+An app whose schema has graphql-ruby's Relay, as `rails g graphql:install` writes it
+by default, uses the same directives on graphql-ruby's ids and `Node`: see
+[Relay through graphql-ruby](#relay-through-graphql-ruby). The sections before it
+describe a schema without it.
+
 ## Global ids
 
 `@globalId` on a field encodes its value with the type's name:
@@ -125,6 +130,64 @@ type Query {
 }
 ```
 
+## Relay through graphql-ruby
+
+graphql-ruby's install (`--relay`, its default) writes Relay's side in Ruby:
+`Types::NodeType`, the `node` and `nodes` fields of `Types::QueryType`, and the
+schema's `id_from_object` / `object_from_id`, on Rails' GlobalID:
+
+```ruby
+class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(
+  options: { base_types: { query_type: Types::QueryType, node: Types::NodeType, object: Types::BaseObject } }
+)
+  def self.id_from_object(object, type_definition, query_ctx)
+    object.to_gid_param
+  end
+
+  def self.object_from_id(global_id, query_ctx)
+    GlobalID.find(global_id)
+  end
+end
+```
+
+`lighthouse:install` names those classes in `base_types`, and Lighthouse's
+directives then work on them. The schema has one kind of global id and one `Node`:
+
+- `@globalId` on a field that resolves an object's own id encodes it with
+  `id_from_object`: `Tag.id` answers `tag.to_gid_param`, as graphql-ruby's `Node.id`
+  does. Any other value is encoded as before.
+- `@globalId` on an argument decodes with `object_from_id`, which loads the object.
+  `ID` gives its id, and `ARRAY` / `TYPE` its class name (`["Tag", 1]`, `"Tag"`).
+- `node:` is the SDL's `Node` interface: `interface Node`, which `@node` adds, and
+  `implements Node` refer to `Types::NodeType`. A `@node` type implements it.
+- `Query.node` and `nodes` are graphql-ruby's code-first fields of
+  `Types::QueryType`, which find objects with `object_from_id`. The `node` field
+  `@node` would add to `Query` gives way to them.
+
+```graphql
+type Tag @node {
+  id: ID! @globalId
+  name: String!
+}
+
+type Query {
+  tag(id: ID! @globalId(decode: ID) @eq): Tag @find
+}
+```
+
+```graphql
+{
+  node(id: "Z2lkOi8vYXBwL1RhZy8x") { id ... on Tag { name } }
+  tag(id: "Z2lkOi8vYXBwL1RhZy8x") { name }
+}
+```
+
+`Tag.id` and both arguments carry `Tag` 1's GlobalID (`gid://app/Tag/1`, in base64).
+`Query.node` finds every object with `object_from_id`, so `@node(resolver:)` and
+`@node(model:)` play no part in it, and [`global_id`](configuration.md#global_id)
+encodes only what `id_from_object` does not. A schema without `id_from_object` /
+`object_from_id` works as the sections above describe.
+
 ## Your own encoding
 
 [`global_id`](configuration.md#global_id) takes any object with

data/docs/resolvers.md

@@ -8,9 +8,9 @@ interchangeable. Each kind has its own contract and its own folder:
 | Kind | Folder / namespace | Contract | Used by |
 | --- | --- | --- | --- |
 | Resolver | `app/graphql/resolvers` · `Resolvers::` | `Resolvers::BaseResolver` (a `GraphQL::Schema::Resolver`) | `Query` fields |
-| Mutation | `app/graphql/mutations` · `Mutations::` | `Mutations::BaseMutation` (a `GraphQL::Schema::Mutation`) | `Mutation` fields |
+| Mutation | `app/graphql/mutations` · `Mutations::` | `Mutations::BaseMutation` (graphql-ruby's `GraphQL::Schema::RelayClassicMutation`) | `Mutation` fields |
 | Subscription | `app/graphql/subscriptions` · `Subscriptions::` | `Subscriptions::BaseSubscription` (a `GraphQL::Schema::Subscription`) | `Subscription` fields ([subscriptions.md](subscriptions.md)) |
-| Type | `app/graphql/types` · `Types::` | `Types::BaseObject` (a `GraphQL::Schema::Object`) including `Lighthouse::GraphQL::Type`, named `<Type>Type` | Fields of other types, through its methods ([type classes](#type-classes)); unions, interfaces and scalars too ([types.md](types.md)) |
+| Type | `app/graphql/types` · `Types::` | `Types::BaseObject` (a `GraphQL::Schema::Object`) including `Lighthouse::GraphQL::Type`, named `<Type>Type` | Fields of any object type, through its methods ([type classes](#type-classes), [root type classes](#root-type-classes)); unions, interfaces and scalars too ([types.md](types.md)) |
 | Builder | `app/graphql/builders` · `Builders::` | `call(relation, args, context)` → relation | `@builder` |
 
 Validators (`app/graphql/validators`) are one more kind. They are covered in
@@ -19,12 +19,13 @@ Validators (`app/graphql/validators`) are one more kind. They are covered in
 ## Base classes
 
 As in any graphql-ruby app, each kind of class has a base class in its namespace,
-and every class of the kind inherits from it. graphql-ruby's `graphql:install`,
-which `rails g lighthouse:install` runs, writes `Resolvers::BaseResolver`,
-`Mutations::BaseMutation` and the `Types::Base*` classes; Lighthouse adds
-`Subscriptions::BaseSubscription`, which graphql-ruby has none of, and makes the
-mutation base a plain `GraphQL::Schema::Mutation`, as the SDL declares a mutation's
-arguments ([generators.md](generators.md)):
+and every class of the kind inherits from it. graphql-ruby's `graphql:install`
+writes `Resolvers::BaseResolver`, `Mutations::BaseMutation` and the `Types::Base*`
+classes, and `rails g lighthouse:install` builds on them: it keeps them as
+graphql-ruby wrote them, includes `Lighthouse::GraphQL::Type` in the base object,
+interface, union and scalar, and with `--subscriptions` adds
+`Subscriptions::BaseSubscription`, which graphql-ruby has none of
+([generators.md](generators.md)):
 
 ```ruby
 # app/graphql/resolvers/base_resolver.rb          (graphql-ruby's)
@@ -33,16 +34,17 @@ module Resolvers
   end
 end
 
-# app/graphql/mutations/base_mutation.rb          (graphql-ruby's, made a Mutation)
+# app/graphql/mutations/base_mutation.rb          (graphql-ruby's)
 module Mutations
-  class BaseMutation < GraphQL::Schema::Mutation
+  class BaseMutation < GraphQL::Schema::RelayClassicMutation
     argument_class Types::BaseArgument
     field_class Types::BaseField
+    input_object_class Types::BaseInputObject
     object_class Types::BaseObject
   end
 end
 
-# app/graphql/subscriptions/base_subscription.rb  (Lighthouse's)
+# app/graphql/subscriptions/base_subscription.rb  (Lighthouse's, --subscriptions)
 module Subscriptions
   class BaseSubscription < GraphQL::Schema::Subscription
     include Lighthouse::GraphQL::Subscription
@@ -62,9 +64,12 @@ schema holds every class to them:
 
 ```ruby
 # app/graphql/app_schema.rb
-AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
+class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(
   options: {
     base_types: {
+      query_type: Types::QueryType,
+      mutation_type: Types::MutationType,
+      node: Types::NodeType,
       resolver: Resolvers::BaseResolver,
       mutation: Mutations::BaseMutation,
       subscription: Subscriptions::BaseSubscription,
@@ -77,6 +82,8 @@ AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
     }
   }
 )
+  use GraphQL::Dataloader
+end
 ```
 
 - A class a `Query`, `Mutation` or `Subscription` field resolves to, by convention
@@ -89,12 +96,17 @@ AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
   (`GraphQL::Schema::Resolver`, `GraphQL::Schema::Mutation`, which
   `RelayClassicMutation` is, `GraphQL::Schema::Subscription`), or the schema does not
   build. graphql-ruby never sees these three keys.
+- `query_type:` and `mutation_type:` are the code-first classes the SDL's `Query`
+  and `Mutation` are built on (see [root type classes](#root-type-classes)), and
+  `node:` is the SDL's `Node` interface ([relay.md](relay.md#relay-through-graphql-ruby)).
+  `subscription_type:` does the same for `Subscription`.
 - The others are graphql-ruby's: it builds the SDL's types of each kind from them.
   A [type class](#type-classes) (one including `Lighthouse::GraphQL::Type`) that
   does not inherit from its kind's raises `Lighthouse::DefinitionError` when the
   schema is built.
 
-`rails g lighthouse:install` writes the schema class with them. Without them,
+`rails g lighthouse:install` names in the schema class every one graphql-ruby's
+install wrote. Without them,
 Lighthouse requires only the graphql-ruby class (`GraphQL::Schema::Resolver`, …),
 and a `Subscription` field with no class resolves with a built-in subscription that
 includes the concern.
@@ -149,8 +161,9 @@ end
 
 ### Resolution by convention
 
-A field on `Query` or `Mutation` with **no resolving directive** resolves to the
-class named after it, as in PHP Lighthouse:
+A field on `Query` or `Mutation` with **no resolving directive**, and no method of
+its name on the [root type class](#root-type-classes), resolves to the class named
+after it, as in PHP Lighthouse:
 
 - `Query.latestPosts` resolves to `Resolvers::LatestPosts`;
 - `Mutation.publishPost` resolves to `Mutations::PublishPost`.
@@ -162,9 +175,11 @@ field with no class is reported through [`on_error`](configuration.md#on_error):
 it raises in test and logs elsewhere. Lighthouse never falls back to a top-level
 constant, so a `post` field is never mistaken for the `Post` model.
 
-graphql-ruby's `RelayClassicMutation` (what `rails g graphql:install` makes
-`Mutations::BaseMutation` inherit from) works too, as long as the SDL field takes the
-`input:` argument it expects.
+graphql-ruby's `RelayClassicMutation`, which `Mutations::BaseMutation` inherits from,
+takes a single `input:` argument. A `Mutation` field whose SDL declares its arguments
+one by one calls the class as a plain mutation, with those arguments as keywords
+(`resolve(id:)` above). A field with a single `input:` argument goes through
+`RelayClassicMutation`'s own `input:` handling.
 
 Wrapping directives (`@guard`, the `@can*` family, `@validator`, `@cache`,
 `@clearCache`) are not resolvers, so a field carrying only those still resolves by
@@ -176,6 +191,45 @@ type Mutation {
 }
 ```
 
+### Root type classes
+
+graphql-ruby's install writes `Types::QueryType` and `Types::MutationType`, and the
+schema's `base_types` name them (`query_type:`, `mutation_type:`). The SDL's `Query`
+and `Mutation` are built on them, so they work as in a graphql-ruby app:
+
+- A root field with no resolving directive calls the method of its snake_case name
+  on the class, when the class defines it and includes `Lighthouse::GraphQL::Type`
+  (`Types::BaseObject` does, after `lighthouse:install`). It comes before the
+  conventional class: `Query.latestPosts` calls `Types::QueryType#latest_posts`
+  before `Resolvers::LatestPosts`.
+- The class's own `field`s are the schema's too, beside the SDL's, and resolve as
+  in graphql-ruby: Relay's `node` / `nodes`, and the `field :publish_post, mutation:
+  Mutations::PublishPost` that `rails g graphql:mutation` adds. An SDL field of the
+  same name wins.
+- When the SDL has no `Mutation` type, `Types::MutationType` itself is the root,
+  once it declares a field.
+
+```graphql
+type Query {
+  latestPosts(limit: Int = 10): [Post!]!
+}
+```
+
+```ruby
+# app/graphql/types/query_type.rb
+module Types
+  class QueryType < Types::BaseObject
+    def latest_posts(limit:)
+      Post.order(created_at: :desc).limit(limit)
+    end
+  end
+end
+```
+
+As in a [type class](#type-classes), the method has `object`, `context`, the
+`dataload*` helpers and `resolve_info`, and gets the field's arguments as snake_case
+keywords. `Subscription` fields resolve with their classes, as before.
+
 ### Naming a class explicitly
 
 `@field(resolver:)` points a field at a class by name. On `Query` and `Mutation`
@@ -317,8 +371,9 @@ what every resolver shares.
 
 graphql-ruby keeps the Ruby side of each object type in `app/graphql/types`:
 `Types::PostType`, inheriting from `Types::BaseObject`, as `rails g graphql:object
-Post` writes it. Lighthouse keeps that structure. A type class that includes `Lighthouse::GraphQL::Type` is handed to
-Lighthouse: the SDL still declares the type and its fields, and the class says how
+Post` writes it. Lighthouse keeps that structure. A type class that includes
+`Lighthouse::GraphQL::Type` is handed to Lighthouse. After `lighthouse:install`,
+`Types::BaseObject` includes it, so every type class does: the SDL still declares the type and its fields, and the class says how
 the fields with no resolving directive resolve. A field calls the method of its
 snake_case name, when the class defines it. Fields it does not define are read off
 the object, as before, and fields with a resolving directive keep it.
@@ -343,8 +398,6 @@ type ReadingTime {
 # app/graphql/types/post_type.rb
 module Types
   class PostType < BaseObject
-    include Lighthouse::GraphQL::Type
-
     def reading_time
       { words: object.body.to_s.split.size }
     end
@@ -354,8 +407,6 @@ end
 # app/graphql/types/reading_time_type.rb
 module Types
   class ReadingTimeType < BaseObject
-    include Lighthouse::GraphQL::Type
-
     def minutes(words_per_minute:)
       [(object[:words] / words_per_minute.to_f).ceil, 1].max
     end
@@ -403,9 +454,11 @@ interface to `Article` ([types.md](types.md#the-default)).
 
 The class is the type's name plus `Type`, looked up in `namespaces[:types]`
 (default `['Types']`) when the schema is built. Only a class that includes
-`Lighthouse::GraphQL::Type` counts: any other `Types::PostType`, such as the ones
-a graphql-ruby app already has, is left alone, and its methods resolve nothing.
-Include the concern in `Types::BaseObject` to hand every type class over at once.
+`Lighthouse::GraphQL::Type` counts: any other `Types::PostType` is left alone, and
+its methods resolve nothing. `lighthouse:install` includes the concern in
+`Types::BaseObject`, `BaseInterface`, `BaseUnion` and `BaseScalar`, which hands every
+type class over at once. In an app that did not run it, include the concern in
+those bases, or in each type class (`include Lighthouse::GraphQL::Type`).
 
 A class that includes the concern must inherit from the schema's
 `base_types[:object]` when one is given, or the schema does not build. The concern
@@ -413,9 +466,9 @@ also hands over the classes of unions, interfaces and scalars, which pick the ty
 of a union's values or coerce a scalar's: see [types.md](types.md). It is not the schema's type: it only lends its
 methods. Fields are declared in the SDL, so `field` declarations in it are ignored,
 and graphql-ruby's type-level `authorized?` does not run; authorize with
-[`@can*`](authorization.md). `Query`, `Mutation` and `Subscription` fields resolve
-with their own classes, [by convention](#resolution-by-convention), not with a type
-class.
+[`@can*`](authorization.md). `Query` and `Mutation` are the exception: they are
+built on their [root type classes](#root-type-classes), whose `field`s count.
+`Subscription` fields resolve with their own classes.
 
 ### `@spread` and `@inject`
 
@@ -476,18 +529,18 @@ end
 ## Generators
 
 ```shell
-bin/rails generate lighthouse:query LatestPosts        # app/graphql/resolvers/latest_posts.rb
-bin/rails generate lighthouse:mutation PublishPost     # app/graphql/mutations/publish_post.rb
 bin/rails generate lighthouse:subscription PostUpdated # app/graphql/subscriptions/post_updated.rb
 bin/rails generate lighthouse:builder Published        # app/graphql/builders/published.rb
 bin/rails generate lighthouse:validator CreatePostInput # app/graphql/validators/create_post_input_validator.rb
-bin/rails generate graphql:object Post                 # a type class: then include Lighthouse::GraphQL::Type
+bin/rails generate graphql:object Post                 # a type class, Lighthouse's through Types::BaseObject
+bin/rails generate graphql:mutation PublishPost        # a code-first mutation, a field of Types::MutationType
 ```
 
-Each writes the class with its contract, into the first namespace configured for its
-kind (or `--namespace=…`), inheriting from the namespace's base class. Type classes
-come from graphql-ruby's own `graphql:object`, `graphql:scalar`, `graphql:union` and
-`graphql:interface`. [generators.md](generators.md) has what each generator writes,
+Each Lighthouse generator writes the class with its contract, into the first
+namespace configured for its kind (or `--namespace=…`). Type classes come from
+graphql-ruby's own `graphql:object`, `graphql:scalar`, `graphql:union` and
+`graphql:interface`. A resolver class has no generator, as in graphql-ruby: write
+it by hand, as above. [generators.md](generators.md) has what each generator writes,
 and which of graphql-ruby's fit a Lighthouse app.
 
 ## Changing the namespaces