lighthouse-graphql 0.3.0 → 0.5.0

data/docs/subscriptions.md

@@ -6,9 +6,12 @@ happens. Lighthouse builds on [graphql-ruby's subscriptions](https://graphql-rub
 and keeps the shape of [PHP Lighthouse's](https://lighthouse-php.com/master/subscriptions/getting-started.html):
 
 - a `Subscription` field is declared in the SDL, and **resolves by convention** to a class;
-- that class is a plain graphql-ruby [`GraphQL::Schema::Subscription`](https://graphql-ruby.org/subscriptions/subscription_classes.html),
-  as a query is a `GraphQL::Schema::Resolver` and a mutation a `GraphQL::Schema::Mutation`
-  (see [resolvers.md](resolvers.md));
+- that class inherits from `Subscriptions::BaseSubscription`, a graphql-ruby
+  [`GraphQL::Schema::Subscription`](https://graphql-ruby.org/subscriptions/subscription_classes.html),
+  as a `Query` field's class is a `Resolvers::BaseResolver` and a mutation's a
+  `Mutations::BaseMutation` (see [resolvers.md](resolvers.md#base-classes)). The base
+  includes [Lighthouse's concern](#the-subscription-concern): PHP
+  Lighthouse's model, one topic per field and a `filter?`;
 - a mutation announces what it did with [`@broadcast`](#broadcast-from-a-mutation).
 
 ```graphql
@@ -23,10 +26,10 @@ type Mutation {
 
 ```ruby
 # app/graphql/subscriptions/post_updated.rb  (rails generate lighthouse:subscription PostUpdated)
-class Subscriptions::PostUpdated < GraphQL::Schema::Subscription
-  # Runs for each update: skip the subscribers who may not see this post.
-  def update(**)
-    object.published? || object.author == context[:current_user] ? object : NO_UPDATE
+class Subscriptions::PostUpdated < Subscriptions::BaseSubscription
+  # For each broadcast: skip the subscribers who may not see this post.
+  def filter?(post, **)
+    post.published? || post.author == context[:current_user]
   end
 end
 ```
@@ -94,12 +97,14 @@ type Subscription {
 }
 ```
 
-For anything more, write the class (a field with no class of its own behaves like
-the concern's field-wide topic with no `filter?`). `Subscription.postUpdated` resolves to
+For anything more, write the class. (A field with no class of its own resolves with
+the schema's `base_types[:subscription]`, else with a built-in class that includes
+the concern: one topic for the field, no `filter?`.) `Subscription.postUpdated` resolves to
 `Subscriptions::PostUpdated`, looked up in `Config.namespaces[:subscriptions]`
 (default `['Subscriptions']`) each time it is needed, so code reloading works.
 `rails generate lighthouse:subscription PostUpdated` writes it. It inherits from
-`GraphQL::Schema::Subscription`: anything you know from graphql-ruby applies.
+`Subscriptions::BaseSubscription`, a `GraphQL::Schema::Subscription`: anything you
+know from graphql-ruby applies.
 
 Like a query or a mutation class, it declares neither the arguments nor the return
 type: the SDL does. The field's arguments arrive as `snake_case` keywords.
@@ -109,7 +114,10 @@ type: the SDL does. The field's arguments arrive as `snake_case` keywords.
 graphql-ruby calls the class twice in a subscription's life: once for the
 **subscription request** (the client's `subscription { ... }`), and then once for
 **each update** (`@broadcast`, or `schema.subscriptions.trigger`). All hooks are
-optional.
+optional. These are graphql-ruby's own; the concern `BaseSubscription` includes
+implements `authorized?` and `update` with PHP Lighthouse's hooks
+([below](#the-subscription-concern)), and a class that defines them itself
+keeps graphql-ruby's behavior.
 
 | Hook | Called | Default |
 | --- | --- | --- |
@@ -135,7 +143,7 @@ optional.
   field comes back `null`, with no error.
 
 ```ruby
-class Subscriptions::OrderShipped < GraphQL::Schema::Subscription
+class Subscriptions::OrderShipped < Subscriptions::BaseSubscription
   def authorized?(**)
     raise GraphQL::ExecutionError, 'Sign in to follow your orders.' unless context[:current_user]
 
@@ -145,8 +153,6 @@ class Subscriptions::OrderShipped < GraphQL::Schema::Subscription
   def update(**)
     object.user_id == context[:current_user].id ? object : NO_UPDATE
   end
-
-  def self.trigger_arguments(_order, _context) = {}
 end
 ```
 
@@ -164,22 +170,32 @@ If you know PHP Lighthouse's `GraphQLSubscription`, this is where its methods we
 One real difference is the **topic**. PHP Lighthouse puts every subscriber of a
 field on one topic and `filter` decides who is updated. graphql-ruby's default
 topic includes the arguments, so a trigger reaches only the subscribers whose
-arguments *equal* its own. That is why `@broadcast` asks a plain class for its
-`trigger_arguments`; see [below](#topics-trigger-arguments-and-filtering).
+arguments *equal* its own. The concern in `BaseSubscription` takes PHP Lighthouse's
+topic; a class that keeps graphql-ruby's gives `@broadcast` its `trigger_arguments`.
+See [below](#topics-trigger-arguments-and-filtering).
 
-## Lighthouse's subscription concern
+## The subscription concern
 
-If you prefer PHP Lighthouse's model, with one topic per field, `filter?` to narrow
-it and `resolve_payload` for the result, include `Lighthouse::GraphQL::Subscription`
-in the class, as `include Lighthouse::GraphQL::Controller` gives a controller its
-`execute`. The class is still a plain `GraphQL::Schema::Subscription`, and declares
-its arguments as one would in graphql-ruby (or leaves them to the SDL).
-`rails generate lighthouse:subscription PostUpdated --lighthouse` writes it:
+`Lighthouse::GraphQL::Subscription` is PHP Lighthouse's model: one topic per field,
+`filter?` to narrow it and `resolve_payload` for the result. It is included once, in
+the base every subscription inherits from, as graphql-ruby's convention puts what
+all classes of a kind share in their base:
 
 ```ruby
-class Subscriptions::PostUpdated < GraphQL::Schema::Subscription
-  include Lighthouse::GraphQL::Subscription
+# app/graphql/subscriptions/base_subscription.rb  (rails generate lighthouse:install)
+module Subscriptions
+  class BaseSubscription < GraphQL::Schema::Subscription
+    include Lighthouse::GraphQL::Subscription
+  end
+end
+```
+
+A subscription is still a plain `GraphQL::Schema::Subscription`, and declares its
+arguments as one would in graphql-ruby (or leaves them to the SDL).
+`rails generate lighthouse:subscription PostUpdated` writes one with the hooks:
 
+```ruby
+class Subscriptions::PostUpdated < Subscriptions::BaseSubscription
   def filter?(post, author: nil)
     author.nil? || post.author_id.to_s == author.to_s
   end
@@ -205,17 +221,19 @@ optional.
   [broadcast section](#topics-trigger-arguments-and-filtering) explain.
 - Including it in a class that is not a `GraphQL::Schema::Subscription` raises a
   `Lighthouse::DefinitionError`.
+- To keep graphql-ruby's model for every subscription, leave the `include` out of
+  `BaseSubscription`; the generator then writes classes with `authorized?` and
+  `update` instead.
 - **Precedence.** The concern sits between your class and
-  `GraphQL::Schema::Subscription`, so what the class defines itself wins. A class
+  `GraphQL::Schema::Subscription` (it is in the base), so what the class defines
+  itself wins. A class
   with its own `update` (or `authorized?`) is called instead of the concern's, and
   its `filter?`, `resolve_payload` (or `authorize?`) are not, unless it calls
   `super`. `subscribe`, `unsubscribe`, `subscription_scope` and `ready?` are
   untouched, and combine freely with the hooks.
 
 ```ruby
-class Subscriptions::OrderShipped < GraphQL::Schema::Subscription
-  include Lighthouse::GraphQL::Subscription
-
+class Subscriptions::OrderShipped < Subscriptions::BaseSubscription
   def authorize?(**)
     context[:current_user].present?
   end
@@ -251,8 +269,9 @@ type Subscription {
 
 The name is looked up in `Config.namespaces[:subscriptions]` like the conventional
 one, so `class: "PostUpdated"` finds `Subscriptions::PostUpdated`, and a name with
-`::` is used as it is. A class that does not exist, or is not a
-`GraphQL::Schema::Subscription`, raises `Lighthouse::DefinitionError`.
+`::` is used as it is. A class that does not exist, is not a
+`GraphQL::Schema::Subscription`, or does not inherit from the schema's
+`base_types[:subscription]` raises `Lighthouse::DefinitionError`.
 `@guard`, `@can*` and the other wrapping directives work on a subscription field
 as on any other.
 
@@ -303,7 +322,8 @@ arguments (a Hash, `{}` by default) for the `root` a mutation returned, and
 `subscription_scope` (graphql-ruby's way to give each tenant or user their own
 stream).
 
-With a plain `GraphQL::Schema::Subscription`:
+When the topic includes the arguments (a class with `topic_by :arguments`, or under
+a base that does not include the concern):
 
 - **A field without arguments works out of the box.** Every subscriber's arguments
   are `{}`, and so is the trigger's.
@@ -317,7 +337,9 @@ With a plain `GraphQL::Schema::Subscription`:
   ```
 
   ```ruby
-  class Subscriptions::MessagePosted < GraphQL::Schema::Subscription
+  class Subscriptions::MessagePosted < Subscriptions::BaseSubscription
+    topic_by :arguments
+
     # The subscribers of `messagePosted(room: "<id>")`.
     def self.trigger_arguments(message, _context) = { room: message.room_id.to_s }
   end
@@ -336,11 +358,11 @@ With a plain `GraphQL::Schema::Subscription`:
   those subscribers are updated, so give such a class a `trigger_arguments` too if
   subscribers pass the argument.
 - **To have one trigger reach subscribers with different arguments** (the argument
-  is a filter, not an identity), give the class one topic per field, as
-  graphql-ruby documents, and let `update` return `NO_UPDATE`:
+  is a filter, not an identity) without the concern, give the class one topic per
+  field, as graphql-ruby documents, and let `update` return `NO_UPDATE`:
 
   ```ruby
-  class Subscriptions::PostPublished < GraphQL::Schema::Subscription
+  class Subscriptions::PostPublished < Subscriptions::BaseSubscription # a base without the concern
     def self.topic_for(field:, scope:, **)
       GraphQL::Subscriptions::Serialize.dump_recursive([scope, field.graphql_name])
     end
@@ -417,7 +439,8 @@ the repository's own specs do, in `spec/support/in_memory_subscriptions.rb`.
 graphql-ruby also ships `GraphQL::Testing::MockActionCable` for the real
 ActionCable backend.
 
-The repository's `example/` app is a complete setup: plain subscription classes,
+The repository's `example/` app is a complete setup: subscription classes under
+`Subscriptions::BaseSubscription`,
 `GraphqlChannel`, `ApplicationCable::Connection` with token authentication, and
 specs that drive a mutation through `POST /graphql` and watch the update arrive on
 an ActionCable subscriber (`example/spec/subscriptions/delivery_spec.rb`).

data/docs/types.md

@@ -0,0 +1,219 @@
+# Unions, Interfaces and Scalars
+
+The SDL declares every type. Object types resolve their fields through
+directives, the default reader, or a [type class](resolvers.md#type-classes).
+Three more kinds need Ruby to say how their values work:
+
+- a **union** or an **interface** needs to know which object type each value is;
+- a custom **scalar** needs to know how to read its values from a query and write
+  them to a response.
+
+Lighthouse answers both as [PHP Lighthouse](https://lighthouse-php.com/master/the-basics/types.html)
+does by default, and lets you take over with a class, in graphql-ruby's
+`app/graphql/types` structure, or with a directive.
+
+## Unions and interfaces
+
+```graphql
+type Query {
+  search(term: String!): [SearchResult!]!
+  latestActivity: [Authored!]!
+}
+
+union SearchResult = Post | User
+
+interface Authored {
+  id: ID!
+  author: User!
+}
+
+type Post implements Authored { id: ID! title: String! author: User! }
+type Comment implements Authored { id: ID! body: String! author: User! }
+```
+
+A resolver returns records, of any of the types:
+
+```ruby
+class Resolvers::Search < Resolvers::BaseResolver
+  def resolve(term:)
+    Post.where('title LIKE ?', "%#{term}%").to_a + User.where('name LIKE ?', "%#{term}%").to_a
+  end
+end
+```
+
+```graphql
+{
+  search(term: "Grace") {
+    __typename
+    ... on Post { title }
+    ... on User { name }
+  }
+}
+```
+
+### The default
+
+Each value resolves to the first of these that is one of the union's (or the
+interface's) types:
+
+1. a Hash's `__typename` (`{ __typename: 'Movie', title: 'Heat' }`);
+2. the type named after the value's class (a `Post` record is a `Post`), or after
+   one of its superclasses, so an `Admin < User` STI record is a `User` when no
+   `Admin` type exists;
+3. the type whose [`@model`](directives.md#model) names the value's model. With
+   `type Article @model(class: "Post")`, a `Post` record is an `Article`.
+
+Most schemas need nothing else.
+
+### A type class
+
+When the default is not enough, say when the values are Hashes from a search
+service rather than records, write the union's class as graphql-ruby does
+(`rails g graphql:union SearchResult`),
+`Types::<Name>Type` including `Lighthouse::GraphQL::Type`, with `resolve_type`.
+It returns a type name, or a type class, which stands for the SDL type of its
+`graphql_name`:
+
+```ruby
+# app/graphql/types/search_result_type.rb
+module Types
+  class SearchResultType < BaseUnion
+    include Lighthouse::GraphQL::Type
+
+    def self.resolve_type(object, context)
+      return unless object.is_a?(Hash)
+
+      object['index'] == 'users' ? Types::UserType : 'Post'
+    end
+  end
+end
+```
+
+An interface's goes in graphql-ruby's `definition_methods`:
+
+```ruby
+# app/graphql/types/authored_type.rb
+module Types
+  module AuthoredType
+    include BaseInterface
+    include Lighthouse::GraphQL::Type
+
+    definition_methods do
+      def resolve_type(object, context)
+        object['index'] == 'comments' ? 'Comment' : 'Post' if object.is_a?(Hash)
+      end
+    end
+  end
+end
+```
+
+`nil` leaves the value to the default, so the class only handles the cases that
+need it. The SDL still declares the members: `possible_types` in the class are
+ignored.
+
+### `@union` and `@interface`
+
+PHP Lighthouse's directives name the class in the schema instead. It has
+`resolve_type(object, context)` or `call(object, context)`, and is 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! }
+```
+
+The directive comes first, then the type class, then the default.
+
+### When nothing resolves a value
+
+A value no step resolves, or one resolved to a type the union or interface does
+not include, raises `Lighthouse::DefinitionError`. It is a server bug, not a client
+error, and the message names the ways out:
+
+```text
+Lighthouse could not tell the type of a Tag in the union SearchResult (Post | User):
+name a type after its class, map one to it with @model(class: "Tag"), or resolve
+it in Types::SearchResultType.resolve_type or with @union(resolveType:).
+```
+
+A `@union` or `@interface` naming no class, or a type class of another kind than
+its SDL type (a union class for an interface), fails when the schema is built.
+
+## Scalars
+
+```graphql
+"An ISO 8601 date and time."
+scalar DateTime
+
+type Post {
+  createdAt: DateTime!
+}
+
+type Query {
+  latestActivity(since: DateTime): [Authored!]!
+}
+```
+
+Write the scalar's class with graphql-ruby's `rails g graphql:scalar DateTime`,
+`Types::<Name>Type` including `Lighthouse::GraphQL::Type`:
+
+```ruby
+# app/graphql/types/date_time_type.rb
+module Types
+  class DateTimeType < BaseScalar
+    include Lighthouse::GraphQL::Type
+
+    def self.coerce_input(value, context)
+      Time.iso8601(value.to_s)
+    rescue ArgumentError
+      raise GraphQL::CoercionError, "#{value.inspect} is not an ISO 8601 date and time"
+    end
+
+    def self.coerce_result(value, context)
+      value.utc.iso8601
+    end
+  end
+end
+```
+
+- `coerce_input` reads an argument or variable. The resolver gets its result, here a
+  `Time`. Raising `GraphQL::CoercionError` (or returning `nil`) makes the argument
+  invalid, and the client gets the message.
+- `coerce_result` writes a value a field returns, here `Post#created_at`.
+
+`@scalar(class:)`, PHP Lighthouse's directive, names the class in the schema
+instead, looked up in the types namespace, then as written:
+
+```graphql
+scalar Money @scalar(class: "Money::GraphQLScalar")
+```
+
+A scalar with neither passes its values through unchanged. A `@scalar` naming no
+class with `coerce_input` and `coerce_result` fails when the schema is built.
+
+## Opting in, and base classes
+
+Only a class including `Lighthouse::GraphQL::Type` counts: any other
+`Types::SearchResultType` or `Types::DateTimeType`, such as the ones a graphql-ruby
+app already has, is left alone. The concern can be included in a subclass of
+`GraphQL::Schema::Object`, `Union` or `Scalar`, or in a module including
+`GraphQL::Schema::Interface`.
+
+The classes are looked up in [`namespaces[:types]`](configuration.md#namespaces)
+(default `['Types']`). When the schema's `base_types` name a base for a kind,
+graphql-ruby builds the SDL's types of that kind from it, and a type class of that
+kind must inherit from it, or the schema does not build:
+
+```ruby
+AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
+  options: {
+    base_types: {
+      object: Types::BaseObject,
+      union: Types::BaseUnion,
+      interface: Types::BaseInterface,
+      scalar: Types::BaseScalar
+      # resolver:, mutation:, subscription: (resolvers.md#handing-the-bases-to-the-schema)
+    }
+  }
+)
+```

data/docs/uploads.md

@@ -0,0 +1,80 @@
+# File Uploads
+
+Clients send files with the [GraphQL multipart request specification](https://github.com/jaydenseric/graphql-multipart-request-spec),
+which Apollo Upload Client, urql and most GraphQL clients speak: a multipart form with
+the operation as JSON, a map of where each file goes, and the files.
+`Lighthouse::GraphQL::Controller` reads it, so the endpoint needs nothing more.
+
+## The `Upload` scalar
+
+Declare it, and use it for arguments:
+
+```graphql
+"A file sent with a multipart request."
+scalar Upload
+
+type Mutation {
+  updateAvatar(avatar: Upload!): User! @update @inject(context: "current_user.id", name: "id")
+}
+```
+
+Lighthouse reads its values itself (`Lighthouse::GraphQL::Upload`): the resolver gets
+the uploaded file, an `ActionDispatch::Http::UploadedFile`. A value that is not a file
+makes the argument invalid. `Upload` is for arguments only, never a field's result.
+
+An ActiveStorage attachment takes the file as it is: with `has_one_attached :avatar`
+on `User`, the mutation above attaches it.
+
+## `@upload`
+
+`@upload` stores the file first, and passes along what was stored instead:
+
+```graphql
+type Mutation {
+  updateAvatar(avatar: Upload! @upload(path: "avatars")): User!
+    @guard
+    @update
+    @inject(context: "current_user.id", name: "id")
+}
+```
+
+By default the file becomes an ActiveStorage blob: on the service `disk:` names (the
+default service without it), with its key under `path:`. The argument then holds the
+blob's **signed id**, which an attachment attribute attaches (`user.avatar = signed_id`)
+and `ActiveStorage::Blob.find_signed` finds. Lists of files are stored one by one.
+
+`@upload` runs once `@guard`, the `@can*` family and `@validator` have let the call
+through, so a refused call stores nothing.
+
+To store files elsewhere, give [`upload_store`](configuration.md#upload_store) an
+object with `call(file, disk:, path:, public:)`; the argument holds what it returns:
+
+```ruby
+Lighthouse.configure do |config|
+  config.upload_store = ->(file, path: '/', **) { S3Uploader.put(file, prefix: path) }   # returns the key
+end
+```
+
+## The request
+
+```shell
+curl localhost:3000/graphql \
+  -H 'Authorization: Bearer <token>' \
+  -F operations='{ "query": "mutation($avatar: Upload!) { updateAvatar(avatar: $avatar) { avatarUrl } }", "variables": { "avatar": null } }' \
+  -F map='{ "0": ["variables.avatar"] }' \
+  -F 0=@me.png
+```
+
+A batch sends an array as `operations`, and maps files to `"0.variables.avatar"`,
+`"1.variables.files.0"`, and so on.
+
+In a request spec:
+
+```ruby
+avatar = Rack::Test::UploadedFile.new('spec/fixtures/me.png', 'image/png')
+post '/graphql', params: {
+  operations: { query: mutation, variables: { avatar: nil } }.to_json,
+  map: { '0' => ['variables.avatar'] }.to_json,
+  '0' => avatar
+}
+```

data/lib/generators/lighthouse/base_classes.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'lighthouse-graphql'
+
+# The base class graphql-ruby's convention puts in each namespace, which the
+# classes Lighthouse generates inherit from: Resolvers::BaseResolver,
+# Mutations::BaseMutation and Subscriptions::BaseSubscription.
+#
+# graphql-ruby's `graphql:install` writes the first two (and every Types::Base*),
+# and `lighthouse:install` runs it: Lighthouse does not write copies of them. It
+# writes only the base graphql-ruby has none of, BaseSubscription, which
+# includes Lighthouse's subscription concern. A generator that finds a base
+# missing says how to get it.
+#
+# A base that already exists is never replaced, not even with --force: it holds
+# the app's own code.
+module Lighthouse::Generators::BaseClasses
+  NAMES = { queries: 'BaseResolver', mutations: 'BaseMutation', subscriptions: 'BaseSubscription' }.freeze
+
+  # The bases Lighthouse writes itself, graphql-ruby having none.
+  SOURCES = {
+    subscriptions: <<~RUBY
+      # What every class resolving a Subscription field shares. The concern is PHP
+      # Lighthouse's model: every subscriber of a field gets every broadcast, and the
+      # class's `filter?` decides who receives it. A subclass that defines
+      # graphql-ruby's own `authorized?` or `update` keeps them, and `topic_by
+      # :arguments` brings back graphql-ruby's exact-argument matching.
+      class BaseSubscription < GraphQL::Schema::Subscription
+        include Lighthouse::GraphQL::Subscription
+      end
+    RUBY
+  }.freeze
+
+  private
+
+  # The base class name for `kind` (`BaseResolver`), or nil for a kind without one.
+  def base_class_name(kind)
+    NAMES[kind]
+  end
+
+  # Write the base class of `kind` into `namespace` when Lighthouse owns it and
+  # it is missing; say how to get one graphql-ruby owns.
+  def write_base_class(kind, namespace)
+    return unless base_class_name(kind)
+
+    path = base_class_path(kind, namespace)
+    if File.exist?(File.join(destination_root, path))
+      say_status :skip, "#{path} already exists", :yellow
+    elsif SOURCES[kind]
+      create_file path, ruby_source(namespace.split('::'), SOURCES[kind])
+    else
+      say_status :missing, "#{path}: graphql-ruby writes it — run `bin/rails g lighthouse:install` (which runs graphql:install), " \
+                           "or write #{namespace}::#{base_class_name(kind)} yourself", :red
+    end
+  end
+
+  def base_class_path(kind, namespace)
+    File.join('app/graphql', *namespace.split('::').map(&:underscore), "#{base_class_name(kind).underscore}.rb")
+  end
+
+  # Ruby source defining `body` inside the nested `modules`.
+  def ruby_source(modules, body)
+    lines = ['# frozen_string_literal: true', '']
+    modules.each_with_index { |mod, depth| lines << "#{'  ' * depth}module #{mod}" }
+    body.each_line { |line| lines << (line.strip.empty? ? '' : "#{'  ' * modules.size}#{line.chomp}") }
+    modules.size.times.reverse_each { |depth| lines << "#{'  ' * depth}end" }
+    "#{lines.join("\n")}\n"
+  end
+end

data/lib/generators/lighthouse/class_generator.rb

@@ -2,16 +2,25 @@
 
 require 'rails/generators'
 require 'lighthouse-graphql'
+require_relative 'base_classes'
 
 # Base for the generators that scaffold the classes a schema refers to by
-# name — queries, mutations, builders and validators — each in its own
-# namespace (Config.namespaces) and with its own contract.
+# name — resolvers, mutations, subscriptions, builders and validators — each in
+# its own namespace (Config.namespaces) and with its own contract. A resolver,
+# mutation or subscription inherits from its namespace's base class
+# (Resolvers::BaseResolver, ...), written first when it is missing.
 class Lighthouse::Generators::ClassGenerator < Rails::Generators::NamedBase
+  include Lighthouse::Generators::BaseClasses
+
   hide!
 
   class_option :namespace, type: :string,
                            desc: 'Namespace to generate into (default: the first of Config.namespaces for this kind)'
 
+  def create_base_class
+    write_base_class(kind, namespace_name)
+  end
+
   def create_class
     create_file File.join('app/graphql', *modules.map(&:underscore), "#{class_basename.underscore}.rb"), source
   end
@@ -22,7 +31,7 @@ class Lighthouse::Generators::ClassGenerator < Rails::Generators::NamedBase
 
   private
 
-  # :queries, :mutations, :builders or :validators.
+  # :queries, :mutations, :subscriptions, :builders or :validators.
   def kind
     raise NotImplementedError
   end
@@ -52,10 +61,12 @@ class Lighthouse::Generators::ClassGenerator < Rails::Generators::NamedBase
   end
 
   def source
-    lines = ['# frozen_string_literal: true', '']
-    modules.each_with_index { |mod, depth| lines << "#{'  ' * depth}module #{mod}" }
-    body.each_line { |line| lines << (line.strip.empty? ? '' : "#{'  ' * modules.size}#{line.chomp}") }
-    modules.size.times.reverse_each { |depth| lines << "#{'  ' * depth}end" }
-    "#{lines.join("\n")}\n"
+    ruby_source(modules, body)
+  end
+
+  # The class a generated class inherits from: the namespace's base class,
+  # which Ruby finds from inside the namespace's modules.
+  def superclass_name
+    base_class_name(kind)
   end
 end