rubanok 0.1.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b5cdbefb98c951e26be6bfcd8029250f8b314c9b7bb86e5d5d778bc340b4d40
-  data.tar.gz: abd725823622bdf1ff062cc1496dfd121522e6b866ec01ce2bc9ea421a56785e
+  metadata.gz: 90f6ca9dfd61a6f143eff1f3ab3c2d7e41502c992879af785dcf414af15249fd
+  data.tar.gz: 8807cbb2a680e9fbc739a9f0214fb4753e24ee55e69da72d9b45c7f121900dd9
 SHA512:
-  metadata.gz: aeec1ebbf07db8ec31046cf1442ffac9e6cae698e979768e8560d189f7ab23bfc13d9ef2979dbd45fd00490a5101e3f3b3900d4ff2425b2112880915e8446ba6
-  data.tar.gz: e66af487b2f7b82626d790bc0746559102de30ec0220e5d12de1ce0f29c79c98ed0bad6744ab90df5c5a931b421d90d1b4b4d082e70d15f714efb49fb56b2418
+  metadata.gz: 2e015d7c3c517e42e5fe42037035db950cc87f9bd0099b38580c03ad156c36d0133681bd659451e8bdb58f15254799ce8d7b3158a1dc998210e3a425867a521d
+  data.tar.gz: 6c22e9a876e86f144726e8dbbe79b42f9d3052feb6f9c31688f7259872a5eed1e5ac66b031b890e0d1b4eceba7d3903331a073f2e13321b9f3d45c9fe53229d2

data/CHANGELOG.md

@@ -2,6 +2,64 @@
 
 ## master
 
+## 0.4.0 (2021-03-05)
+
+- Ruby 3.0 compatibility. ([@palkan][])
+
+- Add RBS. ([@palkan][])
+
+## 0.3.0 (2020-10-21)
+
+- Add `filter_with: Symbol | Proc` option to `.map` to allowing filtering the input value. ([@palkan][])
+
+- Allow specifying `ignore_empty_values: *` per rule. ([@palkan][])
+
+- Add `prepare` DSL method to transform the input once before the first rule is activated. ([@palkan][])
+
+When no rules match, the method is not called.
+Useful when you want to perform some default transformations.
+
+## 0.2.1 (2019-08-24)
+
+- Fix bug with trying to add a helper for API controller. ([@palkan][])
+
+Fixes [#10](https://github.com/palkan/rubanok/issues/10).
+
+## 0.2.0 (2019-08-23)
+
+- Add `Process.project` and `rubanok_scope` methods to get the Hash of recognized params. ([@palkan][])
+
+```ruby
+class PostsProcessor < Rubanok::Processor
+  map(:q) { block }
+  match(:page, :per_page, activate_on: :page) { block }
+end
+
+PostsProcessor.project(q: "search_me", filter: "smth", page: 2)
+# => { q: "search_me", page: 2 }
+
+class PostsController < ApplicationController
+  def index
+    @filter_params = rubanok_scope
+    # or
+    @filter_params = rubanok_scope params.require(:filter), with: PostsProcessor
+    # ...
+  end
+end
+```
+
+- Improve naming by using "processor" instead of "plane". ([@palkan][])
+
+See [the discussion](https://github.com/palkan/rubanok/issues/3).
+
+**NOTE**: Older API is still available without deprecation.
+
+- Add `fail_when_no_matches` parameter to `match` method. ([@Earendil95][])
+
+## 0.1.3 (2019-03-05)
+
+- Fix using `activate_always: true` with `default` matching clause. ([@palkan][])
+
 ## 0.1.1 (2019-01-16)
 
 - Fix RSpec matcher to call original implementation instead of returning `nil`. ([@palkan][])
@@ -15,3 +73,4 @@ Initial implementation.
 Proposal added.
 
 [@palkan]: https://github.com/palkan
+[@Earendil95]: https://github.com/Earendil95

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2018 Vladimir Dementyev
+Copyright (c) 2018-2020 Vladimir Dementyev
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,9 +1,12 @@
-[![Gem Version](https://badge.fury.io/rb/rubanok.svg)](https://rubygems.org/gems/rubanok) [![Build Status](https://travis-ci.org/palkan/rubanok.svg?branch=master)](https://travis-ci.org/palkan/rubanok)
+[![Gem Version](https://badge.fury.io/rb/rubanok.svg)](https://rubygems.org/gems/rubanok)
+![Build](https://github.com/palkan/rubanok/workflows/Build/badge.svg)
 
 # Rubanok
 
 Rubanok provides a DSL to build parameters-based data transformers.
 
+📖 Read the introduction post: ["Carve your controllers like Papa Carlo"](https://evilmartians.com/chronicles/rubanok-carve-your-rails-controllers-like-papa-carlo)
+
 The typical usage is to describe all the possible collection manipulation for REST `index` action, e.g. filtering, sorting, searching, pagination, etc..
 
 So, instead of:
@@ -11,12 +14,12 @@ So, instead of:
 ```ruby
 class CourseSessionController < ApplicationController
   def index
-    @sessions = CourseSession.
-                  search(params[:q]).
-                  by_course_type(params[:course_type_id]).
-                  by_role(params[:role_id]).
-                  paginate(page_params).
-                  order(ordering_params)
+    @sessions = CourseSession
+      .search(params[:q])
+      .by_course_type(params[:course_type_id])
+      .by_role(params[:role_id])
+      .paginate(page_params)
+      .order(ordering_params)
   end
 end
 ```
@@ -26,13 +29,13 @@ You have:
 ```ruby
 class CourseSessionController < ApplicationController
   def index
-    @sessions = planish(
+    @sessions = rubanok_process(
       # pass input
       CourseSession.all,
       # pass params
       params,
-      # provide a plane to use
-      with: CourseSessionsPlane
+      # provide a processor to use
+      with: CourseSessionsProcessor
     )
   end
 end
@@ -40,34 +43,42 @@ end
 
 Or we can try to infer all the configuration for you:
 
-
 ```ruby
 class CourseSessionController < ApplicationController
   def index
-    @sessions = planish(CourseSession.all)
+    @sessions = rubanok_process(CourseSession.all)
   end
 end
 ```
 
 Requirements:
+
 - Ruby ~> 2.5
-- Rails >= 4.2 (only for using with Rails)
+- (optional\*) Rails >= 5.2 (Rails 4.2 should work but we don't test against it anymore)
+
+\* This gem has no dependency on Rails.
 
 <a href="https://evilmartians.com/">
 <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54"></a>
 
 ## Installation
 
-**This gem hasn't been released (and even built) yet.**
+Add to your `Gemfile`:
+
+```ruby
+gem "rubanok"
+```
+
+And run `bundle install`.
 
 ## Usage
 
-The core concept of this library is a _plane_ (or _hand plane_, or "рубанок" in Russian). Plane is responsible for mapping parameters to transformrations.
+The core concept of this library is a processor (previously called _plane_ or _hand plane_, or "рубанок" in Russian). Processor is responsible for mapping parameters to transformations.
 
 From the example above:
 
 ```ruby
-class CourseSessionsPlane < Rubanok::Plane
+class CourseSessionsProcessor < Rubanok::Processor
   # You can map keys
   map :q do |q:|
     # `raw` is an accessor for input data
@@ -76,7 +87,7 @@ class CourseSessionsPlane < Rubanok::Plane
 end
 
 # The following code
-CourseSessionsPlane.call(CourseSession.all, q: "xyz")
+CourseSessionsProcessor.call(CourseSession.all, q: "xyz")
 
 # is equal to
 CourseSession.all.search("xyz")
@@ -85,7 +96,7 @@ CourseSession.all.search("xyz")
 You can map multiple keys at once:
 
 ```ruby
-class CourseSessionsPlane < Rubanok::Plane
+class CourseSessionsProcessor < Rubanok::Processor
   DEFAULT_PAGE_SIZE = 25
 
   map :page, :per_page do |page:, per_page: DEFAULT_PAGE_SIZE|
@@ -97,9 +108,9 @@ end
 There is also `match` method to handle values:
 
 ```ruby
-class CourseSessionsPlane < Rubanok::Plane
-  SORT_ORDERS = %w(asc desc).freeze
-  SORTABLE_FIELDS = %w(id name created_at).freeze
+class CourseSessionsProcessor < Rubanok::Processor
+  SORT_ORDERS = %w[asc desc].freeze
+  SORTABLE_FIELDS = %w[id name created_at].freeze
 
   match :sort_by, :sort do
     having "course_id", "desc" do
@@ -124,16 +135,94 @@ class CourseSessionsPlane < Rubanok::Plane
       raw.order(sort_by => sort)
     end
   end
+
+  # strict matching; if Processor will not match parameter, it will raise Rubanok::UnexpectedInputError
+  # You can handle it in controller, for example, with sending 422 Unprocessable Entity to client
+  match :filter, fail_when_no_matches: true do
+    having "active" do
+      raw.active
+    end
+
+    having "finished" do
+      raw.finished
+    end
+  end
+end
+```
+
+By default, Rubanok will not fail if no matches found in `match` rule. You can change it by setting: `Rubanok.fail_when_no_matches = true`.
+If in example above you will call `CourseSessionsProcessor.call(CourseSession, filter: 'acitve')`, you will get `Rubanok::UnexpectedInputError: Unexpected input: {:filter=>'acitve'}`.
+
+**NOTE:** Rubanok only matches exact values; more complex matching could be added in the future.
+
+### Default transformation
+
+Sometimes it's useful to perform some transformations before **any** rule is activated.
+
+There is a special `prepare` method which allows you to define the default transformation:
+
+```ruby
+class CourseSearchQueryProcessor < Rubanok::Processor
+  prepare do
+    next if raw&.dig(:query, :bool)
+
+    {query: {bool: {filters: []}}}
+  end
+
+  map :ids do |ids:|
+    raw.dig(:query, :bool, :filters) << {terms: {id: ids}}
+    raw
+  end
 end
 ```
 
-**NOTE:** matching only match the exact values; more complex matching could be added in the future.
+The block should return a new initial value for the _raw_ input or `nil` (no transformation required).
+
+The `prepare` callback is not executed if no params match, e.g.:
+
+```ruby
+CourseSearchQueryProcessor.call(nil, {}) #=> nil
+
+# But
+CourseSearchQueryProcessor.call(nil, {ids: [1]}) #=> {query {bool: {filters: [{terms: {ids: [1]}}]}}}
+
+# Note that we can omit the first argument altogether
+CourseSearchQueryProcessor.call({ids: [1]})
+```
+
+### Getting the matching params
+
+Sometimes it could be useful to get the params that were used to process the data by Rubanok processor (e.g., you can use this data in views to display the actual filters state).
+
+In Rails, you can use the `#rubanok_scope` method for that:
+
+```ruby
+class CourseSessionController < ApplicationController
+  def index
+    @sessions = rubanok_process(CourseSession.all)
+    # Returns the Hash of params recognized by the CourseSessionProcessor.
+    # For example:
+    #
+    #    params == {q: "search", role_id: 2, date: "2019-08-22"}
+    #    @session_filter == {q: "search", role_id: 2}
+    @sessions_filter = rubanok_scope(
+      params.permit(:q, :role_id),
+      with: CourseSessionProcessor
+    )
+
+    # You can omit all the arguments
+    @sessions_filter = rubanok_scope #=> equals to rubanok_scope(params, with: implicit_rubanok_class)
+  end
+end
+```
+
+You can also accesss `rubanok_scope` in views (it's a helper method).
 
 ### Rule activation
 
 Rubanok _activates_ a rule by checking whether the corresponding keys are present in the params object. All the fields must be present to apply the rule.
 
-Sometimes you might want to make some fields optional (or event all of them). You can use `activate_on` and `activate_always` options for that:
+Some fields may be optional, or perhaps even all of them. You can use `activate_on` and `activate_always` options to mark something as an optional key instead of a required one:
 
 ```ruby
 # Always apply the rule; use default values for keyword args
@@ -147,18 +236,52 @@ match :sort_by, :sort, activate_on: :sort_by do
 end
 ```
 
-By default, Rubanok ignores empty param values (using `#empty?` under the hood) and do not activate the matching rules (i.e. `{ q: "" }` or `{ q: nil }` won't activate the `map :q` rule).
+By default, Rubanok ignores empty param values (using `#empty?` under the hood) and will not run matching rules on those values. For example: `{ q: "" }` and `{ q: nil }` won't activate the `map :q` rule.
+
+You can change this behaviour by specifying `ignore_empty_values: true` option for a particular rule or enabling this behaviour globally via `Rubanok.ignore_empty_values = true` (enabled by default).
+
+### Input values filtering
 
-You can change this behaviour by setting: `Rubanok.ignore_empty_values = false`.
+For complex input types, such as arrays, it might be useful to _prepare_ the value before passing to a transforming block or prevent the activation altogether.
+
+We provide a `filter_with:` option for the `.map` method, which could be used as follows:
+
+```ruby
+class PostsProcessor < Rubanok::Processor
+  # We can pass a Proc
+  map :ids, filter_with: ->(vals) { vals.reject(&:blank?).presence } do |ids:|
+    raw.where(id: ids)
+  end
+
+  # or define a class method
+  def self.non_empty_array(val)
+    non_blank = val.reject(&:blank?)
+    return if non_blank.empty?
+
+    non_blank
+  end
+
+  # and pass its name as a filter_with value
+  map :ids, filter_with: :non_empty_array do |ids:|
+    raw.where(id: ids)
+  end
+end
+
+# Filtered values are used in rules
+PostsProcessor.call(Post.all, {ids: ["1", ""]}) == Post.where(id: ["1"])
+
+# When filter returns empty value, the rule is not applied
+PostsProcessor.call(Post.all, {ids: [nil, ""]}) == Post.all
+```
 
 ### Testing
 
-One of the benefits of having all the modification logic in its own class is the ability to test it in isolation:
+One of the benefits of having modification logic contained in its own class is the ability to test modifications in isolation:
 
 ```ruby
 # For example, with RSpec
-describe CourseSessionsPlane do
-  let(:input ) { CourseSession.all }
+RSpec.describe CourseSessionsProcessor do
+  let(:input) { CourseSession.all }
   let(:params) { {} }
 
   subject { described_class.call(input, params) }
@@ -174,19 +297,19 @@ end
 Now in your controller you only have to test that the specific _plane_ is applied:
 
 ```ruby
-describe CourseSessionController do
+RSpec.describe CourseSessionController do
   subject { get :index }
 
   specify do
-    expect { subject }.to have_planished(CourseSession.all).
-      with(CourseSessionsPlane)
+    expect { subject }.to have_rubanok_processed(CourseSession.all)
+      .with(CourseSessionsProcessor)
   end
 end
 ```
 
 **NOTE**: input matching only checks for the class equality.
 
-To use `have_planished` matcher you must add the following line to your `spec_helper.rb` / `rails_helper.rb` (it's added automatically if RSpec defined and `RAILS_ENV`/`RACK_ENV` is equal to `"test"`):
+To use `have_rubanok_processed` matcher you must add the following line to your `spec_helper.rb` / `rails_helper.rb` (it's added automatically if RSpec defined and `RAILS_ENV`/`RACK_ENV` is equal to `"test"`):
 
 ```ruby
 require "rubanok/rspec"
@@ -194,10 +317,85 @@ require "rubanok/rspec"
 
 ### Rails vs. non-Rails
 
-Rubanok is a Rails-free library but has some useful Rails extensions, such as `planish` helper for controllers (included automatically into `ActionController::Base` and `ActionController::API`).
+Rubanok does not require Rails, but it has some useful Rails extensions such as `rubanok_process` helper for controllers (included automatically into `ActionController::Base` and `ActionController::API`).
 
 If you use `ActionController::Metal` you must include the `Rubanok::Controller` module yourself.
 
+### Processor class inference in Rails controllers
+
+By default, `rubanok_process` uses the following algorithm to define a processor class: `"#{controller_path.classify.pluralize}Processor".safe_constantize`.
+
+You can change this by overriding the `#implicit_rubanok_class` method:
+
+```ruby
+class ApplicationController < ActionController::Smth
+  # override the `implicit_rubanok_class` method
+  def implicit_rubanok_class
+    "#{controller_path.classify.pluralize}Scoper".safe_constantize
+  end
+end
+```
+
+Now you can use it like this:
+
+```ruby
+class CourseSessionsController < ApplicationController
+  def index
+    @sessions = rubanok_process(CourseSession.all, params)
+    # which equals to
+    @sessions = CourseSessionsScoper.call(CourseSession.all, params.to_unsafe_h)
+  end
+end
+```
+
+**NOTE:** the `planish` method is still available and it uses `#{controller_path.classify.pluralize}Plane".safe_constantize` under the hood (via the `#implicit_plane_class` method).
+
+## Using with RBS/Steep
+
+_Read ["Climbing Steep hills, or adopting Ruby 3 types with RBS"](https://evilmartians.com/chronicles/climbing-steep-hills-or-adopting-ruby-types) for the context._
+
+Rubanok comes with Ruby type signatures (RBS).
+
+To use them with Steep, add `library "rubanok"` to your Steepfile.
+
+Since Rubanok provides DSL with implicit context switching (via `instance_eval`), you need to provide type hints for the type checker to help it
+figure out the current context. Here is an example:
+
+```ruby
+class MyProcessor < Rubanok::Processor
+  map :q do |q:|
+    # @type self : Rubanok::Processor
+    raw
+  end
+
+  match :sort_by, :sort, activate_on: :sort_by do
+    # @type self : Rubanok::DSL::Matching::Rule
+    having "status", "asc" do
+      # @type self : Rubanok::Processor
+      raw
+    end
+
+    # @type self : Rubanok::DSL::Matching::Rule
+    default do |sort_by:, sort: "asc"|
+      # @type self : Rubanok::Processor
+      raw
+    end
+  end
+end
+```
+
+Yeah, a lot of annotations 😞 Welcome to the type-safe world!
+
+## Questions & Answers
+
+- **Where to put my processor/plane classes?**
+
+I put mine under `app/planes` (as `<resources>_plane.rb`) in my Rails app.
+
+- **I don't like the naming ("planes" ✈️?), can I still use the library?**
+
+Good news—the default naming [has been changed](https://github.com/palkan/rubanok/pull/8). "Planes" are still available if you prefer them (just like me 😉).
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/palkan/rubanok.