graphql_rails 2.2.0 → 2.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1909c3b76c9addab63bcc0337232c147ceebde0d1f2252da93606b48d1843c64
-  data.tar.gz: 6b405941e4bae0e98abbcc07b93ac1a95fa22bcbdfcaa962d241740a15453ba7
+  metadata.gz: 9ef0115ce3d9107ee48ec4e7a725baff242ce81133be4a955d0a81619b106192
+  data.tar.gz: dcb027f23eb5f6cd71b3144e2794822ee899796a5e40f7b240ea3cd59ef586b9
 SHA512:
-  metadata.gz: f5292647cd5c49c51bec7f9f1df33be882637ac83bd54fb23259fc2b5c6d8f351f3501c5db23f0ff7c10daafafed531b4026ff3790ff281cfd71890ff2b2c007
-  data.tar.gz: 054adf43e83c54be23fb33547ee521e17ae8f180f5f4c05bf3a7b78f554367e6531483d9bf66af75fe4567940f2931c56f93c2adc6af412efba8e644043af8bc
+  metadata.gz: 8282983f1215feffb37e0541680abd91a44799a95d687cb3adb5cfcb91a1adbf8a07d585fffcd4e477579eebdd9f4a09f0efbc6dfb0b264b0a1a288aa0ac9688
+  data.tar.gz: f7cafd9924e8e26abc9a6e5783938ebedbea7a0dd68fc69a5980186affab6593f8af4a25c8205e20fbfb45534bec96aa4b5b36bc558084994200a73f8eca31d7

data/.github/workflows/ruby.yml

@@ -3,14 +3,15 @@ on: [push, pull_request]
 jobs:
   specs:
     strategy:
+      fail-fast: false
       matrix:
-        ruby-version: ['2.6', '2.7', '3.0']
+        ruby-version: ['2.7', '3.0', '3.1', '3.2']
 
     runs-on: ubuntu-latest
     env:
       CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
       - uses: ruby/setup-ruby@v1
         with:
           ruby-version: ${{ matrix.ruby-version }}

data/.ruby-version

@@ -1 +1 @@
-3.0.1
+3.1.2

data/CHANGELOG.md

@@ -9,6 +9,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 * Added/Changed/Deprecated/Removed/Fixed/Security: YOUR CHANGE HERE
 
+## [2.4.0](2023-27-25)
+
+* Added: `hidden_in_groups` for attributes to be able to skip attribute from certain groups
+* Added: `extras` for attributes to be able to include graphql-ruby extensions
+* Added: `lookahead` as a controller request object field
+* Changed: `subscription` definition to `event` definition in router configuration page
+* Fixed: avoid "Found two visible definitions for X" issues for input types
+
+## [2.3.0](2022-11-25)
+
+* Added support for Ruby 3.1.2, keyword arguments for decorators support included
+* Added: error backtrace to SystemError
+* Fixed: skip "base" field name in validation error messages
+* Added: router namespaces and named scopes
+* Added: `deprecate` method/option for attributes and input attributes
+
 ## [2.2.0](2022-01-25)
 
 * Added: support for subscription type

data/Gemfile.lock

@@ -1,9 +1,9 @@
 PATH
   remote: .
   specs:
-    graphql_rails (2.2.0)
+    graphql_rails (2.4.0)
       activesupport (>= 4)
-      graphql (~> 1.12, >= 1.12.4)
+      graphql (= 2.0.21)
 
 GEM
   remote: https://rubygems.org/
@@ -74,17 +74,17 @@ GEM
     codecov (0.6.0)
       simplecov (>= 0.15, < 0.22)
     coderay (1.1.3)
-    concurrent-ruby (1.1.9)
+    concurrent-ruby (1.1.10)
     crass (1.0.6)
     diff-lcs (1.5.0)
     docile (1.4.0)
     erubi (1.10.0)
-    globalid (1.0.0)
+    globalid (1.0.1)
       activesupport (>= 5.0)
-    graphql (1.13.6)
-    i18n (1.8.11)
+    graphql (2.0.21)
+    i18n (1.12.0)
       concurrent-ruby (~> 1.0)
-    loofah (2.13.0)
+    loofah (2.19.1)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     mail (2.7.1)
@@ -92,8 +92,8 @@ GEM
     marcel (1.0.2)
     method_source (1.0.0)
     mini_mime (1.1.2)
-    mini_portile2 (2.7.1)
-    minitest (5.15.0)
+    mini_portile2 (2.8.1)
+    minitest (5.17.0)
     mongo (2.17.0)
       bson (>= 4.8.2, < 5.0.0)
     mongoid (7.3.3)
@@ -101,8 +101,8 @@ GEM
       mongo (>= 2.10.5, < 3.0.0)
       ruby2_keywords (~> 0.0.5)
     nio4r (2.5.8)
-    nokogiri (1.13.1)
-      mini_portile2 (~> 2.7.0)
+    nokogiri (1.14.3)
+      mini_portile2 (~> 2.8.0)
       racc (~> 1.4)
     parallel (1.21.0)
     parser (3.1.0.0)
@@ -113,8 +113,8 @@ GEM
     pry-byebug (3.9.0)
       byebug (~> 11.0)
       pry (~> 0.13.0)
-    racc (1.6.0)
-    rack (2.2.3)
+    racc (1.6.2)
+    rack (2.2.6.4)
     rack-test (1.1.0)
       rack (>= 1.0, < 3)
     rails (6.1.4.4)
@@ -135,8 +135,8 @@ GEM
     rails-dom-testing (2.0.3)
       activesupport (>= 4.2.0)
       nokogiri (>= 1.6)
-    rails-html-sanitizer (1.4.2)
-      loofah (~> 2.3)
+    rails-html-sanitizer (1.4.4)
+      loofah (~> 2.19, >= 2.19.1)
     railties (6.1.4.4)
       actionpack (= 6.1.4.4)
       activesupport (= 6.1.4.4)
@@ -193,13 +193,13 @@ GEM
       activesupport (>= 5.2)
       sprockets (>= 3.0.0)
     thor (1.2.1)
-    tzinfo (2.0.4)
+    tzinfo (2.0.5)
       concurrent-ruby (~> 1.0)
     unicode-display_width (1.8.0)
     websocket-driver (0.7.5)
       websocket-extensions (>= 0.1.0)
     websocket-extensions (0.1.5)
-    zeitwerk (2.5.3)
+    zeitwerk (2.6.6)
 
 PLATFORMS
   ruby

data/docs/README.md

@@ -42,11 +42,12 @@ GraphqlRails::Router.draw do
   resources :users
 
   # if you want custom queries or mutation
-  query 'searchLogs', to: 'logs#search' # redirects request to LogsController
-  mutation 'changeUserPassword', to: 'users#change_password'
+  query 'searchLogs', to: 'logs#search' # action is handled by LogsController#search
 end
 ```
 
+See [Routes docs](components/routes.md) for more info.
+
 ### Define your Graphql model
 
 ```ruby
@@ -56,67 +57,42 @@ class User # works with any class including ActiveRecord
 
   graphql do |c|
     # most common attributes, like :id, :name, :title has default type, so you don't have to specify it (but you can!)
-    c.attribute :id
+    c.attribute(:id)
 
-    c.attribute :email, type: :string
-    c.attribute :surname, type: :string
+    c.attribute(:email).type('String')
+    c.attribute(:surname).type('String')
   end
 end
 ```
 
+See [Model docs](components/model.md) for more info.
+
 ### Define controller
 
 ```ruby
 # 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!')
+  model('User') # specify that all actions returns User by default
 
-  def change_user_password
-    user = User.find(params[:id])
-    user.update!(password: params[:password])
+  # DRUD actions description
+  action(:index).permit(id: 'ID!').returns_many
+  action(:show).permit(id: 'ID!').returns_single
+  action(:create).permit(email: 'String!').returns_single
+  action(:update).permit(id: 'ID!', email: 'String!').returns_single
+  action(:destroy).permit(id: 'ID!').returns_single
 
-    # returned value needs to have all methods defined in model `graphql do` part
-    user # or SomeDecorator.new(user)
+  def index
+    User.all
   end
 
-  action(:search)
-    .permit(search_fields!: SearchFieldsInput) # you can specify your own input fields
-    .returns('[User!]!')
-  def search
+  def show
+    User.find(params[:id])
   end
+  # ... code for create / update / destroy is skipped ...
 end
 ```
 
-## Routes
-
-```ruby
-GraphqlRails::Router.draw do
-  # generates `friend`, `createFriend`, `updateFriend`, `destroyFriend`, `friends` routes
-  resources :friends
-  resources :shops, only: [:show, :index] # generates `shop` and `shops` routes only
-  resources :orders, except: :update # generates all routes except `updateOrder`
-
-  resources :users do
-    # generates `findUser` query
-    query :find, on: :member
-
-    # generates `searchUsers` query
-    query :search, on: :collection
-  end
-
-  # you can use namespaced controllers too:
-  scope module: 'admin' do
-    # `updateTranslations` route will be handled by `Admin::TranslationsController`
-    mutation :updateTranslations, to: 'translations#update'
-
-    # all :groups routes will be handled by `Admin::GroupsController`
-    resources :groups
-  end
-end
-```
+See [Controller docs](components/controller.md) for more info.
 
 ## Testing your GraphqlRails::Controller in RSpec
 
@@ -134,6 +110,8 @@ RSpec.configure do |config|
 end
 ```
 
+See [Testing docs](testing/testing.md) for more info.
+
 ### Helper methods
 
 There are 3 helper methods:

data/docs/_sidebar.md

@@ -1,7 +1,6 @@
 * [Home](README)
 * Getting started
   * [Setup](getting_started/setup)
-  * [Quick start](getting_started/quick_start)
 * Components
   * [Routes](components/routes)
   * [Model](components/model)

data/docs/components/controller.md

@@ -144,7 +144,7 @@ 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
+class UsersController < GraphqlRails::Controller
   # this is the input with email and full_name:
   action(:create)
     .permit_input(:input, type: 'User!')
@@ -155,6 +155,20 @@ class OrderController < GraphqlRails::Controller
 end
 ```
 
+#### *deprecated*
+
+You can mark input input as deprecated with `deprecated` option:
+
+```ruby
+class UsersController < GraphqlRails::Controller
+  action(:create)
+    .permit_input(:input, type: 'User', deprecated: true)
+
+  action(:update)
+    .permit_input(:input, type: 'User', deprecated: 'use updateBasicUser instead')
+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)

data/docs/components/decorator.md

@@ -46,7 +46,7 @@ class UserDecorator < SimpleDelegator
   include GraphqlRails::Model
   include GraphqlRails::Decorator
 
-  graphql_rails do
+  graphql do |c|
     # some setup, attributes, etc...
   end
 

data/docs/components/model.md

@@ -101,7 +101,7 @@ Check [graphql-ruby documentation](https://graphql-ruby.org) for more details ab
 
 ### 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:
+By default graphql attribute names are expected to be same as model methods/attributes, but if you want to use different name on graphql side, you can use `property` option:
 
 ```ruby
 class User
@@ -131,6 +131,21 @@ class User
 end
 ```
 
+### attribute.deprecated
+
+Attribute can be marked as deprecated with `deprecated` method:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql do |c|
+    c.attribute(:legacy_name).deprecated
+    c.attribute(:legacy_id).deprecated('This is my custom deprecation reason')
+  end
+end
+```
+
 ### attribute.groups
 
 Groups are handy feature when you want to have multiple schemas. For example, you want to have public graphql endpoint and internal graphql endpoint where each group has some unique nodes. If attribute has `groups` set, then this attribute will be visible only in appropriate group schemas.
@@ -170,6 +185,24 @@ class User
 end
 ```
 
+### attribute.hidden_in_groups
+
+Opposite for Attribute#groups. It hides attribute in given groups
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql do |c|
+    # visible in all schemas (default):
+    c.attribute(:email)
+
+    # visible in all schemas except "external":
+    c.attribute(:nickname).hidden_in_groups(:external)
+  end
+end
+```
+
 ### attribute.options
 
 Allows passing options to attribute definition. Available options:
@@ -185,6 +218,21 @@ class User
     c.attribute :first_name, options: { attribute_name_format: :original } # will be accessible as first_name from client side
   end
 end
+```
+
+### attribute.extras
+
+Allows passing extras to enable [graphql-ruby field extensions](https://graphql-ruby.org/type_definitions/field_extensions.html#using-extras)
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql do |c|
+    c.attribute(:items).extras([:lookahead])
+  end
+end
+```
 
 ### attribute.permit
 
@@ -263,6 +311,23 @@ class User
 end
 ```
 
+#### *deprecated*
+
+You can mark input input as deprecated with `deprecated` option:
+
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql.attribute(:avatar_url)
+         .permit_input(:size, type: :int!, deprecated: true)
+
+  graphql.attribute(:logo_url)
+         .permit_input(:size, type: :int!, deprecated: 'custom image size is deprecated')
+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)
@@ -271,7 +336,7 @@ You can mark collection method as `paginated`. In this case method will return r
 class User
   include GraphqlRails::Model
 
-  graphql.attribute :items, type: '[Item]', paginatted: true
+  graphql.attribute :items, type: '[Item]', paginated: true
 
   def items
     Item.all
@@ -356,7 +421,7 @@ end
 
 ## name
 
-By default grapqhl type name will be same as model name, but you can change it via `name` method
+By default graphql type name will be same as model name, but you can change it via `name` method
 
 ```ruby
 class User
@@ -370,7 +435,7 @@ end
 
 ## description
 
-To improve grapqhl documentation, you can description for your graphql type:
+To improve graphql documentation, you can description for your graphql type:
 
 ```ruby
 class User
@@ -387,7 +452,7 @@ end
 Sometimes it's handy to get raw graphql type. To do so you can call:
 
 ```ruby
-YourModel.graphql.grapqhl_type
+YourModel.graphql.graphql_type
 ```
 
 ## input
@@ -523,6 +588,36 @@ class User
 end
 ```
 
+
+#### input attribute deprecation
+
+You can mark input attribute as deprecated with `deprecated` method:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql.input do |c|
+    c.attribute(:full_name).deprecated('Use firstName and lastName instead')
+    c.attribute(:surname).deprecated
+  end
+end
+```
+
+#### input attribute default value
+
+You can set default value for input attribute:
+
+```ruby
+class User
+  include GraphqlRails::Model
+
+  graphql.input do |c|
+    c.attribute(:is_admin).type('Boolean').default_value(false)
+  end
+end
+```
+
 ## graphql_context
 
 It's possible to access graphql_context in your model using method `graphql_context`:

data/docs/components/routes.md

@@ -21,10 +21,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
@@ -40,9 +40,9 @@ If you want to exclude some actions you can use `only` or `except` options.
 
 ```ruby
 MyGraphqlSchema = GraphqlRails::Router.draw do
-  resouces :users
-  resouces :friends, only: :index
-  resouces :posts, except: [:destroy, :index]
+  resources :users
+  resources :friends, only: :index
+  resources :posts, except: [:destroy, :index]
 end
 ```
 
@@ -52,7 +52,7 @@ Sometimes it's handy so have non-CRUD actions in your controller. To define such
 
 ```ruby
 MyGraphqlSchema = GraphqlRails::Router.draw do
-  resouces :users do
+  resources :users do
     mutation :changePassword, on: :member
     query :active, on: :collection
   end
@@ -65,7 +65,7 @@ Sometimes, especially when working with member queries, it sounds better when ac
 
 ```ruby
 MyGraphqlSchema = GraphqlRails::Router.draw do
-  resouces :users do
+  resources :users do
     query :details, on: :member, suffix: true
   end
 end
@@ -73,15 +73,25 @@ end
 
 This will generate `userDetails` field on GraphQL side.
 
-## _query_ and _mutation_ & _subscription_
+## _query_ and _mutation_ & _event_
 
-in case you want to have non-CRUD controller with custom actions you can define your own `query`/`mutation`/`subscription` actions like this:
+In case you want to have non-CRUD controller with custom actions you can define your own `query`/`mutation` actions like this:
 
 ```ruby
 MyGraphqlSchema = GraphqlRails::Router.draw do
   mutation :logIn, to: 'sessions#login'
   query :me, to: 'users#current_user'
-  subscribtion :new_message, to: 'messages#created'
+end
+
+Subscriptions are not really controller actions with a single response type, thus, they're defined differently. In GraphQL you subscribe to event, for example `userCreated`. To do this in graphql_rails you would define `event :user_created` in router definition.
+
+```ruby
+MyGraphqlSchema = GraphqlRails::Router.draw do
+  mutation :logIn, to: 'sessions#login'
+  query :me, to: 'users#current_user'
+
+  event :user_created # expects Subscriptions::UserCreatedSubscription class to be present
+  event :user_deleted, subscription_class: 'Subscriptions::UserDeletedSubscription'
 end
 ```
 
@@ -89,18 +99,54 @@ end
 
 ### _module_ options
 
-currently `scope` method accepts single option: `module`. `module` allows to specify controller namespace. So you can use scoped controllers, like so:
+If you want to want to route everything to controllers, located at `controllers/admin/top_secret`, you can use scope with `module` param:
 
 ```ruby
-MyGraphqlSchema = GraphqlRails::Router.draw do
-  scope module: 'admin/top_secret' do
-    mutation :logIn, to: 'sessions#login' # this will trigger Admin::TopSecret::SessionsController
-  end
+scope module: 'admin/top_secret' do
+  mutation :logIn, to: 'sessions#login' # this will trigger Admin::TopSecret::SessionsController
+end
+```
+
+### Named scope
 
+If you want to nest some routes under some other node, you can use named scope:
+
+```ruby
+scope :admin do
   mutation :logIn, to: 'sessions#login' # this will trigger ::SessionsController
 end
 ```
 
+This action will be accessible via:
+
+```graphql
+mutation {
+  admin {
+    logIn(email: 'john@example.com') { ... }
+  }
+}
+```
+
+## _namespace_
+
+You may wish to organize groups of controllers under a namespace. Most commonly, you might group a number of administrative controllers under an `Admin::` namespace, and place these controllers under the app/controllers/admin directory. You can route to such a group by using a namespace block:
+
+```ruby
+  namespace :admin do
+    resources :articles, only: :show
+  end
+```
+
+On GraphQL side, you can reach such route with the following query:
+
+```graphql
+query {
+  admin {
+    article(id: '123') { ... }
+  }
+}
+```
+
 ## _group_
 
 You can have multiple routers / schemas. In order to add resources or query only to specific schema, you need wrap it with `group` method, like this:

data/graphql_rails.gemspec

@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'graphql', '~> 1.12', '>= 1.12.4'
+  spec.add_dependency 'graphql', '2.0.21'
   spec.add_dependency 'activesupport', '>= 4'
 
   spec.add_development_dependency 'bundler', '~> 2'

data/lib/generators/graphql_rails/templates/graphql_controller.erb

@@ -12,7 +12,7 @@ class GraphqlController < ApplicationController
 
   private
 
-  # data defined here will be accessible via `grapqhl_request.context`
+  # data defined here will be accessible via `graphql_request.context`
   # in GraphqlRails::Controller instances
   def graphql_context
     {}

data/lib/graphql_rails/attributes/attribute.rb

@@ -32,8 +32,8 @@ module GraphqlRails
         [
           field_name,
           type_parser.type_arg,
-          *description
-        ]
+          description
+        ].compact
       end
 
       def field_options
@@ -41,30 +41,32 @@ module GraphqlRails
           method: property.to_sym,
           null: optional?,
           camelize: camelize?,
-          groups: groups
+          groups: groups,
+          hidden_in_groups: hidden_in_groups,
+          **deprecation_reason_params,
+          **extras_options
         }
       end
 
-      def argument_args
-        [
-          field_name,
-          type_parser.type_arg,
-          {
-            description: description,
-            required: required?
-          }
-        ]
-      end
-
       protected
 
       attr_reader :initial_name
 
       private
 
+      def extras_options
+        return {} if extras.empty?
+
+        { extras: extras }
+      end
+
       def camelize?
         options[:input_format] != :original && options[:attribute_name_format] != :original
       end
+
+      def deprecation_reason_params
+        { deprecation_reason: deprecation_reason }.compact
+      end
     end
   end
 end