fluxo 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9233de7ffd75f41b5448b99093874d462f38eb53bd0230e87ce110618db4811
-  data.tar.gz: 8fc63126176a8f49904ad2c2276442cbe71799f61c35f7eacd64fcccd176142d
+  metadata.gz: 9453729318ec0b9d59e2833d19a4383c4b2f1bb241a8f97774c3f3b2cb4e6654
+  data.tar.gz: b428e33f29ababb0e2099eb9807f295fb899c965088ab2e650c111961d24c76a
 SHA512:
-  metadata.gz: 59f97254f8ef0ef915f8d3e7d3bc18dc37ef1873bfd845606a56250680bc7eac870504381908859d08693c8b7ac3619881ee8ab82c13ebdcfa236591cf41fda7
-  data.tar.gz: 0ab68181c7f41d299ca02272a216ea94bc2ff078f2c128f90cad99cd6ca88e362a398b127829ab9320a46aaafd4a576e2050d06d4c802bb117ade1461b56301f
+  metadata.gz: 6ce303be1b5fa233fb9fc0e72eccebafd6d36e5ac81b2f6b8b1796c07c63bc5cbc097ed5fa7f48fdaf3457d3414335b8bbd1a63765557e7f3de0279a0dbb78ba
+  data.tar.gz: 514da4e79141fae0847ef16e2f4e9c67ac0246de87415277c657c93471cfe444a6eca8ec332b7a64aaa6286b61375b80d46ce49185fb5942b887d5a01ea4a271

data/.gitignore

@@ -6,3 +6,4 @@
 /pkg/
 /spec/reports/
 /tmp/
+fluxo-*.gem

data/.travis.yml

@@ -4,7 +4,6 @@ before_install:
   - gem --version
   - gem update bundler
   - gem --version
-  - bash ci/setup.sh
 
 jobs:
   fast_finish: true

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    fluxo (0.1.0)
+    fluxo (0.2.0)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -1,8 +1,6 @@
 # Fluxo
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/fluxo`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Provides a simple and powerful way to create operations service objects for complex workflows.
 
 ## Installation
 
@@ -22,7 +20,238 @@ Or install it yourself as:
 
 ## Usage
 
-TODO: Write usage instructions here
+Minimal operation definition:
+```ruby
+class MyOperation < Fluxo::Operation
+  def call!(**)
+    Success(:ok)
+  end
+end
+```
+
+And then just use the opperation by calling:
+```
+result = MyOperation.call
+result.success? # => true
+result.value # => :ok
+```
+
+In order to execute an operation with parameters, you must first define list of attributes:
+
+```ruby
+class MyOperation < Fluxo::Operation
+  attributes :param1, :param2
+
+  def call!(param1:, param2:)
+    Success(:ok)
+  end
+end
+```
+
+or use the shortcut for defining attributes:
+```ruby
+class MyOperation < Fluxo::Operation(:param1, :param2)
+  def call!(param1:, param2:)
+    Success(:ok)
+  end
+end
+```
+
+### Operation Result
+
+The execution result of an operation is a `Fluxo::Result` object. There are three types of results:
+* `:ok`: the operation was successful
+* `:failure`: the operation failed
+* `:exception`: the operation raised an error
+
+Use the `Success` and `Failure` methods to create results accordingly.
+
+```ruby
+class AgeCheckOperation < Fluxo::Operation(:age)
+  def call!(age:)
+    age >= 18 ? Success('ok') : Failure('too young')
+  end
+end
+
+result = AgeCheckOperation.call(age: 16) # #<Fluxo::Result @value="too young", @type=:failure>
+result.success?                          # false
+result.error?                            # false
+result.failure?                          # true
+result.value                             # "too young"
+
+result = AgeCheckOperation.call(age: 18) # #<Fluxo::Result @value="ok", @type=:ok>
+result.success?                          # true
+result.error?                            # false
+result.failure?                          # false
+result.value                             # "ok"
+```
+
+The `result` also provides `on_success`, `on_failure` and `on_error` methods to define callbacks for the `:ok` and `:failure` results.
+
+```ruby
+AgeCheckOperation.call(age: 18)
+  .on_success { |result| puts result.value }
+  .on_failure { |_result| puts "Sorry, you are too young" }
+```
+
+You can also define multiple callbacks for the opportunity result. The callbacks are executed in the order they were defined. You can filter which callbacks are executed by specifying an identifier to the `Success(id) { }` or `Failure(id) { }` methods along with its value as a block.
+
+```ruby
+class AgeCategoriesOperation < Fluxo::Operation(:age)
+  def call!(age:)
+    case age
+    when 0..14
+      Failure(:child) { "Sorry, you are too young" }
+    when 15..17
+      Failure(:teenager) { "You are a teenager" }
+    when 18..65
+      Success(:adult) { "You are an adult" }
+    else
+      Success(:senior) { "You are a senior" }
+    end
+  end
+end
+
+AgeCategoriesOperation.call(age: 18) \
+  .on_success { |_result| puts "Great, you are an adult" } \
+  .on_success(:senior) { |_result| puts "Enjoy your retirement" } \
+  .on_success(:adult, :senior) { |_result| puts "Allowed access" } \
+  .on_failure { |_result| puts "Sorry, you are too young" } \
+  .on_failure(:teenager) { |_result| puts "Almost there, you are a teenager" }
+# The above example will print:
+#   Great, you are an adult
+#   Allowed access
+```
+
+### Operation Flow
+
+Once things become more complex, you can use can define a `flow` with a list of steps to be executed:
+
+```ruby
+class ArithmeticOperation < Fluxo::Operation(:num)
+  flow :normalize, :plus_one, :double, :square, :wrap
+
+  def normalize(num:)
+    Success(num: num.to_i)
+  end
+
+  def plus_one(num:)
+    return Failure('cannot be zero') if num == 0
+
+    Success(num: num + 1)
+  end
+
+  def double(num:)
+    Success(num: num * 2)
+  end
+
+  def square(num:)
+    Success(num: num * num)
+  end
+
+  def wrap(num:)
+    Success(num)
+  end
+end
+
+ArithmeticOperation.call(num: 1) \
+  .on_success { |result| puts "Result: #{result.value}" }
+# Result: 16
+```
+
+Notice that the value of each step is passed to the next step as an argument. And the last step is always the result of the operation.
+
+By default you can only pass defined attributes to the steps. You may want to pass transient attributes to the steps. You can do this by specifying a `transient_attributes` option to the operation class:
+
+```ruby
+class CreateUserOperation < Fluxo::Operation(:name, :age)
+  flow :build, :save
+
+  def build(name:, age:)
+    user = User.new(name: name, age: age)
+    Success(user: user)
+  end
+
+  def save(user:, **)
+    return Failure(user.errors) unless user.save
+
+    Success(user: user)
+  end
+end
+```
+
+This is useful to make the flow data transparent to the operation. But you can also disable this by setting the `strict_transient_attributes` option to `false` under the Operation class or the global configuration.
+
+```ruby
+class CreateUserOperation < Fluxo::Operation(:name, :age)
+  self.strict_transient_attributes = false
+  # ...
+end
+# or globally
+Fluxo.config do |config|
+  config.strict_attributes = false
+  config.strict_transient_attributes = false
+end
+# or even
+Fluxo.config.strict_transient_attributes = false
+```
+
+### Operation Groups
+
+Another very useful feature of Fluxo is the ability to group operations steps. Imagine that you want to execute a bunch of operations in a single transaction. You can do this by defining a the group method and specifying the steps to be executed in the group.
+
+```ruby
+class CreateUserOperation < Fluxo::Operation(:name, :email)
+  transient_attributes :user, :profile
+
+  flow :build, {transaction: %i[save_user save_profile]}, :enqueue_job
+
+  private
+
+  def transaction(**kwargs, &block)
+    ActiveRecord::Base.transaction do
+      result = block.call(**kwargs)
+      raise(ActiveRecord::Rollback) unless result.success?
+    end
+    result
+  end
+
+  def build(name:, email:)
+    user = User.new(name: name, email: email)
+    Success(user: user)
+  end
+
+  def save_user(user:, **)
+    return Failure(user.errors) unless user.save
+
+    Success(user: user)
+  end
+
+  def save_profile(user:, **)
+    UserProfile.create!(user: user)
+    Success()
+  end
+
+  def enqueue_job(user:, **)
+    UserJob.perform_later(user.id)
+
+    Success(user)
+  end
+end
+```
+
+### Configuration
+
+```ruby
+Fluxo.config do |config|
+  config.wrap_falsey_result = false
+  config.wrap_truthy_result = false
+  config.strict_attributes = true
+  config.strict_transient_attributes = true
+  config.error_handlers << ->(result) { Honeybadger.notify(result.value) }
+end
+```
+
 
 ## Development
 

data/fluxo.gemspec

@@ -7,7 +7,8 @@ Gem::Specification.new do |spec|
   spec.email = ["mgzmaster@gmail.com"]
 
   spec.summary = "Simple Ruby DSL to create operation service objects."
-  spec.description = "Simple Ruby DSL to create operation service objects"
+  spec.description = "Provides a simple and powerful way to create operations service objects for complex workflows."
+
   spec.homepage = "https://github.com/marcosgz/fluxo"
   spec.license = "MIT"
   spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")

data/lib/fluxo/config.rb

@@ -17,17 +17,17 @@ module Fluxo
     attr_accessor :wrap_truthy_result
 
     # When set to true, the operation will not validate the transient_attributes defition during the flow step execution.
-    attr_accessor :sloppy_transient_attributes
+    attr_accessor :strict_transient_attributes
 
     # When set to true, the operation will not validate attributes definition before calling the operation.
-    attr_accessor :sloppy_attributes
+    attr_accessor :strict_attributes
 
     def initialize
       @error_handlers = []
       @wrap_falsey_result = false
       @wrap_truthy_result = false
-      @sloppy_transient_attributes = false
-      @sloppy_attributes = false
+      @strict_transient_attributes = true
+      @strict_attributes = true
     end
   end
 end

data/lib/fluxo/operation/attributes.rb

@@ -11,21 +11,21 @@ module Fluxo
         attr_reader :validations_proxy
 
         # When set to true, the operation will not validate the transient_attributes defition during the flow step execution.
-        attr_writer :sloppy_transient_attributes
+        attr_writer :strict_transient_attributes
 
         # When set to true, the operation will not validate attributes definition before calling the operation.
-        attr_writer :sloppy_attributes
+        attr_writer :strict_attributes
 
-        def sloppy_attributes?
-          return @sloppy_attributes if defined?(@sloppy_attributes)
+        def strict_attributes?
+          return @strict_attributes if defined?(@strict_attributes)
 
-          Fluxo.config.sloppy_attributes
+          Fluxo.config.strict_attributes
         end
 
-        def sloppy_transient_attributes?
-          return @sloppy_transient_attributes if defined?(@sloppy_transient_attributes)
+        def strict_transient_attributes?
+          return @strict_transient_attributes if defined?(@strict_transient_attributes)
 
-          Fluxo.config.sloppy_transient_attributes
+          Fluxo.config.strict_transient_attributes
         end
 
         def validations

data/lib/fluxo/operation.rb

@@ -4,6 +4,8 @@ require_relative "operation/constructor"
 require_relative "operation/attributes"
 
 module Fluxo
+  # I know that the underline instance method name is not the best, but I don't want to
+  # conflict with the Operation step methods that are going to inherit this class.
   class Operation
     include Attributes
     include Constructor
@@ -40,13 +42,24 @@ module Fluxo
     # Calls step-method by step-method always passing the value to the next step
     # If one of the methods is a failure stop the execution and return a result.
     def __execute_flow__(steps: [], attributes: {})
-      transient_attributes = attributes.dup
+      transient_attributes, transient_ids = attributes.dup, {ok: [], failure: [], exception: []}
       __validate_attributes__(first_step: steps.first, attributes: transient_attributes)
 
       result = nil
       steps.unshift(:__validate__) if self.class.validations_proxy # add validate step before the first step
       steps.each_with_index do |step, idx|
-        result = __wrap_result__(send(step, **transient_attributes))
+        if step.is_a?(Hash)
+          step.each do |group_method, group_steps|
+            send(group_method, **transient_attributes) do |group_attrs|
+              result = __execute_flow__(steps: group_steps, attributes: (group_attrs || transient_attributes))
+            end
+            break unless result.success?
+          end
+        else
+          result = __wrap_result__(send(step, **transient_attributes))
+          transient_ids.fetch(result.type).push(*result.ids)
+        end
+
         break unless result.success?
 
         if steps[idx + 1]
@@ -57,7 +70,7 @@ module Fluxo
           )
         end
       end
-      result
+      result.tap { |r| r.ids = transient_ids.fetch(r.type).uniq }
     end
 
     # @param value_or_result_id [Any] The value for the result or the id when the result comes from block
@@ -90,47 +103,82 @@ module Fluxo
 
     private
 
+    # Validates the operation was called with all the required keyword arguments.
+    # @param first_step [Symbol, Hash] The first step method
+    # @param attributes [Hash] The attributes to validate
+    # @return [void]
+    # @raise [MissingAttributeError] When a required attribute is missing
     def __validate_attributes__(attributes:, first_step:)
-      if !self.class.sloppy_attributes? && (extra = attributes.keys - self.class.attribute_names).any?
+      if self.class.strict_attributes? && (extra = attributes.keys - self.class.attribute_names).any?
         raise NotDefinedAttributeError, <<~ERROR
           The following attributes are not defined: #{extra.join(", ")}
 
           You can use the #{self.class.name}.attributes method to specify list of allowed attributes.
-          Or you can disable strict attributes mode by setting the sloppy_attributes to true.
+          Or you can disable strict attributes mode by setting the strict_attributes to true.
         ERROR
       end
 
-      method(first_step).parameters.select { |type, _| type == :keyreq }.each do |(_type, name)|
-        raise(MissingAttributeError, "Missing :#{name} attribute on #{self.class.name}#{first_step} step method.") unless attributes.key?(name)
+      __expand_step_method__(first_step).each do |step|
+        method(step).parameters.select { |type, _| type == :keyreq }.each do |(_type, name)|
+          raise(MissingAttributeError, "Missing :#{name} attribute on #{self.class.name}#{step} step method.") unless attributes.key?(name)
+        end
       end
     end
 
+    # Merge the result attributes with the new attributes. Also checks if the upcomming step
+    # has the required attributes and transient attributes to a valid execution.
+    # @param new_attributes [Hash] The new attributes
+    # @param old_attributes [Hash] The old attributes
+    # @param next_step [Symbol, Hash] The next step method
     def __merge_result_attributes__(new_attributes:, old_attributes:, next_step:)
       return old_attributes unless new_attributes.is_a?(Hash)
 
       attributes = old_attributes.merge(new_attributes)
       allowed_attrs = self.class.attribute_names + self.class.transient_attribute_names
-      if !self.class.sloppy_transient_attributes? &&
+      if self.class.strict_transient_attributes? &&
           (extra = attributes.keys - allowed_attrs).any?
         raise NotDefinedAttributeError, <<~ERROR
           The following transient attributes are not defined: #{extra.join(", ")}
 
           You can use the #{self.class.name}.transient_attributes method to specify list of allowed attributes.
-          Or you can disable strict transient attributes mode by setting the sloppy_transient_attributes to true.
+          Or you can disable strict transient attributes mode by setting the strict_transient_attributes to true.
         ERROR
       end
 
-      method(next_step).parameters.select { |type, _| type == :keyreq }.each do |(_type, name)|
-        raise(MissingAttributeError, "Missing :#{name} transient attribute on #{self.class.name}##{next_step} step method.") unless attributes.key?(name)
+      __expand_step_method__(next_step).each do |step|
+        method(step).parameters.select { |type, _| type == :keyreq }.each do |(_type, name)|
+          raise(MissingAttributeError, "Missing :#{name} transient attribute on #{self.class.name}##{step} step method.") unless attributes.key?(name)
+        end
       end
 
       attributes
     end
 
+    # Return the step method as an array. When it's a hash it suppose to be a
+    # be a step group. In this case return its first key and its first value as
+    # the array of step methods.
+    #
+    # @param step [Symbol, Hash] The step method name
+    def __expand_step_method__(step)
+      return [step] unless step.is_a?(Hash)
+
+      key, value = step.first
+      [key, Array(value).first].compact
+    end
+
+    # Execute active_model validation as a flow step.
+    # @param attributes [Hash] The attributes to validate
+    # @return [Fluxo::Result] The result of the validation
     def __validate__(**attributes)
       self.class.validations_proxy.validate!(self, **attributes)
     end
 
+    # Wrap the step method result in a Fluxo::Result object.
+    #
+    # @param result [Fluxo::Result, *Object] The object to wrap
+    # @raise [Fluxo::InvalidResultError] When the result is not a Fluxo::Result config
+    #  is set to not wrap results.
+    # @return [Fluxo::Result] The wrapped result
     def __wrap_result__(result)
       if result.is_a?(Fluxo::Result)
         return result

data/lib/fluxo/result.rb

@@ -2,7 +2,8 @@
 
 module Fluxo
   class Result
-    attr_reader :operation, :type, :value, :ids
+    attr_reader :operation, :type, :value
+    attr_accessor :ids
 
     # @param options [Hash]
     # @option options [Fluxo::Operation] :operation The operation instance that gererated this result
@@ -31,16 +32,16 @@ module Fluxo
       type == :exception
     end
 
-    def on_success(handler_id = nil)
-      tap { yield(self) if success? && (handler_id.nil? || ids.include?(handler_id)) }
+    def on_success(*handler_ids)
+      tap { yield(self) if success? && (handler_ids.none? || (ids & handler_ids).any?) }
     end
 
-    def on_failure(handler_id = nil)
-      tap { yield(self) if failure? && (handler_id.nil? || ids.include?(handler_id)) }
+    def on_failure(*handler_ids)
+      tap { yield(self) if failure? && (handler_ids.none? || (ids & handler_ids).any?) }
     end
 
-    def on_error(handler_id = nil)
-      tap { yield(self) if error? && (handler_id.nil? || ids.include?(handler_id)) }
+    def on_error(*handler_ids)
+      tap { yield(self) if error? && (handler_ids.none? || (ids & handler_ids).any?) }
     end
   end
 end

data/lib/fluxo/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Fluxo
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fluxo
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Marcos G. Zimmermann
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-01-14 00:00:00.000000000 Z
+date: 2022-01-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: standard
@@ -52,7 +52,8 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: Simple Ruby DSL to create operation service objects
+description: Provides a simple and powerful way to create operations service objects
+  for complex workflows.
 email:
 - mgzmaster@gmail.com
 executables: []