pageturner 3.1.0 → 4.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 24794d49a1531ed3ab3a00c71c6b9a963e42bb46
-  data.tar.gz: 23cc7603801d8948df99667797b60949a8d601da
+  metadata.gz: 9ec92e81b1919467490096e12c1bb8413a028262
+  data.tar.gz: 2215eda44407930869479a61c51f40c631d971b8
 SHA512:
-  metadata.gz: 64f858bce99a796dc7ab0885b12c0027542bed4dff38120d41c244c98143931869605683c41d72cab9b504a4e53a2c46229678951913ef989216c5877aa6bf3a
-  data.tar.gz: e9b2883c66a01680d3d6432ba4edd64ceb64c9e64ecc9031ade63ba79ed29150e0391f23588eb0c4febaebe1eb20b2fe69a50ab041f669ed9c19d8a33d63fb59
+  metadata.gz: 9c8ada0c35616416882e52147758e98dfb86222ac440f17c194f27eebc057da2013ae4331742b04356223d59b95881e936284a13e621168b5ce9b7ae68e96df4
+  data.tar.gz: 6de96592c15e9cd52ef14b08c09d1f378107877c93df23b2bdec14817f5fb9a8115c924da77e785f6633c966e1080cb19e37064dc9f539551f617f693d88c63c

data/README.md

@@ -1,6 +1,8 @@
 # Pageturner
 
-Cursor based pagination for activerecord queries.
+Cursor based pagination for activerecord queries as described in [Pagination Done the Right Way](http://use-the-index-luke.com/blog/2013-07/pagination-done-the-postgresql-way).
+
+Pageturner allows you to paginate over a collection's attribute (`anchor_column`) starting from a given record as noted by its id and value (`anchor_id`, `anchor_value`). The `anchor_value` is the main value that divides your collection's pages. When the `anchor_value` is `nil`, we can't perform comparisons so we augment it with `anchor_id` to decide ambiguities about ordering.
 
 ## Usage
 
@@ -39,6 +41,19 @@ json.pagination do
 end
 ```
 
+If the column that you want to paginate on is referenced differently in your database schema than in your application, then you can pass the translations into Pageturner. This may happen when you want to paginate over an associated model's column and the association is aliased in your model (e.g. `has_one :subordinate, class_name: "Employee"`).
+
+```ruby
+@pagination = Pageturner.new(
+  anchor_column: "subordinate",
+  anchor_column_active_record_identifier: "subordinate.id",
+  anchor_column_sql_identifier: "employees.id",
+  ...
+)
+```
+
+Pageturner will send the `anchor_column_active_record_identifier` as a method chain to an instance of the model you're paginating when calculating the next cursor from the current page and it will interpolate the `anchor_column_sql_identifier` string when building the where and order by clauses of the query that paginates your model.
+
 ## API
 
 ### `#next_cursor`

data/lib/pageturner.rb

@@ -6,16 +6,17 @@ class Pageturner
   LESS_THAN_OPERATOR = "<"
 
   # @param [String] anchor_column - Field to paginate on.
-  # @param [String|Number|nil] anchor_value - Value of the anchor_column for the record to paginate from.
+  # @param [Anything, nil] anchor_value - Value of the anchor_column for the record to paginate from.
   # @param [ActiveRecord::Relation] ar_relation - Resource collection to paginate.
   # @param [String] sort_direction - Order of the pagination. Valid values: Pageturner::ASC, Pageturner::DESC.
   # @param [Number] anchor_id - ID of the record to paginate from.
-  def initialize(anchor_column:, anchor_value:, ar_relation:, sort_direction:, page_size:, anchor_id:)
-    # To be used outside dynamic SQL statements.
+  # @param [String, nil] anchor_column_active_record_identifier - Method chain that references the anchor column in the model you are paginating.
+  # @param [String, nil] anchor_column_sql_identifier - SQL identifier that references the anchor column in your database schema.
+  def initialize(anchor_column:, anchor_value:, ar_relation:, sort_direction:, page_size:, anchor_id:, anchor_column_active_record_identifier: nil, anchor_column_sql_identifier: nil)
     @anchor_column = anchor_column
 
-    # To be used in dynamic SQL queries.
-    @sql_anchor_column = ActiveRecord::Base.connection.quote_column_name(anchor_column)
+    @anchor_column_active_record_identifier = anchor_column_active_record_identifier || @anchor_column
+    @anchor_column_sql_identifier = anchor_column_sql_identifier || @anchor_column
 
     @anchor_value = anchor_value
 
@@ -43,17 +44,10 @@ class Pageturner
   end
 
   def next_cursor
-    anchor_value =
-      if external_anchor_column?
-        public_send_chain_from_sql(self.resources.last, @anchor_column)
-      else
-        self.resources.last&.public_send(@anchor_column)
-      end
-
     {
       anchor_column: @anchor_column,
       anchor_id: self.resources.last&.id,
-      anchor_value: anchor_value,
+      anchor_value: try_chain(self.resources.last, @anchor_column_active_record_identifier),
       page_size: @page_size,
       sort_direction: @sort_direction
     }
@@ -91,12 +85,13 @@ class Pageturner
   end
 
   def calculate_next_page
-    if external_anchor_column?
-      table, column = @anchor_column.split(".")
+    # Heuristic to check if the `anchor_column_sql_identifier` is a joined column.
+    if @anchor_column_sql_identifier.include?(".")
+      table, column = @anchor_column_sql_identifier.split(".")
 
       qualified_anchor_column = "`#{table}`.`#{column}`"
     else
-      qualified_anchor_column = "#{@ar_relation.quoted_table_name}.#{@sql_anchor_column}"
+      qualified_anchor_column = "#{@ar_relation.quoted_table_name}.#{ActiveRecord::Base.connection.quote_column_name(@anchor_column)}"
     end
 
     qualified_anchor_pk_column = "#{@ar_relation.quoted_table_name}.#{@ar_relation.quoted_primary_key}"
@@ -117,7 +112,7 @@ class Pageturner
 
   def apply_sort_direction(ar_relation)
     ar_relation
-      .order("#{@anchor_column} #{@sort_direction}", @ar_relation.primary_key => @sort_direction)
+      .order("#{@anchor_column_sql_identifier} #{@sort_direction}", @ar_relation.primary_key => @sort_direction)
       .limit(@page_size)
   end
 
@@ -137,24 +132,9 @@ class Pageturner
     ar_relation.select_values.empty? || ar_relation.select_values.include?(@ar_relation.primary_key.to_sym)
   end
 
-  # Gets an ActiveRecord instance's associated attribute via its qualified column sql identifier.
-  #
-  # Given qualified_column_sql_identifier = "joined_tables.column", it will call `.joined_table.column` on `object`.
-  # `object` must be an ActiveRecord instance.
-  def public_send_chain_from_sql(object, qualified_column_sql_identifier)
-    # We limit `split` to 2 because we are assuming that the SQL identifier is in table.column format.
-    association, attribute = qualified_column_sql_identifier.split(".", 2).each_with_index.map do |string, index|
-      # The first element should be the joined table's sql identifier.
-      # These are always pluralized, so we must singularize it in order to use it as a method call.
-      index == 0 ? string.singularize : string
-    end
-
-    object.try!(association).try!(attribute)
-  end
-
-  # Heuristic to check if the `anchor_column` is a joined column.
-  def external_anchor_column?
-    @anchor_column.include?(".")
+  # Given attribute_chain = "association.attribute", it will call `.association.attribute` on `object`.
+  def try_chain(object, attribute_chain)
+    attribute_chain.split(".").reduce(object) { |o, command| o.try!(command) }
   end
 
   class Exception

data/pageturner.gemspec

@@ -4,7 +4,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
 Gem::Specification.new do |spec|
   spec.name          = "pageturner"
-  spec.version       = "3.1.0"
+  spec.version       = "4.0.0"
   spec.authors       = ["crzrcn"]
   spec.email         = ["fernanlink@gmail.com"]
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pageturner
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 4.0.0
 platform: ruby
 authors:
 - crzrcn
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-01-31 00:00:00.000000000 Z
+date: 2018-02-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord