graphql-groups 0.1.1

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Hans-Jörg Schnedlitz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,182 @@
+# GraphQL Groups
+
+[![Build Status](https://github.com/hschne/graphql-groups/workflows/Build/badge.svg)](https://github.com/hschne/graphql-groups/workflows/Build/badge.svg)
+[![Maintainability](https://api.codeclimate.com/v1/badges/692d4125ac8548fb145e/maintainability)](https://codeclimate.com/github/hschne/graphql-groups/maintainability) 
+[![Test Coverage](https://api.codeclimate.com/v1/badges/692d4125ac8548fb145e/test_coverage)](https://codeclimate.com/github/hschne/graphql-groups/test_coverage)
+
+Create flexible and performant aggregation queries with [graphql-ruby](https://github.com/rmosolgo/graphql-ruby)
+
+## Installation
+
+Add this line to your application's Gemfile and execute bundler.
+
+```ruby
+gem 'graphql-groups'
+```
+```bash
+$ bundle install
+```
+
+## Usage
+
+Create a new group type to specify which attributes you wish to group by inheriting from `GraphQL::Groups::GroupType`
+
+```ruby
+class AuthorGroupType < GraphQL::Groups::GroupType
+  scope { Author.all }
+
+  by :age
+end
+```
+
+Include the new type in your schema using the `group` keyword. 
+
+```ruby
+class QueryType < BaseType
+  include GraphQL::Groups
+
+  group :author_groups, AuthorGroupType
+end
+```
+
+You can then run an aggregation query for this grouping. 
+
+```graphql
+query myQuery{ 
+  authorGroups {
+    age {
+      key
+      count
+    }
+ }
+}
+```
+```json
+{
+  "authorGroups":{
+    "age":[
+      {
+        "key":"31",
+        "count":1
+      },
+      {
+        "key":"35",
+        "count":3
+      },
+      ...
+    ]
+  }
+}
+
+```
+
+## Advanced Usage
+
+#### Custom Grouping Queries
+
+To customize how items are grouped, you may specify the grouping query by creating a method of the same name in the group type. 
+
+```ruby
+class AuthorGroupType < GraphQL::Groups::Schema::GroupType
+  scope { Author.all }
+
+  by :age
+
+  def age(scope:)
+    scope.group("(cast(age/10 as int) * 10) || '-' || ((cast(age/10 as int) + 1) * 10)")
+  end
+end
+```
+
+You may also pass arguments to custom grouping queries. In this case, pass any arguments to your group query as keyword arguments.
+
+```ruby
+class BookGroupType < GraphQL::Groups::Schema::GroupType
+  scope { Book.all }
+
+  by :published_at do
+    argument :interval, String, required: false
+  end
+
+  def published_at(scope:, interval: nil)
+    case interval
+    when 'month'
+      scope.group("strftime('%Y-%m-01 00:00:00 UTC', published_at)")
+    when 'year'
+      scope.group("strftime('%Y-01-01 00:00:00 UTC', published_at)")
+    else
+      scope.group("strftime('%Y-%m-%d 00:00:00 UTC', published_at)")
+    end
+  end
+end
+```
+
+For more examples see the [feature spec](./spec/graphql/feature_spec.rb) and [test schema](./spec/graphql/support/test_schema)
+
+### Custom Aggregates
+
+Per default `graphql-groups` supports aggregating `count` out of the box. If you need to other aggregates, such as sum or average 
+you may add them to your schema by creating a custom `GroupResultType`. Wire this up to your schema by specifying the result type in your
+group type.
+
+```ruby
+class AuthorGroupResultType < GraphQL::Groups::Schema::GroupResultType
+  aggregate :average do
+    attribute :age
+  end
+end
+```
+
+```ruby
+class AuthorGroupType < GraphQL::Groups::Schema::GroupType
+  scope { Author.all }
+
+  result_type { AuthorGroupResultType }
+
+  by :name
+end
+```
+
+Per default, the aggregate name and attribute will be used to construct the underlying aggregation query. The example above creates
+```ruby
+scope.average(:age)
+```
+
+If you need more control over how to aggregate you may define a custom query by creating a method matching the aggregate name. The method *must* take the keyword arguments `scope` and `attribute`. 
+
+```ruby
+class AuthorGroupResultType < GraphQL::Groups::Schema::GroupResultType
+  aggregate :average do
+    attribute :age
+  end
+
+  def average(scope:, attribute:)
+    scope.average(attribute)
+  end
+end
+```
+
+For more examples see the [feature spec](./spec/graphql/feature_spec.rb) and [test schema](./spec/graphql/support/test_schema)
+
+## Limitations and Known Issues
+
+*This gem is in early development!*. There are a number of issues that are still being addressed. There is no guarantee
+that this libraries API will not change fundamentally from one release to the next.
+
+## 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](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/graphql-groups. 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](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Graphql::Groups project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/graphql-groups/blob/master/CODE_OF_CONDUCT.md).

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/groups"
+
+# 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-groups.gemspec

@@ -0,0 +1,44 @@
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'graphql/groups/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'graphql-groups'
+  spec.version = Graphql::Groups::VERSION
+  spec.authors = ['Hans-Jörg Schnedlitz']
+  spec.email = ['hans.schnedlitz@gmail.com']
+
+  spec.summary = 'Create flexible and performant aggregation queries with graphql-ruby'
+  spec.description = <<~HEREDOC
+    GraphQL Groups makes it easy to add aggregation queries to your GraphQL schema. It combines a simple, flexible 
+    schema definition with high performance'
+  HEREDOC
+  spec.homepage = 'https://github.com/hschne/graphql-groups'
+  spec.license = 'MIT'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/hschne/graphql-groups'
+  spec.metadata['changelog_uri'] = 'https://github.com/hschne/graphql-groups/blob/master/CHANGELOG.md'
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |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 'activerecord', '~> 5.0'
+  spec.add_development_dependency 'bundler', '~> 2.0'
+  spec.add_development_dependency 'database_cleaner-active_record'
+  spec.add_development_dependency 'gqli'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rspec', '~> 3.0'
+  spec.add_development_dependency 'rubocop', '~> 0.88'
+  spec.add_development_dependency 'rubocop-rspec', '~> 1.42'
+  spec.add_development_dependency 'simplecov'
+  spec.add_development_dependency 'sqlite3', '~> 1.4.2'
+
+  spec.add_dependency 'graphql', '~> 1', '> 1.9'
+end

data/lib/graphql/groups.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require 'graphql/groups/version'
+
+require 'graphql'
+require 'graphql/groups/extensions/wrap'
+
+require 'graphql/groups/schema/group_field'
+require 'graphql/groups/schema/aggregate_field'
+require 'graphql/groups/schema/aggregate_type'
+
+require 'graphql/groups/has_aggregates'
+require 'graphql/groups/has_groups'
+
+require 'graphql/groups/schema/group_result_type'
+require 'graphql/groups/schema/group_type'
+
+require 'graphql/groups/lookahead_parser'
+require 'graphql/groups/result_transformer'
+require 'graphql/groups/executor'
+
+
+module GraphQL
+  module Groups
+    def self.included(base)
+      base.extend ClassMethods
+    end
+
+    module ClassMethods
+      def group(name, type, **options)
+        # TODO: Suppress/warn if options are used that cannot be used
+        field name, type, extras: [:lookahead], null: false, **options
+
+        define_method name do |lookahead: nil|
+          execution_plan = GraphQL::Groups::LookaheadParser.parse(lookahead)
+          base_query = nil
+          type.instance_eval do
+            base_query = instance_eval(&@own_scope)
+          end
+          results = Executor.call(base_query, execution_plan)
+          GraphQL::Groups::ResultTransformer.new.run(results)
+        end
+      end
+    end
+  end
+end

data/lib/graphql/groups/executor.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Groups
+    class Executor
+      class << self
+        def call(base_query, execution_plan)
+          execution_plan.each_with_object({}) do |(key, value), object|
+            object.merge!(execute(base_query, key, value))
+          end
+        end
+
+        def execute(scope, key, value)
+          group_query = value[:proc].call(scope: scope)
+          results = value[:aggregates].each_with_object({}) do |(aggregate_key, aggregate), object|
+            if aggregate_key == :count
+              object[:count] = aggregate[:proc].call(scope: group_query)
+            else
+              object[aggregate_key] ||= {}
+              aggregate[:attributes].each do |attribute|
+                result = aggregate[:proc].call(scope: group_query, attribute: attribute)
+                object[aggregate_key][attribute] = result
+              end
+            end
+          end
+
+          return { key => results } unless value[:nested]
+
+          value[:nested].each do |inner_key, inner_value|
+            new_key = (Array.wrap(key) << inner_key)
+            inner_result = execute(group_query, inner_key, inner_value)
+            results[new_key] = inner_result[inner_key]
+          end
+          results
+        end
+      end
+    end
+  end
+end

data/lib/graphql/groups/extensions/wrap.rb

@@ -0,0 +1,11 @@
+class Array
+  def self.wrap(object)
+    if object.nil?
+      []
+    elsif object.respond_to?(:to_ary)
+      object.to_ary || [object]
+    else
+      [object]
+    end
+  end
+end

data/lib/graphql/groups/has_aggregates.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module GraphQL
+  module Groups
+    module HasAggregates
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        def aggregate(name, *_, **options, &block)
+          aggregate_type = aggregate_type(name)
+
+          # TODO: Handle method name conflicts, or no query method found error
+          resolve_method = "resolve_#{name}".to_sym
+          query_method = options[:query_method] || name
+          field = aggregate_field name, aggregate_type,
+                                  null: false,
+                                  query_method: query_method,
+                                  resolver_method: resolve_method,
+                                  **options, &block
+          aggregate_type.add_fields(field.own_attributes)
+
+          # TODO: Avoid overwriting existing method
+          define_method query_method do |**kwargs|
+            scope = kwargs[:scope]
+            attribute = kwargs[:attribute]
+            scope.public_send(name, attribute)
+          end
+
+          define_method resolve_method do
+            group_result[1][name]
+          end
+        end
+
+        def aggregate_field(*args, **kwargs, &block)
+          field_defn = Schema::AggregateField.from_options(*args, owner: self, **kwargs, &block)
+          add_field(field_defn)
+          field_defn
+        end
+
+        private
+
+        def aggregate_type(name)
+          # TODO: Handle no aggregate type found
+          name = "#{name}AggregateType".upcase_first
+          own_aggregate_types[name] ||= Class.new(Schema::AggregateType) do
+            graphql_name name
+          end
+        end
+
+        def own_aggregate_types
+          @own_aggregate_types ||= {}
+        end
+      end
+    end
+  end
+end

data/lib/graphql/groups/has_groups.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+module GraphQL
+  module Groups
+    module HasGroups
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # TODO: Error if there are no groupings defined
+        def by(name, **options, &block)
+          query_method = options[:query_method] || name
+          resolver_method = "resolve_#{query_method}".to_sym
+          group_field name, [own_result_type],
+                      null: false,
+                      resolver_method: resolver_method,
+                      query_method: query_method,
+                      **options, &block
+
+          define_method query_method do |**kwargs|
+            kwargs[:scope].group(name)
+          end
+
+          define_method resolver_method do |**_|
+            group[name]
+          end
+        end
+
+        def group_field(*args, **kwargs, &block)
+          field_defn = Schema::GroupField.from_options(*args, owner: self, **kwargs, &block)
+          add_field(field_defn)
+          field_defn
+        end
+
+        def result_type(&block)
+          @own_result_type = instance_eval(&block)
+        end
+
+        def scope(&block)
+          @own_scope = block
+        end
+
+        private
+
+        def own_result_type
+          name = "#{self.name.gsub(/Type$/, '')}ResultType"
+
+          type = name.safe_constantize || GraphQL::Groups::Schema::GroupResultType
+          own_group_type = self
+
+          @classes ||= {}
+          @classes[type] ||= Class.new(type) do
+            graphql_name name
+
+            field :group_by, own_group_type, null: false, camelize: true
+
+            def group_by
+              group_result[1][:nested]
+            end
+          end
+        end
+
+        def own_scope
+          @own_scope ||= nil
+        end
+      end
+    end
+  end
+end