graphql_rails 0.8.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 233cb42d66f27e1bd3b18d5530977285e84358897d9fa4cde2230a811b4712b1
-  data.tar.gz: 773ff5c8223431e2b606c522fbcc5275157d7255b6348bf475a0aa9c76282926
+  metadata.gz: fcc5df5d34e3bf317dd9bb07e2b846bf8dfa48e990258b4bb2f30ef73d049939
+  data.tar.gz: 6cd112b22a0d01f031dd2aba92efc390d44b209c8d6a428e257d1be99377f28c
 SHA512:
-  metadata.gz: c1034a92ab82fb88dfb94b2eb6502b51e2d97ef4f04e6804abd6cb3a8900117682f6cc717576d5aa16008d3486a8182dc2f503d5d307ad9184177e7968d13467
-  data.tar.gz: d44a9b5d7ad5d3a2663bc40edcef96240e7525e2060ca57d360b6b8640af03ebfd3dc13eae97e11ac77d07d1d283a9480bd567e84aa0f7dc8960e35d6ad329a1
+  metadata.gz: 59f24a1ad00e309c7617a6ed65200dc11f62680974f3de7ca4e36d96b0d8dab8f286c8c9c4b50dd4b70a375959187ce21d09a309075a4ffa009716d3b74e7df7
+  data.tar.gz: ca1500174b1443240db65e3b57dbe0616ad7038da3e6f833ca2979e2fb4de7074c8ce9671c55dfa07bb327f4469b7999b8f00769a686c8829abfcf2eb275b6e0

data/CHANGELOG.md

@@ -9,6 +9,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * Added/Changed/Deprecated/Removed/Fixed/Security: YOUR CHANGE HERE
 
+## [1.0.0](2020-02-07)
+
+* Added: "required" and "optional" flags for attribute
+* Added: grouped routes
+* Added: added argument to model.attribute
+* Added: added graphql_context to model
+* Removed: `action.can_return_nil` was removed, because it does no affect anymore
+* Removed: default `action` model was removed. Now each action must have `returns` part
+* Added: default router added. No need to assign value to constant on Router.draw
+* Added: default action added. Now actions can have custom defaults
+* Added: default controller model added. Now actions can be defined in more dynamic way
+* Added: install generator. Now it's possible to generate boilerplate code
+
 ## [0.8.0] (2019-09-03)
 
 * Added: permit_input action config with extended list of permitted input options

data/Gemfile.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    graphql_rails (0.8.0)
+    graphql_rails (1.0.0)
       activesupport (>= 4)
-      graphql (~> 1)
+      graphql (>= 1.9.12)
 
 GEM
   remote: https://rubygems.org/
@@ -60,18 +60,18 @@ GEM
       url
     coderay (1.1.2)
     concurrent-ruby (1.1.5)
-    crass (1.0.4)
+    crass (1.0.5)
     diff-lcs (1.3)
-    docile (1.3.1)
+    docile (1.3.2)
     erubi (1.8.0)
     globalid (0.4.2)
       activesupport (>= 4.2.0)
-    graphql (1.9.7)
+    graphql (1.9.17)
     i18n (1.6.0)
       concurrent-ruby (~> 1.0)
-    jaro_winkler (1.5.2)
-    json (2.2.0)
-    loofah (2.2.3)
+    jaro_winkler (1.5.4)
+    json (2.3.0)
+    loofah (2.3.1)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     mail (2.7.1)
@@ -89,10 +89,10 @@ GEM
       activemodel (>= 5.1, < 6.0.0)
       mongo (>= 2.5.1, < 3.0.0)
     nio4r (2.3.1)
-    nokogiri (1.10.4)
+    nokogiri (1.10.5)
       mini_portile2 (~> 2.4.0)
-    parallel (1.16.0)
-    parser (2.6.2.0)
+    parallel (1.19.1)
+    parser (2.7.0.2)
       ast (~> 2.4.0)
     pry (0.12.2)
       coderay (~> 1.1.0)
@@ -100,8 +100,7 @@ GEM
     pry-byebug (3.7.0)
       byebug (~> 11.0)
       pry (~> 0.10)
-    psych (3.1.0)
-    rack (2.0.7)
+    rack (2.0.8)
     rack-test (1.1.0)
       rack (>= 1.0, < 3)
     rails (5.2.2.1)
@@ -143,22 +142,20 @@ GEM
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.8.0)
     rspec-support (3.8.0)
-    rubocop (0.66.0)
+    rubocop (0.79.0)
       jaro_winkler (~> 1.5.1)
       parallel (~> 1.10)
-      parser (>= 2.5, != 2.5.1.1)
-      psych (>= 3.1.0)
+      parser (>= 2.7.0.1)
       rainbow (>= 2.2.2, < 4.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 1.6)
+      unicode-display_width (>= 1.4.0, < 1.7)
     rubocop-rspec (1.32.0)
       rubocop (>= 0.60.0)
-    ruby-progressbar (1.10.0)
-    simplecov (0.16.1)
+    ruby-progressbar (1.10.1)
+    simplecov (0.18.1)
       docile (~> 1.1)
-      json (>= 1.8, < 3)
-      simplecov-html (~> 0.10.0)
-    simplecov-html (0.10.2)
+      simplecov-html (~> 0.11.0)
+    simplecov-html (0.11.0)
     sprockets (3.7.2)
       concurrent-ruby (~> 1.0)
       rack (> 1, < 3)
@@ -170,7 +167,7 @@ GEM
     thread_safe (0.3.6)
     tzinfo (1.2.5)
       thread_safe (~> 0.1)
-    unicode-display_width (1.5.0)
+    unicode-display_width (1.6.1)
     url (0.3.2)
     websocket-driver (0.7.1)
       websocket-extensions (>= 0.1.0)

data/docs/README.md

@@ -22,12 +22,21 @@ 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
+# config/graphql/routes.rb
+GraphqlRails::Router.draw do
   # will create createUser, updateUser, deleteUser 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
@@ -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

@@ -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)
@@ -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,32 @@ class UsersController < GraphqlRails::Controller
 end
 ```
 
+### *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 +292,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:
@@ -376,3 +439,97 @@ 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 simples way to render error is to provide 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 inherits from `GraphqlRails::ExecutionError`
+
+```ruby
+class MyCustomError < GraphqlRails::ExecutionError
+  def to_h
+    # this part will be rendered in graphl
+    { 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

@@ -23,7 +23,7 @@ This method must be called inside your model body. `grapqhl` is used for making
 
 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,7 +54,7 @@ class User
 end
 ```
 
-### attribute property
+### 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 `propery` option:
 
@@ -72,7 +72,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 +86,123 @@ class User
 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 +388,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' }
+```