graphql_rails 0.8.0 → 1.2.2

data/docs/README.md

@@ -22,13 +22,22 @@ Or install it yourself as:
 
     $ gem install graphql_rails
 
+## Getting started
+
+Execute:
+
+    $ bundle exec rails g graphql_rails:install
+
+This will generate code which will let you start your graphql faster
+
 ## Usage
 
 ### Define GraphQL schema as RoR routes
 
 ```ruby
-MyGraphqlSchema = GraphqlRails::Router.draw do
-  # will create createUser, updateUser, deleteUser mutations and user, users queries.
+# config/graphql/routes.rb
+GraphqlRails::Router.draw do
+  # will create createUser, updateUser, destroyUser mutations and user, users queries.
   # expects that UsersController class exist
   resources :users
 
@@ -41,6 +50,7 @@ end
 ### Define your Graphql model
 
 ```ruby
+# app/models/user.rb
 class User # works with any class including ActiveRecord
   include GraphqlRails::Model
 
@@ -57,10 +67,12 @@ end
 ### Define controller
 
 ```ruby
-class UsersController < GraphqlRails::Controller
+# app/controllers/graphql/users_controller.rb
+class Graphql::UsersController < GraphqlApplicationController
   # graphql requires to describe which attributes controller action accepts and which returns
   action(:change_user_password)
     .permit(:password!, :id!) # Bang (!) indicates that attribute is required
+    .returns('User!')
 
   def change_user_password
     user = User.find(params[:id])
@@ -70,7 +82,9 @@ class UsersController < GraphqlRails::Controller
     user # or SomeDecorator.new(user)
   end
 
-  action(:search).permit(search_fields!: SearchFieldsInput) # you can specify your own input fields
+  action(:search)
+    .permit(search_fields!: SearchFieldsInput) # you can specify your own input fields
+    .returns('[User!]!')
   def search
   end
 end
@@ -79,7 +93,7 @@ end
 ## Routes
 
 ```ruby
-MyGraphqlSchema = GraphqlRails::Router.draw do
+GraphqlRails::Router.draw do
   # generates `friend`, `createFriend`, `updateFriend`, `destroyFriend`, `friends` routes
   resources :friends
   resources :shops, only: [:show, :index] # generates `shop` and `shops` routes only
@@ -95,10 +109,10 @@ MyGraphqlSchema = GraphqlRails::Router.draw do
 
   # you can use namespaced controllers too:
   scope module: 'admin' do
-    # `updateTranslations` route will be handeled by `Admin::TranslationsController`
+    # `updateTranslations` route will be handled by `Admin::TranslationsController`
     mutation :updateTranslations, to: 'translations#update'
 
-    # all :groups routes will be handeled by `Admin::GroupsController`
+    # all :groups routes will be handled by `Admin::GroupsController`
     resources :groups
   end
 end
@@ -132,11 +146,13 @@ There are 3 helper methods:
 
 ```ruby
 class MyGraphqlController
+  action(:create_user).permit(:full_name, :email).returns(User)
+  action(:index).returns('String')
+
   def index
     "Called from index: #{params[:message]}"
   end
 
-  action(:create_user).permit(:full_name, :email)
   def create_user
     User.create!(params)
   end

data/docs/_sidebar.md

@@ -9,3 +9,6 @@
   * [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

@@ -78,7 +78,7 @@ Specifies input type:
 class OrderController < GraphqlRails::Controller
   action(:create)
     .permit_input(:price, type: :integer!)
-    # Same as `.permit(amount: :integer!)`
+    # Same as `.permit(price: :integer!)`
 end
 ```
 
@@ -155,22 +155,6 @@ class OrderController < GraphqlRails::Controller
 end
 ```
 
-### *can_return_nil*
-
-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:
-
-```ruby
-class UsersController < GraphqlRails::Controller
-  action(:show).permit(:email).can_return_nil
-
-  def show
-    user = User.find_by(email: params[:email])
-    return nil if user.blank?
-    user
-  end
-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)
@@ -185,7 +169,7 @@ class UsersController < GraphqlRails::Controller
 end
 ```
 
-Also check ['decorating controller responses']('components/decorator') for more details about working with active record and decorators.
+Also check ['decorating controller responses'](components/decorator) for more details about working with active record and decorators.
 
 #### *max_page_size*
 
@@ -201,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
@@ -215,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:
@@ -262,6 +308,39 @@ class UsersController < GraphqlRails::Controller
 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:
@@ -367,7 +446,7 @@ class UsersController < GraphqlRails::Controller
     raise 'Not authenticated' unless User.where(token: params[:token]).exist?
   end
 
-  def require_auth_token
+  def require_admin_token
     raise 'Admin not authenticated' unless Admin.where(token: params[:admin_token]).exist?
   end
 end
@@ -375,4 +454,98 @@ end
 
 ## decorating objects
 
-See ['Decorating controller responses']('components/decorator') for various options how you can decorate paginated responses
+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/model.md

@@ -17,13 +17,13 @@ end
 
 ## 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
 
 Most commonly you will use `attribute` to make your model methods and attributes visible via graphql endpoint.
 
-## attribute type
+### attribute.type
 
 Some types can be determined by attribute name, so you can skip this attribute:
 
@@ -54,9 +54,33 @@ class User
 end
 ```
 
-### attribute 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
@@ -72,7 +96,7 @@ class User
 end
 ```
 
-### attribute description
+### attribute.description
 
 You can also describe each attribute and make graphql documentation even more readable. To do so, add `description` option:
 
@@ -86,6 +110,139 @@ class User
 end
 ```
 
+### 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:
@@ -271,3 +428,34 @@ class User
   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' }
+```