lighthouse-graphql 0.4.0 → 0.5.0

data/docs/generators.md

@@ -0,0 +1,82 @@
+# 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 base classes (`Types::BaseObject`, `Resolvers::BaseResolver`,
+`Mutations::BaseMutation`, ...) come from graphql-ruby's own `graphql:install`.
+
+## `lighthouse:install`
+
+```shell
+bin/rails generate lighthouse:install
+```
+
+It runs graphql-ruby's install first
+(`graphql:install --no-relay --skip-graphiql --skip-query-logs`), which writes:
+
+- `app/graphql/types/base_*.rb`: `BaseObject`, `BaseField`, `BaseArgument`,
+  `BaseInterface`, `BaseUnion`, `BaseScalar`, `BaseEnum`, `BaseInputObject`;
+- `app/graphql/resolvers/base_resolver.rb` and `app/graphql/mutations/base_mutation.rb`;
+- its schema class, `Types::QueryType`, `Types::MutationType` and controller, and the
+  `POST /graphql` route.
+
+Then Lighthouse puts its own on top of what graphql-ruby wrote in that run:
+
+| File | What Lighthouse does |
+| --- | --- |
+| `app/graphql/app_schema.rb` | Replaced by the schema built from the SDL, naming every base class in `base_types` |
+| `app/controllers/graphql_controller.rb` | Replaced by one including `Lighthouse::GraphQL::Controller` |
+| `app/graphql/types/query_type.rb`, `mutation_type.rb` | Removed: the SDL declares the root types |
+| `app/graphql/mutations/base_mutation.rb` | Made a `GraphQL::Schema::Mutation`: the SDL declares a mutation's arguments, where graphql-ruby's `RelayClassicMutation` takes a single `input:` |
+| `app/graphql/subscriptions/base_subscription.rb` | Written: graphql-ruby has no subscription base. It includes `Lighthouse::GraphQL::Subscription` |
+| `config/initializers/lighthouse.rb` | Written: 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 |
+
+| 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 (graphql-ruby's are removed too) — for apps that serve GraphQL themselves |
+| `--skip-ide` | No `graphql.config.yml` or `.gitignore` entries |
+| `--force` | Replace a schema class or controller the app had before |
+
+Rerunning it is safe: a file the app has is kept, and the route and `.gitignore`
+entries are added once. In an app that already had a graphql-ruby schema class or
+controller, those are kept (Lighthouse replaces only what graphql-ruby wrote in the
+same run), and graphql-ruby's install points that schema at the root types it
+wrote: have the controller call `AppSchema.execute(...)` to serve Lighthouse's
+schema, or pass `--force`.
+
+## 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:query LatestPosts` | `Resolvers::LatestPosts < BaseResolver`, which `Query.latestPosts` resolves to by convention |
+| `lighthouse:mutation PublishPost` | `Mutations::PublishPost < BaseMutation`, for `Mutation.publishPost` |
+| `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` |
+
+The class's arguments and return type are the SDL's, so it declares neither. When
+the base class is missing (an app that never ran an install, or a namespace of its
+own such as `Api::Resolvers`), the generator says so: `lighthouse:install` writes it
+through graphql-ruby, or write `Api::Resolvers::BaseResolver` yourself.
+
+## graphql-ruby's generators in a Lighthouse app
+
+| Generator | In a Lighthouse app |
+| --- | --- |
+| `graphql:install` | Run by `lighthouse:install`. On its own, it writes a code-first schema, root types and a `RelayClassicMutation` base: run `lighthouse:install` instead |
+| `graphql:object Post` | **Use it** for a [type class](resolvers.md#type-classes): add `include Lighthouse::GraphQL::Type`, then 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): add `include Lighthouse::GraphQL::Type`; 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 `include Lighthouse::GraphQL::Type` and a `resolve_type`. Its `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`, `graphql:mutation_create` / `_update` / `_delete` | **Not ready**: they add a field to `Types::MutationType`, which a Lighthouse app has none of (they write it again), and write a `RelayClassicMutation` taking `input:`. Use `lighthouse:mutation`, or [`@create`, `@update`, `@delete`](mutations.md) |
+| `graphql:relay` | Not needed: [`@node`, `@globalId`](relay.md) and `@paginate(type: CONNECTION)` |
+| `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 edits a `class AppSchema < GraphQL::Schema`, which Lighthouse's `AppSchema = get_schema(...)` is not. Add its migration and `AppSchema.use(GraphQL::Tracing::DetailedTrace)` by hand |

data/docs/getting-started.md

@@ -24,32 +24,24 @@ 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 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:
 
 | 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/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) |
 
-| 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`, `--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).
+[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,19 +71,22 @@ 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` 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:`):
 
-```ruby
-# app/graphql/resolvers/base_resolver.rb       — Query fields (Resolvers::LatestPosts)
-module Resolvers
-  class BaseResolver < GraphQL::Schema::Resolver
-  end
-end
+```shell
+bin/rails generate graphql:install --no-relay --skip-graphiql
+```
 
+```ruby
 # app/graphql/mutations/base_mutation.rb       — Mutation fields (Mutations::PublishPost)
 module Mutations
-  class BaseMutation < GraphQL::Schema::Mutation
+  class BaseMutation < GraphQL::Schema::Mutation   # graphql-ruby writes RelayClassicMutation
+    argument_class Types::BaseArgument
+    field_class Types::BaseField
+    object_class Types::BaseObject
   end
 end
 
@@ -103,14 +98,15 @@ 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.
+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

data/docs/relationships.md

@@ -31,6 +31,10 @@ The `morph*` names are PHP Lighthouse's. ActiveRecord resolves polymorphic
 associations the same way as any other, so they behave exactly like their
 non-polymorphic counterparts. Use whichever reads better.
 
+`@hasMany` and `@hasOne` resolve `has_many` / `has_one :through` associations as
+they are. PHP Lighthouse's `@hasManyThrough` and `@hasOneThrough` work too, as
+aliases, so an SDL written for it builds unchanged.
+
 ## Avoiding the N+1 problem
 
 The relationship directives load through graphql-ruby's **Dataloader** and
@@ -50,6 +54,44 @@ the Dataloader, the directives still work, but they load one parent at a time.
 A field with `scopes:` or a filter argument the client supplied runs its own query
 per parent, because each parent's query differs.
 
+## Eager loading for other fields
+
+The relationship directives load their own association. Three directives load for
+the fields that only read one: a method, a type class method, a field read off
+the model. Each one loads across every parent in the response at once, through the
+Dataloader:
+
+- `@with(relation: "tasks")` loads a relation of the parent before the field
+  resolves. `user.tasks` is then in memory for the method that reads it.
+- `@withCount(relation: "posts")` counts a relation for every parent in one
+  `GROUP BY` query, and keeps each count on its parent as `<relation>_count`, as
+  Laravel's `withCount` does. It is not the field's value: the field's resolver,
+  or the default reader of a `postsCount` field, reads `user.posts_count`.
+- `@lazyLoad(relations: ["tags"])` loads relations of the records the field
+  returns: a list, a relation, a `@paginate` page. On a `@hasMany`, the records of
+  every parent load their relations together.
+
+```graphql
+type User {
+  latestPostTitle: String @with(relation: "posts") @method
+  usage: String! @withCount(relation: "posts", scopes: ["published"]) @method
+  posts: [Post!]! @hasMany @lazyLoad(relations: ["tags"])
+}
+```
+
+```ruby
+class User < ApplicationRecord
+  def latest_post_title = posts.max_by(&:created_at)&.title
+  def usage = "#{posts_count} published posts"
+end
+```
+
+Relations may be nested with dots (`"posts.comments"`), and `scopes` narrow what is
+loaded or counted, as model scopes. A count loads in one query when the database has
+window functions and the relation links its parent through one column, as a
+[paginated relation](#paginating-many-parents-at-once) does; otherwise once per
+parent.
+
 ## Lists, and paginating them
 
 Collection directives return a **plain list**, as in PHP Lighthouse:

data/docs/relay.md

@@ -0,0 +1,137 @@
+# Relay: Global Object Identification
+
+Relay clients refetch any object by one opaque id, through a root `node` field.
+Lighthouse gives a schema that, as [PHP Lighthouse](https://lighthouse-php.com/master/digging-deeper/relay.html)
+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).
+
+## Global ids
+
+`@globalId` on a field encodes its value with the type's name:
+
+```graphql
+type User {
+  id: ID! @globalId
+  name: String
+}
+```
+
+`{ user(id: 1) { id } }` answers `"VXNlcjox"`, the base64 of `User:1`.
+
+On an argument, or an input field, `@globalId` decodes what the client sent before
+the field resolves, so every resolver (a directive, `@field`, a `Resolvers::` class)
+gets the decoded value. `decode:` says which part:
+
+| `decode:` | The resolver gets |
+| --- | --- |
+| `ARRAY` (default) | `["User", "1"]` |
+| `TYPE` | `"User"` |
+| `ID` | `"1"` |
+
+```graphql
+type Query {
+  user(id: ID! @globalId(decode: ID) @eq): User @find
+}
+
+type Mutation {
+  deleteNode(id: ID! @globalId): Node
+}
+```
+
+Lists of ids decode item by item. A value that is not a global id makes the field
+fail with `"…" is not a valid global id.`
+
+## Nodes
+
+`@node` registers a type for refetching:
+
+```graphql
+type User @node {
+  id: ID! @globalId
+  name: String
+}
+```
+
+and adds what Relay expects, leaving alone whatever the SDL declares itself:
+
+```graphql
+"Any object implementing this type can be found by ID through `Query.node`."
+interface Node {
+  "Global identifier that can be used to resolve any Node implementation."
+  id: ID!
+}
+
+type User implements Node @node { ... }
+
+type Query {
+  "Fetches an object given its globally unique `ID`."
+  node(id: ID! @globalId): Node
+}
+```
+
+```graphql
+{
+  node(id: "VXNlcjox") {
+    id
+    ... on User { name }
+  }
+}
+```
+
+The type keeps its own `id: ID! @globalId`, which encodes the ids `node` decodes.
+`node` answers `null` for an id with no object, and an error for the id of a type
+without `@node`.
+
+### Where the object comes from
+
+1. `@node(resolver: "Countries@by_code")` names a class, and a method after the `@`
+   (`call` without one). It gets the decoded id and the context, and returns any
+   object, a Hash included:
+
+   ```graphql
+   type Country @node(resolver: "Countries@by_code") {
+     id: ID! @globalId
+     name: String!
+   }
+   ```
+
+   ```ruby
+   class Resolvers::Countries
+     COUNTRIES = { 'DE' => { id: 'DE', name: 'Germany' } }.freeze
+
+     def self.by_code(id, _context) = COUNTRIES[id]
+   end
+   ```
+
+   The class is looked up as `@field` looks one up on a type: in the resolvers
+   namespace, then in [`resolver_namespaces`](configuration.md#resolver_namespaces).
+2. `@node(model: "Account")` names the model.
+3. Otherwise, the type's [`@model`](directives.md#model), or the model named
+   after the type.
+
+A model's record is found by its primary key, through graphql-ruby's Dataloader, so
+several `node` fields in one query load together.
+
+To give `Query.node` your own description or middleware, declare it, with the
+registry Lighthouse uses:
+
+```graphql
+type Query {
+  "This description is up to you."
+  node(id: ID! @globalId): Node
+    @field(resolver: "Lighthouse::GraphQL::NodeRegistry@resolve")
+    @guard
+}
+```
+
+## Your own encoding
+
+[`global_id`](configuration.md#global_id) takes any object with
+`encode(type, id)` and `decode(global_id)`, which returns `[type, id]`:
+
+```ruby
+Lighthouse.configure do |config|
+  config.global_id = MyGlobalIds   # e.g. signed, or a UUID lookup
+end
+```