graphql_rails 0.5.2 → 1.1.0

data/docs/_sidebar.md

@@ -6,4 +6,9 @@
   * [Routes](components/routes)
   * [Model](components/model)
   * [Controller](components/controller)
+  * [Decorator](components/decorator)
+* [Logging and monitoring](logging_and_monitoring/logging_and_monitoring)
 * [Testing](testing/testing)
+* Other tools
+  * [Schema Snapshot](other_tools/schema_dump)
+  * [Query Runner](other_tools/query_runner)

data/docs/components/controller.md

@@ -66,22 +66,95 @@ class UsersController < GraphqlRails::Controller
 end
 ```
 
-### *can_return_nil*
+### *permit_input*
 
-By default it is expected that each controller action returns model or array of models. `nil` is not allowed. You can change that by adding `can_return_nil` like this:
+Allows to permit single input field. It allows to set additional options for each field.
+
+#### *type*
+
+Specifies input type:
+
+```ruby
+class OrderController < GraphqlRails::Controller
+  action(:create)
+    .permit_input(:price, type: :integer!)
+    # Same as `.permit(amount: :integer!)`
+end
+```
+
+#### required type
+
+There are few ways how to mark field as required.
+
+1. Adding exclamation mark at the end of type name:
+
+```ruby
+class UsersController < GraphqlRails::Controller
+  action(:create).permit_input(:some_field, type: :int!)
+end
+```
+
+2. Adding exclamation mark at the end of name
 
 ```ruby
 class UsersController < GraphqlRails::Controller
-  action(:show).permit(:email).can_return_nil
+  action(:create).permit_input(:some_field!)
+end
+```
 
-  def show
-    user = User.find_by(email: params[:email])
-    return nil if user.blank?
-    user
+3. Adding `required: true` options
+
+```ruby
+class UsersController < GraphqlRails::Controller
+  action(:create).permit_input(:some_field, type: :bool, required: true)
+end
+```
+
+#### *description*
+
+You can describe each input by adding `description` keyword argument:
+
+```ruby
+class OrderController < GraphqlRails::Controller
+  action(:create)
+    .permit_input(:price, type: :integer!, description: 'Price in Euro cents')
+end
+```
+
+#### *subtype*
+
+`subtype` allows to specify which named input should be used. Here is an example:
+
+Let's say you have user with two input types
+
+```ruby
+class User
+  graphql.input do |c|
+    c.attribute :full_name
+    c.attribute :email
+  end
+
+  graphql.input(:change_password) do |c|
+    c.attribute :password
+    c.attribute :password_confirmation
   end
 end
 ```
 
+If you do not specify `subtype` then default (without name) input will be used. You need to specify subtype if you want to use non-default input:
+
+```ruby
+class OrderController < GraphqlRails::Controller
+  # this is the input with email and full_name:
+  action(:create)
+    .permit_input(:input, type: 'User!')
+
+  # this is the input with password and password_confirmation:
+  action(:update_password)
+    .permit_input(:input, type: 'User!', subtype: :change_password)
+end
+```
+
 ### *paginated*
 
 You can mark collection action as `paginated`. In this case controller will return relay connection type and it will be possible to return only partial results. No need to do anything on controller side (you should always return full list of items)
@@ -96,6 +169,8 @@ class UsersController < GraphqlRails::Controller
 end
 ```
 
+Also check ['decorating controller responses'](components/decorator) for more details about working with active record and decorators.
+
 #### *max_page_size*
 
 Allows to specify max items count per request
@@ -110,9 +185,29 @@ class UsersController < GraphqlRails::Controller
 end
 ```
 
+### *model*
+
+If you want to define model dynamically, you can use combination of `model` and `returns_list` or `returns_single`. This is especially handy when model is used with `action_default`:
+
+```ruby
+class OrdersController < GraphqlRails::Controller
+  model('Order')
+  action(:show).returns_single # returns `Order!`
+  action(:index).returns_list # returns `[Order!]!`
+
+  def show
+    Order.first
+  end
+
+  def index
+    Order.all
+  end
+end
+```
+
 ### *returns*
 
-By default return type is determined by controller name. When you want to return some custom object, you can specify that with `returns` method:
+You must specify what each action will return. This is done with `returns` method:
 
 ```ruby
 class UsersController < GraphqlRails::Controller
@@ -124,6 +219,48 @@ class UsersController < GraphqlRails::Controller
 end
 ```
 
+You can also return raw graphql-ruby types:
+
+```ruby
+# raw graphql-ruby type:
+class OrderType < GraphQL::Schema::Object
+  graphql_name 'Order'
+  field :id, ID
+end
+
+class UsersController < GraphqlRails::Controller
+  action(:last_order).permit(:id).returns(OrderType)
+end
+```
+
+Check [graphql-ruby documentation](https://graphql-ruby.org) for more details about graphql-ruby types.
+
+### *returns_list*
+
+When you have defined `model` dynamically, you can use `returns_list` to indicate that action must return list without specifying model type for each action. By default list and inner types are required but you can change that with `required_list: false` and `required_inner: false`
+
+```ruby
+class OrdersController < GraphqlRails::Controller
+  model('Order')
+
+  action(:index).returns_list(required_list: false, required_inner: false) # returns `[Order]`
+  action(:search).permit(:filter).returns_list # returns `[Order!]!`
+end
+```
+
+### *returns_single*
+
+When you have defined `model` dynamically, you can use `returns_single` to indicate that action must return single item without specifying model type for each action. By default return type is required, but you can change that by providing `required: false` flag:
+
+```ruby
+class OrdersController < GraphqlRails::Controller
+  model('Order')
+
+  action(:show).returns_single(required: false) # returns `Order`
+  action(:update).permit(title: :string!).returns_single # returns `Order!`
+end
+```
+
 ### *describe*
 
 If you want to improve graphql documentation, you can add description for each action. To do so, use `describe` method:
@@ -153,6 +290,57 @@ class UsersController < GraphqlRails::Controller
 end
 ```
 
+### configuring action with a block
+
+If you do not like chainable methods, you can use "block" style action configuration:
+
+```ruby
+class UsersController < GraphqlRails::Controller
+  action(:index) do |action|
+    action.paginated
+    action.permit(limit: :int!)
+    action.returns '[User!]!'
+  end
+
+  def create
+    User.create(params)
+  end
+end
+```
+
+## *model*
+
+`model` is just a shorter version of `action_default.model`. See `action.model` and `action_default` for more information:
+
+```ruby
+class OrdersController < GraphqlRails::Controller
+  model('Order')
+  action(:show).returns_single # returns `Order!`
+  action(:index).returns_list # returns `[Order!]!`
+
+  def show
+    Order.first
+  end
+
+  def index
+    Order.all
+  end
+end
+```
+
+## *action_default*
+
+Sometimes you want to have some shared attributes for all your actions. In order to make this possible you need to use `action_default`. It acts identical to `action` and is "inherited" by all actions defined after `action_default` part:
+
+```ruby
+class UsersController < GraphqlRails::Controller
+  action_default.permit(token: :string!)
+
+  action(:update).returns('User!') # action(:update) has `permit(token: :string!)
+  action(:create).returns('User') # action(:create) has `permit(token: :string!)
+end
+```
+
 ## *before_action*
 
 You can add `before_action` to run some filters before calling your controller action. Here is an example:
@@ -263,3 +451,101 @@ class UsersController < GraphqlRails::Controller
   end
 end
 ```
+
+## decorating objects
+
+See ['Decorating controller responses'](components/decorator) for various options how you can decorate paginated responses
+
+## Rendering errors
+
+### Rendering strings as errors
+
+The simplest way to render an error is to provide a list of error messages, like this:
+
+```ruby
+class UsersController < GraphqlRails::Controller
+  action(:update).permit(:id, input: 'UserInput!').returns('User!')
+
+  def update
+    user = User.find(params[:id])
+
+    if user.update(params[:input])
+      user
+    else
+      render(errors: ['Something went wrong'])
+    end
+  end
+end
+```
+
+### Rendering validation errors
+
+GraphqlRails controller has `#render` method which you can use to render errors:
+
+```ruby
+class UsersController < GraphqlRails::Controller
+  action(:update).permit(:id, input: 'UserInput!').returns('User!')
+
+  def update
+    user = User.find(params[:id])
+
+    if user.update(params[:input])
+      user
+    else
+      render(errors: user.errors)
+    end
+  end
+end
+```
+
+### Rendering errors with custom data
+
+When you want to return errors with custom data, you can provide hash like this:
+
+```ruby
+class UsersController < GraphqlRails::Controller
+  action(:update).permit(:id, input: 'UserInput!').returns('User!')
+
+  def update
+    user = User.find(params[:id])
+
+    if user.update(params[:input])
+      user
+    else
+      render(
+        errors: [
+          { message: 'Something went wrong', code: 500, type: 'fatal' },
+          { message: 'Something went wrong', custom_param: true, ... },
+        ]
+      )
+    end
+  end
+end
+```
+
+### Raising custom error classes
+
+If you want to have customized error classes you need to create errors which inherit from `GraphqlRails::ExecutionError`
+
+```ruby
+class MyCustomError < GraphqlRails::ExecutionError
+  def to_h
+    # this part will be rendered in graphql
+    { something_custom: 'yes' }
+  end
+end
+
+class UsersController < GraphqlRails::Controller
+  action(:update).permit(:id, input: 'UserInput!').returns('User!')
+
+  def update
+    user = User.find(params[:id])
+
+    if user.update(params[:input])
+      user
+    else
+      raise MyCustomError, 'ups!'
+    end
+  end
+end
+```

data/docs/components/decorator.md

@@ -0,0 +1,69 @@
+# Decorator
+
+Decorator is mostly used whit paginated results, because it can wrap ActiveRecord relations in a "pagination-friendly" way
+
+## Passing extra options to decorator
+
+Let's say you want to decorate `comment`, but you also need `user` in order to print some details. Here is decorator for such comment:
+
+```ruby
+class CommentDecorator < SimpleDelegator
+  include GraphqlRails::Decorator
+
+  def initialize(comment, current_user)
+    @comment = comment
+    @current_user = user
+  end
+
+  def author_name
+    if @current_user.can_see_author_name?(@comment)
+      @comment.author_name
+    else
+      'secret author'
+    end
+  end
+end
+```
+
+In order to decorate object with exra arguments, simply pass them to `.decorate` method. Like this:
+
+```ruby
+CommentDecorator.decorate(comment, current_user)
+```
+
+The only requirement is that first object should be the object which you are decorating. Other arguments are treated as extra data and they are not modified
+
+## Decorating controller responses
+
+If you want to decorate your controller response you can use `GraphqlRails::Decorator` module. It can decorate simple objects and ActiveRecord::Relation objects. This is very handy when you need to decorated paginated actions:
+
+```ruby
+class User < ActiveRecord::Base
+  # it's not GraphqlRails::Model !
+end
+
+class UserDecorator < SimpleDelegator
+  include GraphqlRails::Model
+  include GraphqlRails::Decorator
+
+  graphql_rails do
+    # some setup, attributes, etc...
+  end
+
+  def initialize(user); end
+end
+
+class UsersController < GraphqlRails::Controller
+  action(:index).paginated.returns('[UserDecorator!]!')
+
+  def index
+    users = User.where(active: true)
+    UserDecorator.decorate(users)
+  end
+
+  def create
+    user = User.create(params)
+    UserDecorator.decorate(user)
+  end
+end
+```

data/docs/components/model.md

@@ -15,15 +15,15 @@ class User # works with any class including ActiveRecord
 end
 ```
 
-## _graphql_
+## graphql
 
-This method must be called inside your model body. `grapqhl` is used for making your model convertible to graphql type.
+This method must be called inside your model body. `graphql` is used for making your model convertible to graphql type.
 
-### _attribute_
+## attribute
 
 Most commonly you will use `attribute` to make your model methods and attributes visible via graphql endpoint.
 
-#### _type_
+### attribute.type
 
 Some types can be determined by attribute name, so you can skip this attribute:
 
@@ -54,11 +54,35 @@ class User
 end
 ```
 
-#### _property_
+#### attribute.type: using graphql-ruby objects
 
-By default graphql attribute names are expected to be same as model methods/attributes, but if you want to use different name on grapqhl side, you can use `propery` option:
+You can also use raw graphql-ruby objects as attribute types. Here is an example:
 
+```ruby
+# raw graphql-ruby type:
+class AddressType < GraphQL::Schema::Object
+  graphql_name 'Address'
+
+  field :city, String, null: false
+  field :street_name, String, null: false
+  field :street_number, Integer
+end
+
+# GraphqlRails model:
+class User
+  include GraphqlRails::Model
+
+  graphql.attribute :address, type: AddressType, required: true
+end
 ```
+
+Check [graphql-ruby documentation](https://graphql-ruby.org) for more details about graphql-ruby types.
+
+### attribute.property
+
+By default graphql attribute names are expected to be same as model methods/attributes, but if you want to use different name on grapqhl side, you can use `property` option:
+
+```ruby
 class User
   include GraphqlRails::Model
 
@@ -72,11 +96,11 @@ class User
 end
 ```
 
-#### _description_
+### attribute.description
 
 You can also describe each attribute and make graphql documentation even more readable. To do so, add `description` option:
 
-```
+```ruby
 class User
   include GraphqlRails::Model
 
@@ -86,7 +110,173 @@ class User
 end
 ```
 
-### _name_
+### attribute.options
+
+Allows passing options to attribute definition. Available options:
+
+* `attribute_name_format` - if `:original` value is passed, it will not camelCase attribute name.
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql do |c|
+    c.attribute :first_name # will be accessible as firstName from client side
+    c.attribute :first_name, options: { attribute_name_format: :original } # will be accessible as first_name from client side
+  end
+end
+
+### attribute.permit
+
+To define attributes which are accepted by each model method, you need to call `permit` method, like this:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql do |c|
+    c.attribute(:avatar_url).permit(size: :int!)
+  end
+
+  def avatar_url(size:)
+    # some code here
+  end
+end
+```
+
+### attribute.permit_input
+
+Allows to permit single input field. It allows to set additional options for each field.
+
+#### attribute.permit_input.type
+
+#### attribute.permit_input: required type
+
+There are few ways how to mark field as required.
+
+1. Adding exclamation mark at the end of type name:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql.attribute(:avatar_url).permit_input(:size, type: :int!)
+end
+```
+
+2. Adding `required: true` options
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql.attribute(:avatar_url).permit_input(:size, type: :int, required: true)
+end
+```
+
+#### attribute.permit_input.description
+
+You can describe each input by adding `description` keyword argument:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql.attribute(:avatar_url).permit_input(:size, description: 'max size of avatar')
+end
+```
+
+#### *subtype*
+
+`subtype` allows to specify which named input should be used. Here is an example:
+
+```ruby
+class Image
+  graphql.input(:size_options) do |c|
+    c.attribute :width
+    c.attribute :height
+  end
+end
+
+class User
+  graphql.attribute(:avatar_url).permit_input(:size, type: Image, subtype: :size_options)
+end
+```
+
+### attribute.paginated
+
+You can mark collection method as `paginated`. In this case method will return relay connection type and it will be possible to return only partial results. No need to do anything on method side (you should always return full list of items)
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql.attribute :items, type: '[Item]', paginatted: true
+
+  def items
+    Item.all
+  end
+end
+```
+
+### attribute.required
+
+You can mark attribute as required using `required` method:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql.attribute(:item).type('Item').required
+end
+```
+
+### attribute.optional
+
+You can mark attribute as optional using `optional` method:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql.attribute(:item).type('Item').optional
+end
+```
+
+### "attribute" configuration with chainable methods
+
+If your attribute definition is complex, you can define attribute in more eye-friendly chainable way with:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql do |c|
+    c.attribute(:shop_id)
+      .type('ID!')
+      .description('references to shop')
+  end
+end
+```
+
+### "attribute" configuration with a block
+
+You can also use block in order to specify attribute configuration:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql do |c|
+    c.attribute(:shop_id) do |attr|
+      attr.type 'ID!'
+      attr.description 'references to shop'
+    end
+  end
+end
+```
+
+## name
 
 By default grapqhl type name will be same as model name, but you can change it via `name` method
 
@@ -100,7 +290,7 @@ class User
 end
 ```
 
-### _description_
+## description
 
 To improve grapqhl documentation, you can description for your graphql type:
 
@@ -114,10 +304,158 @@ class User
 end
 ```
 
-### *graphql_type*
+## graphql_type
 
 Sometimes it's handy to get raw graphql type. To do so you can call:
 
 ```ruby
 YourModel.graphql.grapqhl_type
 ```
+
+## input
+
+You can define input types:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql.input do |c|
+    c.attribute :name
+  end
+end
+```
+
+Also you can have multiple input types:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql.input(:create) do |c|
+    c.attribute :name
+  end
+
+  graphql.input(:update) do |c|
+    c.attribute :id
+    c.attribute :name
+  end
+end
+```
+
+### input attribute
+
+Most commonly you will use `attribute` to define what kind of values your endpoint accepts
+
+#### input type
+
+You can specify your input attribute type. If type is not provided then type is set to `:string`.
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql.input do |c|
+    c.attribute :friends_count, type: :integer!
+  end
+end
+```
+
+#### required type
+
+There are few ways how to mark field as required.
+
+1. Adding exclamation mark at the end of type name:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql.input do |c|
+    c.attribute :friends_count, type: :integer!
+  end
+end
+```
+
+2. Adding `required: true` value
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql.input do |c|
+    c.attribute :friends_count, type: :integer, required: true
+  end
+end
+```
+
+#### input enum type
+
+You can specify your input attribute as enum:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql.input do |c|
+    c.attribute :favorite_fruit, enum: %i[apple orange]
+  end
+end
+```
+
+By default enum type is not required. To make it required add `required: true`:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql.input do |c|
+    c.attribute :favorite_fruit, required: true, enum: %i[apple orange]
+  end
+end
+```
+
+#### input attribute description
+
+To improve graphql endpoint documentation, you can add description for each input attribute:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql.input do |c|
+    c.attribute :name, description: "User's first name"
+  end
+end
+```
+
+## graphql_context
+
+It's possible to access graphql_context in your model using method `graphql_context`:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  def method_with_context
+    graphql_context[:some_data]
+  end
+end
+```
+
+Keep in mind that this value will be set only during graphql execution, but in tests this value will be `nil`. To avoid this, you need to set `show_graphql_context` manually like this:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  def show_graphql_context
+    graphql_context[:data]
+  end
+end
+
+user = User.new(...)
+user.show_graphql_context #=> NoMethodError: undefined method `[]' for nil:NilClass
+user.graphql_context =  { data: 'goes to context' }
+user.show_graphql_context #=> { data: 'goes to context' }
+```