order_query 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 04dd1e3cb69ac7b1cd363629e1449f2eec4bd921
-  data.tar.gz: 1d2533afcfea18fe8a1b06ac63dec068ef59cf8f
+  metadata.gz: 02a08c0101e3e15512098357d8e9159941b2606f
+  data.tar.gz: a11460b00d5f8e3dc16dc28f0fc264d4c17f1fef
 SHA512:
-  metadata.gz: f708515aa23195a7cb3051fca8848d1382190429ed9f2055cf0d0bc07b7b66b83c8792d5f1c3fdbbe6c7d3df2f62ec0571cc95755baeec621470c6464c838a05
-  data.tar.gz: 7650728e46013f47e129d9a4e939ef531c687bda7315f8326737d628f1b8bee509395a072c079e342d04e2e34640ea9cde5b4f504eed25625ee05082c61f0a3a
+  metadata.gz: 9e450de5cb30e692f068ae9551459879a3315c9feed3527809a50f82412954ce258a495f54bbefa18f04e1a823310fd1eba55d44caf1d623bb94ac7712e0f905
+  data.tar.gz: b2c92a65bdb70275836a7fede9c457056fdbb9ba7fe768a8fe3b5608790264dec600ad857f504135a7d465905fa3201d7c740f03b71546d68bbd8ea1e92090af

data/CHANGES.md

@@ -1,3 +1,8 @@
+## 0.3.0
+
+* `order_query` now accepts conditions as varargs. Array form is still supported.
+* `order_by` renamed to `seek`
+
 ## 0.2.1
 
 * `complete` now defaults to true for list attributes as well.

data/Gemfile

@@ -3,7 +3,7 @@ source 'https://rubygems.org'
 gemspec
 
 group :test, :development do
-  gem 'coveralls', require: false
+  gem 'codeclimate-test-reporter', group: :test, require: nil
   gem 'byebug', platform: :mri_21, require: false
 end
 

data/README.md

@@ -1,132 +1,143 @@
-# order_query [![Build Status][travis-badge]][travis] [![Code Climate][codeclimate-badge]][codeclimate] [![Coverage Status][coveralls-badge]][coveralls]
+# order_query [![Build Status][travis-badge]][travis] [![Code Climate][codeclimate-badge]][codeclimate] [![Coverage Status][coverage-badge]][coverage]
 
-order_query gives you next or previous records relative to the current one efficiently.
+<a href="http://use-the-index-luke.com/no-offset">
+  <img src="http://use-the-index-luke.com/img/no-offset.q200.png" alt="100% offset-free" align="right" width="106" height="106">
+</a>
 
-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.
+This gem finds the next or previous record(s) relative to the current one efficiently. It is also useful for implementing infinite scroll.
+It uses [keyset pagination](http://use-the-index-luke.com/no-offset) to achieve this.
 
 ## Installation
 
 Add to Gemfile:
 
 ```ruby
-gem 'order_query', '~> 0.2.1'
+gem 'order_query', '~> 0.3.0'
 ```
 
 ## Usage
 
-Define a list of order conditions with `order_query`:
+Define named order conditions with `order_query`:
 
 ```ruby
 class Post < ActiveRecord::Base
   include OrderQuery
-  order_query :order_for_index, [
+  order_query :order_home,
     [:pinned, [true, false]],
     [:published_at, :desc],
     [:id, :desc]
-  ]
 end
 ```
 
-An order condition is specified as an attribute name, optionally an ordered list of values, and a sort direction.
-Additional options are:
+Order query accepts a list of order conditions as varargs or one array, each one specified as:
+
+```ruby
+[<attribute name>, (attribute values in order), (:asc or :desc), (options hash)]
+```
+
+Available options:
 
 | option     | description                                                                |
 |------------|----------------------------------------------------------------------------|
 | unique     | Unique attribute. Default: `true` for primary key, `false` otherwise.      |
-| complete   | Enum attribute contains all the possible values. Default: `true`.          |
+| complete   | Specified attribute values are the only possible values. Default: `true`.  |
 | sql        | Customize attribute value SQL                                              |
 
-### Order scopes
 
-Order scopes are defined by `order_query`:
+### Scopes for `ORDER BY`
 
 ```ruby
-Post.order_for_index         #=> ActiveRecord::Relation<...>
-Post.reverse_order_for_index #=> ActiveRecord::Relation<...>
+Post.published.order_home         #=> #<ActiveRecord::Relation>
+Post.published.order_home_reverse #=> #<ActiveRecord::Relation>
 ```
 
-### Before, after, previous, and next
+### Before / after, previous / next, and position
 
-An method is added by `order_query` to query around a record:
+First, get an `OrderQuery::Point` for the record:
 
 ```ruby
-# get the order object, scope default: Post.all
-p = Post.find(31).order_for_index(scope) #=> OrderQuery::RelativeOrder<...>
-p.before         #=> ActiveRecord::Relation<...>
-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) #=> Post<...>
-p.position   #=> 5
-p.next       #=> Post<...>
-p.after      #=> ActiveRecord::Relation<...>
+p = Post.published.order_home_at(Post.find(31)) #=> #<OrderQuery::Point>
 ```
 
-#### Order conditions, advanced example
+It exposes these finder methods:
 
 ```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
+p.before   #=> #<ActiveRecord::Relation>
+p.after    #=> #<ActiveRecord::Relation>
+p.previous #=> #<Post>
+p.next     #=> #<Post>
+p.position #=> 5
+```
+
+Looping to the first / last record is enabled by default. Pass `false` to disable:
+
+```ruby
+p = Post.order_home_at(Post.order_home.first)
+p.previous        #=> #<Post>
+p.previous(false) #=> nil
 ```
 
-### Dynamic order conditions
+Even with looping, `nil` will be returned if there is only one record.
 
-To query with dynamic order conditions use `Model.order_by` and `Model#order_by`:
+You can also get an `OrderQuery::Point` from an instance and a scope:
 
 ```ruby
-Issue.order_by([[:id, :desc]])         #=> ActiveRecord::Relation<...>
-Issue.visible.reverse_order_by([[:id, :desc]]) #=> ActiveRecord::Relation<...>
-Issue.find(31).order_by([[:id, :desc]]).next #=> Issue<...>
-Issue.find(31).order_by(Issue.visible, [[:id, :desc]]).next #=> Issue<...>
+posts = Post.published
+post  = posts.find(42)
+post.order_home(posts) #=> #<OrderQuery::Point>
 ```
 
-For example, consider ordering by a list of ids returned from an elasticsearch query:
+### Dynamic conditions
+
+Query with dynamic order conditions using the `seek(*spec)` class method:
 
 ```ruby
-ids = Issue.keyword_search('ruby') #=> [7, 3, 5]
-Issue.where(id: ids).order_by([[:id, ids]]).first(2).to_a #=> [Issue<id=7>, Issue<id=3>]
+space = Post.visible.seek([:id, :desc]) #=> #<OrderQuery::Space>
 ```
 
-## How it works
+This returns an `OrderQuery::Space` that exposes these methods:
 
-Internally this gem builds a query that depends on the current record's order values and looks like:
+```ruby
+space.scope           #=> #<ActiveRecord::Relation>
+space.scope_reverse   #=> #<ActiveRecord::Relation>
+space.first           #=> scope.first
+space.last            #=> scope_reverse.first
+space.at(Post.first)  #=> #<OrderQuery::Point>
+```
 
-```sql
-SELECT ... WHERE
-x0 OR
-y0 AND (x1 OR
-        y1 AND (x2 OR
-                y2 AND ...))
-ORDER BY ...
-LIMIT 1
+Alternatively, get an `OrderQuery::Point` using the `seek(scope, *spec)` instance method:
+
+```ruby
+Post.find(42).seek(Post.visible, [:id, :desc]) #=> #<OrderQuery::Point>
+# scope defaults to Post.all
+Post.find(42).seek([:id, :desc]) #=> #<OrderQuery::Point>
+```
+
+#### Advanced options example
+
+```ruby
+class Post < ActiveRecord::Base
+  include OrderQuery
+  order_query :order_home,
+    # For an array of order values, default direction is :desc
+    # High-priority issues will be ordered first in this example
+    [:priority, %w(high medium low)],
+    # A method and custom SQL can be used instead of an attribute
+    [:valid_votes_count, :desc, sql: '(votes - suspicious_votes)'],
+    # Default sort order for non-array conditions is :asc, just like SQL
+    [:updated_at, :desc],
+    # pass unique: true for unique attributes to get more optimized queries
+    # unique is true by default for primary_key
+    [:id, :desc]
+  def valid_votes_count
+    votes - suspicious_votes
+  end
+end
 ```
 
-Where `x` correspond to `>` / `<` terms, and `y` to `=` terms (for resolving ties), per order criterion.
+## How it works
 
-A query may then look like this:
+Internally this gem builds a query that depends on the current record's values and looks like this:
 
 ```sql
 -- Current post: pinned=true published_at='2014-03-21 15:01:35.064096' id=9
@@ -142,32 +153,12 @@ ORDER BY
 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 (
-       (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
-```
-
 The actual query is a bit different because `order_query` wraps the top-level `OR` with a (redundant) non-strict condition `x0' AND (x0 OR ...)`
 for [performance reasons](https://github.com/glebm/order_query/issues/3).
 This can be disabled with `OrderQuery.wrap_top_level_or = false`.
 
+See the implementation in [sql/where.rb](/lib/order_query/sql/where.rb).
+
 See how this affects query planning in Markus Winand's slides on [Pagination done the Right Way](http://use-the-index-luke.com/blog/2013-07/pagination-done-the-postgresql-way).
 
 This project uses MIT license.
@@ -178,5 +169,5 @@ This project uses MIT license.
 [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
+[coverage]: https://codeclimate.com/github/glebm/order_query
+[coverage-badge]: https://codeclimate.com/github/glebm/order_query/badges/coverage.svg

data/lib/order_query/condition.rb

@@ -1,7 +1,10 @@
+# coding: utf-8
 require 'order_query/sql/condition'
 module OrderQuery
+  # An order condition (sort column)
   class Condition
-    attr_reader :name, :order, :order_enum, :options, :sql
+    attr_reader :name, :order, :order_enum, :options
+    delegate :column_name, :quote, to: :@sql
 
     # @option spec [String] :unique    Mark the attribute as unique to avoid redundant conditions
     # @option spec [String] :complete  Mark the condition's domain as complete to avoid redundant conditions (only for array conditions)
@@ -22,7 +25,7 @@ module OrderQuery
       )
       @unique   = @options[:unique]
       @complete = @options[:complete]
-      @sql = SQL::Condition.new(self, scope)
+      @sql      = SQL::Condition.new(self, scope)
     end
 
     def unique?
@@ -56,7 +59,15 @@ module OrderQuery
     end
 
     def inspect
-      "Condition(#{@name.inspect}#{" #{@order_enum.inspect}" if @order_enum} #{@order.to_s.upcase} #{'unique ' if @unique}#{@complete ? 'complete' : 'partial' if @order_enum})"
+      parts = [
+          @name,
+          (@order_enum.inspect if order_enum),
+          ('unique' if @unique),
+          ('complete' if order_enum && complete?),
+          (column_name if options[:sql]),
+          {desc: '▼', asc: '▲'}[@order]
+      ].compact
+      "(#{parts.join(' ')})"
     end
   end
 end

data/lib/order_query/point.rb

@@ -5,7 +5,7 @@ module OrderQuery
   # Search around a record in an order space
   class Point
     attr_reader :record, :space
-    delegate :scope, :reverse_scope, to: :space
+    delegate :first, :last, :count, to: :space
 
     # @param [ActiveRecord::Base] record
     # @param [OrderQuery::Space] space
@@ -15,26 +15,6 @@ module OrderQuery
       @where_sql = SQL::Where.new(self)
     end
 
-    # @return [ActiveRecord::Base]
-    def first
-      scope.first
-    end
-
-    # @return [ActiveRecord::Base]
-    def last
-      reverse_scope.first
-    end
-
-    # @return [Integer]
-    def count
-      @total ||= scope.count
-    end
-
-    # @return [Integer]
-    def position
-      count - after.count
-    end
-
     # @params [true, false] loop if true, consider last and first as adjacent (unless they are equal)
     # @return [ActiveRecord::Base]
     def next(loop = true)
@@ -46,6 +26,11 @@ module OrderQuery
       unless_record_eq before.first || (last if loop)
     end
 
+    # @return [Integer]
+    def position
+      space.count - after.count
+    end
+
     # @return [ActiveRecord::Relation]
     def after
       side :after
@@ -63,7 +48,7 @@ module OrderQuery
       scope = if side == :after
                 space.scope
               else
-                space.reverse_scope
+                space.scope_reverse
               end
       if query.present?
         scope.where(query, *query_args)
@@ -76,6 +61,10 @@ module OrderQuery
       record.send(cond.name)
     end
 
+    def inspect
+      "#<OrderQuery::Point @record=#{@record.inspect} @space=#{@space.inspect}>"
+    end
+
     protected
 
     # @param [ActiveRecord::Base] rec

data/lib/order_query/space.rb

@@ -3,28 +3,46 @@ require 'order_query/sql/order_by'
 module OrderQuery
   # Order specification and a scope
   class Space
-    # @return [Array<Condition>]
+    # @return [Array<OrderQuery::Condition>]
     attr_reader :conditions
-    # @return [ActiveRecord::Relation]
-    attr_reader :base_scope
 
-    # @param [ActiveRecord::Relation] scope
-    # @param [Array<Array<Symbol,String>>] order_spec
+    # @param [ActiveRecord::Relation] base_scope
+    # @param [Array<Array<Symbol,String>>, OrderQuery::Spec] order_spec
     def initialize(base_scope, order_spec)
       @base_scope   = base_scope
-      order_spec    = [order_spec] unless order_spec.empty? || order_spec.first.is_a?(Array)
-      @conditions   = order_spec.map { |spec| Condition.new(spec, base_scope) }
-      @order_by_sql = SQL::OrderBy.new(self)
+      @conditions   = order_spec.map { |cond_spec| Condition.new(cond_spec, base_scope) }
+      @order_by_sql = SQL::OrderBy.new(@conditions)
+    end
+
+    # @return [Point]
+    def at(record)
+      Point.new(record, self)
     end
 
     # @return [ActiveRecord::Relation] scope ordered by conditions
     def scope
-      @base_scope.order(@order_by_sql.build)
+      @scope ||= @base_scope.order(@order_by_sql.build)
     end
 
     # @return [ActiveRecord::Relation] scope ordered by conditions in reverse
-    def reverse_scope
-      @base_scope.order(@order_by_sql.build_reverse)
+    def scope_reverse
+      @scope_reverse ||= @base_scope.order(@order_by_sql.build_reverse)
+    end
+
+    # @return [ActiveRecord::Base]
+    def first
+      scope.first
+    end
+
+    # @return [ActiveRecord::Base]
+    def last
+      scope_reverse.first
+    end
+
+    delegate :count, :empty?, to: :@base_scope
+
+    def inspect
+      "#<OrderQuery::Space @conditions=#{@conditions.inspect} @base_scope=#{@base_scope.inspect}>"
     end
   end
 end

data/lib/order_query/sql/condition.rb

@@ -12,8 +12,7 @@ module OrderQuery
         @column_name ||= begin
           sql = condition.options[:sql]
           if sql
-            sql = sql.call if sql.respond_to?(:call)
-            sql
+            sql.respond_to?(:call) ? sql.call : sql
           else
             connection.quote_table_name(scope.table_name) + '.' + connection.quote_column_name(condition.name)
           end

data/lib/order_query/sql/order_by.rb

@@ -1,35 +1,33 @@
 module OrderQuery
   module SQL
     class OrderBy
-      attr_reader :space
-
       # @param [Array<Condition>]
-      def initialize(space)
-        @space = space
+      def initialize(conditions)
+        @conditions = conditions
       end
 
       # @return [String]
       def build
-        join_order_by_clauses order_by_sql_clauses
+        @sql ||= join_order_by_clauses order_by_sql_clauses
       end
 
       # @return [String]
       def build_reverse
-        join_order_by_clauses order_by_reverse_sql_clauses
+        @reverse_sql ||= join_order_by_clauses order_by_reverse_sql_clauses
       end
 
       protected
 
       # @return [Array<String>]
       def order_by_sql_clauses
-        space.conditions.map { |cond| condition_clause cond }
+        @conditions.map { |cond| condition_clause cond }
       end
 
       def condition_clause(cond)
         dir_sql = sort_direction_sql cond.order
-        col_sql = cond.sql.column_name
+        col_sql = cond.column_name
         if cond.order_enum
-          cond.order_enum.map { |v| "#{col_sql}=#{cond.sql.quote v} #{dir_sql}" }.join(', ').freeze
+          cond.order_enum.map { |v| "#{col_sql}=#{cond.quote v} #{dir_sql}" }.join(', ').freeze
         else
           "#{col_sql} #{dir_sql}".freeze
         end

data/lib/order_query/sql/where.rb

@@ -7,7 +7,8 @@ module OrderQuery
 
       # @param [OrderQuery::Point] point
       def initialize(point)
-        @point = point
+        @point      = point
+        @conditions = point.space.conditions
       end
 
       # Join condition pairs with OR, and nest within each other with AND
@@ -20,7 +21,7 @@ module OrderQuery
       #       ... ))
       def build(side)
         # generate pairs of terms such as sales < 5, sales = 5
-        parts = point.space.conditions.map { |cond|
+        parts = @conditions.map { |cond|
           [where_side(cond, side, true), where_tie(cond)].reject { |x| x == WHERE_IDENTITY }
         }
         # group pairwise with OR, and nest with AND
@@ -66,7 +67,7 @@ module OrderQuery
         top_pair_idx = pairs.index(&:present?)
         if top_pair_idx &&
             (top_pair = pairs[top_pair_idx]).length == 2 &&
-            top_pair.first != (redundant_cond = where_side(point.space.conditions[top_pair_idx], side, false))
+            top_pair.first != (redundant_cond = where_side(@conditions[top_pair_idx], side, false))
           join_terms 'AND'.freeze, redundant_cond, wrap_term_with_parens(query)
         else
           query
@@ -104,19 +105,19 @@ module OrderQuery
           when 1
             where_eq cond, values[0]
           else
-            ["#{cond.sql.column_name} IN (?)".freeze, [values]]
+            ["#{cond.column_name} IN (?)".freeze, [values]]
         end
       end
 
       def where_eq(cond, value = point.value(cond))
-        [%Q(#{cond.sql.column_name} = ?).freeze, [value]]
+        [%Q(#{cond.column_name} = ?).freeze, [value]]
       end
 
       def where_ray(cond, from, mode, strict = true)
         ops = %w(< >)
         ops = ops.reverse if mode == :after
         op  = {asc: ops[0], desc: ops[1]}[cond.order || :asc]
-        ["#{cond.sql.column_name} #{op}#{'=' unless strict} ?".freeze, [from]]
+        ["#{cond.column_name} #{op}#{'=' unless strict} ?".freeze, [from]]
       end
 
       WHERE_IDENTITY = [''.freeze, [].freeze].freeze

data/lib/order_query/version.rb

@@ -1,3 +1,3 @@
 module OrderQuery
-  VERSION = '0.2.1'
+  VERSION = '0.3.0'
 end

data/lib/order_query.rb

@@ -6,20 +6,28 @@ require 'order_query/point'
 module OrderQuery
   extend ActiveSupport::Concern
 
-  # @param [ActiveRecord::Relation] scope
-  # @param [Array<Array<Symbol,String>>] order_spec
-  def order_by(scope = nil, order_spec)
+  # @param [ActiveRecord::Relation] scope optional first argument (default: self.class.all)
+  # @param [Array<Array<Symbol,String>>, OrderQuery::Spec] order_spec
+  # @return [OrderQuery::Point]
+  # @example
+  #   users = User.active
+  #   user  = users.find(42)
+  #   next_user = user.seek(users, [:activated_at, :desc], [:id, :desc]).next
+  def seek(*spec)
+    fst = spec.first
+    if fst.nil? || fst.is_a?(ActiveRecord::Relation) || fst.is_a?(ActiveRecord::Base)
+      scope = spec.shift
+    end
     scope ||= self.class.all
-    Point.new(self, Space.new(scope, order_spec))
+    scope.seek(*spec).at(self)
   end
 
   module ClassMethods
-    def order_by(order_spec)
-      Space.new(self, order_spec).scope
-    end
-
-    def reverse_order_by(order_spec)
-      Space.new(self, order_spec).reverse_scope
+    # @return [OrderQuery::Space]
+    def seek(*spec)
+      # allow passing without a splat, as we can easily distinguish
+      spec = spec.first if spec.length == 1 && spec.first.first.is_a?(Array)
+      Space.new(all, spec)
     end
 
     #= DSL
@@ -27,18 +35,46 @@ module OrderQuery
     # @param [Symbol] name
     # @param [Array<Array<Symbol,String>>] order_spec
     # @example
-    #   class Issue
-    #     order_query :order_display, [[:created_at, :desc], [:id, :desc]]
+    #   class Post < ActiveRecord::Base
+    #     include OrderQuery
+    #     order_query :order_home,
+    #                [:pinned, [true, false]]
+    #                [:published_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_spec)
-      scope name, -> { order_by(order_spec) }
-      scope :"reverse_#{name}", -> { reverse_order_by(order_spec) }
-      define_method name do |scope = nil|
-        order_by scope, order_spec
-      end
+    #== Scopes
+    #   .order_home
+    #     #<ActiveRecord::Relation...>
+    #   .order_home_reverse
+    #     #<ActiveRecord::Relation...>
+    #
+    #== Class methods
+    #   .order_home_at(post)
+    #     #<OrderQuery::Point...>
+    #   .order_home_space
+    #     #<OrderQuery::Space...>
+    #
+    #== Instance methods
+    #   .order_home(scope)
+    #     #<OrderQuery::Point...>
+    def order_query(name, *spec)
+      space_method = :"#{name}_space"
+      define_singleton_method space_method, -> {
+        seek(*spec)
+      }
+      scope name, -> {
+        send(space_method).scope
+      }
+      scope :"#{name}_reverse", -> {
+        send(space_method).scope_reverse
+      }
+      define_singleton_method "#{name}_at", -> (record) {
+        send(space_method).at(record)
+      }
+      define_method(name) { |scope = nil|
+        (scope || self.class).send(space_method).at(self)
+      }
     end
   end
 

data/spec/order_query_spec.rb

@@ -8,11 +8,10 @@ end
 # Simple model
 class Post < ActiveRecord::Base
   include OrderQuery
-  order_query :order_list, [
-      [:pinned, [true, false], complete: true],
-      [:published_at, :desc],
-      [:id, :desc]
-  ]
+  order_query :order_list,
+              [:pinned, [true, false], complete: true],
+              [:published_at, :desc],
+              [:id, :desc]
 end
 
 def create_post(attr = {})
@@ -94,7 +93,7 @@ describe 'OrderQuery' do
               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.space.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)
@@ -118,21 +117,54 @@ describe 'OrderQuery' do
           expect(Issue.id_order_asc.count).to eq(2)
         end
 
-        it '.order_by works on a list of ids' do
-          ids = (1..3).map { create_issue.id }
-          expect(Issue.order_by([[:id, ids]]).size).to eq ids.length
+        it '.seek works on a list of ids' do
+          ids = 3.times.map { create_issue.id }
+          expect(Issue.seek([[:id, ids]]).scope.count).to eq ids.length
+          expect(Issue.seek([:id, ids]).scope.count).to eq ids.length
         end
 
-        it '.order_by preserves previous' do
-          create_issue(active: true)
-          expect(Issue.where(active: false).order_by([[:id, :desc]])).to be_empty
-          expect(Issue.where(active: true).order_by([[:id, :desc]]).size).to eq 1
+        context 'partitioned on a boolean flag' do
+          before do
+            create_issue(active: true)
+            create_issue(active: false)
+            create_issue(active: true)
+          end
+
+          let!(:order) { [[:id, :desc]] }
+          let!(:active) { Issue.where(active: true).seek(order) }
+          let!(:inactive) { Issue.where(active: false).seek(order) }
+
+          it '.seek preserves scope' do
+            expect(inactive.scope.count).to eq 1
+            expect(inactive.count).to eq 1
+            expect(active.count).to eq 2
+            expect(active.scope.count).to eq 2
+          end
+
+          it 'gives a valid result if at argument is outside of the space' do
+            expect(inactive.at(active.first).next).to_not be_active
+            expect(inactive.at(active.last).next).to_not be_active
+            expect(active.at(inactive.first).next).to be_active
+            expect(active.at(inactive.last).next).to be_active
+          end
+
+          it 'next/previous(false)' do
+            expect(active.at(active.first).next(false)).to_not be_nil
+            expect(active.at(active.last).next(false)).to be_nil
+            expect(inactive.at(inactive.first).previous(false)).to be_nil
+            # there is only one, so previous(last) is also nil
+            expect(inactive.at(inactive.last).previous(false)).to be_nil
+          end
+
+          it 'previous(true) with only 1 record' do
+            expect(inactive.at(inactive.last).previous(true)).to be_nil
+          end
         end
 
-        it '#order_by falls back to scope when order condition is missing self' do
+        it '#seek falls back to scope when order condition is missing self' do
           a = create_issue(priority: 'medium')
           b = create_issue(priority: 'high')
-          expect(a.order_by(Issue.display_order, [[:priority, ['wontfix', 'askbob']], [:id, :desc]]).next).to eq(b)
+          expect(a.seek(Issue.display_order, [[:priority, ['wontfix', 'askbob']], [:id, :desc]]).next).to eq(b)
         end
 
         before do
@@ -149,7 +181,7 @@ describe 'OrderQuery' do
               t.column :suspicious_votes, :integer
               t.column :announced_at, :datetime
               t.column :updated_at, :datetime
-              t.column :active, :boolen, null: false, default: true
+              t.column :active, :boolean, null: false, default: true
             end
           end
 
@@ -197,7 +229,7 @@ describe 'OrderQuery' do
     context 'wrap top-level OR on' do
       wrap_top_level_or true
       it 'wraps top-level OR' do
-        after_scope = User.create!(updated_at: Date.parse('2014-09-06')).order_by([[:updated_at, :desc], [:id, :desc]]).after
+        after_scope = User.create!(updated_at: Date.parse('2014-09-06')).seek([[:updated_at, :desc], [:id, :desc]]).after
         expect(after_scope.to_sql).to include('<=')
       end
     end
@@ -205,7 +237,7 @@ describe 'OrderQuery' do
     context 'wrap top-level OR off' do
       wrap_top_level_or false
       it 'does not wrap top-level OR' do
-        after_scope = User.create!(updated_at: Date.parse('2014-09-06')).order_by([[:updated_at, :desc], [:id, :desc]]).after
+        after_scope = User.create!(updated_at: Date.parse('2014-09-06')).seek([[:updated_at, :desc], [:id, :desc]]).after
         expect(after_scope.to_sql).to_not include('<=')
       end
     end

data/spec/spec_helper.rb

@@ -1,13 +1,9 @@
 # -*- 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
+if ENV['TRAVIS'] && !(defined?(RUBY_ENGINE) && RUBY_ENGINE == 'rbx')
+  require 'codeclimate-test-reporter'
+  CodeClimate::TestReporter.start
 end
 require 'order_query'
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: order_query
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Gleb Mazovetskiy
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-09-06 00:00:00.000000000 Z
+date: 2014-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord