application_action 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40e24ce5fd068b724a6573c07d3154491898503fe9c1c4839269ddc0de3be3b5
-  data.tar.gz: e4b19aa8a56a71fe567ca1b3a95d549c89c8de3ef8349bc383bb41a56820bcc9
+  metadata.gz: 27b97dc76c7dc83d6bc045272e8c609f084802792b5216cd6973c91193cd5f0e
+  data.tar.gz: d33acad78be39e11c1356a1864631327dbf8ce1b60afa45cadaca4f21ad1183c
 SHA512:
-  metadata.gz: 89b664cc4431ba1086548f131bb9446724fac74f3da63607c88b0e3690451c1a6a269b95a6af13cd9e56763cc95d6cd57c1a82931b68dbc66bf2057ccfe37c0b
-  data.tar.gz: d1fad00bfe14f8cf62ef0e9a02792bc91c56cfbccb6399fe3daa55043187366f836836052235a7bc2e0e7c79120115f7839c3ae9333ea4b6cf2ecdab4b5b4456
+  metadata.gz: 453de2f239c07d257e3aa0d6c7fa79b1f13149babd3219663f5d6bfb637bc85810fa744803a213d4352dac7fb23547bfb44555ea643931775488870ddfd79968
+  data.tar.gz: a00c1f08163af8c36f7fb34fae4b974ebbbf0c72906af47dd5803c77544dd16204a4685806b17a42930389a8eeedf0077d645beda3e7c52ccc198ac41a874d5d

data/README.md

@@ -1,28 +1,244 @@
 # ApplicationAction
-Short description and motivation.
 
-## Usage
-How to use my plugin.
+Tiny on code, heavy on concept. ApplicationAction is an opiniated concept extend of the Ruby on Rails framework.
+
+ApplicationAction is an useful `Action` pattern I found myself following for many years among many Rails projects so I hope its usefull for you too. It mimics `ApplicationRecord`'s interface to the `Action`s your applications execute. Its easy to extent, test, compose and reuse.
+
+This is the code. All of it:
+
+```ruby
+class ApplicationAction
+  include ActiveModel::Model
+
+  def save
+    return false unless valid?
+
+    ApplicationRecord.transaction { run }
+
+    return true
+  end
+
+  def save!
+    raise errors.full_messages.join(', ') unless save
+  end
+
+  def run
+    raise 'You should write your own #run method'
+  end
+end
+```
 
 ## Installation
-Add this line to your application's Gemfile:
+
+Add this line to your Gemfile:
 
 ```ruby
 gem 'application_action'
 ```
 
 And then execute:
+
 ```bash
 $ bundle
 ```
 
-Or install it yourself as:
-```bash
-$ gem install application_action
+## Usage
+
+`app/actions/some_action.rb`
+
+```ruby
+class SomeAction < ApplicationAction
+  attr_accessor :foo, :bar
+
+  # write what you need to validate before run the action
+  validates :foo, :bar, presence: true
+  validate :foo_is_complete, :bar_is_available
+
+  def run
+    # what the action should do when its valid
+  end
+
+  private
+
+  # the validations
+  def foo_is_complete
+    errors.add(:foo, :not_complete) unless foo.complete?
+  end
+
+  def bar_is_available
+    errors.add(:foo, :not_available) unless bar.available?
+  end
+end
+```
+
+Then, whenever suits you, call the action like this:
+
+```ruby
+action = SomeAction.new(foo: foo, bar: bar)
+action.valid?
+action.save
+action.save! # raises the validations errors as RuntimeErrors
 ```
 
+Having being through all the "fat models, skinny controllers" eras, I find an `Action` usefull when I have something my application need to do but no model or controller seem like the right place. It's usually some logic involving multiple models and a different set of validations. Its specially usefull when the same `Action` needs to be called from different entries (e.g. API, WEB Interface, background job, etc).
+
+**`#run` method is atomic** so feel free to change multiple database tables using different models `.create!` or `.update!` that it will all get rolled back if some exception happens. Be sure you create all the validations you need to ensure your `Action` will run with no exception. Its easy to handle validations errors and display messages this way.
+
+## Philosophy
+
+Think of `Action`s as one small state transition of your application. It's the representation of what your application does. So everytime an `Action` run, something changes and there are consequences. Each `Action` have a well-defined and validated scenario before running.
+
+#### The business logic should not live in the models
+
+You heard the story before: `ActiveRecord` already does too much. The database interface, query, validations and relationships are more than enough.
+
+Models should represent an entity stored at the database, a small piece of your entire application state. A single model or record should not handle complex operations, specially involving multiple models.
+
+Models validations should only check what is expected for every record, everytime. Some validations will only be applied in certain moments so these validations lives in an `Action`. [ActiveRecord's validations scope](https://guides.rubyonrails.org/active_record_validations.html#on) can handle simple scenarios but `Action`s validations is a better suit for complex logics.
+
+#### The business logic should not live in controllers
+
+Same here. Controller already handle request params and formats, response codes and authorization. But most important, you should be able to test your business logic without the need of an HTTP request.
+
+#### Actions are important changes
+
+`Action`s should have strict validations to make sure everything is ok before running. `Action`s are atomic, so you must have it completely done, or not done at all. This will help with your database (and the whole app) consistency.
+
+They should be well tested and you should be able to test every scenario without an integration test. You can unit test every `Action` validation and every change it makes when it runs.
+
+### A Practical Example
+
+#### Uber-like Logic
+
+Consider an Uber-like app, where passengers request for trips and the nearest available driver is found. The driver can refuse the request, so the next driver should be requested. Driver also have a 1 minute timeout to respond the request, otherwise it expires and the next driver is called. You can have some _DRY_ `Action`s like these:
+
+1. Request Trip Action:
+
+```ruby
+class RequestTrip < ApplicationAction
+  attr_accessor :passenger, :pickup_address, :destination_address
+
+  validate :passenger_is_not_blocked
+  validate :passenger_is_not_in_debt
+
+  def run
+    Trip.create!(
+      passenger: passenger,
+      pickup_address: pickup_address,
+      destination_address: destination_address,
+      requested_at: Time.current,
+      driver: nil,
+      accepted: false
+    )
+
+    FindTripDriver.new(trip: trip).save!
+  end
+
+  private
+
+  def passenger_is_not_blocked
+    #...
+  end
+
+  def passenger_is_not_in_debt
+    #...
+  end
+end
+```
+
+2. Find a Trip Driver
+
+```ruby
+class FindTripDriver < ApplicationAction
+  attr_accessor :trip
+
+  validate :trip_is_still_a_request
+  validates :nearest_driver, :trip, presence: true
+
+  def nearest_driver
+    Driver.available.where(...).first
+  end
+
+  def run
+    trip.update!(driver: nearest_driver)
+    driver.update!(current_trip: trip)
+    invite = TripInvitation.create!(trip: trip, driver: driver)
+
+    Notifications::InviteDriverToTrip.new(invite: invite).send!
+
+    # rejects automatically after 1 minute
+    DriverRejectTripJob.set(wait: 1.minute).perform_later(invite: invite)
+  end
+
+  private
+
+  def trip_is_still_a_request
+    errors.add(:trip, :already_accepted) if trip.accepted?
+  end
+end
+```
+
+3. Driver Rejects the request
+
+```ruby
+class DriverRejectTrip < ApplicationAction
+  attr_accessor :invite
+
+  validates :trip_is_not_already_accepted
+
+  delegate :trip, :driver, to: :invite
+
+  def run
+    invite.update!(accepted: false)
+    trip.update!(driver: nil)
+    driver.update!(current_trip: nil)
+
+    FindTripDriver.new(trip: trip).save! # easy to reuse the action
+  end
+
+  private
+
+  def trip_is_not_already_accepted
+    #...
+  end
+end
+```
+
+- Note how simple it is to test these actions.
+- You can call them at diferent Controllers, from `ActiveJob`s or **GraphQL Mutations**
+- Your life at the `rails console` will be a lot easer having a way to call these business logic directly. No need of api calls or web interface.
+
+### Translating error messages
+
+As the `Action`s includes `ActiveModel::Model` you can have each action's error message get translated by following this structure:
+
+```yml
+en:
+  activemodel:
+    attributes:
+      find_tripd_river: # <- The action name snake-cased
+        driver: Driver
+        trip: Trip
+    errors:
+      models:
+        find_tripd_river: # <- The action name snake-cased
+          attributes:
+            trip:
+              already_accepted: "was already accepted." # <- each error message  translation
+```
+
+## Inspiration
+
+The experience of building multiple web applications with Rails, including different environments like 100% web interface apps or API only (both REST & GraphQL) apps, a single product with a legacy monorepo maintained by a big team or multiple quickly built on demand projects, made it clear this commom gap of Rails on where to place some more complex business logic. I covered this gap in many different ways in the past. From **Fat Models** to **Fat Controllers**, sometimes as `PORO`s under the `lib` folder and sometimes with different names (as `Services` or `Runners`).
+
+It was after i built some React SPA's and got familiar with the [Flux](https://facebook.github.io/flux/) architecture to handle front-end's application state and later getting used to the [Redux](https://redux.js.org) implementation library that i shamelessly copied the name **Action** as I found it's was a nice fit for the case of a Rails application as well.
+
+I could translate the [Redux's Core Concepts](https://redux.js.org/introduction/core-concepts) and [Principles](https://redux.js.org/introduction/three-principles) to a Rails. I can see the database as the entire application state, the single source of truth and one should avoid change the application's state without an `Action` (specially for big changes). Every `Action` have an explicit changelist on the state so its easy to track how the state was before running and how the state became after.
+
 ## Contributing
-Contribution directions go here.
+
+`bin/rspec spec` to run te spec suit and all PRs are welcome.
 
 ## License
+
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/application_action.rb

@@ -6,6 +6,8 @@ class ApplicationAction
 
     ApplicationRecord.transaction { run }
 
+    after_run
+
     return true
   end
 
@@ -16,4 +18,6 @@ class ApplicationAction
   def run
     raise 'You should write your own #run method'
   end
+
+  def after_run; end
 end

data/lib/application_action/version.rb

@@ -1,3 +1,3 @@
 class ApplicationAction
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: application_action
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Rudiney Altair Franceschi
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-01-11 00:00:00.000000000 Z
+date: 2021-06-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -106,7 +106,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.1.4
 signing_key: 
 specification_version: 4
 summary: Adds the 'Actions' concept to your Rails APP