functional_interactor 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 42e88c718a1683448f282cae14099b67a7816885
+  data.tar.gz: c2a9c1a1be617e58001d1d3caba40d45225a27c1
+SHA512:
+  metadata.gz: 3287a14707157e7bfe623f4ecc2771b96f64f4ec4288cc2296661b4c268e69b040660af4218c1b10fe42273898282b5a65937360d0faf2674c965f512b759a59
+  data.tar.gz: d2ab9f05f340a6a0eb8dfab94f8871c83f43cea8db09e1e6fcf89b89e1530ccd0cd4a5df136dba325c2ea84e41d6ac50ed35b01fcb37b5ee9f549aa16492b9d9

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--order random
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,22 @@
+before_install:
+  - gem update bundler rake
+branches:
+  only:
+    - master
+    - v3
+env:
+  global:
+    - secure: | # CODECLIMATE_REPO_TOKEN
+        BIemhM273wHZMpuULDMYGPsxYdfw+NMw7IQbOD6gy5r+dha07y9ssTYYE5Gn
+        t1ptAb09lhQ4gexXTr83i6angMrnHgQ1ZX2wfeoZ0FvWDHQht9YkXyiNH+R6
+        odHUeDIYAlUiqLX9nAkklL89Rc22BrHMGGNyuA8Uc5sktW5P/FE=
+language: ruby
+matrix:
+  allow_failures:
+    - rvm: ruby-head
+rvm:
+  - 1.9.3
+  - "2.0"
+  - "2.1"
+  - ruby-head
+script: bundle exec rspec

data/CHANGELOG.md

@@ -0,0 +1,42 @@
+## 3.1.0 / 2014-10-13
+
+* [FEATURE] Add around hooks
+
+## 3.0.1 / 2014-09-09
+
+* [ENHANCEMENT] Add TomDoc code documentation
+
+## 3.0.0 / 2014-09-07
+
+* [FEATURE] Remove "magical" access to the context through the interactor
+* [FEATURE] Manage context values via setters/getters rather than hash access
+* [FEATURE] Change the primary interactor API method from "perform" to "call"
+* [FEATURE] Return the mutated context rather than the interactor instance
+* [FEATURE] Replace interactor setup with before and after hooks
+* [FEATURE] Abort execution immediately upon interactor failure
+* [ENHANCEMENT] Build a suite of realistic integration tests
+* [ENHANCEMENT] Move rollback responsibility into the context
+
+## 2.1.1 / 2014-09-30
+
+* [FEATURE] Halt performance if the interactor fails prior
+* [ENHANCEMENT] Add support for Ruby 2.1
+
+## 2.1.0 / 2013-09-05
+
+* [FEATURE] Roll back when an interactor within an organizer raises an error
+* [BUGFIX] Ensure that context-deferred methods respect string keys
+* [FEATURE] Respect context initialization from an indifferent access hash
+
+## 2.0.1 / 2013-08-28
+
+* [BUGFIX] Allow YAML (de)serialization by fixing interactor allocation
+
+## 2.0.0 / 2013-08-19
+
+* [BUGFIX] Fix rollback behavior within nested organizers
+* [BUGFIX] Skip rollback for the failed interactor
+
+## 1.0.0 / 2013-08-17
+
+* Initial release!

data/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing to Interactor
+
+Interactor is open source and contributions from the community are encouraged!
+No contribution is too small.
+
+Please consider:
+
+* adding a feature
+* squashing a bug
+* writing [documentation](http://tomdoc.org)
+* reporting an issue
+* fixing a typo
+* correcting [style](https://github.com/styleguide/ruby)
+
+## How do I contribute?
+
+For the best chance of having your changes merged, please:
+
+1. [Fork](https://github.com/collectiveidea/interactor/fork) the project.
+2. [Write](http://en.wikipedia.org/wiki/Test-driven_development) a failing test.
+3. [Commit](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html) changes that fix the tests.
+4. [Submit](https://github.com/collectiveidea/interactor/pulls) a pull request with *at least* one animated GIF.
+5. Be patient.
+
+If your proposed changes only affect documentation, include the following on a
+new line in each of your commit messages:
+
+```
+[ci skip]
+```
+
+This will signal [Travis](https://travis-ci.org) that running the test suite is
+not necessary for these changes.
+
+## Bug Reports
+
+If you are experiencing unexpected behavior and, after having read Interactor's
+documentation, are convinced this behavior is a bug, please:
+
+1. [Search](https://github.com/collectiveidea/interactor/issues) existing issues.
+2. Collect enough information to reproduce the issue:
+  * Interactor version
+  * Ruby version
+  * Rails version (if applicable)
+  * Specific setup conditions
+  * Description of expected behavior
+  * Description of actual behavior
+3. [Submit](https://github.com/collectiveidea/interactor/issues/new) an issue.
+4. Be patient.

data/Gemfile

@@ -0,0 +1,8 @@
+source "https://rubygems.org"
+
+gemspec
+
+group :test do
+  gem "codeclimate-test-reporter", require: false
+  gem "rspec", "~> 3.1"
+end

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Collective Idea
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,332 @@
+# Functional Interactor
+
+Based around https://github.com/collectiveidea/interactor, reimagined to use Kase with composability operators.
+
+## Getting Started
+
+Add Interactor to your Gemfile and `bundle install`.
+
+```ruby
+gem "functional_interactor", "~> 0.0.1"
+```
+
+This implementation is meant to be used with the [Kase](https://github.com/lasseebert/kase) gem. This
+is also an experiment -- some of the ideas such as generic interactors are somethign we (Legal.io engineering)
+is trying due to the sheer complexity of our code base. The examples we have in the advanced usage section
+can use a lot of improvement.
+
+## What is an Interactor?
+
+An interactor is a simple, single-purpose object.
+
+Interactors are used to encapsulate your application's
+[business logic](http://en.wikipedia.org/wiki/Business_logic). Each interactor
+represents one thing that your application *does*.
+
+### Call and Return Protocol
+
+An Interactor must respond to the method `call`, and takes a single object.
+
+An Interactor following this protocol will accept a single object which encapsulates
+the state or context. By convention, we use a Hash-like object so that interactors
+can be composed into higher-order interactions.
+
+#### Success
+
+When the action succeeds, return
+```ruby
+[:ok, context]
+```
+
+The return value of `context` can be anything, though it is suggested that you
+stick with a Hash-like object so that interactors can be chained together.
+
+#### Failure
+
+When the action fails, return an array where the first element is the symbol
+`:error`. Examples:
+
+```ruby
+[:error, "This failed"]
+[:error, :invalid, [{'field' => 'must be present'}]]
+[:error, :stripe_error, StripeException.new]
+```
+
+You are typically going to use Kase to handle errors:
+
+```ruby
+Kase.kase PushUserToElasticSearch.call(user) do
+  on(:ok) do |ctx|
+    # Do something
+  end
+  
+  on(:error, :network) do |reason|
+    NotifyHuman.log "failed to push user ##{user.id} to ElasticSearch"
+  end
+end
+```
+
+### Context
+
+An interactor is given a *context*. The context contains everything the
+interactor needs to do its work.
+
+When an interactor does its single purpose, it affects its given context.
+
+Context are assumed to be a Hash like object.
+
+#### Adding to the Context
+
+As an interactor runs it can add information to the context.
+
+```ruby
+context[:user] = user
+```
+
+### Hooks
+
+This implementation has no hooks.
+
+### An Example Interactor
+
+Your application could use an interactor to authenticate a user.
+
+```ruby
+class AuthenticateUser
+  include FunctionalInteractor
+
+  def call(context = {})
+    user = User.authenticate(context[:email], context[:password])
+
+    return [:error, :not_authenticated] unless user
+
+    context[:user] = user
+    context[:token] = user.secret_token
+
+    # Return a new context so we are not modifying the original
+    [:ok,  { user: user, token: user.secret_token }]
+  end
+end
+```
+
+To define an interactor, simply create a class that includes the `Interactor`
+module and give it a `call` instance method. The interactor can access its
+`context` from within `call`.
+
+## Interactors in the Controller
+
+Most of the time, your application will use its interactors from its
+controllers. The following controller:
+
+```ruby
+class SessionsController < ApplicationController
+  def create
+    if user = User.authenticate(session_params[:email], session_params[:password])
+      session[:user_token] = user.secret_token
+      redirect_to user
+    else
+      flash.now[:message] = "Please try again."
+      render :new
+    end
+  end
+
+  private
+
+  def session_params
+    params.require(:session).permit(:email, :password)
+  end
+end
+```
+
+can be refactored to:
+
+```ruby
+class SessionsController < ApplicationController
+  def create
+    Kase.kase AuthenticateUser.call(session_params) do
+      on(:ok) do |result|
+        session[:user_token] = result[:token]
+        redirect_to root_path
+      end
+      
+      on(:error, :not_authenticated) do
+        flash.now[:message] = t(result.message)
+        render :new
+      end
+    end
+  end
+
+  private
+
+  def session_params
+    params.require(:session).permit(:email, :password)
+  end
+end
+```
+
+The `.call` class method simply instantiates a new `AuthenticatedUser` interactor
+and passes the context to it. This allows us to create generic interactors 
+that can be inlined and composed together. This is discussed in the following section.
+
+## Advanced Usage
+
+### Sequences 
+
+`creativeideas/interactor` has an `Organizer` class. We have a similar code called
+`Interactors::Sequence`.
+
+Let's define a second interactor:
+
+```ruby
+class NotifyLogin
+  include FunctionalInteractor
+  
+  def call(context = {})
+    NotificationsMailer.login(user: context[:user]).deliver
+    [:ok, context]
+  end
+end
+```
+
+We can then chain them together like so:
+
+```ruby
+interactions = Interactors::Sequence.new
+interactions.compose(AuthenticatedUser)
+interactions.compose(NotifyLogin)
+
+Kase.kase interactions.call(session_params) do
+  on(:ok)    { |context| puts "Yay! Logged in!" }
+  on(:error) { |context| puts "Failed to login" }
+end
+```
+
+Here, the `Interactors::Sequence` object holds a sequence of
+interactions. It will call them one by one, starting from the top. If
+at any point, it returns something with `[:error, ...]` then the chain
+will stop. We can then use `Kase` to handle the error.
+
+### `#compose` and `|`
+
+We do not actually have to create an `Interactors::Sequence` object. The
+`#compose` method will create an `Interactors::Sequence` for you. You can
+chain them together like so:
+
+```ruby
+interactions = AuthenticatedUser.compose(NotifyLogin)
+
+Kase.kase interactions.call(session_params) do
+  on(:ok)    { |context| puts "Yay! Logged in!" }
+  on(:error) { |context| puts "Failed to login" }
+end
+```
+
+We also aliased `|` so you can use that instead:
+
+```ruby
+interactions = AuthenticatedUser | NotifyLogin
+
+Kase.kase interactions.call(session_params) do
+  on(:ok)    { |context| puts "Yay! Logged in!" }
+  on(:error) { |context| puts "Failed to login" }
+end
+```
+
+### Generic Interactors
+
+Sometimes we want to dynamically create an interactor. We can change the
+notification interactor to:
+
+```ruby
+interactions = AuthenticatedUser \
+| Interactors::Anonymous.new do
+    NotificationsMailer.login(user: context[:user]).deliver
+    [:ok, context]
+  end
+
+Kase.kase interactions.call(session_params) do
+  on(:ok)    { |context| puts "Yay! Logged in!" }
+  on(:error) { |context| puts "Failed to login" }
+end
+```
+
+There is a helper, `Interactors.new` that can simplify that:
+
+```ruby
+interactions = AuthenticatedUser \
+| Interactors.new do
+    NotificationsMailer.login(user: context[:user]).deliver
+    [:ok, context]
+  end
+
+Kase.kase interactions.call(session_params) do
+  on(:ok)    { |context| puts "Yay! Logged in!" }
+  on(:error) { |context| puts "Failed to login" }
+end
+```
+
+Since we don't care about handling errors, we can `Interactors::Simple` instead:
+
+```ruby
+interactions = AuthenticatedUser \
+| Interactors::Simple.new { NotificationsMailer.login(user: context[:user]).deliver }
+
+Kase.kase interactions.call(session_params) do
+  on(:ok)    { |context| puts "Yay! Logged in!" }
+  on(:error) { |context| puts "Failed to login" }
+end
+```
+
+This might seem like a lot for just a simple mailer. The real value comes from when
+there is a long chain of interactions:
+
+```ruby
+interactions = AuthenticatedUser \
+| FraudDetector \
+| Interactors::Simple.new { NotificationsMailer.login(user: context[:user]).deliver } \
+| ActivityLogger.new(:user_logs_in, controller: self) \
+| Interactors::RPC.new(service: :presence, module: :'Elixir.Presence.RPC', func: :register)
+
+Kase.kase interactions.call(session_params) do
+  on(:ok)    { |context| puts "Yay! Logged in!" }
+  on(:error) { |context| puts "Failed to login" }
+end
+```
+
+### Custom Generic Interactors
+
+Generic interactors work because we can override the constructor. In the case of a Rails mailer, 
+maybe we want to have a generic mailer:
+
+```ruby
+class Interactors::Mailer
+  include FunctionalInteractor
+  
+  def new(mailer:, method:)
+    @mailer = mailer
+    @method = method
+  end
+  
+  def call(context = {})
+    mailer.send(method, context)
+    [:ok, context]
+  end
+end
+```
+
+In which case, we can then use that:
+
+```ruby
+interactions = AuthenticatedUser \
+| Interactors::Mailer.new(mailer: NotificationsMailer, method: :login)
+
+Kase.kase interactions.call(session_params) do
+  on(:ok)    { |context| puts "Yay! Logged in!" }
+  on(:error) { |context| puts "Failed to login" }
+end
+```
+
+## Further Discussion
+
+`collectiveideas/interactor` has a great section discussing on when to
+use interactors: https://github.com/collectiveidea/interactor#when-to-use-an-interactor