lite-command 2.0.3 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b21cf35a72b7a37760d250919ee052e3800bfe09083709e9d9f65593612d8826
-  data.tar.gz: b2b55e457b95ce878aab140537ba1f28aa5310c4e257d0e2b11948ed9ee7f9c2
+  metadata.gz: efd37a3a2fcbb8d90fef73088313f18bd281922d46594a4a57ee8dd34fcaf801
+  data.tar.gz: 4e88ca10b986095be52c3e454e70a6c8d7b3556bb4770ed51aca80d0b9beb894
 SHA512:
-  metadata.gz: f8ab004280e1c00026dacc92a7d652dc2859c68f6648e31210ccfa1c16a1aba9ba31e57843910bf90d4b94677e8cd8c4c651989c2e2f1983556f33ff786e6514
-  data.tar.gz: aed6da43c95926071114ef9692b17c4fa2b5a3215629e473c8bd70a552fdd624f189095cfa1744da6aa427cbcf80cfb6adb6db81c5b754f4ff81bfee500d046d
+  metadata.gz: 4123ef0a3315a8b00796a58ca65b10bc2a51905dc59e663b1ffef2ec7f9becc700ae64216cb896024564993749979cd824087a68bac1e95532311dba29cd7aa0
+  data.tar.gz: dd4e22ead3d68f981319a372a0ce305f734f1745a31223daf725d93ff71cccbe1b4708e7b3d7ef4921f98f2e8df6c04939855b8a7e8d0e3292f5e7f3e0ec6c1a

data/.rubocop.yml

@@ -51,6 +51,12 @@ RSpec/MultipleExpectations:
   Enabled: false
 RSpec/MultipleMemoizedHelpers:
   Enabled: false
+RSpec/NestedGroups:
+  Enabled: false
+RSpec/StringAsInstanceDoubleConstant:
+  Enabled: false
+RSpec/VerifiedDoubleReference:
+  EnforcedStyle: string
 Style/ArgumentsForwarding:
   Enabled: false
 Style/Documentation:

data/CHANGELOG.md

@@ -6,6 +6,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.1.0] - 2024-10-05
+### Added
+- Added passing metadata to faults
+- Added `on_success` callback
+- Added `on_pending`, `on_executing`, `on_complete`, and `on_interrupted` callbacks
+- Added attributes and attribute validations
+- Added sequences
+### Changed
+- Check error descendency instead of type
+- Rename internal modules
+- Make execute(!) methods private
+### Removed
+- Remove predefined callback methods
+- Remove non-bang fault methods
+
 ## [2.0.3] - 2024-09-30
 ### Changed
 - Simplify error building

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    lite-command (2.0.3)
+    lite-command (2.1.0)
       ostruct
 
 GEM
@@ -114,7 +114,7 @@ GEM
     rspec-expectations (3.13.3)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
-    rspec-mocks (3.13.1)
+    rspec-mocks (3.13.2)
       diff-lcs (>= 1.2.0, < 2.0)
       rspec-support (~> 3.13.0)
     rspec-support (3.13.1)
@@ -135,7 +135,7 @@ GEM
       rubocop-ast (>= 1.31.1, < 2.0)
     rubocop-rake (0.6.0)
       rubocop (~> 1.0)
-    rubocop-rspec (3.0.5)
+    rubocop-rspec (3.1.0)
       rubocop (~> 1.61)
     ruby-progressbar (1.13.0)
     ruby_parser (3.21.1)

data/README.md

@@ -1,7 +1,6 @@
 # Lite::Command
 
 [![Gem Version](https://badge.fury.io/rb/lite-command.svg)](http://badge.fury.io/rb/lite-command)
-[![Build Status](https://travis-ci.org/drexed/lite-command.svg?branch=master)](https://travis-ci.org/drexed/lite-command)
 
 Lite::Command provides an API for building simple and complex command based service objects.
 
@@ -9,6 +8,10 @@ Lite::Command provides an API for building simple and complex command based serv
 
 Add this line to your application's Gemfile:
 
+> [!NOTE]
+> Gem versions `2.0.0`, `2.0.1`, `2.0.2`, and `2.0.3` are borked.
+> Version `2.1.0` is the latest working version.
+
 ```ruby
 gem 'lite-command'
 ```
@@ -25,50 +28,112 @@ Or install it yourself as:
 
 * [Setup](#setup)
 * [Execution](#execution)
+  * [Dynamic Faults](#dynamic-faults)
 * [Context](#context)
-* [Internals](#Internals)
+  * [Attributes](#attributes)
+* [States](#states)
+* [Statuses](#statuses)
+* [Callbacks](#callbacks)
+  * [State Hooks](#status-hooks)
+  * [Execution Hooks](#execution-hooks)
+  * [Status Hooks](#status-hooks)
+* [Children](#children)
+  * [Throwing Faults](#throwing-faults)
+* [Sequences](#sequences)
+* [Results](#results)
+* [Examples](#examples)
+  * [Disable Instance Calls](#disable-instance-calls)
+  * [ActiveModel Validations](#activemodel-validations)
 * [Generator](#generator)
 
 ## Setup
 
-Defining a command is as simple as adding a call method.
+Defining a command is as simple as adding a call method to a command object (required).
 
 ```ruby
 class CalculatePower < Lite::Command::Base
 
   def call
-    # TODO: implement calculator
+    if all_even_numbers?
+      context.result = ctx.a ** ctx.b
+    else
+      invalid!("All values must be even")
+    end
+  end
+
+  private
+
+  def all_even_numbers?
+    # Some logic...
   end
 
 end
 ```
 
+> [!TIP]
+> You should make all of your domain logic private so that only the command API is exposed.
+
 ## Execution
 
 Executing a command can be done as an instance or class call.
-It returns the command instance in a forzen state.
+It returns the command instance in a frozen state.
 These will never call will never raise an execption, but will
 be kept track of in its internal state.
 
-**NOTE:** Class calls is the prefered format due to its readability.
-
 ```ruby
-# Class call
-CalculatePower.call(..args)
-
-# Instance call
-caculator = CalculatePower.new(..args).call
+CalculatePower.call(...)
+# - or -
+CalculatePower.new(...).call
 
+# On success, fault and exception:
 #=> <CalculatePower ...>
 ```
 
+> [!TIP]
+> Class calls is the prefered format due to its readability.
+
 Commands can be called with a `!` bang method to raise a
 `Lite::Command::Fault` based exception or the original
 `StandardError` based exception.
 
 ```ruby
-CalculatePower.call!(..args)
+CalculatePower.call!(...)
+# - or -
+CalculatePower.new(...).call!
+
+# On success:
+#=> <CalculatePower ...>
+
+# On fault:
 #=> raises Lite::Command::Fault
+
+# On exception:
+#=> raises StandardError
+```
+
+### Dynamic Faults
+
+You can enable dynamic faults named after your command. This is
+especially helpful for catching + running custom logic or filtering
+out specific errors from you APM service.
+
+```ruby
+class CalculatePower < Lite::Command::Base
+
+  def call
+    fail!("Some failure")
+  end
+
+  private
+
+  def raise_dynamic_faults?
+    true
+  end
+
+end
+
+CalculatePower.call!(...)
+#=> raises CalculatePower::Fault
 ```
 
 ## Context
@@ -81,7 +146,8 @@ of its children commands.
 class CalculatePower < Lite::Command::Base
 
   def call
-    context.result = context.a ** context.b
+    # `ctx` is an alias to `context`
+    context.result = ctx.a ** ctx.b
   end
 
 end
@@ -90,50 +156,425 @@ command = CalculatePower.call(a: 2, b: 3)
 command.context.result #=> 8
 ```
 
-## Internals
-
-#### States
-State represents the state of the executable code. Once `execute`
-is ran, it will always `complete` or `interrupted` if a fault is thrown by a
-child command.
-
-- `pending`
-    - Command objects that have been initialized.
-- `executing`
-    - Command objects actively executing code.
-- `complete`
-    - Command objects that executed to completion.
-- `interrupted`
-    - Command objects that could NOT be executed to completion.
-      This could be as a result of a fault/exception on the
-      object itself or one of its children.
-
-#### Statuses
-
-Status represents the state of the callable code. If no fault
-is thrown then a status of `success` is returned even if `call`
-has not been executed. The list of status include (by severity):
-
-- `success`
-    - No fault or exception
-- `noop`
-    - Noop represents skipping completion of call execution early
-      an unsatisfied condition or logic check where there is no
-      point on proceeding.
-    - **eg:** account is sample: skip since its a non-alterable record
-- `invalid`
-    - Invalid represents a stoppage of call execution due to
-      missing, bad, or corrupt data.
-    - **eg:** user not found: stop since rest of the call cant be executed
-- `failure`
-    - Failure represents a stoppage of call execution due to
-      an unsatisfied condition or logic check where it blocks
-      proceeding any further.
-    - **eg:** record not found: stop since there is nothing todo
-- `error`
-    - Error represents a caught exception for a call execution
-      that could not complete.
-    - **eg:** ApiServerError: stop since there was a 3rd party issue
+### Attributes
+
+Delegate methods for a cleaner command setup, type checking and
+argument requirements. Setup a contract by using the `attribute`
+method which automatically delegates to `context`.
+
+| Options    | Values | Default | Description |
+| ---------- | ------ | ------- | ----------- |
+| `from`     | Symbol, String | `:context` | The object containing the attribute. |
+| `types`    | Symbol, String, Array, Proc | | The allowed class types of the attribute value. |
+| `required` | Symbol, String, Boolean, Proc | `false` | The attribute must be passed to the context or delegatable (no matter the value). |
+| `filled`   | Symbol, String, Boolean, Proc | `false` | The attribute value must be not be `nil`. |
+
+> [!NOTE]
+> If optioned with some similar to `filled: true, types: [String, NilClass]`
+> then `NilClass` for the `types` option will be removed automatically.
+
+```ruby
+class CalculatePower < Lite::Command::Base
+
+  attribute :remote_storage, required: true, filled: true, types: RemoteStorage
+
+  attribute :a, :b
+  attribute :c, :d, from: :remote_storage, types: [Integer, Float]
+  attribute :x, :y, from: :local_storage, if: :signed_in?
+
+  def call
+    context.result =
+      (a.to_i ** b.to_i) +
+      (c.to_i + d.to_i) -
+      (x.to_i + y.to_i)
+  end
+
+  private
+
+  def local_storage
+    @local_storage ||= LocalStorage.new(x: 1, y: 1, z: 99)
+  end
+
+  def signed_in?
+    ctx.user.signed_in?
+  end
+
+end
+
+# With valid options:
+storage = RemoteStorage.new(c: 2, d: 2, j: 99)
+command = CalculatePower.call(a: 2, b: 2, remote_storage: storage)
+command.status         #=> "success"
+command.context.result #=> 6
+
+# With invalid options
+command = CalculatePower.call
+command.status   #=> "invalid"
+command.reason   #=> "Invalid context attributes"
+command.metadata #=> {
+                 #=>   context: ["a is required", "remote_storage must be filled"],
+                 #=>   remote_storage: ["d type invalid"]
+                 #=>   local_storage: ["is not defined or an attribute"]
+                 #=> }
+```
+
+## States
+`state` represents the condition of all the code command should execute.
+
+| Status        | Description |
+| ------------- | ----------- |
+| `pending`     | Command objects that have been initialized. |
+| `executing`   | Command objects that are actively executing code. |
+| `complete`    | Command objects that executed to completion without fault/exception. |
+| `interrupted` | Command objects that could **NOT** be executed to completion due to a fault/exception. |
+
+> [!CAUTION]
+> States are automatically transitioned and should **NEVER** be altered manually.
+
+```ruby
+class CalculatePower < Lite::Command::Base
+
+  def call
+    # ...
+  end
+
+end
+
+command = CalculatePower.call(a: 1, b: 3)
+command.state     #=> "executed"
+command.pending?  #=> false
+command.executed? #=> false
+```
+
+## Statuses
+
+`status` represents the state of the domain logic executed via the `call` method.
+A status of `success` is returned even if the command has **NOT** been executed.
+
+| Status    | Description |
+| --------- | ----------- |
+| `success` | Call execution completed without fault/exception. |
+| `noop`    | **Fault** to skip completion of call execution early for an unsatisfied condition where proceeding is pointless. |
+| `invalid` | **Fault** to stop call execution due to missing, bad, or corrupt data. |
+| `failure` | **Fault** to stop call execution due to an unsatisfied condition where it blocks proceeding any further. |
+| `error`   | **Fault** to stop call execution due to a thrown `StandardError` based exception. |
+
+> [!IMPORTANT]
+> Each **fault** status has a setter method ending in `!` that invokes a matching fault procedure.
+> Metadata may also be passed to enrich your fault response.
+
+```ruby
+class CalculatePower < Lite::Command::Base
+
+  def call
+    if ctx.a.nil? || ctx.b.nil?
+      invalid!("An a and b parameter must be passed")
+    elsif ctx.a < 1 || ctx.b < 1
+      failure!("Parameters must be >= 1")
+    elsif ctx.a == 1 || ctx.b == 1
+      noop!(
+        "Anything to the power of 1 is 1",
+        { i18n: "some.key" }
+      )
+    else
+      ctx.result = ctx.a ** ctx.b
+    end
+  rescue DivisionError => e
+    error!("Cathcing it myself")
+  end
+
+end
+
+command = CalculatePower.call(a: 1, b: 3)
+command.ctx.result #=> nil
+command.status     #=> "noop"
+command.reason     #=> "Anything to the power of 1 is 1"
+command.metadata   #=> { i18n: "some.key" }
+command.invalid?   #=> false
+command.noop?      #=> true
+command.noop?("Anything to the power of 1 is 1") #=> true
+```
+
+## Callbacks
+
+Use callbacks to run arbituary code at transition points and
+on finalized internals. The following is an example of the hooks
+called for a failed command with a successful child command.
+
+```ruby
+-> 1. FooCommand.on_pending
+-> 2. FooCommand.on_before_execution
+-> 3. FooCommand.on_executing
+---> 3a. BarCommand.on_pending
+---> 3b. BarCommand.on_before_execution
+---> 3c. BarCommand.on_executing
+---> 3d. BarCommand.on_after_execution
+---> 3e. BarCommand.on_success
+---> 3f. BarCommand.on_complete
+-> 4. FooCommand.on_after_execution
+-> 5. FooCommand.on_failure
+-> 6. FooCommand.on_interrupted
+```
+
+### Status Hooks
+
+Define one or more callbacks that are called during transitions
+between states.
+
+```ruby
+class CalculatePower < Lite::Command::Base
+
+  def call
+    # ...
+  end
+
+  private
+
+  def on_pending
+    # eg: Append additional contextual data
+  end
+
+  def on_executing
+    # eg: Insert inspection debugger
+  end
+
+  def on_complete
+    # eg: Log message for posterity
+  end
+
+  def on_interrupted
+    # eg: Report to APM with tags and metadata
+  end
+
+end
+```
+
+### Execution Hooks
+
+Define before and after callbacks to call around execution.
+
+```ruby
+class CalculatePower < Lite::Command::Base
+
+  def call
+    # ...
+  end
+
+  private
+
+  def on_before_execution
+    # eg: Append additional contextual data
+  end
+
+  def on_after_execution
+    # eg: Store results to database
+  end
+
+end
+```
+
+### Status Hooks
+
+Define one or more callbacks that are called after execution for
+specific statuses.
+
+```ruby
+class CalculatePower < Lite::Command::Base
+
+  def call
+    # ...
+  end
+
+  private
+
+  def on_success
+    # eg: Increment KPI counter
+  end
+
+  def on_noop(fault)
+    # eg: Log message for posterity
+  end
+
+  def on_invalid(fault)
+    # eg: Send metadata errors to frontend
+  end
+
+  def on_failure(fault)
+    # eg: Rollback record changes
+  end
+
+  def on_error(fault_or_exception)
+    # eg: Report to APM with tags and metadata
+  end
+
+end
+```
+
+> [!NOTE]
+> The `on_success` callback does **NOT** take any arguments.
+
+## Children
+
+When building complex commands, its best that you pass the
+parents context to the child command (unless neccessary) so
+that it gains automated indexing and the parents `cmd_id`.
+
+```ruby
+class CalculatePower < Lite::Command::Base
+
+  def call
+    CalculateSqrt.call(context.merge!(some_other: "required value"))
+  end
+
+end
+```
+
+### Throwing Faults
+
+Throwing faults allows you to bubble up child faults up to the parent.
+Use it to create branches within your logic and create clean tracing
+of your command results. You can use `throw!` as a catch-all or any
+of the bang status method `failure!`.
+
+```ruby
+class CalculatePower < Lite::Command::Base
+
+  def call
+    command = CalculateSqrt.call(context.merge!(some_other: "required value"))
+
+    if command.noop?("Sqrt of 1 is 1")
+      # Manually throw any fault you want
+      invalid!(command)
+    elsif command.fault?
+      # Automatically throws a matching fault type
+      throw!(command)
+    else
+      # Success, do nothing
+    end
+  end
+
+end
+```
+
+## Sequences
+
+A sequence is a command that calls commands in a linear fashion.
+This is useful for composing multiple steps into one call.
+
+> [!NOTE]
+> Sequences only stop processing on `invalid`, `failure`, and `error`
+> faults. This is due to the the idea the `noop` performs no work,
+> so its no different than just passing the context forward. To change
+> this behavior, just override the `ok?` method with you logic, eg: just `success`
+
+```ruby
+class ProcessCheckout < Lite::Command::Sequence
+
+  attribute :user, required: true, filled: true
+
+  step FinalizeInvoice
+  step ChargeCard, if: :card_available?
+  step SendConfirmationEmail, SendConfirmationText
+  step NotifyWarehouse, unless: proc { ctx.invoice.fullfilled_by_amazon? }
+
+  # Do NOT set a call method.
+  # Its defined by Lite::Command::Sequence
+
+  private
+
+  def card_available?
+    user.has_card?
+  end
+
+end
+
+sequence = ProcessCheckout.call(...)
+# <ProcessCheckout ...>
+```
+
+## Results
+
+During any point in the lifecyle of a command, `to_hash` can be
+called to dump out the current values. The `index` value is
+auto-incremented and the `cmd_id` is static when its passed to
+child commands. This helps with debugging and logging.
+
+```ruby
+command = CalculatePower.call(...)
+command.to_hash #=> {
+                #=>   index: 1,
+                #=>   cmd_id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
+                #=>   command: "FailureCommand",
+                #=>   outcome: "failure",
+                #=>   state: "interrupted",
+                #=>   status: "failure",
+                #=>   reason: "[!] command stopped due to failure",
+                #=>   metadata: {
+                #=>     errors: { name: ["is too short"] },
+                #=>     i18n_key: "command.failure"
+                #=>   },
+                #=>   caused_by: 1,
+                #=>   thrown_by: 1,
+                #=>   runtime: 0.0123
+                #=> }
+```
+
+## Examples
+
+### Disable Instance Calls
+
+```ruby
+class CalculatePower < Lite::Command::Base
+
+  private_class_method :new
+
+  def call
+    # ...
+  end
+
+end
+
+CalculatePower.new(...).call
+#=> raise NoMethodError
+```
+
+### ActiveModel Validations
+
+```ruby
+class CalculatePower < Lite::Command::Base
+  include ActiveModel::Validations
+
+  validates :a, :b, presence: true
+
+  def call
+    # ...
+  end
+
+  def read_attribute_for_validation(key)
+    context.public_send(key)
+  end
+
+  private
+
+  def on_before_execution
+    return if valid?
+
+    invalid!(
+      errors.full_messages.to_sentence,
+      errors.to_hash
+    )
+  end
+
+end
+
+CalculatePower.call!
+
+# With `validate!`
+#=> raise ActiveRecord::RecordInvalid
+
+# With `valid?`
+#=> raise Lite::Command::Invalid
+```
 
 ## Generator