rack-reducer 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1877d2e46030a53f725c98db2652b4523d292c8f2d069633e7ea41a03effc211
-  data.tar.gz: 4681a5249f40b6669c4750ea8cfd7788c4f3cc01440d334aebe48b3b2cdf05c3
+  metadata.gz: a41029921e31a738165238e25af3300edc47c9a131b537ce597a313ba2060b4d
+  data.tar.gz: 2b1c09a05bb3f5af59344d9e65bbdb166a54c1d8d8bffbe34ba3bb8e768d6c4e
 SHA512:
-  metadata.gz: b02f1193154c6ae870fb0de14d0876e50adae875189e698b10532569601495465afdfb3a218ab6b04ac4831fdab1ff5d334e17a3bdf806c87f517962885ef963
-  data.tar.gz: ca39507186ea87517fa1148f29b30338b8326a79dc37f945823caecfbd06bf27e7bdd1a306fe05ce2c1e22dbbbe597c6dfa5928bc96ae2f68d50dce13f4076dd
+  metadata.gz: 7c6c6a069e7a9b6b9cdb1cf423143175cfa257215f69a2c7aaa7e027ac935d14073ed8192030af702f263441d38046671f26f635bd559d3cfe3c0743a1cb12a8
+  data.tar.gz: 9839e1d5a9cd4f4557ad0a87c24c1cee4a4ec5357f085baa894c81c7e8981eadc01f65de84656818ce13357ea7a6ef9d7cabef22c0a7b2d96e65cd1d32a455b3

data/README.md

@@ -3,8 +3,8 @@ 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, sort, and paginate data via URL params, with controller
-logic as simple as
+Dynamically filter and sort data via URL params, with controller logic as
+succint as
 
 ```ruby
 @artists = Artist.reduce(params)
@@ -23,41 +23,25 @@ gem 'rack-reducer', require: 'rack/reducer'
 
 Use
 ------------------------------------------
-Rack::Reducer safely maps incoming URL params to an array of filter functions
-you define, chains the applicable filters, and returns filtered data.
+If your app needs to render a list of database records, you probably want those
+records to be filterable via URL params, like so:
 
-Suppose you have some incoming requests like these...
-
-`GET /artists`  
-`GET /artists?name=janelle+monae`  
-`GET /artists?name=blake&genre=electronic`
-
-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`
-statements gets messy.
+```
+GET /artists?name=blake` => artists named 'blake'
+GET /artists?genre=electronic&sort=name => electronic artists, sorted by name
+GET /artists => all artists
+```
 
-### A Mess
+You _could_ conditionally apply filters with hand-written `if` statements, but
+that approach gets uglier the more filters you have.
 
-```ruby
-# app/controllers/artists_controller.rb
-class ArtistsController < ApplicationController
-  def index
-    @artists = Artist.all
-    @artists = @artists.where('lower(name) like ?', "%#{name.downcase}%") if params[:name]
-    @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 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.
 
-Rack::Reducer helps you clean this mess up, in your choice of two styles: mixin
-or functional.
+You can use Rack::Reducer in your choice of two styles: mixin or functional.
 
-### Cleaned up, mixin-style
+### Mixin style
 Call `Model.reduce(params)` in your controllers...
 
 ```ruby
@@ -70,52 +54,46 @@ class ArtistsController < ApplicationController
 end
 ```
 
-... and `extend Rack::Reducer` in your models:
+...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
+  extend Rack::Reducer
 
   # 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,
+  # in this case Artist class methods and scopes
   reduces self.all, filters: [
     ->(name:) { where('lower(name) like ?', "%#{name.downcase}%") },
     ->(genre:) { where(genre: genre) },
-    ->(order:) { order(order.to_sym) },
+    ->(sort:) { order(sort.to_sym) },
   ]
 end
 ```
 
-### Cleaned up, functional-style
-Call Rack::Reducer as a function:
+### 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
-  # this is an options hash that we'll pass to Rack::Reducer
-  QUERY = {
-    dataset: Artist.all,
-    filters: [
+  def index
+    @artists = Rack::Reducer.call(params, dataset: Artist.all, filters: [
       ->(name:) { where('lower(name) like ?', "%#{name.downcase}%") },
       ->(genre:) { where(genre: genre) },
-      ->(order:) { order(order.to_sym) },
-    ]
-  }
-
-  def index
-    @artists = Rack::Reducer.call(params, QUERY)
+      ->(sort:) { order(sort.to_sym) },
+    ])
     render json: @artists
   end
 end
 ```
 
-The mixin style requires less boilerplate, and is stylistically Railsier.
-The functional style is more flexible, and keeps your filtering logic all in
-one place. Both styles are supported, tested, and handle requests identically.
+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:
 
@@ -142,12 +120,13 @@ 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 arbitrary, just to
-demonstrate a few possible stacks.
+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)
 
@@ -167,13 +146,13 @@ class SinatraFunctionalApp < Sinatra::Base
     filters: [
       ->(genre:) { where(genre: genre) },
       ->(name:) { grep(:name, "%#{name}%", case_insensitive: true) },
-      ->(order:) { order(order.to_sym) },
+      ->(sort:) { order(sort.to_sym) },
     ]
   }
 
   get '/artists' do
     @artists = Rack::Reducer.call(params, QUERY).to_a
-    @artists.all.to_json
+    @artists.to_json
   end
 end
 ```
@@ -187,13 +166,13 @@ class SinatraMixinApp < Sinatra::Base
     reduces self.dataset, filters: [
       ->(genre:) { where(genre: genre) },
       ->(name:) { grep(:name, "%#{name}%", case_insensitive: true) },
-      ->(order:) { order(order.to_sym) },
+      ->(sort:) { order(sort.to_sym) },
     ]
   end
 
   get '/artists' do
     @artists = Artist.reduce(params)
-    @artists.all.to_json
+    @artists.to_a.to_json
   end
 end
 ```
@@ -221,7 +200,7 @@ app = Rack::Builder.new do
   use Rack::Reducer, dataset: ARTISTS, filters: [
     ->(genre:) { select { |item| item[:genre].match(/#{genre}/i) } },
     ->(name:) { select { |item| item[:name].match(/#{name}/i) } },
-    ->(order:) { sort_by { |item| item[order.to_sym] } },
+    ->(sort:) { sort_by { |item| item[sort.to_sym] } },
   ]
   run ->(env) { [200, {}, [env['rack.reduction'].to_json]] }
 end
@@ -240,7 +219,40 @@ use Rack::Reducer, key: 'myapp.custom_key', dataset: ARTISTS, filters: [
 ]
 ```
 
+### Roda
+This example uses [Roda][roda] to handle requests, and [Sequel][sequel] as an
+ORM.
+
+```ruby
+# app.rb
+require 'roda'
+require 'sequel'
+
+class App < Roda
+  plugin :json
+
+  DB = Sequel.connect ENV['DATABASE_URL']
+
+  QUERY = {
+    dataset: DB[:artists],
+    filters: [
+      ->(genre:) { where(genre: genre) },
+      ->(name:) { grep(:name, "%#{name}%", case_insensitive: true) },
+      ->(sort:) { order(sort.to_sym) },
+    ]
+  }
+  # 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
@@ -250,7 +262,7 @@ module Web::Controllers::Artists
 
     def call(params)
       @artists = ArtistRepository.new.reduce(params)
-      self.body = @artists.all.to_json
+      self.body = @artists.to_a.to_json
     end
   end
 end
@@ -261,19 +273,18 @@ class ArtistRepository < Hanami::Repository
     Rack::Reducer.call(params, dataset: artists.dataset, filters: [
       ->(genre:) { where(genre: genre) },
       ->(name:) { grep(:name, "%#{name}%", case_insensitive: true) },
-      ->(order:) { order(order.to_sym) },
+      ->(sort:) { order(sort.to_sym) },
     ])
   end
 end
 ```
 
-### Advanced use in Rails
+### 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. I wholeheartedly endorse [Roda][roda], and use
-Rack::Reducer with Roda/Sequel in production.
+techniques there too.
 
 #### Default filters
 Most of the time it makes sense to use *required* keyword arguments for each
@@ -283,7 +294,7 @@ 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[:order]` when it exists, and by name
+The code below will order by `params[:sort]` when it exists, and by name
 otherwise.
 
 ```ruby
@@ -292,9 +303,9 @@ class ArtistsController < ApplicationController
   def index
     @artists = Rack::Reducer.call(params, dataset: Artist.all, filters: [
       ->(genre:) { where(genre: genre) },
-      ->(order: 'name') { order(order.to_sym) }
+      ->(sort: 'name') { order(sort.to_sym) }
     ])
-    @artists.to_json
+    render json: @artists
   end
 end
 ```
@@ -312,9 +323,9 @@ class ArtistsController < ApplicationController
     @artists = Rack::Reducer.call(params, dataset: @scope, filters: [
       ->(name:) { by_name(name) },
       ->(genre:) { where(genre: genre) },
-      ->(order:) { order(order.to_sym) }
+      ->(sort:) { order(sort.to_sym) }
     ])
-    @artists.to_json
+    render json: @artists
   end
 end
 ```
@@ -332,7 +343,7 @@ class Artist < ApplicationRecord
     # 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) }
+    ->(sort:) { order(sort.to_sym) }
   ]
 
   scope :by_name, lambda { |name|
@@ -350,7 +361,7 @@ class ArtistsController < ApplicationController
     # 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
+    render json: @artists
   end
 end
 ```
@@ -359,8 +370,8 @@ How Rack::Reducer Works
 --------------------------------------
 Rack::Reducer takes a dataset, a params hash, and an array of lambda functions.
 
-To return filtered data, it calls [reduce][reduce] on your array of lambdas,
-with the reduction's initial value set to `dataset`.
+To return filtered data, it calls Enumerable#[reduce][reduce] on your array of
+lambdas, with the reduction's initial value set to `dataset`.
 
 Each reduction looks for keys in the `params` hash that match the
 current lambda's [keyword arguments][keywords]. If the keys exist, it
@@ -372,7 +383,8 @@ execute at all, and just pass the unaltered dataset down the chain.
 
 The reason Reducer works with any ORM is that *you* supply the dataset and
 filter functions. Reducer doesn't need to know anything about ActiveRecord,
-Mongoid, etc -- it just `instance_exec`s your own code against your own dataset.
+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
@@ -382,7 +394,7 @@ 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 extra safety, you can typecast the params in your filters. Most ORMs
+For extra safety, you can typecast the params in your filters. Many ORMs
 handle this for you, but as an example:
 
 ```ruby
@@ -404,8 +416,8 @@ 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
+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.
 
 [Periscope][periscope], by laserlemon, seems like another good Rails option, and
@@ -446,3 +458,4 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 [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/spec/_rails_example/app/models/rails_example/artist.rb

@@ -14,7 +14,8 @@ module RailsExample
       # or scopes...
       ->(name:) { by_name(name) },
       # or inline ActiveRecord queries
-      ->(order:) { order(order.to_sym) }
+      ->(order:) { order(order.to_sym) },
+      ->(releases: ) { where(release_count: releases.to_i) },
     ]
   end
 end

data/spec/behavior.rb

@@ -35,6 +35,13 @@ shared_examples_for Rack::Reducer do
     end
   end
 
+  it 'handles falsy values' do
+    get('/artists?releases=0') do |response|
+      expect(response.body).to include('Chris Frank')
+      expect(JSON.parse(response.body).length).to eq(1)
+    end
+  end
+
   it 'can sort as well as filter' do
     get '/artists?order=genre' do |response|
       genre = JSON.parse(response.body)[0]['genre']

data/spec/middleware_spec.rb

@@ -9,7 +9,8 @@ module MiddlewareTest
     filters: [
       ->(genre:) { select { |item| item[:genre].match(/#{genre}/i) } },
       ->(name:) { select { |item| item[:name].match(/#{name}/i) } },
-      ->(order:) { sort_by { |item| item[order.to_sym] } }
+      ->(order:) { sort_by { |item| item[order.to_sym] } },
+      ->(releases:) { select { |item| item[:release_count] == releases.to_i } },
     ]
   }
 

data/spec/roda_spec.rb

@@ -4,9 +4,7 @@ require 'roda'
 class RodaTest < Roda
   plugin :json
   route do |r|
-    r.on 'artists' do
-      r.get { Rack::Reducer.call(r.params, SEQUEL_QUERY).to_a }
-    end
+    r.get('artists') { Rack::Reducer.call(r.params, SEQUEL_QUERY).to_a }
   end
 end
 

data/spec/sinatra_mixin_spec.rb

@@ -6,11 +6,7 @@ class SinatraMixin < Sinatra::Base
   class Artist < Sequel::Model
     plugin :json_serializer
     extend Rack::Reducer
-    reduces dataset, filters: [
-      ->(genre:) { grep(:genre, "%#{genre}%", case_insensitive: true) },
-      ->(name:) { grep(:name, "%#{name}%", case_insensitive: true) },
-      ->(order:) { order(order.to_sym) }
-    ]
+    reduces dataset, filters: SEQUEL_QUERY[:filters]
   end
 
   get '/artists' do

data/spec/spec_helper.rb

@@ -13,7 +13,8 @@ SEQUEL_QUERY = {
   filters: [
     ->(genre:) { grep(:genre, "%#{genre}%", case_insensitive: true) },
     ->(name:) { grep(:name, "%#{name}%", case_insensitive: true) },
-    ->(order: 'genre') { order(order.to_sym) }
+    ->(order: 'genre') { order(order.to_sym) },
+    ->(releases: ) { where(release_count: releases.to_i) },
   ]
 }.freeze
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rack-reducer
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Chris Frank
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-03-27 00:00:00.000000000 Z
+date: 2018-04-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -288,7 +288,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.7.3
+rubygems_version: 2.7.6
 signing_key: 
 specification_version: 4
 summary: Dynamically filter data via URL params, in any Rack app.