Zen::Query

Param-based scope (relation, dataset) generation.

---

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:

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:

# 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:

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:

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:

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:

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:

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

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:

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:

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:

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

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

query_by(:some_field_id) { |id| scope.where(some_field_id: id) }

you can do the following to make things more DRY:

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

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

class ApplicationQuery
  def self.query_by_fields(*fields)
    fields.each do |field|
      query_by field
    end
  end
end

and then

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.