lighthouse-graphql 0.1.1 → 0.2.1

data/docs/relationships.md

@@ -12,27 +12,47 @@ end
 
 ```graphql
 type Post {
-  author: User! @belongsTo(relation: "author")
+  author: User! @belongsTo
   comments: [Comment!]! @hasMany
 }
 ```
 
+| Directive | ActiveRecord association |
+| --- | --- |
+| `@belongsTo` | `belongs_to` |
+| `@hasOne` | `has_one` |
+| `@hasMany` | `has_many` |
+| `@belongsToMany` | `has_many :through`, `has_and_belongs_to_many` |
+| `@morphTo` | `belongs_to …, polymorphic: true` |
+| `@morphOne` / `@morphMany` | `has_one` / `has_many …, as:` |
+| `@morphToMany` | `has_many :through` a polymorphic join |
+
+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.
+
 ## Avoiding the N+1 problem
 
-Resolving relationships naively triggers one query per parent record. Lighthouse's
-relationship directives load through graphql-ruby's **Dataloader**, batching all
-sibling loads into a single query. Enable it on your schema:
+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):
 
 ```ruby
-class AppSchema < BaseAppSchema
-  use GraphQL::Dataloader
-end
+AppSchema = Lighthouse::GraphQL::RbLightHouse.get_schema(
+  options: { using: { GraphQL::Dataloader => {} } }
+)
 ```
 
-With the Dataloader in place, a query for 100 posts and their authors issues two
-queries, not 101.
+A query for 100 posts and their authors then issues two queries, not 101. A
+many-to-many or `:through` association adds one query for the join table. Without
+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.
+
+## Lists, and paginating them
 
-## One-to-many — `@hasMany`
+Collection directives return a **plain list**, as in PHP Lighthouse:
 
 ```graphql
 type User {
@@ -40,38 +60,59 @@ type User {
 }
 ```
 
-`@hasMany` returns a **connection** type, so it supports pagination arguments and
-`edges { node { ... } }` / `nodes { ... }` selections out of the box. The inverse
-is `@belongsTo`.
+```graphql
+{ user(id: 1) { posts { title } } }
+```
 
-## One-to-one — `@hasOne`
+To paginate, pass `type:`, which takes the same values as
+[`@paginate`](directives.md#paginate): `PAGINATOR`, `SIMPLE` or `CONNECTION`.
+Lighthouse rewrites the field and adds the pagination arguments:
 
 ```graphql
 type User {
-  profile: Profile @hasOne
+  posts: [Post!]! @hasMany(type: PAGINATOR, defaultCount: 10)
+  feed: [Post!]! @hasMany(relation: "posts", type: CONNECTION)
 }
 ```
 
-## Inverse — `@belongsTo`
-
 ```graphql
-type Post {
-  author: User! @belongsTo(relation: "author")
+{
+  user(id: 1) {
+    posts(first: 5, page: 2) { paginatorInfo { total lastPage } data { title } }
+    feed(first: 5, after: "NQ==") { pageInfo { hasNextPage endCursor } edges { node { title } } }
+  }
 }
 ```
 
-## Many-to-many — `@belongsToMany`
+`defaultCount` and `maxCount` work as on `@paginate`.
 
-```graphql
-type User {
-  roles: [Role!]! @belongsToMany
-}
-```
+### Paginating many parents at once
+
+With the Dataloader, a paginated relation loads the pages of **every parent** of
+a level together, as PHP Lighthouse does: `{ users { posts(first: 5) { … } } }`
+costs one query for the pages, plus one for the totals if the client selects
+`paginatorInfo` or `pageInfo` — however many users there are. The same goes for
+`@paginate` on a nested field.
+
+- **Pages.** A window function numbers each parent's rows in the field's order
+  (`@orderBy`, else the primary key), and one query keeps the rows of the
+  requested page: `ROW_NUMBER() OVER (PARTITION BY posts.user_id ORDER BY …)`.
+  PHP Lighthouse uses a `UNION ALL` of one query per parent instead; a window
+  function keeps the SQL the same size for 3 parents or 3,000.
+- **Totals.** One `GROUP BY` counts every parent's related records, with the same
+  scopes and filters as the page. The count only runs when a total is asked for,
+  and never for `SIMPLE`, which fetches one extra row instead.
+
+This needs window functions: PostgreSQL, MySQL 8+, MariaDB 10.2+ or SQLite 3.25+.
+A relation falls back to one query per parent on other databases, without the
+Dataloader, and when its rows can't be numbered per parent: a composite key, an
+association scope that reads the owner (`has_many :x, ->(owner) { … }`), or
+`DISTINCT`. The pages are the same either way.
 
 ## Renaming relations
 
-By default the relation name equals the field name (snake_cased). When they
-differ, pass `relation:`:
+By default the relation name is the field name, snake_cased. When they differ,
+pass `relation:`:
 
 ```graphql
 type Post {
@@ -79,17 +120,23 @@ type Post {
 }
 ```
 
-## Filtering a relationship
+## Scopes and filters
 
-Relationship fields accept the same [argument filters](filtering-and-ordering.md)
-and [`@whereConditions`](filtering-and-ordering.md#complex-where-conditions) as
-root queries, so you can scope the related records:
+`scopes:` applies model scopes to the association. Relationship fields also
+accept the same [argument filters](filtering-and-ordering.md) and
+[`@whereConditions`](filtering-and-ordering.md#complex-where-conditions) as root
+queries:
 
 ```graphql
 type User {
   publishedPosts(
-    status: String @eq
+    title: String @like
     orderBy: [OrderByClause!] @orderBy
-  ): [Post!]! @hasMany(relation: "posts")
+  ): [Post!]! @hasMany(relation: "posts", scopes: ["published"])
 }
 ```
+
+## Writing relationships
+
+Creating, connecting, syncing or deleting related records from a mutation's input
+is covered by [nested mutations](mutations.md#nested-mutations).

data/docs/resolvers.md

@@ -0,0 +1,189 @@
+# 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.
+
+The gem ships RBS signatures in `sig/`, so with Steep (or anything that reads
+`rbs collection`) a builder can be checked against `Lighthouse::_Builder`:
+
+```rbs
+# sig/builders/published.rbs
+class Builders::Published
+  extend Lighthouse::_Builder
+end
+```
+
+## 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. Its type is Lighthouse::_Builder.
+      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