graphql-sugar 0.1.1

data/README.md

@@ -0,0 +1,601 @@
+# GraphQL::Sugar
+
+A sweet, extended DSL written on top of the [graphql-ruby](https://github.com/rmosolgo/graphql-ruby) gem.
+
+**Looking for a quick overview of this gem in action?** Head over to the [Usage](#usage) section.
+
+This gem allows you to:
+
+* Easily write [object types](#object-types) and [input types](#input-types) that are backed by ActiveRecord models.
+  * Automatically convert field names to snake_case.
+  * Automatically add `id`, `createdAt` and `updatedAt` fields if these columns exist in your database schema.
+  * Automatically determine the type of the field, based on your database schema and model validation rules, keeping things DRY.
+* Easily write [resolvers](#resolvers) and [mutators](#mutators) to encapsulate query and mutation logic.
+  * Provide an object-oriented layer, allowing easy refactoring of common code across queries and mutations.
+  * Look like (and function very similar to) Rails controllers, so that writing them is a breeze.
+
+## Installation
+
+```ruby
+gem 'graphql'
+gem 'graphql-sugar'
+```
+
+And then execute:
+
+    $ bundle
+
+And finally, do some initial setup:
+
+    $ rails g graphql:sugar
+
+## Usage
+
+This section provides a quick overview of the how simple the DSL can be, as well as a general workflow to follow:
+
+### Writing Queries
+
+Create the ObjectType:
+
+```ruby
+Types::PostType = GraphQL::ObjectType.define do
+  model_class Post
+
+  attribute :title
+  attribute :content
+  attribute :isPublic
+
+  relationship :user
+  relationship :comments
+end
+```
+
+Create a [Resolver](#resolvers):
+
+```ruby
+class PostResolver < ApplicationResolver
+  parameter :id, !types.ID
+
+  def resolve
+    Post.find(params[:id])
+  end
+end
+```
+
+Expose the Resolver:
+
+```ruby
+Types::QueryType = GraphQL::ObjectType.define do
+  name 'Query'
+
+  resolver :post
+end
+```
+
+### Writing Mutations
+
+Create the InputObjectType:
+
+```ruby
+Inputs::PostInputType = GraphQL::InputObjectType.define do
+  name 'PostInput'
+
+  model_class Post
+
+  parameter :title
+  parameter :content
+end
+```
+
+Create a [Mutator](#mutators):
+
+```ruby
+class CreatePostMutator < ApplicationMutator
+  parameter :input, !Inputs::PostInputType
+
+  type !Types::PostType
+
+  def mutate
+    Post.create!(params[:input])
+  end
+end
+```
+
+Expose the Mutator:
+
+```ruby
+Types::MutationType = GraphQL::ObjectType.define do
+  name 'Mutation'
+
+  mutator :createPost
+end
+```
+
+## Usage
+
+### Object Types
+
+Start by generating an ObjectType as you normally would:
+
+    $ rails g graphql:object Post
+
+This would create the following under `app/graphql/types/post_type.rb`:
+
+```ruby
+Types::PostType = GraphQL::ObjectType.define do
+  name "Post"
+end
+```
+
+Replace the `name` line with a `model_class` declaration:
+
+```ruby
+Types::PostType = GraphQL::ObjectType.define do
+  model_class Post
+end
+```
+
+This automatically sets the name as `PostType`. If you wish to overwrite the name, you can pass a second argument:
+
+```ruby
+Types::PostType = GraphQL::ObjectType.define do
+  model_class Post, 'PostObject'
+end
+```
+
+The `model_class` declaration is **required** to use rest of the extended ObjectType DSL (like `attributes`, `attribute`, `relationships`, `relationship`, etc). If you forget to declare it however, a helpful exception is raised. :smile:
+
+#### Defining attributes
+
+*Normally*, this is how you would add a couple of fields to your ObjectType:
+
+```ruby
+Types::PostType = GraphQL::ObjectType.define do
+  model_class Post
+
+  field :id, !types.ID
+  field :title, !types.String
+  field :content, types.String
+  field :isPublic, !types.Boolean, property: :is_public
+  field :createdAt
+  field :updatedAt
+end
+```
+
+However, using GraphQL::Sugar, you can now shorten this to:
+
+```ruby
+Types::PostType = GraphQL::ObjectType.define do
+  model_class Post
+
+  attribute :title
+  attribute :content
+  attribute :isPublic
+end
+```
+
+Under the hood:
+
+* The `id`, `createdAt` and `updatedAt` fields are automatically added if your model has those attributes.
+* The type for the rest of the fields are automatically determined based on your `schema.rb` and model validations. (Read more about [automatic type resolution](#automatic-type-resolution).)
+* The fields automatically resolve to the snake_cased method names of the attribute name provided (eg. `isPublic` => `is_public`).
+
+You can shorten this further [active_model_serializers](https://github.com/rails-api/active_model_serializers)-style:
+
+```ruby
+Types::PostType = GraphQL::ObjectType.define do
+  model_class Post
+
+  attributes :title, :content, :isPublic
+end
+```
+
+Or even more simply:
+
+```ruby
+Types::PostType = GraphQL::ObjectType.define do
+  model_class Post
+
+  attributes
+end
+```
+
+... which automatically includes *all* the attributes of a model based on your schema. While NOT recommended for production, this provides easy scaffolding of model-backed object types during development.
+
+Internally `attribute` just defines a `field`, but automatically determines the type and resolves to the model's snake_cased attribute. For simplicity, it follows the *exact same syntax* as `field`, so you can override type or specify a `resolve:` function:
+
+```ruby
+Types::PostType = GraphQL::ObjectType.define do
+  model_class Post
+
+  attribute :thumbnail, types.String, resolve: ->(obj, args, ctx) { obj.picture_url(:thumb) }
+end
+```
+
+This is useful (and necessary) if you wish to expose `attr_accessor`s defined in your model. (Read more about [automatic type resolution](#automatic-type-resolution).)
+
+**Side Note:** You _can_ always mix in good ol' `field`s along with `attribute`s if you really need to access the old DSL:
+
+```ruby
+Types::PostType = GraphQL::ObjectType.define do
+  model_class Post
+
+  attribute :title
+  field :isArchived, types.Boolean, resolve: ->(obj, args, ctx) { obj.is_archived? }
+end
+```
+
+However, since the syntax is pretty much the same, it is preferable to use either `field` or `attribute` throughout the type definition for the sake of uniformity. You may have a non-model backed ObjectType for example, which can use `field`s.
+
+#### Defining relationships
+
+Assume the Post model has the following associations:
+
+```ruby
+class Post < ApplicationRecord
+  belongs_to :user
+  has_many :comments
+end
+```
+
+*Normally*, this is how you would define the relationship in your ObjectType:
+
+```ruby
+Types::PostType = GraphQL::ObjectType.define do
+  model_class Post
+
+  field :userId, !types.ID, property: :user_id
+  field :user, Types::UserType
+
+  field :comments, !types[Types::CommentType]
+end
+```
+
+However, using GraphQL::Sugar, you can now shorten this to:
+
+```ruby
+Types::PostType = GraphQL::ObjectType.define do
+  model_class Post
+
+  relationship :user
+  relationship :comments
+end
+```
+
+Under the hood:
+
+* If the relationship is **belongs_to**, it automatically defines a field for the corresponding foreign key. It also determines the type and marks the association as non-null using [automatic type resolution](#automatic-type-resolution).
+* If the relationship is **has_one** or **has_many**, it first looks for a corresponding [Resolver](#resolvers) (eg. in this case, `CommentsResolver`). If it doesn't find one, it defaults to calling method of the underlying association on the object (eg. `obj.comments`)
+
+You can shorten the above code to:
+
+```ruby
+Types::PostType = GraphQL::ObjectType.define do
+  model_class Post
+
+  relationships :user, :comments
+end
+```
+
+Or even more simply:
+
+```ruby
+Types::PostType = GraphQL::ObjectType.define do
+  model_class Post
+
+  relationships
+end
+```
+
+... which automatically reflects on *all* your model associations and includes them. While NOT recommended for production, this provides easy scaffolding of model-backed object types during development.
+
+**Side Note:** Unlike `attribute`, `relationship` is not just syntactic sugar for `field` and it does much more. It is recommended that you revert to using `field`s (rather than `attribute`) if you need to achieve a specific behavior involving associations. For example:
+
+```ruby
+Types::PostType = GraphQL::ObjectType.define do
+  model_class Post
+
+  relationship :user
+
+  field :recentComments, !types[Types::CommentType], resolve: ->(obj, args, ctx) {
+    obj.comments.not_flagged.recent.limit(3)
+  }
+  end
+end
+```
+
+#### Automatic Type Resolution
+
+Your model attribute's type is automatically determined using Rails' reflection methods, as follows:
+
+* First, we look at the column type:
+  * `:integer` gets mapped to `types.Int` (`GraphQL::INT_TYPE`),
+  * `:float` and `:decimal` get mapped to `types.Float` (`GraphQL::FLOAT_TYPE`),
+  * `:boolean` gets mapped to `types.Boolean` (`GraphQL::BOOLEAN_TYPE`),
+  * and the rest get mapped to `types.String` (`GraphQL::STRING_TYPE`).
+* Then, we determine the non-nullability based on whether:
+  * You have specified `null: false` for the column in your schema, or
+  * You have specified `presence: true` validation for the attribute in your model.
+
+In instances where a type cannot be automatically determined, you must provide the type yourself. For example, `attr_accessor`s are not persisted and don't have a corresponding column in your database schema.
+
+### Input Types
+
+*Normally*, this is how you would define your InputObjectType:
+
+```ruby
+Inputs::PostInputType = GraphQL::InputObjectType.define do
+  name 'PostInput'
+
+  argument :title, types.String
+  argument :content, types.String
+  argument :isPublic, types.Boolean, as: :is_public
+end
+```
+
+However, using GraphQL::Sugar, you can now shorten this to:
+
+```ruby
+Inputs::PostInputType = GraphQL::InputObjectType.define do
+  name 'PostInput'
+
+  model_class 'Post'
+
+  parameter :title
+  parameter :content
+  parameter :isPublic
+end
+```
+
+Under the hood,
+* `parameter` uses the same [automatic type resolution](#automatic-type-resolution) as `attribute`, but creates arguments that are not-null by default. The default behavior passes all values to be validated in the model instead, in order to return proper error messages in the response. (**TODO:** Allow this behavior to be configured via an initializer.)
+* It allows sets the `:as` value to the snake_cased form of the provided name. (eg. `:isPublic` => `:is_public`). This allows us to easily pass them into ActiveRecord's `create` and `update_attributes` methods.
+
+You can override the type to make a field non-null as follows:
+
+```ruby
+Inputs::PostInputType = GraphQL::InputObjectType.define do
+  name 'PostInput'
+
+  model_class 'Post'
+
+  parameter :title, !types.String
+  parameter :content
+end
+```
+
+### Resolvers
+
+In its simplest form, a Resolver simply inherits from `ApplicationResolver` and contains a `#resolve` method.
+
+```ruby
+class PostsResolver < ApplicationResolver
+  def resolve
+    Post.all
+  end
+end
+```
+
+To expose the resolver as a field, declare it in your root QueryType:
+
+```ruby
+Types::QueryType = GraphQL::ObjectType.define do
+  name 'Query'
+
+  resolver :posts
+end
+```
+
+To declare arguments, you can use the `parameter` keyword which follows the same syntax:
+
+```ruby
+class PostResolver < ApplicationResolver
+  parameter :id, !types.ID
+
+  def resolve
+    Post.find(params[:id])
+  end
+end
+```
+
+The benefit is that all `parameter`s (read: arguments) are loaded into a `params` object, with all keys transformed into snake_case. This allows them to be easily used with ActiveRecord methods like `where` and `find_by`.
+
+You also have `object` and `context` available in your resolve method:
+
+```ruby
+class PostsResolver < ApplicationResolver
+  def resolve
+    (object || context[:current_user]).posts
+  end
+end
+```
+
+#### Thinking in Graphs *using Resolvers*
+
+Assume the following GraphQL query ("fetch 10 posts, along with the authors and 2 of their highest rated posts."):
+
+```
+query {
+  posts(limit: 10) {
+    title
+    content
+
+    user {
+      name
+
+      posts(limit: 2, sort: "rating_desc") {
+        title
+        rating
+      }
+    }
+  }
+}
+```
+
+When executed, we resolve both the first and second `posts` using `PostsResolver`. This means:
+
+1. All the `argument`s (or `parameter`s) available to your top level `posts` are available to all your nested `posts`s through relationships without any extra work.
+
+2. The `object` value passed to your `PostsResolver#resolve` function is *very* important. This would be a good place to perform an authorization check to see if the current user has access to this relationship on the `object`.
+
+**A quick detour:** At the top of your graph, you have your **root_value** ([read more](http://graphql-ruby.org/queries/executing_queries.html#root-value)), which the [graphql-ruby](https://github.com/rmosolgo/graphql-ruby) library allows you to set for your schema. By default, this is `null`. You can either *explicitly* set this root_value, or *implicitly* consider to be the current user (or current organization, or whatever your application deems it to be).
+
+For example,
+
+```ruby
+class PostsResolver < ApplicationResolver
+  def resolve
+    parent_object = (object || context[:current_user])
+    authorize! :view_posts, parent_object
+
+    parent_object.posts
+  end
+end
+```
+
+### Mutators
+
+In its simplest form, a Mutator simply inherits from `ApplicationMutator` and contains a `#mutate` method:
+
+```ruby
+class CreatePostMutator < ApplicationMutator
+  parameter :input, !Inputs::PostInputType
+
+  type !Types::PostType
+
+  def mutate
+    Post.create!(params[:input])
+  end
+end
+```
+
+To expose the mutator as a field, declare it in your root MutationType:
+
+```ruby
+Types::MutationType = GraphQL::ObjectType.define do
+  name 'Mutation'
+
+  mutator :createPost
+end
+```
+
+Just like resolvers, you have access to `object`, `params` and `context`:
+
+```ruby
+class UpdatePostMutator < ApplicationMutator
+  parameter :id, !types.ID
+  parameter :input, !Inputs::PostInputType
+
+  type !Types::PostType
+
+  def mutate
+    post = context[:current_user].posts.find(params[:id])
+    post.update_attributes!(params[:input])
+    post
+  end
+end
+```
+
+### Organizing Your Code
+
+When you install the gem using `rails g graphql:sugar`, it creates the following files:
+
+```
+app/graphql/functions/application_function.rb
+app/graphql/resolvers/application_resolver.rb
+app/graphql/mutators/application_mutator.rb
+```
+
+All your resolvers inherit from `ApplicationResolver` and all your mutators inherit from `ApplicationMutator`, both of which in turn inherit from `ApplicationFunction`. You can use these classes to write shared code common to multiple queries, mutations, or both.
+
+#### Applying OO principles
+
+*Pagination and Sorting:* You can easily create methods that enable common features.
+
+```ruby
+class ApplicationResolver < ApplicationFunction
+  include GraphQL::Sugar::Resolver
+
+  def self.sortable
+    parameter :sort, types.String
+    parameter :sortDir, types.String
+  end
+end
+```
+
+Use in your other resolvers:
+
+```ruby
+class PostsResolver < ApplicationResolver
+  sortable
+
+  def resolve
+    # ...
+  end
+end
+```
+
+*Shared Code:* You can also easily share common code across a specific set of mutators. For example, your `CreatePostMutator` and `UpdatePostMutator` could inherit from `PostMutator`, which inherits from `ApplicationMutator`.
+
+#### Tips for Large Applications
+
+In a large app, you can quite easily end up with tons of mutations. During setup, GraphQL::Sugar adds a few lines to your eager_load_paths so you can group them in folders, while maintaining mutations at the root level. For example,
+
+```
+# Folder Structure
+app/graphql/mutators/
+- posts
+  - create_post_mutator.rb
+  - update_post_mutator.rb
+- users
+  - create_user_mutator.rb
+  - update_user_mutator.rb
+- application_mutator.rb
+```
+
+```ruby
+Types::MutationType = GraphQL::ObjectType.define do
+  name 'Mutation'
+
+  mutator :createPost
+  mutator :updatePost
+
+  mutator :createUser
+  mutator :updateUser
+end
+```
+
+### Generators
+
+A few basic generators have been written to quickly create some of the boilerplate code. They may not work perfectly, and the generated code may require further editing.
+
+    $ rails g graphql:resolver BlogPosts
+
+Creates a `BlogPostsResolver` class at `app/graphql/resolvers/blog_posts_resolver.rb`.
+
+    $ rails g graphql:mutator CreateBlogPost
+
+Creates a `CreateBlogPostMutator` class under `app/graphql/mutators/create_blog_post_mutator.rb`.
+
+## Credits
+
+Many thanks to the work done by the authors of the following gems, which this gem uses as a foundation and/or inspiration:
+
+- [graphql-ruby](https://github.com/rmosolgo/graphql-ruby)
+- [graphql-activerecord](https://github.com/goco-inc/graphql-activerecord)
+- [graphql-rails-resolver](https://github.com/colepatrickturner/graphql-rails-resolver)
+- [active_model_serializers](https://github.com/rails-api/active_model_serializers)
+
+---
+
+Maintained and sponsored by [KeepWorks](http://www.keepworks.com).
+
+![KeepWorks](http://www.keepworks.com/assets/logo-800bbf55fabb3427537cf669dc8cd018.png "KeepWorks")
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/keepworks/graphql-sugar. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "graphql/sugar"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/graphql-sugar.gemspec

@@ -0,0 +1,26 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'graphql/sugar/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "graphql-sugar"
+  spec.version       = GraphQL::Sugar::VERSION
+  spec.authors       = ["Pradeep Kumar"]
+  spec.email         = ["pradeep@keepworks.com"]
+
+  spec.summary       = "A sweet, extended DSL written on top of the graphql-ruby gem."
+  spec.homepage      = "https://github.com/keepworks/graphql-sugar"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.14"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+end

data/lib/generators/graphql/mutator/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Creates a GraphQL::Sugar Mutator.
+
+Example:
+    rails generate graphql:mutator Thing
+
+    This will create:
+      app/graphql/mutators/thing_mutator.rb

data/lib/generators/graphql/mutator/mutator_generator.rb

@@ -0,0 +1,9 @@
+module Graphql
+  class MutatorGenerator < Rails::Generators::NamedBase
+    source_root File.expand_path('../templates', __FILE__)
+
+    def create_mutator
+      template 'mutator.erb', File.join('app/graphql/mutators', class_path, "#{file_name}_mutator.rb")
+    end
+  end
+end

data/lib/generators/graphql/mutator/templates/mutator.erb

@@ -0,0 +1,15 @@
+class <%= class_name %>Mutator < ApplicationMutator
+  <%= class_name %>InputType = GraphQL::InputObjectType.define do
+    name '<%= class_name %>Input'
+
+    parameter :id, !types.ID
+  end
+
+  parameter :input, !<%= class_name %>InputType
+
+  <%- type_name = file_name.split('_').drop(1).join('_').camelize -%>
+  type !Types::<%= type_name %>Type
+
+  def mutate
+  end
+end

data/lib/generators/graphql/resolver/USAGE

@@ -0,0 +1,8 @@
+Description:
+    Creates a GraphQL::Sugar Resolver.
+
+Example:
+    rails generate graphql:resolver Thing
+
+    This will create:
+        app/graphql/resolvers/thing_resolver.rb