cursor_pager 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1cfa8e486f765f437f2737c1778ea9f70c22849d8e0a6912bee1ec20440487a2
+  data.tar.gz: 99bbe1f36e20d8574217ca27f6bec0ef431487679f048ce7e6fb55fb8c73de5e
+SHA512:
+  metadata.gz: fe4e2e39e9d28cb318b6da7d09368f2d866a2f5386e796f8f816af22fdada3539748c46e59259c51673eee30ddb5d6059d0e02a8f6800da936be6fe1db7af6ae
+  data.tar.gz: 0e861720ee32d06b9d55c58a0f0a4ff6ba316435ae619186b8f762c42a6df40db87c79e7d968517d899fe3be3777dc146641dfa79dcada4f66883bc6e6686c48

data/.github/workflows/ci.yml

@@ -0,0 +1,56 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    branches: [master]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby-version: ["2.6", "2.7"]
+        activerecord-version: ["5.2", "6.0"]
+
+    services:
+      db:
+        image: postgres:12
+        env:
+          POSTGRES_PASSWORD: password
+          POSTGRES_DB: test
+        ports: ['5432:5432']
+        options: --health-cmd pg_isready --health-interval 10s --health-timeout 5s --health-retries 5
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+
+      - name: Set up bundler cache
+        uses: actions/cache@v1
+        with:
+          path: vendor/bundle
+          key: ${{ runner.os }}-gems-${{ hashFiles('**/Gemfile.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-gems-
+
+      - name: Set up Ruby ${{ matrix.ruby-version }}
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+
+      - name: Install dependencies (bundler)
+        run: |
+          export BUNDLE_GEMFILE="${GITHUB_WORKSPACE}/gemfiles/activerecord_${{ matrix.activerecord-version }}.gemfile"
+          gem install bundler
+          bundle config path "vendor/bundle"
+          bundle config jobs "$(nproc)"
+          bundle install
+
+      - name: Run tests
+        env:
+          DATABASE_URL: postgres://postgres:password@localhost:5432/test
+        run: |
+          export BUNDLE_GEMFILE="${GITHUB_WORKSPACE}/gemfiles/activerecord_${{ matrix.activerecord-version }}.gemfile"
+          bundle exec rspec

data/.gitignore

@@ -0,0 +1,12 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+.DS_Store
+
+# rspec failure tracking
+.rspec_status

data/.rspec

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

data/.rubocop.yml

@@ -0,0 +1,22 @@
+AllCops:
+  NewCops: enable
+  Exclude: 
+    - /**/bin/*
+    - /**/gemfiles/**
+
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Metrics:
+  Exclude:
+    - /**/spec/**/*
+
+Metrics/BlockLength:
+  Exclude:
+    - /**/spec/**/*
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes

data/.ruby-version

@@ -0,0 +1 @@
+2.7.1

data/.travis.yml

@@ -0,0 +1,6 @@
+---
+language: ruby
+cache: bundler
+rvm:
+  - 2.7.1
+before_install: gem install bundler -v 2.1.4

data/Appraisals

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+appraise "activerecord-5.2" do
+  gem "activerecord", "~> 5.2.0"
+end
+
+appraise "activerecord-6.0" do
+  gem "activerecord", "~> 6.0.0"
+end

data/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## Unreleased

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,74 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at bastian.bartmann@check24.de. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [https://contributor-covenant.org/version/1/4][version]
+
+[homepage]: https://contributor-covenant.org
+[version]: https://contributor-covenant.org/version/1/4/

data/Gemfile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in cursor_pager.gemspec
+gemspec
+
+gem "appraisal"
+gem "database_cleaner-active_record"
+gem "pg"
+gem "rake", "~> 12.0"
+gem "rspec", "~> 3.0"
+gem "rubocop"

data/Gemfile.lock

@@ -0,0 +1,85 @@
+PATH
+  remote: .
+  specs:
+    cursor_pager (0.1.0)
+      activerecord (>= 5.2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (6.0.2.2)
+      activesupport (= 6.0.2.2)
+    activerecord (6.0.2.2)
+      activemodel (= 6.0.2.2)
+      activesupport (= 6.0.2.2)
+    activesupport (6.0.2.2)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+      zeitwerk (~> 2.2)
+    appraisal (2.2.0)
+      bundler
+      rake
+      thor (>= 0.14.0)
+    ast (2.4.0)
+    concurrent-ruby (1.1.6)
+    database_cleaner (1.8.4)
+    database_cleaner-active_record (1.8.0)
+      activerecord
+      database_cleaner (~> 1.8.0)
+    diff-lcs (1.3)
+    i18n (1.8.2)
+      concurrent-ruby (~> 1.0)
+    jaro_winkler (1.5.4)
+    minitest (5.14.0)
+    parallel (1.19.1)
+    parser (2.7.1.1)
+      ast (~> 2.4.0)
+    pg (1.2.3)
+    rainbow (3.0.0)
+    rake (12.3.3)
+    rexml (3.2.4)
+    rspec (3.9.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+    rspec-core (3.9.1)
+      rspec-support (~> 3.9.1)
+    rspec-expectations (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.2)
+    rubocop (0.82.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.7.0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      rexml
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    ruby-progressbar (1.10.1)
+    thor (1.0.1)
+    thread_safe (0.3.6)
+    tzinfo (1.2.7)
+      thread_safe (~> 0.1)
+    unicode-display_width (1.7.0)
+    zeitwerk (2.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  appraisal
+  cursor_pager!
+  database_cleaner-active_record
+  pg
+  rake (~> 12.0)
+  rspec (~> 3.0)
+  rubocop
+
+BUNDLED WITH
+   2.1.4

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 CHECK24 Vergleichsportal Profis GmbH
+
+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,107 @@
+# CursorPager
+
+![build](https://github.com/askcharlie/cursor_pager/workflows/CI/badge.svg)
+
+A small and easy-to-use library that aims to make it easy to build Rails APIs
+with cursor-based pagination (aka keyset pagination).
+
+It aims to support the [JSON API Cursor Pagination] and [Relay's GraphQL Cursor
+Connection] specs.
+
+Stable ordering is essential for cursor-based pagination. The gem will
+automatically add additional sorting by primary key if the relation passed
+into the page isn't already ordered by the primary key or a datetime column.
+
+## Installation
+
+CursorPager is compatible with ActiveRecord 6.0 and 5.2 on Ruby 2.6 and later.
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "cursor_pager"
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install cursor_pager
+
+## Usage
+
+To fetch the first ten users:
+
+
+```ruby
+page = CursorPager::Page.new(User.all, first: 10)
+page.records
+```
+
+To get information about the page or generate a cursor
+
+```ruby
+page.previous_page?                # Tells you if there is a previous page
+page.next_page?                    # Tells you if there is a next page
+page.cursor_for(page.records.last) # Will generate a cursor for a specific item
+```
+
+To fetch the first then usres after a certain cursor
+
+```ruby
+page = CursorPager::Page.new(User.all, first: 10, after: "MTA=")
+page.records
+
+```
+
+To paginate backwards
+
+```ruby
+page = CursorPager::Page.new(User.all, last: 10, before: "NTA=")
+page.records
+```
+
+## Configuration
+
+By default cursors are base64 encoded primary keys of the records. If you wish
+to change that because you want to add encryption or something similiar, you
+can provide your own encoder class.
+
+```ruby
+class CustomEncoder
+  def encode(data)
+    # Your encoding logic
+  end
+
+  def decode(data)
+    # Your decoding logic
+  end
+end
+
+CursorPager.configure do |config|
+  config.encoder = CustomEncoder
+end
+```
+
+## Not (yet) supported
+
+* Ordering by SQL alias or function
+* Ordering by multiple columns in different directions
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub. This project is intended
+to be a safe, welcoming space for collaboration, and contributors are expected
+to adhere to the [code of conduct].
+
+
+## License
+
+The gem is available as open source under the terms of the [MIT License].
+
+[JSON API Cursor Pagination]: https://jsonapi.org/profiles/ethanresnick/cursor-pagination/
+[Relay's GraphQL Cursor Connection]: https://relay.dev/graphql/connections.htm
+[code of conduct]: https://github.com/askcharlie/cursor_pager/blob/master/CODE_OF_CONDUCT.md
+[MIT License]: https://opensource.org/licenses/MIT

data/Rakefile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+RSpec::Core::RakeTask.new(:spec)
+
+task default: %i[rubocop spec]
+
+namespace :db do
+  desc "Create the test DB"
+  task :create do
+    `createdb cursor_pager_test`
+  end
+
+  desc "Drop the test DB"
+  task :drop do
+    `dropdb cursor_pager_test`
+  end
+end

data/bin/console

@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'cursor_pager'
+
+# 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/cursor_pager.gemspec

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "lib/cursor_pager/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "cursor_pager"
+  spec.version       = CursorPager::VERSION
+  spec.authors       = ["Bastian Bartmann"]
+  spec.email         = ["bastian.bartmann@check24.de"]
+
+  spec.summary       = "Cursor-based pagination for ActiveRecord relations."
+  spec.homepage      = "https://github.com/askcharlie/cursor_pager"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.6.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] =
+    "https://github.com/askcharlie/cursor_pager/blob/master/CHANGELOG.md"
+
+  spec.files = Dir.chdir(File.expand_path(__dir__)) do
+    `git ls-files -z`
+      .split("\x0")
+      .reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency("activerecord", ">= 5.2.0")
+end

data/gemfiles/.bundle/config

@@ -0,0 +1,2 @@
+---
+BUNDLE_RETRY: "1"

data/gemfiles/activerecord_5.2.gemfile

@@ -0,0 +1,13 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "database_cleaner-active_record"
+gem "pg"
+gem "rake", "~> 12.0"
+gem "rspec", "~> 3.0"
+gem "rubocop"
+gem "activerecord", "~> 5.2.0"
+
+gemspec path: "../"

data/gemfiles/activerecord_5.2.gemfile.lock

@@ -0,0 +1,86 @@
+PATH
+  remote: ..
+  specs:
+    cursor_pager (0.1.0)
+      activerecord (>= 5.2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (5.2.4.2)
+      activesupport (= 5.2.4.2)
+    activerecord (5.2.4.2)
+      activemodel (= 5.2.4.2)
+      activesupport (= 5.2.4.2)
+      arel (>= 9.0)
+    activesupport (5.2.4.2)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+    appraisal (2.2.0)
+      bundler
+      rake
+      thor (>= 0.14.0)
+    arel (9.0.0)
+    ast (2.4.0)
+    concurrent-ruby (1.1.6)
+    database_cleaner (1.8.4)
+    database_cleaner-active_record (1.8.0)
+      activerecord
+      database_cleaner (~> 1.8.0)
+    diff-lcs (1.3)
+    i18n (1.8.2)
+      concurrent-ruby (~> 1.0)
+    jaro_winkler (1.5.4)
+    minitest (5.14.0)
+    parallel (1.19.1)
+    parser (2.7.1.1)
+      ast (~> 2.4.0)
+    pg (1.2.3)
+    rainbow (3.0.0)
+    rake (12.3.3)
+    rexml (3.2.4)
+    rspec (3.9.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+    rspec-core (3.9.1)
+      rspec-support (~> 3.9.1)
+    rspec-expectations (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.2)
+    rubocop (0.81.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.7.0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      rexml
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    ruby-progressbar (1.10.1)
+    thor (1.0.1)
+    thread_safe (0.3.6)
+    tzinfo (1.2.7)
+      thread_safe (~> 0.1)
+    unicode-display_width (1.7.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord (~> 5.2.0)
+  appraisal
+  cursor_pager!
+  database_cleaner-active_record
+  pg
+  rake (~> 12.0)
+  rspec (~> 3.0)
+  rubocop
+
+BUNDLED WITH
+   2.1.4

data/gemfiles/activerecord_6.0.gemfile

@@ -0,0 +1,13 @@
+# This file was generated by Appraisal
+
+source "https://rubygems.org"
+
+gem "appraisal"
+gem "database_cleaner-active_record"
+gem "pg"
+gem "rake", "~> 12.0"
+gem "rspec", "~> 3.0"
+gem "rubocop"
+gem "activerecord", "~> 6.0.0"
+
+gemspec path: "../"

data/gemfiles/activerecord_6.0.gemfile.lock

@@ -0,0 +1,86 @@
+PATH
+  remote: ..
+  specs:
+    cursor_pager (0.1.0)
+      activerecord (>= 5.2.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (6.0.2.2)
+      activesupport (= 6.0.2.2)
+    activerecord (6.0.2.2)
+      activemodel (= 6.0.2.2)
+      activesupport (= 6.0.2.2)
+    activesupport (6.0.2.2)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
+      minitest (~> 5.1)
+      tzinfo (~> 1.1)
+      zeitwerk (~> 2.2)
+    appraisal (2.2.0)
+      bundler
+      rake
+      thor (>= 0.14.0)
+    ast (2.4.0)
+    concurrent-ruby (1.1.6)
+    database_cleaner (1.8.4)
+    database_cleaner-active_record (1.8.0)
+      activerecord
+      database_cleaner (~> 1.8.0)
+    diff-lcs (1.3)
+    i18n (1.8.2)
+      concurrent-ruby (~> 1.0)
+    jaro_winkler (1.5.4)
+    minitest (5.14.0)
+    parallel (1.19.1)
+    parser (2.7.1.1)
+      ast (~> 2.4.0)
+    pg (1.2.3)
+    rainbow (3.0.0)
+    rake (12.3.3)
+    rexml (3.2.4)
+    rspec (3.9.0)
+      rspec-core (~> 3.9.0)
+      rspec-expectations (~> 3.9.0)
+      rspec-mocks (~> 3.9.0)
+    rspec-core (3.9.1)
+      rspec-support (~> 3.9.1)
+    rspec-expectations (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-mocks (3.9.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.9.0)
+    rspec-support (3.9.2)
+    rubocop (0.81.0)
+      jaro_winkler (~> 1.5.1)
+      parallel (~> 1.10)
+      parser (>= 2.7.0.1)
+      rainbow (>= 2.2.2, < 4.0)
+      rexml
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 1.4.0, < 2.0)
+    ruby-progressbar (1.10.1)
+    thor (1.0.1)
+    thread_safe (0.3.6)
+    tzinfo (1.2.7)
+      thread_safe (~> 0.1)
+    unicode-display_width (1.7.0)
+    zeitwerk (2.3.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord (~> 6.0.0)
+  appraisal
+  cursor_pager!
+  database_cleaner-active_record
+  pg
+  rake (~> 12.0)
+  rspec (~> 3.0)
+  rubocop
+
+BUNDLED WITH
+   2.1.4

data/lib/cursor_pager.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require "cursor_pager/version"
+
+module CursorPager
+  class Error < StandardError
+  end
+end
+
+require "cursor_pager/conflicting_orders_error"
+require "cursor_pager/cursor_not_found_error"
+require "cursor_pager/invalid_cursor_error"
+require "cursor_pager/order_value_error"
+
+require "cursor_pager/configuration"
+require "cursor_pager/base64_encoder"
+require "cursor_pager/order_value"
+require "cursor_pager/order_values"
+require "cursor_pager/limit_relation"
+require "cursor_pager/slice_relation"
+require "cursor_pager/page"

data/lib/cursor_pager/base64_encoder.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require "base64"
+
+module CursorPager
+  # Default encoder used to encode & decode cursors.
+  class Base64Encoder
+    class << self
+      def encode(data)
+        Base64.urlsafe_encode64(data)
+      end
+
+      def decode(data)
+        Base64.urlsafe_decode64(data)
+      rescue ArgumentError
+        raise InvalidCursorError, data
+      end
+    end
+  end
+end

data/lib/cursor_pager/configuration.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Top level module on which the configuration will be applied.
+module CursorPager
+  # Encapulates all the configuration for the library.
+  class Configuration
+    # The encoder that will be used to encode & decode cursors.
+    attr_accessor :encoder
+
+    def initialize
+      @encoder = Base64Encoder
+    end
+  end
+
+  def self.configuration
+    @configuration ||= Configuration.new
+  end
+
+  def self.configuration=(config)
+    @configuration = config
+  end
+
+  def self.reset
+    @configuration = Configuration.new
+  end
+
+  def self.configure
+    yield(configuration)
+  end
+end

data/lib/cursor_pager/conflicting_orders_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module CursorPager
+  # Will be raised when the relation is ordered by multiple attributes but in
+  # different directions.
+  class ConflictingOrdersError < Error
+    MESSAGE = <<~MESSAGE
+      Ordering by multiple attributes requires they are all ordered in the
+      same direction.
+    MESSAGE
+
+    def initialize
+      super(MESSAGE)
+    end
+  end
+end

data/lib/cursor_pager/cursor_not_found_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module CursorPager
+  # Will be raised when the cursor's record couldn't be found in the relation.
+  class CursorNotFoundError < Error
+    def initialize(cursor)
+      message = "Couldn't find item for cursor: #{cursor}."
+
+      super(message)
+    end
+  end
+end

data/lib/cursor_pager/invalid_cursor_error.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module CursorPager
+  # Will be raise when the cursor couldn't be parsed.
+  class InvalidCursorError < Error
+    def initialize(cursor)
+      message = "Couldn't parse cursor: #{cursor}."
+
+      super(message)
+    end
+  end
+end

data/lib/cursor_pager/limit_relation.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module CursorPager
+  # Applies first and last limits to a relation.
+  class LimitRelation
+    attr_reader :base_relation, :first, :last
+
+    def initialize(base_relation, first, last)
+      @base_relation = base_relation
+      @first = first
+      @last = last
+    end
+
+    def call
+      relation = base_relation
+
+      relation = apply_first(relation) if first.present?
+      relation = apply_last(relation) if last.present?
+
+      relation
+    end
+
+    private
+
+    # Apply first if it sets a stricter limit than the one already applied
+    def apply_first(relation)
+      previous_limit = relation.limit_value
+
+      if previous_limit.nil? || previous_limit > first
+        relation.limit(first)
+      else
+        relation
+      end
+    end
+
+    # Apply last if it's a smaller slice than the previous limit
+    def apply_last(relation)
+      previous_limit = relation.limit_value
+
+      if previous_limit.present?
+        if last <= previous_limit
+          relation = apply_stricter_last(relation, previous_limit)
+        end
+      else
+        relation = apply_last_withouth_previous_limit(relation)
+      end
+
+      relation
+    end
+
+    def apply_stricter_last(relation, previous_limit)
+      offset = (relation.offset_value || 0) + (previous_limit - last)
+
+      relation.offset(offset).limit(last)
+    end
+
+    def apply_last_withouth_previous_limit(relation)
+      count = base_relation.size
+      previous_offset = relation.offset_value || 0
+      offset = previous_offset + count - [last, count].min
+
+      relation.offset(offset).limit(last)
+    end
+  end
+end

data/lib/cursor_pager/order_value.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module CursorPager
+  # Wraps ActiveRecord's order values.
+  # Depending on how the order of the relation is defined, ActiveRecord will
+  # give you multiple arel nodes or just one string. This deals with the
+  # differences so we don't have to do it anywhere else.
+  class OrderValue
+    PARENTHESIS_REGEX = /[\(\)]/.freeze
+
+    attr_reader :attribute, :direction
+
+    def self.from_arel_node(relation, node)
+      new(relation, node.value.name, node.direction)
+    end
+
+    def self.from_order_string(relation, value)
+      if value.match?(PARENTHESIS_REGEX)
+        raise OrderValueError, "Order values can't include functions."
+      end
+
+      value.split(",").map do |split_value|
+        new(relation, *split_value.squish.split)
+      end
+    end
+
+    def initialize(relation, attribute, direction = :asc)
+      @relation = relation
+      @attribute = attribute
+      @direction = direction.downcase.to_sym
+    end
+
+    def primary_key?
+      relation.primary_key == attribute
+    end
+
+    def type
+      relation.type_for_attribute(attribute).type
+    end
+
+    def prefixed_attribute
+      return attribute if attribute.include?(".")
+
+      "#{relation.table_name}.#{attribute}"
+    end
+
+    def select_alias
+      prefixed_attribute.tr(".", "_")
+    end
+
+    def select_string
+      "#{prefixed_attribute} AS #{select_alias}"
+    end
+
+    def order_string
+      "#{prefixed_attribute} #{direction}"
+    end
+
+    private
+
+    attr_reader :relation
+  end
+end

data/lib/cursor_pager/order_value_error.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module CursorPager
+  class OrderValueError < Error
+  end
+end

data/lib/cursor_pager/order_values.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+module CursorPager
+  # OrderValue collection wrapper.
+  class OrderValues
+    extend Forwardable
+    include Enumerable
+
+    def_delegators :@collection, :each, :<<, :size, :present?
+
+    # A relation's order_values can either be an empty array, an array including
+    # just one string, or an array of arel ordering nodes.
+    def self.from_relation(relation)
+      arel_order_values = relation.order_values.uniq.reject(&:blank?)
+      collection = arel_order_values.flat_map do |value|
+        case value
+        when Arel::Nodes::Ordering
+          OrderValue.from_arel_node(relation, value)
+        when String
+          OrderValue.from_order_string(relation, value)
+        end
+      end
+
+      new(collection)
+    end
+
+    def initialize(collection = [])
+      @collection = collection
+    end
+
+    def direction
+      @collection.first&.direction
+    end
+
+    def order_string
+      @collection.map(&:order_string).join(", ")
+    end
+  end
+end

data/lib/cursor_pager/page.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module CursorPager
+  # The main class that coordinates the whole pagination.
+  class Page
+    attr_reader :relation, :first, :last, :after, :before, :order_values
+
+    def initialize(relation, first: nil, last: nil, after: nil, before: nil)
+      @relation = relation
+      @first = first
+      @last = last
+      @after = after
+      @before = before
+      @order_values = OrderValues.from_relation(relation)
+
+      add_default_order
+      verify_order_directions!
+    end
+
+    def previous_page?
+      @previous_page ||= if after_limit_value.present?
+                           true
+                         elsif last
+                           limited_relation.offset_value.to_i.positive?
+                         else
+                           false
+                         end
+    end
+
+    def next_page?
+      @next_page ||= if before_limit_value.present?
+                       true
+                     elsif first
+                       sliced_relation.limit(first + 1).count == first + 1
+                     else
+                       false
+                     end
+    end
+
+    def cursor_for(item)
+      encoder.encode(item.id.to_s)
+    end
+
+    def records
+      @records ||= limited_relation.to_a
+    end
+
+    private
+
+    def add_default_order
+      return if sufficiently_ordered?
+
+      direction = order_values.direction || :asc
+
+      @order_values << OrderValue.new(relation, relation.primary_key, direction)
+    end
+
+    def sufficiently_ordered?
+      order_values.present? && order_values.all? do |value|
+        value.primary_key? || value.type == :datetime
+      end
+    end
+
+    def verify_order_directions!
+      return if order_values.map(&:direction).uniq.size == 1
+
+      raise ConflictingOrdersError
+    end
+
+    def limited_relation
+      @limited_relation ||= LimitRelation.new(sliced_relation, first, last).call
+    end
+
+    def sliced_relation
+      @sliced_relation ||= SliceRelation.new(
+        ordered_relation,
+        order_values,
+        after_limit_value,
+        before_limit_value
+      ).call
+    end
+
+    def ordered_relation
+      @ordered_relation ||= relation.reorder(order_values.order_string)
+    end
+
+    def before_limit_value
+      @before_limit_value ||= before.present? && limit_value_for(before)
+    end
+
+    def after_limit_value
+      @after_limit_value ||= after.present? && limit_value_for(after)
+    end
+
+    def limit_value_for(cursor)
+      id = encoder.decode(cursor)
+
+      selects = order_values.map(&:select_string)
+      item = relation.where(id: id).select(selects).first
+
+      raise CursorNotFoundError, cursor if item.blank?
+
+      order_values.map { |value| item[value.select_alias] }
+    end
+
+    def encoder
+      CursorPager.configuration.encoder
+    end
+  end
+end

data/lib/cursor_pager/slice_relation.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module CursorPager
+  # Applies after and before cursors to a relation.
+  class SliceRelation
+    attr_reader :base_relation, :order_values, :after_values, :before_values
+
+    def initialize(base_relation, order_values, after_values, before_values)
+      @base_relation = base_relation
+      @order_values = order_values
+      @after_values = after_values
+      @before_values = before_values
+    end
+
+    def call
+      relation = base_relation
+
+      relation = apply_after(relation)
+      relation = apply_before(relation)
+
+      relation
+    end
+
+    private
+
+    def apply_after(relation)
+      return relation if after_values.blank?
+
+      if order_values.direction == :asc
+        slice_relation(relation, ">", after_values)
+      else
+        slice_relation(relation, "<", after_values)
+      end
+    end
+
+    def apply_before(relation)
+      return relation if before_values.blank?
+
+      if order_values.direction == :asc
+        slice_relation(relation, "<", before_values)
+      else
+        slice_relation(relation, ">", before_values)
+      end
+    end
+
+    def slice_relation(relation, operator, value)
+      slice_attribute = order_values.map(&:prefixed_attribute).join(", ")
+
+      relation.where("(#{slice_attribute}) #{operator} (?)", value)
+    end
+  end
+end

data/lib/cursor_pager/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module CursorPager
+  VERSION = "0.1.0"
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: cursor_pager
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Bastian Bartmann
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-04-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 5.2.0
+description: 
+email:
+- bastian.bartmann@check24.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".github/workflows/ci.yml"
+- ".gitignore"
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- ".travis.yml"
+- Appraisals
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- cursor_pager.gemspec
+- gemfiles/.bundle/config
+- gemfiles/activerecord_5.2.gemfile
+- gemfiles/activerecord_5.2.gemfile.lock
+- gemfiles/activerecord_6.0.gemfile
+- gemfiles/activerecord_6.0.gemfile.lock
+- lib/cursor_pager.rb
+- lib/cursor_pager/base64_encoder.rb
+- lib/cursor_pager/configuration.rb
+- lib/cursor_pager/conflicting_orders_error.rb
+- lib/cursor_pager/cursor_not_found_error.rb
+- lib/cursor_pager/invalid_cursor_error.rb
+- lib/cursor_pager/limit_relation.rb
+- lib/cursor_pager/order_value.rb
+- lib/cursor_pager/order_value_error.rb
+- lib/cursor_pager/order_values.rb
+- lib/cursor_pager/page.rb
+- lib/cursor_pager/slice_relation.rb
+- lib/cursor_pager/version.rb
+homepage: https://github.com/askcharlie/cursor_pager
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/askcharlie/cursor_pager
+  source_code_uri: https://github.com/askcharlie/cursor_pager
+  changelog_uri: https://github.com/askcharlie/cursor_pager/blob/master/CHANGELOG.md
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: Cursor-based pagination for ActiveRecord relations.
+test_files: []