seek 0.0.1

data/README.md

@@ -0,0 +1,32 @@
+[![Build Status](https://travis-ci.org/bukowskis/seek.png)](https://travis-ci.org/bukowskis/seek)
+
+# Seek
+
+Sanitizes pagination and sorting options in a reusable and serializable way.
+
+# Installation
+
+```ruby
+gem install seek
+```
+
+# Examples
+
+```ruby
+params = { page: '4', sort_order: 'desc', per_page: '1000' }
+
+seek = Seek.new params,
+       valid_sort_bys: %w{ first_name, last_name, age },
+       max_per_page: 50,
+       default_sort_by: :age,
+       default_sort_order: :asc
+
+seek.page       #=> 4
+seek.per_page   #=> 50
+seek.sort_by    #=> 'age'
+seek.sort_order #=> 'desc
+seek.order      #=> 'age desc'
+
+seek.to_hash
+  #=> Returns a Hash with all the parameters listed above.
+```

data/lib/seek.rb

@@ -0,0 +1,36 @@
+require 'seek/configuration'
+require 'seek/pagination'
+require 'seek/sorting'
+require 'seek/tools'
+require 'seek/version'
+
+class Seek
+  include Pagination
+  include Sorting
+
+  attr_reader :options
+
+  def initialize(params = {}, options = {})
+    params  = params ? Tools.symbolize_keys(params) : {}
+    options = options ? Tools.symbolize_keys(options) : {}
+    self.page         = params[:page]
+    self.per_page     = params[:per_page]
+    self.sort_by      = params[:sort_by]
+    self.sort_order   = params[:sort_order]
+    self.max_per_page       = options[:max_per_page]
+    self.valid_sort_bys     = options[:valid_sort_bys]
+    self.default_sort_by    = options[:default_sort_by]
+    self.default_sort_order = options[:default_sort_order]
+  end
+
+  def to_hash
+    {
+      page: page,
+      per_page: per_page,
+      sort_by: sort_by,
+      sort_order: sort_order,
+      order: order,
+    }
+  end
+
+end

data/lib/seek/configuration.rb

@@ -0,0 +1,40 @@
+class Seek
+  class Configuration
+
+    attr_writer :default_per_page, :default_max_per_page
+
+    def default_per_page
+      Positify.it {
+        @default_per_page ||= 20
+      }
+    end
+
+    def default_max_per_page
+      Positify.it {
+        @default_max_per_page ||= 100
+      }
+    end
+
+  end
+end
+
+class Seek
+
+  # Public: Returns the the configuration instance.
+  #
+  def self.config
+    @config ||= Configuration.new
+  end
+
+  # Public: Yields the configuration instance.
+  #
+  def self.configure(&block)
+    yield config
+  end
+
+  # Public: Reset the configuration (useful for testing)
+  #
+  def self.reset!
+    @config = nil
+  end
+end

data/lib/seek/pagination.rb

@@ -0,0 +1,25 @@
+require 'positify'
+
+class Seek
+  module Pagination
+
+    attr_writer :page, :per_page, :max_per_page
+
+    def page
+      Positify.it @page
+    end
+
+    def per_page
+      Positify.it @per_page, max: max_per_page
+    end
+
+    def max_per_page
+      if @max_per_page.to_i > 0
+        @max_per_page.to_i
+      else
+        self.class.config.default_max_per_page
+      end
+    end
+
+  end
+end

data/lib/seek/sorting.rb

@@ -0,0 +1,57 @@
+class Seek
+  module Sorting
+
+    attr_writer :sort_by, :sort_order, :valid_sort_bys, :default_sort_by, :default_sort_order
+
+    # Returns true if sort_by and sort_order are present.
+    #
+    def sortable?
+      !!order
+    end
+
+    # Returns a String or nil.
+    #
+    def sort_by
+      result = @sort_by.to_s.downcase
+      return result if !result.empty? && (valid_sort_bys.empty? || valid_sort_bys.include?(result))
+      default_sort_by
+    end
+
+    def sort_order
+      result = @sort_order.to_s.downcase
+      valid_sort_orders.include?(result) ? result : valid_sort_orders.first
+    end
+
+    # Useful for queries that require the format "first_name desc" (such as SQL or lucene)
+    #
+    # Returns a String or nil
+    #
+    def order
+      return if sort_by.to_s.empty?
+      [sort_by, sort_order].join(' ')
+    end
+
+    def valid_sort_bys
+      Array(@valid_sort_bys).map(&:to_s).map(&:downcase)
+    end
+
+    # Returns a String or nil.
+    #
+    def default_sort_by
+      result = @default_sort_by.to_s.downcase
+      valid_sort_bys.include?(result) ? result : valid_sort_bys.first
+    end
+
+    def default_sort_order
+      result = @default_sort_order.to_s.downcase
+      valid_sort_orders.include?(result) ? result : valid_sort_orders.first
+    end
+
+    private
+
+    def valid_sort_orders
+      %w{ asc desc }
+    end
+
+  end
+end

data/lib/seek/tools.rb

@@ -0,0 +1,13 @@
+class Seek
+  module Tools
+
+    def self.symbolize_keys(hash)
+      result = hash.dup
+      result.keys.each do |key|
+        result[(key.to_sym rescue key) || key] = result.delete(key)
+      end
+      result
+    end
+
+  end
+end

data/lib/seek/version.rb

@@ -0,0 +1,9 @@
+class Seek
+  module VERSION
+    MAJOR = 0
+    MINOR = 0
+    TINY  = 1
+
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

data/spec/lib/seek/tools_spec.rb

@@ -0,0 +1,14 @@
+require 'spec_helper'
+
+describe Seek::Tools do
+
+  let(:original) { { 'one' => 1, two: 2 } }
+
+  describe '.symbolize_keys' do
+    it 'symbolizes String keys in a hash' do
+      Seek::Tools.symbolize_keys(original).should == { one: 1, two: 2 }
+      original.should == { 'one' => 1, two: 2 }
+    end
+  end
+
+end

data/spec/lib/seek_spec.rb

@@ -0,0 +1,116 @@
+require 'spec_helper'
+
+describe Seek do
+
+  let(:params)  { { page: 4, per_page: 20, 'sort_by' => :first_name, sort_order: 'DESC' } }
+  let(:options) { { 'max_per_page' => 30, valid_sort_bys: %w{ age first_name last_name } } }
+
+  let(:seek)    { Seek.new params, options }
+
+  context 'pagination' do
+    describe 'page' do
+      it 'comes from the params' do
+        seek.page.should == 4
+      end
+
+      it 'is has a positive attitude' do
+        seek = Seek.new params.merge page: 'what?'
+        seek.page.should == 1
+      end
+    end
+
+    describe '#per_page' do
+      it 'comes from the params' do
+        seek.per_page.should == 20
+      end
+
+      it 'limits the maximum' do
+        seek = Seek.new params, max_per_page: 15
+        seek.per_page.should == 15
+      end
+
+      it 'does not become negative on weird values' do
+        seek = Seek.new params.merge(per_page: 'what?')
+        seek.per_page.should == 1
+      end
+    end
+
+    describe '#max_per_page' do
+      it 'defaults to the global configuration' do
+        Seek.new.max_per_page.should == 100
+      end
+
+      it 'prefers the options' do
+        seek.max_per_page.should == 30
+      end
+    end
+  end
+
+  context 'sorting' do
+    describe '#sort_by' do
+      it 'comes from the params and is a String' do
+        seek.sort_by.should == 'first_name'
+      end
+
+      it 'defaults to the first valid sort_by' do
+        seek = Seek.new nil, options
+        seek.sort_by.should == 'age'
+      end
+
+      it 'accepts only valid values if the valid ones are specified' do
+        seek = Seek.new({ sort_by: 'size'} , options)
+        seek.sort_by.should == 'age'
+      end
+
+      it 'accepts invalid values if no valid ones are specified' do
+        seek = Seek.new sort_by: 'width'
+        seek.sort_by.should == 'width'
+      end
+
+      it 'is nil if there is no sort_by' do
+        Seek.new.sort_by.should be_nil
+      end
+    end
+
+    describe '#sort_order' do
+      it 'comes from the params and is a String' do
+        seek.sort_order.should == 'desc'
+      end
+
+      it 'is ascending if nothing is specified' do
+        Seek.new.sort_order.should == 'asc'
+      end
+
+      it 'is ascending if something invalid is specified' do
+        Seek.new(sort_order: 'vertically').sort_order.should == 'asc'
+      end
+    end
+  end
+
+  describe '#order' do
+    it 'is sort_by and sort_order separated by a space' do
+      seek.order.should == 'first_name desc'
+    end
+
+    it 'is nil if there is no sort_by' do
+      Seek.new.order.should be_nil
+    end
+  end
+
+  describe '#sortable?' do
+    it 'is true if there is sort_by and sort_order' do
+      seek.should be_sortable
+    end
+
+    it 'is nil if there is no sort_by' do
+      Seek.new.should_not be_sortable
+    end
+  end
+
+  describe '#to_hash' do
+    it 'contains all params' do
+      seek.to_hash.should == { page: 4, per_page: 20, sort_by: 'first_name', sort_order: 'desc', order: 'first_name desc' }
+    end
+  end
+
+end

data/spec/spec_helper.rb

@@ -0,0 +1 @@
+require 'seek'

metadata

@@ -0,0 +1,122 @@
+--- !ruby/object:Gem::Specification
+name: seek
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- bukowskis
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-04-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: positify
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.0.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.0.1
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: guard-rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rb-fsevent
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A sanitizer for pagination and sorting options. It is supposed to help
+  unify passing search options via cross-application APIs.
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/seek/configuration.rb
+- lib/seek/pagination.rb
+- lib/seek/sorting.rb
+- lib/seek/tools.rb
+- lib/seek/version.rb
+- lib/seek.rb
+- spec/lib/seek/tools_spec.rb
+- spec/lib/seek_spec.rb
+- spec/spec_helper.rb
+- README.md
+homepage: https://github.com/bukowskis/seek
+licenses:
+- MIT
+post_install_message: 
+rdoc_options:
+- --encoding
+- UTF-8
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.23
+signing_key: 
+specification_version: 3
+summary: A sanitizer for pagination and sorting options.
+test_files: []