Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/elmassimo/queryable
❔ Gives your queries a home and avoid tucking scopes inside your models
https://github.com/elmassimo/queryable
activerecord design-pattern mongoid query query-objects rails ruby
Last synced: about 1 month ago
JSON representation
❔ Gives your queries a home and avoid tucking scopes inside your models
- Host: GitHub
- URL: https://github.com/elmassimo/queryable
- Owner: ElMassimo
- License: mit
- Created: 2014-04-12T01:20:43.000Z (almost 11 years ago)
- Default Branch: main
- Last Pushed: 2022-02-22T19:11:38.000Z (almost 3 years ago)
- Last Synced: 2024-12-05T15:49:57.189Z (about 1 month ago)
- Topics: activerecord, design-pattern, mongoid, query, query-objects, rails, ruby
- Language: Ruby
- Homepage:
- Size: 127 KB
- Stars: 42
- Watchers: 4
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
Queryable
=====================
[](http://badge.fury.io/rb/queryable)
[](https://travis-ci.org/ElMassimo/queryable)
[](https://codeclimate.com/github/ElMassimo/queryable)
[](https://codeclimate.com/github/ElMassimo/queryable)
[](http://inch-ci.org/github/ElMassimo/queryable)
[](https://github.com/ElMassimo/queryable/blob/master/LICENSE.txt)
Queryable is a mixin that allows you to easily define query objects with chainable scopes.
### Scopes
Scopes serve to encapsulate reusable business rules, a method is defined with
the selected name and block (or proc)
```ruby
class CustomersQuery
include Queryable
scope(:recent) { desc(:logged_in_at) }
scope :active, ->{ where(status: 'active') }
scope :favourite_brand do |product, brand|
where("favourites.#{product}": brand)
end
def current
recent.active
end
def miller_fans
favourite_brand(:beer, :Miller)
end
end
CustomerQuery.new(shop.customers).miller_fans
```
### Delegation
By default most Array methods are delegated to the internal query. It's possible
to delegate extra methods to the query by calling `delegate`.
```ruby
class CustomersQuery
include Queryable
delegate :update_all, :destroy_all, :exists?
end
```
### Delegate and Chain
Sometimes you want to delegate a method to the internal query, but continue
working with the query object like if you were calling scopes.
You can achieve that using `delegate_and_chain`, which will delegate the method
call, assign the return value as the internal query, and return the query object.
```ruby
class CustomersQuery
include Queryable
delegate_and_chain :where, :order_by
end
```
## Advantages
* Query objects are easy to understand.
* You can inherit, mixin, and chain queries in a very natural way.
* Increased testability, pretty close to being ORM/ODM agnostic.
## Basic Usage
If you are using Mongoid or ActiveRecord, you might want to try the
`Queryable::Mongoid` and `Queryable::ActiveRecord` modules that already take
care of delegating and chaining most of the methods in the underlying queries.
```ruby
class CustomersQuery
include Queryable::Mongoid
end
CustomersQuery.new.where(:amount_purchased.gt => 2).active.asc(:logged_in_at)
```
This modules also include all the optional modules. If you would like to opt-out
of the other modules you can follow the approach in the [Notes](https://github.com/ElMassimo/queryable#notes) section.
## Advanced Usage
There are three opt-in modules that can help you when creating query objects.
These modules would need to be manually required during app initialization or
wherever necessary (in Rails, config/initializers).
### DefaultQuery
Provides default initialization for query objects, by attempting to infer the
class name of the default collection for the query, and it also provides a
`queryable` method to specify it.
```ruby
require 'queryable/default_query'
def CustomersQuery
include Queryable
include Queryable::DefaultQuery
end
def OldCustomersQuery < CustomersQuery
queryable ArchivedCustomers
end
CustomersQuery.new.queryable == Customer.all
OldCustomersQuery.new.queryable == ArchivedCustomers.all
```
If you want to use common base objects for your queries, you may want want to
delay the automatic inference:
```ruby
class BaseQuery
include Queryable
include Queryable::DefaultQuery
queryable false
end
class CustomersQuery < BaseQuery
end
CustomersQuery.new.queryable == Customer.all
```
### DefaultScope
Allows to define default scopes in query objects, and inherit them in query
object subclasses.
```ruby
require 'queryable/default_scope'
def CustomersQuery
include Queryable
include Queryable::DefaultScope
include Queryable::DefaultQuery
default_scope :active
scope :active, -> { where(:last_purchase.gt => 7.days.ago) }
end
def BigCustomersQuery < CustomersQuery
default_scope :big_spender
scope :big_spender, -> { where(:total_expense.gt => 9999999) }
end
CustomersQuery.new.queryable == Customer.where(:last_purchase.gt => 7.days.ago)
BigCustomersQuery.new.queryable ==
Customer.where(:last_purchase.gt => 7.days.ago, :total_expense.gt => 9999999)
```
### Chainable
While scopes are great because of their terseness, they can be limiting because
the block executes in the context of the internal query, so methods, constants,
and variables of the Queryable are not accessible.
For those cases, you can use a normal method, and then `chain` it. Chainable
will take care of setting the return value of the method as the internal query,
and return `self` at the end to make the method chainable.
```ruby
class CustomersQuery
include Queryable
include Queryable::Chainable
chain :active, :recent
def active
where(status: 'active')
end
def recent
queryable.desc(:logged_in_at)
end
chain def search(field_values)
field_values.inject(queryable) { |query, (field, value)|
query.where(field => /#{value}/i)
}
end
def search_in_active(field_values)
search(field_values).active
end
end
CustomerQuery.new(shop.customers).miller_fans.search_in_current(last_name: 'M')
```
### Notes
To avoid repetition, it's a good idea to create a `BaseQuery` object
to contain both the modules inclusion, and common scopes you may reuse.
```ruby
require 'queryable/chainable'
require 'queryable/default_scope'
require 'queryable/default_query'
def BaseQuery
include Queryable
include Queryable::Chainable
include Queryable::DefaultScope
include Queryable::DefaultQuery
# If you want to be concise:
include Queryable::DefaultQuery, Queryable::DefaultScope, Queryable::Chainable, Queryable
queryable false
scope :recent, ->{ where(:created_at.gt => 1.week.ago) }
end
def CustomersQuery < BaseQuery
...
end
```
## Testing
You can check the [specs](https://github.com/ElMassimo/queryable/tree/master/spec) of the project
to check how to test query objects without even having to require the ORM/ODM, or
you can test by requiring your ORM/ODM and executing queries as usual.
## RDocs
You can view the **Queryable** documentation in RDoc format here:
http://rubydoc.info/github/ElMassimo/queryable/master/frames
License
--------
Copyright (c) 2014 Máximo Mussini
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.