order_query 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6d9ac479b13db9c6531719b51bca15d8079b2b37
-  data.tar.gz: 1c9e90573f1cf98650bdf2d2de5d9969e10ce5fb
+  metadata.gz: 2e1364db02e6ba3b3d20bf11d77103dc33a1d287
+  data.tar.gz: 70f8f66433ef24caebe56b83a165073ac7377f88
 SHA512:
-  metadata.gz: 38e902e5c4804d578d6b4817e9b428c4eb295f3fa87d6cf11efae6592630594f7df2d036c1242766ded5f5d58c703a7f01689d60332be0ef5c0bfe2da375f5e3
-  data.tar.gz: c7830348c5d536abd766fbd9d9834f3359a09f110c62bef57a69a74d4d7ee23f0b08df55650a1abf00247ea675d099d0afe6f5f2b93f4938a1544d66750451cf
+  metadata.gz: 2ea5b0e8beb0268407ce15504ce0d57200c41fe4f059782c220c7c2b84c40205dd12123eb61f67e9b01d1c287b836123424ae6925d585142bea19b0077d2cf78
+  data.tar.gz: 3a9dc43bab64321c33f27d2869f895cb36efab27fea662919e61a49d7454863fef8c83ee16a50350b6beb789b51f86936b80636ecac4dfdf1b948a44ce4b0057

data/CHANGES.md

@@ -0,0 +1,7 @@
+## 0.1.1
+
+* `#next(true)` and `#previous(true)` return nil if there is only one record in total.
+
+## 0.1.0
+
+Initial release

data/README.md

@@ -1,54 +1,94 @@
 # 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.
+order_query gives you next or previous records relative to the current one efficiently.
+
+For example, you have a list of items, sorted by priority. You have 10,000 items!
+If you are showing the user a single item, how do you provide buttons for the user to see the previous item or the next item?
+
+You could pass the item's position to the item page and use `OFFSET` in your SQL query.
+The downside of this, apart from having to pass a number that may change, is that the database cannot jump to the offset; it has to read every record until it reaches, say, the 9001st record.
+This is slow. Here is where `order_query` comes in!
+
+`order_query` uses the same `ORDER BY` query, but also includes a `WHERE` clause that excludes records before (for next) or after (for prev) the current one.
+
+## Installation
+
+Add to Gemfile:
 
 ```ruby
-gem 'order_query', '~> 0.1.0'
+gem 'order_query', '~> 0.1.1'
 ```
 
 ## Usage
 
+Define the criteria with `order_query`:
+
 ```ruby
-class Issue < ActiveRecord::Base
+class Post < 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]
+  order_query :order_list, [
+    [:pinned, [true, false]],
+    [:published_at, :desc],
+    [:id, :desc]
   ]
-  def valid_votes_count
-    votes - suspicious_votes
-  end
 end
 ```
 
-Order scopes:
+### Order scopes
+
+Defining the criteria adds `ORDER BY` scopes:
 
 ```ruby
-Issue.order_display         #=> ActiveRecord::Relation<...>
-Issue.reverse_order_display #=> ActiveRecord::Relation<...>
+Post.order_list #=> ActiveRecord::Relation<...>
+Post.reverse_order_list #=> ActiveRecord::Relation<...>
 ```
 
-Relative order:
+### Relative order
+
+`order_query` also adds an instance method for querying relative to the record:
 
 ```ruby
-# get the order object, scope default: Issue.all
-p = Issue.find(31).order_display(scope)
+# get the order object, scope default: Post.all
+p = Post.find(31).order_list(scope) #=> OrderQuery::RelativeOrder<...>
 p.before         #=> ActiveRecord::Relation<...>
-p.previous       #=> Issue<...>
+p.previous       #=> Post<...>
 # 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.previous(true) #=> Post<...>
 p.position   #=> 5
-p.next       #=> Issue<...>
+p.next       #=> Post<...>
 p.after      #=> ActiveRecord::Relation<...>
 ```
 
-`order_query` defines methods that call `.order_by_query` and `#relative_order_by_query`, also public:
+### Advanced options
+
+There is a number of advanced options to help you:
+
+```ruby
+class Issue < ActiveRecord::Base
+  include OrderQuery
+  order_query :order_display, [
+    # Pass an array for attribute order, and an optional sort direction for the array,
+    # default is *:desc*, so that first in the array <=> first in the result
+    [:priority, %w(high medium low), :desc],
+    # Sort attribute can be a method name, provided you pass :sql for the attribute
+    [:valid_votes_count, :desc, sql: '(votes - suspicious_votes)'],
+    # Default sort order for non-array attributes is :asc, just like SQL
+    [: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
+```
+
+### Dynamic criteria
+
+Including `OrderQuery` adds `.order_by_query` and `#relative_order_by_query`.
+These methods can be called directly directly with the order criteria:
 
 ```ruby
 Issue.order_by_query([[:id, :desc]])         #=> ActiveRecord::Relation<...>
@@ -57,6 +97,14 @@ Issue.find(31).relative_order_by_query([[:id, :desc]]).next #=> Issue<...>
 Issue.find(31).relative_order_by_query(Issue.visible, [[:id, :desc]]).next #=> Issue<...>
 ```
 
+This is especially helpful if the order criteria is dynamic, so `order_query` cannot be used to define them beforehand.
+For example, consider ordering by a list of ids returned from an elasticsearh query:
+
+```ruby
+ids = Issue.keyword_search('ruby') #=> [7, 3, 5]
+Issue.where(id: ids).order_by_query([[:id, ids]]).to_a #=> [Issue<id=7>, Issue<id=3>, Issue<id=5>]
+```
+
 ## How it works
 
 Internally this gem builds a query that depends on the current record's order values and looks like:
@@ -73,9 +121,25 @@ 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):
+A query may then look like this:
+
+```sql
+-- Current post: pinned=true published_at='2014-03-21 15:01:35.064096' id=9
+SELECT "posts".* FROM "posts"  WHERE
+  ("posts"."pinned" = 'f' OR
+   "posts"."pinned" = 't' AND (
+      "posts"."published_at" < '2014-03-21 15:01:35.064096' OR
+      "posts"."published_at" = '2014-03-21 15:01:35.064096' AND "posts"."id" < 9))
+ORDER BY
+  "posts"."pinned"='t' DESC,
+  "posts"."pinned"='f' DESC, "posts"."published_at" DESC, "posts"."id" DESC
+LIMIT 1
+```
+
+A query for the advanced example would look like this:
 
 ```sql
+-- Current issue: priority='high' (votes - suspicious_votes)=4 updated_at='2014-03-19 10:23:18.671039' id=9
 SELECT  "issues".* FROM "issues"  WHERE
   ("issues"."priority" IN ('medium','low') OR
    "issues"."priority" = 'high' AND (

data/lib/order_query/relative_order.rb

@@ -129,7 +129,11 @@ module OrderQuery
                       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]]
+        if sort_values.length == 1
+          ["#{attr.col_name_sql} = ?", [sort_values]]
+        else
+          ["#{attr.col_name_sql} IN (?)", [sort_values]]
+        end
       else
         # ord is :asc or :desc
         op = {before: {asc: '<', desc: '>'}, after: {asc: '>', desc: '<'}}[mode][ord || :asc]

data/lib/order_query/version.rb

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

data/spec/order_query_spec.rb

@@ -1,5 +1,20 @@
 require 'spec_helper'
 
+# Simple example
+class Post < ActiveRecord::Base
+  include OrderQuery
+  order_query :order_list, [
+      [:pinned, [true, false]],
+      [:published_at, :desc],
+      [:id, :desc]
+  ]
+end
+
+def create_post(attr = {})
+  Post.create!({pinned: false, published_at: Time.now}.merge(attr))
+end
+
+# Advanced example
 class Issue < ActiveRecord::Base
   DISPLAY_ORDER = [
       [:priority, %w(high medium low)],
@@ -17,104 +32,133 @@ class Issue < ActiveRecord::Base
   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))
+def create_issue(attr = {})
+  Issue.create!({priority: 'high', votes: 3, suspicious_votes: 0, updated_at: Time.now}.merge(attr))
 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)
+  context 'Issue test model' 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
-  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 '#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 '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 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 '.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
+    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 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
+    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
+
+  context 'Post test model' do
+    it '#next works' do
+      p1 = create_post(pinned: true)
+      o1 = p1.order_list
+      expect(o1.next).to be_nil
+      expect(o1.next(true)).to be_nil
+      p2 = create_post(pinned: false)
+      o2 = p2.order_list
+      expect(o1.next(false)).to eq(p2)
+      expect(o2.next(false)).to be_nil
+      expect(o2.next(true)).to eq(p1)
     end
 
-    Issue.reset_column_information
+    before do
+      Post.delete_all
+    end
+    before :all do
+      ActiveRecord::Schema.define do
+        self.verbose = false
+        create_table :posts do |t|
+          t.boolean :pinned
+          t.datetime :published_at
+        end
+      end
+    end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: order_query
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Gleb Mazovetskiy
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-03-19 00:00:00.000000000 Z
+date: 2014-03-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -42,36 +42,37 @@ dependencies:
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '2.14'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
+        version: '10.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '0'
-description: 
+        version: '10.2'
+description: Find next / previous Active Record(s) in one efficient query
 email: glex.spb@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGES.md
 - Gemfile
 - MIT-LICENSE
 - README.md
@@ -86,7 +87,8 @@ files:
 homepage: https://github.com/glebm/order_query
 licenses:
 - MIT
-metadata: {}
+metadata:
+  issue_tracker: https://github.com/glebm/order_query
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -106,7 +108,7 @@ rubyforge_project:
 rubygems_version: 2.2.0
 signing_key: 
 specification_version: 4
-summary: Find next / previous record(s) in one query, for ActiveRecord
+summary: Find next / previous Active Record(s) in one query
 test_files:
 - spec/order_query_spec.rb
 - spec/spec_helper.rb