lighthouse-graphql 0.5.0 → 0.7.0

data/docs/getting-started.md

@@ -24,29 +24,32 @@ 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/schema.graphql` | The schema's entrypoint: a starter schema (`user` via `@find`, `users` via `@paginate`) that assumes a `User` model. Skipped when the file exists |
 | `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`, `--schema-path=app/schema/schema.graphql`, `--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)
 
-By default Lighthouse loads every `*.graphql` file under `RAILS_ROOT/graphql`,
-sorted by path and concatenated. Split your schema however you like:
+Lighthouse reads the schema from one entrypoint, `RAILS_ROOT/graphql/schema.graphql`
+(`config.schema_path`), as PHP Lighthouse does:
 
 ```graphql
 # graphql/schema.graphql
@@ -67,29 +70,64 @@ 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")`.
 
+To split the schema, the entrypoint imports the other files. A type is defined
+once, and the other files add to it with `extend type`:
+
+```graphql
+# graphql/schema.graphql
+type Query
+
+#import user.graphql
+#import blog/*.graphql
+```
+
+```graphql
+# graphql/user.graphql
+type User {
+  id: ID!
+  name: String
+}
+
+extend type Query {
+  users: [User!]! @all
+}
+```
+
+A file nothing imports is not part of the schema, and a type defined twice is an
+error. See [schema-organisation.md](schema-organisation.md).
+
 ## 2. Provide your base classes
 
 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 +136,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.schema_path` and the files it imports
+(`get_schema(schema_path: ...)` 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
@@ -225,7 +286,9 @@ Your IDE validates and autocompletes `.graphql` files against the schema it can
 see. Lighthouse's directive definitions and the types its manipulation phase
 generates live in Ruby, so without help the IDE flags `@paginate` as unknown and
 can't resolve `UserPaginator`. PHP Lighthouse solves this with an IDE helper
-command; so does Lighthouse for Rails:
+command, and so does Lighthouse for Rails. In development, an app with a
+`graphql.config.yml` gets the files rewritten on boot and on every reload
+(`config.ide_helper`), so you never run it by hand there. Elsewhere:
 
 ```shell
 bin/rails lighthouse:ide_helper              # writes to Rails.root
@@ -239,8 +302,11 @@ It writes two files:
   declares (so the IDE never sees a duplicate).
 - **`programmatic-types.graphql`** — the types Lighthouse adds to the executable
   schema: `<Type>Paginator`, `<Type>SimplePaginator`, `<Type>Connection`/`Edge`,
-  `PaginatorInfo`, `SimplePaginatorInfo`, `PageInfo`, the `whereConditions`
-  inputs and enums, and the `_` placeholder scalar.
+  `PaginatorInfo`, `SimplePaginatorInfo`, `PageInfo`, the `@whereConditions` and
+  `@orderBy` inputs and enums, and the `_` placeholder scalar (without it, the
+  IDE reports `Unknown type "_"`). It leaves out every type the SDL or
+  `schema-directives.graphql` defines, because graphql-js, which the IDE plugins
+  use, rejects a type defined twice.
 
 Point your IDE's [graphql-config](https://the-guild.dev/graphql/config) at them
 next to your SDL — the install generator writes this `graphql.config.yml`:
@@ -254,7 +320,9 @@ schema:
 
 It works with the GraphQL plugin for JetBrains IDEs and the GraphQL extension for
 VS Code. The files are derived from your schema, so the generator adds them to
-`.gitignore`; rerun the task after changing the schema or registering a directive.
+`.gitignore`. Outside development, rerun the task after changing the schema or
+registering a directive. The IDE reads every `.graphql` file the glob matches, as
+one schema: it does not follow `#import`.
 
 > The IDE reads fields as you wrote them: `users: [User!]! @paginate` still looks
 > like a list to it, although clients query `users { data { … } }`. Field
@@ -286,7 +354,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/motivation.md

@@ -98,8 +98,9 @@ generated from Ruby classes:
 - **It is designed before it is implemented.** You can agree on the types and fields
   first, as a team, and the server follows the design rather than leaking its internals.
 - **Tools understand it directly.** IDE plugins, code generators and schema registries
-  read SDL. Lighthouse's `lighthouse:ide_helper` task adds its directives and generated
-  types so editors validate and autocomplete the schema.
+  read SDL. Lighthouse writes out its directives and generated types (in development
+  on every reload, or with `lighthouse:ide_helper`), so editors validate and
+  autocomplete the schema.
 - **It says what each field does.** `posts: [Post!]! @paginate @guard @cacheControl(maxAge: 60)`
   tells a reader, without opening any Ruby, that the field is paginated, requires a
   signed-in user and can be cached for a minute.

data/docs/performance.md

@@ -59,10 +59,11 @@ 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.
+edit only shows up after restarting the server. With it, the folder of
+`config.schema_path` joins `config.watchable_dirs`, and an edit to any `.graphql`
+file below it reloads the app, and with it the schema, on the next request, like
+a Ruby change. The reload also rewrites the IDE helper files (`config.ide_helper`). 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
@@ -173,7 +174,8 @@ queries:
 type User {
   publishedPosts(
     title: String @like
-    orderBy: [OrderByClause!] @orderBy
+    orderBy: _ @orderBy(columns: ["title", "created_at"])
+    where: _ @whereConditions(columns: ["title"])
   ): [Post!]! @hasMany(relation: "posts", scopes: ["published"])
 }
 ```

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