decouplio 1.0.0alpha7 → 1.0.0rc

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b142d4fd94ec689714987c59946aab6c14d7d857a4aa11e55c624c5f7975e622
-  data.tar.gz: fc96e94c4d3358fda4eca1e80bfaeb7021a444bc5d9d1ff41b2b1b5f2283dbda
+  metadata.gz: 3f372ffe111d0d286f3c1898645caeb50be16ef3131b6749a28d0d8b43629392
+  data.tar.gz: 717430fa9380f5f4fcd8eb399b1399b47355bdc05860d253fce1b9ea105c5764
 SHA512:
-  metadata.gz: 1fc456438780d78c73280883a8b780148568e0a3ac5a2d21162575c73be6a7401378d6a37367aa31f28878226a274a27803da6ecf2b8b2e976b04b536829f3c1
-  data.tar.gz: 760d3c4a61d0985b4b49633f3c010107a5833e241ac133613439f9f9f031417e022af02ccef23e77681db22d6fdaeb3d186a18d46237bcd216a22dc0388f77eb
+  metadata.gz: 011e581a2643ebfd78a93de90dd5e425cf062fe555d8c0f115a12066cf2a612118ba41e9975f97c7decced6bf1d44f805062b1170b558c9e32fd16bdd818c47e
+  data.tar.gz: 072a87e219c5a90ab64c3aebcd5bb61459108f3cdc3c69e1f0d28a772860cba47a9cd0a36912b8e412bda6d45e9b264aac8bc6ef962fcdb2fd0856e4c4e3f649

data/README.md

@@ -2,37 +2,335 @@
 
 Decouplio is a zero dependency, thread safe and framework agnostic gem designed to encapsulate application business logic. It's reverse engineered through TDD and inspired by such frameworks and gems like Trailblazer, Interactor.
 
-## Installation
+# How to install?
 
-Add this line to your application's Gemfile:
+```
+gem install decouplio --pre
+```
+
+### Gemfile
+```
+gem 'decouplio', '~> 1.0.0rc'
+```
+
+# Compatibility
+  Ruby:
+ - 2.7
+ - 3.0
+
+# Quick reference to docs
+
+|Options/Step type|[**step**](https://differencialx.github.io/decouplio.github.io/step/)|[**fail**](https://differencialx.github.io/decouplio.github.io/fail/)|[**pass**](https://differencialx.github.io/decouplio.github.io/pass/)|[**wrap**](https://differencialx.github.io/decouplio.github.io/wrap/)|[**octo**](https://differencialx.github.io/decouplio.github.io/octo/)|[**resq**](https://differencialx.github.io/decouplio.github.io/resq/)|
+|:-|:-:|:-:|:-:|:-:|:-:|:-:|
+||[**on_success**](https://differencialx.github.io/decouplio.github.io/on_success/)|[**on_success**](https://differencialx.github.io/decouplio.github.io/on_success/)||[**on_success**](https://differencialx.github.io/decouplio.github.io/on_success/)|[**on_success**](https://differencialx.github.io/decouplio.github.io/on_success/)|-|
+||[**on_failure**](https://differencialx.github.io/decouplio.github.io/on_failure/)|[**on_failure**](https://differencialx.github.io/decouplio.github.io/on_failure/)||[**on_failure**](https://differencialx.github.io/decouplio.github.io/on_failure/)|[**on_failure**](https://differencialx.github.io/decouplio.github.io/on_failure/)|-|
+||[**on_error**](https://differencialx.github.io/decouplio.github.io/on_error/)|[**on_error**](https://differencialx.github.io/decouplio.github.io/on_error/)|[**on_error**](https://differencialx.github.io/decouplio.github.io/on_error/)|[**on_error**](https://differencialx.github.io/decouplio.github.io/on_error/)|[**on_error**](https://differencialx.github.io/decouplio.github.io/on_error/)|-|
+||[**finish_him**](https://differencialx.github.io/decouplio.github.io/finish_him/)|[**finish_him**](https://differencialx.github.io/decouplio.github.io/finish_him/)|[**finish_him**](https://differencialx.github.io/decouplio.github.io/finish_him/)|[**finish_him**](https://differencialx.github.io/decouplio.github.io/finish_him/)||-|
+||[**if/unless**](https://differencialx.github.io/decouplio.github.io/if_unless/)|[**if/unless**](https://differencialx.github.io/decouplio.github.io/if_unless/)|[**if/unless**](https://differencialx.github.io/decouplio.github.io/if_unless/)|[**if/unless**](https://differencialx.github.io/decouplio.github.io/if_unless/)|[**if/unless**](https://differencialx.github.io/decouplio.github.io/if_unless/)|-|
+
+#### [Documentation is HERE](https://differencialx.github.io/decouplio.github.io/)
+
+# Quick start
+## What should you know before start?
+
+### Action
+
+Action is a class which encapsulates business logic. To create one just create a class and inherit it from `Decouplio::Action` class
 
 ```ruby
-gem 'decouplio'
+require 'decouplio'
+
+class MyAction < Decouplio::Action
+end
 ```
 
-And then execute:
+### Logic block
 
-    $ bundle
+Block inside `Action` which contains definition of business logic.
 
-Or install it by yourself:
+```ruby
+require 'decouplio'
 
-    $ gem install decouplio
+class MyAction < Decouplio::Action
+  logic do
+    # logic block
+  end
+end
+```
 
-## Currently decouplio is in alpha testing, more features will come soon.
+### Step
 
-### Compatibility
-  Ruby:
- - 2.7
- - 3.0
+Step is an atomic part of business logic and it defines inside `Logic block`.
+
+```ruby
+require 'decouplio'
+
+class MyAction < Decouplio::Action
+  logic do
+    step :hello_world
+  end
+
+  def hello_world
+    ctx[:result] = 'Hello world'
+  end
+end
+
+MyAction.call[:result] # => Hello world
+```
+
+|Step types|
+|:-:|
+|[**step**](https://differencialx.github.io/decouplio.github.io/step/)|
+|[**fail**](https://differencialx.github.io/decouplio.github.io/fail/)|
+|[**pass**](https://differencialx.github.io/decouplio.github.io/pass/)|
+|[**wrap**](https://differencialx.github.io/decouplio.github.io/wrap/)|
+|[**octo**](https://differencialx.github.io/decouplio.github.io/octo/)|
+|[**resq**](https://differencialx.github.io/decouplio.github.io/resq/)|
+
+
+### Context
+Action context is an object which is used to share data between steps. It's accessible only inside step.
+- To access the action context inside step you need to call `ctx` method
+- `ctx` behaves like a `Hash`.
+- To assign some value to `ctx` just do `ctx[:some_key] = 'some value'`
+- To access `ctx` value use `ctx[:some_value]` or use a shortcut `c.some_value`
+
+NOTE: you **can't** assign context value using `c.<some key>` shortcut.
+
+```ruby
+require 'decouplio'
+
+class CtxIntroduction < Decouplio::Action
+  logic do
+    step :calculate_result
+  end
+
+  def calculate_result
+    ctx[:result] = c.one + c.two
+    # OR
+    # c[:result] = c[:one] + c[:two]
+    #OR
+    # ctx[:result] = ctx[:one] + ctx[:two]
+  end
+end
+
+action_result = CtxIntroduction.call(one: 1, two: 2)
+
+action_result[:result] # => 3
+```
+
+### Success/Failure track
+Execution flow of action is changing depending on step result.
+- If step returns truthy value(**not** `nil|false`), when next `success` track step will be executed.
+- If step returns falsy value(`nil|false`), when next `failure` track step will be executed.
+
+|Success track|Failure track|
+|-|-|
+|[**step**](https://differencialx.github.io/decouplio.github.io/step/)|[**fail**](https://differencialx.github.io/decouplio.github.io/fail/)|
+|[**pass**](https://differencialx.github.io/decouplio.github.io/pass/)||
+|[**wrap**](https://differencialx.github.io/decouplio.github.io/wrap/)||
+|[**octo**](https://differencialx.github.io/decouplio.github.io/octo/)||
+
+```ruby
+require 'decouplio'
+
+class Divider < Decouplio::Action
+  logic do
+    step :validate_divider
+    step :divide
+    fail :failure_message
+  end
+
+  def validate_divider
+    !ctx[:divider].zero?
+  end
+
+  def divide
+    ctx[:result] = c.number / c.divider
+  end
 
-### [Documentation is HERE](https://differencialx.github.io/decouplio.github.io/)
+  def failure_message
+    ctx[:error_message] = 'Division by zero is not allowed'
+  end
+end
+
+divider_success = Divider.call(number: 4, divider: 2)
+divider_success.success? # => true
+divider_success.failure? # => false
+divider_success[:result] # => 2
+divider_success[:error_message] # => nil
+divider_success.railway_flow # => [:validate_divider, :divide]
+puts divider_success # =>
+# Result: success
+
+# RailwayFlow:
+#   validate_divider -> divide
+
+# Context:
+#   :number => 4
+#   :divider => 2
+#   :result => 2
+
+# Status: NONE
+
+# Errors:
+#   NONE
+
+divider_failure = Divider.call(number: 4, divider: 0)
+divider_failure.success? #=> false
+divider_failure.failure? #=> true
+divider_failure[:result] # => nil
+divider_failure[:error_message] # => 'Division by zero is not allowed'
+divider_failure.railway_flow# => [:validate_divider, :failure_message]
+divider_failure # =>
+# Result: failure
+
+# RailwayFlow:
+#   validate_divider -> failure_message
+
+# Context:
+#   :number => 4
+#   :divider => 0
+#   :error_message => "Division by zero is not allowed"
+
+# Status: NONE
+
+# Errors:
+#   NONE
+
+```
+
+### Railway flow
+
+During execution `Decouplio` is recording executed steps, so you check which steps were executed. It becomes in handy during debugging and writing test.
+
+```ruby
+class RailwayAction < Decouplio::Action
+  logic do
+    step :step1
+    step :step2
+    step :step3
+  end
+
+  def step1
+    ctx[:step1] = 'Step1'
+  end
+
+  def step2
+    ctx[:step2] = 'Step2'
+  end
+
+  def step3
+    ctx[:step3] = 'Step3'
+  end
+end
+
+railway_action = RailwayAction.call
+railway_action.railway_flow.inspect # => [:step1, :step2, :step3]
+
+railway_action # =>
+# Result: success
+
+# RailwayFlow:
+#   step1 -> step2 -> step3
+
+# Context:
+#   :step1 => "Step1"
+#   :step2 => "Step2"
+#   :step3 => "Step3"
+
+# Status: NONE
+
+# Errors:
+#   NONE
+```
+
+### Meta Store
+
+Generally `metastore` is a PORO, which is accessible inside steps by calling `meta_store` method or it's alias `ms`. It was created to help developers to standardize things and keep meta info about action, because sometimes `success?` or `failure?` is not enough to make a decision about what to do next. I defined default metastore class which can manage custom action `status` and standardizes the way how error messages should be added.
+
+That's how default `metastore` class looks like
+```ruby
+# frozen_string_literal: true
+module Decouplio
+  class DefaultMetaStore
+    attr_accessor :status, :errors
+
+    def initialize
+      @errors = {}
+      @status = nil
+    end
+
+    def add_error(key, messages)
+      @errors.store(
+        key,
+        (@errors[key] || []) + [messages].flatten
+      )
+    end
+
+    # This method is used to print metastore status to console
+    # when you checking action output
+    def to_s
+      <<~METASTORE
+        Status: #{@status || 'NONE'}
+
+        Errors:
+          #{errors_string}
+      METASTORE
+    end
+
+    private
+
+    def errors_string
+      return 'NONE' if @errors.empty?
+
+      @errors.map do |k, v|
+        "#{k.inspect} => #{v.inspect}"
+      end.join("\n  ")
+    end
+  end
+end
+```
+So it's allows you do this
+```ruby
+  class MetaStoreAction < Decouplio::Action
+    logic do
+      step :always_fails
+      fail :handle_fail
+    end
+
+    # Decouplio has to constants which are accessible inside steps
+    # PASS = true
+    # FAIL = false
+    # You can use then to force step to fail or pass instead of `true` of `false`
+
+    def always_fails
+      FAIL
+    end
+
+    def handle_fail
+      ms.status = :failed_and_i_duno_why
+      ms.add_error(:something_went_wrong, 'Something went wrong')
+      ms.add_error(:something_went_wrong, 'And I duno why :(')
+    end
+  end
+
+  MetaStoreAction.call #=>
+  # Result: failure
+  # RailwayFlow:
+  #   always_fails -> handle_fail
+  # Context:
+  #   Empty
+  # Status: :failed_and_i_duno_why
+  # Errors:
+  #   :something_went_wrong => ["Something went wrong", "And I duno why :("]
+```
+ **NOTE: you can always define your own metastore class accordingly to your needs. [DOCS ARE HERE](https://differencialx.github.io/decouplio.github.io/meta_store/)**
 
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/differencialx/decouplio/issues.
 
-More detailed description for contribution process will be added later.
-
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/decouplio.gemspec

@@ -17,7 +17,7 @@ Gem::Specification.new do |spec|
 
   if spec.respond_to?(:metadata)
     spec.metadata['homepage_uri'] = spec.homepage
-    spec.metadata['source_code_uri'] = 'https://github.com/differencialx/decouplio/blob/master/docs'
+    spec.metadata['source_code_uri'] = 'https://github.com/differencialx/decouplio/'
     spec.metadata['changelog_uri'] = 'https://github.com/differencialx/decouplio/blob/master/docs/CHANGELOG.md'
   else
     raise 'RubyGems 2.0 or newer is required to protect against ' \
@@ -25,8 +25,14 @@ Gem::Specification.new do |spec|
   end
 
   spec.files = Dir.chdir(File.expand_path(__dir__)) do
-    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+    `git ls-files -z`.split("\x0").select { |f| f.match(%r{^(lib)/|.gemspec|LICENSE|Rakefile|README}) }
   end
+
+  # spec.files = Dir.chdir(File.expand_path(__dir__)) do
+  #   `git ls-files -z`.split("\x0").reject do |f|
+  #     f.match(%r{(test|spec|features|benchmarks|bin|.rubocop|.gitignore|Dockerfile|.ruby-version|docker|.vscode|.circle)(\/)*})
+  #   end
+  # end
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']

data/lib/decouplio/action.rb

@@ -1,83 +1,38 @@
 # frozen_string_literal: true
 
-require 'forwardable'
-require_relative 'flow'
-require_relative 'processor'
-require_relative 'default_error_handler'
-require_relative 'errors/logic_redefinition_error'
-require_relative 'errors/logic_is_not_defined_error'
-require_relative 'errors/error_store_error'
-require_relative 'errors/execution_error'
-require_relative 'const/results'
-
 module Decouplio
   class Action
     extend Forwardable
-    def_delegators :@error_store, :errors, :add_error, :error_status
-    attr_reader :railway_flow, :ctx, :error_store
+    def_delegator :@ctx, :[]
+
+    attr_reader :railway_flow, :ctx, :meta_store
+    attr_writer :success
+
+    alias ms meta_store
+    alias c ctx
+
+    PASS = true
+    FAIL = false
 
     def initialize(
-      parent_railway_flow: nil, parent_ctx: nil, error_store:, **params
+      meta_store, parent_railway_flow, ctx
     )
-      @error_store = error_store
-      @ctx = parent_ctx || params
-      @railway_flow = parent_railway_flow || []
-      @failure = false
-    end
-
-    def [](key)
-      @ctx[key]
+      @meta_store = meta_store
+      @ctx = ctx
+      @railway_flow = parent_railway_flow
+      @success = true
     end
 
     def success?
-      !@failure
+      @success
     end
 
     def failure?
-      @failure
-    end
-
-    def fail_action
-      @failure = true
-    end
-
-    def pass_action
-      @failure = false
-    end
-
-    def previous_step
-      railway_flow[PREVIOUS_STEP_INDEX]
-    end
-
-    def append_railway_flow(stp)
-      railway_flow << stp
+      !@success
     end
 
     def inspect
-      <<~INSPECT
-        Result: #{success? ? 'success' : 'failure'}
-
-        Railway Flow:
-          #{railway_flow.join(' -> ')}
-
-        Context:
-          #{ctx.map { |k, v| "#{k.inspect} => #{v.inspect}" }.join("\n  ")}
-
-        Errors:
-          #{
-            if errors.is_a?(Hash)
-              if errors.empty?
-                'None'
-              else
-                errors.map do |k, v|
-                  "#{k.inspect} => #{v.inspect}"
-                end.join("\n  ")
-              end
-            else
-              errors
-            end
-          }
-      INSPECT
+      Decouplio::ActionStatePrinter.call(self)
     end
 
     def to_s
@@ -85,16 +40,21 @@ module Decouplio
     end
 
     class << self
-      attr_accessor :error_store
+      attr_accessor :meta_store
 
-      def error_store_class(klass)
-        self.error_store = klass
+      def meta_store_class(klass)
+        self.meta_store = klass
       end
 
-      def call(**params)
-        instance = new(error_store: error_store.new, **params)
-        Decouplio::Processor.call(instance: instance, **@flow)
-        # TODO: process block with after actions
+      def call(_parent_meta_store: nil, _parent_railway_flow: nil, _parent_ctx: nil, **params)
+        instance = new(
+          _parent_meta_store || meta_store.new,
+          _parent_railway_flow || [],
+          _parent_ctx || Ctx[params]
+        )
+        next_step = @first_step
+
+        next_step = next_step.process(instance) while next_step
         instance
       end
 
@@ -112,19 +72,19 @@ module Decouplio
       private
 
       def inherited(child_class)
-        child_class.error_store = error_store || Decouplio::DefaultErrorHandler
+        child_class.meta_store = meta_store || Decouplio::DefaultMetaStore
       end
 
       def logic(&block)
-        if @flow && !@flow[:first_step].nil?
+        unless @first_step.nil?
           raise Decouplio::Errors::LogicRedefinitionError.new(
             errored_option: to_s
           )
         end
         if block_given?
-          @flow = Decouplio::Flow.call(logic: block, action_class: self)
+          @first_step = Decouplio::NewFlow.call(block)
 
-          if @flow && @flow[:first_step].nil?
+          if @first_step.nil?
             raise Decouplio::Errors::LogicIsNotDefinedError.new(
               errored_option: to_s
             )

data/lib/decouplio/action_state_printer.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Decouplio
+  class ActionStatePrinter
+    def self.call(action)
+      <<~INSPECT
+        Result: #{result(action)}
+        RailwayFlow:
+          #{railway_flow(action)}
+        Context:
+          #{action_context(action)}
+        #{meta_store(action)}
+      INSPECT
+    end
+
+    def self.result(action)
+      action.success? ? 'success' : 'failure'
+    end
+
+    def self.railway_flow(action)
+      action.railway_flow.join(' -> ')
+    end
+
+    def self.action_context(action)
+      return 'Empty' if action.ctx.empty?
+
+      action.ctx.map { |k, v| "#{k.inspect} => #{v.inspect}" }.join("\n  ")
+    end
+
+    def self.meta_store(action)
+      action.ms.to_s
+    end
+  end
+end

data/lib/decouplio/const/flows.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Decouplio
+  module Const
+    module Flows
+      MAIN_FLOW = [
+        Decouplio::Steps::Step,
+        Decouplio::Steps::Fail,
+        Decouplio::Steps::Pass,
+        Decouplio::Steps::InnerActionStep,
+        Decouplio::Steps::InnerActionFail,
+        Decouplio::Steps::InnerActionPass,
+        Decouplio::Steps::OctoByKey,
+        Decouplio::Steps::OctoByMethod,
+        Decouplio::Steps::ServiceAsStep,
+        Decouplio::Steps::ServiceAsFail,
+        Decouplio::Steps::ServiceAsPass,
+        Decouplio::Steps::ServiceAsPass,
+        Decouplio::Steps::WrapWithClass,
+        Decouplio::Steps::WrapWithClassMethod,
+        Decouplio::Steps::Wrap
+      ].freeze
+      PASS_FLOW = [
+        Decouplio::Steps::Step,
+        Decouplio::Steps::Pass,
+        Decouplio::Steps::InnerActionStep,
+        Decouplio::Steps::InnerActionPass,
+        Decouplio::Steps::ServiceAsStep,
+        Decouplio::Steps::ServiceAsPass,
+        Decouplio::Steps::ServiceAsPass,
+        Decouplio::Steps::OctoByKey,
+        Decouplio::Steps::OctoByMethod,
+        Decouplio::Steps::WrapWithClass,
+        Decouplio::Steps::WrapWithClassMethod,
+        Decouplio::Steps::Wrap
+      ].freeze
+      FAIL_FLOW = [
+        Decouplio::Steps::Fail,
+        Decouplio::Steps::InnerActionFail,
+        Decouplio::Steps::ServiceAsFail
+      ].freeze
+      RESQ_CLASSES = [
+        Decouplio::Steps::ResqPass,
+        Decouplio::Steps::ResqFail,
+        Decouplio::Steps::ResqWithMappingPass,
+        Decouplio::Steps::ResqWithMappingFail
+      ].freeze
+      WRAP_CLASSES = [
+        Decouplio::Steps::WrapWithClass,
+        Decouplio::Steps::WrapWithClassMethod,
+        Decouplio::Steps::Wrap
+      ].freeze
+      OCTO_CLASSES = [
+        Decouplio::Steps::OctoByMethod,
+        Decouplio::Steps::OctoByKey
+      ].freeze
+    end
+  end
+end

data/lib/decouplio/const/reserved_methods.rb

@@ -1,21 +1,14 @@
 # frozen_string_literal: true
 
-require_relative 'results'
-
 module Decouplio
   module Const
     module ReservedMethods
-      NAMES = [
-        :[],
-        :success?,
-        :failure?,
-        :fail_action,
-        :pass_action,
-        :append_railway_flow,
-        :inspect,
-        :to_s,
-        Decouplio::Const::Results::STEP_PASS,
-        Decouplio::Const::Results::STEP_FAIL
+      NAMES = %i[
+        \[\]
+        inspect
+        to_s
+        PASS
+        FAIL
       ].freeze
     end
   end