toschas-filterable 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f83471709da4dc0f30669acc4c5a27c6d44fa6f9
+  data.tar.gz: 8f8792764eb8536762d2094bf882acf4692e22df
+SHA512:
+  metadata.gz: 229de4e950f36b47a2566cd4c7a888ca82ebf62f47b76628c4c9610eda96c5d5db84d645e4021f7550c14b35f90ac17d4cda8e978329bb4b8a37a4150731fe48
+  data.tar.gz: b03b18b23365781d9aa2270c4888fbd58ec143ffdd1d5ed89a9b159ea6feea924c8acdd7873cca9a7b1af2718fd9b537f82efd5c25a44d2353bbcafa977f8374

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# vim
+*.swp

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--require spec_helper
+--format documentation

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.3
+cache: bundler

data/CONTRIBUTING.md

@@ -0,0 +1,10 @@
+# Contributing
+
+Thank you for considering contributing to filterable.
+
+ - Fork the repo
+ - Clone the fork: `git clone git@github.com:your_username/filterable.git`
+ - Setup locally: `bundle install` or `bin/setup`
+ - Run the tests: `rspec`
+ - Make your changes and make sure the tests pass
+ - Push to your repo and submit a pull request

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in filterable.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Darjan Vukusic
+
+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,180 @@
+# Filterable 
+[![Build Status](https://travis-ci.org/toschas/filterable.svg?branch=master)](https://travis-ci.org/toschas/filterable)
+[![Code Climate](https://codeclimate.com/github/toschas/filterable/badges/gpa.svg)](https://codeclimate.com/github/toschas/filterable)
+
+Filterable gem aims to simplify the process of filtering active record objects. 
+
+It provides an easy way to define filters on the model (without having to write scopes) and apply them on any active record collection.
+
+See [Defining Filters](#defining-filters), [Filtering objects](#filtering-objects) and [Using in Controller (Rails)](#using-in-controller-rails) for the main focus of the gem.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'toschas-filterable'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install toschas-filterable
+
+## Usage
+
+### Defining filters
+Filterable provides `filter_by` method to ActiveRecord Objects which lets you define attributes to be filtered by:
+
+```ruby
+class User < ActiveRecord::Base
+  filter_by :active, :user_type
+end
+```
+
+### Filtering objects
+Filterable will generate those methods on User class in the example above which can be used directly or passed to `filter` method as a hash of filters.
+
+```ruby
+User.filter(by_active: true, by_user_type: 'customer') # returns users where active is true and user type is equal to 'customer'
+User.by_active(true).by_user_type('customer') # same thing
+```
+
+Method is available on an AR Collection and it returns an AR collection so it can be chained with other methods.
+
+```ruby
+User.where('email LIKE ?', '%@example.com').filter(by_active: true, by_user_type: 'customer')
+```
+or
+```ruby
+User.filter(by_active: true, by_user_type: 'customer').where('email LIKE ?', '%@example.com')
+```
+
+### Using in Controller (Rails)
+You can pass a hash to the `filter` method, like the parameters hash in rails. It will ignore keys that are not defined in the model by default.
+
+**Important - you should always control parameters coming from the request, so the same applies to the `filter` method.**
+
+The right way in rails would be using strong parameters so you can control what can be passed to the filter.
+
+```ruby
+class UsersController < ApplicationController
+    def index
+        @users = User.filter(filter_params)
+    end
+    
+    protected
+    
+    def filter_params
+        params.permit(:by_active, :by_user_type)
+    end
+end
+```
+
+### Range Filters
+For comparable types of fields (numeric values, date or datetime) `from` and `to` filters are also generated
+
+```ruby
+class User < ActiveRecord::Base
+    filter_by :registered_on, :tasks_assigned
+end
+```
+Presuming that 'registered_on' is a date and 'tasks_assigned' is an integer, the following filters will be available:
+
+ - by_registered_on (attribute value is equal to the value passed)
+ - from_registered_on (attribute value is greather than the value passed)
+ - to_registered_on (attribute value is smaller than the value passed)
+ 
+ 
+and the same for 'tasks_assigned' attribute. So for example: 
+
+```ruby
+User.filter(from_tasks_assigned: 2) # returns users with more than 2 tasks assigned
+User.filter(to_registered_on: Date.today) # retuns users registered before today
+```
+
+### Filter by related model attribute
+Filtering by attributes of another model is possible with `joins` option.
+
+**Names of joined models follow the same pattern as when defining relations: singular for 'belongs_to' and 'has_one', and plural for 'has_many'.**
+
+**Filters must also be named accordingly: `:user_email, joins: :user` and `:tasks_title, joins: :tasks`**
+
+```ruby
+class Task < ActiveRecord::Base
+    belongs_to :user
+    filter_by :user_email, joins: :user 
+end
+
+class User < ActiveRecord::Base
+    has_many :tasks
+    filter_by :tasks_title, joins: :tasks
+end
+```
+
+```ruby
+User.filter(by_tasks_title: 'test') # returns users where task title is 'test'
+Task.filter(by_user_email: 'test@example.com') # returns tasks where user email is 'test@example.com'
+```
+
+
+Filtering through two or more related models works the same way, `joins` options must be specified the same way as passing it to `.joins()` method.
+
+So if you want to filter `Company` by task title and you need to join tasks through users, format the option the same way you would tell ActiveRecord
+how to join the tables, and name the filter accordingly.
+
+```ruby
+class Company < ActiveRecord::Base
+    has_many :users
+    filter_by :users_tasks_title, joins: { users: :tasks }
+end
+```
+
+then
+
+```ruby
+Company.filter(by_user_tasks_title: 'test')
+```
+
+### Custom Filters
+By passing `custom: true` option an empty custom filter will be defined. 
+
+It can than be overridden with a scope or a class method.
+
+```ruby
+class Task < ActiveRecord::Base
+    filter_by :fuzzy_title, custom: true # generates empty by_fuzzy_title filter
+    
+    # Overiding the filter with a class method or a scope
+    scope :by_fuzzy_title, ->(title) { where('title LIKE ?', "%#{title}%") }
+end
+```
+
+Custom filters support `prefix` option which can be a symbol, an array, or `:none` explicitly.
+If `prefix` option is not present `by` prefix will be used.
+
+```ruby
+filter_by :custom_filter, custom: true # generates by_custom_filter filter
+filter_by :custom_filter, custom: true, prefix: :where # generates where_custom_filter filter
+filter_by :custom_filter, custom: true, prefix: [:by, :recent] # generates by_custom_filter and recent_custom_filter filters
+filter_by :cutom_filter, custom: true, prefix: :none # generates custom_filter filter
+```
+
+**`joins` option is ignored if `custom: true` is passed**
+
+**`prefix` option is ignored if `custom: true` is not passed**
+
+## Issues
+Bug reports and feature proposals are always welcome. Feel free to open an issue.
+
+## Contributing
+Please see [contributing guide](https://github.com/toschas/filterable/blob/master/CONTRIBUTING.md)
+
+
+## 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,11 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+task :console do
+  exec "irb -r filterable -I ./lib"
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "filterable"
+
+# 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

data/bin/setup

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+bundle install
+

data/lib/toschas/filterable/base.rb

@@ -0,0 +1,13 @@
+module Filterable
+  module Base
+    module ClassMethods
+      def filter_by(*args)
+        Generator.new(self, args).generate
+      end
+    end
+
+    def self.included(base)
+      base.extend ClassMethods
+    end
+  end
+end

data/lib/toschas/filterable/configuration.rb

@@ -0,0 +1,10 @@
+module Filterable
+  class Configuration
+    attr_accessor :ignore_unknown_filters, :ignore_empty_values
+
+    def initialize
+      @ignore_unknown_filters = true
+      @ignore_empty_values = true
+    end
+  end
+end

data/lib/toschas/filterable/generator.rb

@@ -0,0 +1,54 @@
+require_relative 'generators/base'
+require_relative 'generators/custom'
+require_relative 'generators/simple'
+require_relative 'generators/joined'
+
+module Filterable
+  class Generator
+    attr_accessor :model, :filters, :options
+
+    def initialize(model, filters)
+      @model = model
+      @filters = filters
+      @options = filters.last.is_a?(Hash) ? filters.pop : {}
+    end
+
+    def generate
+      generate_filter unless model.respond_to? :filter
+      generate_scopes
+    end
+
+    private
+
+    def generate_filter
+      model.define_singleton_method(
+        :filter, 
+        ->(filtering_params) {
+          results = where(nil)
+          filtering_params.each do |key, value|
+            unless results.respond_to?(key)
+              if Filterable.configuration.ignore_unknown_filters
+                next
+              else
+                raise UnknownFilter, "Unknown filter received: #{key}"
+              end
+            end
+            next if value.blank? && Filterable.configuration.ignore_empty_values
+            results = results.public_send(key, value)
+          end
+          results
+        }
+      )
+    end
+
+    def generate_scopes
+      if options[:custom]
+        Generators::Custom.new(model, filters, options).generate
+      elsif options[:joins].present?
+        Generators::Joined.new(model, filters, options).generate
+      else
+        Generators::Simple.new(model, filters, options).generate
+      end
+    end
+  end
+end

data/lib/toschas/filterable/generators/base.rb

@@ -0,0 +1,20 @@
+module Generators
+  class Base
+    attr_reader :model, :filters, :options
+
+    def initialize(model, filters, options)
+      @model = model
+      @filters = filters
+      @options = options
+    end
+
+    def generate
+    end
+
+    private
+
+    def range_types
+      [:date, :datetime, :integer, :float, :decimal]
+    end
+  end
+end

data/lib/toschas/filterable/generators/custom.rb

@@ -0,0 +1,25 @@
+module Generators
+  class Custom < Base
+    def generate
+      prefixes = custom_prefixes
+      filters.each do |filter|
+        prefixes.each do |prefix|
+          filter_name = prefix == :none ? "#{filter}" : "#{prefix}_#{filter}"
+          model.define_singleton_method(
+            filter_name, 
+            ->(_value) { send(:where, nil) }
+          )
+        end
+      end
+    end
+
+    def custom_prefixes
+      prefix = options[:prefix].blank? ? 'by' : options[:prefix]
+      ensure_prefix_array(prefix)
+    end
+
+    def ensure_prefix_array(prefix)
+      prefix.is_a?(Array) ? prefix.reject(&:blank?) : [prefix]
+    end
+  end
+end

data/lib/toschas/filterable/generators/joined.rb

@@ -0,0 +1,76 @@
+module Generators
+  class Joined < Base
+    def generate
+      filters.each do |filter|
+        field = joined_field(filter)
+        generate_joined_filter(filter, field, relation_name, options[:joins])
+        if range_filter?(field)
+          generate_range_filter(filter, field, relation_name, options[:joins])
+        end
+      end
+    end
+
+    private
+
+    def generate_joined_filter(filter, field, relation_name, join_options)
+      model.define_singleton_method(
+        "by_#{filter}",
+        ->(value) {
+          send(:joins, join_options)
+          .send(:where, 
+                { relation_name.to_s.pluralize => { 
+            field => value } 
+          }
+               )
+        }
+      )
+    end
+
+    def generate_range_filter(filter, field, relation_name, join_options)
+      define_range_filter(:from, filter, field, relation_name, join_options)
+      define_range_filter(:to, filter, field, relation_name, join_options)
+    end
+
+    def define_range_filter(prefix, filter, field, relation_name, join_options)
+      operand = prefix == :from ? '>' : '<'
+
+      model.define_singleton_method(
+        "#{prefix}_#{filter}",
+        ->(value) {
+          send(:joins, join_options)
+          .send(:where, 
+                "#{relation_name.to_s.pluralize}.#{field} #{operand} ?", 
+          value)
+        }
+      )
+    end
+
+
+    def extract_relations(join_options)
+      if join_options.is_a?(Hash)
+        join_options.flat_map{|k, v| [k, *extract_relations(v)]}
+      else
+        [join_options]
+      end
+    end
+
+    def relations
+      @relations ||= extract_relations(options[:joins])
+    end
+
+    def relation_name
+      @relation_name ||= relations.last
+    end
+
+    def joined_field(filter)
+      filter.to_s.split("#{relation_name}_").last
+    end
+
+    def range_filter?(filter)
+      range_types.include?(
+        relation_name.to_s.classify.constantize
+        .type_for_attribute(filter.to_s).type
+      )
+    end
+  end
+end

data/lib/toschas/filterable/generators/simple.rb

@@ -0,0 +1,35 @@
+module Generators
+  class Simple < Base
+    def generate
+      filters.each do |filter|
+        model.define_singleton_method(
+          "by_#{filter}", 
+          ->(value) { send(:where, { filter => value }) }
+        )
+
+        generate_range_filter(filter) if range_filter?(filter)
+      end
+    end
+
+    private
+
+    def range_filter?(filter)
+      range_types.include?(
+        model.to_s.classify.constantize
+        .type_for_attribute(filter.to_s).type
+      )
+    end
+
+    def generate_range_filter(filter)
+      model.define_singleton_method(
+        "from_#{filter}", 
+        ->(value) { send(:where, "#{filter} > ?", value) }
+      )
+
+      model.define_singleton_method(
+        "to_#{filter}", 
+        ->(value) { send(:where, "#{filter} < ?", value) }
+      )
+    end
+  end
+end

data/lib/toschas/filterable/hook.rb

@@ -0,0 +1,9 @@
+module Filterable
+  class Hook
+    def self.init
+      ActiveSupport.on_load(:active_record) do
+        include Filterable::Base
+      end
+    end
+  end
+end

data/lib/toschas/filterable/version.rb

@@ -0,0 +1,3 @@
+module Filterable
+  VERSION = "1.0.1"
+end

data/lib/toschas/filterable.rb

@@ -0,0 +1,21 @@
+require "toschas/filterable/version"
+require "active_record"
+require "toschas/filterable/base"
+require "toschas/filterable/hook"
+require "toschas/filterable/generator"
+require "toschas/filterable/configuration"
+
+module Filterable
+  UnknownFilter = Class.new(StandardError)
+  Hook.init
+
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+  end
+end

data/lib/toschas-filterable.rb

@@ -0,0 +1 @@
+require 'toschas/filterable'

data/toschas-filterable.gemspec

@@ -0,0 +1,29 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'toschas/filterable/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "toschas-filterable"
+  spec.version       = Filterable::VERSION
+  spec.authors       = ["Darjan Vukusic"]
+  spec.email         = ["darjan.vukusic@gmail.com"]
+
+  spec.summary       = %q{Easy filtering of Active Record objects}
+  spec.description   = %q{Filterable gem aims to simplify the process of filtering active record objects.It provides an easy way to define filters on the model (without having to write scopes) and apply them on any active record collection.}
+  spec.homepage      = "https://github.com/toschas/filterable"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.11"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "sqlite3"
+
+  spec.add_dependency "activerecord", ">= 3.0"
+end

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: toschas-filterable
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Darjan Vukusic
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-05-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.11'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+description: Filterable gem aims to simplify the process of filtering active record
+  objects.It provides an easy way to define filters on the model (without having to
+  write scopes) and apply them on any active record collection.
+email:
+- darjan.vukusic@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- CONTRIBUTING.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/toschas-filterable.rb
+- lib/toschas/filterable.rb
+- lib/toschas/filterable/base.rb
+- lib/toschas/filterable/configuration.rb
+- lib/toschas/filterable/generator.rb
+- lib/toschas/filterable/generators/base.rb
+- lib/toschas/filterable/generators/custom.rb
+- lib/toschas/filterable/generators/joined.rb
+- lib/toschas/filterable/generators/simple.rb
+- lib/toschas/filterable/hook.rb
+- lib/toschas/filterable/version.rb
+- toschas-filterable.gemspec
+homepage: https://github.com/toschas/filterable
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5.1
+signing_key: 
+specification_version: 4
+summary: Easy filtering of Active Record objects
+test_files: []