action_logic 0.2.4 → 0.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: fb4115622aa03370f1c78ca57d8c45670d2c52bf
-  data.tar.gz: f1687c7f429d52c51369d91814cde3927a3eadd2
+  metadata.gz: c66d180782e1862be0377d7fe898882aa0ade055
+  data.tar.gz: 888830e3f75532ca8f4478d408a50c44598b0f06
 SHA512:
-  metadata.gz: 65e4f68bd7c54c1a838fdd81f399c9031c25a1409c423ad622d68203cbde71532f27b6df86a2c50437d6c0d23d360938df536b6593c550ce4580ea3302ac1054
-  data.tar.gz: 453fa766e4778a577fcea58ffdfc2c59b8fb256ca42322136874926f1f5bf56748aa9fc79998edbbaff6eec696c7e942e91d6b3e6034d7c13c3ca72580b5d171
+  metadata.gz: a74659bc15c3f9d9269954cdf222f03bf33d10a0164ca11a76494e4d94ea508b8659d0c89f9fc344b374b56dd05de4b96e5377894f67644c0cc20a8530745cc2
+  data.tar.gz: 8178b2136a5c4855fb3f50318f97c1645f551d269e129b7b147d57a4c37919cd077edd9187c70bf85148969ae277d7e1e4d70b9e83db1b4356bbf50c78523509

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    action_logic (0.2.3)
+    action_logic (0.2.4)
 
 GEM
   remote: https://rubygems.org/

data/README.md

@@ -32,6 +32,11 @@ Why another business logic abstraction gem? `ActionLogic` provides teams of vari
 * [Before Validations](#before-validations)
 * [After Validations](#after-validations)
 * [Around Validations](#around-validations)
+* [Benchmarking](#benchmarking)
+	* [Enable Benchmarking](#enable-benchmarking)
+	* [Benchmark Logging](#benchmark-logging)
+	* [Benchark Log Formatting](#benchmark-log-formatting)
+	* [Custom Benchmark Handling](#custom-benchmark-handling)
 
 ### Backstory
 
@@ -925,3 +930,120 @@ result = ActionTaskExample.execute(:example_attribute => [1, 2, 3], :example_att
 
 result # => #<ActionLogic::ActionContext example_attribute=[1, 2, 3], example_attribute2=1, status=:success>
 ```
+
+### Benchmarking
+
+At some point you may want to benchmark and profile the performance of your code. `ActionLogic` allows for benchmarking that
+range from simple defaults to highly customizable options depending on your use case and needs.
+
+### Enable Benchmarking
+
+Because benchmarking negatively impacts performance, we must explicitly tell `ActionLogic` that we want to benchmark (otherwise
+it defaults to ignore benchmarking). To do this, we configure `ActionLogic` using the `configure` method. With the provided
+`config` object, we explicitly enable benchmarking by setting `config.benchmark = true`:
+
+```ruby
+ActionLogic.configure do |config|
+  config.benchmark = true
+end
+```
+
+### Benchmark Logging
+
+Additionally, `ActionLogic` writes a benchmark log to `$stdout` by default, or you can override this default configuration
+by specifying a log file. To do this, you configure `ActionLogic` to use a `File` object for logging benchmark results via the
+`ActionLogic.configure` method:
+
+```ruby
+ActionLogic.configure do |config|
+  config.benchmark = true
+	config.benchmark_log = File.open("benchmark.log", "w")
+end
+```
+
+### Benchmark Log Formatting
+
+By default, `ActionLogic` formats benchmark logs in the following format:
+
+```
+context:ValidateAroundPresenceTestUseCase user_time:0.000000 system_time:0.000000 total_time:0.000000 real_time:0.000135
+...
+```
+
+The default format is intended to be machine readable for easy parsing and is not intended to be used for human reading.
+However, if you wish to change the format of the log output, `ActionLogic` allows you to override the default formatter by
+allowing you to provide your own formatter:
+
+```ruby
+ActionLogic.configure do |config|
+  config.benchmark = true
+	config.benchmark_log = File.open("benchmark.log", "w")
+	config.benchmark_formatter = YourCustomFormatter
+end
+```
+
+Where `YourCustomFormatter` subclasses `ActionLogic::ActionBenchmark::DefaultFormatter`:
+
+```ruby
+class CustomFormatter < ActionLogic::ActionBenchmark::DefaultFormatter
+
+  def log_coordinator(benchmark_result, execution_context_name)
+		benchmark_log.puts("The ActionCoordinator #{execution_context_name} took #{benchmark_result.real} to complete.")
+  end
+
+  def log_use_case(benchmark_result, execution_context_name)
+		benchmark_log.puts("The ActionUseCase #{execution_context_name} took #{benchmark_result.real} to complete.")
+  end
+
+  def log_task(benchmark_result, execution_context_name)
+		benchmark_log.puts("The ActionTask #{execution_context_name} took #{benchmark_result.real} to complete.")
+  end
+
+end
+```
+
+From the example above, you can see that a custom formatter is required to define three methods: `log_coordinator`, `log_use_case` and `log_task`. The `log_t cqcoordinator`
+method is called when a `ActionCoordinator` context is benchmarked. The `use_case` and `task` methods are invoked when `ActionUseCase` and `ActionTask`
+contexts are benchmarked, respectively.
+
+Each of the three log methods receives two input parameters: `benchmark_result` and `execution_context_name` where `benchmark_result` is a Ruby
+standard library `Benchmark` result object, and `execution_context_name` is the class name of the `ActionLogic` context.
+
+Once configured, you can verify that the formatter outputs to the specified log file by executing your `ActionLogic` contexts
+and verifying that the log file is written to with the correct format:
+
+```
+The ActionUseCase TestUseCase2 took 0.00011722202179953456 to complete.
+The ActionTask TestTask3 took 4.570698365569115e-05 to complete.
+...
+```
+
+### Custom Benchmark Handling
+
+By default, `ActionLogic` benchmarks execution contexts using Ruby's `Benchmark` module. If you are content with a `Benchmark` result object, then
+you do not need to specify a custom benchmark handler. However, if you wish to have maximum control, or you require something different than Ruby's
+`Benchmark` module, you can define a custom handler like so:
+
+```ruby
+class CustomHandler
+  def call
+    # custom logic
+    yield
+    # custom logic
+  end
+end
+```
+
+Your custom handler is free to define any custom logic, but you must yield during the body of the `call` method. This is what triggers the execution
+context and will allow your custom handler to measure the length of execution. If you do not yield, the relevant `ActionCoordinator`, `ActionUseCase`
+or `ActionTask` will not be executed and will result in no execution to benchmark.
+
+Additionally, you must register your custom handler with `ActionLogic` using `ActionLogic.configure`:
+
+```ruby
+ActionLogic.configure do |config|
+  config.benchmark = true
+  config.benchmark_log = File.open("benchmark.log", "w")
+  config.benchmark_handler = CustomHandler.new
+end
+```

data/lib/action_logic.rb

@@ -1,4 +1,3 @@
-require 'action_logic/action_configuration'
 require 'action_logic/action_context'
 require 'action_logic/action_coordinator'
 require 'action_logic/action_core'
@@ -7,6 +6,8 @@ require 'action_logic/action_use_case'
 require 'action_logic/action_validation'
 require 'action_logic/action_benchmark'
 require 'action_logic/action_benchmark/default_formatter'
+require 'action_logic/action_benchmark/default_benchmark_block'
 
+require 'action_logic/configuration'
 require 'action_logic/errors'
 require 'action_logic/version'

data/lib/action_logic/action_benchmark.rb

@@ -1,38 +1,25 @@
-require 'benchmark'
-
 module ActionLogic
   module ActionBenchmark
-
     module ClassMethods
       def with_benchmark(execution_context, &block)
-        if benchmark?
-          benchmark_result, context = benchmark!(&block)
-          log!(benchmark_result, execution_context)
-          context
-        else
-          block.call
-        end
+        ActionLogic.benchmark? ? benchmark!(execution_context, &block) : block.call
       end
 
       private
 
-      def benchmark?
-        ActionConfiguration.benchmark?
-      end
-
-      def benchmark!(&block)
+      def benchmark!(execution_context, &block)
         context = nil
-        benchmark_result  = Benchmark.measure { context = block.call }
-        [benchmark_result, context]
+        benchmark_result  = ActionLogic.benchmark_handler.call { context = block.call }
+        log!(benchmark_result, execution_context)
+        context
       end
 
       def log!(benchmark_result, execution_context)
-        benchmark_formatter.send(execution_context.__private__type, benchmark_result, execution_context.name)
+        ActionLogic.benchmark_formatter.send("log_#{execution_context.__private__type}".to_sym,
+                                             benchmark_result,
+                                             execution_context.name)
       end
 
-      def benchmark_formatter
-        ActionConfiguration.benchmark_formatter
-      end
     end
   end
 end

data/lib/action_logic/action_benchmark/default_benchmark_block.rb

@@ -0,0 +1,11 @@
+require 'benchmark'
+
+module ActionLogic
+  module ActionBenchmark
+    class DefaultBenchmarkHandler
+      def call
+        Benchmark.measure { yield }
+      end
+    end
+  end
+end

data/lib/action_logic/action_benchmark/default_formatter.rb

@@ -1,12 +1,12 @@
 module ActionLogic
   module ActionBenchmark
     class DefaultFormatter
-      def initialize(benchmark_log: ActionConfiguration.benchmark_log)
+      def initialize(benchmark_log: ActionLogic.benchmark_log)
         @benchmark_log = benchmark_log
       end
 
       def format(benchmark_result, context_name)
-        benchmark_log.printf("%-10s %-50s %-10s %-10f %-10s %-10f %-10s %-10f %-10s %-10f\n",
+        benchmark_log.printf("%s%s %s%f %s%f %s%f %s%f\n",
                              "context:",
                              context_name,
                              "user_time:",
@@ -19,9 +19,9 @@ module ActionLogic
                              benchmark_result.real)
       end
 
-      alias_method :coordinator, :format
-      alias_method :use_case, :format
-      alias_method :task, :format
+      alias_method :log_coordinator, :format
+      alias_method :log_use_case, :format
+      alias_method :log_task, :format
 
       private
       attr_reader :benchmark_log

data/lib/action_logic/action_coordinator.rb

@@ -35,7 +35,7 @@ module ActionLogic
       end
 
       def __private__type
-        :coordinator
+        "coordinator"
       end
     end
   end

data/lib/action_logic/action_task.rb

@@ -17,7 +17,7 @@ module ActionLogic
       end
 
       def __private__type
-        :task
+        "task"
       end
     end
   end

data/lib/action_logic/action_use_case.rb

@@ -23,7 +23,7 @@ module ActionLogic
       end
 
       def __private__type
-        :use_case
+        "use_case"
       end
     end
   end

data/lib/action_logic/configuration.rb

@@ -0,0 +1,44 @@
+require 'ostruct'
+
+module ActionLogic
+  extend self
+
+  def self.configure(&block)
+    block.call(configuration_options)
+  end
+
+  def self.configuration_options
+    @configuration_options ||= OpenStruct.new
+  end
+
+  def self.benchmark?
+    configuration_options.benchmark || false
+  end
+
+  def self.benchmark_log
+    configuration_options.benchmark_log || $stdout
+  end
+
+  def self.benchmark_formatter
+    custom_benchmark_formatter || default_formatter
+  end
+
+  def self.benchmark_handler
+    configuration_options.benchmark_handler || ActionBenchmark::DefaultBenchmarkHandler.new
+  end
+
+  def self.reset!
+    @configuration_options = OpenStruct.new
+    @custom_benchmark_formatter = nil
+    @default_formatter = nil
+  end
+
+  def self.custom_benchmark_formatter
+    @custom_benchmark_formatter ||= configuration_options.benchmark_formatter &&
+      configuration_options.benchmark_formatter.new
+  end
+
+  def self.default_formatter
+    @default_formatter ||= ActionBenchmark::DefaultFormatter.new
+  end
+end

data/lib/action_logic/version.rb

@@ -1,3 +1,3 @@
 module ActionLogic
-  VERSION = '0.2.4'
+  VERSION = '0.2.5'
 end

data/spec/action_logic/action_benchmark/default_formatter_spec.rb

@@ -9,21 +9,21 @@ module ActionLogic::ActionBenchmark
     subject { described_class.new(benchmark_log: benchmark_log) }
 
     it "writes the benchmark result to the log for an ActionCoordinator" do
-      subject.coordinator(benchmark_result, "CoordinatorContext")
+      subject.log_coordinator(benchmark_result, "CoordinatorContext")
       expect(benchmark_log.string).to\
-        eq "context:   CoordinatorContext                                 user_time: 0.000030   system_time: 0.000020   total_time: 0.000010   real_time: 0.000300  \n"
+        eq "context:CoordinatorContext user_time:0.000030 system_time:0.000020 total_time:0.000010 real_time:0.000300\n"
     end
 
     it "writes the benchmark result to the log for an ActionUseCase" do
-      subject.coordinator(benchmark_result, "UseCaseContext")
+      subject.log_use_case(benchmark_result, "UseCaseContext")
       expect(benchmark_log.string).to\
-        eq "context:   UseCaseContext                                     user_time: 0.000030   system_time: 0.000020   total_time: 0.000010   real_time: 0.000300  \n"
+        eq "context:UseCaseContext user_time:0.000030 system_time:0.000020 total_time:0.000010 real_time:0.000300\n"
     end
 
     it "writes the benchmark result to the log for an ActionTask" do
-      subject.coordinator(benchmark_result, "TaskContext")
+      subject.log_task(benchmark_result, "TaskContext")
       expect(benchmark_log.string).to\
-        eq "context:   TaskContext                                        user_time: 0.000030   system_time: 0.000020   total_time: 0.000010   real_time: 0.000300  \n"
+        eq "context:TaskContext user_time:0.000030 system_time:0.000020 total_time:0.000010 real_time:0.000300\n"
     end
   end
 end

data/spec/action_logic/action_coordinator_spec.rb

@@ -6,7 +6,7 @@ require 'fixtures/custom_types'
 module ActionLogic
   describe ActionCoordinator do
     it "knows its type" do
-      expect(TestCoordinator1.__private__type).to eq(:coordinator)
+      expect(TestCoordinator1.__private__type).to eq("coordinator")
     end
 
     context "no failures and no halts" do

data/spec/action_logic/action_task_spec.rb

@@ -5,7 +5,7 @@ require 'fixtures/tasks'
 module ActionLogic
   describe ActionTask do
     it "knows its type" do
-      expect(SimpleTestTask.__private__type).to eq(:task)
+      expect(SimpleTestTask.__private__type).to eq("task")
     end
 
     it "returns an instance of ActionContext" do

data/spec/action_logic/active_use_case_spec.rb

@@ -6,7 +6,7 @@ require 'fixtures/custom_types'
 module ActionLogic
   describe ActionUseCase do
     it "knows its type" do
-      expect(SimpleTestUseCase.__private__type).to eq(:use_case)
+      expect(SimpleTestUseCase.__private__type).to eq("use_case")
     end
 
     it "returns an instance of ActionContext" do

data/spec/action_logic/configuration_spec.rb

@@ -0,0 +1,75 @@
+require 'spec_helper'
+require 'action_logic'
+
+describe ActionLogic do
+
+  subject { described_class }
+
+  around do |example|
+    described_class.reset!
+    example.run
+    described_class.reset!
+  end
+
+  context "benchmark" do
+    it "defaults the benchmark configuration option to false" do
+      expect(described_class.benchmark?).to be_falsey
+    end
+
+    it "returns true when the benchmark configuration option is set to true" do
+      described_class.configure do |config|
+        config.benchmark = true
+      end
+
+      expect(described_class.benchmark?).to be_truthy
+    end
+  end
+
+  context "benchmark_log" do
+    it "defaults benchmark log file to stdout" do
+      expect(described_class.benchmark_log).to eq($stdout)
+    end
+
+    it "returns the log file when the benchmark log configuration option is set" do
+      temp_file = Object.new
+
+      described_class.configure do |config|
+        config.benchmark_log = temp_file
+      end
+
+      expect(described_class.benchmark_log).to eq(temp_file)
+    end
+  end
+
+  context "benchmark_formatter" do
+    it "uses default formatter if a custom formatter is not provided" do
+      expect(described_class.benchmark_formatter).to be_a(ActionLogic::ActionBenchmark::DefaultFormatter)
+    end
+
+    it "uses a custom formatter if one is provided" do
+      class CustomFormatter; end
+
+      described_class.configure do |config|
+        config.benchmark_formatter = CustomFormatter
+      end
+
+      expect(described_class.benchmark_formatter).to be_a(CustomFormatter)
+    end
+  end
+
+  context "benchmark_handler" do
+    it "uses a default benchmark handler if a custom benchmark handler is not provided" do
+      expect(described_class.benchmark_handler).to be_a(ActionLogic::ActionBenchmark::DefaultBenchmarkHandler)
+    end
+
+    it "uses a custom benchmark handler if one is provided" do
+      custom_benchmark_handler = -> { yield }
+
+      described_class.configure do |config|
+        config.benchmark_handler = custom_benchmark_handler
+      end
+
+      expect(described_class.benchmark_handler).to eq(custom_benchmark_handler)
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -9,10 +9,33 @@ $LOAD_PATH << File.join(File.dirname(__FILE__))
 
 require 'action_logic'
 
+class CustomFormatter < ActionLogic::ActionBenchmark::DefaultFormatter
+  def log_coordinator(benchmark_result, execution_context_name)
+    benchmark_log.puts("The ActionCoordinator #{execution_context_name} took #{benchmark_result} to complete.")
+  end
+
+  def log_use_case(benchmark_result, execution_context_name)
+    benchmark_log.puts("The ActionUseCase #{execution_context_name} took #{benchmark_result} to complete.")
+  end
+
+  def log_task(benchmark_result, execution_context_name)
+    benchmark_log.puts("The ActionTask #{execution_context_name} took #{benchmark_result} to complete.")
+  end
+end
+
+class CustomHandler
+  def call
+    yield
+    "this is the custom handler"
+  end
+end
+
 if ENV['BENCHMARK']
-  ActionLogic::ActionConfiguration.configure do |config|
+  ActionLogic.configure do |config|
     config.benchmark = true
     config.benchmark_log = File.open("benchmark.log", "w")
+    config.benchmark_formatter = CustomFormatter
+    config.benchmark_handler = CustomHandler.new
   end
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: action_logic
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.5
 platform: ruby
 authors:
 - Rick Winfrey
@@ -80,8 +80,8 @@ files:
 - action_logic.gemspec
 - lib/action_logic.rb
 - lib/action_logic/action_benchmark.rb
+- lib/action_logic/action_benchmark/default_benchmark_block.rb
 - lib/action_logic/action_benchmark/default_formatter.rb
-- lib/action_logic/action_configuration.rb
 - lib/action_logic/action_context.rb
 - lib/action_logic/action_coordinator.rb
 - lib/action_logic/action_core.rb
@@ -93,6 +93,7 @@ files:
 - lib/action_logic/action_validation/base_validation.rb
 - lib/action_logic/action_validation/presence_validation.rb
 - lib/action_logic/action_validation/type_validation.rb
+- lib/action_logic/configuration.rb
 - lib/action_logic/errors.rb
 - lib/action_logic/version.rb
 - resources/action_coordinator_diagram.png
@@ -101,11 +102,11 @@ files:
 - resources/diagrams.sketch
 - resources/overview_diagram.png
 - spec/action_logic/action_benchmark/default_formatter_spec.rb
-- spec/action_logic/action_configuration_spec.rb
 - spec/action_logic/action_context_spec.rb
 - spec/action_logic/action_coordinator_spec.rb
 - spec/action_logic/action_task_spec.rb
 - spec/action_logic/active_use_case_spec.rb
+- spec/action_logic/configuration_spec.rb
 - spec/fixtures/constants.rb
 - spec/fixtures/coordinators.rb
 - spec/fixtures/custom_types.rb
@@ -138,11 +139,11 @@ specification_version: 4
 summary: Business logic abstraction
 test_files:
 - spec/action_logic/action_benchmark/default_formatter_spec.rb
-- spec/action_logic/action_configuration_spec.rb
 - spec/action_logic/action_context_spec.rb
 - spec/action_logic/action_coordinator_spec.rb
 - spec/action_logic/action_task_spec.rb
 - spec/action_logic/active_use_case_spec.rb
+- spec/action_logic/configuration_spec.rb
 - spec/fixtures/constants.rb
 - spec/fixtures/coordinators.rb
 - spec/fixtures/custom_types.rb

data/lib/action_logic/action_configuration.rb

@@ -1,40 +0,0 @@
-require 'ostruct'
-
-module ActionLogic
-  class ActionConfiguration
-    def self.configure(&block)
-      block.call(configuration_options)
-    end
-
-    def self.configuration_options
-      @configuration_options ||= OpenStruct.new
-    end
-
-    def self.benchmark?
-      configuration_options.benchmark || false
-    end
-
-    def self.benchmark_log
-      configuration_options.benchmark_log || $stdout
-    end
-
-    def self.benchmark_formatter
-      custom_benchmark_formatter || default_formatter
-    end
-
-    def self.reset!
-      @configuration_options = OpenStruct.new
-      @custom_benchmark_formatter = nil
-      @default_formatter = nil
-    end
-
-    def self.custom_benchmark_formatter
-      @custom_benchmark_formatter ||= configuration_options.benchmark_formatter &&
-        configuration_options.benchmark_formatter.new
-    end
-
-    def self.default_formatter
-      @default_formatter ||= ::ActionLogic::ActionBenchmark::DefaultFormatter.new
-    end
-  end
-end

data/spec/action_logic/action_configuration_spec.rb

@@ -1,62 +0,0 @@
-require 'spec_helper'
-require 'action_logic'
-
-module ActionLogic
-  describe ActionConfiguration do
-    subject { described_class }
-
-    before do
-      described_class.reset!
-    end
-
-    after do
-      described_class.reset!
-    end
-
-    context "benchmark" do
-      it "defaults the benchmark configuration option to false" do
-        expect(described_class.benchmark?).to be_falsey
-      end
-
-      it "returns true when the benchmark configuration option is set to true" do
-        described_class.configure do |config|
-          config.benchmark = true
-        end
-
-        expect(described_class.benchmark?).to be_truthy
-      end
-    end
-
-    context "benchmark_log" do
-      it "defaults benchmark log file to stdout" do
-        expect(described_class.benchmark_log).to eq($stdout)
-      end
-
-      it "returns the log file when the benchmark log configuration option is set" do
-        temp_file = Object.new
-
-        described_class.configure do |config|
-          config.benchmark_log = temp_file
-        end
-
-        expect(described_class.benchmark_log).to eq(temp_file)
-      end
-    end
-
-    context "benchmark_formatter" do
-      it "uses default formatter if a custom formatter is not provided" do
-        expect(described_class.benchmark_formatter).to be_a(ActionLogic::ActionBenchmark::DefaultFormatter)
-      end
-
-      it "uses a custom formatter if one is provided" do
-        class CustomFormatter; end
-
-        described_class.configure do |config|
-          config.benchmark_formatter = CustomFormatter
-        end
-
-        expect(described_class.benchmark_formatter).to be_a(CustomFormatter)
-      end
-    end
-  end
-end