cmdx 0.1.0

data/docs/example.md

@@ -0,0 +1,82 @@
+# Example
+
+The following is a full example of task that is commonly implemented.
+
+## Setup
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+
+  required :order
+  required :billing_details, :shipping_details, from: :order
+
+  optional :package do
+    required :delivery_company, default: -> { Current.account.premium? ? "UPS" : "DHL" }
+    optional :weight, :volume, type: :float
+  end
+
+  after_execution :track_metrics
+
+  def call
+    if cart_abandoned?
+      skip!(reason: "Cart was abandoned due to 30 days of inactivity")
+    elsif cart_items_out_of_stock?
+      fail!(reason: "Items in the cart are out of stock", item: [123, 987])
+    else
+      charge_payment_method
+      ship_order_packages
+      send_confirmation_email
+    end
+  end
+
+  private
+
+  def charge_payment_method
+    @charge_payment_method ||= ChargePaymentMethodTask.call(details: billing_details)
+  end
+
+  def ship_order_packages
+    @ship_order_packages ||= ShipOrderPackagesTask.call(details: shipping_details)
+  end
+
+  def send_confirmation_email
+    return if charge_payment_method.failed? || ship_order_packages.bad?
+
+    BatchSendConfirmationNotifications.call(context)
+  end
+
+  def track_metrics
+    if Rails.env.development?
+      logger.debug { "Sending metrics to collector" }
+    else
+      TrackMetricsTask.call(metric: :process_order, status: order.status)
+    end
+  end
+
+end
+```
+
+## Execution
+
+```ruby
+class OrdersController < ApplicationController
+
+  def create
+    task = ProcessOrderTask.call(order_params)
+
+    if task.success?
+      flash[:success] = "Order is on its way!"
+      redirect_to(my_orders_path)
+    else
+      flash[:error] = "Whoops something is wrong: #{task.metadata[:reason]}"
+      render(:new)
+    end
+  end
+
+end
+```
+
+---
+
+- **Prev:** [Tips & Tricks](https://github.com/drexed/cmdx/blob/main/docs/tips_and_tricks.md)
+- **Next:** [Getting Started](https://github.com/drexed/cmdx/blob/main/docs/getting_started.md)

data/docs/getting_started.md

@@ -0,0 +1,47 @@
+# Getting Start
+
+`CMDx` is a framework for expressive processing of business logic.
+
+Goals:
+- Provide easy branching, nesting, and composition of complex tasks
+- Supply intent, severity, and reasoning to halting execution of tasks
+- Demystify root causes of complex multi-level tasks with exhaustive tracing
+
+## Setup
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+
+  def call
+    fail!(reason: "Order was canceled") if context.order.canceled?
+    skip!(reason: "Order is processing") if context.order.processing?
+
+    inform_partner_warehouses
+    send_confirmation_email
+  end
+
+end
+```
+
+## Execution
+
+```ruby
+result = ProcessOrderTask.call(order: order)
+```
+
+## Result
+
+```ruby
+if result.failed?
+  flash[:error] = "Failed! #{result.metadata[:reason]}"
+elsif result.skipped?
+  flash[:notice] = "FYI: #{result.metadata[:reason]}"
+else
+  flash[:success] = "Order successfully processed"
+end
+```
+
+---
+
+- **Prev:** [Example](https://github.com/drexed/cmdx/blob/main/docs/example.md)
+- **Next:** [Configuration](https://github.com/drexed/cmdx/blob/main/docs/configuration.md)

data/docs/hooks.md

@@ -0,0 +1,59 @@
+# Hooks
+
+Hooks (callbacks) run logic at task transition points. Callable hooks have access
+to all the same information as the `call` method.
+
+> [!TIP]
+> Hooks are inheritable which is handy for setting up global logic execution,
+> eg: setting tracking markers, account plan checks, etc.
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+
+  # Symbol or string declaration:
+  after_validation :verify_message_starting_chars
+
+  # Proc or lambda declaration:
+  on_complete -> { send_telemetry_data }
+
+  # Multiple declarations:
+  on_success :increment_success_task_counter, :scrub_secret_message_data
+
+  # With options (applies to all declared in that group):
+  on_failure :increment_failure_task_counter, if: :worth_keep_track?
+
+  def call
+    # Do work...
+  end
+
+end
+```
+
+The hook methods support the following options:
+
+| Option        | Description |
+| ------------- | ----------- |
+| `:if`         | Specifies a callable method, proc or string to determine if hook processing should occur. |
+| `:unless`     | Specifies a callable method, proc, or string to determine if hook processing should not occur. |
+
+## Order
+
+Hook types are executed in the following order:
+
+```ruby
+1. before_execution
+2. on_executing
+3. before_validation
+4. after_validation
+5. on_[success, skipped, failed]
+6. on_[complete, interrupted]
+7. after_execution
+```
+
+> [!IMPORTANT]
+> Callable hooks are executed in the order they are declared (FIFO: first in, first out).
+
+---
+
+- **Prev:** [Outcomes - States](https://github.com/drexed/cmdx/blob/main/docs/outcomes/states.md)
+- **Next:** [Batch](https://github.com/drexed/cmdx/blob/main/docs/batch.md)

data/docs/interruptions/exceptions.md

@@ -0,0 +1,29 @@
+# Interruptions - Exceptions
+
+## Non-bang call
+
+Any unhandled exception will be caught and halted using `fail!`.
+The original exception will be passed as metadata of the result object.
+
+```ruby
+result = ProcessOrderTask.call
+result.state    #=> "interrupted"
+result.status   #=> "failed"
+result.metadata #=> {
+                #=>   reason: "[RuntimeError] method xyz is not defined",
+                #=>   original_exception: <RuntimeError message="method xyz is not defined">
+                #=> }
+```
+
+## Bang call
+
+Any unhandled exception from a `call!` method will be raised as is.
+
+```ruby
+ProcessOrderTask.call! #=> raises NoMethodError, "method xyz is not defined"
+```
+
+---
+
+- **Prev:** [Interruptions - Faults](https://github.com/drexed/cmdx/blob/main/docs/interruptions/faults.md)
+- **Next:** [Outcomes - Result](https://github.com/drexed/cmdx/blob/main/docs/outcomes/result.md)

data/docs/interruptions/faults.md

@@ -0,0 +1,89 @@
+# Interruptions - Faults
+
+Faults are the mechanisms by which `CMDx` goes about halting execution of tasks
+via the `skip!` and `fail!` methods. When tasks are executed with bang `call!` method,
+a fault exception that matches the current task status will be raised.
+
+## Rescue
+
+Use the standard Ruby `rescue` method to handle any faults with custom logic.
+
+```ruby
+begin
+  ProcessOrderTask.call!
+rescue CMDx::Skipped
+  # Do work on any skipped tasks
+rescue CMDx::Failed
+  # Do work on any failed tasks
+rescue CMDx::Fault
+  # Do work on any skipped or failed tasks
+end
+```
+
+## For
+
+Faults can be matched for the task that caused it.
+
+```ruby
+begin
+  ProcessOrderTask.call!
+rescue CMDx::Skipped.for?(ProcessOrderTask, DeliverOrderTask)
+  # Do work on just skipped ProcessOrderTask or DeliverOrderTask tasks
+end
+```
+
+## Matches
+
+Faults allow advance rescue matching with access to the underlying task internals.
+
+```ruby
+begin
+  ProcessOrderTask.call!
+rescue CMDx::Fault.matches? { |f| f.result.metadata[:reason].includes?("out of stock") }
+  # Do work on any skipped or failed tasks that have `:reason` metadata equals "out of stock"
+end
+```
+
+> [!IMPORTANT]
+> All fault exceptions have access to the `for?` and `matches?` methods.
+
+## Throw
+
+Throw the result of subtasks to bubble up fault as its own. Throwing will use the
+subtask results' status and metadata to create a matching halt on the parent task.
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+
+  def call
+    throw!(SendConfirmationNotificationsTask.call)
+
+    # Do other work...
+  end
+
+end
+
+result = ProcessOrderTask.call
+result.state    #=> "interrupted"
+result.status   #=> "skipped"
+result.metadata #=> { reason: "Order confirmation could not be sent due to invalid email." }
+```
+
+> [!NOTE]
+> `throw!` will bubble any skipped and failed results. To only throw skipped results, just add
+> a conditional for the specific status.
+
+## Results
+
+The following represents a result output example of a thrown fault.
+
+```ruby
+result = ProcessOrderTask.call
+result.threw_failure  #=> <CMDx::Result[SendConfirmationNotificationsTask] ...>
+result.caused_failure #=> <CMDx::Result[DeliverEmailTask] ...>
+```
+
+---
+
+- **Prev:** [Interruptions - Halt](https://github.com/drexed/cmdx/blob/main/docs/interruptions/halt.md)
+- **Next:** [Interruptions - Exceptions](https://github.com/drexed/cmdx/blob/main/docs/interruptions/exceptions.md)

data/docs/interruptions/halt.md

@@ -0,0 +1,80 @@
+# Interruptions - Halt
+
+Halting stops execution of a task. Halt methods signal the intent as to why a task
+is stopped executing.
+
+## Skip
+
+The `skip!` method indicates that a task did not meet the criteria to continue execution.
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+
+  def call
+    skip! if cart_abandoned?
+
+    # Do work...
+  end
+
+end
+```
+
+## Fail
+
+The `fail!` method indicates that a task met with incomplete, broken, or failed logic.
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+
+  def call
+    fail! if cart_items_out_of_stock?
+
+    # Do work...
+  end
+
+end
+```
+
+## Metadata
+
+Pass metadata to enrich faults with additional contextual information. Metadata requires
+that it be passed as a hash object. Internal failures will hydrate metadata into its result,
+eg: failed validations and unrescued exceptions.
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+
+  def call
+    if cart_abandoned?
+      skip!(reason: "Cart was abandoned due to 30 days of inactivity")
+    elsif cart_items_out_of_stock?
+      fail!(reason: "Items in the cart are out of stock", item: [123, 987])
+    else
+      # Do work...
+    end
+  end
+
+end
+
+result = ProcessOrderTask.call
+result.metadata #=> { reason: "Items in the cart are out of stock", item: [123, 987] }
+```
+
+> [!Important]
+> The `:reason` key is used to define the fault exception message. While not
+> required, it is strongly recommended that it is used on every halt method.
+
+## Results
+
+The following represents a result output example of a halted task.
+
+```ruby
+result = ProcessOrderTask.call
+result.status   #=> "failed"
+result.metadata #=> { reason: "Cart was abandoned due to 30 days of inactivity" }
+```
+
+---
+
+- **Prev:** [Basics - Run](https://github.com/drexed/cmdx/blob/main/docs/basics/run.md)
+- **Next:** [Interruptions - Faults](https://github.com/drexed/cmdx/blob/main/docs/interruptions/faults.md)

data/docs/logging.md

@@ -0,0 +1,102 @@
+# Logging
+
+Tasks log the result object after execution. Multi-threaded systems will have many
+tasks executing concurrently so `CMDx` uses a custom logger to make debugging easier.
+
+## Output
+
+Built-in log formatters are: `Line` (default), `Json`, `KeyValue`, `Logstash`, `Raw`
+
+#### Success:
+```txt
+I, [2022-07-17T18:43:15.000000 #3784] INFO -- CMDx: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 state=complete status=success outcome=success metadata={} runtime=0 tags=[] pid=3784
+```
+
+#### Skipped:
+```txt
+W, [2022-07-17T18:43:15.000000 #3784] WARN -- CMDx: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 state=interrupted status=skipped outcome=skipped metadata={} runtime=0 tags=[] pid=3784
+```
+
+#### Failed:
+```txt
+E, [2022-07-17T18:43:15.000000 #3784] ERROR -- CMDx: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 state=interrupted status=failed outcome=failed metadata={} runtime=0 tags=[] pid=3784
+```
+
+#### Level 1 subtask failure:
+```txt
+E, [2022-07-17T18:43:15.000000 #3784] ERROR -- CMDx: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 state=interrupted status=failed outcome=interrupted metadata={} runtime=0 tags=[] pid=3784 caused_failure={:index=>1, :run_id=>"018c2b95-b764-7615-a924-cc5b910ed1e5", :type=>"Task", :class=>"SimulationTask", :id=>"018c2b95-b764-7615-a924-cc5b910ed1e5", :state=>"interrupted", :status=>"failed", :outcome=>"failed", :metadata=>{}, :runtime=>0, :tags=>[], :pid=>3784} threw_failure={:index=>1, :run_id=>"018c2b95-b764-7615-a924-cc5b910ed1e5", :type=>"Task", :class=>"SimulationTask", :id=>"018c2b95-b764-7615-a924-cc5b910ed1e5", :state=>"interrupted", :status=>"failed", :outcome=>"failed", :metadata=>{}, :runtime=>0, :tags=>[], :pid=>3784}
+```
+
+#### Level 2+ subtask failure:
+```txt
+E, [2022-07-17T18:43:15.000000 #3784] ERROR -- CMDx: index=0 run_id=018c2b95-b764-7615-a924-cc5b910ed1e5 type=Task class=SimulationTask id=018c2b95-b764-7615-a924-cc5b910ed1e5 state=interrupted status=failed outcome=interrupted metadata={} runtime=0 tags=[] pid=3784 caused_failure={:index=>2, :run_id=>"018c2b95-b764-7615-a924-cc5b910ed1e5", :type=>"Task", :class=>"SimulationTask", :id=>"018c2b95-b764-7615-a924-cc5b910ed1e5", :state=>"interrupted", :status=>"failed", :outcome=>"failed", :metadata=>{}, :runtime=>0, :tags=>[], :pid=>3784} threw_failure={:index=>1, :run_id=>"018c2b95-b764-7615-a924-cc5b910ed1e5", :type=>"Task", :class=>"SimulationTask", :id=>"018c2b95-b764-7615-a924-cc5b910ed1e5", :state=>"interrupted", :status=>"failed", :outcome=>"interrupted", :metadata=>{}, :runtime=>0, :tags=>[], :pid=>3784}
+```
+
+## Logger
+
+CMDx defaults to using Ruby's standard library Logger. Log levels thus follow the
+[stdlib documentation](http://www.ruby-doc.org/stdlib/libdoc/logger/rdoc/Logger.html).
+
+#### Global settings:
+
+```ruby
+CMDx.configure do |config|
+  # Single declaration:
+  config.logger = Logger.new($stdout, formatter: CMDx::LogFormatters::Line.new, level: Logger::DEBUG)
+
+  # Multiline declarations:
+  config.logger           = Rails.logger
+  config.logger.formatter = CMDx::LogFormatters::Line.new
+  config.logger.level     = Logger::WARN
+end
+```
+
+#### Task settings:
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+
+  task_settings!(logger: Rails.logger, log_format: CMDx::LogFormatters::Logstash.new, log_level: Logger::WARN)
+
+  def call
+    # Do work...
+  end
+
+end
+```
+
+> [!TIP]
+> In production environments, a log level of DEBUG may be too verbose for your needs.
+> For quieter logs that use less disk space, you can change the log level to only show INFO and higher.
+
+## Write to log
+
+Write to log via the `logger` method.
+
+```ruby
+class ProcessOrderTask < CMDx::Task
+
+  def call
+    logger.info "Processing order"
+    logger.debug { context.to_h }
+  end
+
+end
+```
+
+## Output format
+
+Define a custom log formatter to match your expected output, for example one that changes the JSON keys:
+
+```ruby
+class CustomCmdxLogFormat
+  def call(severity, time, progname, message)
+    # Return string, hash, array, etc to output...
+  end
+end
+```
+
+---
+
+- **Prev:** [Batch](https://github.com/drexed/cmdx/blob/main/docs/batch.md)
+- **Next:** [Tips & Tricks](https://github.com/drexed/cmdx/blob/main/docs/tips_and_tricks.md)

data/docs/outcomes/result.md

@@ -0,0 +1,17 @@
+# Outcomes -  Result
+
+The result object is returned after a task execution. This is the main object
+that will be interacted with post call.
+
+```ruby
+result = ProcessOrderTask.call
+result.task     #=> <ProcessOrderTask ...>
+result.context  #=> <CMDx::Context ...>
+result.metadata #=> { ... }
+result.run      #=> <CMDx::Run ...>
+```
+
+---
+
+- **Prev:** [Interruptions - Exceptions](https://github.com/drexed/cmdx/blob/main/docs/interruptions/exceptions.md)
+- **Next:** [Outcomes - Statuses](https://github.com/drexed/cmdx/blob/main/docs/outcomes/statuses.md)

data/docs/outcomes/states.md

@@ -0,0 +1,31 @@
+# Outcomes -  States
+
+State represents the condition of all the code task should execute.
+
+| Status        | Description |
+| ------------- | ----------- |
+| `initialized` | Initial task state prior to any execution. |
+| `executing`   | Task is actively executing code. |
+| `complete`    | Task executed to completion without halting for any reason. |
+| `interrupted` | Task could **NOT** be executed to completion due to a fault/exception. |
+
+> [!CAUTION]
+> States are automatically transitioned and should **NEVER** be altered manually.
+
+```ruby
+result = ProcessOrderTask.call
+result.state        #=> "complete"
+
+result.pending?     #=> false
+result.executing?   #=> false
+result.complete?    #=> true
+result.interrupted? #=> false
+
+# `complete` or `interrupted`
+result.executed?
+```
+
+---
+
+- **Prev:** [Outcomes - Statuses](https://github.com/drexed/cmdx/blob/main/docs/outcomes/statuses.md)
+- **Next:** [Hooks](https://github.com/drexed/cmdx/blob/main/docs/hooks.md)

data/docs/outcomes/statuses.md

@@ -0,0 +1,33 @@
+# Outcomes -  Statuses
+
+Status represents the state of the task logic executed after its called.
+A status of `success` is returned even if the task has **NOT** been executed.
+
+| Status    | Description |
+| --------- | ----------- |
+| `success` | Call execution completed without fault/exception. |
+| `skipped` | Task stopped completion of call execution early where proceeding is pointless. |
+| `failed`  | Task stopped completion of call execution due to an unsatisfied/invalid condition or a `StandardError`. |
+
+> [!NOTE]
+> Statuses (except success) are paired with halt methods used to stop call execution.
+
+```ruby
+result = ProcessOrderTask.call
+result.status   #=> "skipped"
+
+result.success? #=> false
+result.skipped? #=> true
+result.failed?  #=> false
+
+# `success` or `skipped`
+result.good?    #=> true
+
+# `skipped` or `failed`
+result.bad?     #=> true
+```
+
+---
+
+- **Prev:** [Outcomes - Result](https://github.com/drexed/cmdx/blob/main/docs/outcomes/result.md)
+- **Next:** [Outcomes - States](https://github.com/drexed/cmdx/blob/main/docs/outcomes/states.md)

data/docs/parameters/coercions.md

@@ -0,0 +1,52 @@
+# Parameters - Coercions
+
+Parameter values will be returned as given (`type: :virtual`) but can be coerced (typecast)
+to a specific type. This is useful for casting stringified parameter values.
+
+Supported coercions are: `:array`, `:big_decimal`, `:boolean`, `:complex`, `:datetime`, `:date`,
+`:float`, `:hash`, `:integer`, `:rational`, `:string`, `:time`, `:virtual`
+
+```ruby
+class DetermineBoxSizeTask < CMDx::Task
+
+  # Single type
+  required :width, type: :string
+
+  # Multiple types
+  optional :height, type: [:float, :integer]
+
+  def call
+    width  #=> "1"
+    height #=> 2.3
+  end
+
+end
+
+# Coerced to value types
+DetermineBoxSizeTask.call(width: 1, height: "2.3")
+```
+
+> [!NOTE]
+> When passing multiple type, coercions are done in the order they are passed. An example of
+> numeric casting would be to cast numbers with precision first: `[:float, :integer]`
+
+## Results
+
+The following represents a result output example of a failed coercion.
+
+```ruby
+result = DetermineBoxSizeTask.call
+result.state    #=> "interrupted"
+result.status   #=> "failed"
+result.metadata #=> {
+                #=>   reason: "height could not be coerced into one of: float, integer.",
+                #=>   messages: {
+                #=>     height: ["could not be coerced into one of: float, integer"]
+                #=>   }
+                #=> }
+```
+
+---
+
+- **Prev:** [Namespacing](https://github.com/drexed/cmdx/blob/main/docs/parameters/namespacing.md)
+- **Next:** [Validations](https://github.com/drexed/cmdx/blob/main/docs/parameters/validations.md)

data/docs/parameters/defaults.md

@@ -0,0 +1,47 @@
+# Parameters - Defaults
+
+Assign default values for parameters that return a `nil` value.
+
+```ruby
+class DetermineBoxSizeTask < CMDx::Task
+
+  # Fixed value
+  required :width, default: 12
+
+  # Proc or lambda
+  optional :length, default: -> { Current.account.usa? ? 12 : 18 }
+
+  # Symbol or string
+  optional :depth, default: :depth_by_country
+
+  def call
+    width  #=> 12
+    length #=> 18
+    depth  #=> 48
+  end
+
+  private
+
+  def depth_by_country
+    case Current.account.country
+    when "usa" then 12
+    when "can" then 18
+    when "mex" then 24
+    else 48
+    end
+  end
+
+end
+
+# Initializes with default values
+DetermineBoxSizeTask.call(width: nil, length: nil)
+```
+
+> [!NOTE]
+> Defaults are subject to coercion and validations so take care setting
+> the fallback value to contain valid conditions.
+
+---
+
+- **Prev:** [Validations](https://github.com/drexed/cmdx/blob/main/docs/parameters/validations.md)
+- **Next:** [Results](https://github.com/drexed/cmdx/blob/main/docs/outcomes.md)