cmdx 0.5.0 → 1.0.1

data/docs/parameters/defaults.md

@@ -1,47 +1,280 @@
 # Parameters - Defaults
 
-Assign default values for parameters that return a `nil` value.
+Parameter defaults provide fallback values when arguments are not provided or
+resolve to `nil`. Defaults ensure tasks have sensible values for optional
+parameters while maintaining flexibility for callers to override when needed.
+Defaults work seamlessly with coercion, validation, and nested parameters.
+
+## Table of Contents
+
+- [TLDR](#tldr)
+- [Default Value Fundamentals](#default-value-fundamentals)
+  - [Fixed Value Defaults](#fixed-value-defaults)
+  - [Callable Defaults](#callable-defaults)
+- [Defaults with Type Coercion](#defaults-with-type-coercion)
+- [Defaults with Validation](#defaults-with-validation)
+- [Nested Parameter Defaults](#nested-parameter-defaults)
+
+## TLDR
+
+- **Defaults** - Provide fallback values when parameters not provided or are `nil`
+- **Fixed values** - `default: "normal"`, `default: true`, `default: []`
+- **Dynamic values** - `default: -> { Time.now }`, `default: :method_name` for callable defaults
+- **With coercion** - Defaults are subject to same type coercion as provided values
+- **With validation** - Defaults must pass same validation rules as provided values
+
+## Default Value Fundamentals
+
+> [!NOTE]
+> Defaults are specified using the `:default` option and are applied when a parameter value resolves to `nil`. This includes cases where optional parameters are not provided in call arguments or when source objects return `nil` values.
+
+### Fixed Value Defaults
+
+The simplest defaults use fixed values that are applied consistently:
+
+```ruby
+class ProcessUserOrderTask < CMDx::Task
+
+  required :user_id, type: :integer
+  optional :priority, type: :string, default: "normal"
+  optional :send_confirmation, type: :boolean, default: true
+  optional :max_retries, type: :integer, default: 3
+
+  optional :notification_tags, type: :array, default: []
+  optional :order_metadata, type: :hash, default: {}
+  optional :created_at, type: :datetime, default: -> { Time.now }
+
+  def call
+    user_id            #=> provided value (required)
+    priority           #=> "normal" if not provided
+    send_confirmation  #=> true if not provided
+    max_retries        #=> 3 if not provided
+    notification_tags  #=> [] if not provided
+    order_metadata     #=> {} if not provided
+    created_at         #=> current time if not provided
+  end
+
+end
+
+# Defaults applied for missing parameters
+ProcessUserOrderTask.call(user_id: 12345)
+# priority: "normal", send_confirmation: true, max_retries: 3, etc.
+
+# Explicit values override defaults
+ProcessUserOrderTask.call(
+  user_id: 12345,
+  priority: "urgent",
+  send_confirmation: false,
+  notification_tags: ["rush_order"]
+)
+```
+
+### Callable Defaults
+
+> [!TIP]
+> Use procs, lambdas, or method symbols for dynamic defaults that are evaluated at parameter resolution time. This is especially useful for timestamps, UUIDs, and context-dependent values.
 
 ```ruby
-class DetermineBoxSizeTask < CMDx::Task
+class SendOrderNotificationTask < CMDx::Task
+
+  required :order_id, type: :integer
 
-  # Fixed value
-  required :width, default: 12
+  # Dynamic defaults using procs
+  optional :sent_at, type: :datetime, default: -> { Time.now }
+  optional :tracking_id, type: :string, default: -> { SecureRandom.uuid }
 
-  # Proc or lambda
-  optional :length, default: -> { Current.account.usa? ? 12 : 18 }
+  # Environment-aware defaults
+  optional :notification_service, type: :string, default: -> { Rails.env.production? ? "sendgrid" : "mock" }
+  optional :sender_email, type: :string, default: -> { Rails.application.credentials.sender_email }
 
-  # Symbol or string
-  optional :depth, default: :depth_by_country
+  # Method symbol defaults
+  optional :template_name, type: :string, default: :determine_template
+  optional :delivery_time, type: :datetime, default: :calculate_delivery_window
 
   def call
-    width  #=> 12
-    length #=> 18
-    depth  #=> 48
+    sent_at              #=> current time when accessed
+    tracking_id          #=> unique UUID when accessed
+    notification_service #=> production or test service
+    sender_email         #=> configured sender email
+    template_name        #=> result of determine_template method
+    delivery_time        #=> result of calculate_delivery_window method
   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
+  def determine_template
+    order.priority == "urgent" ? "urgent_order" : "standard_order"
+  end
+
+  def calculate_delivery_window
+    order.priority == "urgent" ? 15.minutes.from_now : 1.hour.from_now
+  end
+
+  def order
+    @order ||= Order.find(order_id)
   end
 
 end
+```
+
+## Defaults with Type Coercion
+
+> [!IMPORTANT]
+> Defaults work seamlessly with type coercion, with the default value being subject to the same coercion rules as provided values.
+
+```ruby
+class ConfigureOrderSettingsTask < CMDx::Task
+
+  # String defaults coerced to integers
+  optional :max_items, type: :integer, default: "50"
+
+  # JSON string defaults coerced to hash
+  optional :shipping_config, type: :hash, default: '{"carrier": "ups", "speed": "standard"}'
 
-# Initializes with default values
-DetermineBoxSizeTask.call(width: nil, length: nil)
+  # String defaults coerced to arrays
+  optional :allowed_countries, type: :array, default: '["US", "CA", "UK"]'
+
+  # String defaults coerced to booleans
+  optional :require_signature, type: :boolean, default: "true"
+
+  # String defaults coerced to dates
+  optional :embargo_date, type: :date, default: "2024-01-01"
+
+  # Dynamic defaults with coercion
+  optional :order_number, type: :string, default: -> { Time.now.to_i }
+
+  def call
+    max_items         #=> 50 (integer)
+    shipping_config   #=> {"carrier" => "ups", "speed" => "standard"} (hash)
+    allowed_countries #=> ["US", "CA", "UK"] (array)
+    require_signature #=> true (boolean)
+    embargo_date      #=> Date object
+    order_number      #=> "1640995200" (string from integer)
+  end
+
+end
 ```
 
-> [!NOTE]
-> Defaults are subject to coercion and validations so take care setting
-> the fallback value to contain valid conditions.
+## Defaults with Validation
+
+> [!WARNING]
+> Default values are subject to the same validation rules as provided values, ensuring consistency and catching configuration errors early.
+
+```ruby
+class ValidateOrderPriorityTask < CMDx::Task
+
+  required :order_id, type: :integer
+
+  # Default must pass inclusion validation
+  optional :priority, type: :string, default: "standard",
+    inclusion: { in: %w[low standard high urgent] }
+
+  # Numeric default with range validation
+  optional :processing_timeout, type: :integer, default: 300,
+    numeric: { min: 60, max: 3600 }
+
+  # Email default with format validation
+  optional :escalation_email, type: :string,
+    default: -> { "support@#{Rails.application.config.domain}" },
+    format: { with: /@/ }
+
+  # Custom validation with default
+  optional :approval_code, type: :string, default: :generate_approval_code,
+    custom: { validator: ApprovalCodeValidator }
+
+  def call
+    priority           #=> "standard" (validated against inclusion list)
+    processing_timeout #=> 300 (validated within range)
+    escalation_email   #=> support email (validated format)
+    approval_code      #=> generated code (custom validated)
+  end
+
+  private
+
+  def generate_approval_code
+    "APV_#{SecureRandom.hex(8).upcase}"
+  end
+
+end
+```
+
+## Nested Parameter Defaults
+
+```ruby
+class ProcessOrderShippingTask < CMDx::Task
+
+  required :order_id, type: :integer
+
+  # Parent parameter with default
+  optional :shipping_details, type: :hash, default: {} do
+    optional :carrier, type: :string, default: "fedex"
+    optional :expedited, type: :boolean, default: false
+    optional :insurance_required, type: :boolean, default: -> { order_value > 500 }
+
+    optional :delivery_address, type: :hash, default: -> { customer_default_address } do
+      optional :country, type: :string, default: "US"
+      optional :state, type: :string, default: -> { determine_default_state }
+      optional :requires_appointment, type: :boolean, default: false
+    end
+  end
+
+  # Complex nested defaults
+  optional :notification_preferences, type: :hash, default: -> { customer_notification_defaults } do
+    optional :email_updates, type: :boolean, default: true
+    optional :sms_updates, type: :boolean, default: false
+
+    optional :delivery_window, type: :hash, default: {} do
+      optional :preferred_time, type: :string, default: "anytime"
+      optional :weekend_delivery, type: :boolean, default: false
+    end
+  end
+
+  def call
+    # Parent defaults applied when not provided
+    shipping_details         #=> {} if not provided
+    notification_preferences #=> customer defaults if not provided
+
+    # Child defaults (when parent exists)
+    carrier                  #=> "fedex"
+    expedited                #=> false
+    insurance_required       #=> true if order > $500
+    country                  #=> "US"
+    state                    #=> determined by logic
+    email_updates            #=> true
+    preferred_time           #=> "anytime"
+    weekend_delivery         #=> false
+  end
+
+  private
+
+  def order
+    @order ||= Order.find(order_id)
+  end
+
+  def order_value
+    order.total_amount
+  end
+
+  def customer_default_address
+    order.customer.default_shipping_address&.to_hash || {}
+  end
+
+  def determine_default_state
+    order.customer.billing_address&.state || "CA"
+  end
+
+  def customer_notification_defaults
+    prefs = order.customer.notification_preferences
+    {
+      email_updates: prefs.email_enabled?,
+      sms_updates: prefs.sms_enabled?
+    }
+  end
+
+end
+```
 
 ---
 
-- **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)
+- **Prev:** [Parameters - Validations](validations.md)
+- **Next:** [Callbacks](../callbacks.md)

data/docs/parameters/definitions.md

@@ -1,123 +1,298 @@
-## Parameters - Definitions
+# Parameters - Definitions
 
-Parameters provide a contract to verify that a task only executes if the arguments
-of a call match.
+Parameters provide a contract to verify that task execution arguments match expected requirements and structure. They define the interface between task callers and task implementation, enabling automatic validation, type coercion, and method generation for clean parameter access within tasks.
 
-## Basics
+## Table of Contents
 
-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.
+- [TLDR](#tldr)
+- [Parameter Fundamentals](#parameter-fundamentals)
+- [Parameter Sources](#parameter-sources)
+- [Nested Parameters](#nested-parameters)
+- [Parameter Method Generation](#parameter-method-generation)
+- [Error Handling](#error-handling)
 
-```ruby
-class DetermineBoxSizeTask < CMDx::Task
+## TLDR
+
+- **Required/Optional** - Define with `required :param` and `optional :param` class methods
+- **Method generation** - Parameters become instance methods for easy access
+- **Sources** - Default `:context` source, or custom with `source: :user`
+- **Nested params** - Complex structures with `required :address do ... end`
+- **Call interface** - Parameters passed as keyword arguments to `TaskClass.call(param: value)`
+
+## Parameter Fundamentals
+
+Parameters are defined using `required` and `optional` class methods that automatically create accessor methods within task instances. Parameters are matched from call arguments and made available as instance methods.
+
+> [!IMPORTANT]
+> Required parameters must be provided in call arguments or task execution will fail.
 
-  # Must be passed as call arguments
-  required :material
+### Basic Parameter Definition
 
-  # Returns value if passed as a call arguments, else returns nil
-  optional :depth
+```ruby
+class CreateOrderTask < CMDx::Task
+  # Must be provided in call arguments
+  required :order_id
+
+  # Optional - returns nil if not provided
+  optional :priority
 
-  # Define multiple parameters one line
-  optional :width, :height
+  # Multiple parameters in one declaration
+  required :customer_id, :product_id
+  optional :notes, :shipping_method
 
   def call
-    material #=> "cardboard"
-    depth    #=> nil
-    height   #=> 12
-    width    #=> 24
+    order_id        #=> 123 (from call arguments)
+    priority        #=> "high" or nil
+    customer_id     #=> 456 (from call arguments)
+    shipping_method #=> "express" or nil
   end
-
 end
 
-# Initializes local variables matching the parameter name
-DetermineBoxSizeTask.call(material: "cardboard", height: 12, width: 24)
+# Parameters passed as keyword arguments
+CreateOrderTask.call(
+  order_id: 123,
+  customer_id: 456,
+  product_id: 789,
+  priority: "high",
+  shipping_method: "express"
+)
 ```
 
-## Source
+## Parameter Sources
 
-Parameters will be delegated to the task context by default but any delegatable
-object within the task will do.
+Parameters delegate to source objects within the task context. The default source is `:context`, but any accessible method or object can serve as a parameter source.
+
+### Default Context Source
 
 ```ruby
-class UpdateUserDetailsTask < CMDx::Task
+class UpdateUserTask < CMDx::Task
+  # Delegates to context.user_id (default source)
+  required :user_id
 
-  # Default (:context)
-  required :user
+  # Explicitly specified context source
+  required :email, source: :context
 
-  # Defined parameter
-  required :email, source: :user
+  def call
+    user_id #=> delegates to context.user_id
+    email   #=> delegates to context.email
+  end
+end
 
-  # Proc or lambda
-  optional :address, source: -> { user.address }
+UpdateUserTask.call(user_id: 123, email: "user@example.com")
+```
 
-  # Symbol or string
-  optional :name, source: :company
+### Custom Object Sources
+
+```ruby
+class ProcessUserOrderTask < CMDx::Task
+  # Delegate to user object
+  required :name, :email, source: :user
+
+  # Delegate to order object
+  required :total, :status, source: :order
+  optional :discount, source: :order
 
   def call
-    user    #=> <User #a1b2c3d>
-    email   #=> "bill@bigcorp.com"
-    address #=> "123 Maple St, Miami, Fl 33023"
-    name    #=> "Big Corp."
+    name     #=> delegates to user.name
+    email    #=> delegates to user.email
+    total    #=> delegates to order.total
+    status   #=> delegates to order.status
+    discount #=> delegates to order.discount
   end
 
   private
 
-  def company
-    user.account.company
+  def user
+    @user ||= User.find(context.user_id)
   end
 
+  def order
+    @order ||= user.orders.find(context.order_id)
+  end
 end
 
-# Hash or delegatable object
-user = User.new(email: "bill@bigcorp.com")
-UpdateUserDetailsTask.call(user: user)
+ProcessUserOrderTask.call(user_id: 123, order_id: 456)
 ```
 
-## Nesting
-
-Nesting builds upon parameter source option. Build complex parameter blocks that
-delegate to the parent parameter automatically.
+### Dynamic Sources
 
 ```ruby
-class UpdateUserDetailsTask < CMDx::Task
+class ProcessDynamicParameterTask < CMDx::Task
+  # Lambda source for dynamic resolution
+  required :company_name, source: -> { user.company }
+
+  # Method name sources
+  required :account_type, source: :determine_account_type
+  optional :access_level, source: :calculate_access_level
+
+  def call
+    company_name #=> resolved via lambda
+    account_type #=> result of determine_account_type method
+    access_level #=> result of calculate_access_level method
+  end
+
+  private
+
+  def user
+    @user ||= User.find(context.user_id)
+  end
+
+  def determine_account_type
+    user.premium? ? "premium" : "standard"
+  end
+
+  def calculate_access_level
+    user.admin? ? "admin" : "user"
+  end
+end
+```
+
+## Nested Parameters
+
+Nested parameters allow complex parameter structures where child parameters automatically inherit their parent as the source. This enables validation and access of structured data.
+
+> [!NOTE]
+> Child parameters are only required when their parent parameter is provided.
+
+### Basic Nesting
 
-  required :address do
-    required :street1
-    optional :street2
+```ruby
+class CreateShippingLabelTask < CMDx::Task
+  # Parent parameter with nested children
+  required :shipping_address do
+    required :street, :city, :state, :zip_code
+    optional :apartment_number
   end
 
-  optional :locality do
-    required :city, :state # Required if locality argument is passed
-    optional :zipcode
+  # Optional parent with required children
+  optional :billing_address do
+    required :street, :city # Only required if billing_address provided
+    optional :same_as_shipping
   end
 
   def call
-    address  #=> { city: "Miami", state: "Fl" }
-    street1  #=> "123 Maple St."
-    street2  #=> nil
+    # Parent parameter access
+    shipping_address #=> { street: "123 Main St", city: "Miami", ... }
+
+    # Child parameter access (delegates to parent)
+    street           #=> "123 Main St" (from shipping_address.street)
+    city             #=> "Miami" (from shipping_address.city)
+    apartment_number #=> nil (optional, not provided)
+  end
+end
+
+CreateShippingLabelTask.call(
+  shipping_address: {
+    street: "123 Main St",
+    city: "Miami",
+    state: "FL",
+    zip_code: "33101"
+  }
+)
+```
+
+### Multi-Level Nesting
 
-    locality #=> { city: "Miami", state: "Fl" }
-    city     #=> "Miami"
-    state    #=> "Fl"
-    zipcode  #=> nil
+```ruby
+class CreateUserProfileTask < CMDx::Task
+  required :user do
+    required :name, :email
+
+    required :profile do
+      required :age
+      optional :bio
+
+      optional :preferences do
+        optional :theme, :language
+        required :notifications  # Required if preferences provided
+      end
+    end
   end
 
+  def call
+    # Access at any nesting level
+    name  #=> delegates to user.name
+    email #=> delegates to user.email
+    age   #=> delegates to user.profile.age
+    theme #=> delegates to user.profile.preferences.theme
+  end
 end
+```
+
+## Parameter Method Generation
+
+Parameters automatically generate accessor methods that delegate to their configured sources.
+
+> [!TIP]
+> Parameter names become instance methods accessible within the task.
+
+```ruby
+class ProcessPaymentTask < CMDx::Task
+  # Standard method generation
+  required :payment_id # Generates: payment_id method
+
+  # Custom source with method name
+  required :account_name, source: :account # Generates: account_name method
+
+  # Nested parameter method generation
+  required :billing_info do
+    required :card_number  # Generates: card_number method
+    required :expiry_date  # Generates: expiry_date method
+  end
 
-# Hash or delegatable object
-address = Address.new(street1: "123 Maple St.")
-locality = { city: "Miami", state: "Fl" }
-UpdateUserDetailsTask.call(address: address, locality: locality)
+  def call
+    payment_id   #=> accesses context.payment_id
+    account_name #=> accesses account.account_name
+    card_number  #=> accesses billing_info.card_number
+    expiry_date  #=> accesses billing_info.expiry_date
+  end
+
+  private
+
+  def account
+    @account ||= Account.find(context.account_id)
+  end
+end
 ```
 
-> [!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.
+## Error Handling
+
+Parameter validation failures result in structured error information:
+
+> [!WARNING]
+> Invalid parameters will cause task execution to fail with detailed error messages.
+
+```ruby
+class ValidateUserTask < CMDx::Task
+  required :age, type: :integer, numeric: { min: 18, max: 120 }
+  required :email, type: :string, format: { with: /@/ }
+  optional :phone, type: :string, format: { with: /\A\d{10}\z/ }
+
+  def call
+    # Task logic here
+  end
+end
+
+# Invalid parameters
+result = ValidateUserTask.call(
+  age: "invalid",
+  email: "not-an-email",
+  phone: "123"
+)
+
+result.failed?  #=> true
+result.metadata
+#=> {
+#     reason: "age could not coerce into an integer. email format is not valid. phone format is not valid.",
+#     messages: {
+#       age: ["could not coerce into an integer"],
+#       email: ["format is not valid"],
+#       phone: ["format is not valid"]
+#     }
+#   }
+```
 
 ---
 
-- **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)
+- **Prev:** [Configuration](../configuration.md)
+- **Next:** [Parameters - Namespacing](namespacing.md)