procore-sift 0.15.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96191da518ce07229dd35fe0375a2b52a4da4ee69b7f506835a236c7e87c77a1
-  data.tar.gz: 994eff7f0ed3417b0a9272e554d4ece07b73fdf99769b89497bbf56cf4259c00
+  metadata.gz: bf5b2ef9c9c924ef031b2626d1acc7a89fe5fce882410c01ff0d0b784640e9be
+  data.tar.gz: 5adf8202ac47b3cfeea5244480de98a27737fad342a8c138d3338b0dd7eb27f6
 SHA512:
-  metadata.gz: c6633d0d1260108f39ea161f001980c66102f908ca1b310aab9eefeec9b41dae02bd678dafad461e5f6c4d841b4ac61446f79136b27dd3e159c1b67bb84c5967
-  data.tar.gz: 0d5ce661231cd9caaf98c145be89765e269755619838b60f9ba088d8f4456110794b154e6871887c05d42661dba2e7733e3178449ef474a0be78830a3ae14832
+  metadata.gz: 1b0e77176f7c0648832374c63f60087695519ba1878e4ad325bd13453d9c77c584cb25d975d2ec129fb42b20ce8abc1afd1fc33e0e1ed0dc92af4108d96adf05
+  data.tar.gz: e633d786d9dbafd79f551e8c41dd6e1031658a4c299c2b6d11a4821561fde62b98b47696c0820f7800d464c0e69cd53a240880d7959bde837981e83ea00598f2

data/README.md

@@ -5,6 +5,7 @@
 A tool to build your own filters and sorts with Rails and Active Record!
 
 ## Developer Usage
+
 Include Sift in your controllers, and define some filters.
 
 ```ruby
@@ -27,7 +28,7 @@ Sift will also handle rendering errors using the standard rails errors structure
 before_action :render_filter_errors, unless: :filters_valid?
 
 def render_filter_errors
-  render json: { errors: filter_errors } and return
+  render json: { errors: filter_errors }, status: :bad_request && return
 end
 ```
 
@@ -36,19 +37,22 @@ to your controller.
 These errors are based on the type that you told sift your param was.
 
 ### Filter Types
+
 Every filter must have a type, so that Sift knows what to do with it. The current valid filter types are:
-* int - Filter on an integer column
-* decimal - Filter on a decimal column
-* boolean - Filter on a boolean column
-* string - Filter on a string column
-* text - Filter on a text column
-* date - Filter on a date column
-* time - Filter on a time column
-* datetime - Filter on a datetime column
-* scope - Filter on an ActiveRecord scope
-* jsonb - Filter on a jsonb column (supported only in PostgreSQL)
+
+- int - Filter on an integer column
+- decimal - Filter on a decimal column
+- boolean - Filter on a boolean column
+- string - Filter on a string column
+- text - Filter on a text column
+- date - Filter on a date column
+- time - Filter on a time column
+- datetime - Filter on a datetime column
+- scope - Filter on an ActiveRecord scope
+- jsonb - Filter on a jsonb column (supported only in PostgreSQL)
 
 ### Filter on Scopes
+
 Just as your filter values are used to scope queries on a column, values you
 pass to a scope filter will be used as arguments to that scope. For example:
 
@@ -75,7 +79,7 @@ Scopes that accept no arguments are currently not supported.
 
 #### Accessing Params with Filter Scopes
 
-Filters with `type: :scope` have access to the params hash by passing in the desired keys to the `scope_params`. The keys passed in will be returned as a hash with their associated values, and should always appear as the last argument in your scope.
+Filters with `type: :scope` have access to the params hash by passing in the desired keys to the `scope_params`. The keys passed in will be returned as a hash with their associated values.
 
 ```ruby
 class Post < ActiveRecord::Base
@@ -94,6 +98,7 @@ class UsersController < ApplicationController
   end
 end
 ```
+
 Passing `?filters[user_posts_on_date]=10/12/20` will call the `user_posts_on_date` scope with
 `10/12/20` as the the first argument, and will grab the `user_id` and `blog_id` out of the params and pass them as a hash, as the second argument.
 
@@ -111,17 +116,38 @@ end
 ```
 
 ### Filter on Ranges
+
 Some parameter types support ranges. Ranges are expected to be a string with the bounding values separated by `...`
 
 For example `?filters[price]=3...50` would return records with a price between 3 and 50.
 
 The following types support ranges
-* int
-* decimal
-* boolean
-* date
-* time
-* datetime
+
+- int
+- decimal
+- boolean
+- date
+- time
+- datetime
+
+### Mutating Filters
+
+Filters can be mutated before the filter is applied using the `tap` argument. This is useful, for example, if you need to adjust the time zone of a `datetime` range filter.
+
+```ruby
+
+class PostsController < ApplicationController
+  include Sift
+
+  filter_on :expiration, type: :datetime, tap: ->(value, params) {
+    value.split("...").
+      map do |str|
+        str.to_date.in_time_zone(LOCAL_TIME_ZONE)
+      end.
+      join("...")
+  }
+end
+```
 
 ### Filter on jsonb column
 
@@ -130,19 +156,22 @@ Usually JSONB columns stores values as an Array or an Object (key-value), in bot
 **Array**
 
 It should be sent an array in the URL Query parameters
- * `?filters[metadata]=[1,2]`
+
+- `?filters[metadata]=[1,2]`
 
 **key-value**
 
 It can be passed one or more Key values:
- * `?filters[metadata]={"data_1":"test"}`
- * `?filters[metadata]={"data_1":"test","data_2":"[1,2]"}`
+
+- `?filters[metadata]={"data_1":"test"}`
+- `?filters[metadata]={"data_1":"test","data_2":"[1,2]"}`
 
 When the value is an array, it will filter records with those values or more, for example:
 
-* `?filters[metadata]={"data_2":"[1,2]"}`
+- `?filters[metadata]={"data_2":"[1,2]"}`
 
 Will return records with next values stored in the JSONB column `metadata`:
+
 ```ruby
 { data_2: 1 }
 { data_2: 2 }
@@ -154,9 +183,10 @@ Will return records with next values stored in the JSONB column `metadata`:
 
 When the `null` value is included in the array, it will return also all the records without any value in that property, for example:
 
-* `?filters[metadata]={"data_2":"[false,null]"}`
+- `?filters[metadata]={"data_2":"[false,null]"}`
 
 Will return records with next values stored in the JSONB column `metadata`:
+
 ```ruby
 { data_2: null }
 { data_2: false }
@@ -165,9 +195,11 @@ Will return records with next values stored in the JSONB column `metadata`:
 ```
 
 ### Filter on JSON Array
+
 `int` type filters support sending the values as an array in the URL Query parameters. For example `?filters[id]=[1,2]`. This is a way to keep payloads smaller for GET requests. When URI encoded this will become `filters%5Bid%5D=%5B1,2%5D` which is much smaller the standard format of `filters%5Bid%5D%5B%5D=1&&filters%5Bid%5D%5B%5D=2`.
 
 On the server side, the params will be received as:
+
 ```ruby
 # JSON array encoded result
 "filters"=>{"id"=>"[1,2]"}
@@ -177,34 +209,41 @@ On the server side, the params will be received as:
 ```
 
 Note that this feature cannot currently be wrapped in an array and should not be used in combination with sending array parameters individually.
- * `?filters[id][]=[1,2]` => invalid
- * `?filters[id][]=[1,2]&filters[id][]=3` => invalid
- * `?filters[id]=[1,2]&filters[id]=3` => valid but only 3 is passed through to the server
- * `?filters[id]=[1,2]` => valid
+
+- `?filters[id][]=[1,2]` => invalid
+- `?filters[id][]=[1,2]&filters[id][]=3` => invalid
+- `?filters[id]=[1,2]&filters[id]=3` => valid but only 3 is passed through to the server
+- `?filters[id]=[1,2]` => valid
 
 #### A note on encoding for JSON Array feature
+
 JSON arrays contain the reserved characters "`,`" and "`[`" and "`]`". When encoding a JSON array in the URL there are two different ways to handle the encoding. Both ways are supported by Rails.
 For example, lets look at the following filter with a JSON array `?filters[id]=[1,2]`:
- * `?filters%5Bid%5D=%5B1,2%5D`
- * `?filters%5Bid%5D%3D%5B1%2C2%5D`
+
+- `?filters%5Bid%5D=%5B1,2%5D`
+- `?filters%5Bid%5D%3D%5B1%2C2%5D`
 
 In both cases Rails will correctly decode to the expected result of
+
 ```ruby
 { "filters" => { "id" => "[1,2]" } }
 ```
 
 ### Sort Types
+
 Every sort must have a type, so that Sift knows what to do with it. The current valid sort types are:
-* int - Sort on an integer column
-* decimal - Sort on a decimal column
-* string - Sort on a string column
-* text - Sort on a text column
-* date - Sort on a date column
-* time - Sort on a time column
-* datetime - Sort on a datetime column
-* scope - Sort on an ActiveRecord scope
+
+- int - Sort on an integer column
+- decimal - Sort on a decimal column
+- string - Sort on a string column
+- text - Sort on a text column
+- date - Sort on a date column
+- time - Sort on a time column
+- datetime - Sort on a datetime column
+- scope - Sort on an ActiveRecord scope
 
 ### Sort on Scopes
+
 Just as your sort values are used to scope queries on a column, values you
 pass to a scope sort will be used as arguments to that scope. For example:
 
@@ -240,7 +279,6 @@ Scopes that accept no arguments are currently supported, but you should note tha
 
 `scope_params` can also accept symbols that are keys in the `params` hash. The value will be fetched and passed on as an argument to the scope.
 
-
 ## Consumer Usage
 
 Filter:
@@ -255,6 +293,7 @@ Sort is translated to Active Record `order` The sorts are applied in the order t
 the `-` symbol means to sort in `desc` order. By default, keys are sorted in `asc` order.
 
 ## Installation
+
 Add this line to your application's Gemfile:
 
 ```ruby
@@ -262,11 +301,13 @@ gem 'procore-sift'
 ```
 
 And then execute:
+
 ```bash
 $ bundle
 ```
 
 Or install it yourself as:
+
 ```bash
 $ gem install procore-sift
 ```
@@ -278,6 +319,7 @@ We have some future plans to remove the rails dependency so that other framework
 ## Contributing
 
 Running tests:
+
 ```bash
 $ bundle exec rake test
 ```
@@ -290,6 +332,7 @@ When a bump is desired, the gemspec should have the version number bumped and me
 
 Step 1: build the new version
 `gem build sift.gemspec`
+
 ```
   Successfully built RubyGem
   Name: procore-sift
@@ -299,6 +342,7 @@ Step 1: build the new version
 
 Step2: Push the updated build
 `gem push procore-sift-0.14.0.gem`
+
 ```
 Pushing gem to https://rubygems.org...
 Successfully registered gem: procore-sift (0.14.0)

data/lib/procore-sift.rb

@@ -66,8 +66,8 @@ module Sift
   end
 
   class_methods do
-    def filter_on(parameter, type:, internal_name: parameter, default: nil, validate: nil, scope_params: [])
-      filters << Filter.new(parameter, type, internal_name, default, validate, scope_params)
+    def filter_on(parameter, type:, internal_name: parameter, default: nil, validate: nil, scope_params: [], tap: nil)
+      filters << Filter.new(parameter, type, internal_name, default, validate, scope_params, tap)
     end
 
     def filters

data/lib/sift/filter.rb

@@ -4,11 +4,12 @@ module Sift
   class Filter
     attr_reader :parameter, :default, :custom_validate, :scope_params
 
-    def initialize(param, type, internal_name, default, custom_validate = nil, scope_params = [])
+    def initialize(param, type, internal_name, default, custom_validate = nil, scope_params = [], tap = ->(value, _params) { value })
       @parameter = Parameter.new(param, type, internal_name)
       @default = default
       @custom_validate = custom_validate
       @scope_params = scope_params
+      @tap = tap
       raise ArgumentError, "scope_params must be an array of symbols" unless valid_scope_params?(scope_params)
       raise "unknown filter type: #{type}" unless type_validator.valid_type?
     end
@@ -24,7 +25,9 @@ module Sift
       elsif should_apply_default?(value)
         default.call(collection)
       else
-        handler.call(collection, parameterize(value), params, scope_params)
+        parameterized_values = parameterize(value)
+        processed_values = @tap.present? ? @tap.call(parameterized_values, params) : parameterized_values
+        handler.call(collection, processed_values, params, scope_params)
       end
     end
     # rubocop:enable Lint/UnusedMethodArgument

data/lib/sift/sort.rb

@@ -17,6 +17,7 @@ module Sift
     def initialize(param, type, internal_name = param, scope_params = [])
       raise "unknown filter type: #{type}" unless WHITELIST_TYPES.include?(type)
       raise "scope params must be an array" unless scope_params.is_a?(Array)
+
       @parameter = Parameter.new(param, type, internal_name)
       @scope_params = scope_params
     end

data/lib/sift/subset_comparator.rb

@@ -5,6 +5,8 @@ module Sift
     end
 
     def include?(other)
+      other = [other] unless other.is_a?(Array)
+
       @array.to_set >= other.to_set
     end
   end

data/lib/sift/version.rb

@@ -1,3 +1,3 @@
 module Sift
-  VERSION = "0.15.0".freeze
+  VERSION = "0.16.0".freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: procore-sift
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Procore Technologies
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-08-03 00:00:00.000000000 Z
+date: 2021-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -139,7 +139,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.3
+rubygems_version: 3.0.3
 signing_key: 
 specification_version: 4
 summary: Summary of Sift.