page_cursor 1.0.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 932517a4e798874d1d618d79ec7d96957a27997e3bcf7b755a8922e13b1d6563
-  data.tar.gz: a4e27daca15f4d1f4fc83a8dbd467de05e35319e0ddfefdfa5495cd54371783e
+  metadata.gz: bc17e3a2f1646fe6cd177515fc81cd3bd67877e26562938780249532a6c3f75c
+  data.tar.gz: bd134f3c437cdc8ed21e4f2fde253bdbd319e4941b2ddb4bafe839f1da35e498
 SHA512:
-  metadata.gz: 56a5c40258fc216d7dbcaf61e44514f400f5dc2e52d9cfa81020e5f4b6a3e587f806c7ff29c62e1d7c6ad4d57ba57aebcf614b2e714ce9d2e61442dac1174e41
-  data.tar.gz: d49481ae21e0667fef99733800187caaed9dbecbcb173de4e42bf762cefd138015aa299ef345e198070963ee6d79865c7043bb45656a8f1a45c1a90272f4b20b
+  metadata.gz: 311d31e985abf64c5a7ba7471554bc33d80bbeec415938f2d18e018c4e91f26698214887f80b9d113f3ccf4ab357d2b63e6c7b7fa9b8c2baa7ef132011d4a1bb
+  data.tar.gz: 6d354c73561bd0f8d18d76016d8b68b37181ae33ea94830ff37792f58f8108ba991bf30a2961d3d912fb511f9047dc6a0bd5e3468c66b19a63bc9e6d30ca9e6b

data/README.md

@@ -1,15 +1,25 @@
 # page_cursor
 
-Cursor-based pagination for Rails.
-
 ```ruby
 gem 'page_cursor'
 ```
 
+Cursor-based pagination for Rails.
+
+* Does not use `OFFSET/LIMIT` queries.
+* Cursors are primary keys, i.e. `{before: "<pk>", after: "<pk>"}` and are expected to be present as
+  `params[:after]` and/or `params[:before]`.
+  Primary keys must be unique and __sortable__.
+* Multiple columns can be used for ordering (see examples below).
+
+Works great in combination with [KSUID](https://github.com/mattes/ksuid-ruby)s as primary keys, but
+any other sortable key will do.
+
+
 ## Usage
 
 ```ruby
-@cursor, @records = paginate(User.where(active: true)) # in controller
+@cursor, @users = paginate(User.where(active: true)) # in controller
 
 <%= pagination_nav @cursor %> # in view
 ```
@@ -18,3 +28,33 @@ Please note that you'll have to create the `pagination_nav` helper yourself. Hav
 at an [example helper](test/dummy/app/helpers/application_helper.rb) with its rendered
 [example partial](test/dummy/app/views/layouts/_pagination_nav.html.erb).
 
+## More examples
+
+```ruby
+# Example 1
+@users = User.where(active: true)
+@cursor, @users = paginate(@users, limit: 25)
+
+# Example 2
+@cursor, @users = paginate(User)
+
+# Example 3
+@users = User.where(active: true)
+@cursor, @users = paginate(@users, :desc) # order primary key descending (defaults to :asc)
+
+# Example 4
+@users = User.where(active: true).order(:city => :desc)
+@cursor, @users = paginate(@users)
+
+# Example 5
+@users = User.where(active: true).order(:lastname => :asc, :firstname => :asc, :city => :desc)
+@cursor, @users = paginate(@users, :desc) # :desc orders primary key descending
+
+# Example 6 - change position of primary key in sort order
+@users = User.where(active: true).order(:city => :asc, :id => :desc, :city => :asc)
+@cursor, @users = paginate(@users)
+
+# Example 7
+@cursor, @users = paginate(User, primary_key: "custom")
+```
+

data/lib/page_cursor/cursor.rb

@@ -4,63 +4,259 @@ module PageCursor
     # It uses params[:after] and params[:before] request variables.
     # It assumes @record's primary key is sortable.
     #
-    # Example usage:
-    # ```
-    # @cursor, @records = paginate(@records) # in controller
-    # <%= pagination_nav @cursor %>          # in view
-    # ```
-    #
-    # @cursor is a hash returning the next (`after`)
-    # and previous (`before`) primary key, if more records are available.
-    #
-    # Caveat: All collection's order statements are overwritten by paginate.
-    def paginate(collection, direction = :asc, limit = 10)
-      fail "direction must be :asc or :desc" unless [:asc, :desc].include?(direction)
-      fail "limit must be >= 1" unless limit >= 1
-
-      after = params[:after]
-      before = params[:before]
-      fail "only provide one, either params[:after] or params[:before]" if after.present? && before.present?
-
-      # reference the table's primary key attribute
-      pk = collection.arel_table[collection.primary_key]
-
-      # return limit + 1 to see if there are more records
-      collection = collection.limit(limit + 1)
-
-      if after.present?
-        if direction == :asc
-          collection = collection.where(pk.send("gt", after)).reorder(pk.send(:asc))
-        elsif direction == :desc
-          collection = collection.where(pk.send("lt", after)).reorder(pk.send(:desc))
+    # opts[:primary_key] = string
+    # opts[:limit] = n
+    def paginate(c, direction = nil, **opts)
+      opts.symbolize_keys!
+      limit = opts[:limit]&.to_i || 10
+
+      raise ArgumentError, "direction must be either nil, :asc or :desc" unless [nil, :asc, :desc].include?(direction)
+      raise ArgumentError, "limit must be >= 1" unless limit >= 1
+      raise ArgumentError, "only provide one, either params[:after] or params[:before]" if params[:after].present? && params[:before].present?
+
+      # make sure we have a primary key
+      pk_name = (opts[:primary_key] || c.primary_key).to_s
+      if !c.column_names.include?(pk_name)
+        if opts[:primary_key].present?
+          raise ArgumentError, "column '#{opts[:primary_key]}' does not exist in table '#{c.table_name}'"
+        else
+          raise "table '#{c.table_name}' has no primary key"
+        end
+      end
+
+      # reference the table's primary key
+      pk = c.arel_table[pk_name]
+      raise ArgumentError, "expect primary key to be Arel::Attributes:Attribute instead of #{pk.class}" unless pk.is_a?(Arel::Attributes::Attribute)
+
+      # set cursor to :after/:before and the according pk_value from the params
+      cursor = nil
+      pk_value = nil
+      if params[:after].present?
+        cursor = :after
+        pk_value = params[:after]
+      elsif params[:before].present?
+        cursor = :before
+        pk_value = params[:before]
+      end
+
+      # always fetch limit + 1 to see if there are more records
+      c = c.limit(limit + 1)
+
+      all = []
+
+      # check if c already has one or more order directives set
+      unless already_has_order?(c)
+        # easy, no existing order directives, we'll just order by our primary key
+        comparison, order, reverse = ordering(direction || :asc, cursor)
+        c = c.where(pk.send(comparison, pk_value)) if comparison
+        c = c.reorder(pk.send(order)).all
+        c = c.reverse if reverse
+        all = c.to_a
+      else
+        # collection has order directives, we need to do a bit more work ...
+
+        # replace existing order with new one
+        c = reorder(c, cursor, pk, direction || :asc)
+
+        # if a cursor is given, we need to fetch its row from the database
+        # so that we can use the row's values for our where conditions.
+        unless cursor.nil?
+          row = find!(c, pk_name, pk_value)
+          c = where(c, cursor, row)
+        end
+
+        all = c.all.to_a
+        all = all.reverse if cursor == :before
+      end
+
+      has_more = all.size <= limit ? false : true
+
+      # return new after/before cursor and all results if there are no more results to expect after this
+      unless has_more
+        if cursor.nil?
+          return { :after => nil, :before => nil }, all # first and only page, no afters/befores
+        elsif cursor == :after
+          return { :after => nil, :before => all.first&.read_attribute(pk_name) }, all  # last page, no afters
+        elsif cursor == :before
+          return { :after => all.last&.read_attribute(pk_name), :before => nil }, all  # last page, no befores
+        end
+      end
+
+      # return new after/before cursors and all results if there are more results to expect
+      if cursor == :before
+        all = all.last(all.size - 1)
+      else
+        all = all.first(all.size - 1)
+      end
+
+      if cursor.nil?
+        return { :after => all.last&.read_attribute(pk_name), :before => nil }, all # first page, continue after
+      elsif cursor == :after
+        return { :after => all.last&.read_attribute(pk_name), :before => all.first&.read_attribute(pk_name) }, all
+      elsif cursor == :before
+        return { :after => all.last&.read_attribute(pk_name), :before => all.first&.read_attribute(pk_name) }, all
+      end
+
+      fail "never" # safeguard if cursor has a weird value
+    end
+
+    private
+
+    # order = :asc|:desc
+    # cursor = nil|:after|:before
+    # returns comparison, order, reverse
+    def ordering(order, cursor)
+      raise ArgumentError, "'#{order}' must be either :asc or :desc" unless [:asc, :desc].include?(order)
+      raise ArgumentError, "'#{cursor}' must be either nil, :after or :before" unless [nil, :after, :before].include?(cursor)
+
+      if order == :asc
+        if cursor.nil?
+          return nil, :asc, false # asc - nil
+        elsif cursor == :after
+          return :gt, :asc, false # asc - after
+        else
+          return :lt, :desc, true # asc - before
+        end
+      else
+        if cursor.nil?
+          return nil, :desc, false # desc - nil
+        elsif cursor == :after
+          return :lt, :desc, false # desc - after
+        else
+          return :gt, :asc, true # desc - before
+        end
+      end
+    end
+
+    # reorder applies a new ordering to the collection considering
+    # the cursor's :after or :before value
+    def reorder(collection, cursor, pk, pk_direction)
+      x = []
+      collection.order_values.each do |v|
+        if cursor == :after || cursor.nil?
+          x << v
+        elsif cursor == :before
+          x << v.reverse
+        end
+      end
+
+      # also add our primary key, if it's not yet included in the existing order directives
+      unless order_includes_pk?(collection, pk)
+        if cursor == :after || cursor.nil?
+          x << pk.send(pk_direction)
+        elsif cursor == :before
+          x << pk.send(pk_direction).reverse
         end
-        r = collection.all
-
-        return { :after => nil, :before => r.first&.id }, r if r.size <= limit
-        r = r.first(r.size - 1)
-        return { :after => r.last&.id, :before => r.first&.id }, r
-
-        # ---
-      elsif before.present?
-        if direction == :asc
-          collection = collection.where(pk.send("lt", before)).reorder(pk.send(:desc))
-        elsif direction == :desc
-          collection = collection.where(pk.send("gt", before)).reorder(pk.send(:asc))
+      end
+
+      collection.reorder(x)
+    end
+
+    # where returns a where clause which finds a row in an ordered collection
+    def where(collection, cursor, row)
+      parts = []
+      values = []
+
+      # recursively build where query elements
+      i = collection.order_values.count
+      while i > 0
+        i -= 1
+        subparts = []
+
+        last = collection.order_values[i]
+        chain = i > 0 ? collection.order_values.first(i) : []
+
+        # iterate through and build elements from chain
+        chain.each do |v|
+          table_name, col_name = extract_column(v)
+          quoted_col = quote(table_name, col_name)
+          subparts << "#{quoted_col} = ?"
+          values << row[col_name]
         end
-        r = collection.all.reverse
 
-        return { :after => r.last&.id, :before => nil }, r if r.size <= limit
-        r = r.last(r.size - 1)
-        return { :after => r.last&.id, :before => r.first&.id }, r
+        # build last element
+        table_name, col_name = extract_column(last)
+        quoted_col = quote(table_name, col_name)
+        last = last.reverse if cursor == :before # reverse the reverse from reordering
+        comparison, _, _ = ordering(last.direction, cursor)
+        comparison_str = comparison_to_s(comparison)
+        subparts << "#{quoted_col} #{comparison_str} ?"
+        values << row[col_name]
+
+        # merge subparts into all parts
+        parts << "(" + subparts.join(" AND ") + ")"
+      end
+
+      # build final where clause
+      query = parts.join(" OR ")
+      collection.where(values.prepend(query))
+    end
+
+    def find!(collection, pk_name, pk_value)
+      collection.reorder(nil).rewhere(pk_name => pk_value).take!
+    end
 
-        # ---
+    def quote(table, column)
+      raise ArgumentError, "column can't be blank" if column.blank?
+      c = ActiveRecord::Base.connection
+      if table.present?
+        c.quote_table_name(table.to_s) + "." + c.quote_column_name(column.to_s)
       else
-        # if after and before are both missing
-        r = collection.reorder(pk.send(direction)).all
-        return { :after => nil, :before => nil }, r if r.size <= limit
-        r = r.first(r.size - 1)
-        return { :after => r.last&.id, :before => nil }, r
+        c.quote_column_name(column.to_s)
       end
     end
+
+    # extract_column returns table_name and column_name for order directive
+    def extract_column(v)
+      if v.is_a? String
+        # TODO We can't reliably parse table_name and column_name from string syntax?
+        raise ArgumentError, "order(string) syntax is not supported"
+      end
+
+      if v.is_a?(Arel::Nodes::Ascending) || v.is_a?(Arel::Nodes::Descending)
+        val = v.value
+
+        if val.is_a?(Arel::Nodes::NamedFunction)
+          if val.expressions && val.expressions.size > 0
+            raise ArgumentError, "only one expression supported for #{val.class}" if val.expressions.size > 1 # TODO can we support more?
+            x = val.expressions[0]
+            if x.is_a?(Arel::Attributes::Attribute)
+              return x.relation.table_name.to_s, x.name.to_s
+            end
+          end
+        end
+
+        if val.is_a?(Arel::Attributes::Attribute)
+          return val.relation.table_name.to_s, val.name.to_s
+        end
+      end
+
+      raise ArgumentError, "unsupported type '#{v.class}' for order directive '#{v}'"
+    end
+
+    # order_includes_pk returns true if collection's order directives contain pk
+    def order_includes_pk?(collection, pk)
+      raise ArgumentError, "nil primary key" if pk == nil
+      raise ArgumentError, "missing table or column name for primary key" if pk.name.blank? || pk.relation.table_name.blank?
+
+      collection.order_values.each do |v|
+        table_name, col_name = extract_column(v)
+        raise ArgumentError, "unable to extract table and column name from #{v}" if table_name.blank? || col_name.blank?
+        return true if col_name.to_s == pk.name.to_s && table_name.to_s == pk.relation.table_name.to_s
+      end
+      return false
+    end
+
+    # already_has_order? returns true if collection has order directives set already
+    def already_has_order?(collection)
+      return false if collection.order_values.blank?
+      collection.order_values.size > 0
+    end
+
+    def comparison_to_s(comparison)
+      return "<" if comparison.to_sym == :lt # less than
+      return ">" if comparison.to_sym == :gt # greater than
+      raise ArgumentError, "'#{comparison}' must be either :lt or :gt"
+    end
   end
 end

data/lib/page_cursor/version.rb

@@ -1,3 +1,3 @@
 module PageCursor
-  VERSION = "1.0.0"
+  VERSION = "2.0.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: page_cursor
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Matthias Kadenbach
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-10-27 00:00:00.000000000 Z
+date: 2020-10-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails