cmdx 0.1.0

data/docs/parameters/definitions.md

@@ -0,0 +1,123 @@
+## Parameters - Definitions
+
+Parameters provide a contract to verify that a task only executes if the arguments
+of a call match.
+
+## Basics
+
+Parameters are defined based on methods that can be delegated to a source object
+(default `:context`) or keys on a hash. Parameters are automatically defined as
+attributes within the task instance. `optional` parameters that do not respond or
+missing the hash key will still delegate but return `nil` as a value.
+
+```ruby
+class DetermineBoxSizeTask < CMDx::Task
+
+  # Must be passed as call arguments
+  required :material
+
+  # Returns value if passed as a call arguments, else returns nil
+  optional :depth
+
+  # Define multiple parameters one line
+  optional :width, :height
+
+  def call
+    material #=> "cardboard"
+    depth    #=> nil
+    height   #=> 12
+    width    #=> 24
+  end
+
+end
+
+# Initializes local variables matching the parameter name
+DetermineBoxSizeTask.call(material: "cardboard", height: 12, width: 24)
+```
+
+## Source
+
+Parameters will be delegated to the task context by default but any delegatable
+object within the task will do.
+
+```ruby
+class UpdateUserDetailsTask < CMDx::Task
+
+  # Default (:context)
+  required :user
+
+  # Defined parameter
+  required :email, source: :user
+
+  # Proc or lambda
+  optional :address, source: -> { user.address }
+
+  # Symbol or string
+  optional :name, source: :company
+
+  def call
+    user    #=> <User #a1b2c3d>
+    email   #=> "bill@bigcorp.com"
+    address #=> "123 Maple St, Miami, Fl 33023"
+    name    #=> "Big Corp."
+  end
+
+  private
+
+  def company
+    user.account.company
+  end
+
+end
+
+# Hash or delegatable object
+user = User.new(email: "bill@bigcorp.com")
+UpdateUserDetailsTask.call(user: user)
+```
+
+## Nesting
+
+Nesting builds upon parameter source option. Build complex parameter blocks that
+delegate to the parent parameter automatically.
+
+```ruby
+class UpdateUserDetailsTask < CMDx::Task
+
+  required :address do
+    required :street1
+    optional :street2
+  end
+
+  optional :locality do
+    required :city, :state # Required if locality argument is passed
+    optional :zipcode
+  end
+
+  def call
+    address  #=> { city: "Miami", state: "Fl" }
+    street1  #=> "123 Maple St."
+    street2  #=> nil
+
+    locality #=> { city: "Miami", state: "Fl" }
+    city     #=> "Miami"
+    state    #=> "Fl"
+    zipcode  #=> nil
+  end
+
+end
+
+# Hash or delegatable object
+address = Address.new(street1: "123 Maple St.")
+locality = { city: "Miami", state: "Fl" }
+UpdateUserDetailsTask.call(address: address, locality: locality)
+```
+
+> [!NOTE]
+> Optional parent parameters that have required child parameters will only have
+> the child parameters be required if the parent option is a delegatable source
+> or default value.
+
+---
+
+- **Prev:** [Parameters](https://github.com/drexed/cmdx/blob/main/docs/parameters.md)
+- **Next:** [Namespacing](https://github.com/drexed/cmdx/blob/main/docs/parameters/namespacing.md)

data/docs/parameters/namespacing.md

@@ -0,0 +1,57 @@
+# Parameters - Namespacing
+
+Parameters can have the delegated method prefixed and/or suffixed to
+prevent clashing where the source object have methods with the same name.
+
+`:prefix` and `:suffix` can be used independently or both at the same time.
+
+## With fixed value
+
+```ruby
+class DetermineBoxSizeTask < CMDx::Task
+
+  required :width, prefix: :before_
+  required :height, suffix: "_after"
+
+  def call
+    before_width #=> 1
+    height_after #=> 2
+  end
+
+end
+
+# Call arguments match the parameter names
+DetermineBoxSizeTask.call(width: 1, height: 2)
+```
+
+## With source name
+
+```ruby
+class DetermineBoxSizeTask < CMDx::Task
+
+  # Default (:context) as source
+  optional :height, prefix: true
+
+  # Custom source
+  optional :width, source: :account, suffix: true
+
+  def call
+    context_height #=> 1
+    width_account  #=> 2
+  end
+
+end
+
+# Call arguments match the parameter names
+account = Account.new(width: 2)
+DetermineBoxSizeTask.call(height: 1, account: account)
+```
+
+> [!NOTE]
+> `:prefix` or `:suffix` with a custom source and a fixed value
+> will always return the fixed value without the source.
+
+---
+
+- **Prev:** [Definitions](https://github.com/drexed/cmdx/blob/main/docs/parameters/definitions.md)
+- **Next:** [Coercions](https://github.com/drexed/cmdx/blob/main/docs/parameters/coercions.md)

data/docs/parameters/validations.md

@@ -0,0 +1,312 @@
+# Parameters - Validations
+
+Parameter values can be validated using one of the built-in validators. Build custom validators
+to check parameter values against your own business logic. `i18n` internalization is supported
+out of the box.
+
+Built-in validators are: [Presence](#presence), [Format](#format), [Exclusion](#exclusion),
+[Inclusion](#inclusion), [Length](#length), [Numeric](#numeric), [Custom](#custom)
+
+All validators support the following common options:
+
+| Option       | Description |
+| ------------ | ----------- |
+| `:allow_nil` | Skip validation if the parameter value is `nil`. |
+| `:if`        | Specifies a callable method, proc or string to determine if the validation should occur. |
+| `:unless`    | Specifies a callable method, proc, or string to determine if the validation should not occur. |
+| `:message`   | The error message to use for a violation. Fallback for any error key below that's not provided. |
+
+> [!NOTE]
+> Validators on `optional` parameters will only be executed if they are supplied as
+> call arguments.
+
+## Presence
+
+Validates that the specified parameter value is not empty. If you want to validate the
+presence of a boolean field (where the real values are true and false), you will
+want to use `inclusion: { in: [true, false] }`.
+
+```ruby
+class UpdateUserDetailsTask < CMDx::Task
+
+  # Boolean
+  required :username, presence: true
+
+  # With custom error message
+  optional :email, presence: { message: "must not be empty" }
+
+  def call
+    # Do work...
+  end
+
+end
+```
+
+## Format
+
+Validates whether the specified parameter value is of the correct form,
+going by the regular expression provided.
+
+```ruby
+class UpdateUserDetailsTask < CMDx::Task
+
+  # With
+  required :username, format: { with: /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\z/i }
+
+  # Without (with proc if conditional)
+  optional :email, format: { without: /NOSPAM/, if: proc { Current.account.spam_check? } }
+
+  def call
+    # Do work...
+  end
+
+end
+```
+
+Constraint options:
+
+| Option     | Description |
+| ---------- | ----------- |
+| `:with`    | Regular expression that if the parameter value matches will result in a successful validation. |
+| `:without` | Regular expression that if the parameter value does not match will result in a successful validation. |
+
+## Exclusion
+
+Validates that the specified parameter is not in a particular enumerable object.
+
+```ruby
+class DetermineBoxSizeTask < CMDx::Task
+
+  # Array
+  required :width, exclusion: { in: [12, 24, 36] }
+
+  # Range (with allow nil)
+  optional :length, exclusion: { in: 12..36, allow_nil: true }
+
+  def call
+    # Do work...
+  end
+
+end
+```
+
+Constraint options:
+
+| Option       | Description |
+| ------------ | ----------- |
+| `:in`        | An enumerable object of unavailable items such as an array or range. |
+| `:within`    | A synonym (or alias) for `:in` |
+
+Other options:
+
+| Option            | Description |
+| ----------------- | ----------- |
+| `:of_message`     | The error message if the parameter value is in array. (default: "must not be one of: %{values}") |
+| `:in_message`     | The error message if the parameter value is in range. (default: "must not be within %{min} and %{max}") |
+| `:within_message` | A synonym (or alias) for `:in_message` |
+
+## Inclusion
+
+Validates that the specified parameter value is in a particular enumerable object.
+
+```ruby
+class DetermineBoxSizeTask < CMDx::Task
+
+  # Array
+  required :width, inclusion: { in: [12, 24, 36] }
+
+  # Range (with custom error message)
+  optional :length, inclusion: { in: 12..36, unless: :length_check? }
+
+  def call
+    # Do work...
+  end
+
+  private
+
+  def skip_length_check?
+    false
+  end
+
+end
+```
+
+Constraint options:
+
+| Option       | Description |
+| ------------ | ----------- |
+| `:in`        | An enumerable object of available items such as an array or range. |
+| `:within`    | A synonym (or alias) for `:in` |
+
+Other options:
+
+| Option            | Description |
+| ----------------- | ----------- |
+| `:of_message`     | The error message if the parameter value is not in array. (default: "must be one of: %{values}") |
+| `:in_message`     | The error message if the parameter value is not in range. (default: "must be within %{min} and %{max}") |
+| `:within_message` | A synonym (or alias) for `:in_message` |
+
+## Length
+
+Validates that the specified parameter value matches the length restrictions supplied.
+Only one constraint option can be used at a time apart from `:min` and `:max`
+that can be combined together:
+
+```ruby
+class UpdateUserDetailsTask < CMDx::Task
+
+  # Range (with custom error message)
+  required :email, length: { within: 12..36, message: "must be within range" }
+  required :username, length: { not_within: 48..96 }
+
+  # Boundary
+  optional :first_name, length: { min: 24 }
+  optional :middle_name, length: { max: 48 }
+  optional :last_name, length: { min: 24, max: 48 }
+
+  # Exact
+  required :title, length: { is: 24 }
+  required :count, length: { is_not: 48 }
+
+  def call
+    # Do work...
+  end
+
+end
+```
+
+Constraint options:
+
+| Option        | Description |
+| ------------- | ----------- |
+| `:within`     | A range specifying the minimum and maximum size of the parameter value. |
+| `:not_within` | A range specifying the minimum and maximum size of the parameter value it's not to be. |
+| `:in`         | A synonym (or alias) for `:within` |
+| `:not_in`     | A synonym (or alias) for `:not_within` |
+| `:min`        | The minimum size of the parameter value. |
+| `:max`        | The maximum size of the parameter value. |
+| `:is`         | The exact size of the parameter value. |
+| `:is_not`     | The exact size of the parameter value it's not to be. |
+
+Other options:
+
+| Option                | Description |
+| --------------------- | ----------- |
+| `:within_message`     | The error message if the parameter value is within the value range. (default: "length must not be within %{min} and %{max}") |
+| `:not_within_message` | The error message if the parameter value is not within the value range. (default: "length must be within %{min} and %{max}") |
+| `:in_message`         | A synonym (or alias) for `:within_message` |
+| `:not_in_message`     | A synonym (or alias) for `:not_within_message` |
+| `:min_message`        | The error message if the parameter value is below the min value. (default: "length must be at least %{min}") |
+| `:max_message`        | The error message if the parameter value is above the min value. (default: "length must be at most %{max}") |
+| `:is_message`         | The error message if the parameter value is the exact value. (default: "length must be %{is}") |
+| `:is_not_message`     | The error message if the parameter value is not the exact value. (default: "length must not be %{is_not}") |
+
+## Numeric
+
+Validates that the specified parameter value matches the numeric restrictions supplied.
+Only one constraint option can be used at a time apart from `:min` and `:max`
+that can be combined together:
+
+```ruby
+class UpdateUserDetailsTask < CMDx::Task
+
+  # Range (with custom error message)
+  required :height, numeric: { within: 36..196 }
+  required :weight, numeric: { not_within: 0..5 }
+
+  # Boundary
+  optional :dob_year, numeric: { min: 1900 }
+  optional :dob_day, numeric: { max: 31 }
+  optional :dob_month, numeric: { min: 1, max: 12 }
+
+  # Exact
+  required :age, numeric: { is: 18 }
+  required :parents, numeric: { is_not: 0 }
+
+  def call
+    # Do work...
+  end
+
+end
+```
+
+Constraint options:
+
+| Option        | Description |
+| ------------- | ----------- |
+| `:within`     | A range specifying the minimum and maximum size of the parameter value. |
+| `:not_within` | A range specifying the minimum and maximum size of the parameter value it's not to be. |
+| `:in`         | A synonym (or alias) for `:within` |
+| `:not_in`     | A synonym (or alias) for `:not_within` |
+| `:min`        | The minimum size of the parameter value. |
+| `:max`        | The maximum size of the parameter value. |
+| `:is`         | The exact size of the parameter value. |
+| `:is_not`     | The exact size of the parameter value it's not to be. |
+
+Other options:
+
+| Option                | Description |
+| --------------------- | ----------- |
+| `:within_message`     | The error message if the parameter value is within the value range. (default: "must not be within %{min} and %{max}") |
+| `:not_within_message` | The error message if the parameter value is not within the value range. (default: "must be within %{min} and %{max}") |
+| `:in_message`         | A synonym (or alias) for `:within_message` |
+| `:not_in_message`     | A synonym (or alias) for `:not_within_message` |
+| `:min_message`        | The error message if the parameter value is below the min value. (default: "must be at least %{min}") |
+| `:max_message`        | The error message if the parameter value is above the min value. (default: "must be at most %{max}") |
+| `:is_message`         | The error message if the parameter value is the exact value. (default: "must be %{is}") |
+| `:is_not_message`     | The error message if the parameter value is not the exact value. (default: "must not be %{is_not}") |
+
+## Custom
+
+Validate the specified parameter value using custom validators.
+
+```ruby
+class TLDValidator
+  def self.call(value, options)
+    tld = options.dig(:custom, :tld) || %w[com]
+    value.ends_with?(tld)
+  end
+end
+
+class UpdateUserDetailsTask < CMDx::Task
+
+  # Basic
+  required :unconfirmed_email, custom: { validator: TLDValidator }
+
+  # Passable options (with custom error message)
+  optional :confirmed_email, custom: { validator: TLDValidator, tld: %w[com net org], message: "is not valid" }
+
+  def call
+    # Do work...
+  end
+
+end
+```
+
+Constraint options:
+
+| Option       | Description |
+| ------------ | ----------- |
+| `:validator` | Callable class that returns true or false. |
+
+## Results
+
+The following represents a result output example of a failed validation.
+
+```ruby
+result = DetermineBoxSizeTask.call
+result.state    #=> "interrupted"
+result.status   #=> "failed"
+result.metadata #=> {
+                #=>   reason: "email format is not valid. username cannot be empty.",
+                #=>   messages: {
+                #=>     email: ["format is not valid"],
+                #=>     username: ["cannot be empty"]
+                #=>   }
+                #=> }
+```
+
+---
+
+- **Prev:** [Coercions](https://github.com/drexed/cmdx/blob/main/docs/parameters/coercions.md)
+- **Next:** [Defaults](https://github.com/drexed/cmdx/blob/main/docs/parameters/defaults.md)

data/docs/tips_and_tricks.md

@@ -0,0 +1,79 @@
+# Tips & Tricks
+
+## Configuration
+
+Configure `CMDx` to get the most out of your Rails application.
+
+```ruby
+CMDx.configure do |config|
+  # Redirect your logs through the app defined logger:
+  config.logger = Rails.logger
+
+  # Adjust the log level to write depending on the environment:
+  config.logger.level = Rails.env.development? ? Logger::DEBUG : Logger::INFO
+
+  # Structure log lines using a pre-built or custom formatter:
+  config.logger.formatter = CMDx::LogFormatters::Logstash.new
+end
+```
+
+## Setup
+
+While not required, a common setup involves creating an `app/cmds` directory
+to place all of your tasks and batches under, eg:
+
+```txt
+/app
+  /cmds
+    /notifications
+      - deliver_email_task.rb
+      - post_slack_message_task.rb
+      - send_carrier_pigeon_task.rb
+      - batch_deliver_all.rb
+    - process_order_task.rb
+    - application_batch.rb
+    - application_task.rb
+```
+
+> [!TIP]
+> Prefix batches with `batch_` and suffix tasks with `_task` to they convey their function.
+> Use a verb+noun naming structure to convey the work that will be performed, eg:
+> `BatchDeliverNotifications` or `DeliverEmailTask`
+
+## Parameters
+
+Use the Rails `with_options` as an elegant way to factor duplication
+out of options passed to a series of parameter definitions. The following
+are a few common example:
+
+```ruby
+class UpdateUserDetailsTask < CMDx::Task
+
+  # Apply `type: :string, presence: true` to this set of parameters:
+  with_options(type: :string, presence: true) do
+    required :email, format: { with: /\A([^@\s]+)@((?:[-a-z0-9]+\.)+[a-z]{2,})\z/i }
+    optional :first_name, :last_name
+  end
+
+  required :address do
+    # Apply the `address_*` prefix to this set of nested parameters:
+    with_options(prefix: :address_) do
+      required :city, :country
+      optional :state
+    end
+  end
+
+  def call
+    # Do work
+  end
+
+end
+```
+
+[Learn More](https://api.rubyonrails.org/classes/Object.html#method-i-with_options)
+about its usages on the official Rails docs.
+
+---
+
+- **Prev:** [Logging](https://github.com/drexed/cmdx/blob/main/docs/logging.md)
+- **Next:** [Example](https://github.com/drexed/cmdx/blob/main/docs/example.md)

data/lib/cmdx/batch.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module CMDx
+  class Batch < Task
+
+    Group = Struct.new(:tasks, :options)
+
+    class << self
+
+      def batch_groups
+        @batch_groups ||= []
+      end
+
+      def process(*tasks, **options)
+        batch_groups << Group.new(
+          tasks.flatten.map do |task|
+            next task if task <= Task
+
+            raise ArgumentError, "must be a Batch or Task"
+          end,
+          options
+        )
+      end
+
+    end
+
+    def call
+      self.class.batch_groups.each do |group|
+        next unless __cmdx_eval(group.options)
+
+        batch_halt = group.options[:batch_halt] || task_setting(:batch_halt)
+
+        group.tasks.each do |task|
+          task_result = task.call(context)
+          next unless Array(batch_halt).include?(task_result.status)
+
+          throw!(task_result)
+        end
+      end
+    end
+
+  end
+end

data/lib/cmdx/coercions/array.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module CMDx
+  module Coercions
+    module Array
+
+      module_function
+
+      def call(value, _options = {})
+        Array(value)
+      end
+
+    end
+  end
+end

data/lib/cmdx/coercions/big_decimal.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module CMDx
+  module Coercions
+    module BigDecimal
+
+      DEFAULT_PRECISION = 14
+
+      module_function
+
+      def call(value, options = {})
+        BigDecimal(value, options[:precision] || DEFAULT_PRECISION)
+      rescue ArgumentError, TypeError
+        raise CoercionError, I18n.t(
+          "cmdx.coercions.into_a",
+          type: "big decimal",
+          default: "could not coerce into a big decimal"
+        )
+      end
+
+    end
+  end
+end

data/lib/cmdx/coercions/boolean.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module CMDx
+  module Coercions
+    module Boolean
+
+      FALSEY = /^(false|f|no|n|0)$/i
+      TRUTHY = /^(true|t|yes|y|1)$/i
+
+      module_function
+
+      def call(value, _options = {})
+        case value.to_s
+        when FALSEY then false
+        when TRUTHY then true
+        else
+          raise CoercionError, I18n.t(
+            "cmdx.coercions.into_a",
+            type: "boolean",
+            default: "could not coerce into a boolean"
+          )
+        end
+      end
+
+    end
+  end
+end

data/lib/cmdx/coercions/complex.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module CMDx
+  module Coercions
+    module Complex
+
+      module_function
+
+      def call(value, _options = {})
+        Complex(value)
+      rescue ArgumentError, TypeError
+        raise CoercionError, I18n.t(
+          "cmdx.coercions.into_a",
+          type: "complex",
+          default: "could not coerce into a complex"
+        )
+      end
+
+    end
+  end
+end