Snfoil::Searcher

SnFoil Searchers allow you to break complex searching functionality into small easily testable sections.

Installation

Add this line to your application's Gemfile:

gem 'snfoil-searcher'

Usage

Quickstart

Here is a quick example of how you would use a SnFoil Searcher with Active Record.

# lib/searchers/people_searcher
class PeopleSearcher
  include SnFoil::Searcher

  model Person

  filter do |scope, params|
    scope.where('first_name ilike ?', params[:query])
  end
end

and call it like so

PeopleSearcher.new.search(query: 'alf')

Getting a Searcher Configured

Include

This one is pretty simple - to add the functionality to your searcher class, you need to include it.

Like so:

class PeopleSearcher
  include SnFoil::Searcher

  ...
end

Scoping

You can provide an initial scope to the searcher by passing it to new. If you don't pass in an initial scope, the searcher will try to use the model.

PeopleSearcher.new(People.where(team_id: 2))

Model

Model is an optional parameter you can set on the searcher class. If a model is defined - and there is no default scope provided when initializing the searcher - it will default to using model.all

class PeopleSearcher
  include SnFoil::Searcher

  model Person
end

Filter

A filter is a step in the search process that takes the current scope and parameters and returns an altered scope. We recommend keeping each filter as simple as possible - it should only have one responsibility. This way you can easily see every step the searcher takes to get to its outcome as well as defining behaviors that should be tested.

You can create as many filters as you would like, but it is important to remember that a filter should always return a scope.

class PeopleSearcher
  ...

  # query by first_name
  filter do |scope, params|
    scope.where('first_name ilike ?', params[:query])
  end

  # filter to age demographic
  filter do |scope, _params|
    scope.where('age >= 18').where('age <= 34')
  end
end

Conditional Filters

You probably don't want a filter to always run. You can set if and unless procs to check whether or not the filter should run.

class PeopleSearcher
  ...

  # query by first_name
  filter(if: ->(params) { params[:query].present? }) do |scope, params|
    scope.where('first_name ilike ?', params[:query])
  end
end

Setup

Setup is just a filter that runs first - before any other filters. It does not allow for conditionals. We recommend using this block to setup any requirements, tenant scoping, or stuff that just needs to happen first.

class PeopleSearcher
  ...

  setup do |scope, params|
    scope.where(client_id: 1)
  end

  filter do |scope, params|
    ...
  end
end

Casting Booleans

To help with casting boolean params - especially those coming from http params - we've added explicit boolean casting for params. There are parsed and cast in place before any filter. Just pass in an array of the params you would like to have cast.

PeopleSearcher.new.search(red: 'true', blue: 'true', green: nil)

class PeopleSearcher
  booleans :red, :green

  ...

  filter do |scope, params|
    # params => { red: true, blue: 'true', green: false }
    ...
  end
end

PORO

Although our examples so far have used Active Record, you can use SnFoil Searchers with any dataset you need to filter.

class FruitSearcher
  include SnFoil::Searcher

  # always filter out unavailable
  setup do |scope, _params|
    scope.select { |x| x[:available] }
  end

  filter(unless: ->(params) { params[:type].nil? || params[:type].empty? }) do |scope, params|
    scope.select { |x| x[:type] == params[:type] }
  end

  filter(unless: ->(params) { params[:color].nil? || params[:color].empty? }) do |scope, params|
    scope.select { |x| x[:color] == params[:color] }
  end
end

fruits = [
  { name: 'Apple', color: 'red', type: 'pome', available: true },
  { name: 'Rowan', color: 'red', type: 'pome', available: false },
  { name: 'Pear', color: 'green', type: 'pome', available: true },
  { name: 'Grape', color: 'red', type: 'berry', available: true  }
]

FruitSearcher.new(fruits).search( type:'pome')
  #=> [{ name: 'Apple', color: 'red', type: 'pome', available: true }, { name: 'Pear', color: 'green', type: 'pome', available: true }]

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/limited-effort/snfoil-searcher. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the code of conduct.

License

The gem is available as open source under the terms of the Apache 2 License.

Code of Conduct

Everyone interacting in the Snfoil::Policy project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the code of conduct.