Thorderbolt
Thorderbolt
adds the ability to order ActiveRecord
relation in an arbitrary order without having to store anything extra in the database.
It's as easy as:
class User < ActiveRecord::Base
extend Thorderbolt
end
User.order_as(name: ['John', 'Tom'])
=> #<ActiveRecord::Relation [
#<User id: 3, name: 'John'>,
#<User id: 1, name: 'Tom'>,
#<User id: 2, name: 'Alex'>,
#<User id: 4, name: 'Mike'>
#]>
Ordering of each specified field as equal is also supported. In that case usual order will be applied for all the satisfying condition records:
User.order_as_any(name: ['John', 'Tom'])
=> #<ActiveRecord::Relation [
#<User id: 1, name: 'Tom'>,
#<User id: 3, name: 'John'>,
#<User id: 2, name: 'Alex'>,
#<User id: 4, name: 'Mike'>
#]>
Using thorderbolt
doesn't require any additional tables in DB.
This gem is heavily inspired by order_as_specified, but strongly refactored with addition of some extra features.
Installation
Add this line to your application Gemfile:
gem 'thorderbolt'
And then execute:
$ bundle
Or install it yourself as:
$ gem install thorderbolt
Usage
actually, each example below is true for order_as
and order_as_any
methods. The difference is that order_as
fixes ordering between specified records, when order_as_any
just puts specified records at the top and don't change ordering between them at all.
Basic usage is simple:
class User < ActiveRecord::Base
extend Thorderbolt
end
User.order_as(name: ['John', 'Tom'])
=> #<ActiveRecord::Relation [
#<User id: 3, name: 'John'>,
#<User id: 1, name: 'Tom'>,
#<User id: 2, name: 'Alex'>,
#<User id: 4, name: 'Mike'>
#]>
This returns all Users
ordered by the given names. Note that this
ordering is not possible with a simple ORDER BY
. Magic!
Like any other ActiveRecord
relation, it can be chained:
User
.where(name: ['John', 'Tom', 'Mike']).
.order_as(name: ['John', 'Tom'])
.limit(3)
=> #<ActiveRecord::Relation [
#<User id: 3, name: 'John'>,
#<User id: 1, name: 'Tom'>,
#<User id: 4, name: 'Mike'>
]>
We can use chaining in this way to order by multiple attributes as well:
User.
order_as(name: ['John', 'Mike']).
order_as(id: [4, 3, 5]).
order(:updated_at)
=> #<ActiveRecord::Relation [
# First is name 'John'...
#<User id: 1, name: 'John', updated_at: '2020-08-01 02:22:00'>,
# Within the name, we order by :updated_at...
#<User id: 2, name: 'John', updated_at: '2020-08-01 07:29:07'>,
# Then name 'Mike'...
#<User id: 9, name: 'Mike', updated_at: '2020-08-03 04:11:26'>,
# Within the name, we order by :updated_at...
#<User id: 8, name: 'Mike', updated_at: '2020-08-04 18:52:14'>,
# Then id 4...
#<User id: 4, name: 'Alex', updated_at: '2020-08-01 12:59:33'>,
# Then id 3...
#<User id: 3, name: 'Tom', updated_at: '2020-08-02 19:41:44'>,
# Then id 5...
#<User id: 5, name: 'Tom', updated_at: '2020-08-02 22:12:52'>,
# Then we order by :updated_at...
#<User id: 7, name: 'Alex', updated_at: '2020-08-02 14:27:16'>,
#<User id: 6, name: 'Tom', updated_at: '2020-08-03 14:26:06'>,
]>
We can also use this when we want to sort by an attribute in another model:
User
.joins(:city)
.order_as(cities: { id: [first_city.id, second_city.id, third_city.id] })
In all the cases, results with attribute values which aren't in tghe given list will be
sorted as if the attribute is NULL
in a typical ORDER BY
:
User.order_as(name: ['Tom', 'John'])
=> #<ActiveRecord::Relation [
#<User id: 2, name: 'Tom'>,
#<User id: 3, name: 'John'>,
#<User id: 1, name: 'Mike'>,
#<User id: 4, name: 'Mike'>
]>
Note that an error is raised if a nil
value was passed in the ordering params, because
databases do not have good or consistent support for ordering with NULL
values
in an arbitrary order, so this behavior isn't permitted.
Limitations
Databases may have limitations on the underlying number of fields you can have
in an ORDER BY
clause. For example, in PostgreSQL if you pass in more than
1664 list elements you'll receive such error:
PG::ProgramLimitExceeded: ERROR: target lists can have at most 1664 entries
That's a database limitation that this gem cannot avoid, unfortunately.
Contributing
- Fork it (https://github.com/TolichP/thorderbolt/fork)
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create a new Pull Request
Please, make sure your changes have appropriate tests (bundle exec rspec
) and conform to the Rubocop style specified.
License
Thorderbolt
is released under the MIT License.