much-result 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f4805f13dbc5498186070c28c422564440a511d0b9e4af9f695802b969e3f7da
+  data.tar.gz: 811cb65cfb9bb197329e06b44ce7511daab25adc9bbdbcd1610d307c2f1b4cb3
+SHA512:
+  metadata.gz: 2e3a53796159c10e8b8e05ab1afd862cdbc77bc0eb729d3874808f731ae8f82a69f71479fb3664dffc3cb69c0bc4a815a9e29f1c1ed5c4ba1f71b584bdd29377
+  data.tar.gz: 77b2ac454e76ba063bc3ff2812a063caafe776d42e0875f111fa17868d58a1716f0ced1e423bb045f723250e5f6e72f11f3bc5acd2cd3db89cff3b4e77e704ba

data/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+ruby "~> 2.5"
+
+gemspec
+
+gem "pry", "~> 0.12.2"

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2020-Present Kelly Redding and Collin Redding
+
+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,233 @@
+# MuchResult
+
+API for managing the results of operations.
+
+## Usage
+
+Have services/methods return a MuchResult based on the whether an exception was raised or not:
+
+```ruby
+class PerformSomeOperation
+  def self.call
+    # Do something that could fail by raising an exception.
+    MuchResult.success(message: "it worked!")
+  rescue => exception
+    MuchResult.failure(exception: exception)
+  end
+end
+
+result = PerformSomeOperation.call
+
+result.success?    # => true
+result.failure?    # => false
+result.message     # => "it worked!"
+result.sub_results # => []
+```
+
+Have services/methods return a MuchResult based on a result value (i.e. "truthy" = success; "false-y" = failure):
+
+```ruby
+def perform_some_operation(success:)
+  # Do something that could fail.
+  MuchResult.for(success, message: "it ran :shrug:")
+end
+
+result = perform_some_operation(success: true)
+result.success? # => true
+result.failure? # => false
+result.message  # => "it ran :shrug:"
+
+result = perform_some_operation(success: false)
+result.success? # => false
+result.failure? # => true
+result.message  # => "it ran :shrug:"
+
+result = perform_some_operation(success: nil)
+result.success? # => false
+result.failure? # => true
+result.message  # => "it ran :shrug:"
+```
+
+Set arbitrary values on MuchResults before or after they are created:
+
+```ruby
+result = MuchResult.success(message: "it worked!")
+result.set(
+  other_value1: "something else 1",
+  other_value2: "something else 2"
+)
+result.message      # => "it worked!"
+result.other_value1 # => "something else 1"
+result.other_value2 # => "something else 2"
+```
+
+### Capture sub-Results
+
+Capture MuchResults for sub-operations into a parent MuchResult:
+
+```ruby
+class PerformSomeOperation
+  def self.call
+    MuchResult.tap(description: "Do both parts") { |result|
+      result          # => <MuchResult ...>
+      result.success? # => true
+
+      result.capture { do_part_1 }
+      # OR you can use `capture_all` to capture from an Array of MuchResults
+
+      # raise an Exception if failure
+      result.capture! { do_part_2 }
+      # OR you can use `capture_all!` to capture from an Array of MuchResults
+
+      # set some arbitrary values b/c it worked.
+      result.set(message: "it worked!")
+    } # => result
+  end
+
+  def self.do_part_1
+    MuchResult.failure(description: "Part 1")
+  end
+
+  def self.do_part_2
+    MuchResult.success(description: "Part 2")
+  end
+end
+
+result = PerformSomeOperation.call
+
+result.success? # => true
+result.message  # => "it worked!"
+
+# Get just the immediate sub-results that were captured for the MuchResult.
+result.sub_results # => [<MuchResult Part 1>, <MuchResult Part 2>]
+
+# Get all MuchResults that make up this MuchResult (including those captured
+# on all recursive sub-results).
+result.all_results # => [result, <MuchResult Part 1>, <MuchResult Part 2>]
+
+# Get aggregated values for each MuchResult that makes up this MuchResult.
+result.get_for_sub_results(:description)
+# => ["Part 1", "Part 2"]
+result.get_for_success_sub_results(:description)
+# => ["Part 2"]
+result.get_for_failure_sub_results(:description)
+# => ["Part 1"]
+
+result.get_for_all_results(:description)
+# => ["Do both parts", "Part 1", "Part 2"]
+result.get_for_all_success_results(:description)
+# => ["Part 2"]
+result.get_for_all_failure_results(:description)
+# => ["Do both parts", "Part 1"]
+```
+
+### Transactions
+
+Run transactions capturing sub-Results:
+
+```ruby
+class PerformSomeOperation
+  def self.call
+    MuchResult.transaction(
+      ActiveRecord::Base,
+      value: "something",
+      description: "Do both parts"
+    ) { |transaction|
+      transaction        # => <MuchResult::Transaction ...>
+      transaction.result # => <MuchResult ...>
+
+      # You can interact with a transaction as if it were a MuchResult.
+      transaction.value    # => "something"
+      transaction.success? # => true
+
+      transaction.capture { do_part_1 }
+      # OR you can use `capture_all` to capture from an Array of MuchResults
+
+      # raise an Exception if failure (which will rollback the transaction)
+      transaction.capture! { do_part_2 }
+      # OR you can use `capture_all!` to capture from an Array of MuchResults
+
+      # manually rollback the transaction if needed
+      # (stops processing and doesn't commit the transaction)
+      transaction.rollback if rollback_needed?
+
+      # manually halt the transaction if needed
+      # (stops processing and commits the transaction)
+      transaction.halt if halt_needed?
+
+      # set some arbitrary values b/c it worked.
+      transaction.set(message: "it worked!")
+    } # => transaction.result
+  end
+
+  def self.do_part_1
+    MuchResult.failure(description: "Part 1")
+  end
+
+  def self.do_part_2
+    MuchResult.success(description: "Part 2")
+  end
+
+  def rollback_needed?
+    false
+  end
+
+  def halt_needed?
+    false
+  end
+end
+
+result = PerformSomeOperation.call
+
+result.success? # => true
+result.message  # => "it worked!"
+
+result.much_result_transaction_rolled_back # => false
+result.much_result_transaction_halted      # => false
+
+# Get just the immediate sub-results that were captured for the MuchResult.
+result.sub_results # => [<MuchResult Part 1>, <MuchResult Part 2>]
+
+# Get all MuchResults that make up this MuchResult (including those captured
+# on all recursive sub-results).
+result.all_results # => [result, <MuchResult Part 1>, <MuchResult Part 2>]
+
+# Get aggregated values for each MuchResult that makes up this MuchResult.
+result.get_for_sub_results(:description)
+# => ["Part 1", "Part 2"]
+result.get_for_success_sub_results(:description)
+# => ["Part 2"]
+result.get_for_failure_sub_results(:description)
+# => ["Part 1"]
+
+result.get_for_all_results(:description)
+# => ["Do both parts", "Part 1", "Part 2"]
+result.get_for_all_success_results(:description)
+# => ["Part 2"]
+result.get_for_all_failure_results(:description)
+# => ["Do both parts", "Part 1"]
+```
+
+Note: MuchResult::Transactions are designed to delegate to their MuchResult. You can interact with a MuchResult::Transaction as if it were a MuchResult.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem "much-result"
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install much-result
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am "Added some feature"`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/lib/much-result.rb

@@ -0,0 +1,205 @@
+require "much-result/version"
+require "much-result/aggregate"
+require "much-result/transaction"
+
+class MuchResult
+  SUCCESS = "success".freeze
+  FAILURE = "failure".freeze
+
+  Error    = Class.new(StandardError)
+  Rollback = Class.new(RuntimeError)
+
+  def self.success(backtrace: caller, **kargs)
+    new(MuchResult::SUCCESS, **kargs, backtrace: backtrace)
+  end
+
+  def self.failure(backtrace: caller, **kargs)
+    new(MuchResult::FAILURE, **kargs, backtrace: backtrace)
+  end
+
+  def self.for(value, backtrace: caller, **kargs)
+    if value.respond_to?(:to_much_result)
+      return value.to_much_result(**kargs, backtrace: backtrace)
+    end
+
+    new(
+      !!value ? MuchResult::SUCCESS : MuchResult::FAILURE,
+      **kargs,
+      backtrace: backtrace
+    )
+  end
+
+  def self.tap(backtrace: caller, **kargs)
+    success(backtrace: backtrace, **kargs).tap { |result|
+      yield result if block_given?
+    }
+  end
+
+  def self.transaction(receiver, backtrace: caller, **kargs, &block)
+    MuchResult::Transaction.call(receiver, backtrace: backtrace, **kargs, &block)
+  end
+
+  attr_reader :sub_results, :description, :backtrace
+
+  def initialize(result_value, description: nil, backtrace: caller, **kargs)
+    @result_value = result_value
+    @description  = description
+    @backtrace    = backtrace
+
+    set(**kargs)
+
+    @sub_results = []
+    reset_sub_results_cache
+  end
+
+  def set(**kargs)
+    @data = ::OpenStruct.new((@data || {}).to_h.merge(**kargs))
+    self
+  end
+
+  def success?
+    if @success_predicate.nil?
+      @success_predicate =
+        @sub_results.reduce(@result_value == MuchResult::SUCCESS) { |acc, result|
+          acc && result.success?
+        }
+    end
+
+    @success_predicate
+  end
+
+  def failure?
+    !success?
+  end
+
+  def capture_for(value, backtrace: caller, **kargs)
+    self.class.for(value, backtrace: backtrace, **kargs).tap { |result|
+      @sub_results.push(result)
+      reset_sub_results_cache
+    }
+  end
+
+  def capture_for!(value, backtrace:caller, **kargs)
+    capture_for(value, **kargs, backtrace: backtrace).tap { |result|
+      raise(result.capture_exception) if result.failure?
+    }
+  end
+
+  def capture_for_all(values, backtrace: caller, **kargs)
+    [*values].map { |value| capture_for(value, **kargs, backtrace: backtrace) }
+  end
+
+  def capture_for_all!(values, backtrace: caller, **kargs, &block)
+    capture_for_all(values, **kargs, backtrace: backtrace).tap { |results|
+      if (first_failure_result = results.detect(&:failure?))
+        raise(first_failure_result.capture_exception)
+      end
+    }
+  end
+
+  def capture(backtrace: caller, **kargs)
+    capture_for((yield if block_given?), **kargs, backtrace: backtrace)
+  end
+
+  def capture!(backtrace: caller, **kargs, &block)
+    capture_for!((yield if block_given?), **kargs, backtrace: backtrace)
+  end
+
+  def capture_all(backtrace: caller, **kargs)
+    capture_for_all((yield if block_given?), **kargs, backtrace: backtrace)
+  end
+
+  def capture_all!(backtrace: caller, **kargs, &block)
+    capture_for_all!((yield if block_given?), **kargs, backtrace: backtrace)
+  end
+
+  # Prefer any `#exception` set on the data. Fallback to building an exception
+  # from the description/backtrace of the result.
+  def capture_exception
+    @data.exception || build_default_capture_exception
+  end
+
+  def success_sub_results
+    @success_sub_results ||= @sub_results.select { |result| result.success? }
+  end
+
+  def failure_sub_results
+    @failure_sub_results ||= @sub_results.select { |result| result.failure? }
+  end
+
+  def all_results
+    @all_results ||=
+      [self] +
+      @sub_results.flat_map { |result| result.all_results }
+  end
+
+  def all_success_results
+    @all_success_results ||=
+      [*(self if success?)] +
+      @sub_results.flat_map { |result| result.all_success_results }
+  end
+
+  def all_failure_results
+    @all_failure_results ||=
+      [*(self if failure?)] +
+      @sub_results.flat_map { |result| result.all_failure_results }
+  end
+
+  def get_for_sub_results(attribute_name)
+    MuchResult::Aggregate.(sub_results.map(&attribute_name.to_sym))
+  end
+
+  def get_for_success_sub_results(attribute_name)
+    MuchResult::Aggregate.(success_sub_results.map(&attribute_name.to_sym))
+  end
+
+  def get_for_failure_sub_results(attribute_name)
+    MuchResult::Aggregate.(failure_sub_results.map(&attribute_name.to_sym))
+  end
+
+  def get_for_all_results(attribute_name)
+    MuchResult::Aggregate.(all_results.map(&attribute_name.to_sym))
+  end
+
+  def get_for_all_success_results(attribute_name)
+    MuchResult::Aggregate.(all_success_results.map(&attribute_name.to_sym))
+  end
+
+  def get_for_all_failure_results(attribute_name)
+    MuchResult::Aggregate.(all_failure_results.map(&attribute_name.to_sym))
+  end
+
+  def to_much_result(backtrace: caller, **kargs)
+    self.set(**kargs)
+  end
+
+  def inspect
+    "#<#{self.class}:#{"0x0%x" % (object_id << 1)} "\
+      "#{success? ? "SUCCESS" : "FAILURE"} "\
+      "#{"@description=#{@description.inspect} " if @description}"\
+      "@sub_results=#{@sub_results.inspect}>"
+  end
+
+  private
+
+  def build_default_capture_exception
+    Error.new(description).tap { |exception| exception.set_backtrace(backtrace) }
+  end
+
+  def reset_sub_results_cache
+    @success_predicate = nil
+    @success_sub_results = nil
+    @failure_sub_results = nil
+    @all_results = nil
+    @all_success_results = nil
+    @all_failure_results = nil
+  end
+
+  def respond_to_missing?(*args)
+    @data.send(:respond_to_missing?, *args)
+  end
+
+  def method_missing(method, *args, &block)
+    @data.public_send(method, *args, &block)
+  end
+end