lighthouse-graphql 0.3.0 → 0.5.0

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)
 
@@ -75,16 +67,48 @@ argument (the `@eq` makes `id` a filter). Lighthouse infers the model from the
 field's return type name (`User`), or you can be explicit with
 `@all(model: "User")`.
 
-## 2. Provide your base types
+## 2. Provide your base classes
 
-Lighthouse builds on graphql-ruby, so you supply the base classes it should use
-for objects, interfaces, etc. — exactly the place to mix in Apollo Federation or
-any custom field/argument behavior.
+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:`):
+
+```shell
+bin/rails generate graphql:install --no-relay --skip-graphiql
+```
 
 ```ruby
-# app/graphql/base_object.rb
-class BaseObject < GraphQL::Schema::Object
-  # include ApolloFederation::Object   # if you use federation
+# 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
+    field_class Types::BaseField
+    object_class Types::BaseObject
+  end
+end
+
+# app/graphql/subscriptions/base_subscription.rb — Subscription fields
+module Subscriptions
+  class BaseSubscription < GraphQL::Schema::Subscription
+    include Lighthouse::GraphQL::Subscription
+  end
+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
 ```
 
@@ -98,13 +122,22 @@ AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
   sdl_folder: Rails.root.join('graphql').to_s,
   options: {
     base_types: {
-      object: BaseObject,
+      resolver: Resolvers::BaseResolver,
+      mutation: Mutations::BaseMutation,
+      subscription: Subscriptions::BaseSubscription,
+      object: Types::BaseObject,
       # interface:, union:, enum:, input_object:, scalar: ...
     }
   }
 )
 ```
 
+`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).
+
 `get_schema` returns a `GraphQL::Schema` subclass you can use directly, or
 subclass further (e.g. to add federation, tracing, a Dataloader):
 
@@ -247,18 +280,19 @@ type User {
 }
 ```
 
-## Custom queries and mutations
+## Custom resolvers 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).
+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
+[resolvers.md](resolvers.md).
 
 ## Next steps
 
 - [Directives reference](directives.md) — the full vocabulary.
-- [Queries, mutations & builders](resolvers.md), [Mutations](mutations.md),
+- [Resolvers, 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.

data/docs/motivation.md

@@ -151,8 +151,9 @@ Schema-first doesn't mean schema-only. When a field does something no directive
 describes, write Ruby, using graphql-ruby's own classes:
 
 - A `Query` or `Mutation` field without a resolving directive resolves by convention to
-  `Queries::FieldName` (a `GraphQL::Schema::Resolver`) or `Mutations::FieldName` (a
-  `GraphQL::Schema::Mutation`). See [Queries, Mutations and Builders](resolvers.md).
+  `Resolvers::FieldName` (a `Resolvers::BaseResolver`) or `Mutations::FieldName` (a
+  `Mutations::BaseMutation`), under the base classes graphql-ruby's convention gives
+  each kind. See [Resolvers, Mutations and Builders](resolvers.md).
 - `@builder` classes adjust a query; `@validator` contracts check arguments.
 - Your own directives plug in through the registry, with the same contracts as the
   built-in ones. See [Custom Directives](custom-directives.md).

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
+```