parascope gem for param-based scope generation
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.
Add this line to your application's Gemfile:
gem 'zen-query'
And then execute:
$ bundle
Or install it yourself as:
$ gem install zen-query
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.
zen-query
provides Zen::Query
class, descendants of which should declare
scope manipulations using query_by
, sift_by
and other class methods bellow.
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.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
: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")
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
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.
Bug reports and pull requests are welcome on GitHub at https://github.com/akuzko/zen-query.
The gem is available as open source under the terms of the MIT License.