light_operations 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: c894c1e7f9c3a1a15692c6875f4ded5b88d458d9
-  data.tar.gz: 9d841c8af28c066013159703d302ef42cb354991
+  metadata.gz: f01d43765f156039ef8227aa36ef7fc853bbc722
+  data.tar.gz: 6a28e10184931953b04722b98ad505e100636307
 SHA512:
-  metadata.gz: 2c3dcbef05689a60f891fc292b4fb96079406e6703d5ce7df0ca56ca2fee36ccc6808bb4987bbbfe4f095ec03f2dee656ff1aaa90dc5155a6982ddd4a522f3fb
-  data.tar.gz: a1b15f8668462cf6409450825a6a9f23d2e20040b44e53a8b39a42f17a73499a23bf28ab70ead3a583911e3453836bbc13e15bcbfe69163c2aae3df8f8a68952
+  metadata.gz: 0709083f10d462b9421924e4313323b38dd077a3908827fef106eb8cfee646a6128cde566399fff48cc431c72cc18d5e1c86a8bfa3044d9f61a59a4ba9219527
+  data.tar.gz: 80297934730c17e80022a7ecb2c843a3882ae14cd6041fab3a8fa08941e446c47aa6dca8c507005dfc2014dd0777fbe884d8793d6354065193282d61087ce6d5

data/README.md

@@ -19,6 +19,109 @@ Or install it yourself as:
 
     $ gem install light_operations
 
+## How it works
+
+Basicly this is a Container for buissnes logic.
+
+You can define dependencies during initialization and run with custom parameters.
+When you define deferred actions on `success` and `fail` before operation execution is finished,
+after execution one of those action depend for execution result will be executed.
+Actions could be a block (Proc) or you could delgate execution to method other object,
+by binding operation with specific object with those methods.
+You also could use operation as simple execution and check status by `success?` or `fail?` method
+and then by using `subject` and `errors` method build your own logic to finish your result.
+There is many possible usecases where and how you could use operations.
+You can build csacade of opreations, use them one after the other,
+use them recursively and a lot more.
+
+Class
+
+```ruby
+class MyOperation < LightOperations::Core
+  def execute(_params = nil)
+    dependency(:my_service) # when missing MissingDependency error will be raised
+  end
+end
+
+```
+
+Initialization
+
+```ruby
+MyOperation.new(my_service: MyService.new)
+```
+
+You can add deferred actions for success and fail
+
+```ruby
+# 1
+MyOperation.new.on_success { |model| render :done, locals: { model: model } }
+# 2
+MyOperation.new.on(success: -> () { |model| render :done, locals: { model: model } )
+```
+
+When you bind operation with other object you could delegate actions to binded object methods
+
+```ruby
+# 1
+MyOperation.new.bind_with(self).on_success(:done)
+# 2
+MyOperation.new.bind_with(self).on(success: :done)
+```
+
+Execution method `#run` finalize actions execution
+
+```ruby
+MyOperation.new.bind_with(self).on(success: :done).run(params)
+```
+
+After execution operation hold execution state you could get back all info you need
+
+- `#success?` => `true/false`
+- `#fail?`    => `true/false`
+- `#subject?` => `success or fail object`
+- `#errors`   => `errors by default array but you can return any objec tou want`
+
+Default usage
+
+```ruby
+operation.new(dependencies)
+  .on(success: :done, fail: :show_error)
+  .bind_with(self)
+  .run(params)
+```
+
+or
+
+```ruby
+operation.new(dependencies).tap do |op|
+  return op.run(params).success? ? op.subject : op.errors
+end
+```
+
+#### success block or method receive subject as argument
+`(subject) -> { }`
+
+or
+
+```ruby
+def success_method(subject)
+  ...
+end
+
+```
+#### fail block or method receive subject and errors as argument
+`(subject, errors) -> { }`
+
+or
+
+```ruby
+def fail_method(subject, errors)
+  ...
+end
+
+```
+
 ## Usage
 
 
@@ -37,10 +140,11 @@ class ArticleVoteBumperOperation < LightOperations::Core
       article.vote = article.vote.next
       article.save
     end
+    { success: true }
   end
 
   def on_ar_error(_exception)
-    fail!({ vote: 'could not be updated!' })
+    fail!(vote: 'could not be updated!')
   end
 end
 ```
@@ -50,14 +154,14 @@ Controller
 ```ruby
 class ArticleVotesController < ApplicationController
   def up
-    response = article_vote_bumper_op.run.success? ? { success: true } : article_vote_bumper_op.errors
+    response = operation.run.success? ? response.subject : response.errors
     render :up, json: response
   end
 
   private
 
-  def article_vote_bumper_op
-    @article_vote_bumper_op ||= ArticleVoteBumperOperation.new(article_model: article)
+  def operation
+    @operation ||= ArticleVoteBumperOperation.new(article_model: article)
   end
 
   def article
@@ -66,7 +170,7 @@ class ArticleVotesController < ApplicationController
 end
 ```
 
-#### Basic recursion execution for collect newsfeeds from 2 sources
+#### Basic recursive execution to collect newsfeeds from 2 sources
 
 Operation
 
@@ -92,7 +196,8 @@ class NewsFeedsController < ApplicationController
   BACKUP_NEWS_URL = 'http://rss.not_so_bad_news.pl'
   def news
     collect_feeds_op
-      on(success: :display_news, fail: :second_attempt)
+      .bind_with(self)
+      .on(success: :display_news, fail: :second_attempt)
       .run(url: DEFAULT_NEWS_URL)
   end
 
@@ -105,7 +210,7 @@ class NewsFeedsController < ApplicationController
   end
 
   def display_news(news)
-    render :display_news, locals { news: news }
+    render :display_news, locals: { news: news }
   end
 
   def display_old_news
@@ -121,7 +226,58 @@ class NewsFeedsController < ApplicationController
 end
 ```
 
+#### Basic with active_model/active_record object
+
+Operation
+
+```ruby
+class AddBookOperation < LightOperations::Core
+  def execute(params = {})
+    dependency(:book_model).new(params).tap do |model|
+      model.valid? # this method automatically provide errors from model.errors
+    end
+  end
+end
+```
+
+Controller
+
+```ruby
+class BooksController < ApplicationController
+  def index
+    render :index, locals: { collection: Book.all }
+  end
+
+  def new
+    render_book_form
+  end
+
+  def create
+    add_book_op
+      .bind_with(self)
+      .on(success: :book_created, fail: :render_book_form)
+      .run(permit_book_params)
+  end
+
+  private
+
+  def book_created(book)
+    redirect_to :index, notice: "book #{book.name} created"
+  end
+
+  def render_book_form(book = Book.new, _errors = nil)
+    render :new, locals: { book: book }
+  end
 
+  def add_book_op
+    @add_book_op ||= AddBookOperation.new(book_model: Book)
+  end
+
+  def permit_book_params
+    params.requre(:book)
+  end
+end
+```
 
 #### Simple case when you want have user authorization
 
@@ -253,13 +409,27 @@ class AuthController < ApplicationController
 end
 ```
 
+Register success and fails action is avialable by `#on` like :
+
+```ruby
+  def create
+    auth_op.bind_with(self).on(success: :dashboard, fail: :show_error).run(params)
+  end
+```
+
+Operation have some helper methods (to improve recursive execution)
+
+- `#clear!`                     => return operation to init state
+- `#unbind!`                    => unbind binded object
+- `#clear_subject_with_errors!` => clear subject and errors
+
 When operation status is most importent we can simply use `#success?` or `#fail?` on the executed operation
 
 Errors are available by `#errors` after operation is executed
 
 ## Contributing
 
-1. Fork it ( https://github.com/[my-github-username]/swift_operations/fork )
+1. Fork it ( https://github.com/[my-github-username]/light_operations/fork )
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Add some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)

data/lib/light_operations/core.rb

@@ -13,6 +13,7 @@ module LightOperations
 
     # do no.t override this method
     def run(params = {})
+      clear_subject_with_errors!
       @subject = execute(params)
       execute_actions
       self

data/lib/light_operations/version.rb

@@ -1,3 +1,3 @@
 module LightOperations
-  VERSION = '0.0.3'
+  VERSION = '0.0.4'
 end

data/spec/lib/core_spec.rb

@@ -5,6 +5,16 @@ describe LightOperations::Core do
   let(:params)        { { login: 'pawel', password: 'abc' } }
   let(:dependencies)  { { login_service: login_service } }
 
+  let(:binding_object) do
+    Class.new(Object).tap do |klass|
+      klass.class_eval do
+        def success_action(_subject); end
+
+        def error_action(_subject, _errors); end
+      end
+    end.new
+  end
+
   def subject_factory(&block)
     Class.new(described_class).tap do |klass|
       klass.class_eval(&block)
@@ -18,15 +28,6 @@ describe LightOperations::Core do
   end
 
   context 'use cases' do
-    let(:binding_object) do
-      Class.new(Object).tap do |klass|
-        klass.class_eval do
-          def success_action(_subject); end
-
-          def error_action(_subject, _errors); end
-        end
-      end.new
-    end
 
     # dependency using
 
@@ -234,4 +235,27 @@ describe LightOperations::Core do
       subject.clear!
     end
   end
+
+  context 'Operation executed several times' do
+    subject do
+      subject_factory do
+        def execute(params = {})
+          fail!(:missing_result) unless params.key?(:result)
+          params[:result]
+        end
+      end
+    end
+
+    it 'always start with clean state of subject and errors' do
+
+      subject
+        .bind_with(binding_object)
+        .on(success: :success_action, fail: :error_action)
+
+      expect(binding_object).to receive(:error_action).with(nil, :missing_result)
+      subject.run
+      expect(binding_object).to receive(:success_action).with(:success)
+      subject.run(result: :success)
+    end
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: light_operations
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Pawel Niemczyk
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-28 00:00:00.000000000 Z
+date: 2015-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport