order_query 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6d9ac479b13db9c6531719b51bca15d8079b2b37
+  data.tar.gz: 1c9e90573f1cf98650bdf2d2de5d9969e10ce5fb
+SHA512:
+  metadata.gz: 38e902e5c4804d578d6b4817e9b428c4eb295f3fa87d6cf11efae6592630594f7df2d036c1242766ded5f5d58c703a7f01689d60332be0ef5c0bfe2da375f5e3
+  data.tar.gz: c7830348c5d536abd766fbd9d9834f3359a09f110c62bef57a69a74d4d7ee23f0b08df55650a1abf00247ea675d099d0afe6f5f2b93f4938a1544d66750451cf

data/Gemfile

@@ -0,0 +1,22 @@
+source 'https://rubygems.org'
+
+gemspec
+
+group :test, :development do
+  gem 'coveralls', require: false
+end
+
+platform :mri, :rbx do
+  # version locked because of rbx issue, see https://github.com/travis-ci/travis-ci/issues/2006#issuecomment-36275141
+  gem 'sqlite3', '=1.3.8'
+end
+
+platform :jruby do
+  gem 'activerecord-jdbcsqlite3-adapter'
+end
+
+platform :rbx do
+  gem 'rubysl-singleton', '~> 2.0'
+  gem 'rubysl-optparse', '~> 2.0'
+  gem 'rubysl-ostruct', '~> 2.0'
+end

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2014 Gleb Mazovetskiy
+
+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,106 @@
+# order_query [![Build Status][travis-badge]][travis] [![Code Climate][codeclimate-badge]][codeclimate] [![Coverage Status][coveralls-badge]][coveralls]
+
+order_query provides ActiveRecord methods to find items relative to the position of a given one for a particular ordering. These methods are useful for many navigation scenarios, e.g. links to the next / previous search result from the show page in a typical index/search -> show scenario.
+order_query generates queries that only use `WHERE`, `ORDER BY`, and `LIMIT`, and *not* `OFFSET`. It only takes 1 query (returning 1 row) to get the record before or after the given one.
+
+```ruby
+gem 'order_query', '~> 0.1.0'
+```
+
+## Usage
+
+```ruby
+class Issue < ActiveRecord::Base
+  include OrderQuery
+  order_query :order_display, [
+    [:priority, %w(high medium low)],
+    [:valid_votes_count, :desc, sql: '(votes - suspicious_votes)'],
+    [:updated_at, :desc],
+    # pass unique: true for unique attributes to get more optimized queries
+    # default: true for primary_key, false otherwise
+    [:id, :desc, unique: true]
+  ]
+  def valid_votes_count
+    votes - suspicious_votes
+  end
+end
+```
+
+Order scopes:
+
+```ruby
+Issue.order_display         #=> ActiveRecord::Relation<...>
+Issue.reverse_order_display #=> ActiveRecord::Relation<...>
+```
+
+Relative order:
+
+```ruby
+# get the order object, scope default: Issue.all
+p = Issue.find(31).order_display(scope)
+p.before         #=> ActiveRecord::Relation<...>
+p.previous       #=> Issue<...>
+# pass true to #next and #previous in order to loop onto the the first / last record
+# will not loop onto itself
+p.previous(true) #=> Issue<...>
+p.position   #=> 5
+p.next       #=> Issue<...>
+p.after      #=> ActiveRecord::Relation<...>
+```
+
+`order_query` defines methods that call `.order_by_query` and `#relative_order_by_query`, also public:
+
+```ruby
+Issue.order_by_query([[:id, :desc]])         #=> ActiveRecord::Relation<...>
+Issue.reverse_order_by_query([[:id, :desc]]) #=> ActiveRecord::Relation<...>
+Issue.find(31).relative_order_by_query([[:id, :desc]]).next #=> Issue<...>
+Issue.find(31).relative_order_by_query(Issue.visible, [[:id, :desc]]).next #=> Issue<...>
+```
+
+## How it works
+
+Internally this gem builds a query that depends on the current record's order values and looks like:
+
+```sql
+SELECT ... WHERE
+x0 OR
+y0 AND (x1 OR
+        y1 AND (x2 OR
+                y2 AND ...))
+ORDER BY ...
+LIMIT 1
+```
+
+Where `x` correspond to `>` / `<` terms, and `y` to `=` terms (for resolving ties), per order criterion.
+
+A query may then look like this (with `?` for values):
+
+```sql
+SELECT  "issues".* FROM "issues"  WHERE
+  ("issues"."priority" IN ('medium','low') OR
+   "issues"."priority" = 'high' AND (
+       (votes - suspicious_votes) < 4 OR
+       (votes - suspicious_votes) = 4 AND (
+           "issues"."updated_at" < '2014-03-19 10:23:18.671039' OR
+           "issues"."updated_at" = '2014-03-19 10:23:18.671039' AND
+               "issues"."id" < 9)))
+ORDER BY
+  "issues"."priority"='high' DESC,
+  "issues"."priority"='medium' DESC,
+  "issues"."priority"='low' DESC,
+  (votes - suspicious_votes) DESC,
+  "issues"."updated_at" DESC,
+  "issues"."id" DESC
+LIMIT 1
+```
+
+This project uses MIT license.
+
+
+[travis]: http://travis-ci.org/glebm/order_query
+[travis-badge]: http://img.shields.io/travis/glebm/order_query.svg
+[gemnasium]: https://gemnasium.com/glebm/order_query
+[codeclimate]: https://codeclimate.com/github/glebm/order_query
+[codeclimate-badge]: http://img.shields.io/codeclimate/github/glebm/order_query.svg
+[coveralls]: https://coveralls.io/r/glebm/order_query
+[coveralls-badge]: http://img.shields.io/coveralls/glebm/order_query.svg

data/Rakefile

@@ -0,0 +1,10 @@
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/order_query/order_condition.rb

@@ -0,0 +1,29 @@
+module OrderQuery
+  class OrderCondition
+    attr_reader :name, :order, :order_order, :options, :scope
+
+    def initialize(scope, line)
+      line              = line.dup
+      @options          = line.extract_options!
+      @name             = line[0]
+      @order            = line[1] || :asc
+      @order_order      = line[2] || :desc
+      @scope            = scope
+      @unique           = @options.key?(:unique) ? !!@options[:unique] : (name.to_s == scope.primary_key)
+    end
+
+    def unique?
+      @unique
+    end
+
+    def col_name_sql
+      sql = options[:sql]
+      if sql
+        sql = sql.call if sql.respond_to?(:call)
+        sql
+      else
+        scope.connection.quote_table_name(scope.table_name) + '.' + scope.connection.quote_column_name(name)
+      end
+    end
+  end
+end

data/lib/order_query/order_space.rb

@@ -0,0 +1,44 @@
+require 'order_query/order_condition'
+module OrderQuery
+  class OrderSpace
+    include Enumerable
+    attr_reader :order
+
+    delegate :each, :length, :size, to: :@order
+
+    def initialize(scope, order)
+      @scope = scope
+      @order = order.map { |line| OrderCondition.new(scope, line) }
+    end
+
+    def scope
+      @scope.order(order_by_sql)
+    end
+
+    def reverse_scope
+      @scope.order(order_by_reverse_sql)
+    end
+
+    def to_order_by_sql
+      @order.map { |spec|
+        ord = spec.order
+        if ord == :asc || ord == :desc
+          "#{spec.col_name_sql} #{ord.to_s.upcase}"
+        elsif ord.respond_to?(:map)
+          ord.map { |v| "#{spec.col_name_sql}=#{@scope.connection.quote v} #{spec.order_order.to_s.upcase}" } * ', '
+        else
+          raise "Unknown order #{spec.order.inspect} (#{spec.inspect})"
+        end
+      }
+    end
+
+    def order_by_reverse_sql
+      swap = {'DESC' => 'ASC', 'ASC' => 'DESC'}
+      to_order_by_sql.map { |s| s.gsub(/DESC|ASC/) { |m| swap[m] }  } * ', '
+    end
+
+    def order_by_sql
+       to_order_by_sql * ', '
+    end
+  end
+end

data/lib/order_query/relative_order.rb

@@ -0,0 +1,144 @@
+require 'order_query/order_space'
+module OrderQuery
+
+  class RelativeOrder
+    attr_reader :record, :scope, :order, :values, :options
+
+    def initialize(record, scope, order)
+      @record = record
+      @scope  = scope
+      @order  = order.is_a?(OrderSpace) ? order : OrderSpace.new(scope, order)
+    end
+
+    def first
+      order.scope.first
+    end
+
+    def last
+      order.scope.last
+    end
+
+    def count
+      @total ||= scope.count
+    end
+
+    def position
+      count - after.count
+    end
+
+    def next(loop = true)
+      record_unless_current after.first || (first if loop)
+    end
+
+    def previous(loop = true)
+      record_unless_current before.first || (last if loop)
+    end
+
+    def after
+      records :after
+    end
+
+    def before
+      records :before
+    end
+
+    def records(mode)
+      scope             = (mode == :after ? order.scope : order.reverse_scope)
+      query, query_args = build_query(mode)
+      if query.present?
+        scope.where(query, *query_args)
+      else
+        scope
+      end
+    end
+
+    protected
+
+    def record_unless_current(record)
+      record unless record == @record
+    end
+
+    # @param [:before or :after] mode
+    # @return [query, parameters] conditions that exclude all elements not before / after the current one
+    def build_query(mode)
+      group_operators order.map { |term| [where_mode(term, mode), where_eq(term)] }
+    end
+
+    # Join conditions with operators and parenthesis
+    # @param [Array] term_pairs of query terms [[x0, y0], [x1, y1], ...],
+    #                xi, yi are pairs of [query, parameters]
+    # @return [query, parameters]
+    #   x0 OR
+    #   y0 AND (x1 OR
+    #           y1 AND (x2 OR
+    #                   y2 AND x3))
+    #
+    # Since x matches order criteria with values that come before / after the current record,
+    # and y matches order criteria with values equal to the current record's value (for resolving ties),
+    # the resulting condition matches just the elements that come before / after the record
+    def group_operators(term_pairs)
+      # create "x OR y" string
+      term = join_terms 'OR', *term_pairs[0]
+      rest = term_pairs.from(1)
+      if rest.present?
+        # nest the remaining pairs recursively, appending them with " AND "
+        rest_grouped    = group_operators rest
+        rest_grouped[0] = "(#{rest_grouped[0]})" unless rest.length == 1
+        join_terms 'AND', term, rest_grouped
+      else
+        term
+      end
+    end
+
+    # joins terms with an operator
+    # @return [query, parameters]
+    def join_terms(op, *terms)
+      [terms.map { |t| t.first.presence }.compact.join(" #{op} "),
+       terms.map(&:second).reduce(:+) || []]
+    end
+
+    EMPTY_FILTER = ['', []]
+
+    # @return [query, params] Unless order attribute is unique, such as id, return ['WHERE value = ?', current value].
+    def where_eq(attr)
+      if attr.unique?
+        EMPTY_FILTER
+      else
+        [%Q(#{attr.col_name_sql} = ?), [attr_value(attr)]]
+      end
+    end
+
+    # @param [:before or :after] mode
+    # @return [query, params] return query conditions for attribute values before / after the current one
+    def where_mode(attr, mode)
+      ord   = attr.order
+      value = attr_value attr
+      if ord.is_a?(Array)
+        # ord is an array of sort values, ordered first to last
+        pos         = ord.index(value)
+        sort_values = if pos
+                        dir = attr.order_order
+                        if mode == :after && dir == :desc || mode == :before && dir == :asc
+                          ord.from(pos + 1)
+                        else
+                          ord.first(pos)
+                        end
+                      else
+                        # default to all if current is not in sort order values
+                        ord
+                      end
+        # if current not in result set, do not apply filter
+        return EMPTY_FILTER unless sort_values.present?
+        ["#{attr.col_name_sql} IN (?)", [sort_values]]
+      else
+        # ord is :asc or :desc
+        op = {before: {asc: '<', desc: '>'}, after: {asc: '>', desc: '<'}}[mode][ord || :asc]
+        ["#{attr.col_name_sql} #{op} ?", [value]]
+      end
+    end
+
+    def attr_value(attr)
+      record.send attr.name
+    end
+  end
+end

data/lib/order_query/version.rb

@@ -0,0 +1,3 @@
+module OrderQuery
+  VERSION = '0.1.0'
+end

data/lib/order_query.rb

@@ -0,0 +1,38 @@
+require 'active_support'
+require 'active_record'
+require 'order_query/relative_order'
+
+module OrderQuery
+  extend ActiveSupport::Concern
+
+  included do
+    # @return [OrderSpace] order definition
+    # @example
+    #   Issue.order_query [[:id, :desc]] #=> <ActiveRecord::Relation#...>
+    scope :order_by_query, ->(order) { OrderSpace.new(self, order).scope }
+    scope :reverse_order_by_query, ->(order) { OrderSpace.new(self, order).reverse_scope }
+  end
+
+  def relative_order_by_query(scope = self.class.all, order)
+    RelativeOrder.new(self, scope, order)
+  end
+
+  module ClassMethods
+    protected
+    # @example
+    #   class Issue
+    #     order_query :order_display, [[:created_at, :desc], [:id, :desc]]
+    #   end
+    #
+    #   Issue.order_display #=> <ActiveRecord::Relation#...>
+    #   Issue.active.find(31).display_order(Issue.active).next  #=> <Issue#...>
+    def order_query(name, order)
+      scope name, -> { order_by_query(order) }
+      scope :"reverse_#{name}", -> { reverse_order_by_query(order) }
+      define_method(name) do |scope = nil|
+        scope ||= self.class.all
+        relative_order_by_query(scope, order)
+      end
+    end
+  end
+end

data/spec/order_query_spec.rb

@@ -0,0 +1,120 @@
+require 'spec_helper'
+
+class Issue < ActiveRecord::Base
+  DISPLAY_ORDER = [
+      [:priority, %w(high medium low)],
+      [:valid_votes_count, :desc, sql: '(votes - suspicious_votes)'],
+      [:updated_at, :desc],
+      [:id, :desc]
+  ]
+
+  def valid_votes_count
+    votes - suspicious_votes
+  end
+
+  include OrderQuery
+  order_query :display_order, DISPLAY_ORDER
+  order_query :id_order_asc, [[:id, :asc]]
+end
+
+def create_issue(options = {})
+  Issue.create!({priority: 'high', votes: 3, suspicious_votes: 0, updated_at: Time.now}.merge(options))
+end
+
+describe 'OrderQuery.order_query' do
+
+  t        = Time.now
+  datasets = [
+      [
+          ['high', 5, 0, t],
+          ['high', 5, 1, t],
+          ['high', 5, 1, t - 1.day],
+          ['medium', 10, 0, t],
+          ['medium', 10, 5, t - 12.hours],
+          ['low', 30, 0, t + 1.day]
+      ],
+      [
+          ['high', 5, 0, t],
+          ['high', 5, 1, t],
+          ['high', 5, 1, t - 1.day],
+          ['low', 30, 0, t + 1.day]
+      ],
+      [
+          ['high', 5, 1, t - 1.day],
+          ['low', 30, 0, t + 1.day]
+      ],
+  ]
+
+  datasets.each_with_index do |ds, i|
+    it "is ordered correctly (test data #{i})" do
+      issues = ds.map do |attr|
+        Issue.new(priority: attr[0], votes: attr[1], suspicious_votes: attr[2], updated_at: attr[3])
+      end
+      issues.reverse_each(&:save!)
+      expect(Issue.display_order.to_a).to eq(issues)
+      issues.each_slice(2) do |prev, cur|
+        cur ||= issues.first
+        expect(prev.display_order.next).to eq(cur)
+        expect(cur.display_order.previous).to eq(prev)
+        expect(cur.display_order.scope.count).to eq(Issue.count)
+        expect(cur.display_order.before.count + 1 + cur.display_order.after.count).to eq(cur.display_order.count)
+
+        expect(cur.display_order.before.to_a.reverse + [cur] + cur.display_order.after.to_a).to eq(Issue.display_order.to_a)
+      end
+    end
+  end
+
+  it '#next returns nil when there is only 1 record' do
+    p = create_issue.display_order
+    expect(p.next).to be_nil
+    expect(p.next(true)).to be_nil
+  end
+
+  it 'is ordered correctly for order query [[:id, :asc]]' do
+    a = create_issue
+    b = create_issue
+    expect(a.id_order_asc.next).to eq b
+    expect(b.id_order_asc.previous).to eq a
+    expect([a] + a.id_order_asc.after.to_a).to eq(Issue.id_order_asc.to_a)
+    expect(b.id_order_asc.before.reverse.to_a + [b]).to eq(Issue.id_order_asc.to_a)
+    expect(Issue.id_order_asc.count).to eq(2)
+  end
+
+  it '.order_by_query works on a list of ids' do
+    ids = (1..3).map { create_issue.id }
+    expect(Issue.order_by_query([[:id, ids]])).to have(ids.length).issues
+  end
+
+  it '.order_by_query preserves previous' do
+    create_issue(active: true)
+    expect(Issue.where(active: false).order_by_query([[:id, :desc]])).to have(0).records
+    expect(Issue.where(active: true).order_by_query([[:id, :desc]])).to have(1).record
+  end
+
+  it '#relative_order_by_query falls back to scope when order condition is missing self' do
+    a = create_issue(priority: 'medium')
+    b = create_issue(priority: 'high')
+    expect(a.relative_order_by_query(Issue.display_order, [[:priority, ['wontfix', 'askbob']], [:id, :desc]]).next).to eq(b)
+  end
+
+  before do
+    Issue.delete_all
+  end
+
+  before :all do
+    ActiveRecord::Schema.define do
+      self.verbose = false
+
+      create_table :issues do |t|
+        t.column :priority, :string
+        t.column :votes, :integer
+        t.column :suspicious_votes, :integer
+        t.column :announced_at, :datetime
+        t.column :updated_at, :datetime
+        t.column :active, :boolen, null: false, default: true
+      end
+    end
+
+    Issue.reset_column_information
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,16 @@
+# -*- encoding : utf-8 -*-
+# Configure Rails Environment
+ENV['RAILS_ENV'] = ENV['RACK_ENV'] = 'test'
+unless defined?(RUBY_ENGINE) && RUBY_ENGINE == 'rbx'
+  begin
+    require 'coveralls'
+    Coveralls.wear!
+  rescue LoadError
+    false
+  end
+end
+require 'order_query'
+
+Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each { |f| require f }
+
+ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')

metadata

@@ -0,0 +1,112 @@
+--- !ruby/object:Gem::Specification
+name: order_query
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Gleb Mazovetskiy
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-03-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  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: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email: glex.spb@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Gemfile
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/order_query.rb
+- lib/order_query/order_condition.rb
+- lib/order_query/order_space.rb
+- lib/order_query/relative_order.rb
+- lib/order_query/version.rb
+- spec/order_query_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/glebm/order_query
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.0
+signing_key: 
+specification_version: 4
+summary: Find next / previous record(s) in one query, for ActiveRecord
+test_files:
+- spec/order_query_spec.rb
+- spec/spec_helper.rb