rack-reducer 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1fd376a5091b8dac2c04e97b36e3e8880e7cfaecf01e1ef25d69580b30ba0bc4
-  data.tar.gz: 7511b21435b309a104381dc2a5a3ccaad4b3b916d937de986c7087b7632ebe95
+  metadata.gz: 1877d2e46030a53f725c98db2652b4523d292c8f2d069633e7ea41a03effc211
+  data.tar.gz: 4681a5249f40b6669c4750ea8cfd7788c4f3cc01440d334aebe48b3b2cdf05c3
 SHA512:
-  metadata.gz: 482102225a82151f8bbb0036ad4234f9caa741d112477f367e36c63e5c86e688defff43c130f70a0e88b1d006673e42d095228eeb376a86acd0d327c441a14e1
-  data.tar.gz: af0473c9840adfea73479dffe3def6c96ca46fa9b1452bbefd9c680b1231f767ff9179dcedfa30a501b10b5726f77e677e500ff666db4ce73b70b128049e788f
+  metadata.gz: b02f1193154c6ae870fb0de14d0876e50adae875189e698b10532569601495465afdfb3a218ab6b04ac4831fdab1ff5d334e17a3bdf806c87f517962885ef963
+  data.tar.gz: ca39507186ea87517fa1148f29b30338b8326a79dc37f945823caecfbd06bf27e7bdd1a306fe05ce2c1e22dbbbe597c6dfa5928bc96ae2f68d50dce13f4076dd

data/README.md

@@ -1,12 +1,17 @@
 Rack::Reducer
 ==========================================
-Safely map URL params to database filters, in any Rack app. If your users need
-to filter or sort data by making HTTP requests, this gem can help.
+[![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)
 
-If you're working in Rails, note that Rack::Reducer solves the same problem
-as Platformatec's excellent [HasScope][has_scope]. But Rack::Reducer works in
-any Rack app, with any ORM, or without an ORM at all. Even in Rails, Reducer's
-simpler, more functional API may be a better fit for your needs.
+Dynamically filter, sort, and paginate data via URL params, with controller
+logic as simple as
+
+```ruby
+@artists = Artist.reduce(params)
+```
+
+Rack::Reducer works in any Rack-compatible app, with any ORM, and has no
+dependencies beyond Rack itself.
 
 Install
 ------------------------------------------
@@ -18,8 +23,8 @@ gem 'rack-reducer', require: 'rack/reducer'
 
 Use
 ------------------------------------------
-Rack::Reducer maps incoming URL params to an array of filter functions you
-define, chains the applicable filters, and returns filtered data.
+Rack::Reducer safely maps incoming URL params to an array of filter functions
+you define, chains the applicable filters, and returns filtered data.
 
 Suppose you have some incoming requests like these...
 
@@ -30,7 +35,7 @@ Suppose you have some incoming requests like these...
 You want to filter your `artists` table by name and/or genre when those
 params are present, or return all artists otherwise.
 
-Even with just a few optional filters, running them conditonally via `if` 
+Even with just a few optional filters, running them conditonally via `if`
 statements gets messy.
 
 ### A Mess
@@ -44,40 +49,39 @@ class ArtistsController < ApplicationController
     @artists = @artists.where(genre: params[:genre]) if params[:genre]
     @artists = @artists.order(params[:order].to_sym) if params[:order]
     # ...
-    # ...
     # pages later...
     @artists.all.to_json
   end
 ```
 
-Rack::Reducer lets you chain filters elegantly, whether you're chaining two
-filters or twenty. You can use it by extending it in your models, or by
-calling it as a function.
+Rack::Reducer helps you clean this mess up, in your choice of two styles: mixin
+or functional.
 
-### Cleaned up by extending Rack::Reducer
+### Cleaned up, mixin-style
 Call `Model.reduce(params)` in your controllers...
 
 ```ruby
 # app/controllers/artists_controller.rb
-class ArtistsController < ApplicatonController
+class ArtistsController < ApplicationController
   def index
     @artists = Artist.reduce(params)
-    @artists.all.to_json
+    render json: @artists
   end
 end
 ```
 
 ... and `extend Rack::Reducer` in your models:
+
 ```ruby
 # app/models/artist.rb
 class Artist < ActiveRecord::Base
   extend Rack::Reducer # makes `self.reduce` available at class level
 
-  # configure by calling
+  # Configure by calling
   # `reduces(some_initial_scope, filters: [an, array, of, lambdas])`
   #
-  # filters can use any methods your initial dataset understands.
-  # here it's an ActiveRecord query, so filters use AR query methods
+  # Filters can use any methods your initial dataset understands.
+  # Here it's an ActiveRecord query, so filters use AR query methods.
   reduces self.all, filters: [
     ->(name:) { where('lower(name) like ?', "%#{name.downcase}%") },
     ->(genre:) { where(genre: genre) },
@@ -86,29 +90,34 @@ class Artist < ActiveRecord::Base
 end
 ```
 
-### Cleaned up by calling Rack::Reducer as a function
-If you prefer composition to inheritance, you can call Rack::Reducer as a
-function instead of extending it. The functional style can (a) help keep
-your filtering logic in one file, and (b) let you use Rack::Reducer without
-polluting your model's methods.
+### Cleaned up, functional-style
+Call Rack::Reducer as a function:
 
 ```ruby
 # app/controllers/artists_controller.rb
 class ArtistsController < ApplicationController
-  def index
-    @artists = Rack::Reducer.call(params, dataset: Artist.all, filters: [
+  # this is an options hash that we'll pass to Rack::Reducer
+  QUERY = {
+    dataset: Artist.all,
+    filters: [
       ->(name:) { where('lower(name) like ?', "%#{name.downcase}%") },
       ->(genre:) { where(genre: genre) },
       ->(order:) { order(order.to_sym) },
-    ])
-    @artists.all.to_json
+    ]
+  }
+
+  def index
+    @artists = Rack::Reducer.call(params, QUERY)
+    render json: @artists
   end
 end
 ```
 
 The mixin style requires less boilerplate, and is stylistically Railsier.
-The functional style is more flexible. Both styles are supported, tested, and
-handle requests identically. In the examples above:
+The functional style is more flexible, and keeps your filtering logic all in
+one place. Both styles are supported, tested, and handle requests identically.
+
+In the examples above:
 
 ```ruby
 # GET /artists returns all artists, e.g.
@@ -120,13 +129,13 @@ handle requests identically. In the examples above:
   { "name": "SZA", "genre": "alt-soul" }
 ]
 
-# GET /artists?name=blake returns e.g.
+# GET /artists?name=blake returns artists named 'blake',  e.g.
 [
   { "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 returns e.g.
 [{ "name": "James Blake", "genre": "electronic" }]
 ```
 
@@ -134,50 +143,56 @@ handle requests identically. In the examples above:
 Framework-specific Examples
 ---------------------------
 These examples apply Rack::Reducer in different frameworks, with a different
-ORM each time. The pairings of ORMs and frameworks are abitrary, just to
+ORM each time. The pairings of ORMs and frameworks are arbitrary, just to
 demonstrate a few possible stacks.
 
-- [Sinatra](#sinatrasequel)
-- [Rack Middleware](#rack-middlewarehash)
-- [Rails](#railsadvanced)
+- [Sinatra/Sequel](#sinatrasequel)
+- [Rack Middleware/Ruby Hash](#rack-middlewarehash)
+- [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.
 
-#### Mixin-style
+#### Functional-style
 ```ruby
-# sintra_mixin_style.rb
-class SinatraMixinApp < Sinatra::Base
-  class Artist < Sequel::Model
-    extend Rack::Reducer
-    reduces self.dataset, filters: [
+# sinatra_functional_style.rb
+class SinatraFunctionalApp < 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) },
       ->(order:) { order(order.to_sym) },
     ]
-  end
-  
+  }
+
   get '/artists' do
-    @artists = Artist.reduce(params)
+    @artists = Rack::Reducer.call(params, QUERY).to_a
     @artists.all.to_json
   end
 end
 ```
 
-#### Functional style
+#### Mixin-style
 ```ruby
-# sinatra_functional_style.rb
-class SinatraFunctionalApp < Sinatra::Base
-  DB = Sequel.connect ENV['DATABASE_URL']
-  
-  get '/artists' do
-    # dataset is a Sequel::Dataset, so filters use Sequel query methods
-    @artists = Rack::Reducer.call(params, dataset: DB[:artists], filters: [
+# 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) },
       ->(order:) { order(order.to_sym) },
-    ])
+    ]
+  end
+
+  get '/artists' do
+    @artists = Artist.reduce(params)
     @artists.all.to_json
   end
 end
@@ -185,7 +200,7 @@ end
 
 ### Rack Middleware/Hash
 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 hash.
+It doesn't use an ORM at all -- it just stores data in a ruby hash.
 
 ```ruby
 # config.ru
@@ -225,7 +240,34 @@ use Rack::Reducer, key: 'myapp.custom_key', dataset: ARTISTS, filters: [
 ]
 ```
 
-### Rails/Advanced
+### Hanami
+
+```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.all.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) },
+      ->(order:) { order(order.to_sym) },
+    ])
+  end
+end
+```
+
+### Advanced use in Rails
 The examples in the [introduction](#use) cover basic Rails use. The examples
 below cover more advanced use.
 
@@ -233,47 +275,34 @@ If you're comfortable in a non-Rails stack, you can apply these advanced
 techniques there too. I wholeheartedly endorse [Roda][roda], and use
 Rack::Reducer with Roda/Sequel in production.
 
-#### 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) },
-    ->(order:) { order(order.to_sym) }
-  ]
+#### 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.
 
-  scope :by_name, lambda { |name|
-    where('lower(name) like ?', "%#{name.downcase}%")
-  }
+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.
 
-  # 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
+The code below will order by `params[:order]` when it exists, and by name
+otherwise.
 
+```ruby
 # 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
+    @artists = Rack::Reducer.call(params, dataset: Artist.all, filters: [
+      ->(genre:) { where(genre: genre) },
+      ->(order: 'name') { order(order.to_sym) }
+    ])
     @artists.to_json
   end
 end
 ```
 
-
 #### Dynamically setting Reducer's initial dataset
-Rack::Reducer's mixin style only lets you target one dataset for reduction.
-If you need different initial data in different contexts, and don't want to
-determine that data via filters, you can use the functional style:
+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:
 
 ```ruby
 # app/controllers/artists_controller.rb
@@ -290,31 +319,42 @@ class ArtistsController < ApplicationController
 end
 ```
 
-#### 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.
+#### 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:
 
-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.
+```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) },
+    ->(order:) { order(order.to_sym) }
+  ]
 
-The code below will order by `params[:order]` when it exists, and by name
-otherwise.
+  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
 
-```ruby
 # app/controllers/artists_controller.rb
 class ArtistsController < ApplicationController
   def index
-    @artists = Rack::Reducer.call(params, dataset: Artist.all, filters: [
-      ->(genre:) { where(genre: genre) },
-      ->(order: 'name') { order(order.to_sym) }
-    ])
+    # you can chain reduce with other ActiveRecord queries,
+    # as long as reduce is first in the chain
+    @artists = Artist.reduce(params).signed
     @artists.to_json
   end
 end
 ```
 
-
 How Rack::Reducer Works
 --------------------------------------
 Rack::Reducer takes a dataset, a params hash, and an array of lambda functions.
@@ -338,11 +378,11 @@ Mongoid, etc -- it just `instance_exec`s your own code against your own dataset.
 Rack::Reducer claims to "safely" map URL params to filters, but it accepts an
 unfiltered params hash. What gives?
 
-By using keyword arguments in your filter lambdas, you are *explicitly* naming
+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.
 
-For even more security, you can typecast the params in your filters. Most ORMs
+For extra safety, you can typecast the params in your filters. Most ORMs
 handle this for you, but as an example:
 
 ```ruby
@@ -358,25 +398,51 @@ FILTERS = [
 ```
 
 ### Performance
-According to `spec/benchmarks.rb`, Rack::Reducer executes about 90% as quickly 
-as a set of hard-coded conditional filters. It is extremly unlikely to be a
+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.
 
+Alternatives
+-------------------
+If you're working in Rails, Platformatec's excellent [HasScope][has_scope] has
+been solving this problem since 2013. I prefer keeping my query 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.
+
+For Sinatra, Simon Courtois has a [Sinatra port of has_scope][sin_has_scope].
+It depends on ActiveRecord.
 
 Contributing
 -------------------------------
 ### Bugs
-Open [an issue](https://github.com/chrisfrank/rack-reducer/issues) on Github.
+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`.
 
+License
+----------
+### MIT
+
+Copyright 2018 Chris Frank
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
 
 
 [has_scope]: https://github.com/plataformatec/has_scope
+[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

data/lib/rack/reducer/middleware.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative 'reduction'
+
+module Rack
+  module Reducer
+    # Mount Rack::Reducer as middleware
+    class Middleware
+      def initialize(app, options = {})
+        @app = app
+        @key = options[:key] || 'rack.reduction'
+        @props = options
+      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
+        @app.call env.merge(@key => reduction)
+      end
+    end
+  end
+end

data/lib/rack/reducer/reduction.rb

@@ -13,20 +13,12 @@ module Rack
       DEFAULTS = {
         dataset: [],
         filters: [],
-        key: 'rack.reduction',
         params: nil
       }.freeze
 
-      def initialize(app, props)
-        @app = app
-        @props = DEFAULTS.merge(props)
-      end
-
-      # when mounted as middleware, set env[@props[:key]] to the output
-      # of self.reduce, then call the next app in the middleware stack
-      def call(env)
-        @params = Rack::Request.new(env).params.symbolize_keys
-        @app.call env.merge(@props[:key] => reduce)
+      def initialize(options)
+        @props = DEFAULTS.merge(options)
+        @params = Parser.call(@props[:params]).symbolize_keys
       end
 
       def reduce
@@ -35,14 +27,10 @@ module Rack
 
       private
 
-      def params
-        @params ||= Parser.call(@props[:params]).symbolize_keys
-      end
-
       def apply_filter(data, fn)
         requirements = fn.required_argument_names.to_set
-        return data unless params.satisfies?(requirements)
-        data.instance_exec(params.slice(*fn.all_argument_names), &fn)
+        return data unless @params.satisfies?(requirements)
+        data.instance_exec(@params.slice(*fn.all_argument_names), &fn)
       end
     end
   end

data/lib/rack/reducer.rb

@@ -2,25 +2,26 @@
 
 require 'rack/request'
 require_relative 'reducer/reduction'
+require_relative 'reducer/middleware'
 
 module Rack
-  # use request params to apply filters to a dataset
+  # Use request params to apply filters to a dataset
   module Reducer
-    # call Rack::Reducer as a function, instead of mounting it as middleware
+    # Call Rack::Reducer as a function
     def self.call(params, dataset:, filters:)
       Reduction.new(
-        nil, # first arg to Reduction is `app`, which is for middleware only
         params: params,
         filters: filters,
-        dataset: dataset,
+        dataset: dataset
       ).reduce
     end
 
+    # Mount Rack::Reducer as middleware
     def self.new(app, options = {})
-      Reduction.new(app, options)
+      Middleware.new(app, options)
     end
 
-    # extend Rack::Reducer to get `reduce` and `reduces` as class-methods
+    # Extend Rack::Reducer to get `reduce` and `reduces` as class-methods
     #
     # class Artist < SomeORM::Model
     #   extend Rack::Reducer
@@ -31,7 +32,6 @@ module Rack
     # end
     def reduce(params)
       Reduction.new(
-        nil,
         params: params,
         filters: @rack_reducer_filters,
         dataset: @rack_reducer_dataset