cursor-paginate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9eb90ce934f65fb5dce2a9aa7492fdf6d0c658c9365fa83181ba6295b5726291
+  data.tar.gz: c8570c232ade6edfa9301037c6ec14edb59bd4f27cb454a1649ff343ab66cf8d
+SHA512:
+  metadata.gz: c57badb5e75fb2302a9bdf66a99be3d3978c4779f25b3c40cae4bf4adeff5cccda004b032bd285cce90f15ab51e31242919c82034f4461b1993c532ae08c6ed7
+  data.tar.gz: 040f0b9216b2fbad7953f19808f1b339eeedbf536e32727f7d2fa023c41deeafd6f66c178c094deb14abd60f2800735328b19da3b183488095fb284f25cbe9de

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2019 
+
+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,53 @@
+# cursor-paginate [![CircleCI](https://circleci.com/gh/otoyo/cursor-paginate.svg?style=svg)](https://circleci.com/gh/otoyo/cursor-paginate)
+Cursor based pagination library for Rails.
+
+## Usage
+
+```ruby
+# Get the oldest 100 posts where id <= cursor
+# If cursor is nil, get the oldest 100 posts.
+@posts = Post.before(id: params[:cursor]).limit(100)
+
+# Get the newest 100 posts where id >= cursor
+# If cursor is nil, get the newest 100 posts.
+@posts = Post.after(id: params[:cursor]).limit(100)
+
+# Also you can use other colum as cursor instead of id
+@posts = Post.before(created_at: params[:cursor]).limit(100)
+
+@posts.has_next?   # => true/false
+@posts.next_cursor # => value of cursor column/nil
+```
+
+Note that if multiple data have the same cursor value (like `created_at` at the same time), they appear in duplicate.
+
+### In the template
+
+If you use [Bootstrap 4.x](https://getbootstrap.com/docs/4.3/components/pagination/), pagers are expressed as below:
+
+```html
+<nav aria-label="pagination">
+  <ul class="pagination">
+    <% if @posts.has_next? %>
+      <li class="page-item">
+        <%= link_to "Next &gt;", { controller: :posts, action: :index, cursor: @posts.next_cursor }, class: "page-link" %>
+      </li>
+    <% else %>
+      <li class="page-item disabled"><a href="#" class="page-link">Next &gt;</a></li>
+    <% end %>
+  </ul>
+</nav>
+```
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'cursor-paginate'
+```
+
+## Contributing
+Feel free to send PR.
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/cursor-paginate.rb

@@ -0,0 +1,8 @@
+module CursorPagination
+end
+
+if defined?(Rails::Railtie)
+  require "cursor-paginate/railtie"
+else
+  raise "cursor-paginate is not available with your Rails version."
+end

data/lib/cursor-paginate/active_record.rb

@@ -0,0 +1,94 @@
+require "active_record"
+require "cursor-paginate/errors"
+
+module CursorPagination
+  module ActiveRecord
+    module RelationMethods
+      attr_accessor :cursor_key
+
+      def before(options)
+        options = HashWithIndifferentAccess.new(options)
+
+        rel = if ::ActiveRecord::Relation === self
+                self
+              else
+                all
+              end
+
+        rel.cursor_key = rel.model.columns.map(&:name).find { |column| options.key? column }
+        raise CursorPagination::InvalidColumnGiven unless rel.cursor_key
+
+        cursor = options[rel.cursor_key]
+
+        rel.where(cursor ? arel_table[rel.cursor_key].lteq(cursor) : nil).reorder(arel_table[rel.cursor_key].desc)
+      end
+
+      def after(options)
+        options = HashWithIndifferentAccess.new(options)
+
+        rel = if ::ActiveRecord::Relation === self
+                self
+              else
+                all
+              end
+
+        rel.cursor_key = rel.model.columns.map(&:name).find { |column| options.key? column }
+        raise CursorPagination::InvalidColumnGiven unless rel.cursor_key
+
+        cursor = options[rel.cursor_key]
+
+        rel.where(cursor ? arel_table[rel.cursor_key].gteq(cursor) : nil).reorder(arel_table[rel.cursor_key].asc)
+      end
+
+      def has_next?
+        set_next if @has_next.nil?
+        @has_next
+      end
+
+      def next_cursor
+        set_next if @has_next.nil?
+        @next_cursor
+      end
+
+      # Override ActiveRecord::Relation#load
+      def load
+        return super unless cursor_key
+
+        rel = super
+        rel.set_next
+        rel
+      end
+
+      protected
+
+      def set_next
+        rel = self
+        raise CursorPagination::LimitNotSet if rel.limit_value.nil?
+
+        excess = rel.dup.tap { |r| r.limit_value = r.limit_value + 1 }
+
+        if excess.size > rel.size
+          @has_next = true
+          @next_cursor = excess.last[cursor_key]
+        else
+          @has_next = false
+          @next_cursor = nil
+        end
+      end
+
+      ::ActiveRecord::Base.extend RelationMethods
+
+      klasses = [::ActiveRecord::Relation]
+      if defined? ::ActiveRecord::Associations::CollectionProxy
+        klasses << ::ActiveRecord::Associations::CollectionProxy
+      else
+        klasses << ::ActiveRecord::Associations::AssociationCollection
+      end
+
+      # # support pagination on associations and scopes
+      klasses.each do |klass|
+        klass.send(:include, RelationMethods)
+      end
+    end
+  end
+end

data/lib/cursor-paginate/errors.rb

@@ -0,0 +1,4 @@
+module CursorPagination
+  class InvalidColumnGiven < StandardError; end
+  class LimitNotSet < StandardError; end
+end

data/lib/cursor-paginate/railtie.rb

@@ -0,0 +1,9 @@
+module CursorPagination
+  class Railtie < ::Rails::Railtie
+    initializer "cursor-paginate" do |app|
+      ActiveSupport.on_load :active_record do
+        require "cursor-paginate/active_record"
+      end
+    end
+  end
+end

data/lib/cursor-paginate/version.rb

@@ -0,0 +1,3 @@
+module CursorPagination
+  VERSION = '0.1.0'
+end

data/spec/active_record_spec.rb

@@ -0,0 +1,240 @@
+require "rails_helper"
+
+describe "RelationMethods" do
+  before do
+    10.times do |i|
+      Post.create(created_at: Time.now + i)
+    end
+
+    posts[0, 3].each do |post|
+      post.is_published = true
+      post.save
+    end
+  end
+
+  after do
+    Post.delete_all
+  end
+
+  shared_examples_for "next_cursor exists" do
+    describe "#has_next?" do
+      subject { posts.has_next? }
+
+      it { is_expected.to eq true }
+    end
+
+    describe "next_cursor" do
+      subject { posts.next_cursor }
+
+      it { is_expected.to eq expected }
+    end
+  end
+
+  shared_examples_for "no next_cursor" do
+    describe "#has_next?" do
+      subject { posts.has_next? }
+
+      it { is_expected.to eq false }
+    end
+
+    describe "next_cursor" do
+      subject { posts.next_cursor }
+
+      it { is_expected.to be_nil }
+    end
+  end
+
+  describe "#before" do
+    context "cursor is nil" do
+      let(:cursor) { nil }
+      let!(:posts) { Post.before(id: cursor).limit(limit) }
+
+      context "limit is less than count of all" do
+        let(:limit) { 3 }
+        let(:expected) { Post.order("id desc")[limit].id }
+
+        it_behaves_like "next_cursor exists"
+      end
+
+      context "limit is equal to count of all" do
+        let(:limit) { Post.count }
+
+        it_behaves_like "no next_cursor"
+      end
+    end
+
+    context "id is given as cursor" do
+      let(:cursor_pos) { 3 }
+      let(:cursor) { Post.order("id desc")[cursor_pos].id }
+      let!(:posts) { Post.before(id: cursor).limit(limit) }
+
+      context "limit is less than count of all" do
+        let(:limit) { 3 }
+        let(:expected) { Post.order("id desc")[limit + cursor_pos].id }
+
+        it_behaves_like "next_cursor exists"
+      end
+
+      context "limit is equal to count of all" do
+        let(:limit) { Post.count }
+
+        it_behaves_like "no next_cursor"
+      end
+    end
+
+    context "invalid column given" do
+      let(:cursor_pos) { 3 }
+      let(:posts) { Post.order("id desc") }
+      let(:cursor) { posts[cursor_pos].id }
+
+      subject { -> { Post.before(none: cursor) } }
+
+      it { is_expected.to raise_error(CursorPagination::InvalidColumnGiven) }
+    end
+
+    context "limit not set" do
+      let(:cursor_pos) { 3 }
+      let(:posts) { Post.order("id desc") }
+      let(:cursor) { posts[cursor_pos].id }
+
+      subject { -> { Post.before(id: cursor).has_next? } }
+
+      it { is_expected.to raise_error(CursorPagination::LimitNotSet) }
+    end
+
+    context "other condition is given" do
+      let(:cursor_pos) { 3 }
+      let(:cursor) { Post.where(is_published: false).order("id desc")[cursor_pos].id }
+      let!(:posts) { Post.where(is_published: false).before(id: cursor).limit(limit) }
+
+      context "limit is less than count of all" do
+        let(:limit) { 3 }
+        let(:expected) { Post.where(is_published: false).order("id desc")[limit + cursor_pos].id }
+
+        it_behaves_like "next_cursor exists"
+      end
+
+      context "limit is equal to count of all" do
+        let(:limit) { Post.where(is_published: false).count }
+
+        it_behaves_like "no next_cursor"
+      end
+    end
+
+    context "created_at is given as cursor" do
+      let(:cursor_pos) { 3 }
+      let(:cursor) { Post.order("id desc")[cursor_pos].created_at }
+      let!(:posts) { Post.before(created_at: cursor).limit(limit) }
+
+      context "limit is less than count of all" do
+        let(:limit) { 3 }
+        let(:expected) { Post.order("id desc")[limit + cursor_pos].created_at }
+
+        it_behaves_like "next_cursor exists"
+      end
+
+      context "limit is equal to count of all" do
+        let(:limit) { Post.count }
+
+        it_behaves_like "no next_cursor"
+      end
+    end
+  end
+
+  describe "#after" do
+    context "cursor is nil" do
+      let(:cursor) { nil }
+      let!(:posts) { Post.after(id: cursor).limit(limit) }
+
+      context "limit is less than count of all" do
+        let(:limit) { 3 }
+        let(:expected) { Post.order("id asc")[limit].id }
+
+        it_behaves_like "next_cursor exists"
+      end
+
+      context "limit is equal to count of all" do
+        let(:limit) { Post.count }
+
+        it_behaves_like "no next_cursor"
+      end
+    end
+
+    context "id is given as cursor" do
+      let(:cursor_pos) { 3 }
+      let(:cursor) { Post.order("id asc")[cursor_pos].id }
+      let!(:posts) { Post.after(id: cursor).limit(limit) }
+
+      context "limit is less than count of all" do
+        let(:limit) { 3 }
+        let(:expected) { Post.order("id asc")[limit + cursor_pos].id }
+
+        it_behaves_like "next_cursor exists"
+      end
+
+      context "limit is equal to count of all" do
+        let(:limit) { Post.count }
+
+        it_behaves_like "no next_cursor"
+      end
+    end
+
+    context "invalid column given" do
+      let(:cursor_pos) { 3 }
+      let(:posts) { Post.order("id desc") }
+      let(:cursor) { posts[cursor_pos].id }
+
+      subject { -> { Post.after(none: cursor) } }
+
+      it { is_expected.to raise_error(CursorPagination::InvalidColumnGiven) }
+    end
+
+    context "limit not set" do
+      let(:cursor_pos) { 3 }
+      let(:posts) { Post.order("id desc") }
+      let(:cursor) { posts[cursor_pos].id }
+
+      subject { -> { Post.after(id: cursor).has_next? } }
+
+      it { is_expected.to raise_error(CursorPagination::LimitNotSet) }
+    end
+
+    context "other condition is given" do
+      let(:cursor_pos) { 3 }
+      let(:cursor) { Post.where(is_published: false).order("id asc")[cursor_pos].id }
+      let!(:posts) { Post.where(is_published: false).after(id: cursor).limit(limit) }
+
+      context "limit is less than count of all" do
+        let(:limit) { 3 }
+        let(:expected) { Post.where(is_published: false).order("id asc")[limit + cursor_pos].id }
+
+        it_behaves_like "next_cursor exists"
+      end
+
+      context "limit is equal to count of all" do
+        let(:limit) { Post.where(is_published: false).count }
+
+        it_behaves_like "no next_cursor"
+      end
+    end
+
+    context "created_at is given as cursor" do
+      let(:cursor_pos) { 3 }
+      let(:cursor) { Post.order("id asc")[cursor_pos].created_at }
+      let!(:posts) { Post.after(created_at: cursor).limit(limit) }
+
+      context "limit is less than count of all" do
+        let(:limit) { 3 }
+        let(:expected) { Post.order("id asc")[limit + cursor_pos].created_at }
+
+        it_behaves_like "next_cursor exists"
+      end
+
+      context "limit is equal to count of all" do
+        let(:limit) { Post.count }
+
+        it_behaves_like "no next_cursor"
+      end
+    end
+  end
+end