ii_finder 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1e3ba37c83b4bc3c8015d95bf52544ea29e90928948c0f5926946e8cb0c49bb3
+  data.tar.gz: c785e88d9b5c78e1a1409cedd805a2944d526de46d6b4acb22272c8c97d732a8
+SHA512:
+  metadata.gz: 67e33beb2d96672958062a58301da0ff1cc9bdb8855572c2e41fa41c685e08a7901d52e6c99df97fec2d986b8043cd59726bd1fbaf3d0c5790854d6720fc8c6d
+  data.tar.gz: 6b70c8f8620928ca1997e79f0178aaba61cd04abfedc5d2ff8e24b7296e9c4e0b7cfaa1be9c4bd05a42ee647e7a5d3c0a532a55e09e285fb362876a914c93470

data/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-18.04
+    strategy:
+      fail-fast: false
+      matrix:
+        ruby: [2.3, 2.4, 2.5, 2.6, 2.7, 3.0]
+        gemfile: ['rails50', 'rails51', 'rails52', 'rails60', 'rails61']
+        exclude:
+          - ruby: 2.3
+            gemfile: rails60
+          - ruby: 2.3
+            gemfile: rails61
+          - ruby: 2.4
+            gemfile: rails60
+          - ruby: 2.4
+            gemfile: rails61
+          - ruby: 3.0
+            gemfile: rails50
+          - ruby: 3.0
+            gemfile: rails51
+          - ruby: 3.0
+            gemfile: rails52
+
+    name: ruby ${{ matrix.ruby }}, ${{ matrix.gemfile }}
+
+    env:
+      BUNDLE_GEMFILE: gemfiles/${{ matrix.gemfile }}.gemfile
+
+    steps:
+    - uses: actions/checkout@v2
+    - uses: ruby/setup-ruby@v1
+      with:
+        ruby-version: ${{ matrix.ruby }}
+        bundler-cache: true
+    - name: Prepare test
+      run: |
+        cd spec/dummy
+        BUNDLE_GEMFILE=../../${{ env.BUNDLE_GEMFILE }} RAILS_ENV=test bundle exec rake db:create db:migrate db:seed
+        cd ../..
+    - name: Run test
+      run: |
+        DEBUG=1 bundle exec rspec

data/.gitignore

@@ -0,0 +1,10 @@
+.bundle/
+.project
+Gemfile.lock
+coverage/
+gemfiles/*.lock
+pkg/
+tmp/
+spec/dummy/db/*.sqlite3
+spec/dummy/db/schema_*.rb
+spec/dummy/log/*.log

data/.rspec

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

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# CHANGELOG
+
+## 1.0.0
+
+* First release.

data/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Yoshikazu Kaneta
+
+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,196 @@
+# IIFinder
+
+A base finder to support building relations from parameters.
+
+## Dependencies
+
+* ruby 2.3+
+* activesupport 5.0+
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ii_finder'
+```
+
+Then execute:
+
+    $ bundle
+
+## Usage
+
+Prepare model:
+
+```ruby
+class User < ActiveRecord::Base
+end
+```
+
+Prepare finder:
+
+```ruby
+class UsersFinder < IIFinder::Base
+  parameters :name
+
+  def name(value)
+    @relation.where(name: value)
+  end
+end
+```
+
+Use finder as follows:
+
+```ruby
+UsersFinder.call(name: 'NAME').to_sql
+#=> SELECT "users".* FROM "users" WHERE "users"."name" = 'NAME'
+```
+
+You can also specify relation as first argument:
+
+```ruby
+UsersFinder.call(User.where(id: [1, 2, 3]), name: 'NAME').to_sql
+#=> SELECT "users".* FROM "users" WHERE "users"."id" IN (1, 2, 3) AND "users"."name" = 'NAME'
+```
+
+### Finder
+
+Finder loops keys of `parameters` and call the corresponding method with value of parameter as argument.
+Finder method will not be called when the value of parameter is blank.
+If you want to receive such value, set `allow_blank` as follows:
+
+```ruby
+class UsersFinder < IIFinder::Base
+  parameters :name, allow_blank: true
+
+  def name(value)
+    @relation.where(name: value)
+  end
+end
+
+UsersFinder.call(name: '').to_sql
+#=> SELECT "users".* FROM "users" WHERE "users"."name" = ''
+```
+
+Finder has following attributes:
+
+```ruby
+class UsersFinder < IIFinder::Base
+  parameters :name
+
+  def name(value)
+    puts "relation: #{@relation}"
+    puts "criteria: #{@criteria}"
+    puts "model: #{@model}"
+    puts "table: #{@table}"
+  end
+end
+
+UsersFinder.call(name: 'NAME')
+#=> relation: #<User::ActiveRecord_Relation:
+#   criteria: {:name=>'NAME'}
+#   model: User
+#   table: #<Arel::Table ...>
+```
+
+Return value of each finder method is merged into `@relation` if it is a kind of `ActiveRecord::Relation`.
+In case you want to merge by yourself, set configuration as follows:
+
+```ruby
+IIFinder.configure do |config|
+  config.merge_relation = false
+end
+
+class UsersFinder < IIFinder::Base
+  parameters :name
+
+  def name(value)
+    @relation = @relation.where(name: value)
+  end
+end
+
+UsersFinder.call(name: 'NAME').to_sql
+#=> SELECT "users".* FROM "users" WHERE "users"."name" = 'NAME'
+```
+
+#### Callbacks
+
+Following callbacks are available.
+
+* `before_call`
+* `around_call`
+* `after_call` 
+
+For example:
+
+```ruby
+class UsersFinder < IIFinder::Base
+  after_call :default_order
+
+  def default_order
+    @relation = @relation.order(id: :desc)
+  end
+end
+
+UsersFinder.call.to_sql
+#=> SELECT "users".* FROM "users" ORDER BY "users"."id" DESC
+```
+
+Note that finder does not handle the return value of callback.
+When you want to update `@relation` in the callback,
+reassign `@relation` or use methods like `where!` or `order!`.
+
+### Lookup for model
+
+Finder lookups related model by its class name when the first argument of `call` is not relation.
+So the name of finder class should be composed of the name of model class.
+For example:
+
+```ruby
+class User < ActiveRecord::Base
+end
+
+class UsersFinder < IIFinder::Base
+end
+
+IIFinder::Base.lookup(UsersFinder)
+#=> User
+```
+
+Note that superclass of finder is also looked up until related model is found.
+
+```ruby
+class User < ActiveRecord::Base
+end
+
+class UsersFinder < IIFinder::Base
+end
+
+class InheritedUsersFinder < UsersFinder
+end
+
+IIFinder::Base.lookup(InheritedUsersFinder)
+#=> User
+```
+
+### Scope for model
+
+In case you want to call finder from model, include `IIFinder::Scope` into model as follows:
+
+```ruby
+class User < ActiveRecord::Base
+  include IIFinder::Scope
+end
+
+User.finder_scope(name: 'NAME').to_sql
+#=> SELECT "users".* FROM "users" WHERE "users"."name" = 'NAME'
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome at https://github.com/kanety/ii_finder.
+
+## 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 "ii_finder"
+
+# 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,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/gemfiles/rails50.gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gem "rails", "~> 5.0.0"
+gem "sqlite3", "~> 1.3.6"
+
+gemspec path: "../"

data/gemfiles/rails51.gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gem "rails", "~> 5.1.0"
+gem "sqlite3", "~> 1.3.6"
+
+gemspec path: "../"

data/gemfiles/rails52.gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gem "rails", "~> 5.2.0"
+gem "sqlite3", "~> 1.3.6"
+
+gemspec path: "../"

data/gemfiles/rails60.gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gem "rails", "~> 6.0.0"
+
+gemspec path: "../"

data/gemfiles/rails61.gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gem "rails", "~> 6.1.0"
+
+gemspec path: "../"

data/ii_finder.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ii_finder/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "ii_finder"
+  spec.version       = IIFinder::VERSION
+  spec.authors       = ["Yoshikazu Kaneta"]
+  spec.email         = ["kaneta@sitebridge.co.jp"]
+  spec.summary       = %q{A base finder to support building relations from parameters}
+  spec.description   = %q{A base finder to support building relations from parameters}
+  spec.homepage      = "https://github.com/kanety/ii_finder"
+
+  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_dependency "activesupport", ">= 5.0"
+
+  spec.add_development_dependency "rails", ">= 5.0"
+  spec.add_development_dependency "sqlite3"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec-rails"
+  spec.add_development_dependency "simplecov"
+end

data/lib/ii_finder.rb

@@ -0,0 +1,19 @@
+require 'active_support'
+
+require 'ii_finder/version'
+require 'ii_finder/config'
+require 'ii_finder/errors'
+require 'ii_finder/base'
+require 'ii_finder/scope'
+
+module IIFinder
+  class << self
+    def configure
+      yield Config
+    end
+
+    def config
+      Config
+    end
+  end
+end

data/lib/ii_finder/base.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative 'lookup'
+require_relative 'parameters'
+require_relative 'callbacks'
+
+module IIFinder
+  class Base
+    include Parameters
+    include Callbacks
+    include Lookup
+
+    attr_reader :relation, :criteria, :model, :table
+
+    def initialize(*args)
+      if args.size == 0 || args.size == 1
+        @model = self.class.lookup
+        raise IIFinder::Error.new("could not find model for #{self.class}") unless @model
+        @relation = @model.all
+        @criteria = args[0] || {}
+      else
+        @relation = args[0]
+        @criteria = args[1]
+        @model = @relation.klass
+      end
+      @table = @model.arel_table
+    end
+
+    def call
+      run_callbacks :call do
+        self.class._parameters.each do |param|
+          value = fetch_criteria(param.name)
+          if value.present? || param.allow_blank?
+            call_method(param.name, value)
+          end
+        end
+      end
+
+      @relation
+    end
+
+    def fetch_criteria(name)
+      if @criteria.respond_to?(name)
+        @criteria.send(name)
+      elsif @criteria.respond_to?(:fetch)
+        @criteria.fetch(name, nil)
+      end
+    end
+
+    def call_method(name, value)
+      result = send(name, value)
+
+      if Config.merge_relation && result.is_a?(ActiveRecord::Relation)
+        @relation = @relation.merge(result)
+      end
+    end
+
+    class << self 
+      def call(*args)
+        new(*args).call
+      end
+    end
+  end
+end

data/lib/ii_finder/callbacks.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module IIFinder
+  module Callbacks
+    extend ActiveSupport::Concern
+    include ActiveSupport::Callbacks
+
+    included do
+      define_callbacks :call
+    end
+
+    class_methods do
+      def before_call(*args, &block)
+        set_callback(:call, :before, *args, &block)
+      end
+
+      def after_call(*args, &block)
+        set_callback(:call, :after, *args, &block)
+      end
+
+      def around_call(*args, &block)
+        set_callback(:call, :around, *args, &block)
+      end
+    end
+  end
+end

data/lib/ii_finder/config.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module IIFinder
+  class Config
+    class_attribute :data
+
+    self.data = {
+      lookup_cache: true,
+      merge_relation: true
+    }
+
+    data.keys.each do |key|
+      define_singleton_method "#{key}" do
+        data[key]
+      end
+
+      define_singleton_method "#{key}=" do |val|
+        data[key] = val
+      end
+    end
+  end
+end

data/lib/ii_finder/errors.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module IIFinder
+  class Error < StandardError
+  end
+end

data/lib/ii_finder/lookup.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module IIFinder
+  module Lookup
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_model
+    end
+
+    class_methods do
+      def model(model)
+        self._model = model
+      end
+
+      def lookup(klass = self)
+        _model || Lookup.call(klass)
+      end
+    end
+
+    class << self
+      class_attribute :_cache
+      self._cache = {}
+
+      def call(klass)
+        return if terminate?(klass)
+
+        cache(klass) do
+          if klass.name && (resolved = resolve(klass))
+            resolved
+          elsif klass.superclass
+            call(klass.superclass)
+          end
+        end
+      end
+
+      private
+
+      def cache(klass)
+        if Config.lookup_cache
+          self._cache[klass] ||= yield
+        else
+          yield
+        end
+      end
+
+      def terminate?(klass)
+        klass.name.to_s.in?(['IIFinder::Base', 'ActiveRecord::Base'])
+      end
+
+      def resolve(klass)
+        resolved_name = if klass < IIFinder::Base
+            klass.name.sub(/Finder$/, '').singularize
+          else
+            klass.name.pluralize + 'Finder'
+          end
+        resolved = resolved_name.safe_constantize
+        return resolved if resolved && resolved_name == resolved.name
+      end
+    end
+  end
+end

data/lib/ii_finder/parameter.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module IIFinder
+  class Parameter
+    attr_accessor :name
+    attr_accessor :options
+
+    def initialize(name, options = {})
+      @name = name
+      @options = options
+    end
+
+    def allow_blank?
+      @options[:allow_blank]
+    end
+  end
+end

data/lib/ii_finder/parameters.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require_relative 'parameter'
+
+module IIFinder
+  module Parameters
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_parameters
+      self._parameters = []
+    end
+
+    class_methods do
+      def parameters(*names, **options)
+        names.each do |name|
+          self._parameters = _parameters + [Parameter.new(name, options)]
+        end
+      end
+    end
+  end
+end

data/lib/ii_finder/scope.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module IIFinder
+  module Scope
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def finder_scope(criteria)
+        finder = IIFinder::Lookup.call(self)
+        raise IIFinder::Error.new("could not find finder for #{self}") unless finder
+        finder.call(criteria)
+      end
+    end
+  end
+end

data/lib/ii_finder/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module IIFinder
+  VERSION = '1.0.0'
+end

metadata

@@ -0,0 +1,152 @@
+--- !ruby/object:Gem::Specification
+name: ii_finder
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Yoshikazu Kaneta
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2021-07-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.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: rake
+  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: rspec-rails
+  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: simplecov
+  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'
+description: A base finder to support building relations from parameters
+email:
+- kaneta@sitebridge.co.jp
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- CHANGELOG.md
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- gemfiles/rails50.gemfile
+- gemfiles/rails51.gemfile
+- gemfiles/rails52.gemfile
+- gemfiles/rails60.gemfile
+- gemfiles/rails61.gemfile
+- ii_finder.gemspec
+- lib/ii_finder.rb
+- lib/ii_finder/base.rb
+- lib/ii_finder/callbacks.rb
+- lib/ii_finder/config.rb
+- lib/ii_finder/errors.rb
+- lib/ii_finder/lookup.rb
+- lib/ii_finder/parameter.rb
+- lib/ii_finder/parameters.rb
+- lib/ii_finder/scope.rb
+- lib/ii_finder/version.rb
+homepage: https://github.com/kanety/ii_finder
+licenses: []
+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: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: A base finder to support building relations from parameters
+test_files: []