lighthouse-graphql 0.4.0 → 0.6.0

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,164 @@ 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`
+
+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
 }
 ```
 
+### `@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 +452,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 +514,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 +533,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 +580,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: "/", 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 {
+  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 —

data/docs/generators.md

@@ -0,0 +1,84 @@
+# Generators
+
+Lighthouse builds on graphql-ruby, and so do its generators: it writes only what
+graphql-ruby has no generator for, or what an SDL-first schema needs differently.
+Every graphql-ruby app's schema class and base classes (`Types::BaseObject`,
+`Resolvers::BaseResolver`, `Mutations::BaseMutation`, ...) come from graphql-ruby's
+own `graphql:install`, and `lighthouse:install` builds on them.
+
+## `lighthouse:install`
+
+```shell
+bin/rails generate graphql:install     # graphql-ruby's, with the options you choose
+bin/rails generate lighthouse:install
+```
+
+It works on what graphql-ruby's `graphql:install` wrote, with whichever of its
+options the app chose (`--relay`, the default, `--batch`, `--skip-mutation-root-type`,
+`--schema`, `--directory`, `--api`, ...). When the app has no graphql-ruby schema
+class yet, it runs `graphql:install` first, with graphql-ruby's defaults (and
+`--api` when `config.api_only = true`). Then it adapts what graphql-ruby wrote:
+
+| File | What Lighthouse does |
+| --- | --- |
+| `app/graphql/app_schema.rb` | `class AppSchema < GraphQL::Schema` becomes `class AppSchema < Lighthouse::GraphQL::RbLightHouse.get_schema(options: { base_types: { ... } })`, naming every class graphql-ruby wrote. The rest of the class stays, but the `query(...)` / `mutation(...)` lines (the SDL's root types are built on those classes) and the `resolve_type` stub (Lighthouse resolves types). With `--batch`, `use GraphQL::Dataloader` goes beside `use GraphQL::Batch`, as Lighthouse's directives batch through the Dataloader |
+| `app/graphql/types/query_type.rb`, `mutation_type.rb` | The example `test_field` goes. Relay's `node` / `nodes` stay: the SDL's `Query` is built on `Types::QueryType`, so its `field`s are the schema's too |
+| `app/graphql/types/base_object.rb`, `base_interface.rb`, `base_union.rb`, `base_scalar.rb` | `include Lighthouse::GraphQL::Type`: every type class inheriting from them is Lighthouse's, `Types::QueryType` and `Types::NodeType` included |
+| `app/graphql/mutations/base_mutation.rb` | Kept as graphql-ruby wrote it, a `RelayClassicMutation` (see [resolvers.md](resolvers.md#resolution-by-convention)) |
+| `app/controllers/graphql_controller.rb` | Replaced by one including `Lighthouse::GraphQL::Controller` (`lighthouse_schema AppSchema`), when it is still as graphql-ruby wrote it. One the app changed is kept, and the install says how to serve the schema |
+
+And it adds Lighthouse's own:
+
+| File | What it is |
+| --- | --- |
+| `config/initializers/lighthouse.rb` | Every [configuration](configuration.md) option, commented out |
+| `graphql/schema.graphql` | A starter schema, unless the folder holds `.graphql` files already |
+| `graphql.config.yml` | IDE configuration, and `.gitignore` entries for the [IDE helper](getting-started.md#ide-support) files |
+| `app/graphql/subscriptions/base_subscription.rb` | With `--subscriptions` only: graphql-ruby has no subscription base. It includes `Lighthouse::GraphQL::Subscription` |
+| `config/routes.rb` | `post "/graphql", to: "graphql#execute"`, when missing |
+
+| Option | Effect |
+| --- | --- |
+| `--schema=ApiSchema` | Which graphql-ruby schema class to adopt, and its name when `graphql:install` has to run |
+| `--sdl-folder=app/schema` | Where the `.graphql` files live (default `graphql`); sets `config.sdl_folder` |
+| `--subscriptions` | Write `Subscriptions::BaseSubscription` and name it in `base_types` |
+| `--skip-controller` | Leave graphql-ruby's controller as it is, and add no route — for apps that serve GraphQL themselves |
+| `--skip-ide` | No `graphql.config.yml` or `.gitignore` entries |
+
+Rerunning it changes nothing: a schema class that is Lighthouse's already, a file
+the app has, the route and the `.gitignore` entries are left as they are.
+
+## Lighthouse's generators
+
+For the classes graphql-ruby has no generator for, or none that fits an SDL-first
+schema. Each writes into the first namespace configured for its kind (or
+`--namespace=…`); namespaced names nest modules (`Blog::Publish`).
+
+| Generator | Writes |
+| --- | --- |
+| `lighthouse:subscription PostUpdated` | `Subscriptions::PostUpdated < BaseSubscription`, with its hooks (and the base, when missing) |
+| `lighthouse:builder Published` | `Builders::Published`, for `@builder(class: "Published")` |
+| `lighthouse:validator CreatePostInput` | `Validators::CreatePostInputValidator`, a `Dry::Validation::Contract` |
+
+A subscription's arguments and return type are the SDL's, so the class declares
+neither. When `Subscriptions::BaseSubscription` is missing, `lighthouse:subscription`
+writes it.
+
+A resolver or mutation class has no Lighthouse generator: write a
+`Resolvers::BaseResolver` subclass by hand (see [resolvers.md](resolvers.md)), add a
+method to `Types::QueryType`, or run graphql-ruby's `graphql:mutation`.
+
+## graphql-ruby's generators in a Lighthouse app
+
+| Generator | In a Lighthouse app |
+| --- | --- |
+| `graphql:install` | The base `lighthouse:install` builds on: run it first with the options you want, or let `lighthouse:install` run it with its defaults |
+| `graphql:object Post` | **Use it** for a [type class](resolvers.md#type-classes): it inherits from `Types::BaseObject`, so it is Lighthouse's; add methods. The `field` lines it writes (from the model's columns, when there is one) are ignored, as the SDL declares the fields: delete them |
+| `graphql:scalar DateTime` | **Use it** for a [scalar](types.md#scalars): its `coerce_input` / `coerce_result` are the ones Lighthouse calls |
+| `graphql:union SearchResult`, `graphql:interface Authored` | **Use them** when the [default resolution](types.md#the-default) is not enough: add a `resolve_type`. Their `possible_types` and `field` lines are ignored |
+| `graphql:enum`, `graphql:input` | Not needed: the SDL declares enums and inputs ([`@enum`](directives.md#enum) gives a value an internal one) |
+| `graphql:mutation PublishPost` | **Use it** for a code-first mutation: it writes `Mutations::PublishPost` and adds `field :publish_post, mutation: Mutations::PublishPost` to `Types::MutationType`, which the SDL's `Mutation` is built on. The class declares its own arguments and fields, as in graphql-ruby |
+| `graphql:mutation_create` / `_update` / `_delete` | Code-first mutations like `graphql:mutation`'s, whose payload and input are code-first types (`Types::PostType`, `Types::PostInputType`). For a type the SDL declares, use [`@create`, `@update`, `@delete`](mutations.md) |
+| `graphql:relay` | Run by `graphql:install` (`--relay` is its default). On an app installed with `--no-relay`, it adds `Types::NodeType`, `node` / `nodes` and the schema's `id_from_object` / `object_from_id`: add `node: Types::NodeType` to `base_types` by hand. See [relay.md](relay.md#relay-through-graphql-ruby) |
+| `graphql:loader` | A GraphQL::Batch loader, which your own resolver classes may use; Lighthouse's directives batch through graphql-ruby's Dataloader instead |
+| `graphql:detailed_trace` | **Not ready**: it looks for `class AppSchema < GraphQL::Schema`, which a Lighthouse schema class (`< Lighthouse::GraphQL::RbLightHouse.get_schema(...)`) does not match, and stops. Add `use GraphQL::Tracing::DetailedTrace` and `def self.detailed_trace?(query)` to the class body by hand, with graphql-ruby's migration (or `redis:`) |

data/docs/getting-started.md

@@ -24,32 +24,27 @@ a hard dependency of Lighthouse so non-federated apps stay lean.
 bin/rails generate lighthouse:install
 ```
 
-does steps 1–5 below for you:
+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, 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.
+`--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.
 
 ## 1. Write your schema (SDL)
 
@@ -79,22 +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. `rails g lighthouse:install` writes the bases of the classes that resolve
-root fields:
+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
+```
+
+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/resolvers/base_resolver.rb       — Query fields (Resolvers::LatestPosts)
-module Resolvers
-  class BaseResolver < GraphQL::Schema::Resolver
+# 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
+    # include ApolloFederation::Object   # if you use federation
   end
 end
+```
 
-# app/graphql/mutations/base_mutation.rb       — Mutation fields (Mutations::PublishPost)
-module Mutations
-  class BaseMutation < GraphQL::Schema::Mutation
-  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
@@ -103,61 +110,85 @@ module Subscriptions
 end
 ```
 
-The SDL's types can have graphql-ruby base classes too, as `graphql:install`
-writes them: 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
-    # 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
@@ -290,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