rack-reducer 1.0.1 → 1.1.0

data/lib/rack/reducer/warnings.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Rack
+  module Reducer
+    module Warnings
+      MESSAGES = {
+        new: [
+          'Rack::Reducer.new will become an alias of ::create in v2.',
+          'To mount middleware that will still work in 2.0, write',
+          '"use Rack::Reducer::Middleware" instead of "use Rack::Reducer"',
+        ],
+        reduces: [
+          'Rack::Reducer’s mixin-style is deprecated and may be removed in v2.',
+          'To keep using Rack::Reducer in your models, use a Reducer constant.',
+          'class MyModel',
+          '  MyReducer = Rack::Reducer.create(dataset, *filter_functions)',
+          'end',
+          'MyModel::MyReducer.call(params)',
+        ]
+      }.freeze
+
+      def self.[](key)
+        MESSAGES.fetch(key, []).join("\n")
+      end
+    end
+  end
+end

data/lib/rack/reducer.rb

@@ -1,38 +1,64 @@
+# frozen_string_literal: true
+
 require_relative 'reducer/reduction'
 require_relative 'reducer/middleware'
+require_relative 'reducer/warnings'
 
 module Rack
-  # Use request params to apply filters to a dataset
+  # Declaratively filter data via URL params, in any Rack app.
   module Reducer
-    # Filter a dataset
+    # Create a Reduction object that can filter +dataset+ via +#apply+.
+    # @param [Object] dataset an ActiveRecord::Relation, Sequel::Dataset,
+    #   or other class with chainable methods
+    # @param [Array<Proc>] filters  An array of lambdas whose keyword arguments
+    #   name the URL params you will use as filters
+    # @return Rack::Reducer::Reduction
+    # @example Create a reducer and use it in a Sinatra app
+    #   DB = Sequel.connect(ENV['DATABASE_URL'])
+    #   MyReducer = Rack::Reducer.create(
+    #     DB[:artists],
+    #     lambda { |name:| where(name: name) },
+    #     lambda { |genre:| where(genre: genre) },
+    #   )
+    #
+    #   get '/artists' do
+    #     @artists = MyReducer.apply(params)
+    #     @artists.to_json
+    #   end
+    def self.create(dataset, *filters)
+      Reduction.new(dataset, *filters)
+    end
+
+    # Filter a dataset without creating a Reducer first.
+    # Note that this approach is a bit slower and less memory-efficient than
+    # creating a Reducer via ::create. Use ::create when you can.
+    #
     # @param params [Hash] Rack-compatible URL params
     # @param dataset [Object] A dataset, e.g. one of your App's models
     # @param filters [Array<Proc>] An array of lambdas with keyword arguments
     # @example Call Rack::Reducer as a function in a Sinatra app
-    #   ArtistReducer = {
-    #     dataset: Artist,
-    #     filters: [
+    #   get '/artists' do
+    #     @artists = Rack::Reducer.call(params, dataset: Artist.all, filters: [
     #       lambda { |name:| where(name: name) },
     #       lambda { |genre:| where(genre: genre) },
-    #     ]
-    #   }
-    #   get '/artists' do
-    #     @artists = Rack::Reducer.call(params, ArtistReducer)
+    #     ])
     #   end
     def self.call(params, dataset:, filters:)
-      Reduction.new(
-        params: params,
-        filters: filters,
-        dataset: dataset
-      ).reduce
+      Reduction.new(dataset, *filters).apply(params)
     end
 
     # Mount Rack::Reducer as middleware
+    # @deprecated
+    #   Rack::Reducer.new will become an alias of ::create in v2.0.
+    #   To mount middleware that will still work in 2.0, write
+    #   "use Rack::Reducer::Middleware" instead of "use Rack::Reducer"
     def self.new(app, options = {})
+      warn "#{caller(1..1).first}}\n#{Warnings[:new]}"
       Middleware.new(app, options)
     end
 
     # Extend Rack::Reducer to get +reduce+ and +reduces+ as class-methods
+    #
     # @example Make an "Artists" model reducible
     #   class Artist < SomeORM::Model
     #     extend Rack::Reducer
@@ -41,15 +67,20 @@ module Rack
     #       lambda { |genre:| where(genre: genre) },
     #     ]
     #   end
-    #
     #   Artist.reduce(params)
+    #
+    # @deprecated
+    #   Rack::Reducer's mixin-style is deprecated and may be removed in 2.0.
+    #   To keep using Rack::Reducer in your models, create a Reducer constant.
+    #     class MyModel < ActiveRecord::Base
+    #       MyReducer = Rack::Reducer.create(dataset, *filter_functions)
+    #     end
+    #     MyModel::MyReducer.call(params)
     def reduces(dataset, filters:)
+      warn "#{caller(1..1).first}}\n#{Warnings[:reduces]}"
+      reducer = Reduction.new(dataset, *filters)
       define_singleton_method :reduce do |params|
-        Reduction.new(
-          params: params,
-          filters: filters,
-          dataset: dataset,
-        ).reduce
+        reducer.apply(params)
       end
     end
   end

data/spec/benchmarks.rb

@@ -1,40 +1,70 @@
-require_relative 'spec_helper'
-require 'sinatra/base'
+require 'rack'
+require 'pry'
 require 'json'
+require_relative '../lib/rack/reducer'
 require 'benchmark/ips'
+require_relative 'fixtures'
+require 'sequel'
 
-Conditionals = lambda do |params = {}|
+DB = Sequel.sqlite.tap do |db|
+  db.create_table(:artists) do
+    primary_key :id
+    String :name
+    String :genre
+    Integer :release_count
+  end
+  Fixtures::DB[:artists].each { |row| db[:artists].insert(row) }
+end
+
+conditional_app = lambda do |env|
+  params = Rack::Request.new(env).params
   @artists = DB[:artists]
-  if (genre = params[:genre])
-    @artists = @artists.grep(:genre, "%#{genre}%", case_insensitive: true)
+  if (genre = params['genre'])
+    @artists = @artists.where(genre: genre.to_s)
   end
-  if (name = params[:name])
+  if (name = params['name'])
     @artists = @artists.grep(:name, "%#{name}%", case_insensitive: true)
   end
-
-  @artists.to_json
+  Rack::Response.new(@artists).finish
 end
 
-Reduction = lambda do |params = {}|
-  @artists = Rack::Reducer.call(params, dataset: DB[:artists], filters: [
-    ->(genre:) { grep(:genre, "%#{genre}%", case_insensitive: true) },
-    ->(name:) { grep(:name, "%#{name}%", case_insensitive: true) },
-  ])
+TestReducer = Rack::Reducer.create(
+  DB[:artists],
+  ->(genre:) { where(genre: genre.to_s) },
+  ->(name:) { grep(:name, "%#{name}%", case_insensitive: true) },
+)
 
-  @artists.to_json
+reducer_app = lambda do |env|
+  params = Rack::Request.new(env).params
+  @artists = TestReducer.apply(params)
+  Rack::Response.new(@artists).finish
 end
 
-Benchmark.ips(3) do |bm|
-  bm.report('conditionals, empty params') { Conditionals.call }
+Benchmark.ips do |bm|
+  env = {
+    'REQUEST_METHOD' => 'GET',
+    'PATH_INFO' => '/',
+    'rack.input' => StringIO.new('')
+  }
 
-  bm.report('reduction, empty params') { Reduction.call }
+  query = {
+    'QUERY_STRING' => 'name=blake&genre=electronic',
+  }
+
+  bm.report('Conditionals (full)') do
+    conditional_app.call env.merge(query)
+  end
+
+  bm.report('Reducer (full)') do
+    reducer_app.call env.merge(query)
+  end
 
-  bm.report('conditionals, full params') do
-    Conditionals.call({ name: 'blake', genre: 'electric' })
+  bm.report('Conditionals (empty)') do
+    conditional_app.call env.dup
   end
 
-  bm.report('reduction, full params') do
-    Reduction.call({ name: 'blake', genre: 'electric' })
+  bm.report('Reducer (empty)') do
+    reducer_app.call env.dup
   end
 
   bm.compare!

data/spec/fixtures.rb

@@ -0,0 +1,30 @@
+module Fixtures
+  DB = {
+    artists: [
+      { name: 'Blake Mills', genre: 'alternative', release_count: 3 },
+      { name: 'Björk', genre: 'electronic', release_count: 3 },
+      { name: 'James Blake', genre: 'electronic', release_count: 3 },
+      { name: 'Janelle Monae', genre: 'alt-soul', release_count: 3 },
+      { name: 'SZA', genre: 'alt-soul', release_count: 3 },
+      { name: 'Chris Frank', genre: 'alt-soul', release_count: nil },
+    ]
+  }
+
+  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] }
+    },
+    ->(releases:) {
+      select { |item| item[:release_count].to_i == releases.to_i }
+    },
+  ]
+
+  ArtistReducer = Rack::Reducer.create(DB[:artists], *FILTERS)
+end
+

data/spec/middleware_spec.rb

@@ -1,31 +1,63 @@
 require 'spec_helper'
-require 'json'
+require_relative 'fixtures'
 
-# mount Rack::Reducer as middleware, let it filter data into env['rack.reduction'],
-# and respond with env['rack.reduction'].to_json
-module MiddlewareTest
-  DEFAULTS = {
-    dataset: DB[:artists].all,
-    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] } },
-      ->(releases:) { select { |item| item[:release_count] == releases.to_i } },
-    ]
-  }
+RSpec.describe Rack::Reducer::Middleware do
+  using SpecRefinements
+  module AppFactory
+    def self.create(key: nil, middleware_class: Rack::Reducer::Middleware)
+      Rack::Builder.new do
+        use(
+          middleware_class,
+          dataset: Fixtures::DB[:artists],
+          filters: Fixtures::FILTERS,
+          key: key
+        )
+        run ->(env) {  [200, {}, [env.to_json]] }
+      end
+    end
+  end
+
+  describe 'without a key set' do
+    let(:app) { AppFactory.create }
+    it 'responds with unfiltered data when filter params are empty' do
+      get('/') do |res|
+        reduction = res.json['rack.reduction']
+        expect(reduction.count).to eq(Fixtures::DB[:artists].count)
+      end
+    end
 
-  def self.app(options = {}, key = options[:key] || 'rack.reduction')
-    Rack::Builder.new do
-      use Rack::Reducer, DEFAULTS.merge(options)
-      run ->(env) { [200, {}, [env[key].to_json]] }
+    it 'filters by a single param, e.g. name' do
+      get('/artists?name=Blake') do |res|
+        reduction = res.body
+        expect(reduction).to include('Blake Mills')
+        expect(reduction).to include('James Blake')
+        expect(reduction).not_to include('SZA')
+      end
     end
   end
-end
 
-describe MiddlewareTest.app do
-  it_behaves_like Rack::Reducer
-end
+  describe 'with a custom key' do
+    let(:app) { AppFactory.create(key: 'custom_key') }
+    it 'stores reducer data at env[custom_key]' do
+      get('/') do |res|
+        expect(res.json['custom_key'].class).to eq(Array)
+      end
+    end
+  end
+
+  describe 'using Rack::Reducer instead of Rack::Reducer::Middleware' do
+    before do
+      @warnings = []
+      allow(Rack::Reducer).to receive(:warn) do |msg|
+        @warnings << msg
+      end
+    end
 
-describe MiddlewareTest.app(key: 'some.custom.key') do
-  it_behaves_like Rack::Reducer
+    let(:app) { AppFactory.create(middleware_class: Rack::Reducer) }
+
+    it 'emits a deprecation warning' do
+      get('/')
+      expect(@warnings.last).to include('alias of ::create')
+    end
+  end
 end

data/spec/rails_spec.rb

@@ -1,6 +1,36 @@
 require 'spec_helper'
-require_relative '_rails_example/config/environment'
+require_relative 'fixtures'
+require 'action_controller/railtie'
+require 'securerandom'
 
-describe Rails.application do
-  it_behaves_like Rack::Reducer
+class RailsApp < Rails::Application
+  routes.append do
+    get "/", to: "artists#index"
+    get "/query", to: "artists#query"
+  end
+
+  config.api_only = true
+  config.eager_load = true
+  config.secret_key_base = SecureRandom.hex(64)
+end
+
+class ArtistsController < ActionController::API
+  def index
+    @artists = Fixtures::ArtistReducer.apply(params)
+    render json: @artists
+  end
+
+  def query
+    @artists = Fixtures::ArtistReducer.apply(request.query_parameters)
+    render json: @artists
+  end
+end
+
+RSpec.describe RailsApp do
+  let(:app) { RailsApp.initialize! }
+
+  it 'works with ActionController::Parameters and a plain hash' do
+    get('/') { |res| expect(res.status).to eq(200) }
+    get('/query') { |res| expect(res.status).to eq(200) }
+  end
 end

data/spec/reducer_spec.rb

@@ -0,0 +1,104 @@
+require 'spec_helper'
+require_relative 'fixtures'
+
+RSpec.describe Rack::Reducer do
+  using SpecRefinements
+
+  let(:app) do
+    lambda do |env|
+      req = Rack::Request.new(env)
+      res = Fixtures::ArtistReducer.apply(req.params).to_json
+      [200, { 'Content-Type' => 'application/json' }, [res]]
+    end
+  end
+
+  it 'responds with unfiltered data when filter params are empty' do
+    get('/') do |res|
+      expect(res.json.count).to eq(Fixtures::DB[:artists].count)
+    end
+  end
+
+  it 'filters by a single param, e.g. name' do
+    get('/artists?name=Blake') do |response|
+      expect(response.body).to include('Blake Mills')
+      expect(response.body).to include('James Blake')
+      expect(response.body).not_to include('SZA')
+    end
+  end
+
+  it 'resets state between requests' do
+    get('/artists?name=Blake')
+    get('/artists') do |res|
+      expect(res.json.count).to eq(Fixtures::DB[:artists].count)
+    end
+  end
+
+  it 'filters by a single param, e.g. genre' do
+    get('/artists?genre=electronic') do |response|
+      expect(response.body).to include('Björk')
+      expect(response.body).to include('James Blake')
+      expect(response.body).not_to include('Blake Mills')
+    end
+
+    get '/artists?genre=soul' do |response|
+      expect(response.body).to include('Janelle Monae')
+      expect(response.body).not_to include('Björk')
+    end
+  end
+
+  it 'chains multiple filters' do
+    get('/artists?genre=electronic&name=blake') do |response|
+      expect(response.body).to include('James Blake')
+      expect(response.body).not_to include('Blake Mills')
+    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 'accepts nil as params' do
+    expect(Fixtures::ArtistReducer.apply(nil)).to be_truthy
+  end
+
+  it 'can sort' do
+    get '/artists?order=genre' do |response|
+      genre = response.json[0]['genre']
+      expect(genre).to eq('alternative')
+    end
+  end
+
+  describe 'ad-hoc style via ::call' do
+    let(:params) { { 'genre' => 'electronic', 'name' => 'blake' } }
+    it 'works just like the primary style, but slower' do
+      result = Rack::Reducer.call(
+        params,
+        dataset: Fixtures::DB[:artists],
+        filters: Fixtures::FILTERS,
+      )
+      expect(result.count).to eq(1)
+      expect(result[0][:name]).to eq('James Blake')
+    end
+  end
+
+  describe 'mixin-style' do
+    before { @warnings = [] }
+
+    let(:model) do
+      dataset = Fixtures::DB[:artists].dup
+      allow(dataset).to(receive(:warn)) { |msg| @warnings << msg }
+      dataset.extend Rack::Reducer
+      dataset.reduces dataset, filters: Fixtures::FILTERS
+      dataset
+    end
+
+    it 'is still supported, but with a deprecation warning' do
+      params = { 'genre' => 'electronic', 'name' => 'blake' }
+      expect(model.reduce(params).count).to eq(1)
+      expect(@warnings.first).to include('mixin-style is deprecated')
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -1,26 +1,17 @@
 require 'bundler/setup'
 Bundler.setup
-require 'rspec'
 require 'pry'
 require 'rack/test'
 require 'rack/reducer'
-require 'sequel'
-require_relative 'behavior'
-ENV['RACK_ENV'] = ENV['RAILS_ENV'] = 'test'
-DB = Sequel.connect "sqlite://#{__dir__}/fixtures.sqlite"
-
-SEQUEL_QUERY = {
-  dataset: DB[:artists],
-  filters: [
-    ->(genre:) { grep(:genre, "%#{genre}%", case_insensitive: true) },
-    ->(name:) { grep(:name, "%#{name}%", case_insensitive: true) },
-    ->(order: 'genre') { order(order.to_sym) },
-    ->(releases: ) { where(release_count: releases.to_i) },
-  ]
-}.freeze
 
 RSpec.configure do |config|
   config.color = true
   config.order = :random
   config.include Rack::Test::Methods
 end
+
+module SpecRefinements
+  refine Rack::MockResponse do
+    define_method(:json) { JSON.parse(body) }
+  end
+end