zen-query 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 50b08ec0ae8f0289575e0741873b57ec885f9d6c06fcd0dd6f31909127102585
+  data.tar.gz: 00aa3acdcbf0b33c4128bd420e90f95b260e4166963fba4d248e17508fc11a2c
+SHA512:
+  metadata.gz: 45044327d4848b4250a6f8603f19110ed1dcaf4ede3d333b5171425a6f7679f0369674f17ca1f0afec812b260583ea60ed64b39c6bf1aa5bf63c6aa60bdd53c4
+  data.tar.gz: bff2db15804f328d7f5e2c7f59d1b180443449ff78b7a9cf304ceb6310e794043fc0c8ec001b603b90200b9a2c827496c92f002d5927dc346c5d7feec45dd4c7

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+.rspec_status
+.ruby-version
+.ruby-gemset
+

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,36 @@
+AllCops:
+  NewCops: disable
+  TargetRubyVersion: 2.4
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented_relative_to_receiver
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/AccessModifierDeclarations:
+  EnforcedStyle: group
+
+Style/Documentation:
+  Enabled: false
+
+Style/LambdaCall:
+  Enabled: false
+
+Style/ClassAndModuleChildren:
+  Enabled: false
+
+Style/DoubleNegation:
+  Enabled: false
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*.rb'
+    - 'zen-query.gemspec'
+
+Layout/LineLength:
+  Exclude:
+    - 'spec/**/*.rb'

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.4.0
+before_install: gem install bundler -v 2.1.0

data/CHANGELOG

@@ -0,0 +1,21 @@
+=== master
+
+Improve :index option support, add query_by! and sift_by! methods
+
+=== 1.0.3
+
+Explicitly apply query blocks in definition order
+
+=== 1.0.2
+
+Remove base_scope application on sifted instance
+
+=== 1.0.1
+
+Fix base scope application on sifted instance
+
+Add [github release] badge to README
+
+Update README, add CHANGELOG
+
+=== 1.0.0

data/Gemfile

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2016 Artem Kuzko
+
+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,428 @@
+# Zen::Query
+
+Param-based scope (relation, dataset) generation.
+
+[![build status](https://secure.travis-ci.org/akuzko/zen-query.png)](http://travis-ci.org/akuzko/zen-query)
+[![github release](https://img.shields.io/github/release/akuzko/zen-query.svg)](https://github.com/akuzko/zen-query/releases)
+
+---
+
+This gem provides a `Zen::Query` class with a declarative and convenient API
+to build scopes (ActiveRecord relations or arbitrary objects) dynamically, based
+on parameters passed to query object on initialization.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'zen-query'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install zen-query
+
+## Usage
+
+Despite the fact `zen-query` was intended to help building ActiveRecord relations
+via scopes or query methods, it's usage is not limited to ActiveRecord cases and
+may be used with any arbitrary classes and objects. In fact, for development and
+testing, `OpenStruct` instance is used as a generic subject. However, ActiveRecord
+examples should illustrate gem's usage in the best way.
+
+For most examples in this README, `scope` method is used as accessor to
+current subject value. This behavior is easily achieved via `Query.alias_subject_name(:scope)`
+method call.
+
+### API
+
+`zen-query` provides `Zen::Query` class, descendants of which should declare
+scope manipulations using `query_by`, `sift_by` and other class methods bellow.
+
+#### Class Methods
+
+- `query_by(*presence_fields, **value_fields, &block)` declares a scope-generation query
+  block that will be executed if, and only if all values of query params at the keys of
+  `presence_fields` are present in activesupport's definition of presence and all `value_fields`
+  are present in query params as is. The block is executed in context of query
+  object. All values of specified params are yielded to the block. If the block
+  returns a non-nil value, it becomes a new scope for subsequent processing. Of course,
+  there can be multiple `query_by` block definitions. Methods accepts additional options:
+  - `:index` - allows to specify order of query block applications. By default all query
+    blocks have index of 0. This option also accepts special values `:first` and `:last` for
+    more convenient usage. Queries with the same value of `:index` option are applied in
+    order of declaration.
+  - `:if` - specifies condition according to which query should be applied. If Symbol
+    or String is passed, calls corresponding method. If Proc is passed, it is executed
+    in context of query object. Note that this is optional condition, and does not
+    overwrite original param-based condition for a query block that should always be met.
+  - `:unless` - the same as `:if` option, but with reversed boolean check.
+
+- `query_by!(*fields, &block)` declares scope-generation block that is always executed
+  (unless `:if` and/or `:unless` options are used). All values in params at `fields` keys are
+  yielded to the block. As `query_by`, accepts `:index`, `:if` and `:unless` options.
+
+- `query(&block)` declares scope-generation block that is always executed (unless `:if`
+  and/or `:unless` options are used). As `query_by`, accepts `:index`, `:if` and `:unless`
+  options.
+
+*Examples:*
+
+```ruby
+# executes block only when params[:department_id] is non-empty:
+query_by(:department_id) { |id| scope.where(department_id: id) }
+
+# executes block only when params[:only_active] == 'true':
+query_by(only_active: 'true') { scope.active }
+
+# executes block only when *both* params[:first_name] and params[:last_name]
+# are present:
+query_by(:first_name, :last_name) do |first_name, last_name|
+  scope.where(first_name: first_name, last_name: last_name)
+end
+
+# if query block returns nil, scope will remain intact:
+query { scope.active if only_active? }
+
+# conditional example:
+query(if: :include_inactive?) { scope.with_inactive }
+
+def include_inactive?
+  company.settings.include_inactive?
+end
+```
+
+- `sift_by(*presence_fields, **value_fields, &block)` method is used to hoist sets of
+  query definitions that should be applied if, and only if, all specified values
+  match criteria in the same way as in `query_by` method. Just like `query_by` method,
+  values of specified fields are yielded to the block. Accepts the same options as
+  it's `query_by` counterpart. Such `sift_by` definitions may be nested in any depth.
+
+- `sift_by!(*fields, &block)` declares a sifter block that is always applied (unless
+  `:if` and/or `:unless` options are used). All values in params at specified `fields`
+  are yielded to the block.
+
+- `sifter` alias for `sift_by`. Results in a more readable construct when a single
+  presence field is passed. For example, `sifter(:paginated)`.
+
+*Examples:*
+
+```ruby
+sift_by(:search_value, :search_type) do |value|
+  # definitions in this block will be applied only if *both* params[:search_value]
+  # and params[:search_type] are present
+
+  search_value = "%#{value}%"
+
+  query_by(search_type: 'name') { scope.name_like(value) }
+  query_by(search_type: 'email') { scope.where("users.email LIKE ?", search_value) }
+end
+
+sifter :paginated do
+  query_by(:page, :per_page) do |page, per|
+    scope.page(page).per(per)
+  end
+end
+
+def paginated_records
+  resolve(:paginated)
+end
+```
+
+- `subject(&block)` method is used to define a base subject as a starting point
+  of subject-generating process. Note that `subject` will not be evaluated if
+  query is initialized with a given subject.
+
+*Examples:*
+
+```ruby
+subject { User.all }
+```
+
+- `defaults(&block)` method is used to declare default query params that are
+  reverse merged with params passed on query initialization. When used in `sift_by`
+  block, hashes are merged altogether. Accepts a `block`, it's return value
+  will be evaluated and merged on query object instantiation, allowing to have
+  dynamic default params values.
+
+*Examples:*
+
+```ruby
+defaults { { later_than: 1.week.ago } }
+
+sifter :paginated do
+  # sifter defaults are merged with higher-level defaults:
+  defaults { { page: 1, per_page: 25 } }
+end
+```
+
+- `guard(message = nil, &block)` defines a guard instance method block (see instance methods
+  bellow). All such blocks are executed before query object resolves scope via
+  `resolve_scope` method. Optional `message` may be supplied to provide more informative
+  error message.
+
+*Examples:*
+
+```ruby
+sift_by(:sort_col, :sort_dir) do |scol, sdir|
+  # will raise Zen::Query::GuardViolationError on scope resolution if
+  # params[:sort_dir] is not 'asc' or 'desc'
+  guard(':sort_dir should be "asc" or "desc"') do
+    sdir.downcase.in?(%w(asc desc))
+  end
+
+  query { scope.order(scol => sdir) }
+end
+```
+
+- `raise_on_guard_violation(value)` allows to specify whether or not exception should be raised
+  whenever any guard block is violated during scope resolution. When set to `false`, in case
+  of any violation, `resolve` will return `nil`, and query will have `violation` property
+  set with value corresponding to the message of violated block. Default option value is `true`.
+
+*Examples:*
+
+```ruby
+raise_on_guard_violation false
+
+sift_by(:sort_col, :sort_dir) do |scol, sdir|
+  guard(':sort_dir should be "asc" or "desc"') do
+    sdir.downcase.in?(%w(asc desc))
+  end
+
+  query { scope.order(scol => sdir) }
+end
+```
+
+```ruby
+query = UsersQuery.new(sort_col: 'id', sort_dir: 'there')
+query.resolve # => nil
+query.violation # => ":sort_dir should be \"asc\" or \"desc\""
+```
+
+- `attributes(*attribute_names)` allows to specify additional attributes that can be passed
+  to query object on initialization. For each given attribute name, reader method is generated.
+
+#### Instance Methods
+
+- `initialize(params: {}, subject: nil, **attributes)` initializes a query with
+  `params`, an optional subject and attributes. If subject is aliased, corresponding
+  key should be used instead. The rest of attributes are only accepted if they were
+  declared via `attributes` class method call.
+
+*Examples:*
+
+```ruby
+query = UsersQuery.new(params: query_params, company: company)
+```
+
+- `params` returns a parameters passed in initialization, reverse merged with query
+  defaults.
+
+- `subject` "current" subject of query object. For an initialized query object corresponds
+  to base subject. Primary usage is to call this method in `query_by` blocks and return
+  it's mutated version corresponding to passed `query_by` arguments.
+
+  Can be aliased to more suitable name with `Query.alias_subject_name` class method.
+
+- `guard(&block)` executes a passed `block`. If this execution returns falsy value,
+  `GuardViolationError` is raised. You can use this method to ensure safety of param
+  values interpolation to a SQL string in a `query_by` block for example.
+
+*Examples:*
+
+```ruby
+query_by(:sort_col, :sort_dir) do |scol, sdir|
+  # will raise Zen::Query::GuardViolationError on scope resolution if
+  # params[:sort_dir] is not 'asc' or 'desc'
+  guard { sdir.downcase.in?(%w(asc desc)) }
+
+  scope.order(scol => sdir)
+end
+```
+
+- `resolve(*presence_keys, override_params = {})` returns a resulting scope
+  generated by all queries and sifted queries that fit to query params applied to
+  base scope. Optionally, additional params may be passed to override the ones passed on
+  initialization. For convinience, you may pass list of keys that should be resolved
+  to `true` with params (for example, `resolve(:with_projects)` instead of
+  `resolve(with_projects: true)`). It's the main `Query` instance method that
+  returns the sole purpose of it's instances.
+
+*Examples:*
+
+```ruby
+defaults { { only_active: true } }
+
+subject { company.users }
+
+query_by(:only_active) { subject.active }
+
+sifter :with_departments do
+  query { subject.joins(:departments) }
+
+  query_by(:department_name) do |name|
+    subject.where(departments: { name: name })
+  end
+end
+
+def users
+  @users ||= resolve
+end
+
+# you can use options to overwrite defaults:
+def all_users
+  resolve(only_active: false)
+end
+
+# or to apply a sifter with additional params:
+def managers
+  resolve(:with_departments, department_name: 'managers')
+end
+```
+
+### Composite usage example with ActiveRecord Relation as a subject, aliased as `:relation`
+
+```ruby
+class UserQuery < Zen::Query
+  alias_subject_name :relation
+
+  attributes :company
+
+  defaults { { only_active: true } }
+
+  relation { company.users }
+
+  query_by(:only_active) { relation.active }
+
+  query_by(:birthdate) { |date| relation.by_birtdate(date) }
+
+  query_by :name do |name|
+    relation.where("CONCAT(first_name, ' ', last_name) LIKE :name", name: "%#{name}%")
+  end
+
+  sift_by :sort_column, :sort_direction do |scol, sdir|
+    guard { sdir.to_s.downcase.in?(%w(asc desc)) }
+
+    query { relation.order(scol => sdir) }
+
+    query_by(sort_column: 'name') do
+      relation.reorder("CONCAT(first_name, ' ', last_name) #{sdir}")
+    end
+  end
+
+  sifter :with_projects do
+    query { relation.joins(:projects) }
+
+    query_by :project_name do |name|
+      scope.where(projects: { name: name })
+    end
+  end
+
+  def users
+    @users ||= resolve
+  end
+
+  def project_users
+    @project_users ||= resolve(:with_projects)
+  end
+end
+
+params = { name: 'John', sort_column: 'name', sort_direction: 'DESC', project_name: 'ExampleApp' }
+
+query = UserQuery.new(params: params, company: some_company)
+
+query.project_users # => this is the same as:
+# some_company.users
+#   .active
+#   .joins(:projects)
+#   .where("CONCAT(first_name, ' ', last_name) LIKE ?", "%John%")
+#   .where(projects: { name: 'ExampleApp' })
+#   .order("CONCAT(first_name, ' ', last_name) DESC")
+```
+
+### Hints and Tips
+
+- Keep in mind that query classes are just plain Ruby classes. All `sifter`,
+`query_by` and `guard` declarations are inherited, as well as default params
+declared by `defaults` method. Thus, you can define a BaseQuery with common
+definitions as a base class for queries in your application. Or you can define
+query API blocks in some module's `included` callback to share common definitions
+via module inclusion.
+
+- Being plain Ruby classes also means you can easily extend default functionality
+for your needs. For example, if you're querying ActiveRecord relations, and your
+primary use case looks like
+
+```ruby
+query_by(:some_field_id) { |id| scope.where(some_field_id: id) }
+```
+you can do the following to make things more DRY:
+
+```ruby
+class ApplicationQuery < Zen::Query
+  def self.query_by(*fields, &block)
+    block ||= default_query_block(fields)
+    super(*fields, &block)
+  end
+
+  def self.default_query_block(fields)
+    ->(*values){ scope.where(Hash[fields.zip(values)]) }
+  end
+  private_class_method :default_query_block
+end
+```
+
+and then you can simply call
+
+```ruby
+class UsersQuery < ApplicationQuery
+  base_scope { company.users }
+
+  query_by :first_name
+  query_by :last_name
+  query_by :city, :street_address
+end
+```
+
+Or you can go a little further and declare a class method
+
+```ruby
+class ApplicationQuery
+  def self.query_by_fields(*fields)
+    fields.each do |field|
+      query_by field
+    end
+  end
+end
+```
+
+and then
+
+```ruby
+class UserQuery < ApplicationQuery
+  query_by_fields :first_name, :last_name, :department_id
+end
+```
+
+## 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.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/akuzko/zen-query.
+
+
+## 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,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,73 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "zen/query"
+
+require "ostruct"
+
+class Query < Zen::Query
+  raise_on_guard_violation(false)
+
+  alias_subject_name(:scope)
+
+  subject { OpenStruct.new }
+
+  defaults { { time: Time.now, barbak: "barbak" } }
+
+  query_by :foo do |foo|
+    guard('wrong value for :foo param. try "foo"') { foo == "foo" }
+
+    scope.tap { scope.foo = foo }
+  end
+
+  query_by bar: "bar" do
+    scope.tap { scope.bar = "bar" }
+  end
+
+  sift_by baz: "baz" do |baz|
+    defaults { { bakbar: "bakbar" } }
+
+    guard { upcase(baz) == "BAZ" }
+
+    query { scope.tap { scope.baz = "baz" } }
+
+    query_by :bak do |bak|
+      scope.tap { scope.bak = bak }
+    end
+
+    query_by :barbak do |barbak|
+      scope.tap { scope.barbak = barbak }
+    end
+
+    sift_by :nested_baz do |nested_baz|
+      query_by :bakbar do |bakbar|
+        scope.tap { scope.bakbar = [baz, nested_baz, bakbar].join("-") }
+      end
+    end
+  end
+
+  sift_by :other_baz do |other|
+    query { scope.tap { scope.other_baz = other } }
+  end
+
+  query(if: :condition?) { scope.tap { scope.by_instance_condition = true } }
+  query(unless: :bad_condition?) { scope.tap { scope.not_bad_condition = true } }
+
+  def condition?
+    !!params[:condition]
+  end
+
+  def bad_condition?
+    !condition?
+  end
+
+  def upcase(str)
+    str.upcase
+  end
+end
+
+# q = Query.new(params: { foo: "foo", bar: "bar", baz: "baz", bak: "bak", nested_baz: "nb", other_baz: "ob" })
+
+require "pry"
+Pry.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/lib/zen/query.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+require_relative "query/api_block"
+require_relative "query/api_methods"
+require_relative "query/attributes"
+
+module Zen
+  class Query # rubocop:disable Metrics/ClassLength
+    UndefinedSubjectError = Class.new(StandardError)
+    GuardViolationError = Class.new(ArgumentError)
+
+    extend ApiMethods
+    include Attributes
+
+    raise_on_guard_violation(true)
+
+    attr_reader :params, :violation
+
+    def self.inherited(subclass) # rubocop:disable Metrics/AbcSize
+      subclass.raise_on_guard_violation(raise_on_guard_violation?)
+      subclass.query_blocks.replace(query_blocks.dup)
+      subclass.sift_blocks.replace(sift_blocks.dup)
+      subclass.guard_blocks.replace(guard_blocks.dup)
+      subclass.subject(&subject)
+      subclass.defaults(&defaults) unless defaults.nil?
+      super
+    end
+
+    def initialize(params: {}, **attrs)
+      @params  = klass.fetch_defaults.merge(params)
+      @subject = attrs.delete(self.class.subject_name)
+      @base_params = @params
+      super
+    end
+
+    def subject
+      @subject ||= base_subject
+    end
+
+    def base_subject
+      subject =
+        klass
+          .ancestors
+          .select { |mod| mod.respond_to?(:subject) }
+          .map(&:subject)
+          .compact
+          .first
+          &.call
+
+      raise UndefinedSubjectError, "failed to build subject. Have you missed subject definition?" if subject.nil?
+
+      subject
+    end
+
+    def resolve(*args)
+      @violation = nil
+      arg_params = args.pop if args.last.is_a?(Hash)
+      return sifted_instance.resolve! if arg_params.nil? && args.empty?
+
+      clone_with_params(trues(args).merge(arg_params || {})).resolve
+    rescue GuardViolationError => e
+      @violation = e.message
+      raise if self.class.raise_on_guard_violation?
+    end
+
+    def klass
+      sifted? ? singleton_class : self.class
+    end
+
+    protected
+
+    attr_writer :subject, :params
+    attr_accessor :block
+    attr_reader :attrs
+
+    def sifted_instance
+      blocks = klass.sift_blocks.select { |block| block.fits?(self) }
+
+      blocks.empty? ? self : sifted_instance_for(blocks)
+    end
+
+    def resolve!
+      guard_all
+      klass.sorted_query_blocks.reduce(subject) do |subject, block|
+        clone_with_subject(subject, block).apply_block!.subject
+      end
+    end
+
+    def apply_block!
+      if block&.fits?(self)
+        subject  = instance_exec(*block.values_for(params), &block.block)
+        @subject = subject unless subject.nil?
+      end
+      self
+    end
+
+    def sifted!(query, blocks) # rubocop:disable Metrics/AbcSize
+      singleton_class.query_blocks.replace(query.klass.query_blocks.dup)
+      singleton_class.guard_blocks.replace(query.klass.guard_blocks.dup)
+      singleton_class.subject(&query.klass.subject)
+      blocks.each do |block|
+        singleton_class.instance_exec(*block.values_for(params), &block.block)
+      end
+      params.replace(singleton_class.fetch_defaults.merge(params))
+      @sifted = true
+    end
+
+    def sifted?
+      !!@sifted
+    end
+
+    def clone_with_subject(subject, block = nil)
+      clone.tap do |query|
+        query.subject = subject
+        query.block = block
+      end
+    end
+
+    def clone_with_params(other_params)
+      dup.tap do |query|
+        query.params = @base_params.merge(other_params)
+        query.remove_instance_variable("@sifted") if query.instance_variable_defined?("@sifted")
+        query.remove_instance_variable("@subject") if query.instance_variable_defined?("@subject")
+      end
+    end
+
+    def clone_sifted_with(blocks)
+      dup.tap do |query|
+        query.sifted!(self, blocks)
+      end
+    end
+
+    private
+
+    def guard_all
+      klass.guard_blocks.each { |message, block| guard(message, &block) }
+    end
+
+    def guard(message = nil, &block)
+      return if instance_exec(&block)
+
+      violation = message || "guard block violated on #{block.source_location.join(':')}"
+
+      raise GuardViolationError, violation
+    end
+
+    def sifted_instance_for(blocks)
+      clone_sifted_with(blocks).sifted_instance
+    end
+
+    def trues(keys)
+      keys.each_with_object({}) do |key, hash|
+        hash[key] = true
+      end
+    end
+  end
+end

data/lib/zen/query/api_block.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Zen
+  class Query
+    class ApiBlock
+      OPTION_KEYS = %i[index if unless].freeze
+      private_constant :OPTION_KEYS
+
+      attr_reader :presence_fields, :value_fields, :block, :force, :options
+
+      def initialize(presence_fields:, value_fields:, block:, force: false)
+        @options = extract_options!(value_fields)
+
+        @presence_fields = presence_fields
+        @value_fields = value_fields
+        @block = block
+        @force = force
+      end
+
+      def fits?(query)
+        return false unless conditions_met_by?(query)
+        return true if force
+
+        (presence_fields.empty? && value_fields.empty?) ||
+          values_for(query.params).all? { |value| present?(value) }
+      end
+
+      def values_for(params)
+        params.values_at(*presence_fields) + valued_values_for(params)
+      end
+
+      def present?(value)
+        value.respond_to?(:empty?) ? !value.empty? : !!value
+      end
+
+      def index
+        case options[:index]
+        when :first  then -Float::INFINITY
+        when :last   then Float::INFINITY
+        when Numeric then options[:index]
+        else 0
+        end
+      end
+
+      private
+
+      def extract_options!(fields)
+        fields.keys.each_with_object({}) do |key, options|
+          options[key] = fields.delete(key) if OPTION_KEYS.include?(key)
+        end
+      end
+
+      def valued_values_for(params)
+        value_fields.map do |field, required_value|
+          params[field] == required_value && required_value
+        end
+      end
+
+      def conditions_met_by?(query)
+        condition_met?(query, :if) && condition_met?(query, :unless)
+      end
+
+      def condition_met?(query, key)
+        return true unless options.key?(key)
+
+        condition = options[key]
+
+        value =
+          case condition
+          when String, Symbol then query.send(condition)
+          when Proc then query.instance_exec(&condition)
+          else condition
+          end
+
+        key == :if ? value : !value
+      end
+    end
+  end
+end

data/lib/zen/query/api_methods.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module Zen
+  class Query
+    module ApiMethods
+      def alias_subject_name(name)
+        @subject_name = name
+
+        define_singleton_method(name) { |&block| subject(&block) }
+
+        alias_method(name, :subject)
+      end
+
+      def subject_name
+        @subject_name || :subject
+      end
+
+      def raise_on_guard_violation(value)
+        @raise_on_guard_violation = !!value
+      end
+
+      def raise_on_guard_violation?
+        @raise_on_guard_violation
+      end
+
+      def subject(&block)
+        return @subject_block unless block_given?
+
+        @subject_block = block
+      end
+
+      def defaults(&block)
+        return @defaults_block unless block_given?
+
+        @defaults_block = block
+      end
+
+      def fetch_defaults
+        ancestors
+          .select { |mod| mod.respond_to?(:defaults) }
+          .map(&:defaults)
+          .compact
+          .reduce({}) { |result, block| result.merge!(block.call) }
+      end
+
+      def sift_by(*presence_fields, **value_fields, &block)
+        sift_blocks.push(
+          Query::ApiBlock.new(
+            presence_fields: presence_fields,
+            value_fields: value_fields,
+            block: block
+          )
+        )
+      end
+
+      def query_by(*presence_fields, **value_fields, &block)
+        query_blocks.push(
+          Query::ApiBlock.new(
+            presence_fields: presence_fields,
+            value_fields: value_fields,
+            block: block
+          )
+        )
+      end
+
+      alias sifter sift_by
+      alias query query_by
+
+      def sift_by!(*presence_fields, &block)
+        sift_blocks.push(
+          Query::ApiBlock.new(
+            presence_fields: presence_fields,
+            value_fields: {},
+            block: block,
+            force: true
+          )
+        )
+      end
+
+      def query_by!(*presence_fields, &block)
+        query_blocks.push(
+          Query::ApiBlock.new(
+            presence_fields: presence_fields,
+            value_fields: {},
+            block: block,
+            force: true
+          )
+        )
+      end
+
+      alias sifter! sift_by!
+      alias query! query_by!
+
+      def guard(message = nil, &block)
+        guard_blocks.push([message, block])
+      end
+
+      def sift_blocks
+        @sift_blocks ||= []
+      end
+
+      def query_blocks
+        @query_blocks ||= []
+      end
+
+      def guard_blocks
+        @guard_blocks ||= []
+      end
+
+      def sorted_query_blocks
+        query_blocks.sort do |a, b|
+          if a.index == b.index
+            query_blocks.index(a) <=> query_blocks.index(b)
+          else
+            a.index <=> b.index
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zen/query/attributes.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Zen
+  class Query
+    module Attributes
+      module ClassMethods
+        def inherited(query_class)
+          query_class.const_set(:AttributeMethods, Module.new)
+          query_class.send(:include, query_class::AttributeMethods)
+          query_class.attributes_list.replace(attributes_list.dup)
+          super
+        end
+
+        def attribute_methods
+          const_get(:AttributeMethods)
+        end
+
+        def attributes(*attrs)
+          attributes_list.concat(attrs)
+
+          attrs.each do |name|
+            attribute_methods.send(:define_method, name) { @attributes[name] }
+          end
+        end
+
+        def attributes_list
+          @attributes_list ||= []
+        end
+      end
+
+      def self.included(target)
+        target.extend(ClassMethods)
+      end
+
+      def initialize(**attrs)
+        attributes = attrs.dup
+        attributes.delete(:params)
+        assert_valid_attributes!(attributes)
+        @attributes = attributes
+      end
+
+      private
+
+      def assert_valid_attributes!(attrs)
+        unknown_attrs = attrs.keys - self.class.attributes_list
+
+        raise(ArgumentError, "Unknown attributes #{unknown_attrs.inspect}") if unknown_attrs.any?
+      end
+    end
+  end
+end

data/lib/zen/query/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Zen
+  class Query
+    VERSION = "1.0.0"
+  end
+end

data/zen-query.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "lib/zen/query/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "zen-query"
+  spec.version       = Zen::Query::VERSION
+  spec.authors       = ["Artem Kuzko"]
+  spec.email         = ["a.kuzko@gmail.com"]
+
+  spec.summary       = "Builds a params-sifted scope"
+  spec.description   = 'Zen::Query class provides a way to dynamically
+    apply scopes or ActiveRecord (or any other ORM) query methods based on passed
+    params with a declarative and convenient API'
+  spec.homepage      = "https://github.com/akuzko/zen-query"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.4.0")
+
+  spec.metadata["allowed_push_host"] = "https://rubygems.org/"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/akuzko/zen-query.git"
+
+  # 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(__dir__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", ">= 2.1.0"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "pry-nav"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.0"
+  spec.add_development_dependency "rspec-its", "~> 1.2"
+  spec.add_development_dependency "rubocop", "~> 0.80"
+end

metadata

@@ -0,0 +1,164 @@
+--- !ruby/object:Gem::Specification
+name: zen-query
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Artem Kuzko
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2021-05-11 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.1.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.1.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: pry-nav
+  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: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-its
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.80'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.80'
+description: |-
+  Zen::Query class provides a way to dynamically
+      apply scopes or ActiveRecord (or any other ORM) query methods based on passed
+      params with a declarative and convenient API
+email:
+- a.kuzko@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".travis.yml"
+- CHANGELOG
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/zen/query.rb
+- lib/zen/query/api_block.rb
+- lib/zen/query/api_methods.rb
+- lib/zen/query/attributes.rb
+- lib/zen/query/version.rb
+- zen-query.gemspec
+homepage: https://github.com/akuzko/zen-query
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org/
+  homepage_uri: https://github.com/akuzko/zen-query
+  source_code_uri: https://github.com/akuzko/zen-query.git
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.4.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.6
+signing_key: 
+specification_version: 4
+summary: Builds a params-sifted scope
+test_files: []