openstax_utilities 4.1.0 → 4.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5f74a54eb979770038bb0b7a22dd9ab49c7d0bd7
-  data.tar.gz: 24be3a1eba292de415db675f55c93fcb127bf693
+  metadata.gz: 7336e5f9c9952756f9a981da7b79d5dece466022
+  data.tar.gz: e6a8621a11547eae03d63fc0d94e05053cc86664
 SHA512:
-  metadata.gz: 3cd0d23114ea4b34234afab28e67ee749af4150a50510fc85c12ec740a10a45518be29405ca8a350ee713eda378850e205394207d3d09ee74ae4c68ab6fac132
-  data.tar.gz: 77855c34ee526501c39e723164036aa2af493cb473fb4f7c68b481795844641ca6170ed8da1f39a5c6b5a15cdd99bd42ebce9b5d7f379823330f2209bc6598e8
+  metadata.gz: 7b17cb61f65fe32b021ce90b736ff163fedc34ffcb3173f9ba0af024d165a4b53ea586547df15cda7b3d787bcf2afc3cf5a2c39a69ce1bc546ddce1056c6a6cf
+  data.tar.gz: a5a03f359924bc9de55fd70e3b433fd3ef84dbed7c94d1c7ff40e802b1c5cc65d452a6bf09d77198872d94f82f3e3da6ca65a773f1becd7d6b003a122605c16c

data/app/routines/openstax/utilities/limit_and_paginate_relation.rb

@@ -0,0 +1,85 @@
+# Database-agnostic search result limiting and pagination routine
+#
+# Counts the number of items in a relation and empties it
+# if the number exceeds the specified absolute maximum
+# Otherwise, applies the specified pagination
+#
+# Callers of this routine provide the relation argument and
+# may provide the max_items, per_page and page arguments
+#
+# Required arguments:
+#
+#   Developer-supplied:
+#
+#   relation  - the ActiveRecord::Relation to be limited or paginated
+#
+# Optional arguments:
+#
+#   Developer-supplied:
+#
+#   max_items - the maximum allowed number of search results
+#               default: nil (disabled)
+#
+#   User or developer-supplied:
+#
+#   per_page  - the maximum number of search results per page
+#               default: nil (disabled)
+#   page      - the number of the page to return
+#               default: 1
+#
+# This routine's outputs contain:
+#
+#   outputs[:total_count] - the total number of items in the relation
+#   outputs[:items]       - the original relation after it has
+#                           potentially been emptied or paginated
+
+require 'lev'
+
+module OpenStax
+  module Utilities
+    class LimitAndPaginateRelation
+
+      lev_routine transaction: :no_transaction
+
+      protected
+
+      def exec(*args)
+
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        relation = options[:relation] || args[0]
+        max_items = options[:max_items] || nil
+        per_page = Integer(options[:per_page]) rescue nil
+        page = Integer(options[:page]) rescue 1
+
+        raise ArgumentError, 'You must specify a :relation option' \
+          if relation.nil?
+
+        fatal_error(offending_inputs: :per_page,
+                    message: 'Invalid page size',
+                    code: :invalid_per_page) if !per_page.nil? && per_page < 1
+        fatal_error(offending_inputs: :page,
+                    message: 'Invalid page number',
+                    code: :invalid_page) if page < 1
+
+        outputs[:total_count] = relation.count
+
+        if !max_items.nil? && outputs[:total_count] > max_items
+          # Limiting
+          relation = relation.none
+          nonfatal_error(code: :too_many_items,
+                         message: "The number of matches exceeded the allowed limit of #{
+                           max_items} matches. Please refine your query and try again.")
+        elsif per_page.nil?
+          relation = relation.none if page > 1
+        else
+          # Pagination
+          relation = relation.limit(per_page).offset(per_page*(page-1))
+        end
+
+        outputs[:items] = relation
+      end
+
+    end
+
+  end
+end

data/app/routines/openstax/utilities/order_relation.rb

@@ -0,0 +1,105 @@
+# Database-agnostic search result ordering routine
+#
+# Performs ordering of search results
+#
+# Callers of this routine provide the relation,
+# sortable_fields and order_by arguments
+#
+# Required arguments:
+#
+#   Developer-supplied:
+#
+#   relation        - the ActiveRecord::Relation to be ordered
+#
+#   sortable_fields - list of fields that can appear in the order_by argument
+#                     can be a Hash that maps field names to database columns
+#                     or an Array of Strings
+#                     invalid fields in order_by will be replaced with
+#                     the first field listed here, in :asc order
+#
+# Optional arguments:
+#
+#   User or developer-supplied:
+#
+#   order_by        - list of fields to order by, with optional sort directions
+#                     can be (an Array of) Hashes, or Strings
+#                     default: {sortable_fields.values.first => :asc}
+#
+# This routine's outputs contain:
+#
+#   outputs[:items] - a relation containing the ordered records
+
+require 'lev'
+
+module OpenStax
+  module Utilities
+    class OrderRelation
+
+      lev_routine transaction: :no_transaction
+
+      protected
+
+      def exec(*args)
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        relation = options[:relation] || args[0]
+        sortable_fields = options[:sortable_fields] || args[1]
+        order_by = options[:order_by] || args[2]
+
+        raise ArgumentError, 'You must specify a :relation option' \
+          if relation.nil?
+        raise ArgumentError, 'You must specify a :sortable_fields option' \
+          if sortable_fields.nil?
+
+        # Convert sortable_fields to Hash if it's an Array
+        sortable_fields = Hash[*sortable_fields.collect{|s| [s.to_s, s]}] \
+          if sortable_fields.is_a? Array
+
+        # Ordering
+        order_bys = sanitize_order_bys(sortable_fields, order_by)
+        outputs[:items] = relation.order(order_bys)
+      end
+
+      # Returns an order_by Object
+      def sanitize_order_by(sortable_fields, field = nil, dir = nil)
+        sanitized_field = sortable_fields[field.to_s.downcase] || \
+                            sortable_fields.values.first
+        sanitized_dir = dir.to_s.downcase == 'desc' ? :desc : :asc
+        case sanitized_field
+        when Symbol
+          {sanitized_field => sanitized_dir}
+        when Arel::Attributes::Attribute
+          sanitized_field.send sanitized_dir
+        else
+          "#{sanitized_field.to_s} #{sanitized_dir.to_s.upcase}"
+        end
+      end
+
+      # Returns an Array of order_by Objects
+      def sanitize_order_bys(sortable_fields, order_bys = nil)
+        obs = case order_bys
+        when Array
+          order_bys.collect do |ob|
+            case ob
+            when Hash
+              sanitize_order_by(sortable_fields, ob.keys.first, ob.values.first)
+            when Array
+              sanitize_order_by(sortable_fields, ob.first, ob.second)
+            else
+              sanitize_order_by(sortable_fields, ob)
+            end
+          end
+        when Hash
+          order_bys.collect { |k, v| sanitize_order_by(sortable_fields, k, v) }
+        else
+          order_bys.to_s.split(',').collect do |ob|
+            fd = ob.split(' ')
+            sanitize_order_by(sortable_fields, fd.first, fd.second)
+          end
+        end
+        obs.blank? ? sanitize_order_by(sortable_fields) : obs
+      end
+
+    end
+
+  end
+end

data/app/routines/openstax/utilities/search_and_organize_relation.rb

@@ -0,0 +1,130 @@
+# Database-agnostic routine for keyword searching
+# and ordering, limiting and paginating search results
+#
+# Searches, orders, imposes a maximum number or records and paginates
+# a given relation using the appropriate routines and user-supplied
+# parameters from the params hash
+#
+# See the search_routine.rb, order_routine.rb and
+# limit_and_paginate_routine.rb files for more information
+#
+# Callers must provide the search_relation, search_proc and
+# sortable_fields arguments and may provide the max_items argument
+#
+# Users must provide the q (query) argument and may provide
+# the order_by, per_page and page arguments in the params hash
+# Users must also be authorized to search the base class of the search_routine
+#
+# Required arguments:
+#
+#   Developer-supplied:
+#
+#   relation        - the initial ActiveRecord::Relation to start searching on
+#   search_proc     - a Proc passed to keyword_search's `search` method
+#                     it receives keyword_search's `with` object as argument
+#                     this proc must define the `keyword` blocks for keyword_search
+#                     the relation to be scoped is contained in the @items instance variable
+#                     the `to_string_array` helper can help with
+#                     parsing strings from the query
+#
+#   sortable_fields - list of fields that can appear in the order_by argument
+#                     can be a Hash that maps field names to database columns
+#                     or an Array of Strings
+#                     invalid fields in order_by will be replaced with
+#                     the first field listed here, in :asc order
+#
+#   User or UI-supplied:
+#
+#   params[:query]  - a String that follows the keyword format
+#                     Keywords have the format keyword:value
+#                     Keywords can also be negated with -, as in -keyword:value
+#                     Values are comma-separated; keywords are space-separated
+#
+# Optional arguments:
+#
+#   Developer-supplied (recommended to prevent scraping):
+#
+#   max_items         - the maximum number of matching items allowed to be returned
+#                       no results will be returned if this number is exceeded,
+#                       but the total result count will still be returned
+#                       applies even if pagination is enabled
+#                       default: nil (disabled)
+#
+#   User or UI-supplied:
+#
+#   params[:order_by] - list of fields to order by, with optional sort directions
+#                       can be (an Array of) Hashes, or Strings
+#                       default: {sortable_fields.values.first => :asc}
+#
+#   params[:per_page] - the maximum number of search results per page
+#                       default: nil (disabled)
+#   params[:page]     - the number of the page to return 
+#                       default: 1
+#
+# This handler's output contains:
+#
+#   outputs[:total_count] - the total number of items that matched the query
+#   outputs[:items]       - the relation returned by the search routines
+
+require 'lev'
+
+module OpenStax
+  module Utilities
+    class SearchAndOrganizeRelation
+
+      lev_routine transaction: :no_transaction
+
+      uses_routine SearchRelation,
+                   as: :search
+      uses_routine OrderRelation,
+                   as: :order
+      uses_routine LimitAndPaginateRelation,
+                   as: :limit_and_paginate,
+                   errors_are_fatal: false,
+                   translations: { inputs: { type: :verbatim },
+                                   outputs: { type: :verbatim } }
+
+      protected
+
+      def exec(*args, &search_proc)
+
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        relation = options[:relation] || args[0]
+        sortable_fields = options[:sortable_fields] || args[1]
+        params = options[:params] || args[2]
+        search_proc ||= options[:search_proc] || args[3]
+        max_items = options[:max_items] || nil
+
+        raise ArgumentError, 'You must specify a :relation option' \
+          if relation.nil?
+        raise ArgumentError, 'You must specify a :sortable_fields option' \
+          if sortable_fields.nil?
+        raise ArgumentError, 'You must specify a :params option' if params.nil?
+        raise ArgumentError, 'You must specify a block or :search_proc option' \
+          if search_proc.nil?
+
+        query = params[:query] || params[:q]
+        order_by = params[:order_by] || params[:ob]
+        per_page = params[:per_page] || params[:pp]
+        page = params[:page] || params[:p]
+
+        items = run(:search, relation: relation, search_proc: search_proc,
+                    query: query).outputs[:items]
+
+        items = run(:order, relation: items, sortable_fields: sortable_fields,
+                    order_by: order_by).outputs[:items]
+
+        if max_items.nil? && per_page.nil? && page.nil?
+          outputs[:items] = items
+          outputs[:total_count] = items.count
+          return
+        end
+
+        run(:limit_and_paginate, relation: items, max_items: max_items,
+            per_page: per_page, page: page)
+      end
+
+    end
+
+  end
+end

data/app/routines/openstax/utilities/search_relation.rb

@@ -0,0 +1,89 @@
+# Database-agnostic keyword searching routine
+#
+# Filters a relation based on a search Proc and a query String
+# See https://github.com/bruce/keyword_search for more information
+# about these arguments
+#
+# Callers of this routine provide the search_proc, relation and query arguments
+#
+# Required arguments:
+#
+#   Developer-supplied:
+#
+#   relation    - the initial ActiveRecord::Relation to start searching on
+#   search_proc - a Proc passed to keyword_search's `search` method
+#                 it receives keyword_search's `with` object as argument
+#                 this proc must define the `keyword` blocks for keyword_search
+#                 the relation to be scoped is contained in the @items instance variable
+#                 the `to_string_array` helper can help with
+#                 parsing strings from the query
+#
+#   User or developer-supplied:
+#
+#   query       - a String that follows the keyword format
+#                 Keywords have the format keyword:value
+#                 Keywords can also be negated with -, as in -keyword:value
+#                 Values are comma-separated, while keywords are space-separated
+#
+# This routine's outputs contain:
+#
+#   outputs[:items] - a relation with records that match the query terms
+
+require 'lev'
+require 'keyword_search'
+
+module OpenStax
+  module Utilities
+    class SearchRelation
+
+      lev_routine transaction: :no_transaction
+
+      protected
+
+      def exec(*args, &search_proc)
+
+        options = args.last.is_a?(Hash) ? args.pop : {}
+        @items = options[:relation] || args[0]
+        query = options[:query] || args[1]
+        search_proc ||= options[:search_proc] || args[2]
+
+        raise ArgumentError, 'You must specify a :relation option' if @items.nil?
+        raise ArgumentError, 'You must specify a block or :search_proc option' \
+          if search_proc.nil?
+
+        # Scoping
+
+        ::KeywordSearch.search(query.to_s) do |with|
+          instance_exec(with, &search_proc)
+        end
+
+        outputs[:items] = @items
+      end
+
+      # Parses a keyword string into an array of strings
+      # User-supplied wildcards are removed and strings are split on commas
+      # Then wildcards are appended or prepended if the append_wildcard or
+      # prepend_wildcard options are specified
+      def to_string_array(str, options = {})
+        sa = case str
+        when Array
+          str.collect{|name| name.gsub('%', '').split(',')}.flatten
+        else
+          str.to_s.gsub('%', '').split(',')
+        end
+        sa = sa.collect{|str| "#{str}%"} if options[:append_wildcard]
+        sa = sa.collect{|str| "%#{str}"} if options[:prepend_wildcard]
+        sa
+      end
+
+      # Parses a keyword string into an array of numbers
+      # User-supplied wildcards are removed and strings are split on commas
+      # Only numbers are returned
+      def to_number_array(str)
+        to_string_array(str).collect{|s| Integer(s) rescue nil}.compact
+      end
+
+    end
+
+  end
+end

data/lib/openstax/utilities/version.rb

@@ -1,5 +1,5 @@
 module OpenStax
   module Utilities
-    VERSION = "4.1.0"
+    VERSION = "4.2.0"
   end
 end

data/spec/dummy/{app/routines → config/initializers}/search_users.rb

@@ -1,7 +1,9 @@
-# Dummy routine for testing the general keyword search
+# Convenience constants for testing the search routines
 
-class SearchUsers < OpenStax::Utilities::AbstractKeywordSearchRoutine
-  self.search_proc = lambda { |with|
+class SearchUsers
+  RELATION = User.unscoped
+
+  SEARCH_PROC = lambda { |with|
     with.keyword :username do |names|
       snames = to_string_array(names, append_wildcard: true)
       @items = @items.where{username.like_any snames}
@@ -17,5 +19,8 @@ class SearchUsers < OpenStax::Utilities::AbstractKeywordSearchRoutine
       @items = @items.where{name.like_any snames}
     end
   }
-  self.sortable_fields_map = {'name' => :name, 'created_at' => :created_at, 'id' => :id}
+
+  SORTABLE_FIELDS = {'id' => :id, 'name' => :name, 'created_at' => :created_at}
+
+  MAX_ITEMS = 50
 end

data/spec/routines/openstax/utilities/limit_and_paginate_relation_spec.rb

@@ -0,0 +1,72 @@
+require 'rails_helper'
+
+module OpenStax
+  module Utilities
+    describe SearchRelation do
+
+      let!(:john_doe) { FactoryGirl.create :user, name: "John Doe",
+                                           username: "doejohn",
+                                           email: "john@doe.com" }
+
+      let!(:jane_doe) { FactoryGirl.create :user, name: "Jane Doe",
+                                           username: "doejane",
+                                           email: "jane@doe.com" }
+
+      let!(:jack_doe) { FactoryGirl.create :user, name: "Jack Doe",
+                                           username: "doejack",
+                                           email: "jack@doe.com" }
+
+      before(:each) do
+        100.times do
+          FactoryGirl.create(:user)
+        end
+
+        @relation = User.unscoped
+      end
+
+      it "returns nothing if too many results" do
+        routine = LimitAndPaginateRelation.call(relation: @relation,
+                                                max_items: 10)
+        outputs = routine.outputs
+        errors = routine.errors
+        expect(outputs).not_to be_empty
+        expect(outputs[:total_count]).to eq User.count
+        expect(outputs[:items]).to be_empty
+        expect(errors).not_to be_empty
+        expect(errors.first.code).to eq :too_many_items
+      end
+
+      it "paginates results" do
+        all_items = @relation.to_a
+
+        items = LimitAndPaginateRelation.call(relation: @relation,
+                                              per_page: 20).outputs[:items]
+        expect(items.limit(nil).offset(nil).count).to eq all_items.count
+        expect(items.limit(nil).offset(nil).to_a).to eq all_items
+        expect(items.count).to eq 20
+        expect(items.to_a).to eq all_items[0..19]
+
+        for page in 1..5
+          items = LimitAndPaginateRelation.call(relation: @relation,
+                                                page: page,
+                                                per_page: 20)
+                                          .outputs[:items]
+          expect(items.limit(nil).offset(nil).count).to eq all_items.count
+          expect(items.limit(nil).offset(nil).to_a).to eq all_items
+          expect(items.count).to eq 20
+          expect(items.to_a).to eq all_items.slice(20*(page-1), 20)
+        end
+
+        items = LimitAndPaginateRelation.call(relation: @relation,
+                                              page: 1000,
+                                              per_page: 20)
+                                        .outputs[:items]
+        expect(items.limit(nil).offset(nil).count).to eq all_items.count
+        expect(items.limit(nil).offset(nil).to_a).to eq all_items
+        expect(items.count).to eq 0
+        expect(items.to_a).to be_empty
+      end
+
+    end
+  end
+end

data/spec/routines/openstax/utilities/order_relation_spec.rb

@@ -0,0 +1,57 @@
+require 'rails_helper'
+
+module OpenStax
+  module Utilities
+    describe SearchRelation do
+
+      let!(:john_doe) { FactoryGirl.create :user, name: "John Doe",
+                                           username: "doejohn",
+                                           email: "john@doe.com" }
+
+      let!(:jane_doe) { FactoryGirl.create :user, name: "Jane Doe",
+                                           username: "doejane",
+                                           email: "jane@doe.com" }
+
+      let!(:jack_doe) { FactoryGirl.create :user, name: "Jack Doe",
+                                           username: "doejack",
+                                           email: "jack@doe.com" }
+
+      before(:each) do
+        100.times do
+          FactoryGirl.create(:user)
+        end
+
+        @relation = User.where{username.like 'doe%'}
+      end
+
+      it "orders results by multiple fields in different directions" do
+        items = OrderRelation.call(relation: @relation,
+                                   sortable_fields: SearchUsers::SORTABLE_FIELDS,
+                                   order_by: 'cReAtEd_At AsC, iD')
+                          .outputs[:items]
+        expect(items).to include(john_doe)
+        expect(items).to include(jane_doe)
+        expect(items).to include(jack_doe)
+        john_index = items.index(john_doe)
+        jane_index = items.index(jane_doe)
+        jack_index = items.index(jack_doe)
+        expect(jane_index).to be > john_index
+        expect(jack_index).to be > jane_index
+
+        items = OrderRelation.call(relation: @relation,
+                                   sortable_fields: SearchUsers::SORTABLE_FIELDS,
+                                   order_by: 'CrEaTeD_aT dEsC, Id DeSc')
+                          .outputs[:items]
+        expect(items).to include(john_doe)
+        expect(items).to include(jane_doe)
+        expect(items).to include(jack_doe)
+        john_index = items.index(john_doe)
+        jane_index = items.index(jane_doe)
+        jack_index = items.index(jack_doe)
+        expect(jane_index).to be < john_index
+        expect(jack_index).to be < jane_index
+      end
+
+    end
+  end
+end

data/spec/routines/openstax/utilities/{abstract_keyword_search_routine_spec.rb → search_and_organize_relation_spec.rb}

@@ -2,7 +2,14 @@ require 'rails_helper'
 
 module OpenStax
   module Utilities
-    describe AbstractKeywordSearchRoutine do
+    describe SearchAndOrganizeRelation do
+
+      OPTIONS = {
+        relation: SearchUsers::RELATION,
+        search_proc: SearchUsers::SEARCH_PROC,
+        sortable_fields: SearchUsers::SORTABLE_FIELDS,
+        max_items: SearchUsers::MAX_ITEMS
+      }
 
       let!(:john_doe) { FactoryGirl.create :user, name: "John Doe",
                                            username: "doejohn",
@@ -22,8 +29,9 @@ module OpenStax
         end
       end
 
-      it "filters results based on one field" do
-        items = SearchUsers.call(User.unscoped, 'last_name:dOe').outputs[:items]
+      it "filters results" do
+        items = SearchAndOrganizeRelation.call(OPTIONS.merge(params: {
+                  q: 'last_name:dOe'})).outputs[:items]
 
         expect(items).to include(john_doe)
         expect(items).to include(jane_doe)
@@ -31,11 +39,9 @@ module OpenStax
         items.each do |item|
           expect(item.name.downcase).to match(/\A[\w]* doe[\w]*\z/i)
         end
-      end
 
-      it "filters results based on multiple fields" do
-        items = SearchUsers.call(User.unscoped, 'first_name:jOhN last_name:DoE')
-                           .outputs[:items]
+        items = SearchAndOrganizeRelation.call(OPTIONS.merge(params: {
+                  q: 'first_name:jOhN last_name:DoE'})).outputs[:items]
 
         expect(items).to include(john_doe)
         expect(items).not_to include(jane_doe)
@@ -43,11 +49,9 @@ module OpenStax
         items.each do |item|
           expect(item.name).to match(/\Ajohn[\w]* doe[\w]*\z/i)
         end
-      end
 
-      it "filters results based on multiple keywords per field" do
-        items = SearchUsers.call(User.unscoped, 'first_name:JoHn,JaNe last_name:dOe')
-                           .outputs[:items]
+        items = SearchAndOrganizeRelation.call(OPTIONS.merge(params: {
+                  q: 'first_name:JoHn,JaNe last_name:dOe'})).outputs[:items]
 
         expect(items).to include(john_doe)
         expect(items).to include(jane_doe)
@@ -57,22 +61,10 @@ module OpenStax
         end
       end
 
-      it "filters scoped results" do
-        items = SearchUsers.call(User.where{name.like 'jOhN%'},
-                                 'last_name:dOe').outputs[:items]
-
-        expect(items).to include(john_doe)
-        expect(items).not_to include(jane_doe)
-        expect(items).not_to include(jack_doe)
-        items.each do |item|
-          expect(item.name.downcase).to match(/\Ajohn[\w]* doe[\w]*\z/i)
-        end
-      end
-
-      it "orders results by multiple fields in different directions" do
-        items = SearchUsers.call(User.unscoped, 'username:DoE',
-                                 order_by: 'cReAtEd_At AsC, iD')
-                          .outputs[:items]
+      it "orders results" do
+        items = SearchAndOrganizeRelation.call(OPTIONS.merge(params: {
+                    order_by: 'cReAtEd_At AsC, iD',
+                    q: 'username:dOe'})).outputs[:items].to_a
         expect(items).to include(john_doe)
         expect(items).to include(jane_doe)
         expect(items).to include(jack_doe)
@@ -81,13 +73,10 @@ module OpenStax
         jack_index = items.index(jack_doe)
         expect(jane_index).to be > john_index
         expect(jack_index).to be > jane_index
-        items.each do |item|
-          expect(item.username).to match(/\Adoe[\w]*\z/i)
-        end
 
-        items = SearchUsers.call(User.unscoped, 'username:dOe',
-                                 order_by: 'CrEaTeD_aT dEsC, Id DeSc')
-                          .outputs[:items]
+        items = SearchAndOrganizeRelation.call(OPTIONS.merge(params: {
+                  order_by: 'CrEaTeD_aT dEsC, Id DeSc',
+                  q: 'username:dOe'})).outputs[:items].to_a
         expect(items).to include(john_doe)
         expect(items).to include(jane_doe)
         expect(items).to include(jack_doe)
@@ -96,31 +85,49 @@ module OpenStax
         jack_index = items.index(jack_doe)
         expect(jane_index).to be < john_index
         expect(jack_index).to be < jane_index
-        items.each do |item|
-          expect(item.username).to match(/\Adoe[\w]*\z/i)
-        end
+      end
+
+      it "returns nothing if too many results" do
+        routine = SearchAndOrganizeRelation.call(OPTIONS.merge(params: {
+                    q: ''}))
+        outputs = routine.outputs
+        errors = routine.errors
+        expect(outputs).not_to be_empty
+        expect(outputs[:total_count]).to eq User.count
+        expect(outputs[:items]).to be_empty
+        expect(errors).not_to be_empty
+        expect(errors.first.code).to eq :too_many_items
       end
 
       it "paginates results" do
-        all_items = SearchUsers.call(User.unscoped, '').outputs[:items].to_a
+        all_items = SearchUsers::RELATION.to_a
 
-        items = SearchUsers.call(User.unscoped, '', per_page: 20).outputs[:items]
-        expect(items.limit(nil).offset(nil).count).to eq all_items.count
+        items = SearchAndOrganizeRelation.call(OPTIONS
+                  .except(:max_items)
+                  .merge(params: {q: '',
+                                  per_page: 20})).outputs[:items]
+        expect(items.limit(nil).offset(nil).count).to eq all_items.length
         expect(items.limit(nil).offset(nil).to_a).to eq all_items
         expect(items.count).to eq 20
         expect(items.to_a).to eq all_items[0..19]
 
         for page in 1..5
-          items = SearchUsers.call(User.unscoped, '', page: page, per_page: 20)
-                             .outputs[:items]
+          items = SearchAndOrganizeRelation.call(OPTIONS
+                    .except(:max_items)
+                    .merge(params: {q: '',
+                                    page: page,
+                                    per_page: 20})).outputs[:items]
           expect(items.limit(nil).offset(nil).count).to eq all_items.count
           expect(items.limit(nil).offset(nil).to_a).to eq all_items
           expect(items.count).to eq 20
           expect(items.to_a).to eq all_items.slice(20*(page-1), 20)
         end
 
-        items = SearchUsers.call(User.unscoped, '', page: 1000, per_page: 20)
-                           .outputs[:items]
+        items = SearchAndOrganizeRelation.call(OPTIONS
+                  .except(:max_items)
+                  .merge(params: {q: '',
+                                  page: 1000,
+                                  per_page: 20})).outputs[:items]
         expect(items.limit(nil).offset(nil).count).to eq all_items.count
         expect(items.limit(nil).offset(nil).to_a).to eq all_items
         expect(items.count).to eq 0

data/spec/routines/openstax/utilities/search_relation_spec.rb

@@ -0,0 +1,81 @@
+require 'rails_helper'
+
+module OpenStax
+  module Utilities
+    describe SearchRelation do
+
+      let!(:john_doe) { FactoryGirl.create :user, name: "John Doe",
+                                           username: "doejohn",
+                                           email: "john@doe.com" }
+
+      let!(:jane_doe) { FactoryGirl.create :user, name: "Jane Doe",
+                                           username: "doejane",
+                                           email: "jane@doe.com" }
+
+      let!(:jack_doe) { FactoryGirl.create :user, name: "Jack Doe",
+                                           username: "doejack",
+                                           email: "jack@doe.com" }
+
+      before(:each) do
+        100.times do
+          FactoryGirl.create(:user)
+        end
+      end
+
+      it "filters results based on one field" do
+        items = SearchRelation.call(relation: SearchUsers::RELATION,
+                                    search_proc: SearchUsers::SEARCH_PROC,
+                                    query: 'last_name:dOe').outputs[:items]
+
+        expect(items).to include(john_doe)
+        expect(items).to include(jane_doe)
+        expect(items).to include(jack_doe)
+        items.each do |item|
+          expect(item.name.downcase).to match(/\A[\w]* doe[\w]*\z/i)
+        end
+      end
+
+      it "filters results based on multiple fields" do
+        items = SearchRelation.call(relation: SearchUsers::RELATION,
+                                    search_proc: SearchUsers::SEARCH_PROC,
+                                    query: 'first_name:jOhN last_name:DoE')
+                              .outputs[:items]
+
+        expect(items).to include(john_doe)
+        expect(items).not_to include(jane_doe)
+        expect(items).not_to include(jack_doe)
+        items.each do |item|
+          expect(item.name).to match(/\Ajohn[\w]* doe[\w]*\z/i)
+        end
+      end
+
+      it "filters results based on multiple keywords per field" do
+        items = SearchRelation.call(relation: SearchUsers::RELATION,
+                                    search_proc: SearchUsers::SEARCH_PROC,
+                                    query: 'first_name:JoHn,JaNe last_name:dOe')
+                           .outputs[:items]
+
+        expect(items).to include(john_doe)
+        expect(items).to include(jane_doe)
+        expect(items).not_to include(jack_doe)
+        items.each do |item|
+          expect(item.name).to match(/\A[john|jane][\w]* doe[\w]*\z/i)
+        end
+      end
+
+      it "filters scoped results" do
+        items = SearchRelation.call(relation: User.where{name.like 'jOhN%'},
+                                    search_proc: SearchUsers::SEARCH_PROC,
+                                    query: 'last_name:dOe').outputs[:items]
+
+        expect(items).to include(john_doe)
+        expect(items).not_to include(jane_doe)
+        expect(items).not_to include(jack_doe)
+        items.each do |item|
+          expect(item.name.downcase).to match(/\Ajohn[\w]* doe[\w]*\z/i)
+        end
+      end
+
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openstax_utilities
 version: !ruby/object:Gem::Version
-  version: 4.1.0
+  version: 4.2.0
 platform: ruby
 authors:
 - JP Slavinsky
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-10-13 00:00:00.000000000 Z
+date: 2014-12-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -132,8 +132,10 @@ files:
 - MIT-LICENSE
 - README.md
 - Rakefile
-- app/handlers/openstax/utilities/keyword_search_handler.rb
-- app/routines/openstax/utilities/abstract_keyword_search_routine.rb
+- app/routines/openstax/utilities/limit_and_paginate_relation.rb
+- app/routines/openstax/utilities/order_relation.rb
+- app/routines/openstax/utilities/search_and_organize_relation.rb
+- app/routines/openstax/utilities/search_relation.rb
 - app/views/osu/shared/_action_list.html.erb
 - lib/openstax/utilities/access.rb
 - lib/openstax/utilities/access_policy.rb
@@ -164,7 +166,6 @@ files:
 - spec/dummy/app/controllers/application_controller.rb
 - spec/dummy/app/helpers/application_helper.rb
 - spec/dummy/app/models/user.rb
-- spec/dummy/app/routines/search_users.rb
 - spec/dummy/app/views/layouts/application.html.erb
 - spec/dummy/bin/bundle
 - spec/dummy/bin/rails
@@ -184,6 +185,7 @@ files:
 - spec/dummy/config/initializers/filter_parameter_logging.rb
 - spec/dummy/config/initializers/inflections.rb
 - spec/dummy/config/initializers/mime_types.rb
+- spec/dummy/config/initializers/search_users.rb
 - spec/dummy/config/initializers/session_store.rb
 - spec/dummy/config/initializers/wrap_parameters.rb
 - spec/dummy/config/locales/en.yml
@@ -196,10 +198,12 @@ files:
 - spec/dummy/public/500.html
 - spec/dummy/public/favicon.ico
 - spec/factories/user.rb
-- spec/handlers/openstax/utilities/keyword_search_handler_spec.rb
 - spec/lib/openstax/utilities/access_policy_spec.rb
 - spec/rails_helper.rb
-- spec/routines/openstax/utilities/abstract_keyword_search_routine_spec.rb
+- spec/routines/openstax/utilities/limit_and_paginate_relation_spec.rb
+- spec/routines/openstax/utilities/order_relation_spec.rb
+- spec/routines/openstax/utilities/search_and_organize_relation_spec.rb
+- spec/routines/openstax/utilities/search_relation_spec.rb
 - spec/spec_helper.rb
 homepage: http://github.com/openstax/openstax_utilities
 licenses:
@@ -232,7 +236,6 @@ test_files:
 - spec/dummy/app/controllers/application_controller.rb
 - spec/dummy/app/helpers/application_helper.rb
 - spec/dummy/app/models/user.rb
-- spec/dummy/app/routines/search_users.rb
 - spec/dummy/app/views/layouts/application.html.erb
 - spec/dummy/bin/bundle
 - spec/dummy/bin/rails
@@ -251,6 +254,7 @@ test_files:
 - spec/dummy/config/initializers/filter_parameter_logging.rb
 - spec/dummy/config/initializers/inflections.rb
 - spec/dummy/config/initializers/mime_types.rb
+- spec/dummy/config/initializers/search_users.rb
 - spec/dummy/config/initializers/session_store.rb
 - spec/dummy/config/initializers/wrap_parameters.rb
 - spec/dummy/config/locales/en.yml
@@ -266,8 +270,10 @@ test_files:
 - spec/dummy/Rakefile
 - spec/dummy/README.md
 - spec/factories/user.rb
-- spec/handlers/openstax/utilities/keyword_search_handler_spec.rb
 - spec/lib/openstax/utilities/access_policy_spec.rb
 - spec/rails_helper.rb
-- spec/routines/openstax/utilities/abstract_keyword_search_routine_spec.rb
+- spec/routines/openstax/utilities/limit_and_paginate_relation_spec.rb
+- spec/routines/openstax/utilities/order_relation_spec.rb
+- spec/routines/openstax/utilities/search_and_organize_relation_spec.rb
+- spec/routines/openstax/utilities/search_relation_spec.rb
 - spec/spec_helper.rb

data/app/handlers/openstax/utilities/keyword_search_handler.rb

@@ -1,95 +0,0 @@
-# Database-agnostic keyword searching handler
-#
-# Keywords have the format keyword:value
-# Keywords can also be negated with -, as in -keyword:value
-# Values are comma-separated, while keywords are space-separated
-# See https://github.com/bruce/keyword_search for more information
-#
-# Callers must pass the search_routine and search_relation options:
-#
-# Required:
-#
-#   search_routine  - the Lev::Routine that will handle the search
-#   search_relation - the ActiveRecord::Relation that will be searched
-#
-# Optional (recommended to prevent scraping):
-#
-#   min_characters - the minimum number of characters allowed in the query
-#                    only an error will be returned if the query has less
-#                    than the minimum number of characters allowed
-#                    default: nil (disabled)
-#
-#   max_items      - the maximum number of matching items allowed to be returned
-#                    no results will be returned if this number is exceeded,
-#                    but the total result count will still be returned
-#                    applies even if pagination is enabled
-#                    default: nil (disabled)
-#
-# This handler also expects the following parameters from the user or the UI:
-#
-# Required:
-#
-#   q - the query itself, a String that follows the keyword format above
-#
-# Optional:
-#
-#   order_by - a String used to order the search results - default: 'created_at ASC'
-#   per_page - the number of results returned per page - default: nil (disabled)
-#   page     - the current page number - default: 1
-#
-# This handler's output contains:
-#
-#   outputs[:total_count] - the total number of items that matched the query
-#                           set even when no results are returned due to
-#                           a query that is too short or too generic
-#   outputs[:items]       - the array of objects returned by the search routine
-#
-# See spec/dummy/app/handlers/users_search.rb for an example search handler
-
-require 'lev'
-
-module OpenStax
-  module Utilities
-    class KeywordSearchHandler
-
-      lev_handler
-
-      protected
-
-      def authorized?
-        routine = options[:search_routine]
-        relation = options[:search_relation]
-        raise ArgumentError if routine.nil? || relation.nil?
-        OSU::AccessPolicy.action_allowed?(:search, caller, relation.base_class)
-      end
-
-      def handle
-        query = params[:q]
-        fatal_error(code: :query_blank,
-                    message: 'You must provide a query parameter (q or query).') if query.nil?
-
-        min_characters = options[:min_characters]
-        fatal_error(code: :query_too_short,
-                    message: "The provided query is too short (minimum #{
-                      min_characters} characters).") \
-          if !min_characters.nil? && query.length < min_characters
-
-        routine = options[:search_routine]
-        relation = options[:search_relation]
-        items = run(routine, relation, query, params).outputs[:items]
-
-        outputs[:total_count] = items.limit(nil).offset(nil).count
-
-        max_items = options[:max_items]
-        fatal_error(code: :too_many_items,
-                    message: "The number of matches exceeded the allowed limit of #{
-                      max_items} matches. Please refine your query and try again.") \
-          if !max_items.nil? && outputs[:total_count] > max_items
-
-        outputs[:items] = items.to_a
-      end
-
-    end
-
-  end
-end

data/app/routines/openstax/utilities/abstract_keyword_search_routine.rb

@@ -1,158 +0,0 @@
-# Database-agnostic keyword searching routine
-#
-# Keywords have the format keyword:value
-# Keywords can also be negated with -, as in -keyword:value
-# Values are comma-separated, while keywords are space-separated
-# See https://github.com/bruce/keyword_search for more information
-#
-# Subclasses must set the search_proc and sortable_fields class variables
-#
-#   search_proc - a proc passed to keyword_search's `search` method
-#                 it receives keyword_search's `with` object as argument
-#                 this proc must define the `keyword` blocks for keyword_search
-#                 the relation to be scoped is contained in the @items instance variable
-#                 the `to_string_array` helper can help with
-#                 parsing strings from the query
-#
-#   sortable_fields_map - a Hash that maps the lowercase names of fields
-#                         which can be used to sort the results to symbols
-#                         for their respective database columns
-#                         keys are lowercase strings that should be allowed
-#                         in options[:order_by]
-#                         values are the corresponding database column names
-#                         that will be passed to the order() method
-#                         columns from other tables can be specified either
-#                         through Arel attributes (Class.arel_table[:column])
-#                         or through literal strings
-#
-# Callers of subclass routines provide a relation argument,
-# a query argument and an options hash
-#
-# Required arguments:
-#
-#   relation - the initial relation to start searching on
-#   query - a string that follows the keyword format above
-#
-# Options hash:
-#
-#     Ordering:
-#
-#       :order_by - list of fields to sort by, with optional sort directions
-#                   can be a String, Array of Strings or Array of Hashes
-#                   default: {:created_at => :asc}
-#
-#     Pagination:
-#
-#       :per_page - the maximum number of results per page - default: nil (disabled)
-#       :page     - the page to return - default: 1
-#
-# This routine's output contains:
-#
-#   outputs[:items] - an ActiveRecord::Relation that matches the query terms and options
-#
-# You can use the following expression to obtain the
-# total count of records that matched the query terms:
-#
-#   outputs[:items].limit(nil).offset(nil).count
-#
-# See spec/dummy/app/routines/search_users.rb for an example search routine
-
-require 'lev'
-require 'keyword_search'
-
-module OpenStax
-  module Utilities
-    class AbstractKeywordSearchRoutine
-
-      lev_routine transaction: :no_transaction
-
-      protected
-
-      class_attribute :search_proc, :sortable_fields_map
-
-      def exec(relation, query, options = {})
-        raise NotImplementedError if search_proc.nil? || sortable_fields_map.nil?
-
-        raise ArgumentError \
-          unless relation.is_a?(ActiveRecord::Relation) && query.is_a?(String)
-
-        @items = relation
-
-        # Scoping
-
-        ::KeywordSearch.search(query) do |with|
-          instance_exec(with, &search_proc)
-        end
-
-        # Ordering
-
-        order_bys = sanitize_order_bys(options[:order_by])
-        @items = @items.order(order_bys)
-        
-        # Pagination
-
-        per_page = Integer(options[:per_page]) rescue nil
-        unless per_page.nil?
-          page = Integer(options[:page]) rescue 1
-          @items = @items.limit(per_page).offset(per_page*(page-1))
-        end
-
-        outputs[:items] = @items
-      end
-
-      def sanitize_order_by(field, dir = nil)
-        sanitized_field = sortable_fields_map[field.to_s.downcase] || :created_at
-        sanitized_dir = dir.to_s.downcase == 'desc' ? :desc : :asc
-        case sanitized_field
-        when Symbol
-          {sanitized_field => sanitized_dir}
-        when Arel::Attributes::Attribute
-          sanitized_field.send sanitized_dir
-        else
-          "#{sanitized_field.to_s} #{sanitized_dir.to_s.upcase}"
-        end
-      end
-
-      def sanitize_order_bys(order_bys)
-        case order_bys
-        when Array
-          order_bys.collect do |ob|
-            case ob
-            when Hash
-              sanitize_order_by(ob.keys.first, ob.values.first)
-            when Array
-              sanitize_order_by(ob.first, ob.second)
-            else
-              sanitize_order_by(ob)
-            end
-          end
-        when Hash
-          order_bys.collect { |k, v| sanitize_order_by(k, v) }
-        else
-          order_bys.to_s.split(',').collect do |ob|
-            fd = ob.split(' ')
-            sanitize_order_by(fd.first, fd.second)
-          end
-        end
-      end
-
-      # Parses a keyword string into an array of strings
-      # User-supplied wildcards are removed and strings are split on commas
-      # Then wildcards are appended or prepended if the append_wildcard or
-      # prepend_wildcard options are specified
-      def to_string_array(str, options = {})
-        sa = case str
-        when Array
-          str.collect{|name| name.gsub('%', '').split(',')}.flatten
-        else
-          str.to_s.gsub('%', '').split(',')
-        end
-        sa = sa.collect{|str| "#{str}%"} if options[:append_wildcard]
-        sa = sa.collect{|str| "%#{str}"} if options[:prepend_wildcard]
-        sa
-      end
-
-    end
-
-  end
-end

data/spec/handlers/openstax/utilities/keyword_search_handler_spec.rb

@@ -1,126 +0,0 @@
-require 'rails_helper'
-
-module OpenStax
-  module Utilities
-    describe KeywordSearchHandler do
-
-      options = {
-        caller: FactoryGirl.create(:user),
-        search_routine: SearchUsers,
-        search_relation: User.unscoped,
-        max_items: 10,
-        min_characters: 3
-      }
-
-      let!(:john_doe) { FactoryGirl.create :user, name: "John Doe",
-                                           username: "doejohn",
-                                           email: "john@doe.com" }
-
-      let!(:jane_doe) { FactoryGirl.create :user, name: "Jane Doe",
-                                           username: "doejane",
-                                           email: "jane@doe.com" }
-
-      let!(:jack_doe) { FactoryGirl.create :user, name: "Jack Doe",
-                                           username: "doejack",
-                                           email: "jack@doe.com" }
-
-      before(:each) do
-        100.times do
-          FactoryGirl.create(:user)
-        end
-
-        DummyAccessPolicy.last_action = nil
-        DummyAccessPolicy.last_requestor = nil
-        DummyAccessPolicy.last_resource = nil
-      end
-
-      it "passes its params to the search routine and sets the total_count output" do
-        outputs = KeywordSearchHandler.call(options.merge(
-                                              params: {q: 'username:dOe'})).outputs
-        total_count = outputs[:total_count]
-        items = outputs[:items]
-        expect(DummyAccessPolicy.last_action).to eq :search
-        expect(DummyAccessPolicy.last_requestor).to eq options[:caller]
-        expect(DummyAccessPolicy.last_resource).to eq User
-        expect(total_count).to eq items.count
-        expect(items).to include(john_doe)
-        expect(items).to include(jane_doe)
-        expect(items).to include(jack_doe)
-        john_index = items.index(john_doe)
-        jane_index = items.index(jane_doe)
-        jack_index = items.index(jack_doe)
-        expect(jane_index).to be > john_index
-        expect(jack_index).to be > jane_index
-        items.each do |item|
-          expect(item.username).to match(/\Adoe[\w]*\z/i)
-        end
-
-        DummyAccessPolicy.last_action = nil
-        DummyAccessPolicy.last_requestor = nil
-        DummyAccessPolicy.last_resource = nil
-        outputs = KeywordSearchHandler.call(options.merge(
-                                              params: {order_by: 'cReAtEd_At DeSc, iD dEsC',
-                                                     q: 'username:DoE'})).outputs
-        total_count = outputs[:total_count]
-        items = outputs[:items]
-        expect(DummyAccessPolicy.last_action).to eq :search
-        expect(DummyAccessPolicy.last_requestor).to eq options[:caller]
-        expect(DummyAccessPolicy.last_resource).to eq User
-        expect(total_count).to eq items.count
-        expect(items).to include(john_doe)
-        expect(items).to include(jane_doe)
-        expect(items).to include(jack_doe)
-        john_index = items.index(john_doe)
-        jane_index = items.index(jane_doe)
-        jack_index = items.index(jack_doe)
-        expect(jane_index).to be < john_index
-        expect(jack_index).to be < jane_index
-        items.each do |item|
-          expect(item.username).to match(/\Adoe[\w]*\z/i)
-        end
-      end
-
-      it "errors out if no query is provided" do
-        routine = KeywordSearchHandler.call(options.merge(params: {}))
-        outputs = routine.outputs
-        errors = routine.errors
-        expect(DummyAccessPolicy.last_action).to eq :search
-        expect(DummyAccessPolicy.last_requestor).to eq options[:caller]
-        expect(DummyAccessPolicy.last_resource).to eq User
-        expect(outputs).to be_empty
-        expect(errors).not_to be_empty
-        expect(errors.first.code).to eq :query_blank
-      end
-
-      it "errors out if the query is too short" do
-        routine = KeywordSearchHandler.call(options.merge(params: {q: 'a'}))
-        outputs = routine.outputs
-        errors = routine.errors
-        expect(DummyAccessPolicy.last_action).to eq :search
-        expect(DummyAccessPolicy.last_requestor).to eq options[:caller]
-        expect(DummyAccessPolicy.last_resource).to eq User
-        expect(outputs).to be_empty
-        expect(errors).not_to be_empty
-        expect(errors.first.code).to eq :query_too_short
-      end
-
-      it "errors out if too many items match" do
-        routine = KeywordSearchHandler.call(options.merge(
-                                              params: {
-                                                q: 'username:a,b,c,d,e,f,g,h,i,j,k,l,m,n,o,p,q,r,s,t,u,v,w,x,y,z,0,1,2,3,4,5,6,7,8,9,-,_'
-                                              }))
-        outputs = routine.outputs
-        errors = routine.errors
-        expect(DummyAccessPolicy.last_action).to eq :search
-        expect(DummyAccessPolicy.last_requestor).to eq options[:caller]
-        expect(DummyAccessPolicy.last_resource).to eq User
-        expect(outputs).not_to be_empty
-        expect(outputs[:total_count]).to eq User.count
-        expect(outputs[:items]).to be_nil
-        expect(errors).not_to be_empty
-        expect(errors.first.code).to eq :too_many_items
-      end
-
-    end
-  end
-end