lighthouse-graphql 0.4.0 → 0.6.0

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

@@ -31,16 +31,21 @@ 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
 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
@@ -50,6 +55,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,200 @@
+# 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).
+
+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:
+
+```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
+}
+```
+
+## 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
+`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
+```