README.md
# SteelWheel
[](https://codeclimate.com/github/andriy-baran/steel_wheel/maintainability)
[](https://codeclimate.com/github/andriy-baran/steel_wheel/test_coverage)
[](https://badge.fury.io/rb/steel_wheel)
The library is a tool for building highly structured service objects.
## Concepts
### Stages
We may consider any controller action as a sequence of following stages:
1. **Input validations and preparations**
* Describe the structure of parameters
* Validate values, provide defaults
2. **Querying data and preparing context**
* Records lookups by IDs in parameters
* Validate permissions to perform an action
* Validate conditions (business logic requirements)
* Inject Dependencies
* Set up current user
3. **Performing Action (skipped on GET requests)**
* Updade database state
* Enqueue jobs
* Handle exceptions
* Validate intermediate states
4. **Exposing Results/Errors**
* Presenters
* Contextual information useful for the users
### Implementation of stages
As you can see each step has specific tasks and can be implemented as a separate object.
**SteelWheel::Params (gem https://github.com/andriy-baran/easy_params)**
* provides DSL for `params` structure definition
* provides type coercion and default values for individual attributes
* has ActionModel::Validation included
* implements `http_status` method that returs HTTP error code
**SteelWheel::Query**
* has `Memery` module included
* has ActionModel::Validation included
* implements `http_status` method that returs HTTP error code
**SteelWheel::Command**
* has ActionModel::Validation included
* implements `http_status` method that returs HTTP error code
* implements `call` method that should do the stuff
**SteelWheel::Response**
* has ActionModel::Validation included
* implements `status` method that returs HTTP error code
* implements `success?` method that checks if there are any errors
### Process
Let's image the process that connects stages described above
* Get an input and initialize object for params, trigger callbacks
* Initialize object for preparing context and give it an access to previous object, trigger callbacks
* Initialize object for performing action and give it an access to previous object, trigger callbacks
* Initialize resulting object and give it an access to previous object,
* Run validations, collect errros, trigger callbacks
* If everything is ok run action and handle errors that appear during execution time.
* If we have an error on any stage we stop validating following objects.
### Callbacks
We have two types of callbacks explicit and implicit
### Implicit callbacks
We define them via handler instance methods
```ruby
def on_params_created(params)
# NOOP
end
def on_query_created(query)
# NOOP
end
def on_command_created(command)
# NOOP
end
def on_response_created(command)
# NOOP
end
# After validation callbacks
def on_failure(flow)
# NOOP
end
def on_success(flow)
# NOOP
end
```
### Explicit callbacks
We define them during instantiation of hanler by providing a block parameter
```ruby
handler = handler_class.new do |c|
c.params { |o| puts o }
c.query { |o| puts o }
c.command { |o| puts o }
c.response { |o| puts o }
end
result = handler.handle(input: { id: 1 })
```
In addition we can manipulate with objects directly via callback of `handle` mathod
```ruby
result = handler_class.handle(input: { id: 1 }) do |c|
c.params.id = 12
c.query.user = current_user
c.command.request_headers = request.headers
c.response.prepare_presenter
end
```
## Installation
Add this line to your application's Gemfile:
```ruby
gem 'steel_wheel'
```
And then execute:
$ bundle
Or install it yourself as:
$ gem install steel_wheel
## Usage
Add base handler
```bash
bin/rails g steel_wheel:application_handler
```
Add specific handler
```bash
bin/rails g steel_wheel:handler products/create
```
This will generate `app/handlers/products/create_handler.rb`. And we can customize it
```ruby
class Products::CreateHandler < ApplicationHandler
define do
params do
attribute :title, string
attribute :weight, string
attribute :price, string
validates :title, :weight, :price, presence: true
validates :weight, allow_blank: true, format: { with: /\A[0-9]+\s[g|kg]\z/ }
end
query do
validate :product, :variant
memoize def new_product
Product.new(title: title)
end
memoize def new_variant
new_product.build_variant(weight: weight, price: price)
end
private
def product
errors.add(:base, :unprocessable_entity, new_product.errors.full_messages.join("\n")) if new_product.invalid?
end
def variant
errors.add(:base, :unprocessable_entity, new_variant.errors.full_messages.join("\n")) if new_variant.invalid?
end
end
command do
def add_to_stock!
PointOfSale.find_each do |pos|
PosProductStock.create!(pos_id: pos.id, product_id: new_product.id, on_hand: 0.0)
end
end
def call(response)
::ApplicationRecord.transaction do
new_product.save!
new_variant.save!
add_to_stock!
rescue => e
response.errors.add(:unprocessable_entity, e.message)
raise ActiveRecord::Rollback
end
end
end
end
def on_success(flow)
flow.call
end
end
```
Looks too long. Lets move code into separate files.
```bash
bin/rails g steel_wheel:params products/create
```
Add relative code
```ruby
# Base class also can be refered via
# ApplicationHandler.main_builder.abstract_factory.params_factory.base_class
class Products::CreateHandler
class Params < SteelWheel::Params
attribute :title, string
attribute :weight, string
attribute :price, string
validates :title, :weight, :price, presence: true
validates :weight, allow_blank: true, format: { with: /\A[0-9]+\s[g|kg]\z/ }
end
end
```
Than do the same for query
```bash
bin/rails g steel_wheel:query products/create
```
Add code...
```ruby
# Base class also can be refered via
# ApplicationHandler.main_builder.abstract_factory.query_factory.base_class
class Products::CreateHandler
class Query < SteelWheel::Query
validate :product, :variant
memoize def new_product
Product.new(title: title)
end
memoize def new_variant
new_product.build_variant(weight: weight, price: price)
end
private
def product
errors.add(:unprocessable_entity, new_product.errors.full_messages.join("\n")) if new_product.invalid?
end
def variant
errors.add(:unprocessable_entity, new_variant.errors.full_messages.join("\n")) if new_variant.invalid?
end
end
end
```
And finally command
```bash
bin/rails g steel_wheel:command products/create
```
Move code
```ruby
class Products::CreateHandler
class Command < SteelWheel::Command
def add_to_stock!
::PointOfSale.find_each do |pos|
::PosProductStock.create!(pos_id: pos.id, product_id: new_product.id, on_hand: 0.0)
end
end
def call(response)
::ApplicationRecord.transaction do
new_product.save!
new_variant.save!
add_to_stock!
rescue => e
response.errors.add(:unprocessable_entity, e.message)
raise ActiveRecord::Rollback
end
end
end
end
```
Than we can update handler
```ruby
# app/handlers/manage/products/create_handler.rb
class Manage::Products::CreateHandler < ApplicationHandler
define do
params Params
query Query
command Command
end
def on_success(flow)
flow.call(flow)
end
end
```
### HTTP status codes and errors handling
It's important to provide a correct HTTP status when we faced some problem(s) during request handling. The library encourages developers to add the status codes when they add errors.
```ruby
errors.add(:unprocessable_entity, 'error')
```
As you know `full_messages` will produce `['Unprocessable Entity error']` to prevent this and get only error `SteelWheel::Response` has special method that makes some error keys to behave like `:base`
```ruby
# Default setup
generic_validation_keys(:not_found, :forbidden, :unprocessable_entity, :bad_request, :unauthorized)
# To override it in your app
class SomeHandler
define do
response do
generic_validation_keys(:not_found, :forbidden, :unprocessable_entity, :bad_request, :unauthorized, :payment_required)
end
end
end
```
In Rails 6.1 `ActiveModel::Error` was introdused and previous setup is not needed, second argument is used instead
```ruby
errors.add(:base, :unprocessable_entity, 'error')
```
## 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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
## Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/andriy-baran/steel_wheel. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
## License
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
## Code of Conduct
Everyone interacting in the SteelWheel project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/andriy-baran/steel_wheel/blob/master/CODE_OF_CONDUCT.md).