rack-reducer 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d400c7b68a3ecf7da56af02f7f5e86ab18177ff306d6871a10ef8f9e7bcb7109
-  data.tar.gz: ff1b1f50ccb165d041a04fced63adbd946d8976f06460ce83c30b66c91599c17
+  metadata.gz: 96e9d87cd9c12373fb42f37eedb4246d6296009faab5bb5f1831236a4c200b0f
+  data.tar.gz: cb1e793d45ba3e71f588b22df0469358a40f56ab3167d8dc734b105306a841f0
 SHA512:
-  metadata.gz: 0dadfa90dce4dfd009c5dab96bc6c32557863a8413cf7888a10fe0f5af9d1479c2a93c29b79ea501abaa89dafa0de1daf95ac2665bae2534884d3c9a8cd4bf17
-  data.tar.gz: da77f4e36e9a979be6a52d37a996f10636935dc9097dc47dc22cb972d5e59a5634b327dcae60d7c9573a4e62b6b9fa789dbd0511459724a15103a619b49ccc63
+  metadata.gz: ebb52de791e396e475cbfb76040645120e4892f12d9fc9f3b7901d86a9b52adf2d7314b6795472640fb5a3eb2c1f44b49191a823457a9b94588fea129a530870
+  data.tar.gz: c373da2d40a7e3da1b281408636c38107430a7583155f3923539e8db7ce85c09cffd2b1233fc867dc1f56dd94e86281dd7820a9131d5ed544f1dd3439def249b

data/README.md

@@ -3,15 +3,7 @@ Rack::Reducer
 [![Build Status](https://travis-ci.org/chrisfrank/rack-reducer.svg?branch=master)](https://travis-ci.org/chrisfrank/rack-reducer)
 [![Maintainability](https://api.codeclimate.com/v1/badges/675e7a654c7e11c24b9f/maintainability)](https://codeclimate.com/github/chrisfrank/rack-reducer/maintainability)
 
-Dynamically filter and sort data via URL params, with controller logic as
-succint as
-
-```ruby
-@artists = Artist.reduce(params)
-```
-
-Rack::Reducer works in any Rack-compatible app, with any ORM, and has no
-dependencies beyond Rack itself.
+Declaratively filter data via URL params, in any Rack app, with any ORM.
 
 Install
 ------------------------------------------
@@ -21,85 +13,45 @@ Add `rack-reducer` to your Gemfile:
 gem 'rack-reducer', require: 'rack/reducer'
 ```
 
+Rack::Reducer has zero dependencies beyond Rack itself.
+
 Use
 ------------------------------------------
 If your app needs to render a list of database records, you probably want those
 records to be filterable via URL params, like so:
 
 ```
-GET /artists?name=blake` => artists named 'blake'
-GET /artists?genre=electronic&sort=name => electronic artists, sorted by name
 GET /artists => all artists
+GET /artists?name=blake` => artists named 'blake'
+GET /artists?genre=electronic&name=blake => electronic artists named 'blake'
 ```
 
-You _could_ conditionally apply filters with hand-written `if` statements, but
-that approach gets uglier the more filters you have.
-
-Rack::Reducer can help. It maps incoming URL params to an array of filter
-functions you define, applies only the applicable filters, and returns your
-filtered data.
-
-You can use Rack::Reducer in your choice of two styles: **mixin** or
-**functional**.
-
-### Mixin style
-Call `Model.reduce(params)` in your controllers...
+Rack::Reducer can help. It applies incoming URL params to an array of filter
+functions you define, runs only the relevant filters, and returns your filtered
+data. Here’s how you might use it in a Rails controller:
 
 ```ruby
 # app/controllers/artists_controller.rb
 class ArtistsController < ApplicationController
-  def index
-    @artists = Artist.reduce(params)
-    render json: @artists
-  end
-end
-```
-
-...and `extend Rack::Reducer` in your models:
-
-```ruby
-# app/models/artist.rb
-class Artist < ActiveRecord::Base
-  extend Rack::Reducer
-
-  # Configure by calling
-  # `reduces(some_initial_scope, filters: [an, array, of, lambdas])`
-  #
-  # Filters can use any methods your initial dataset understands,
-  # in this case Artist class methods and scopes
-  reduces self.all, filters: [
+  # Step 1: Create a reducer
+  ArtistReducer = Rack::Reducer.create(
+    Artist.all,
     ->(name:) { where('lower(name) like ?', "%#{name.downcase}%") },
     ->(genre:) { where(genre: genre) },
-    ->(sort:) { order(sort.to_sym) },
-  ]
-end
-```
+  )
 
-### Functional style
-Call Rack::Reducer as a function, maybe right in your controllers, maybe in
-a dedicated [query object][query_obj], or really anywhere you like:
-
-```ruby
-# app/controllers/artists_controller.rb
-class ArtistsController < ApplicationController
+  # Step 2: Apply the reducer to incoming requests
   def index
-    @artists = Rack::Reducer.call(params, dataset: Artist.all, filters: [
-      ->(name:) { where('lower(name) like ?', "%#{name.downcase}%") },
-      ->(genre:) { where(genre: genre) },
-      ->(sort:) { order(sort.to_sym) },
-    ])
+    @artists = ArtistReducer.apply(params)
     render json: @artists
   end
 end
 ```
 
-The mixin style is stylistically Railsier. The functional style is more
-flexible. Both styles are supported, tested, and handle requests identically.
-
-In the examples above:
+This example app would handle requests as follows:
 
 ```ruby
-# GET /artists returns all artists, e.g.
+# GET /artists => All artists:
 [
   { "name": "Blake Mills", "genre": "alternative" },
   { "name": "Björk", "genre": "electronic" },
@@ -108,79 +60,48 @@ In the examples above:
   { "name": "SZA", "genre": "alt-soul" }
 ]
 
-# GET /artists?name=blake returns artists named 'blake',  e.g.
+# GET /artists?name=blake => Artists named "blake":
 [
   { "name": "Blake Mills", "genre": "alternative" },
   { "name": "James Blake", "genre": "electronic" }
 ]
 
-# GET /artists?name=blake&genre=electronic returns e.g.
+# GET /artists?name=blake&genre=electronic => Electronic artists named "blake"
 [{ "name": "James Blake", "genre": "electronic" }]
 ```
 
-
 Framework-specific Examples
 ---------------------------
 These examples apply Rack::Reducer in different frameworks and ORMs. The
 pairings of ORMs and frameworks are arbitrary, just to demonstrate a few
 possible stacks.
 
-- [Sinatra/Sequel](#sinatrasequel)
-- [Rack Middleware/Ruby Hash](#rack-middlewarehash)
-- [Roda](#roda)
-- [Hanami](#hanami)
-- [Advanced use in Rails and other frameworks](#advanced-use-in-rails-and-other-frameworks)
-
 ### Sinatra/Sequel
 This example uses [Sinatra][sinatra] to handle requests, and [Sequel][sequel]
 as an ORM.
 
-#### Functional-style
 ```ruby
 # sinatra_functional_style.rb
-class SinatraFunctionalApp < Sinatra::Base
+class SinatraExample < Sinatra::Base
   DB = Sequel.connect ENV['DATABASE_URL']
 
   # dataset is a Sequel::Dataset, so filters use Sequel query methods
-  QUERY = {
-    dataset: DB[:artists],
-    filters: [
-      ->(genre:) { where(genre: genre) },
-      ->(name:) { grep(:name, "%#{name}%", case_insensitive: true) },
-      ->(sort:) { order(sort.to_sym) },
-    ]
-  }
-
-  get '/artists' do
-    @artists = Rack::Reducer.call(params, QUERY)
-    @artists.to_a.to_json
-  end
-end
-```
-
-#### Mixin-style
-```ruby
-# sintra_mixin_style.rb
-class SinatraMixinApp < Sinatra::Base
-  class Artist < Sequel::Model
-    extend Rack::Reducer
-    reduces self.dataset, filters: [
-      ->(genre:) { where(genre: genre) },
-      ->(name:) { grep(:name, "%#{name}%", case_insensitive: true) },
-      ->(sort:) { order(sort.to_sym) },
-    ]
-  end
+  ArtistReducer = Rack::Reducer.create(
+    DB[:artists],
+    ->(genre:) { where(genre: genre) },
+    ->(name:) { grep(:name, "%#{name}%", case_insensitive: true) },
+  )
 
   get '/artists' do
-    @artists = Artist.reduce(params)
-    @artists.to_a.to_json
+    @artists = ArtistReducer.apply(params).all
+    @artists.to_json
   end
 end
 ```
 
-### Rack Middleware/Hash
+### Rack Middleware/Ruby Array
 This example runs a raw Rack app with Rack::Reducer mounted as middleware.
-It doesn't use an ORM at all -- it just stores data in a ruby hash.
+It doesn't use an ORM at all -- it just stores data in a ruby array.
 
 ```ruby
 # config.ru
@@ -197,8 +118,8 @@ ARTISTS = [
 ]
 
 app = Rack::Builder.new do
-  # dataset  is a hash, so filter functions use ruby hash methods
-  use Rack::Reducer, dataset: ARTISTS, filters: [
+  # dataset is an Array, so filter functions use Array methods
+  use Rack::Reducer::Middleware, dataset: ARTISTS, filters: [
     ->(genre:) { select { |item| item[:genre].match(/#{genre}/i) } },
     ->(name:) { select { |item| item[:name].match(/#{name}/i) } },
     ->(sort:) { sort_by { |item| item[sort.to_sym] } },
@@ -215,161 +136,92 @@ change the `env` key by passing a new name as option to `use`:
 
 ```ruby
 # config.ru
-use Rack::Reducer, key: 'myapp.custom_key', dataset: ARTISTS, filters: [
-  #an array of lambdas
+use Rack::Reducer::Midleware, key: 'custom.key', dataset: ARTISTS, filters: [
+  # an array of lambdas
 ]
 ```
 
-### Roda
-This example uses [Roda][roda] to handle requests, and [Sequel][sequel] as an
-ORM.
+### With Rails scopes
+The Rails [quickstart example](#use) created a reducer inside a
+controller, but if your filters use lots of ActiveRecord scopes, it might make
+more sense to keep your reducers in your models instead.
 
 ```ruby
-# app.rb
-require 'roda'
-require 'sequel'
-
-class App < Roda
-  plugin :json
-
-  DB = Sequel.connect ENV['DATABASE_URL']
+# app/models/artist.rb
+class Artist < ApplicationRecord
+  # filters get instance_exec'd against the dataset you provide -- in this case
+  # it's `self.all` -- so filters can use query methods, scopes, etc
+  Reducer = Rack::Reducer.create(
+    self.all,
+    ->(name:) { by_name(name) },
+    ->(genre:) { where(genre: genre) },
+    ->(sort:) { order(sort.to_sym) }
+  ]
 
-  QUERY = {
-    dataset: DB[:artists],
-    filters: [
-      ->(genre:) { where(genre: genre) },
-      ->(name:) { grep(:name, "%#{name}%", case_insensitive: true) },
-      ->(sort:) { order(sort.to_sym) },
-    ]
+  scope :by_name, lambda { |name|
+    where('lower(name) like ?', "%#{name.downcase}%")
   }
-  # Note that QUERY[:dataset] is a Sequel::Dataset, so the functions 
-  # in QUERY[:filters] use Sequel methods
-
-  route do |r|
-    r.get('artists') { Rack::Reducer.call(r.params, QUERY).to_a }
-  end
-end
-```
-
-### Hanami
-This example uses [Hanami][hanami] to handle requests, and hanami-model as an
-ORM.
-
-```ruby
-# apps/web/controllers/artists/index.rb
-module Web::Controllers::Artists
-  class Index
-    include Web::Action
-
-    def call(params)
-      @artists = ArtistRepository.new.reduce(params)
-      self.body = @artists.to_a.to_json
-    end
-  end
 end
 
-# lib/app_name/repositories/artist_repository.rb
-class ArtistRepository < Hanami::Repository
-  def reduce(params)
-    Rack::Reducer.call(params, dataset: artists.dataset, filters: [
-      ->(genre:) { where(genre: genre) },
-      ->(name:) { grep(:name, "%#{name}%", case_insensitive: true) },
-      ->(sort:) { order(sort.to_sym) },
-    ])
+# app/controllers/artists_controller.rb
+class ArtistsController < ApplicationController
+  def index
+    @artists = Artist::Reducer.apply(params)
+    render json: @artists
   end
 end
 ```
 
-### Advanced use in Rails and other frameworks
-The examples in the [introduction](#use) cover basic Rails use. The examples
-below cover more advanced use.
-
-If you're comfortable in a non-Rails stack, you can apply these advanced
-techniques there too.
-
-#### Default filters
+Default filters
+------------------------------------------
 Most of the time it makes sense to use *required* keyword arguments for each
 filter, and skip running the filter altogether when the keyword argments aren't
 present.
 
-But you may want to run a filter always, with a sensible default when the params
-don't specify a value. Ordering results is a common case.
-
-The code below will order by `params[:sort]` when it exists, and by name
-otherwise.
+But sometimes you'll want to run a filter with a default value, even when the
+required params are missing.  The code below will order by `params[:sort]` when
+it exists, and by name otherwise.
 
 ```ruby
 # app/controllers/artists_controller.rb
 class ArtistsController < ApplicationController
+  ArtistReducer = Rack::Reducer.create(
+    Artist.all,
+    ->(genre:) { where(genre: genre) },
+    ->(sort: 'name') { order(sort.to_sym) }
+  )
+
   def index
-    @artists = Rack::Reducer.call(params, dataset: Artist.all, filters: [
-      ->(genre:) { where(genre: genre) },
-      ->(sort: 'name') { order(sort.to_sym) }
-    ])
+    @artists = ArtistReducer.apply(params)
     render json: @artists
   end
 end
 ```
 
-#### Dynamically setting Reducer's initial dataset
-Rack::Reducer's mixin style only lets you target one initial dataset for
-reduction. If you need different initial datasets in different contexts, use
-the functional style:
+Calling Rack::Reducer as a function
+-------------------------------------------
+For a slight performance penalty (~5%), you can skip creating a reducer via
+`::create` and just call Rack::Reducer as a function. This can be useful when
+prototyping, mostly because you don't need to think about naming anything.
 
 ```ruby
 # app/controllers/artists_controller.rb
 class ArtistsController < ApplicationController
+  # Step 1: there is no step 2
   def index
-    @scope = current_user.admin? ? Artist.all : Artist.signed
-    @artists = Rack::Reducer.call(params, dataset: @scope, filters: [
-      ->(name:) { by_name(name) },
+    @artists = Rack::Reducer.call(params, dataset: Artist.all, filters: [
+      ->(name:) { where('lower(name) like ?', "%#{name.downcase}%") },
       ->(genre:) { where(genre: genre) },
-      ->(sort:) { order(sort.to_sym) }
     ])
     render json: @artists
   end
 end
 ```
 
-#### Chaining reduce with other ActiveRecord query methods
-In the mixin-style, you can chain `Model.reduce` with other ActiveRecord
-queries, as long as `reduce` is the first call in the chain:
-
-```ruby
-# app/models/artist.rb
-class Artist < ApplicationRecord
-  extend Rack::Reducer
-  reduces self.all, filters: [
-    # filters get instance_exec'd against the initial dataset, 
-    # in this case `self.all`, so filters can use query methods, scopes, etc
-    ->(name:) { by_name(name) },
-    ->(genre:) { where(genre: genre) },
-    ->(sort:) { order(sort.to_sym) }
-  ]
-
-  scope :by_name, lambda { |name|
-    where('lower(name) like ?', "%#{name.downcase}%")
-  }
-
-  # here's a scope we're not using in our Reducer filters,
-  # but will use in our controller
-  scope :signed, lambda { where(signed: true) }
-end
-
-# app/controllers/artists_controller.rb
-class ArtistsController < ApplicationController
-  def index
-    # you can chain reduce with other ActiveRecord queries,
-    # as long as reduce is first in the chain
-    @artists = Artist.reduce(params).signed
-    render json: @artists
-  end
-end
-```
 
 How Rack::Reducer Works
 --------------------------------------
-Rack::Reducer takes a dataset, a params hash, and an array of lambda functions.
+Rack::Reducer takes a dataset, an array of lambdas, and a params hash.
 
 To return filtered data, it calls Enumerable#[reduce][reduce] on your array of
 lambdas, with the reduction's initial value set to `dataset`.
@@ -387,42 +239,53 @@ filter functions. Reducer doesn't need to know anything about ActiveRecord,
 Sequel, Mongoid, etc -- it just `instance_exec`s your own code against your
 own dataset.
 
-### Security
-Rack::Reducer claims to "safely" map URL params to filters, but it accepts an
-unfiltered params hash. What gives?
+Performance
+---------------------
+For requests with empty params, Rack::Reducer has no measurable performance
+impact. For requests with populated params, Rack::Reducer is about 10% slower
+than a set of hand-coded conditionals, according to `spec/benchmarks.rb`.
 
-By using keyword arguments in your filter lambdas, you are explicitly naming
-the params you'll accept into your filters. Params that aren't keywords never 
-get evaluated.
+```
+ Conditionals (full)   530.000  i/100ms
+      Reducer (full)   432.000  i/100ms
+Conditionals (empty)   780.000  i/100ms
+     Reducer (empty)   808.000  i/100ms
+Calculating -------------------------------------
+ Conditionals (full)      4.864k (± 2.3%) i/s -     24.380k in   5.015551s
+      Reducer (full)      4.384k (± 1.3%) i/s -     22.032k in   5.026651s
+Conditionals (empty)      7.889k (± 1.7%) i/s -     39.780k in   5.043797s
+     Reducer (empty)      8.129k (± 1.7%) i/s -     41.208k in   5.070453s
+
+Comparison:
+     Reducer (empty):     8129.5 i/s
+Conditionals (empty):     7889.3 i/s - same-ish: difference falls within error
+ Conditionals (full):     4863.7 i/s - 1.67x  slower
+      Reducer (full):     4383.8 i/s - 1.85x  slower
+```
 
-For extra safety, you can typecast the params in your filters. Many ORMs
-handle this for you, but as an example:
+In Rails, note that `params` is never empty, so use `request.query_parameters`
+instead if you want to handle parameterless requests at top speed.
 
 ```ruby
-FILTERS = [
-  # typecast params[:name] to a string
-  ->(name:) { where(name: name.to_s) },
-  # typecast params[:updated_before] and params[:updated_after]
-  # to times, and set a default for updated_after if it's missing
-  lambda |updated_before:, updated_after: 1.month.ago| {
-    where(updated_at: updated_after.to_time..updated_before.to_time)
-  }
-]
-```
+# app/controllers/artists_controller.rb
+class ArtistController < ApplicationController
+  # ArtistReducer = Rack::Reducer.create(...etc etc)
 
-### Performance
-According to `spec/benchmarks.rb`, Rack::Reducer executes about 90% as quickly
-as a set of hard-coded conditional filters. It is unlikely to be a
-bottleneck in your application.
+  def index
+    @artists = ArtistReducer.apply(request.query_parameters)
+    render json: @artists
+  end
+end
+```
 
 Alternatives
 -------------------
 If you're working in Rails, Plataformatec's excellent [HasScope][has_scope] has
-been solving this problem since 2009. I prefer keeping my query logic all in one
-place, though, instead of spreading it across my controllers and models.
+been solving this problem since 2009. I prefer keeping my request logic all in
+one place, though, instead of spreading it across my controllers and models.
 
-[Periscope][periscope], by laserlemon, seems like another good Rails option, and
-though it's Rails only, it supports more than just ActiveRecord.
+[Periscope][periscope], by Steve Richert, seems like another solid Rails option.
+It is Rails-only, but it supports more than just ActiveRecord.
 
 For Sinatra, Simon Courtois has a [Sinatra port of has_scope][sin_has_scope].
 It depends on ActiveRecord.
@@ -434,7 +297,7 @@ Please open [an issue](https://github.com/chrisfrank/rack-reducer/issues) on
 Github.
 
 ### Pull Requests
-Please include tests, following the style of the specs in `spec/*_spec.rb`.
+PRs are welcome, and I'll do my best to review them promptly.
 
 License
 ----------
@@ -454,9 +317,6 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 [sin_has_scope]: https://github.com/simonc/sinatra-has_scope
 [sinatra]: https://github.com/sinatra/sinatra
 [sequel]: https://github.com/jeremyevans/sequel
-[roda]: https://github.com/jeremyevans/roda
 [reduce]: http://ruby-doc.org/core-2.5.0/Enumerable.html#method-i-reduce
 [keywords]: https://robots.thoughtbot.com/ruby-2-keyword-arguments
-[query_obj]: https://robots.thoughtbot.com/using-yieldself-for-composable-activerecord-relations
 [periscope]: https://github.com/laserlemon/periscope
-[hanami]: http://hanamirb.org

data/lib/rack/reducer/middleware.rb

@@ -1,21 +1,36 @@
+# frozen_string_literal: true
+
 require 'rack/request'
 require_relative 'reduction'
 
 module Rack
   module Reducer
     # Mount Rack::Reducer as middleware
+    # @example A microservice that filters artists
+    #   ArtistService = Rack::Builder.new do
+    #     use(
+    #       Rack::Reducer::Middleware,
+    #       dataset: Artist.all,
+    #       filters: [
+    #         lambda { |name:| where(name: name) },
+    #         lambda { |genre:| where(genre: genre) },
+    #       ]
+    #     )
+    #
+    #     run ->(env) {  [200, {}, [env['rack.reduction'].to_json]] }
+    #   end
     class Middleware
       def initialize(app, options = {})
         @app = app
         @key = options[:key] || 'rack.reduction'
-        @props = options
+        @reducer = Rack::Reducer.create(options[:dataset], *options[:filters])
       end
 
       # Call the next app in the middleware stack, with env[key] set
       # to the ouput of a reduction
       def call(env)
         params = Rack::Request.new(env).params
-        reduction = Reduction.new(@props.merge(params: params)).reduce
+        reduction = @reducer.apply(params)
         @app.call env.merge(@key => reduction)
       end
     end

data/lib/rack/reducer/reduction.rb

@@ -1,5 +1,6 @@
+# frozen_string_literal: true
+
 require_relative 'refinements'
-require_relative 'parser'
 
 module Rack
   module Reducer
@@ -8,26 +9,28 @@ module Rack
     class Reduction
       using Refinements # define Proc#required_argument_names, #satisfies?, etc
 
-      DEFAULTS = {
-        dataset: [],
-        filters: [],
-        params: nil
-      }.freeze
-
-      def initialize(options)
-        @props = DEFAULTS.merge(options)
-        @params = Parser.call(@props[:params])
+      def initialize(dataset, *filters)
+        @dataset = dataset
+        @filters = filters
       end
 
-      def reduce
-        @props[:filters].reduce(@props[:dataset]) do |data, filter|
-          next data unless filter.satisfies?(@params)
+      # Run +@filters+ against the params argument
+      # @param [Hash, ActionController::Parameters, nil] params
+      #   a Rack-compatible params hash
+      # @return +@dataset+ with the matching filters applied
+      def apply(params)
+        return @dataset if !params || params.empty?
 
-          data.instance_exec(@params.slice(*filter.all_argument_names), &filter)
+        symbolized_params = params.to_unsafe_h.symbolize_keys
+        @filters.reduce(@dataset) do |data, filter|
+          next data unless filter.satisfies?(symbolized_params)
+
+          data.instance_exec(
+            **symbolized_params.slice(*filter.all_argument_names),
+            &filter
+          )
         end
       end
     end
-
-    private_constant :Reduction
   end
 end

data/lib/rack/reducer/refinements.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Rack
   module Reducer
     # refine Proc and hash in this scope only
@@ -17,7 +19,7 @@ module Rack
         end
       end
 
-      # backport Hash#slice for older rubies
+      # backport Hash#slice for Ruby < 2.4
       unless {}.respond_to?(:slice)
         refine Hash do
           def slice(*keys)
@@ -25,6 +27,16 @@ module Rack
           end
         end
       end
+
+      refine Hash do
+        def symbolize_keys
+          each_with_object({}) do |(key, val), hash|
+            hash[key.to_sym] = val.is_a?(Hash) ? symbolize(val) : val
+          end
+        end
+
+        alias_method :to_unsafe_h, :to_h
+      end
     end
 
     private_constant :Refinements

data/lib/rack/reducer/version.rb

@@ -1,5 +1,7 @@
+# frozen_string_literal: true
+
 module Rack
   module Reducer
-    VERSION = '1.0.1'.freeze
+    VERSION = '1.1.0'
   end
 end