graphql-filters 1.0.0

data/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+[//]: # (
+## <Release number> <Date YYYY-MM-DD>
+### Breaking changes
+### Deprecations
+### New features
+### Bug fixes
+)
+
+## 1.0.0 2023-03-06
+
+First release. Refer to [README.md](README.md) for the full documentation.

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in graphql-filters.gemspec
+gemspec
+
+gem 'rake', '~> 13.0'
+
+gem 'rspec', '~> 3.0'
+
+gem 'rubocop', '~> 1.21'

data/Gemfile.lock

@@ -0,0 +1,77 @@
+PATH
+  remote: .
+  specs:
+    graphql-filters (1.0.0)
+      activerecord (~> 7.0.0)
+      activesupport (~> 7.0.0)
+      graphql (~> 2.0.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (7.0.4.2)
+      activesupport (= 7.0.4.2)
+    activerecord (7.0.4.2)
+      activemodel (= 7.0.4.2)
+      activesupport (= 7.0.4.2)
+    activesupport (7.0.4.2)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 1.6, < 2)
+      minitest (>= 5.1)
+      tzinfo (~> 2.0)
+    ast (2.4.2)
+    concurrent-ruby (1.2.2)
+    diff-lcs (1.5.0)
+    graphql (2.0.17)
+    i18n (1.12.0)
+      concurrent-ruby (~> 1.0)
+    json (2.6.3)
+    minitest (5.18.0)
+    parallel (1.22.1)
+    parser (3.2.0.0)
+      ast (~> 2.4.1)
+    rainbow (3.1.1)
+    rake (13.0.6)
+    regexp_parser (2.6.2)
+    rexml (3.2.5)
+    rspec (3.12.0)
+      rspec-core (~> 3.12.0)
+      rspec-expectations (~> 3.12.0)
+      rspec-mocks (~> 3.12.0)
+    rspec-core (3.12.0)
+      rspec-support (~> 3.12.0)
+    rspec-expectations (3.12.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-mocks (3.12.3)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.12.0)
+    rspec-support (3.12.0)
+    rubocop (1.44.1)
+      json (~> 2.3)
+      parallel (~> 1.10)
+      parser (>= 3.2.0.0)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 1.8, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.24.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.24.1)
+      parser (>= 3.1.1.0)
+    ruby-progressbar (1.11.0)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    unicode-display_width (2.4.2)
+
+PLATFORMS
+  arm64-darwin-22
+
+DEPENDENCIES
+  graphql-filters!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+  rubocop (~> 1.21)
+
+BUNDLED WITH
+   2.3.9

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Moku S.r.l., Riccardo Agatea
+
+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,265 @@
+# GraphQL Filters
+
+A way to define automated filters on GraphQL fields.
+
+This gem provides a module to include (or prepend, see below) in your resolvers that will automatically generate a tree of input types that your clients can use to filter the result of their queries. The filters are completely typed in the GraphQL schema, and are transpiled into an Active Record relation. The relation uses subqueries instead of joins to apply filters on associations, which might be less efficient. This, however, makes it possible for the client to make a query like "I need all the Kanto routes where I can catch Oddish, but for each route I also need all the other Pokémon".
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'graphql-filters', '~> 0.1.0'
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+## Usage
+
+The easiest way to use GraphQL Filters is on top of [SearchObject](https://github.com/RStankov/SearchObject) and its [GraphQL plugin](https://github.com/RStankov/SearchObjectGraphQL). Just include `GraphQL::Filters::Filterable` in your resolvers, and it will add an option to automatically filter the underlying collection. For example:
+
+```ruby
+class RoutesResolver < BaseResolver
+  include SearchObject.module(:graphql)
+  
+  scope { Route.all }
+
+  type [RouteType], null: false
+
+  include GraphQL::Filters::Filterable
+end
+```
+
+Otherwise, you have to explicitly define a `resolve` method and have it return an `ActiveRecord::Relation`; in this case youy need to prepend `GraphQL::Filters::Filterable` in the resolver, otherwise it won't have access to the starting scope:
+
+```ruby
+class RoutesResolver < BaseResolver
+  type [RouteType], null: false
+  
+  def resolve
+    Route.all
+  end
+
+  prepend GraphQL::Filters::Filterable
+end
+```
+
+Using either of these resolvers for a `routes` field will generate all the necessary input types to make a query like this:
+
+```graphql
+query {
+  routes(
+    filter: {
+      fields: {
+        region: {
+          fields: {
+            name: { equals: "Kanto" }
+          }
+        },
+        catchablePokemon: {
+          any: {
+            fields: {
+              pokemon: {
+                types: {
+                  any: {
+                    fields: {
+                      name: { equals: "Water"}
+                    }
+                  }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  ){
+    name
+    trainers{
+      name
+      isDouble
+    }
+    catchablePokemon{
+      levelRange
+      rate
+      pokemon{
+        name
+        types{
+          name
+        }
+      }
+    }
+}
+```
+
+Notice that eager loading is outside the scope of this gem, so if without anything else the above query will fall victim to the N+1 problem.
+
+Each input type is generated based on the respective type: scalar and enum types allow for basic comparisons like equality and inclusion, while object types let you build complex queries that mix and match comparisons on their fields. List types let you make `any`, `all`, and `none` queries based on a nested filter. Support for null-checked filters is planned for future development.
+
+### Underlying models
+
+GraphQL Filters relies on the assumption that every object type exists on top of an Active Record model. A field of type `PokemonType` will always be resolved to an instance of `Pokemon`, and its fields will match (at least loosely) the attributes of the model. This assumption allows the gem to generate appropriate subqueries for nested filters.
+
+By default, the gem assumes that if an object type is `<Name>Type`, then its underlying model is `<Name>` and it is in the same module. This isn't always the case, especially if you follow the convention suggested by the GraphQL Ruby documentation, so all your object types are in a `Types` module. For a single exception you can explicitly declare the model inside your object type:
+
+```ruby
+module Types
+  class PokemonType < BaseObject
+    model_class Pokemon
+    ...
+  end
+end
+```
+
+To change the default behavior of the gem, override the `default_model_class` class method in your base object class:
+
+```ruby
+module Types
+  class BaseObject < GraphQL::Schema::Object
+    def self.default_model_class
+      model_name = name
+                     .delete_prefix('Types::')
+                     .delete_suffix('Type')
+
+      const_get model_name
+    end
+  end
+end
+```
+
+### Comparators
+
+The best way to know what comparators you can use with each field is to open the GraphQL schema in your favorite client. What follows is a description of what each comparator does; unless explicitly indicated, `not<Comparison>` will match if and only if `<comparison>` will not.
+
+#### Constant
+
+`constant` is available for all types, and either always or never matches, depending on the passed boolean value. It can be useful to build complex filters.
+
+#### Equality
+
+`equals` is available for all scalar and enum types, and their respective list types, and matches if the field has the provided value.
+
+#### Inclusion
+
+`in` is available for all scalar and enum types, and their respective list types, and matches if the field has one of the provided values.
+
+#### Numerical comparisons
+
+`greaterThan`, `greaterThanOrEqualsTo`, `lessThan` and `lessThanOrEqualsTo` are available for numerical types (including `ISO8601Date` and `ISO8601DateTime`) and behave as expected.
+
+#### Pattern matching
+
+`matches` is available for the `String` type. Its value is a string in the format `<version>/<pattern>/<options>`.
+
+- At the moment, `<version>` can only be `v1`, but extensions are planned for future development.
+- For version `v1`, `<pattern>` will match a `.` with any one character and a `*` with zero or more characters. To match any literal character you can prefix it with `\​`.
+- For version `v1`, `<options>` can be empty, or be `i`, which will make the match case insensitive.
+
+#### List comparisons
+
+`any`, `all`, and `none` are available for any list, take a comparator for the type of the elements of the list, and match, respectively, if at least one, all, or none, of the elements of the list match the nested comparator.
+
+#### Object comparisons
+
+For each object type `<Type>`, two comparison input types are generated. `<Type>ComplexFilterInput` has `and`, `or`, and `not` fields to build complex comparators, plus a `fields` field of type `<Type>ComparisonInput`. For each field of `<Type>`, `<Type>ComparisonInput` has a field with the same name and the respective comparison input type. For example , if `Pokemon` has a `name` field of type `String`, then `PokemonComparisonInput` has a `name` field of type `StringComparisonInput`.
+
+### Input Types
+
+The autogenerated input types are ready to go as is, but you might need to access them, for example to provide some documentation (the autogeneration of extensive documentation is planned for future development). For each type, you can access its corresponding input type through the `comparison_input_type` method. For object types, this method returns the class corresponding to the `<Type>ComplexFilterInput` input type; in turn, it has a `fields_comparison_input_type` that returns the class corresponding to the `<Type>ComparisonInput`  input type.
+
+### Configuration
+
+To configure the behavior of GraphQL Filters, create an initializer in `config/initializers`, and call the `configure` method:
+
+```ruby
+GraphQL::Filters.configure do |config|
+  ...
+end
+```
+
+#### `config.base_input_object_class`
+
+By default, GraphQL Filters uses `GraphQL::Schema::InputObject` as base class for comparison input types. To use another class, assign it to `config.base_input_object_class`.
+
+### Options
+
+The `field` method accepts some options that can tweak the generated input types and the transpilation of the arguments into a query. You can pass these options in three ways, in order of priority:
+
+- as a keyword argument to the `field` method:
+
+```ruby
+field :name, String, null: false, filter: {...}
+```
+
+- as a single positional argument to the `filter` method inside the block you pass to the `field` method:
+
+```ruby
+field :name, String, null: false do
+  filter({...})
+end
+```
+
+- as keyword arguments to the `filter` method inside the block you pass to the `field` method:
+
+```ruby
+field :name, String, null: false do
+  filter ...
+end
+```
+
+#### Valid options
+
+- `enabled`
+
+  Can be `true` or `false` (default: `true`). Controls whether or not the client can use this field in the filters. Passing `true` or `false` directly to `filter` is a shortcut:
+
+```ruby
+field :name, String, null: false, filter: false 
+
+# is equivalent to
+
+field :name, String, null: false, filter: {enabled: false}
+```
+
+- `attribute_name`
+
+  The name of the attribute that the field is tied to in the model. Defaults to the name of the resolver method for the field (which by default is the same as the name of the field itself).
+
+- `association_name`
+  
+  The name of the Active Record association that the field is tied to in the model. Equivalent to `attribute_name`, has the same default.
+
+## Plans for future development
+
+- A finer grain support for non-nullable fields.
+- A pattern format for the string match comparator that uses real regular expressions.
+- Autogenerated documentation.
+- More options, both for the gem as a whole and for the single fields.
+- The ability to (easily) specify custom comparator input types and provide custom logic for specific comparators.
+
+## Version numbers
+
+GraphQL Filters loosely follows [Semantic Versioning](https://semver.org/), with a hard guarantee that breaking changes to the public API will always coincide with an increase to the `MAJOR` number.
+
+Version numbers are in three parts: `MAJOR.MINOR.PATCH`.
+
+- Breaking changes to the public API increment the `MAJOR`. There may also be changes that would otherwise increase the `MINOR` or the `PATCH`.
+- Additions, deprecations, and "big" non breaking changes to the public API increment the `MINOR`. There may also be changes that would otherwise increase the `PATCH`.
+- Bug fixes and "small" non breaking changes to the public API increment the `PATCH`.
+
+Notice that any feature deprecated by a minor release can be expected to be removed by the next major release.
+
+## Changelog
+
+Full list of changes in [CHANGELOG.md](CHANGELOG.md)
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/moku-io/graphql-filters.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,10 @@
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new :spec
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: [:spec, :rubocop]

data/lib/graphql/filters/activerecord_patch/arel/nodes/contained.rb

@@ -0,0 +1,9 @@
+module Arel
+  module Nodes
+    class Contained < InfixOperation
+      def initialize left, right
+        super :'<@', left, right
+      end
+    end
+  end
+end

data/lib/graphql/filters/activerecord_patch/arel/predications.rb

@@ -0,0 +1,9 @@
+require_relative 'nodes/contained'
+
+monkey_patch = Module.new do
+  def contained other
+    Nodes::Contained.new self, Nodes.build_quoted(other, self)
+  end
+end
+
+Arel::Predications.prepend monkey_patch

data/lib/graphql/filters/activerecord_patch.rb

@@ -0,0 +1,3 @@
+Dir['activerecord_patch/**/*.rb', base: __dir__].each do |filename|
+  require_relative filename
+end

data/lib/graphql/filters/dsl/graphql/schema/enum.rb

@@ -0,0 +1,16 @@
+require 'active_support/concern'
+require_relative '../../../input_types/base_scalar_comparison_input_type'
+
+monkey_patch = Module.new do
+  extend ActiveSupport::Concern
+
+  class_methods do
+  protected
+
+    def get_comparison_input_type(*)
+      GraphQL::Filters::InputTypes::BaseScalarComparisonInputType[self]
+    end
+  end
+end
+
+GraphQL::Schema::Enum.prepend monkey_patch

data/lib/graphql/filters/dsl/graphql/schema/field.rb

@@ -0,0 +1,64 @@
+require 'active_support/concern'
+require 'active_support/core_ext/class/attribute'
+require 'ostruct'
+
+monkey_patch = Module.new do
+  extend ActiveSupport::Concern
+
+  prepended do
+    class_attribute :filter_options_defaults,
+                    instance_predicate: false,
+                    instance_writer: false,
+                    instance_reader: true,
+                    default: {
+                      enabled:          true,
+                      attribute_name:   :method_sym.to_proc,
+                      association_name: :method_sym.to_proc
+                    }
+  end
+
+  def initialize *args, filter: true, **kwargs, &block
+    super(*args, **kwargs) do
+      filter filter
+
+      next if block.nil?
+
+      if block.arity == 1
+        block.call self
+      else
+        instance_exec &block
+      end
+    end
+  end
+
+  def filter options={}, **kwargs
+    # options can be either true, false, or an hash, so `if options` or `if options.present?` aren't enough
+
+    options = case options
+              when false
+                {enabled: false}
+              when true
+                {enabled: true}
+              else
+                options
+              end
+
+    applied_filter_options_defaults = filter_options_defaults.transform_values do |value|
+      if value.is_a? Proc
+        value.call self
+      else
+        value
+      end
+    end
+
+    filter_options.reverse_merge! applied_filter_options_defaults
+    filter_options.reverse_merge! options
+    filter_options.reverse_merge! kwargs
+  end
+
+  def filter_options
+    @filter_options ||= {}
+  end
+end
+
+GraphQL::Schema::Field.prepend monkey_patch

data/lib/graphql/filters/dsl/graphql/schema/list.rb

@@ -0,0 +1,28 @@
+require 'active_support/concern'
+require_relative '../../../input_types/base_list_comparison_input_type'
+require_relative '../../../input_types/list_scalar_comparison_input_type'
+require_relative '../../../input_types/list_object_comparison_input_type'
+
+monkey_patch = Module.new do
+  extend ActiveSupport::Concern
+
+  def comparison_input_type new_comparison_input_type=nil
+    if new_comparison_input_type.present?
+      @comparison_input_type = new_comparison_input_type
+    else
+      @comparison_input_type ||= build_comparison_input_type
+    end
+  end
+
+protected
+
+  def build_comparison_input_type
+    if [GraphQL::TypeKinds::SCALAR, GraphQL::TypeKinds::ENUM].include? unwrap.kind
+      GraphQL::Filters::InputTypes::ListScalarComparisonInputType[self]
+    else
+      GraphQL::Filters::InputTypes::ListObjectComparisonInputType[self]
+    end
+  end
+end
+
+GraphQL::Schema::List.prepend monkey_patch

data/lib/graphql/filters/dsl/graphql/schema/member.rb

@@ -0,0 +1,25 @@
+require 'active_support/concern'
+require 'active_support/core_ext/class/attribute'
+require_relative '../../../input_types/base_comparison_input_type'
+
+monkey_patch = Module.new do
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def comparison_input_type new_comparison_input_type=nil
+      if new_comparison_input_type.present?
+        @comparison_input_type = new_comparison_input_type
+      else
+        @comparison_input_type ||= get_comparison_input_type
+      end
+    end
+
+  protected
+
+    def get_comparison_input_type
+      GraphQL::Filters::InputTypes::BaseComparisonInputType
+    end
+  end
+end
+
+GraphQL::Schema::Member.prepend monkey_patch

data/lib/graphql/filters/dsl/graphql/schema/non_null.rb

@@ -0,0 +1,15 @@
+require 'active_support/concern'
+
+monkey_patch = Module.new do
+  extend ActiveSupport::Concern
+
+  def comparison_input_type new_comparison_input_type=nil
+    if new_comparison_input_type.present?
+      @comparison_input_type = new_comparison_input_type
+    else
+      @comparison_input_type ||= of_type.comparison_input_type
+    end
+  end
+end
+
+GraphQL::Schema::NonNull.prepend monkey_patch

data/lib/graphql/filters/dsl/graphql/schema/object.rb

@@ -0,0 +1,16 @@
+require 'active_support/concern'
+require_relative '../../../input_types/object_comparison_input_type'
+
+monkey_patch = Module.new do
+  extend ActiveSupport::Concern
+
+  class_methods do
+  protected
+
+    def get_comparison_input_type(*)
+      GraphQL::Filters::InputTypes::ObjectComparisonInputType[self]
+    end
+  end
+end
+
+GraphQL::Schema::Object.prepend monkey_patch

data/lib/graphql/filters/dsl/graphql/schema/scalar.rb

@@ -0,0 +1,16 @@
+require 'active_support/concern'
+require_relative '../../../input_types/base_scalar_comparison_input_type'
+
+monkey_patch = Module.new do
+  extend ActiveSupport::Concern
+
+  class_methods do
+  protected
+
+    def get_comparison_input_type(*)
+      GraphQL::Filters::InputTypes::BaseScalarComparisonInputType[self]
+    end
+  end
+end
+
+GraphQL::Schema::Scalar.prepend monkey_patch

data/lib/graphql/filters/dsl/graphql/types/numeric.rb

@@ -0,0 +1,20 @@
+require 'active_support/concern'
+require_relative '../../../input_types/numeric_comparison_input_type'
+
+monkey_patch = Module.new do
+  extend ActiveSupport::Concern
+
+  class_methods do
+  protected
+
+    def get_comparison_input_type(*)
+      GraphQL::Filters::InputTypes::NumericComparisonInputType[self]
+    end
+  end
+end
+
+GraphQL::Types::Int.prepend monkey_patch
+GraphQL::Types::BigInt.prepend monkey_patch
+GraphQL::Types::Float.prepend monkey_patch
+GraphQL::Types::ISO8601Date.prepend monkey_patch
+GraphQL::Types::ISO8601DateTime.prepend monkey_patch

data/lib/graphql/filters/dsl/graphql/types/string.rb

@@ -0,0 +1,16 @@
+require 'active_support/concern'
+require_relative '../../../input_types/string_comparison_input_type'
+
+monkey_patch = Module.new do
+  extend ActiveSupport::Concern
+
+  class_methods do
+  protected
+
+    def get_comparison_input_type(*)
+      GraphQL::Filters::InputTypes::StringComparisonInputType
+    end
+  end
+end
+
+GraphQL::Types::String.prepend monkey_patch

data/lib/graphql/filters/dsl.rb

@@ -0,0 +1,3 @@
+Dir['dsl/**/*.rb', base: __dir__].each do |filename|
+  require_relative filename
+end