ar_pagination 0.0.7

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5393edb9113a17c5b78f4649638852b8576e16a1
+  data.tar.gz: bc89aaaaf25316e4adae150274652ba844bff02c
+SHA512:
+  metadata.gz: 19734ea986f4d68b53f4ec410d18003a407b84d76b8f8ed3907491584a22e102d36a2939f9920a96388e09c8d4a7283ef16dfc3eb9df8e6cbc9350f508345860
+  data.tar.gz: 677c5c351073647f5a849240127d50687fa6e151df907659139323a0c76d23b765af8041d7e1bcd3ba35bfd0e8fa0d41927b9e09eda2f0f1e782f9e23e83eda0

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+/spec/dummy/log/

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--require spec_helper

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in ar_pagination.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2015 Madeline Carson
+
+MIT License
+
+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,86 @@
+# ArPagination
+
+Active Record Pagination is a gem that allows simple pagination for your api's resource endpoint responses.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'ar_pagination'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install ar_pagination
+
+## Usage
+
+### Cursor Pagination
+
+The cursor is the value of an attribute you would like to fetch a number of resources before/after.
+
+Add the following to your controller:
+
+Query params:
+
+```
+def query_params
+  validate_range!(:count, 1..100)
+  query_params = params.permit(:cursor, :count, :sort) #sort is like: "+age,-name" to sort first by age ascending and name descending
+  query_params
+end
+```
+
+Include the concern:
+
+```
+class SomeController < ActionController::Base
+include ArPagination::RespondWithPage
+```
+
+Use for the response
+
+```
+def index
+  ...
+  @page = ArPagination::CursorPagination::Query.new(@resource_scope).fetch(query_params)
+
+  respond_with_page @page
+end
+```
+
+### Offset Pagination
+
+The offset specifies the number of resources to fetch the count number of resources after.
+
+Add the query params to your controller:
+
+```
+def query_params
+  validate_range!(:count, 1...100)
+  query_params = params.permit(:count, :offset, :sort)
+  query_params
+end
+```
+
+Use in your endpoint method, similar to:
+
+```
+def index
+  ...
+  respond_with_page @page = OffsetPagination::Page.new(@resource_scope, query_params)
+end
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/[my-github-username]/ar_pagination/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/ar_pagination.gemspec

@@ -0,0 +1,28 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ar_pagination/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "ar_pagination"
+  spec.version       = ArPagination::VERSION
+  spec.authors       = ["Madeline Carson"]
+  spec.email         = ["madeline.carson@gmail.com"]
+  spec.summary       = %q{Pagination for Rails controllers. Includes cursor pagination and offset pagination.}
+  spec.description   = %q{Pagination for Rails controllers.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rspec-rails"
+  spec.add_development_dependency "rails"
+  spec.add_development_dependency "pg"
+  spec.add_development_dependency "activesupport"
+end

data/lib/ar_pagination.rb

@@ -0,0 +1,10 @@
+require "ar_pagination/version"
+
+require "ar_pagination/respond_with_page.rb"
+require "ar_pagination/cursor_pagination/page.rb"
+require "ar_pagination/cursor_pagination/query.rb"
+require "ar_pagination/offset_pagination/page.rb"
+
+module ArPagination
+  # ...
+end

data/lib/ar_pagination/cursor_pagination/page.rb

@@ -0,0 +1,41 @@
+module ArPagination::CursorPagination
+  class Page
+
+    attr_reader :count
+    attr_accessor :first, :last
+
+    # param [Array] window in current window
+    # param [Fixnum] cursor previous cursor
+    # option [Fixnum] count
+    def initialize(window, cursor, cursor_key, count: 20)
+      @window = window
+      @cursor = cursor
+      @cursor_key = cursor_key
+      @count = count
+    end
+
+    def data
+      @window[1..-2]
+    end
+
+    def next
+      @window.last.nil? ? nil : @window.last.try(@cursor_key)
+    end
+
+    def prev
+      @window.first.nil? ? nil : @window.first.try(@cursor_key)
+    end
+
+    def params_for(dir)
+      case dir
+      when :first
+        { cursor: cursor, count: @count }
+      when :next
+        { cursor: self.next, count: @count }
+      when :prev
+        { cursor: self.prev, count: @count }
+      end
+    end
+
+  end
+end

data/lib/ar_pagination/cursor_pagination/query.rb

@@ -0,0 +1,77 @@
+require "ar_pagination/helpers/sort"
+
+module ArPagination::CursorPagination
+  class Query
+
+    # @param [ActiveRecord::Relation] scope inwhich to find current page
+    # @option [Symbol] scope `:id` key to use for the cursor
+    def initialize(scope, cursor_key = :id)
+      @scope = scope
+      @cursor_key = cursor_key
+    end
+
+    # Fetch record for given cursor
+    #
+    # @see https://dev.twitter.com/overview/api/cursoring
+    # @option [Fixnum] cursor
+    # @option [Fixnum] count
+    # @return [Pagination::Page] dataset including next&prev cursors
+    def fetch(cursor: -1, count: 50, sort: "")
+
+      # 1. sort if required
+      @scope = ArPagination::Helpers::Sort.new(@scope).sort(sort)
+
+      # 2. only need array of cursor keys from scope
+      scope_keyed = @scope.pluck(@cursor_key)
+
+      cursor = 0 if cursor == -1
+
+      # check direction
+      window =
+        if cursor.to_s.first == "-"
+          cursor = cursor.is_a?(Integer) ? cursor.abs : cursor.to_s[1..-1]
+          backward(@scope, scope_keyed.index(cursor), count)
+        else
+          forward(@scope, scope_keyed.index(cursor), count)
+        end
+
+      Page.new(window, cursor, @cursor_key, count: count)
+    end
+
+    private
+
+    def forward(scope, cursor_index, count)
+      if cursor_index == 0
+        if count < scope.size # Index at count elements is not the end
+          return scope[cursor_index..count].unshift(nil)
+        else
+          return scope[cursor_index..(count-1)].unshift(nil).push(nil)
+        end
+      end
+
+      if count >= (scope.size - cursor_index)
+        return scope[(cursor_index - 1)..-1].push(nil)
+      end
+
+      return scope[(cursor_index - 1)..(count + 1)]
+    end
+
+    def backward(scope, cursor_index, count)
+      if (cursor_index + 1) - count <= 0 # check the returned data elements will include the first element in scope
+        if (cursor_index + 1) == scope.size # cursor is last element in array
+          return scope[0..cursor_index].unshift(nil).push(nil)
+        else
+          return scope[0..(cursor_index+1)].unshift(nil)
+        end
+      end
+
+      # Check if cursor element is the last element
+      if (cursor_index + 1) == scope.size # cursor is last element in array
+        return scope[(cursor_index - count)..cursor_index].push(nil)
+      end
+
+      return scope[(cursor_index - count)..cursor_index+1]
+    end
+
+  end
+end

data/lib/ar_pagination/helpers/sort.rb

@@ -0,0 +1,28 @@
+module ArPagination::Helpers
+  class Sort
+
+    def initialize(scope)
+      @scope = scope
+    end
+
+    def sort(sort)
+      order_hash = {}
+      order_options = sort.split(',') if sort
+      Array.wrap(order_options).each do |order_option|
+        case order_option.first
+        when '-'
+          direction = :desc
+        when '+'
+          direction = :asc
+        else
+          next
+        end
+        sort_attr = order_option[1..-1]
+        order_hash[sort_attr.to_sym] = direction
+      end
+      @scope = @scope.order(order_hash) unless order_hash.empty?
+      @scope
+    end
+
+  end
+end

data/lib/ar_pagination/offset_pagination/page.rb

@@ -0,0 +1,31 @@
+require "ar_pagination/helpers/sort"
+
+module ArPagination::OffsetPagination
+  class Page
+
+    def initialize(scope, options = {})
+      @scope = scope
+      @limit = Integer(options[:limit] || options[:count] || 50)
+      @offset = Integer(options[:offset] || 0)
+      @sort = options[:sort]
+    end
+
+    def data
+      @scope = ArPagination::Helpers::Sort.new(@scope).sort(@sort)
+
+      @scope.offset(@offset).limit(@limit)
+    end
+
+    def params_for(direction)
+      case direction
+      when :first
+        { offset: 0, count: @limit }
+      when :next
+        { offset: @limit + @offset, count: @limit }
+      when :prev
+        @limit > @offset ? { offset: @limit - @offset, count: @limit } : {}
+      end
+    end
+
+  end
+end

data/lib/ar_pagination/respond_with_page.rb

@@ -0,0 +1,30 @@
+module ArPagination::RespondWithPage
+  extend ActiveSupport::Concern
+
+  private
+
+  def respond_with_page(page)
+    render json: {
+      data:  serialize_page(page),
+      links: {
+        first: build_url_for(page, :first),
+        last:  nil, # @note find efficient way if needed
+        next:  build_url_for(page, :next),
+        prev:  build_url_for(page, :prev)
+      }
+    }
+  end
+
+  def serialize_page(page)
+    ActiveModel::ArraySerializer.new(page.data, url_options: url_options, scope: current_user)
+  end
+
+  def query_options
+    params.slice(:count, :offset, :cursor)
+  end
+
+  def build_url_for(page, direction)
+    url_params = page.params_for(direction)
+    url_for(url_params.reverse_merge(params)) if url_params[:cursor]
+  end
+end

data/lib/ar_pagination/version.rb

@@ -0,0 +1,3 @@
+module ArPagination
+  VERSION = "0.0.7"
+end

data/spec/dummy/README.rdoc

@@ -0,0 +1,28 @@
+== README
+
+This README would normally document whatever steps are necessary to get the
+application up and running.
+
+Things you may want to cover:
+
+* Ruby version
+
+* System dependencies
+
+* Configuration
+
+* Database creation
+
+* Database initialization
+
+* How to run the test suite
+
+* Services (job queues, cache servers, search engines, etc.)
+
+* Deployment instructions
+
+* ...
+
+
+Please feel free to use a different markup language if you do not plan to run
+<tt>rake doc:app</tt>.

data/spec/dummy/Rakefile

@@ -0,0 +1,6 @@
+# Add your own tasks in files placed in lib/tasks ending in .rake,
+# for example lib/tasks/capistrano.rake, and they will automatically be available to Rake.
+
+require File.expand_path('../config/application', __FILE__)
+
+Rails.application.load_tasks