lighthouse-graphql 0.1.0 → 0.2.0

data/docs/resolvers.md

@@ -0,0 +1,179 @@
+# Queries, Mutations and Builders
+
+Most fields need no Ruby: a directive (`@all`, `@find`, `@paginate`, `@create`,
+…) or the default attribute reader resolves them. For the rest, Lighthouse looks
+up a class by name. There are three kinds of class, and they are not
+interchangeable. Each kind has its own contract and its own folder:
+
+| Kind | Folder / namespace | Contract | Used by |
+| --- | --- | --- | --- |
+| Query | `app/graphql/queries` · `Queries::` | `GraphQL::Schema::Resolver` | `Query` fields |
+| Mutation | `app/graphql/mutations` · `Mutations::` | `GraphQL::Schema::Mutation` | `Mutation` fields |
+| Builder | `app/graphql/builders` · `Builders::` | `call(relation, args, context)` → relation | `@builder` |
+
+Validators (`app/graphql/validators`) are the fourth kind. They are covered in
+[validation.md](validation.md).
+
+## Queries and mutations: graphql-ruby's contract
+
+A query or mutation class is a plain graphql-ruby
+[resolver](https://graphql-ruby.org/fields/resolvers.html) or
+[mutation](https://graphql-ruby.org/mutations/mutation_classes.html), so everything
+you know from graphql-ruby applies:
+
+- the field's arguments arrive as `snake_case` keyword arguments to `resolve`;
+- `object` and `context` are available;
+- `ready?` and `authorized?` run before `resolve`.
+
+The SDL already declares the field's arguments and return type, so the class
+declares neither.
+
+```graphql
+type Query {
+  latestPosts(limit: Int): [Post!]!
+}
+
+type Mutation {
+  publishPost(id: ID!): Post
+}
+```
+
+```ruby
+# app/graphql/queries/latest_posts.rb
+module Queries
+  class LatestPosts < GraphQL::Schema::Resolver
+    def resolve(limit: 10)
+      Post.order(created_at: :desc).limit(limit)
+    end
+  end
+end
+
+# app/graphql/mutations/publish_post.rb
+module Mutations
+  class PublishPost < GraphQL::Schema::Mutation
+    def authorized?(id:)
+      context[:current_user]&.admin? || raise(GraphQL::ExecutionError, 'Admins only.')
+    end
+
+    def resolve(id:)
+      Post.find(id).tap { |post| post.update!(published: true) }
+    end
+  end
+end
+```
+
+### Resolution by convention
+
+A field on `Query` or `Mutation` with **no resolving directive** resolves to the
+class named after it, as in PHP Lighthouse:
+
+- `Query.latestPosts` resolves to `Queries::LatestPosts`;
+- `Mutation.publishPost` resolves to `Mutations::PublishPost`.
+
+The class is looked up on each call, so code reloading works. Classes found by
+convention must inherit from `GraphQL::Schema::Resolver` (or `Mutation`, which
+is one). Otherwise Lighthouse raises a `Lighthouse::DefinitionError`. A root
+field with no class is reported through [`on_error`](configuration.md#on_error):
+it raises in test and logs elsewhere. Lighthouse never falls back to a top-level
+constant, so a `post` field is never mistaken for the `Post` model.
+
+graphql-ruby's `RelayClassicMutation` (what `rails g graphql:install` generates
+`Mutations::BaseMutation` from) works too, as long as the SDL field takes the
+`input:` argument it expects.
+
+Wrapping directives (`@guard`, the `@can*` family, `@validator`, `@cache`,
+`@clearCache`) are not resolvers, so a field carrying only those still resolves by
+convention:
+
+```graphql
+type Mutation {
+  publishPost(id: ID!): Post @guard @canFind(ability: "publish", find: "id")
+}
+```
+
+### Naming a class explicitly
+
+`@field(resolver:)` points a field at a class by name. On `Query` and `Mutation`
+the name is looked up in the queries and mutations namespaces; on any other type,
+in [`resolver_namespaces`](configuration.md#resolver_namespaces).
+
+```graphql
+type Query {
+  feed: [Post!]! @field(resolver: "Feeds::Home")   # Queries::Feeds::Home
+}
+```
+
+Besides graphql-ruby resolver classes, `@field` also accepts a plain callable:
+anything with `call(object, args, context)`.
+
+### `@spread` and `@inject`
+
+Both shape the keyword arguments a class receives. They do the same for
+[`@create` / `@update`](mutations.md).
+
+```graphql
+type Mutation {
+  createDraft(input: CreateDraftInput! @spread): Post
+    @inject(context: "current_user.id", name: "author_id")
+}
+```
+
+`resolve(title:, body:, author_id:)` receives the input's fields at the top level.
+`author_id` comes from `context[:current_user].id`, so clients cannot set it.
+`@inject` is repeatable, and `name:` may be a dot path into an input
+(`"input.author_id"`).
+
+## Builders
+
+A builder is not a resolver: it does not produce the field's value. It refines the
+query of a field that a model directive resolves. It receives the relation, the
+field's arguments and the context, and returns a relation:
+
+```graphql
+type Query {
+  posts: [Post!]! @paginate @builder(class: "Published")
+}
+```
+
+```ruby
+# app/graphql/builders/published.rb
+module Builders
+  class Published
+    def self.call(relation, args, context)
+      relation.where(published: true)
+    end
+  end
+end
+```
+
+`@builder` works with `@all`, `@paginate`, `@first`, `@count` and `@aggregate`.
+It is repeatable, and `method:` names a method other than `call`. Builder classes
+are looked up in the builders namespace only. Raising a `GraphQL::ExecutionError`
+from a builder (e.g. a tenancy check) always reaches the client; it never falls
+back to the unscoped relation.
+
+## Generators
+
+```shell
+bin/rails generate lighthouse:query LatestPosts        # app/graphql/queries/latest_posts.rb
+bin/rails generate lighthouse:mutation PublishPost     # app/graphql/mutations/publish_post.rb
+bin/rails generate lighthouse:builder Published        # app/graphql/builders/published.rb
+bin/rails generate lighthouse:validator CreatePostInput # app/graphql/validators/create_post_input_validator.rb
+```
+
+Each one writes the class with its contract, into the first namespace configured
+for its kind (or `--namespace=…`). Namespaced names nest modules:
+`lighthouse:mutation Blog::Publish` writes `Mutations::Blog::Publish`. These
+generators do not collide with graphql-ruby's `graphql:*` generators. A
+`lighthouse:mutation` and a `graphql:mutation` of the same name target the same
+file, and Rails asks before overwriting it.
+
+## Changing the namespaces
+
+```ruby
+Lighthouse.configure do |config|
+  config.namespaces = { queries: ['Api::Queries'], mutations: ['Api::Mutations'] }
+end
+```
+
+Kinds you leave out keep their defaults. Each kind takes a list, tried in order.

data/docs/validation.md

@@ -0,0 +1,132 @@
+# Validation
+
+Rails puts validation in the model, and so does Lighthouse: the
+[mutation directives](mutations.md) save through ActiveRecord, so `validates`
+rules apply with no configuration. Not every rule belongs to a model, though:
+a password confirmation, a rule across two arguments, the arguments of a query, or
+input that never reaches a model at all. For those, `@validator` runs a contract
+class before the field resolves.
+
+Both report errors the same way, in PHP Lighthouse's format: messages keyed by
+argument path under `extensions.validation`.
+
+```json
+{
+  "data": { "signUp": null },
+  "errors": [{
+    "message": "Validation failed for the field [signUp].",
+    "extensions": { "validation": { "passwordConfirmation": ["must match password"] } }
+  }]
+}
+```
+
+## Model validations
+
+Nothing to do. A failed `save` in `@create`, `@update`, `@createMany` or
+`@updateMany` reports the model's `full_message`s, keyed by the argument each
+attribute came from (see [mutations.md](mutations.md#validation-errors)).
+
+## `@validator`
+
+```graphql
+directive @validator(class: String) on FIELD_DEFINITION | INPUT_OBJECT
+```
+
+### On a field
+
+The contract receives all of the field's arguments:
+
+```graphql
+type Mutation {
+  signUp(email: String!, password: String!, passwordConfirmation: String): User @validator
+}
+```
+
+```ruby
+# app/graphql/validators/mutation/sign_up_validator.rb
+module Validators
+  module Mutation
+    class SignUpValidator < Dry::Validation::Contract
+      params do
+        required(:email).filled(:string)
+        required(:password).filled(:string, min_size?: 12)
+        optional(:password_confirmation).maybe(:string)
+      end
+
+      rule(:password_confirmation) do
+        key.failure('must match password') if value && value != values[:password]
+      end
+    end
+  end
+end
+```
+
+The class defaults to `Validators::<ParentType>::<FieldName>Validator`. Name
+another with `@validator(class: "SignUpRules")`; it is looked up in the validators
+namespace.
+
+### On an input type
+
+The contract receives that input's values. It runs **wherever the type is used**:
+as an argument, nested inside another input, or as each item of a list. The
+fields that take the input need no directive.
+
+```graphql
+input AddressInput @validator {
+  street: String
+  zipCode: String
+}
+
+type Mutation {
+  ship(to: AddressInput!, billing: BillingInput): Shipment
+  shipMany(to: [AddressInput!]!): [Shipment!]!
+}
+```
+
+The class defaults to `Validators::<InputType>Validator`, here
+`Validators::AddressInputValidator`. Errors are prefixed with the path to the
+input: `to.zipCode`, `billing.address.street`, `to.1.street`.
+
+### Contracts
+
+A contract is a [Dry::Validation](https://dry-rb.org/gems/dry-validation/)
+contract:
+
+- Values arrive with `snake_case` symbol keys, and the error keys are mapped back
+  to the GraphQL argument names.
+- Declare `option :graphql_context, optional: true` to read the GraphQL context in
+  rules (e.g. `graphql_context[:current_user]`).
+- `dry-validation` is an optional dependency. Add it to your Gemfile to use these
+  contracts.
+
+Any other object works if its `call(values)` returns a Dry-style result, or a
+`{ key => [messages] }` Hash (empty when valid):
+
+```ruby
+module Validators
+  class NoSpam
+    def call(values)
+      values[:title].to_s.include?('spam') ? { title: ['looks like spam'] } : {}
+    end
+  end
+end
+```
+
+A missing class raises `Lighthouse::DefinitionError`. Lighthouse never silently
+skips validation.
+
+### Order
+
+Validation runs after authentication and authorization (`@guard`, `@can*`), so
+anonymous clients cannot probe your rules, and before `@cache` and the resolver.
+All contracts on a field run, and their errors are reported together.
+
+Generate a contract with `bin/rails generate lighthouse:validator AddressInput`.
+
+## Why not `@rules`?
+
+PHP Lighthouse's `@rules(apply: ["email", "max:280"])` embeds Laravel's
+string-based rule language in the schema. Rails has no equivalent to port: its
+validations live in models, and Dry contracts express the rest as Ruby with
+proper types. So Lighthouse for Rails supports those two, and does not invent a
+third rule syntax.

data/lib/generators/lighthouse/builder_generator.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative 'class_generator'
+
+# `rails generate lighthouse:builder PublishedPosts` — a query builder for
+# `@builder(class: "PublishedPosts")`.
+class Lighthouse::Generators::BuilderGenerator < Lighthouse::Generators::ClassGenerator
+  desc 'Generate a query builder for @builder in app/graphql/builders.'
+
+  private
+
+  def kind = :builders
+
+  def body
+    <<~RUBY
+      # Applied by @builder(class: "#{class_name}") before the field resolves:
+      # receives the relation, the field's arguments and the GraphQL context, and
+      # returns the relation to use.
+      class #{class_basename}
+        def self.call(relation, args, context)
+          relation
+        end
+      end
+    RUBY
+  end
+
+  def usage
+    "Use it with @builder(class: \"#{class_name}\") on a field resolved by @all, @paginate, @first, @count or @aggregate."
+  end
+end

data/lib/generators/lighthouse/class_generator.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'lighthouse-graphql'
+
+# 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.
+class Lighthouse::Generators::ClassGenerator < Rails::Generators::NamedBase
+  hide!
+
+  class_option :namespace, type: :string,
+                           desc: 'Namespace to generate into (default: the first of Config.namespaces for this kind)'
+
+  def create_class
+    create_file File.join('app/graphql', *modules.map(&:underscore), "#{class_basename.underscore}.rb"), source
+  end
+
+  def show_usage
+    say_status :usage, usage, :blue if usage
+  end
+
+  private
+
+  # :queries, :mutations, :builders or :validators.
+  def kind
+    raise NotImplementedError
+  end
+
+  def body
+    raise NotImplementedError
+  end
+
+  def usage
+    nil
+  end
+
+  def class_basename
+    class_name.demodulize
+  end
+
+  def namespace_name
+    options[:namespace] || Lighthouse::Config.namespaces[kind].first
+  end
+
+  def modules
+    namespace_name.split('::') + class_name.split('::')[0...-1]
+  end
+
+  def full_class_name
+    (modules + [class_basename]).join('::')
+  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"
+  end
+end

data/lib/generators/lighthouse/install/install_generator.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'lighthouse-graphql'
+
+# `rails generate lighthouse:install` — sets a Rails app up for Lighthouse:
+# the initializer, a starter SDL file, the schema class, a controller and
+# its route, plus the graphql-config file IDEs read. Rerunning it skips the
+# route, SDL and .gitignore entries that are already in place.
+#
+# It coexists with graphql-ruby's `graphql:install`, which writes the same
+# controller path and route: an existing schema class or controller is kept
+# (pass --force to replace it) instead of overwritten, so an app already
+# serving a graphql-ruby schema keeps doing so until it is pointed at ours.
+class Lighthouse::Generators::InstallGenerator < Rails::Generators::Base
+  CONTROLLER = 'app/controllers/graphql_controller.rb'
+
+  source_root File.expand_path('templates', __dir__)
+
+  desc 'Install Lighthouse: initializer, starter schema, schema class, controller, route and IDE config.'
+
+  class_option :schema, type: :string, default: 'AppSchema',
+                        desc: 'Name of the schema constant to generate'
+  class_option :sdl_folder, type: :string, default: 'graphql',
+                            desc: 'Folder, relative to the app root, holding the *.graphql files'
+  class_option :skip_controller, type: :boolean, default: false,
+                                 desc: 'Skip the GraphqlController and its route'
+  class_option :skip_ide, type: :boolean, default: false,
+                          desc: 'Skip graphql.config.yml and the .gitignore entries for the IDE helper files'
+
+  def create_initializer
+    template 'initializer.rb.tt', 'config/initializers/lighthouse.rb'
+  end
+
+  def create_starter_schema
+    if Dir[File.join(destination_root, sdl_folder, '**', '*.graphql')].any?
+      say_status :skip, "#{sdl_folder}/ already has .graphql files", :yellow
+      return
+    end
+
+    template 'schema.graphql.tt', File.join(sdl_folder, 'schema.graphql')
+  end
+
+  def create_schema_class
+    path = File.join('app/graphql', "#{schema_name.underscore}.rb")
+    return if keep_existing?(path)
+
+    template 'schema.rb.tt', path
+  end
+
+  def create_controller
+    return if options[:skip_controller]
+    return if (@kept_controller = keep_existing?(CONTROLLER))
+
+    template 'graphql_controller.rb.tt', CONTROLLER
+  end
+
+  def add_route
+    return if options[:skip_controller]
+
+    routes = File.join(destination_root, 'config/routes.rb')
+    return unless File.exist?(routes)
+    return if File.read(routes).include?('graphql#execute')
+
+    # Byte-identical to graphql-ruby's install route, so whichever generator
+    # runs second finds it in place and does not add it again.
+    route 'post "/graphql", to: "graphql#execute"'
+  end
+
+  def create_ide_config
+    return if options[:skip_ide]
+
+    template 'graphql.config.yml.tt', 'graphql.config.yml'
+
+    gitignore = File.join(destination_root, '.gitignore')
+    return unless File.exist?(gitignore)
+
+    entries = ide_helper_files.map { |file| "/#{file}" } - File.read(gitignore).lines.map(&:strip)
+    return if entries.empty?
+
+    append_to_file '.gitignore', "\n# Lighthouse IDE helper output (bin/rails lighthouse:ide_helper)\n#{entries.join("\n")}\n"
+  end
+
+  def show_next_steps
+    serve =
+      if @kept_controller
+        "Serve it: #{CONTROLLER} was kept — have it call #{schema_name}.execute(...) to serve Lighthouse's schema."
+      else
+        'Query it:  POST /graphql  {"query": "{ users { data { id name } paginatorInfo { total } } }"}'
+      end
+
+    say <<~MSG
+
+      Lighthouse is installed. Next steps:
+        1. Describe your API in #{sdl_folder}/*.graphql (the starter schema assumes a User model).
+        2. Generate the IDE helper files:  bin/rails lighthouse:ide_helper
+        3. #{serve}
+    MSG
+  end
+
+  private
+
+  # Files another generator may own (graphql-ruby's install writes the same
+  # controller) are left alone unless --force is given.
+  def keep_existing?(path)
+    return false if options[:force] || !File.exist?(File.join(destination_root, path))
+
+    say_status :skip, "#{path} already exists (pass --force to replace it)", :yellow
+    true
+  end
+
+  def schema_name
+    options[:schema].camelize
+  end
+
+  def sdl_folder
+    options[:sdl_folder].delete_suffix('/')
+  end
+
+  def default_sdl_folder?
+    sdl_folder == 'graphql'
+  end
+
+  def ide_helper_files
+    [Lighthouse::IdeHelper::DIRECTIVES_FILE, Lighthouse::IdeHelper::PROGRAMMATIC_TYPES_FILE]
+  end
+end

data/lib/generators/lighthouse/install/templates/graphql.config.yml.tt

@@ -0,0 +1,8 @@
+# graphql-config, read by the GraphQL plugins for JetBrains IDEs and VS Code.
+# The two generated files describe Lighthouse's directives and the types it
+# generates; refresh them after changing the schema:
+#   bin/rails lighthouse:ide_helper
+schema:
+  - <%= sdl_folder %>/**/*.graphql
+  - <%= Lighthouse::IdeHelper::DIRECTIVES_FILE %>
+  - <%= Lighthouse::IdeHelper::PROGRAMMATIC_TYPES_FILE %>

data/lib/generators/lighthouse/install/templates/graphql_controller.rb.tt

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+class GraphqlController < ApplicationController
+  # If this endpoint is called from outside this domain, null the session
+  # instead of failing CSRF verification:
+  # protect_from_forgery with: :null_session
+
+  def execute
+    # PersistedQueries.execute resolves Apollo-style persisted queries when
+    # config.persisted_queries is on, and otherwise runs params[:query] as is.
+    result = Lighthouse::GraphQL::PersistedQueries.execute(
+      <%= schema_name %>,
+      query: params[:query],
+      extensions: params[:extensions],
+      variables: prepare_variables(params[:variables]),
+      operation_name: params[:operationName],
+      context: {
+        # Read by @guard and the @can* directives — see config/initializers/lighthouse.rb.
+        # current_user: current_user
+      }
+    )
+    # The Cache-Control header the selected fields' @cacheControl hints allow
+    # (a no-op when the schema has none).
+    Lighthouse::GraphQL::CacheControl.apply(response, result)
+    render json: result
+  rescue StandardError => e
+    raise e unless Rails.env.development?
+
+    handle_error_in_development(e)
+  end
+
+  private
+
+  # Variables arrive as a JSON string (GET or form posts) or as parameters.
+  def prepare_variables(variables_param)
+    case variables_param
+    when String
+      variables_param.present? ? JSON.parse(variables_param) || {} : {}
+    when Hash
+      variables_param
+    when ActionController::Parameters
+      variables_param.to_unsafe_hash
+    when nil
+      {}
+    else
+      raise ArgumentError, "Unexpected parameter: #{variables_param}"
+    end
+  end
+
+  def handle_error_in_development(error)
+    logger.error(error.message)
+    logger.error(error.backtrace.join("\n"))
+
+    render json: { errors: [{ message: error.message, backtrace: error.backtrace }], data: {} },
+           status: :internal_server_error
+  end
+end

data/lib/generators/lighthouse/install/templates/initializer.rb.tt

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+# Lighthouse configuration. Every option is optional; the defaults are shown.
+# Reference: https://github.com/Vaz-Innovation/lighthouse-graphql/blob/main/docs/configuration.md
+Lighthouse.configure do |config|
+  # Folder the *.graphql schema files are loaded from.
+<% if default_sdl_folder? -%>
+  # config.sdl_folder = Rails.root.join('graphql').to_s
+<% else -%>
+  config.sdl_folder = Rails.root.join('<%= sdl_folder %>').to_s
+<% end -%>
+
+  # Where classes named by the schema are looked up, by kind. A Query or Mutation
+  # field without a resolving directive resolves by convention: Query.latestPosts
+  # to Queries::LatestPosts (a GraphQL::Schema::Resolver), Mutation.publishPost
+  # to Mutations::PublishPost (a GraphQL::Schema::Mutation). @builder classes
+  # come from :builders and @validator contracts from :validators. Generate them
+  # with `rails g lighthouse:query|mutation|builder|validator Name`.
+  # config.namespaces = {
+  #   queries: ['Queries'], mutations: ['Mutations'], builders: ['Builders'], validators: ['Validators']
+  # }
+
+  # Namespaces tried, in order, for models (@all(model: "User")) and for
+  # @field(resolver:) on types other than Query and Mutation. Fully-qualified
+  # names (containing `::`) are used as-is.
+  # config.resolver_namespaces = ['App::Graphql']
+
+  # Store for @cache and @clearCache.
+  # config.cache_store = Rails.cache
+
+  # Run @create/@update/@createMany/@updateMany in a database transaction.
+  # config.transactional_mutations = true
+
+  # --- For large schemas and high traffic (all off by default) ---------------
+  # Cache the built schema document in tmp/cache, keyed by the SDL and
+  # everything that shapes it; warm it at deploy with `bin/rails lighthouse:cache`.
+  # config.schema_cache = Rails.env.production?
+
+  # Reload the app (and so the schema) when a .graphql file changes.
+  # config.watch_sdl = Rails.env.development?
+
+  # Automatic Persisted Queries (Apollo's protocol). Add a GET route too, so
+  # hashed queries can be cached by CDNs: get "/graphql", to: "graphql#execute"
+  # config.persisted_queries = true
+  # config.persisted_queries_ttl = 1.week.to_i
+  # A manifest of trusted operations from your client build, served by hash;
+  # with persisted_queries_only, nothing else may run.
+  # config.persisted_queries_manifest = Rails.root.join('persisted-queries.json')
+  # config.persisted_queries_only = Rails.env.production?
+
+  # Called when a directive or resolver swallows an error. The default raises in
+  # test and logs otherwise.
+  # config.on_error = ->(error, _context) { Rails.error.report(error) }
+
+  # Authorization seams used by @guard and the @can* directives (Pundit by default).
+  # config.authenticated_user = ->(ctx) { ctx[:current_user] }
+  # config.policy_user = ->(ctx) { ctx[:pundit_user] || ctx[:current_user] }
+  # config.authorizer = ->(user, record, ability, args = []) { Pundit.policy!(user, record).public_send("#{ability}?", *args) }
+end
+
+# Register app-defined directives and federation reference resolvers inside
+# to_prepare, so they reference reloadable constants and run before the schema
+# is built. See docs/custom-directives.md and docs/federation.md.
+# Rails.application.config.to_prepare do
+#   Lighthouse::DirectiveRegistry.register(Directives::Upcase)
+#   Lighthouse::ReferenceResolver.register('User') { |ref, _ctx| User.find_by(id: ref['id']) }
+# end

data/lib/generators/lighthouse/install/templates/schema.graphql.tt

@@ -0,0 +1,19 @@
+# Starter schema generated by `rails generate lighthouse:install`. It assumes a
+# User model with `name` and `email` columns — replace it with your own types.
+# Directives reference: https://github.com/Vaz-Innovation/lighthouse-graphql/blob/main/docs/directives.md
+
+"Indicates what fields are available at the top level of a query operation."
+type Query {
+  "Find a single user by id."
+  user(id: ID! @eq): User @find
+
+  "List users, a page at a time (10 by default; pass first: and page:)."
+  users: [User!]! @paginate(defaultCount: 10)
+}
+
+"Account of a person who uses this application."
+type User {
+  id: ID!
+  name: String
+  email: String
+}