lite-command 1.4.1 → 2.0.0

data/README.md

@@ -4,7 +4,6 @@
 [![Build Status](https://travis-ci.org/drexed/lite-command.svg?branch=master)](https://travis-ci.org/drexed/lite-command)
 
 Lite::Command provides an API for building simple and complex command based service objects.
-It provides mixins for handling errors and memoization to improve your object workflow productivity.
 
 ## Installation
 
@@ -25,260 +24,128 @@ Or install it yourself as:
 ## Table of Contents
 
 * [Setup](#setup)
-* [Simple](#simple)
-* [Complex](#complex)
-* [Procedure](#procedure)
-* [Extensions](#extensions)
+* [Execution](#execution)
+* [Context](#context)
+* [Internals](#Internals)
+* [Generator](#generator)
 
 ## Setup
 
-`rails g command NAME` will generate the following file:
-
-```erb
-app/commands/[NAME]_command.rb
-```
-
-If a `ApplicationCommand` file in the `app/commands` directory is available, the
-generator will create file that inherit from `ApplicationCommand` if not it will
-fallback to `Lite::Command::Complex`.
-
-## Simple
-
-Simple commands build quick class based calls but cannot be extended.
-This is more of a traditional command service call as it only exposes a `call` method.
+Defining a command is as simple as adding a call method.
 
 ```ruby
-class SearchMovies < Lite::Command::Simple
+class CalculatePower < Lite::Command::Base
 
-  # NOTE: This class method is required
-  def self.execute(*args)
-    { generate_fingerprint => movies_by_name }
+  def call
+    # TODO: implement calculator
   end
 
 end
 ```
 
-**Caller**
+## Execution
 
-```ruby
-SearchMovies.call('Toy Story')
-```
-
-## Complex
-
-Complex commands can be used in instance and class based calls and
-extended with access to errors and memoization.
+Executing a command can be done as an instance or class call.
+It returns the command instance in a forzen state.
+These will never call will never raise an execption, but will
+be kept track of in its internal state.
 
-You will then need to fill this class with the required `execute` method as shown below:
+**NOTE:** Class calls is the prefered format due to its readability.
 
 ```ruby
-class SearchMovies < Lite::Command::Complex
-
-  def initialize(name)
-    @name = name
-  end
+# Class call
+CalculatePower.call(..args)
 
-  # NOTE: This instance method is required
-  def execute
-    { generate_fingerprint => movies_by_name }
-  end
-
-  private
+# Instance call
+caculator = CalculatePower.new(..args).call
 
-  def movies_by_name
-    HTTP.get("http://movies.com?title=#{title}")
-  end
-
-  def generate_fingerprint
-    Digest::MD5.hexdigest(movies_by_name)
-  end
-
-end
-```
-
-**Caller**
-
-```ruby
-command = SearchMovies.new('Toy Story')
-command.called? #=> false
-command.call    #=> { 'fingerprint_1' => [ 'Toy Story 1', ... ] }
-command.called? #=> true
-
-# - or -
-
-command = SearchMovies.call('Toy Story')
-command.called? #=> true
-command.call    #=> { 'fingerprint_1' => [ 'Toy Story 1', ... ] }
-
-# - or -
-
-# Useful when you are not using the Errors mixin as its a one time access call.
-# Very similar to the simple command builder.
-SearchMovies.execute('Toy Story') #=> { 'fingerprint_1' => [ 'Toy Story 1', ... ] }
+#=> <CalculatePower ...>
 ```
 
-**Result**
+Commands can be called with a `!` bang method to raise a
+`Lite::Command::Fault` based exception or the original
+`StandardError` based exception.
 
 ```ruby
-command = SearchMovies.new('Toy Story')
-command.result  #=> nil
-
-command.call    #=> { 'fingerprint_1' => [ 'Toy Story 1', ... ] }
-command.result  #=> { 'fingerprint_1' => [ 'Toy Story 1', ... ] }
-
-command.recall! #=> Clears the call, cache, errors, and then re-performs the call
-command.result  #=> { 'fingerprint_2' => [ 'Toy Story 2', ... ] }
-```
-
-## Procedure
-
-Procedures run a collection of commands. It uses the the complex procedure API
-so it has access to all the methods. The `execute` method is already defined to
-handle most common procedure steps. It can be use directly or subclassed.
-
-```ruby
-class SearchChannels < Lite::Command::Procedure; end
-
-procedure = SearchChannels.call(
-  DisneyChannel.new,
-  EspnChannel.new(current_station),
-  MtvChannel.new
-)
-
-procedure.result #=> ['disney: #3', 'espn: #59', 'mtv: #212']
-procedure.steps  #=> [<DisneyChannel  @result="...">, <EspnChannel @result="...">, <MtvChannel  @result="...">]
-
-# If the errors extension is added you can stop the procedure at first failure.
-procedure = SearchChannels.new(
-  DisneyChannel.new,
-  ErrorChannel.new(current_station),
-  MtvChannel.new
-)
-
-procedure.exit_on_failure = true
-procedure.call
-procedure.result #=> ['disney: #3']
-procedure.failed_steps #=> [{ index: 1, step: 2, name: 'ErrorChannel', args: [current_station], errors: ['field error message'] }]
+CalculatePower.call!(..args)
+#=> raises Lite::Command::Fault
 ```
 
-## Extensions
-
-Extend complex (and procedures) base command with any of the following extensions:
+## Context
 
-### Errors (optional)
-
-Learn more about using [Lite::Errors](https://github.com/drexed/lite-errors)
+Accessing the call arguments can be done through its internal context.
+It can be used as internal storage to be accessed by it self and any
+of its children commands.
 
 ```ruby
-class SearchMovies < Lite::Command::Complex
-  include Lite::Command::Extensions::Errors
-
-  # ... ommited ...
+class CalculatePower < Lite::Command::Base
 
-  private
-
-  # Add a fingerprint error to the error pool
-  def generate_fingerprint
-    errors.add(:fingerprint, 'invalid md5 request value') if movies_by_name.nil?
-    Digest::MD5.hexdigest(movies_by_name)
-  rescue ArgumentError => e
-    merge_exception!(e, key: :custom_key)
+  def call
+    context.result = context.a ** context.b
   end
 
 end
-```
-
-**Callers**
-
-```ruby
-# Useful for controllers or actions that depend on states.
-SearchMovies.perform('Toy Story') do |result, success, failure|
-  success.call { redirect_to(movie_path, notice: "Movie can be found at: #{result}") }
-  failure.call { redirect_to(root_path, notice: "Movie cannot be found at: #{result}") }
-end
-```
-
-**Methods**
-
-```ruby
-command = SearchMovies.call('Toy Story')
-command.errors    #=> Lite::Errors::Messages object
-
-command.validate! #=> Raises Lite::Command::ValidationError if it has any errors
-command.valid?    #=> Alias for validate!
-
-command.errored?  #=> false
-command.success?  #=> true
-command.failure?  #=> Checks that it has been called and has errors
-command.status    #=> :failure
-
-command.result!   #=> Raises Lite::Command::ValidationError if it has any errors, if not it returns the result
-
-# Use the following to merge errors from other commands or models
-# with the default direction being `:from`
-command.merge_errors!(command_2)
-user_model.merge_errors!(command, direction: :to)
-```
-
-### Propagation (optional)
-
-Propagation methods help you perform an action on an object. If successful is
-returns the result else it adds the object errors to the form object. Available
-propagation methods are:
-  - `assign_and_return!(object, params)`
-  - `create_and_return!(klass, params)`
-  - `update_and_return!(object, params)`
-  - `destroy_and_return!(object)`
-  - `archive_and_return!(object)` (if using Lite::Archive)
-  - `save_and_return!(object)`
-
-```ruby
-class SearchMovies < Lite::Command::Complex
-  include Lite::Command::Extensions::Errors
-  include Lite::Command::Extensions::Propagation
-
-  # ... ommited ...
 
-  def execute
-    create_and_return!(User, name: 'John Doe')
-  end
-
-end
+command = CalculatePower.call(a: 2, b: 3)
+command.context.result #=> 8
 ```
 
-### Memoize (optional)
-
-Learn more about using [Lite::Memoize](https://github.com/drexed/lite-memoize)
-
-```ruby
-class SearchMovies < Lite::Command::Complex
-  include Lite::Command::Extensions::Memoize
-
-  # ... ommited ...
-
-  private
-
-  # Sets the value in the cache
-  # Subsequent method calls gets the cached value
-  # This saves you the extra external HTTP.get call
-  def movies_by_name
-    cache.memoize { HTTP.get("http://movies.com?title=#{title}") }
-  end
+## Internals
+
+#### States
+State represents the state of the executable code. Once `execute`
+is ran, it will always `complete` or `dnf` if a fault is thrown by a
+child command.
+
+- `pending`
+    - Command objects that have been initialized.
+- `executing`
+    - Command objects actively executing code.
+- `complete`
+    - Command objects that executed to completion.
+- `dnf`
+    - Command objects that could NOT be executed to completion.
+      This could be as a result of a fault/exception on the
+      object itself or one of its children.
+
+#### Statuses
+
+Status represents the state of the callable code. If no fault
+is thrown then a status of `success` is returned even if `call`
+has not been executed. The list of status include (by severity):
+
+- `success`
+    - No fault or exception
+- `noop`
+    - Noop represents skipping completion of call execution early
+      an unsatisfied condition or logic check where there is no
+      point on proceeding.
+    - **eg:** account is sample: skip since its a non-alterable record
+- `invalid`
+    - Invalid represents a stoppage of call execution due to
+      missing, bad, or corrupt data.
+    - **eg:** user not found: stop since rest of the call cant be executed
+- `failure`
+    - Failure represents a stoppage of call execution due to
+      an unsatisfied condition or logic check where it blocks
+      proceeding any further.
+    - **eg:** record not found: stop since there is nothing todo
+- `error`
+    - Error represents a caught exception for a call execution
+      that could not complete.
+    - **eg:** ApiServerError: stop since there was a 3rd party issue
+
+## Generator
 
-  # Gets the value in the cache
-  def generate_fingerprint
-    Digest::MD5.hexdigest(movies_by_name)
-  end
+`rails g command NAME` will generate the following file:
 
-end
+```erb
+app/commands/[NAME]_command.rb
 ```
 
-**Methods**
-
-```ruby
-command = SearchMovies.call('Toy Story')
-command.cache #=> Lite::Memoize::Instance object
-```
+If a `ApplicationCommand` file in the `app/commands` directory is available, the
+generator will create file that inherit from `ApplicationCommand` if not it will
+fallback to `Lite::Command::Base`.
 
 ## Development
 

data/Rakefile

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
-require 'bundler/gem_tasks'
-require 'rspec/core/rake_task'
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
 

data/bin/console

@@ -1,8 +1,8 @@
 #!/usr/bin/env ruby
 # frozen_string_literal: true
 
-require 'bundler/setup'
-require 'lite/command'
+require "bundler/setup"
+require "lite/command"
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
@@ -11,5 +11,5 @@ require 'lite/command'
 # require "pry"
 # Pry.start
 
-require 'irb'
+require "irb"
 IRB.start(__FILE__)

data/lib/generators/rails/command_generator.rb

@@ -3,12 +3,12 @@
 module Rails
   class CommandGenerator < Rails::Generators::NamedBase
 
-    source_root File.expand_path('../templates', __FILE__)
-    check_class_collision suffix: 'Command'
+    source_root File.expand_path("../templates", __FILE__)
+    check_class_collision suffix: "Command"
 
     def copy_files
-      path = File.join('app', 'commands', class_path, "#{file_name}_command.rb")
-      template('command.rb.tt', path)
+      path = File.join("app", "commands", class_path, "#{file_name}_command.rb")
+      template("command.rb.tt", path)
     end
 
     private
@@ -18,7 +18,7 @@ module Rails
     end
 
     def remove_possible_suffix(name)
-      name.sub(/_?command$/i, '')
+      name.sub(/_?command$/i, "")
     end
 
   end

data/lib/generators/rails/templates/command.rb.tt

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 <% module_namespacing do -%>
-class <%= class_name %>Command < <%= ApplicationCommand.to_s rescue 'Lite::Command::Complex' %>
+class <%= class_name %>Command < <%= ApplicationCommand.to_s rescue 'Lite::Command::Base' %>
 end
 <% end -%>

data/lib/lite/command/base.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Lite
+  module Command
+    class Base
+
+      def self.inherited(base)
+        super
+
+        base.include Lite::Command::Internals::Callable
+        base.include Lite::Command::Internals::Executable
+        base.include Lite::Command::Internals::Resultable
+
+        base.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+          # eg: Users::ResetPassword::Fault
+          class #{base}::Fault < Lite::Command::Fault; end
+        RUBY
+
+        FAULTS.each do |f|
+          base.class_eval <<-RUBY, __FILE__, __LINE__ + 1
+            # eg: Users::ResetPassword::Noop < Users::ResetPassword::Fault
+            class #{base}::#{f.capitalize} < #{base}::Fault; end
+          RUBY
+        end
+      end
+
+      attr_reader :context
+
+      def initialize(context = {})
+        @context = Lite::Command::Context.build(context)
+      end
+
+      private
+
+      def additional_result_data
+        {} # Define in your class to add additional info to result hash
+      end
+
+      def on_before_execution
+        # Define in your class to run code before execution
+      end
+
+      def on_after_execution
+        # Define in your class to run code after execution
+      end
+
+    end
+  end
+end

data/lib/lite/command/context.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "ostruct" unless defined?(OpenStruct)
+
+module Lite
+  module Command
+    class Context < OpenStruct
+
+      def self.init(attributes = {})
+        # To save memory and speed up the access to an attribute, the accessor methods
+        # of an attribute are lazy loaded at certain points. This means that the methods
+        # are defined only when a set of defined actions are triggered. This allows context
+        # to only define the minimum amount of required methods to make your data structure work
+        os = new(attributes)
+        os.methods(false)
+        os
+      end
+
+      def self.build(attributes = {})
+        return attributes if attributes.is_a?(self) && !attributes.frozen?
+
+        init(attributes.to_h)
+      end
+
+      def merge!(attributes = {})
+        attrs = attributes.is_a?(self.class) ? attributes.to_h : attributes
+        attrs.each { |k, v| self[k] = v }
+      end
+
+    end
+  end
+end

data/lib/lite/command/fault.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Lite
+  module Command
+
+    # Fault represent a stoppage of a call execution. This error should
+    # not be raised directly since it wont provide any context. Use
+    # `Noop`, `Invalid`, `Failure`, and `Error` to signify severity.
+    class Fault < StandardError
+
+      attr_reader :faulter, :thrower, :reason
+
+      def initialize(faulter, thrower, reason)
+        super(reason)
+
+        @faulter = faulter
+        @thrower = thrower
+        @reason = reason
+      end
+
+      def fault_klass
+        @fault_klass ||= self.class.name.split("::").last
+      end
+
+      def fault_name
+        @fault_name ||= fault_klass.downcase
+      end
+
+    end
+
+    # Noop represents skipping completion of call execution early
+    # an unsatisfied condition or logic check where there is no
+    # point on proceeding.
+    # eg: account is sample: skip since its a non-alterable record
+    class Noop < Fault; end
+
+    # Invalid represents a stoppage of call execution due to
+    # missing, bad, or corrupt data.
+    # eg: user not found: stop since rest of the call cant be executed
+    class Invalid < Fault; end
+
+    # Failure represents a stoppage of call execution due to
+    # an unsatisfied condition or logic check where it blocks
+    # proceeding any further.
+    # eg: record not found: stop since there is nothing todo
+    class Failure < Fault; end
+
+    # Error represents a caught exception for a call execution
+    # that could not complete.
+    # eg: ApiServerError: stop since there was a 3rd party issue
+    class Error < Fault; end
+
+  end
+end