lite-command 2.1.3 → 3.0.0

data/README.md

@@ -8,10 +8,6 @@ Lite::Command provides an API for building simple and complex command based serv
 
 Add this line to your application's Gemfile:
 
-> [!WARNING]
-> Gem versions `~> 2.0` are borked.
-> Version `~> 2.1.0` is the suggested working version.
-
 ```ruby
 gem 'lite-command'
 ```
@@ -26,15 +22,18 @@ Or install it yourself as:
 
 ## Table of Contents
 
-* [Setup](#setup)
+* [Configuration](#configuration)
+* [Usage](#usage)
 * [Execution](#execution)
   * [Dynamic Faults](#dynamic-faults)
 * [Context](#context)
   * [Attributes](#attributes)
+  * [Validations](#validations)
 * [States](#states)
 * [Statuses](#statuses)
-* [Callbacks](#callbacks)
+* [Hooks](#hooks)
   * [State Hooks](#status-hooks)
+  * [Attribute Hooks](#attribute-hooks)
   * [Execution Hooks](#execution-hooks)
   * [Status Hooks](#status-hooks)
 * [Children](#children)
@@ -43,28 +42,38 @@ Or install it yourself as:
 * [Results](#results)
 * [Examples](#examples)
   * [Disable Instance Calls](#disable-instance-calls)
-  * [ActiveModel Validations](#activemodel-validations)
 * [Generator](#generator)
 
-## Setup
+## Configuration
+
+`rails g lite:command:install` will generate the following file in your application root:
+`config/initalizers/lite_command.rb`
+
+```ruby
+Lite::Command.configure do |config|
+  config.raise_dynamic_faults = true
+end
+```
+
+## Usage
 
-Defining a command is as simple as inheriting the base class and
-adding a `call` method to a command object (required).
+Defining a command is as simple as inheriting the base class and adding a `call` method
+to a command object (required).
 
 ```ruby
-class CalculatePower < Lite::Command::Base
+class DecryptSecretMessage < Lite::Command::Base
 
   def call
-    if all_even_numbers?
-      context.result = ctx.a ** ctx.b
+    if invalid_magic_numbers?
+      invalid!("Invalid crypto message")
     else
-      invalid!("All values must be even")
+      context.decrypted_message = SecretMessage.decrypt(context.encrypted_message)
     end
   end
 
   private
 
-  def all_even_numbers?
+  def invalid_magic_numbers?
     # Some logic...
   end
 
@@ -72,38 +81,38 @@ end
 ```
 
 > [!TIP]
-> You should make all of your domain logic private so that only the command API is exposed.
+> You should treat all command as emphemeral objects, so you should think about making
+> all of your domain logic private and leaving the default command API is exposed.
 
 ## Execution
 
-Executing a command can be done as an instance or class call.
-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.
+Executing a command can be done as an instance or class call. 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.
 
 ```ruby
-CalculatePower.call(...)
+DecryptSecretMessage.call(...)
 # - or -
-CalculatePower.new(...).call
+DecryptSecretMessage.new(...).call
 
 # On success, fault and exception:
-#=> <CalculatePower ...>
+#=> <DecryptSecretMessage ...>
 ```
 
 > [!TIP]
-> Class calls is the prefered format due to its readability.
+> Class calls is the prefered format due to its readability. Read the [Disable Instance Calls](#disable-instance-calls)
+> section on how to prevent instance style calls.
 
-Commands can be called with a `!` bang method to raise a
-`Lite::Command::Fault` based exception or the original
-`StandardError` based exception.
+Commands can be called with a `!` bang method to raise a `Lite::Command::Fault` or the
+original `StandardError` based exceptions.
 
 ```ruby
-CalculatePower.call!(...)
+DecryptSecretMessage.call!(...)
 # - or -
-CalculatePower.new(...).call!
+DecryptSecretMessage.new(...).call!
 
 # On success:
-#=> <CalculatePower ...>
+#=> <DecryptSecretMessage ...>
 
 # On fault:
 #=> raises Lite::Command::Fault
@@ -114,12 +123,12 @@ CalculatePower.new(...).call!
 
 ### 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.
+Dynamic faults are custom faults named after your command. This is especially
+helpful for catching + running custom logic or filtering out specific
+exceptions from your APM service.
 
 ```ruby
-class CalculatePower < Lite::Command::Base
+class DecryptSecretMessage < Lite::Command::Base
 
   def call
     fail!("Some failure")
@@ -127,14 +136,17 @@ class CalculatePower < Lite::Command::Base
 
   private
 
+  # Disable raising dynamic faults on a per command basis.
+  # The `raise_dynamic_faults` configuration option must be
+  # enabled for this method to have any affect.
   def raise_dynamic_faults?
-    true
+    false
   end
 
 end
 
-CalculatePower.call!(...)
-#=> raises CalculatePower::Failure
+DecryptSecretMessage.call!(...)
+#=> raises DecryptSecretMessage::Failure
 ```
 
 ## Context
@@ -147,57 +159,49 @@ of its children commands.
 > Attributes that do **NOT** exist on the context will return `nil`.
 
 ```ruby
-class CalculatePower < Lite::Command::Base
+class DecryptSecretMessage < Lite::Command::Base
 
   def call
     # `ctx` is an alias to `context`
-    context.result = ctx.a ** ctx.b
+    context.decrypted_message = SecretMessage.decrypt(ctx.encrypted_message)
   end
 
 end
 
-cmd = CalculatePower.call(a: 2, b: 3)
-cmd.context.result #=> 8
-cmd.ctx.fake       #=> nil
+cmd = DecryptSecretMessage.call(encrypted_message: "a22j3nkenjk2ne2")
+cmd.context.decrypted_message #=> "Hello World"
+cmd.ctx.fake_message          #=> nil
 ```
 
 ### 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, Hash | `false` | The attribute value must be not be `nil`. Prevent empty values using `{ empty: false }` |
-
-> [!NOTE]
-> If optioned with some similar to `filled: true, types: [String, NilClass]`
-> then `NilClass` for the `types` option will be removed automatically.
+Delegate methods for a cleaner command setup by declaring `required` and
+`optional` arguments. `required` only verifies that argument was pass to the
+context or can be called via defined method or another delegated method.
+Is an `:if` or `:unless` callable option on a `required` delegation evaluates
+to false, it will be delegated as an `optional` attribute.
 
 ```ruby
-class CalculatePower < Lite::Command::Base
-
-  attribute :remote_storage, required: true, filled: true, types: RemoteStorage
+class DecryptSecretMessage < Lite::Command::Base
 
-  attribute :a, :b
-  attribute :c, :d, from: :remote_storage, types: [Integer, Float]
-  attribute :x, :y, from: :local_storage, filled: { empty: false }, if: :signed_in?
+  required :user, :encrypted_message
+  required :secret_key, from: :user
+  required :algo, :algo_detector, if: :signed_in?
+  optional :version
 
   def call
-    context.result =
-      (a.to_i ** b.to_i) +
-      (c.to_i + d.to_i) -
-      (x.to_i + y.to_i)
+    context.decrypted_message = SecretMessage.decrypt(
+      encrypted_message,
+      decryption_key: ENV["DECRYPT_KEY"],
+      algo: algo,
+      version: version || 2
+    )
   end
 
   private
 
-  def local_storage
-    @local_storage ||= LocalStorage.new(x: 1, y: 1, z: 99)
+  def algo_detector
+    @algo_detector ||= AlgoDetector.new(encrypted_message)
   end
 
   def signed_in?
@@ -207,19 +211,52 @@ class CalculatePower < Lite::Command::Base
 end
 
 # With valid options:
-rs  = RemoteStorage.new(c: 2, d: 2, j: 99)
-cmd = CalculatePower.call(a: 2, b: 2, remote_storage: rs)
-cmd.status         #=> "success"
-cmd.context.result #=> 6
+cmd = DecryptSecretMessage.call(user: user, encrypted_message: "ll23k2j3kcms", version: 9)
+cmd.status                    #=> "success"
+cmd.context.decrypted_message #=> "Hola Mundo"
 
 # With invalid options:
-cmd = CalculatePower.call
+cmd = DecryptSecretMessage.call
 cmd.status   #=> "invalid"
-cmd.reason   #=> "Invalid context attributes"
+cmd.reason   #=> "Encrypted message is a required argument. User is an undefined argument..."
 cmd.metadata #=> {
-             #=>   context: ["a is required", "remote_storage must be filled"],
-             #=>   remote_storage: ["d type invalid"]
-             #=>   local_storage: ["is not defined or an attribute"]
+             #=>   user: ["is a required argument", "is an undefined argument"],
+             #=>   encrypted_message: ["is a required argument"]
+             #=> }
+```
+
+### Validations
+
+The full power of active model valdations is available to validate
+any and all delegated arguments.
+
+```ruby
+class DecryptSecretMessage < Lite::Command::Base
+
+  required :encrypted_message
+  optional :version
+
+  validates :encrypted_message, length: 10..999
+  validates :version, inclusion: { in: %w[v1 v3 v8], allow_blank: true }
+
+  def call
+    context.decrypted_message = SecretMessage.decrypt(ctx.encrypted_message)
+  end
+
+end
+
+# With valid options:
+cmd = DecryptSecretMessage.call(encrypted_message: "ll23k2j3kcms", version: "v1")
+cmd.status                    #=> "success"
+cmd.context.decrypted_message #=> "Hola Mundo"
+
+# With invalid options:
+cmd = DecryptSecretMessage.call(encrypted_message: "idk", version: "v23")
+cmd.status   #=> "invalid"
+cmd.reason   #=> "Encrypted message is too short (minimum is 10 character). Version is not included in list..."
+cmd.metadata #=> {
+             #=>   user: ["is not included in list"],
+             #=>   encrypted_message: ["is too short (minimum is 10 character)"]
              #=> }
 ```
 
@@ -237,7 +274,7 @@ cmd.metadata #=> {
 > States are automatically transitioned and should **NEVER** be altered manually.
 
 ```ruby
-cmd = CalculatePower.call
+cmd = DecryptSecretMessage.call
 cmd.state        #=> "complete"
 
 cmd.pending?     #=> false
@@ -267,53 +304,55 @@ A status of `success` is returned even if the command has **NOT** been executed.
 > Metadata may also be passed to enrich your fault response.
 
 ```ruby
-class CalculatePower < Lite::Command::Base
+class DecryptSecretMessage < 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" }
-      )
+    if context.encrypted_message.empty?
+      noop!("No message to decrypt")
+    elsif context.encrypted_message.start_with?("== womp")
+      invalid!("Invalid message start value", i18n: "gb.invalid_start_value")
+    elsif context.encrypted_message.algo?(OldAlgo)
+      failure!("Unsafe encryption algo detected")
     else
-      ctx.result = ctx.a ** ctx.b
+      context.decrypted_message = SecretMessage.decrypt(ctx.encrypted_message)
     end
-  rescue DivisionError => e
-    error!("Cathcing it myself")
+  rescue CryptoError => e
+    Apm.report_error(e)
+    error!("Failed decryption due to: #{e}")
   end
 
 end
 
-cmd = CalculatePower.call(a: 1, b: 3)
-cmd.status   #=> "noop"
-cmd.reason   #=> "Anything to the power of 1 is 1"
-cmd.metadata #=> { i18n: "some.key" }
+cmd = DecryptSecretMessage.call(encrypted_message: "2jk3hjeh2hj2jh")
+cmd.status   #=> "invalid"
+cmd.reason   #=> "Invalid message start value"
+cmd.metadata #=> { i18n: "gb.invalid_start_value" }
 
 cmd.success? #=> false
-cmd.noop?    #=> true
-cmd.noop?("Other reason") #=> false
-cmd.invalid? #=> false
+cmd.noop?    #=> false
+cmd.invalid? #=> true
+cmd.invalid?("Other reason") #=> false
 cmd.failure? #=> false
 cmd.error?   #=> false
 
 # `success` or `noop`
-cmd.ok?      #=> true
+cmd.ok?      #=> false
 cmd.ok?("Other reason") #=> false
 
 # NOT `success`
 cmd.fault?   #=> true
 cmd.fault?("Other reason") #=> false
+
+# `invalid` or `failure` or `error`
+cmd.bad?     #=> true
+cmd.bad?("Other reason") #=> false
 ```
 
-## Callbacks
+## Hooks
 
-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.
+Use hooks 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
@@ -332,11 +371,10 @@ called for a failed command with a successful child command.
 
 ### Status Hooks
 
-Define one or more callbacks that are called during transitions
-between states.
+Define one or more callbacks that are called during transitions between states.
 
 ```ruby
-class CalculatePower < Lite::Command::Base
+class DecryptSecretMessage < Lite::Command::Base
 
   def call
     # ...
@@ -363,12 +401,32 @@ class CalculatePower < Lite::Command::Base
 end
 ```
 
+### Attribute Hooks
+
+Define before attribtue validation callbacks.
+
+```ruby
+class DecryptSecretMessage < Lite::Command::Base
+
+  def call
+    # ...
+  end
+
+  private
+
+  def on_before_validation
+    # eg: Normalize context data
+  end
+
+end
+```
+
 ### Execution Hooks
 
 Define before and after callbacks to call around execution.
 
 ```ruby
-class CalculatePower < Lite::Command::Base
+class DecryptSecretMessage < Lite::Command::Base
 
   def call
     # ...
@@ -393,7 +451,7 @@ Define one or more callbacks that are called after execution for
 specific statuses.
 
 ```ruby
-class CalculatePower < Lite::Command::Base
+class DecryptSecretMessage < Lite::Command::Base
 
   def call
     # ...
@@ -429,16 +487,16 @@ end
 
 ## 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`.
+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
+class DecryptSecretMessage < Lite::Command::Base
 
   def call
-    context.merge!(some_other: "required value")
-    CalculateSqrt.call(context)
+    context.merge!(decryption_key: ENV["DECRYPT_KEY"])
+    ValidateSecretMessage.call(context)
   end
 
 end
@@ -446,26 +504,24 @@ 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!`. Any `reason` and `metadata` will
-be bubbled up from the original fault.
+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!`. Any `reason` and
+`metadata` will be bubbled up from the original fault.
 
 ```ruby
-class CalculatePower < Lite::Command::Base
+class DecryptSecretMessage < Lite::Command::Base
 
   def call
-    command = CalculateSqrt.call(context.merge!(some_other: "required value"))
+    context.merge!(decryption_key: ENV["DECRYPT_KEY"])
+    cmd = ValidateSecretMessage.call(context)
 
-    if command.noop?("Sqrt of 1 is 1")
-      # Manually throw a specific fault
-      invalid!(command)
+    if cmd.invalid?("Invalid magic numbers")
+      error!(cmd) # Manually throw a specific fault
     elsif command.fault?
-      # Automatically throws a matching fault
-      throw!(command)
+      throw!(cmd) # Automatically throws a matching fault
     else
-      # Success, do nothing
+      context.decrypted_message = SecretMessage.decrypt(ctx.encrypted_message)
     end
   end
 
@@ -483,14 +539,14 @@ This is useful for composing multiple steps into one call.
 > 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`
 
-> [!IMPORTANT]
+> [!WARNING]
 > Do **NOT** define a call method in this class. The sequence logic is
 > automatically defined by the sequence class.
 
 ```ruby
 class ProcessCheckout < Lite::Command::Sequence
 
-  attribute :user, required: true, filled: true
+  required :user
 
   step FinalizeInvoice
   step ChargeCard, if: :card_available?
@@ -513,13 +569,12 @@ seq = ProcessCheckout.call(...)
 
 ## 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.
+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 = DecryptSecretMessage.call(...)
 command.to_hash #=> {
                 #=>   index: 1,
                 #=>   cmd_id: "018c2b95-b764-7615-a924-cc5b910ed1e5",
@@ -543,7 +598,7 @@ command.to_hash #=> {
 ### Disable Instance Calls
 
 ```ruby
-class CalculatePower < Lite::Command::Base
+class DecryptSecretMessage < Lite::Command::Base
 
   private_class_method :new
 
@@ -553,48 +608,10 @@ class CalculatePower < Lite::Command::Base
 
 end
 
-CalculatePower.new(...).call
+DecryptSecretMessage.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
 
 `rails g command NAME` will generate the following file:

data/lib/generators/lite/command/install_generator.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Lite
+  module Command
+    class InstallGenerator < Rails::Generators::Base
+
+      source_root File.expand_path("../templates", __FILE__)
+
+      def copy_initializer_file
+        copy_file("install.rb", "config/initializers/lite_command.rb")
+      end
+
+    end
+  end
+end

data/lib/generators/lite/command/templates/install.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+Lite::Command.configure do |config|
+  config.raise_dynamic_faults = false
+end