GraphQR
¶ ↑
A compilation of useful extensions and helpers for graphql-ruby.
Installation¶ ↑
Add this line to your application's Gemfile:
gem 'graphqr'
And then execute:
$ bundle
Or install it yourself as:
$ gem install graphqr
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 ruby field_class GraphQR::Fields::BaseField
to your BaseObject
class. This will add the custom options to your fields and add the necessary extensions according to the modules you activated.
module Types class BaseObject < GraphQL::Schema::Object ... field_class GraphQR::Fields::BaseField ... end end
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 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.
module Types class BaseObject < GraphQL::Schema::Object ... extend GraphQR::Pagination ... end end
Usage¶ ↑
module Types class QueryType < Types::BaseObject graphql_name 'Query' field :users, UserType.pagination_type, paginate: true end end
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:
class GraphqlController < ApplicationController def execute context = { your_context, policy_provider: policy_provider } result = YourSchema.execute(query, variables: variables, context: context, operation_name: operation_name) render json: result.to_json rescue StandardError => e raise e unless Rails.env.development? handle_error_in_development(e) end ... end
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 ruby extend GraphQR::Authorized
to any GraphQL::Schema::Object
you'd like, but we recommend adding it to your BaseObject
class.
module Types class BaseObject < GraphQL::Schema::Object ... extend GraphQR::Authorized ... end end
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 ruby extend GraphQR::ScopeItems
to any GraphQL::Schema::Object
you'd like, but we recommend adding it to your BaseObject
class.
module Types class BaseObject < GraphQL::Schema::Object ... extend GraphQR::ScopeItems ... end end
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 ruby include GraphQR::Policies::AuthorizeGraphQL
where you want to use this methos, but we recommend adding it to your Mutations
and Resolvers
classes.
class BaseResolver < GraphQL::Schema::Resolver ... include GraphQR::Policies::AuthorizeGraphQL ... end
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 gem. It provides an apply_scopes
method that can search for model scopes and use them on a collection
To add this method, add ruby include GraphQR::ApplyScopes
where you'd like to use it, but we recommend adding it to your Resolvers
.
class BaseResolver < GraphQL::Schema::Resolver ... include GraphQR::ApplyScopes ... end
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 ruby extend GraphQR::QueryField
to your BaseObject
.
module Types class BaseObject < GraphQL::Schema::Object ... extend GraphQR::QueryField ... end end
Read more about its use in the documentation
Development¶ ↑
After checking out the repo, run bin/setup
to install dependencies. Then, run rake spec
to run the tests. You can also run bin/console
for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install
. To release a new version, update the version number in version.rb
, and then run bundle exec rake release
, which will create a git tag for the version, push git commits and tags, and push the .gem
file to rubygems.org.
Contributing¶ ↑
Bug reports and pull requests are welcome on GitHub at github.com/QultureRocks/graphqr. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
License¶ ↑
The gem is available as open source under the terms of the MIT License.
Code of Conduct¶ ↑
Everyone interacting in the GraphQR
project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.