activerecord_cursor_pagination 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: ec58ef3cae3354d8ae2bde159b228728f072aa4f79bd57ea7d950cfd7a56dd7c
+  data.tar.gz: 1b5d74a9eb2c66cd08219688f97c697f5df984551bee64a83c763a964971357e
+SHA512:
+  metadata.gz: 5440057c5689b27043c534e49048579c7a2a21108f4b7c91e39cf3bb1f1ee08bbd7f366ce14e25156a55fcbff3cebd5b8274803c86e16ce952bfd54c40a1991e
+  data.tar.gz: '0219a04ac75387cbe73056447dfdbfb6cbf7cf3cc7bf0118f35aab50128910560f72134786c695de93de7834acb5fac6240316db3863c951cf9bce54f9c7a5a7'

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,13 @@
+AllCops:
+  TargetRubyVersion: 2.6
+
+Style/StringLiterals:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  Enabled: true
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120

data/Gemfile

@@ -0,0 +1,5 @@
+source "https://rubygems.org"
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}" }
+
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 James Fawks
+
+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,220 @@
+![Tests](https://github.com/jefawks3/activerecord_cursor_pagination/actions/workflows/test.yml/badge.svg)
+
+# ActiverecordCursorPagination
+
+ActiveRecord plugin for cursor based pagination using a serialized representation of the pages to paginate your content.
+
+The main advantage to cursor based pagination over the traditional (`limit` & `offset`) is that the cursors are not
+impacted by changes to the query (i.e. new records or records that no longer fit the query conditions).
+
+The advantage of `ActiverecordCursorPagination` over other gems is their is no requirement to define a row key (usually `id`) to sort
+the records. This allows for more complex queries to include joins or subqueries, and for ordering to also include
+table aliases or complex operations.
+
+## Motivation
+
+I needed a cursor pagination method that was key agnostic and where I can order the records in any method I wish;
+including using complex queries or table aliases. This was especially important when building out user feeds.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'activerecord_cursor_pagination'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install activerecord_cursor_pagination
+
+## The `cursor` Basics
+
+By default, `ActiverecordCursorPagination` defaults to 15 results per page.
+
+```ruby
+# Imagine there are 60 *total* posts (at 10 results/page, that is 6 pages)
+cursor = Posts.where(published: true)
+  .order(published_at: :desc)
+  .cursor(nil)
+
+cursor.per_page         # => 10
+
+# scoped to the whole query
+cursor.scope_size       # => 60
+cursor.scope_empty?     # => false
+cursor.scope_any?       # => true
+cursor.scope_one?       # => false
+cursor.scope_many?      # => true
+
+# scoped to the current page
+cursor.size             # => 10
+cursor.empty?           # => false
+cursor.any?             # => true
+cursor.one?             # => false
+cursor.many?            # => true
+
+# pagination
+cursor.current_page     # => "serialized cursor..."
+cursor.first_page?      # => true
+cursor.last_page?       # => false
+cursor.next_page?       # => true
+cursor.next_page        # => "serialized cursor..."
+cursor.previous_page?   # => false
+cursor.previous_cursor  # => ""
+```
+
+To retrieve the next page of results, pass the next page cursor.
+
+```ruby
+cursor = Posts.where(published: true)
+  .order(published_at: :desc)
+  .cursor("next page serialized cursor...")
+
+cursor.per_page         # => 10
+
+# scoped to the whole query
+cursor.scope_size       # => 60
+cursor.scope_empty?     # => false
+cursor.scope_any?       # => true
+cursor.scope_one?       # => false
+cursor.scope_many?      # => true
+
+# scoped to the current page
+cursor.size             # => 10
+cursor.empty?           # => false
+cursor.any?             # => true
+cursor.one?             # => false
+cursor.many?            # => true
+
+# pagination
+cursor.current_page     # => "serialized cursor..."
+cursor.first_page?      # => false
+cursor.last_page?       # => false
+cursor.next_page?       # => true
+cursor.next_page        # => "serialized cursor..."
+cursor.previous_page?   # => true
+cursor.previous_cursor  # => "serialized cursor..."
+```
+
+You can iterate through the current page of results.
+
+```ruby
+cursor.each { |record| /* do something */ }
+cursor.each_with_index { |record, index| /* do something */ }
+mapped = cursor.map { |record| /* do something */ }
+mapped = cursor.map_with_index { |record, index| /* do something */ }
+```
+
+A custom number of results per page can be specified by passing the `per` option.
+
+```ruby
+cursor = Posts.where(published: true)
+  .order(published_at: :desc)
+  .cursor(nil, per: 50)
+```
+
+## PagerView Helpers
+
+Lets image you have a pager view that displays one `Post` at a time and you have left and right errors to go to
+the next or previous record.
+
+```ruby
+post = Post.find(10)
+
+cursor = Posts.where(published: true)
+  .order(published_at: :desc)
+  .cursor(post, per: 1)
+
+cursor.next_cursor_record       # => [Post] Next published post
+cursor.previous_cursor_record   # => [Post] Previous published post
+```
+
+**Make sure to set `per` to `1` or you will get a `NotSingleRecordError`**
+
+If no record can be found, `next_cursor_record` and `previous_cursor_record` will return `nil`.
+
+## Configuration
+
+Configure `ActiverecordCursorPagination` using the `setup` method.
+
+```ruby
+ActiverecordCursorPagination.setup do |config|
+  config.secret_key = 'your super secret key'
+  config.serializer = YourCustomSerializer
+end
+```
+
+## Custom Cursor Serializer
+
+To create a custom cursor serializer, you need to override `ActiverecordCursorPagination::Serializer`.
+Call `secret_key` in your custom class to get the configured cursor key.
+
+**If you secure your database with external ids, make sure to encrypt the tokens so you don't 
+expose the internal database ids.**
+
+For instance, to create a `JWT` serializer:
+
+```ruby
+class JwtCursorSerializer < ActiverecordCursorPagination::Serializer
+  def deserialize(str)
+    data = JWT.decode str,
+                      secret_key,
+                      true,
+                      { algorithm: 'HS256' }
+
+    data.first.symbolize_keys
+  end
+
+  def serialize(hash)
+    JWT.encode hash, secret_key,'HS256'
+  end
+end
+```
+
+Make sure to configure `ActiverecordCursorPagination` by setting the `serializer` 
+configuration option with your new serializer.
+
+## Known Issues/Limitations
+
+- There is no known public method to call to get the order values. Currently calls `order_values` to get a list of all order values in the current query scope.
+- When using a sub query or `CASE` statement as an order value, you have to use single quote strings.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. 
+Then, run `rake spec` to run the tests. 
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Testing
+
+Run `rake rspec` to run all the tests or you can run:
+- `rake rspec [path]` to run all the tests in a given directory,
+- or `rake rspec [file]` to run a specific file.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jefawks3/activerecord_cursor_pagination.
+
+I hope that you will consider contributing to ActiverecordCursorPagination. 
+You can contribute in many ways. For example, you might:
+- add documentation and “how-to” articles to the README or Wiki.
+- hack on ActiverecordCursorPagination itself by fixing bugs you've found in the GitHub Issue tracker or adding new features to ActiverecordCursorPagination.
+
+When contributing to ActiverecordCursorPagination, we ask that you:
+- let me know what you plan in the GitHub Issue tracker so I can provide feedback.
+- provide tests and documentation whenever possible. It is very unlikely that I will accept new features or functionality into ActiverecordCursorPagination without the proper testing and documentation. When fixing a bug, provide a failing test case that your patch solves.
+- open a GitHub Pull Request with your patches and I will review your contribution and respond as quickly as possible. 
+
+Keep in mind that this is an open source project, and it may take me some time to get back to you. 
+Your patience is very much appreciated.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "activerecord_cursor_pagination"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/examples/jwt_cursor_serializer.rb

@@ -0,0 +1,14 @@
+class JwtCursorSerializer < ActiverecordCursorPagination::Serializer
+  def deserialize(str)
+    data = JWT.decode str,
+                      secret_key,
+                      true,
+                      { algorithm: 'HS256' }
+
+    data.first.symbolize_keys
+  end
+
+  def serialize(hash)
+    JWT.encode hash, secret_key,'HS256'
+  end
+end

data/lib/activerecord_cursor_pagination/ascending_order.rb

@@ -0,0 +1,21 @@
+module ActiverecordCursorPagination
+  class AscendingOrder < OrderBase
+    def direction
+      :asc
+    end
+
+    def reverse
+      order = DescendingOrder.new table, name, index
+      order.base_id = base_id
+      order
+    end
+
+    def than_op
+      '>'
+    end
+
+    def than_or_equal_op
+      '>='
+    end
+  end
+end

data/lib/activerecord_cursor_pagination/class_formatter.rb

@@ -0,0 +1,19 @@
+module ActiverecordCursorPagination
+  class ClassFormatter
+    ##
+    # Format the class name
+    #
+    # @param [String, Symbol, Class] klass_or_name
+    #
+    # @return [String, nil] The formatted class name
+    def format(klass_or_name)
+      if klass_or_name.nil? || klass_or_name.is_a?(String)
+        klass_or_name
+      elsif klass_or_name.is_a? Symbol
+        klass_or_name.to_s.camelcase
+      else
+        klass_or_name.name
+      end
+    end
+  end
+end

data/lib/activerecord_cursor_pagination/configuration.rb

@@ -0,0 +1,45 @@
+module ActiverecordCursorPagination
+  class Configuration
+    attr_accessor :serializer, :secret_key
+
+    def initialize
+      setup_defaults
+    end
+
+    ##
+    # Gets the secret key base for secure cursor implementations.
+    #
+    # If Rails is defined, +secret_key+ will try to find the implementation of the default +secret_key_base+
+    # in the application.
+    #
+    # @raise [NoSecretKeyError] If no key is set or found.
+    #
+    # @return [String] The secret key.
+    def secret_key
+      raise NoSecretKeyError, 'No secret key is defined' if @secret_key.nil? || @secret_key.empty?
+      @secret_key
+    end
+
+    ##
+    # Get an instance of the serializer
+    #
+    # @return [Serializer]
+    def serializer_instance
+      serializer.new
+    end
+
+    private
+
+    def setup_defaults
+      @secret_key = find_secret_key
+      @serializer = SecureCursorSerializer
+    end
+
+    def find_secret_key
+      return nil unless defined?(Rails) && Rails.respond_to?(:application)
+
+      finder = SecretKeyFinder.new
+      finder.find_in Rails.application
+    end
+  end
+end

data/lib/activerecord_cursor_pagination/cursor.rb

@@ -0,0 +1,144 @@
+module ActiverecordCursorPagination
+  class Cursor
+    attr_reader :klass_name, :signed_sql, :per_page, :start_id, :end_id
+
+    ##
+    # Initialize a cursor
+    #
+    # @param [Class, String] klass_or_name The model class
+    # @param [ActiveRecord::Relation, String] sql_or_signed_sql The active record SQL relation
+    # @param [Integer] per_page The number of records per page
+    # @param [Integer] start_id The ID of the first record in the page
+    # @param [Integer] end_id The ID of the last record in the page
+    def initialize(klass_or_name, sql_or_signed_sql, per_page, start_id, end_id)
+      @signed_sql = sql_or_signed_sql.is_a?(String) ? sql_or_signed_sql : sql_signer.sign(sql_or_signed_sql)
+      @klass_name = class_formatter.format klass_or_name
+      @per_page = per_page
+      @start_id = start_id
+      @end_id = end_id
+    end
+
+    ##
+    # Is the cursor not empty
+    #
+    # @return [Boolean]
+    def present?
+      !empty?
+    end
+
+    ##
+    # Is the cursor empty
+    #
+    # @return [Boolean]
+    def empty?
+      @start_id.nil? || @end_id.nil?
+    end
+
+    ##
+    # Gets the hash representation of the cursor
+    #
+    # @return [Hash]
+    def to_hash
+      {
+        start: @start_id,
+        end: @end_id,
+        per_page: @per_page,
+        model: @klass_name,
+        sql: @signed_sql
+      }
+    end
+
+    ##
+    # Get the string representation of the cursor
+    #
+    # @return [String] The serialized cursor
+    def to_s
+      serializer.serialize to_hash
+    end
+
+    alias_method :to_param, :to_s
+
+    ##
+    # Validates the cursor
+    #
+    # @param [Class] klass The model class
+    # @param [ActiveRecord::Relation] sql The active record SQL relation
+    # @param [Integer] per_page The number of records per page
+    #
+    # @raise [InvalidCursorError] If cursor is not valid
+    def validate!(klass, sql, per_page)
+      raise InvalidCursorError.new('Invalid cursor', self) unless valid?(klass, sql, per_page)
+    end
+
+    private
+
+    delegate :class_formatter, :sql_signer, :serializer, to: :class
+
+    def valid?(klass, sql, per_page)
+      formatted_class = class_formatter.format klass
+      signed_sql = sql.is_a?(String) ? sql : sql_signer.sign(sql)
+
+      @klass_name === formatted_class &&
+        @signed_sql === signed_sql &&
+        @per_page === per_page
+    end
+
+    class << self
+      ##
+      # Get sql signer instance
+      #
+      # @return [SqlSigner]
+      def sql_signer
+        SqlSigner.new
+      end
+
+      ##
+      # Get class formatter
+      #
+      # @return [ClassFormatter]
+      def class_formatter
+        ClassFormatter.new
+      end
+
+      ##
+      # Get cursor serializer instance
+      #
+      # @return [Serializer]
+      def serializer
+        ActiverecordCursorPagination.configuration.serializer_instance
+      end
+
+      ##
+      # Parse the cursor string
+      #
+      # @param [String] str Cursor serialized string.
+      #
+      # @return [Cursor, EmptyCursor] Instance of Cursor.
+      def parse(str)
+        return EmptyCursor.new if str.nil? || str.empty?
+
+        hash = serializer.deserialize str
+
+        new hash[:model],
+            hash[:sql],
+            hash[:per_page],
+            hash[:start],
+            hash[:end]
+      end
+
+      ##
+      # Serialize the cursor
+      #
+      # @param [Class, String] klass_or_name The model class
+      # @param [ActiveRecord::Relation, String] sql_or_signed_sql The active record SQL relation
+      # @param [Integer] per_page The number of records per page
+      # @param [Integer] start_id The ID of the first record in the page
+      # @param [Integer] end_id The ID of the last record in the page
+      #
+      # @return [String] The serialized cursor string
+      def to_param(klass_or_name, sql_or_signed_sql, per_page, start_id, end_id)
+        new(klass_or_name, sql_or_signed_sql, per_page, start_id, end_id).to_param
+      end
+    end
+  end
+end