graphqr 0.0.4 → 0.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f872050870c704c750620f560725fedbb386e1e2
-  data.tar.gz: a951daec569df80f61bcc745c539d5a3ebcea16f
+  metadata.gz: 876e07cf3e0eb24c8d8c71f23b23e18ae3d014bc
+  data.tar.gz: bcd24faba39f7be1b3a07ca3629bf6f680f10c25
 SHA512:
-  metadata.gz: f449a600a8c747a0ccbc0e54380862c0981f4be15b41298a0bb5b2a6b162b3ae74846e7a14f863ebc22e743ff61aadd26eb64d3f7bebc5084f65620c24ea4b70
-  data.tar.gz: 28446614b1c6cde4eb44efca6656831dff436c4a4ffab9d29ae3031717499ec8a6ba357dfa4d86da22102a549d46e49a4df4207dd768a1839c0f1b228758b8e9
+  metadata.gz: 51f5c95b0ba53fe528e7e275bf6e00063c4d2cbd6add26bdc16cf41b0f2f2e6f4884e776108e8e4f3a522121ad0419863e50d111f0dadd0ce577d3611c524cf8
+  data.tar.gz: cf5ff9b77895930d9d7bc9d8aa6adb3bdd494c34c6310139055e4ebb57e3403903810a197cd6f0098855dcfad2b0c275ec715bf21ef212569c7b7beeb9290bfa

data/README.md

@@ -1,11 +1,14 @@
+[![Gem Version](https://badge.fury.io/rb/graphqr.svg)](https://rubygems.org/gems/graphqr)
 [![Build Status](https://travis-ci.com/QultureRocks/graphqr.svg?branch=master)](https://travis-ci.com/QultureRocks/graphqr)
 [![Maintainability](https://api.codeclimate.com/v1/badges/7f7b51e89e8fe4de1b23/maintainability)](https://codeclimate.com/github/QultureRocks/graphqr/maintainability)
 
 # GraphQR
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/graphqr`. To experiment with that code, run `bin/console` for an interactive prompt.
+A compilation of useful extensions and helpers for [graphql-ruby](https://github.com/rmosolgo/graphql-ruby).
+
+- [API Documentation](https://qulturerocks.github.io/graphqr/)
+- [Qulture.Rocks](https://qulture.rocks)
 
-TODO: Delete this and the text above, and describe your gem
 
 ## Installation
 
@@ -23,12 +26,171 @@ Or install it yourself as:
 
     $ gem install graphqr
 
-If you'd like to use the pagination feature, you must have `pagy` installed.
+## Configuration (optional)
+
+GraphQR uses `pagy` and `pundit` by default and activates both `Authorization` and `Pagination` modules.
+If you'd like to create a specific configuration, create `config/initializers/graphql.rb` with
+
+```
+GraphQR.configure do |config|
+  config.use_pagination = true # or false to disable
+  config.use_authorization = true # or false to disable
+
+  config.paginator = :pagy # only pagy is available for now
+  config.policy_provider = :pundit # only pundit is available for now
+end
+```
+
+## Modules
+
+To use the extensions correctly add
+```
+field_class GraphQR::Fields::BaseField
+```
+
+to your `BaseObject` class. This will add the `paginate` options to your fields and add the necessary extensions according to the modules you activated.
+
+### Pagination
+
+The Pagination module consists in a easier way of dealing with pages. Instead of using `cursors` we implemented a more Rails way using `per` and `page`.
+Our implementation is (for now) based on [Pagy](https://github.com/ddnexus/pagy) so you must have it installed.
+
+To use the Pagination module add
+
+```
+extend GraphQR::Pagination
+```
+
+to any `GraphQL::Schema::Object` you'd like, but we recommend adding it to your `BaseObject` class.
+
+#### Usage
+
+```
+field :users, UserType.pagination_type, paginate: true
+```
+
+A `pagination_type` adds the `per` and `page` arguments and adds a `page_info` field to the response.
+
+Example gql:
+```
+users(per: 10, page: 1) {
+  nodes {
+    id
+    name
+  }
+}
+```
+
+### Authorization
+
+The Authorization module in some wrappers around a `PolicyProvider` (only Pundit for now). And allows some basic behaviors.
+Everything on this module depends on a `policy_provider` passed to the GraphQL context. You can add it like this:
+
+```
+context = {
+  policy_provider: GraphQR::Policies::PunditProvider.new(policy_context: pundit_user)
+  ...
+}
+
+Schema.execute(query, variables: variables, context: context, operation_name: operation_name)
+```
+
+#### Authorized
+
+This module adds a check on the object policy before resolving it. It always searches for the `show?` policy of the record.
+It works by extending the `authorized?` method.
+
+To add this behavior, add
+```
+extend GraphQR::Authorized
+```
+to any `GraphQL::Schema::Object` you'd like, but we recommend adding it to your `BaseObject` class.
+
+Example:
+
+```
+users {
+  id
+  tags {
+    id
+  }
+}
+```
+
+In this case, the authorization check will run for each `user`, calling `UserPolicy.show?` and for each tag, calling `TagPolicy.show?`.
+If any policy returns falsy, the object is returned as `null`.
+
+#### ScopeItems
+
+This module adds the PolicyProvider scope to the fields that represent an `ActiveRecord::Relation`. It works by implementing the `self.scope_items` method.
+
+To add this behavior, add
+```
+extend GraphQR::ScopeItems
+```
+to any `GraphQL::Schema::Object` you'd like, but we recommend adding it to your `BaseObject` class.
+
+Example:
+
+```
+users {
+  id
+}
+```
+
+In this case, the `users` list will be scoped using `UserPolicy::Scope` provided by Pundit.
+
+#### AuthorizeGraphQL
+
+This module is a wrapper around the PolicyProvider authorization.
+It adds the `authorize_graphql` method, similar to Pundit's `authorize`, but it returns an `GraphQL::ExecutionError` instead of a `Pundit::NotAuthorizedError`
+
+To add this behavior, add
+```
+include GraphQR::AuthorizeGraphQL
+```
+where you want to use this methos, but we recommend adding it to your `Mutations` and `Resolvers` classes.
+
+Example:
+
+```
+authorize_graphql User, :index?
+```
+
+### Helpers
+
+We also provide some helpers to make implementing GraphQL on ruby easier.
+
+#### ApplyScopes
+
+This modules is based on the [has_scope](https://github.com/plataformatec/has_scope/) gem.
+It provides an `apply_scopes` method that can search for model scopes and use them on a collection
+
+To add this method, add
+```
+include GraphQR::ApplyScopes
+```
+where you'd like to use it, but we recommend adding it to your `Resolvers`.
+
+Example:
+
+```
+apply_scopes(User, { order_by_name: true, with_id: [1,2,3] })
+```
+
+#### QueryField
+
+This module adds the `query_field` helper.
+It adds an easy way of creating simple fields with resolvers.
+
+To add this method, add
+```
+extend GraphQR::QueryField
+```
+to your `BaseObject`.
 
-## Usage
+Read more about its use in the [documentation](https://qulturerocks.github.io/graphqr/GraphQR/QueryField.html)
 
-[Documentation](https://qulturerocks.github.io/graphqr/)
-TODO: Write usage instructions here
 
 ## Development
 

data/lib/graphqr.rb

@@ -8,6 +8,14 @@ require 'graphqr/configuration'
 # it contains helpers and integrations we need to keep our workflow as simple as possible.
 module GraphQR
   class << self
+    def use_pagination
+      GraphQR.config.use_pagination || true
+    end
+
+    def use_authorization
+      GraphQR.config.use_authorization || true
+    end
+
     def paginator
       GraphQR.config.paginator
     end
@@ -38,6 +46,7 @@ rescue NameError
   Kernel.warn 'Pagy not found'
 end
 
+require 'graphqr/policies/authorize_graphql'
 begin
   require 'graphqr/policies/pundit_provider'
 rescue LoadError
@@ -46,7 +55,6 @@ end
 
 require 'graphqr/apply_scopes'
 require 'graphqr/authorized'
-require 'graphqr/base'
 require 'graphqr/pagination'
 require 'graphqr/permitted_fields_extension'
 require 'graphqr/query_field'

data/lib/graphqr/authorized.rb

@@ -2,8 +2,15 @@
 
 module GraphQR
   ##
-  # TODO: add documentation
+  # This module is the authorization extension created with our PolicyProvider.
+  #
+  # To use it add `extend GraphQR::Authorized` on the `GraphQL::Schema::Object` you want it,
+  # or add it on your `BaseObject`
   module Authorized
+    ##
+    # The `authorized? `method always runs before resolving an object.
+    #
+    # Our implementation adds a check on the `show?` method from the record Policy.
     def authorized?(object, context)
       policy_provider = context[:policy_provider]
 

data/lib/graphqr/configuration.rb

@@ -2,12 +2,30 @@
 
 module GraphQR # rubocop:disable Style/Documentation
   ##
-  # TODO: add documentation
+  # Module responsible for global configuration of the gem
   class Configuration
+    attr_writer :use_pagination, :use_authorization
+
     def configure
       yield self
     end
 
+    def use_pagination
+      if instance_variable_defined? :@use_pagination
+        @use_pagination
+      else
+        @use_pagination = true
+      end
+    end
+
+    def use_authorization
+      if instance_variable_defined? :@use_authorization
+        @use_authorization
+      else
+        @use_authorization = true
+      end
+    end
+
     ##
     # Returns the selected paginator.
     # If no paginator is selected, it tries to find the one used

data/lib/graphqr/fields/base_field.rb

@@ -18,8 +18,8 @@ module GraphQR
     class BaseField < GraphQL::Schema::Field
       def initialize(*args, paginate: false, **kwargs, &block)
         super(*args, **kwargs, &block)
-        extension(Pagination::PaginationExtension) if paginate
-        extension(PermittedFieldsExtension, null: kwargs[:null])
+        extension(Pagination::PaginationExtension) if paginate && GraphQR.use_pagination
+        extension(PermittedFieldsExtension, null: kwargs[:null]) if GraphQR.use_authorization
       end
     end
   end

data/lib/graphqr/pagination.rb

@@ -2,7 +2,12 @@
 
 module GraphQR
   ##
-  # TODO: add documentation
+  # This module adds the GraphQL pagination types.
+  #
+  # When a field is paginated, the field `page_info` is always included with some pagination information.
+  #
+  # To use this module use `extend GraphQR::Pagination` on the GraphQL::Schema::Object you want it,
+  # or in your `BaseObject`
   module Pagination
     def pagination_type
       @pagination_type ||= begin

data/lib/graphqr/pagination/pagination_extension.rb

@@ -3,9 +3,13 @@
 module GraphQR
   module Pagination
     ##
-    # TODO: add documentation
+    # The PaginationExtension is used on the `GraphQR::Fields::BaseField`.
+    #
+    # It adds the `per` and `page` arguments to the paginated field and uses the selected paginator resolver to add
+    # `nodes`, `edges` and `page_info` on the response
     class PaginationExtension < GraphQL::Schema::FieldExtension
-      DEFAULT_PAGINATION_ERROR = 'No paginator defined'
+      NO_PAGINATOR_ERROR = 'No paginator defined'
+      INVALID_PAGINATOR_ERROR = 'Invalid paginator'
 
       def apply
         field.argument :per, 'Int', required: false, default_value: 25,
@@ -23,9 +27,18 @@ module GraphQR
       end
 
       def after_resolve(value:, arguments:, **_kwargs)
-        raise GraphQL::ExecutionError, DEFAULT_PAGINATION_ERROR unless GraphQR.paginator.present?
+        raise GraphQL::ExecutionError, NO_PAGINATOR_ERROR unless GraphQR.paginator.present?
 
-        Resolvers::PagyResolver.new(value, items: arguments[:per], page: arguments[:page]) if GraphQR.use_pagy?
+        call_resolver(value, arguments)
+      end
+
+      def call_resolver(value, arguments)
+        case GraphQR.paginator
+        when :pagy
+          Resolvers::PagyResolver.new(value, items: arguments[:per], page: arguments[:page])
+        else
+          raise GraphQL::ExecutionError, INVALID_PAGINATOR_ERROR
+        end
       end
     end
   end

data/lib/graphqr/pagination/resolvers/pagy_resolver.rb

@@ -4,7 +4,7 @@ module GraphQR
   module Pagination
     module Resolvers
       ##
-      # TODO: add documentation
+      # This is a resolver that uses `Pagy::Backend` and maps it to the GraphQL pagination structure.
       class PagyResolver
         include Pagy::Backend
 

data/lib/graphqr/pagination/types/pagination_page_info_type.rb

@@ -4,7 +4,7 @@ module GraphQR
   module Pagination
     module Types
       ##
-      # TODO: add documentation
+      # This defines the information about pagination in a connection.
       class PaginationPageInfoType < GraphQL::Schema::Object
         description 'Information about pagination in a connection.'
 

data/lib/graphqr/permitted_fields_extension.rb

@@ -2,7 +2,10 @@
 
 module GraphQR
   ##
-  # TODO: add documentation
+  # This is an extension used on the `GraphQR::Fields::BaseField`.
+  #
+  # It is responsible for authorizing each field within a query.
+  # It searches if the field is defined on the `permitted_fields` method of the policy
   class PermittedFieldsExtension < GraphQL::Schema::FieldExtension
     def resolve(object:, arguments:, context:)
       if authorized?(object, context)

data/lib/graphqr/policies/authorize_graphql.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module GraphQR
+  module Policies
+    ##
+    # The AuthorizeGraphQL module defines a way of running the PolicyProvider authorization with a specific action
+    module AuthorizeGraphQL
+      DEFAULT_AUTHORIZATION_ERROR = 'You are not authorized to perform this action'
+
+      ##
+      # This method is a wrapper around the Pundit authorize, receiving the same arguments.
+      # The only difference is that it turns the Pundit::NotAuthorizedError into a GraphQL::ExecutionError
+      #
+      # ### Example:
+      #
+      # ```
+      # authorize_graphql User, :index?
+      # ```
+      def authorize_graphql(record, action, policy_class: nil)
+        args = { record: record, action: action, policy_class: policy_class }
+        raise GraphQL::ExecutionError, DEFAULT_AUTHORIZATION_ERROR unless policy_provider.allowed?(args)
+      end
+
+      def policy_provider
+        context[:policy_provider]
+      end
+    end
+  end
+end

data/lib/graphqr/policies/pundit_provider.rb

@@ -5,7 +5,17 @@ require 'pundit'
 module GraphQR
   module Policies
     ##
-    # TODO: add documentation
+    # This is a wrapper around Pundit provided to keep all PolicyProviders with the same methods.
+    #
+    # If you want to use the Pundit integration with our extensions you should pass:
+    #
+    # ```
+    # {
+    #   policy_provider: GraphQR::Policies::PunditProvider.new(policy_context: pundit_user)
+    # }
+    # ```
+    #
+    # To the Schema context.
     class PunditProvider
       attr_reader :policy_context
 

data/lib/graphqr/query_field.rb

@@ -1,11 +1,46 @@
 # frozen_string_literal: true
 
-# rubocop:disable Metrics/ParameterLists
-
 module GraphQR
   ##
-  # TODO: add documentation
+  # This extension adds the `query_field` method.
+  # A helper to create simple queries faster and easier
+  #
+  # To use this extension, add `extend Graphql::QueryField` on your `QueryType`
   module QueryField
+    # rubocop:disable Metrics/ParameterLists
+
+    ##
+    # The `query_field` method is a helper to create fields and resolver without effort.
+    #
+    # ### Arguments
+    #
+    # +field_name+ _(required)_: the GraphQL query name
+    #
+    # +active_record_class+ _(required)_: the model ActiveRecord class.
+    # It can be represented as an array if you want it to return a collection
+    #
+    # +type_class+ _(required)_:  The GraphQL type class
+    #
+    # +scope_class+: A specific InputType that contains the possible scopes that can be applied to your collection.
+    # Similar to the [has_scope](https://github.com/plataformatec/has_scope/) gem.
+    # _This argument is required for collection fields._
+    #
+    # ### Examples
+    # ```
+    # query_type :user, User, type_class: UserType
+    # query_type :users, [User], type_class: UserType, scope_class: UserScopeInput
+    # ```
+    #
+    # ### Collention fields
+    #
+    # Collection fields are always paginated using the configured `paginator`
+    # Its resolver will look for the `index?` method on the model Policy.
+    # It'll have the optional `filter` argument with `scope_class` type
+    #
+    # ### Single fields
+    #
+    # Single fields have the required `id` argument to find the exact record searched.
+    # Its resolver will look for the `show?` method on the model Policy.
     def query_field(field_name, active_record_class, type_class:, scope_class: nil, **kwargs, &block)
       is_collection = active_record_class.is_a? Array
       if is_collection
@@ -17,6 +52,7 @@ module GraphQR
 
       field(field_name, paginate: is_collection, resolver: resolver, **kwargs, &block)
     end
+    # rubocop:enable Metrics/ParameterLists
 
     private
 
@@ -58,4 +94,3 @@ module GraphQR
     end
   end
 end
-# rubocop:enable Metrics/ParameterLists

data/lib/graphqr/scope_items.rb

@@ -2,8 +2,15 @@
 
 module GraphQR
   ##
-  # TODO: add documentation
+  # This extension adds the PolicyProvider scope to the fields.
+  # When using the extension, ActiveRecord::Relation fields will be scoped.
+  #
+  # To use this extension add `extend GraphQR::ScopeItems` on the `GraphQL::Schema::Object` you want,
+  # or in your `BaseObject`
   module ScopeItems
+    ##
+    # The method checks whether the items are a ActiveRecord::Relation or not.
+    # If they are, it runs the PolicyProvider `authorized_records` scope.
     def scope_items(items, context)
       if scopable_items?(items)
         context[:policy_provider].authorized_records(records: items)

data/lib/graphqr/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module GraphQR
-  VERSION = '0.0.4'
+  VERSION = '0.0.5'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: graphqr
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - Manuel Puyol
@@ -144,7 +144,6 @@ files:
 - lib/graphqr.rb
 - lib/graphqr/apply_scopes.rb
 - lib/graphqr/authorized.rb
-- lib/graphqr/base.rb
 - lib/graphqr/configuration.rb
 - lib/graphqr/fields/base_field.rb
 - lib/graphqr/hooks.rb
@@ -153,6 +152,7 @@ files:
 - lib/graphqr/pagination/resolvers/pagy_resolver.rb
 - lib/graphqr/pagination/types/pagination_page_info_type.rb
 - lib/graphqr/permitted_fields_extension.rb
+- lib/graphqr/policies/authorize_graphql.rb
 - lib/graphqr/policies/pundit_provider.rb
 - lib/graphqr/query_field.rb
 - lib/graphqr/scope_items.rb

data/lib/graphqr/base.rb

@@ -1,32 +0,0 @@
-# frozen_string_literal: true
-
-module GraphQR
-  ##
-  # The Base module defines some helper methods that can be used once it is included
-  # it also includes the basic ApplyScopes library
-  module Base
-    include GraphQR::ApplyScopes
-
-    DEFAULT_AUTHORIZATION_ERROR = 'You are not authorized to perform this action'
-
-    ##
-    # This method is a wrapper around the Pundit authorize, receiving the same arguments.
-    # The only difference is that it turns the Pundit::NotAuthorizedError into a GraphQL::ExecutionError
-    #
-    # ### Example:
-    #
-    # ```
-    # authorize_graphql User, :index?
-    # ```
-    def authorize_graphql(record, action, policy_class: nil)
-      args = { record: record, action: action, policy_class: policy_class }
-      raise GraphQL::ExecutionError, DEFAULT_AUTHORIZATION_ERROR unless policy_provider.allowed?(args)
-    end
-
-    ##
-    # This is a helper method to get the policy provider from the context
-    def policy_provider
-      context[:policy_provider]
-    end
-  end
-end