paging_cursor 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5a49f5abf6c5a0d96017ad40e05592dd78a208a4
+  data.tar.gz: 4df33eda9a444e83f823ecff325ae23450b6fbe2
+SHA512:
+  metadata.gz: 1b9804935cd5836c327590b37402b4bac7e9eeeca41ffa10703bf237388358c657ad313db67a44266f642f89e0581966f1667781569c8d3085f9b0190b8a6f72
+  data.tar.gz: 783305c3f6a8dd815daa4b78d905fd396b2425a1e8367523891212a8ea313b3a722b7b5b9fe3fc06b9cb51215704d70944501f1368cfd65f21ade0f2d8321f5e

data/LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2016 Rebecca "Becky" Segal
+
+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,66 @@
+# Usage
+
+Use `.before`, `.after`, or `.cursor` in ActiveRecord queries to paginate data. A default limit is always applied, or you can override by including `.limit` in your request.
+
+For example, say we have an app with User and Post models.
+
+```
+# app/models/user.rb
+class User < ActiveRecord::Base
+  has_many :posts
+end
+
+# app/models/post.rb
+class Post < ActiveRecord::Base
+  belongs_to :user
+end
+```
+
+We can retrieve posts starting with the most recent
+
+```
+Post.before                 # get the first page of most recent posts with the default limit
+Post.before.limit(10)       # get the 10 most recent posts
+Post.before(999).limit(10)  # get the 10 most recent posts that were created before the post with id=999
+Post.where(user: User.first).before(999)  # get the 10 most recent posts meeting a condition
+User.first.posts.before     # get the most recent posts belong to a user
+```
+
+
+Likewise, we can results starting from the oldest records
+
+```
+Post.after                  # get the first page of oldest posts with the default limit
+Post.after.limit(10)        # get the 10 oldest posts
+Post.after(999).limit(10)   # get the 10 oldest posts that are newer than the post with id=999
+Post.where(user: User.first).after(999)  # get the 10 oldest posts meeting a condition
+User.first.posts.after      # get the oldest posts belong to a user
+```
+
+# Sorting results
+
+By default, all results are returned in ascending order. 
+
+
+To customize, set a config option, class option or per-query option
+
+
+# Adding pagination metadata to responses
+
+This gem makes no assumptions about how you want to return pagination metadata in your responses. Arrays and results provide the cursor information you need. 
+
+```
+result = Post.before(999)
+result.length
+ => 20
+result.cursor_before
+ => 990  # the minimum id included in the result
+result.cursor_after
+ => 998  # the maximum id included in the result
+```
+
+TODO
+* option for sorting results
+* cursor methods on array
+* global default for limits
+* per-model setting for limits

data/lib/paging_cursor.rb

@@ -0,0 +1,7 @@
+module PagingCursor
+end
+
+
+require 'paging_cursor/config'
+require 'paging_cursor/direction'
+require 'paging_cursor/active_record'

data/lib/paging_cursor/active_record.rb

@@ -0,0 +1,86 @@
+require 'active_record'
+
+module PagingCursor
+  module ActiveRecord
+
+    # TODO: option to set which column is used for pagination
+    #  default = :id
+    module FinderMethods
+
+      # default order = after
+      def cursor(options={})
+        options = HashWithIndifferentAccess.new(options)
+        if options.has_key?(:before) || (!options.has_key?(:after) && PagingCursor.config.default_sort_order == :desc)
+          result = before(options[:before])
+        else
+          result = after(options[:after])
+        end
+        result.limit(options[:limit] || self.cursor_page_limit)
+      end
+
+      def before(cursor=nil)
+        result = where(cursor ? arel_table[primary_key].lt(cursor) : nil).reorder(arel_table[primary_key].desc)
+        result.sort_order = :desc
+        result.cursored = true
+        result
+      end
+
+      def after(cursor=nil)
+        result = where(arel_table[primary_key].gt(cursor || 0)).reorder(arel_table[primary_key].asc)
+        result.sort_order = :asc
+        result.cursored = true
+        result
+      end
+    end
+
+    module Limit
+      attr_accessor :cursor_page_limit
+
+      # TODO: allow setting default at global and model levels
+      def initialize *a
+        self.default_page_limit = 25
+        super *a
+      end
+
+      def cursor_page_limit
+        @cursor_page_limit ||= PagingCursor.config.default_page_limit
+      end
+    end
+
+    module SortedResults
+      attr_accessor :sort_order, :cursored
+
+      def initialize *a
+        self.sort_order = :asc
+        self.cursored = false # todo, separate module??
+        super *a
+      end
+
+      def to_a
+        return super unless self.cursored
+        r = ::PagingCursor::Array.new(super)
+        if self.sort_order != PagingCursor.config.default_sort_order.to_sym
+          r.reverse!
+        end
+        r
+      end
+    end
+
+    ::ActiveRecord::Base.extend FinderMethods
+    ::ActiveRecord::Base.extend Limit
+
+    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(:prepend, SortedResults)
+      klass.send(:include, FinderMethods) 
+      klass.send(:include, ::PagingCursor::Direction)
+    end
+  end
+end

data/lib/paging_cursor/config.rb

@@ -0,0 +1,31 @@
+require 'active_support/configurable'
+
+module PagingCursor
+
+  def self.configure(&block)
+    yield @config ||= PagingCursor::Configuration.new
+  end
+
+  def self.config
+    @config
+  end
+
+  class Configuration
+    include ActiveSupport::Configurable
+    config_accessor :default_sort_order
+    config_accessor :default_page_limit
+
+    def param_name
+      config.param_name.respond_to?(:call) ? config.param_name.call : config.param_name
+    end
+
+    writer, line = 'def param_name=(value); config.param_name = value; end', __LINE__
+    singleton_class.class_eval writer, __FILE__, line
+    class_eval writer, __FILE__, line
+  end
+
+  configure do |config|
+    config.default_sort_order = :asc
+    config.default_page_limit = 25
+  end
+end

data/lib/paging_cursor/direction.rb

@@ -0,0 +1,26 @@
+module PagingCursor
+  module Direction
+
+    # TODO: *terrible* shouldn't need to cast to array to ensure sort order
+    # def first(limit = nil)
+    #   limit.nil? ? to_a.first : super
+    # end
+
+    # def last(limit = nil)
+    #   limit.nil? ? to_a.last : super
+    # end
+
+    def cursor_before
+      self.collect(&:id).min
+    end
+
+    def cursor_after
+      self.collect(&:id).max
+    end
+  end
+
+  class Array < ::Array
+  end
+
+  Array.include Direction
+end

data/spec/active_record_spec.rb

@@ -0,0 +1,172 @@
+require 'rails_helper'
+
+describe 'finders' do
+  shared_examples_for 'the first 5 posts' do
+    specify { expect(result).to eq(Post.first(5)) }
+  end
+
+  shared_examples_for 'the last 5 posts' do
+    specify { expect(result).to eq(Post.last(5))}
+  end
+
+  shared_examples_for 'the first 5 posts after 2' do
+    specify { expect(result.collect(&:id)).to eq((@min+2 .. @min+6).to_a) }
+  end
+
+  shared_examples_for 'the last 5 posts except 2' do
+    specify { expect(result.collect(&:id)).to eq((@max-6 .. @max-2).to_a) }
+  end
+
+  before do
+    PagingCursor.config.default_sort_order = :asc
+    @user = User.create
+    10.times do
+      Post.create(user_id: @user.id)
+    end
+    @min = Post.first.id
+    @max = Post.last.id
+  end
+
+  after do
+    Post.delete_all
+    User.delete_all
+  end
+
+  it 'accepts the limit parameter through cursor' do
+    expect(Post.cursor(limit: 2).size).to eq(2)
+  end
+
+  it 'accepts string and symbol eys' do
+    expect(Post.cursor('limit' => 2)).to eq(Post.cursor(limit: 2))
+  end
+
+  it 'does not override limit() with cursor option' do
+    expect(Post.cursor(limit: 2).limit(8).size).to eq(8)
+  end
+
+  it 'returns a PagingCursor::Array' do
+    expect(Post.after.to_a.class).to be(PagingCursor::Array)
+  end
+
+  it 'respects configured desc sort order' do
+    PagingCursor.config.default_sort_order = :desc
+    after = Post.after
+    before = Post.before
+    cursor = Post.cursor
+    expect(after[0].id).to be > after[1].id
+    expect(before[0].id).to be > before[1].id
+    expect(cursor[0].id).to be > cursor[1].id
+  end
+
+  it 'respects configured asc sort order' do
+    PagingCursor.config.default_sort_order = :asc
+    after = Post.after
+    before = Post.before
+    cursor = Post.cursor
+    expect(after[1].id).to be > after[0].id
+    expect(before[1].id).to be > before[0].id
+    expect(cursor[1].id).to be > cursor[0].id
+  end
+
+  context 'on active record' do
+    it_behaves_like "the first 5 posts" do
+      let(:result) { Post.after.limit(5) }
+    end
+
+    it_behaves_like "the last 5 posts" do
+      let(:result) { Post.before.limit(5) } 
+    end
+
+    it_behaves_like "the first 5 posts after 2" do
+      let(:result) { Post.after(@min + 1).limit(5) }
+    end
+
+    it_behaves_like "the last 5 posts except 2" do
+      let(:result) { Post.before(@max-1).limit(5) }
+    end
+
+    it_behaves_like "the first 5 posts" do
+      let(:result) { Post.cursor(after: nil).limit(5) }
+    end
+
+    it_behaves_like "the last 5 posts" do
+      let(:result) { Post.cursor(before: nil).limit(5) }
+    end
+
+    it_behaves_like "the first 5 posts after 2" do
+      let(:result) { Post.cursor(after: @min + 1).limit(5) }
+    end
+
+    it_behaves_like "the last 5 posts except 2" do
+      let(:result) { Post.cursor(before: @max-1).limit(5) }
+    end
+  end
+
+  context 'on relations' do
+    it_behaves_like "the first 5 posts" do
+      let(:result) { Post.where(user_id: @user.id).after.limit(5) }
+    end
+
+    it_behaves_like "the last 5 posts" do
+      let(:result) { Post.where(user_id: @user.id).before.limit(5) }
+    end
+
+    it_behaves_like "the first 5 posts after 2" do
+      let(:result) { Post.where(user_id: @user.id).after(@min + 1).limit(5) }
+    end
+
+    it_behaves_like "the last 5 posts except 2" do
+      let(:result) { Post.where(user_id: @user.id).before(@max - 1).limit(5) }
+    end
+
+    it_behaves_like "the first 5 posts" do
+      let(:result) { Post.where(user_id: @user.id).cursor(after: nil).limit(5) }
+    end
+
+    it_behaves_like "the last 5 posts" do
+      let(:result) { Post.where(user_id: @user.id).cursor(before: nil).limit(5) }
+    end
+
+    it_behaves_like "the first 5 posts after 2" do
+      let(:result) { Post.where(user_id: @user.id).cursor(after: @min + 1).limit(5) }
+    end
+
+    it_behaves_like "the last 5 posts except 2" do
+      let(:result) { Post.where(user_id: @user.id).cursor(before: @max-1).limit(5) }
+    end
+  end
+
+  context 'on associations' do
+    it_behaves_like "the first 5 posts" do
+      let(:result) { @user.posts.after.limit(5) }
+    end
+
+    it_behaves_like "the last 5 posts" do
+      let(:result) { @user.posts.before.limit(5) }
+    end
+
+    it_behaves_like "the first 5 posts after 2" do
+      let(:result) { @user.posts.after(@min + 1).limit(5) }
+    end
+
+    it_behaves_like "the last 5 posts except 2" do
+      let(:result) { @user.posts.before(@max - 1).limit(5) }
+    end
+
+    it_behaves_like "the first 5 posts" do
+      let(:result) { @user.posts.cursor(after: nil).limit(5) }
+    end
+
+    it_behaves_like "the last 5 posts" do
+      let(:result) { @user.posts.cursor(before: nil).limit(5) }
+    end
+
+    it_behaves_like "the first 5 posts after 2" do
+      let(:result) { @user.posts.cursor(after: @min + 1).limit(5) }
+    end
+
+    it_behaves_like "the last 5 posts except 2" do
+      let(:result) { @user.posts.cursor(before: @max - 1).limit(5) }
+    end
+  end
+end

data/spec/array_spec.rb

@@ -0,0 +1,21 @@
+require 'rails_helper'
+
+describe PagingCursor::Array do
+  it "adds before and after cursors" do
+    a = PagingCursor::Array.new([u1=User.create, u2=User.create])
+    expect(a.cursor_before).to eq(u1.id)
+    expect(a.cursor_after).to eq(u2.id)
+  end
+
+  it "adds correct cursors when array is not sorted" do
+    a = PagingCursor::Array.new([u1=User.create, u2=User.create].reverse)
+    expect(a.cursor_before).to eq(u1.id)
+    expect(a.cursor_after).to eq(u2.id)
+  end
+
+  it "adds cursors for non-id primary key columns" do
+    a = PagingCursor::Array.new([t1=Tag.create, t2=Tag.create])
+    expect(a.cursor_before).to eq(t1.name)
+    expect(a.cursor_after).to eq(t2.name)
+  end
+end

data/spec/rails_helper.rb

@@ -0,0 +1,13 @@
+ENV['RAILS_ENV'] ||= 'test'
+
+require 'spec_helper'
+require 'rails/all'
+require 'rspec/rails'
+ActiveRecord::Base.establish_connection adapter: "sqlite3", database: ":memory:"
+
+load File.dirname(__FILE__) + '/support/schema.rb'
+require File.dirname(__FILE__) + '/support/models.rb'
+
+RSpec.configure do |config|
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1,7 @@
+require 'bundler/setup'
+Bundler.setup
+
+require 'paging_cursor'
+
+RSpec.configure do |config|
+end

data/spec/support/models.rb

@@ -0,0 +1,11 @@
+class User < ActiveRecord::Base
+  has_many :posts
+end
+
+class Post < ActiveRecord::Base
+  belongs_to :user
+end
+
+class Tag < ActiveRecord::Base
+  self.primary_key = 'name'
+end

data/spec/support/schema.rb

@@ -0,0 +1,14 @@
+ActiveRecord::Schema.define do
+  self.verbose = false
+
+  create_table :users, force: true do |t|
+  end
+
+  create_table :posts, force: true do |t|
+    t.integer :user_id
+  end
+
+  create_table :tags, force: true, id: false do |t|
+    t.string :name, primary_key: true
+  end
+end

metadata

@@ -0,0 +1,111 @@
+--- !ruby/object:Gem::Specification
+name: paging_cursor
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Becky Segal
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2016-04-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: ActiveRecord and ActiveController extensions for cursor pagination
+email: becsegal@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/paging_cursor.rb
+- lib/paging_cursor/active_record.rb
+- lib/paging_cursor/config.rb
+- lib/paging_cursor/direction.rb
+- spec/active_record_spec.rb
+- spec/array_spec.rb
+- spec/rails_helper.rb
+- spec/spec_helper.rb
+- spec/support/models.rb
+- spec/support/schema.rb
+homepage: 
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.6
+signing_key: 
+specification_version: 4
+summary: ActiveRecord and ActiveController extensions for cursor pagination
+test_files: []