cmdx 1.1.2 → 1.5.0

data/lib/cmdx/attribute.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Represents a configurable attribute within a CMDx task.
+  # Attributes define the data structure and validation rules for task parameters.
+  # They can be nested to create complex hierarchical data structures.
+  class Attribute
+
+    AFFIX = proc do |value, &block|
+      value == true ? block.call : value
+    end.freeze
+    private_constant :AFFIX
+
+    attr_accessor :task
+
+    attr_reader :name, :options, :children, :parent, :types
+
+    # Creates a new attribute with the specified name and configuration.
+    #
+    # @param name [Symbol, String] The name of the attribute
+    # @param options [Hash] Configuration options for the attribute
+    # @option options [Attribute] :parent The parent attribute for nested structures
+    # @option options [Boolean] :required Whether the attribute is required (default: false)
+    # @option options [Array<Class>, Class] :types The expected type(s) for the attribute value
+    # @option options [Symbol, String, Proc] :source The source of the attribute value
+    # @option options [Symbol, String] :as The method name to use for this attribute
+    # @option options [Symbol, String, Boolean] :prefix The prefix to add to the method name
+    # @option options [Symbol, String, Boolean] :suffix The suffix to add to the method name
+    # @option options [Object] :default The default value for the attribute
+    #
+    # @yield [self] Block to configure nested attributes
+    #
+    # @example
+    #   Attribute.new(:user_id, required: true, types: [Integer, String]) do
+    #     required :name, types: String
+    #     optional :email, types: String
+    #   end
+    def initialize(name, options = {}, &)
+      @parent = options.delete(:parent)
+      @required = options.delete(:required) || false
+      @types = Array(options.delete(:types) || options.delete(:type))
+
+      @name = name.to_sym
+      @options = options
+      @children = []
+
+      instance_eval(&) if block_given?
+    end
+
+    class << self
+
+      # Builds multiple attributes with the same configuration.
+      #
+      # @param names [Array<Symbol, String>] The names of the attributes to create
+      # @param options [Hash] Configuration options for the attributes
+      #
+      # @yield [self] Block to configure nested attributes
+      #
+      # @return [Array<Attribute>] Array of created attributes
+      #
+      # @raise [ArgumentError] When no names are provided or :as is used with multiple attributes
+      #
+      # @example
+      #   Attribute.build(:first_name, :last_name, required: true, types: String)
+      def build(*names, **options, &)
+        if names.none?
+          raise ArgumentError, "no attributes given"
+        elsif (names.size > 1) && options.key?(:as)
+          raise ArgumentError, ":as option only supports one attribute per definition"
+        end
+
+        names.filter_map { |name| new(name, **options, &) }
+      end
+
+      # Creates optional attributes (not required).
+      #
+      # @param names [Array<Symbol, String>] The names of the attributes to create
+      # @param options [Hash] Configuration options for the attributes
+      #
+      # @yield [self] Block to configure nested attributes
+      #
+      # @return [Array<Attribute>] Array of created optional attributes
+      #
+      # @example
+      #   Attribute.optional(:description, :tags, types: String)
+      def optional(*names, **options, &)
+        build(*names, **options.merge(required: false), &)
+      end
+
+      # Creates required attributes.
+      #
+      # @param names [Array<Symbol, String>] The names of the attributes to create
+      # @param options [Hash] Configuration options for the attributes
+      #
+      # @yield [self] Block to configure nested attributes
+      #
+      # @return [Array<Attribute>] Array of created required attributes
+      #
+      # @example
+      #   Attribute.required(:id, :name, types: [Integer, String])
+      def required(*names, **options, &)
+        build(*names, **options.merge(required: true), &)
+      end
+
+    end
+
+    # Checks if the attribute is required.
+    #
+    # @return [Boolean] true if the attribute is required, false otherwise
+    #
+    # @example
+    #   attribute.required? # => true
+    def required?
+      !!@required
+    end
+
+    # Determines the source of the attribute value.
+    #
+    # @return [Symbol] The source identifier for the attribute value
+    #
+    # @example
+    #   attribute.source # => :context
+    def source
+      @source ||= parent&.method_name || begin
+        value = options[:source]
+
+        if value.is_a?(Proc)
+          task.instance_eval(&value)
+        elsif value.respond_to?(:call)
+          value.call(task)
+        else
+          value || :context
+        end
+      end
+    end
+
+    # Generates the method name for accessing this attribute.
+    #
+    # @return [Symbol] The method name for the attribute
+    #
+    # @example
+    #   attribute.method_name # => :user_name
+    def method_name
+      @method_name ||= options[:as] || begin
+        prefix = AFFIX.call(options[:prefix]) { "#{source}_" }
+        suffix = AFFIX.call(options[:suffix]) { "_#{source}" }
+
+        :"#{prefix}#{name}#{suffix}"
+      end
+    end
+
+    # Defines and verifies the entire attribute tree including nested children.
+    def define_and_verify_tree
+      define_and_verify
+
+      children.each do |child|
+        child.task = task
+        child.define_and_verify_tree
+      end
+    end
+
+    private
+
+    # Creates nested attributes as children of this attribute.
+    #
+    # @param names [Array<Symbol, String>] The names of the child attributes
+    # @param options [Hash] Configuration options for the child attributes
+    #
+    # @yield [self] Block to configure the child attributes
+    #
+    # @return [Array<Attribute>] Array of created child attributes
+    #
+    # @example
+    #   attributes :street, :city, :zip, types: String
+    def attributes(*names, **options, &)
+      attrs = self.class.build(*names, **options.merge(parent: self), &)
+      children.concat(attrs)
+    end
+    alias attribute attributes
+
+    # Creates optional nested attributes.
+    #
+    # @param names [Array<Symbol, String>] The names of the optional child attributes
+    # @param options [Hash] Configuration options for the child attributes
+    #
+    # @yield [self] Block to configure the child attributes
+    #
+    # @return [Array<Attribute>] Array of created optional child attributes
+    #
+    # @example
+    #   optional :middle_name, :nickname, types: String
+    def optional(*names, **options, &)
+      attributes(*names, **options.merge(required: false), &)
+    end
+
+    # Creates required nested attributes.
+    #
+    # @param names [Array<Symbol, String>] The names of the required child attributes
+    # @param options [Hash] Configuration options for the child attributes
+    #
+    # @yield [self] Block to configure the child attributes
+    #
+    # @return [Array<Attribute>] Array of created required child attributes
+    #
+    # @example
+    #   required :first_name, :last_name, types: String
+    def required(*names, **options, &)
+      attributes(*names, **options.merge(required: true), &)
+    end
+
+    # Defines the attribute method on the task and validates the configuration.
+    #
+    # @raise [RuntimeError] When the method name is already defined on the task
+    def define_and_verify
+      raise "#{task.class.name}##{method_name} already defined" if task.respond_to?(method_name, true)
+
+      attribute_value = AttributeValue.new(self)
+      attribute_value.generate
+      attribute_value.validate
+
+      task.instance_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+        def #{method_name}
+          attributes[:#{method_name}]
+        end
+      RUBY
+    end
+
+  end
+end

data/lib/cmdx/attribute_registry.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Manages a collection of attributes for task definition and verification.
+  # The registry provides methods to register, deregister, and process attributes
+  # in a hierarchical structure, supporting nested attribute definitions.
+  class AttributeRegistry
+
+    attr_reader :registry
+    alias to_a registry
+
+    # Creates a new attribute registry with an optional initial collection.
+    #
+    # @param registry [Array<Attribute>] Initial attributes to register
+    #
+    # @return [AttributeRegistry] A new registry instance
+    #
+    # @example
+    #   registry = AttributeRegistry.new
+    #   registry = AttributeRegistry.new([attr1, attr2])
+    def initialize(registry = [])
+      @registry = registry
+    end
+
+    # Creates a duplicate of this registry with copied attributes.
+    #
+    # @return [AttributeRegistry] A new registry with duplicated attributes
+    #
+    # @example
+    #   new_registry = registry.dup
+    def dup
+      self.class.new(registry.dup)
+    end
+
+    # Registers one or more attributes to the registry.
+    #
+    # @param attributes [Attribute, Array<Attribute>] Attribute(s) to register
+    #
+    # @return [AttributeRegistry] Self for method chaining
+    #
+    # @example
+    #   registry.register(attribute)
+    #   registry.register([attr1, attr2])
+    def register(attributes)
+      @registry.concat(Array(attributes))
+      self
+    end
+
+    # Removes attributes from the registry by name.
+    # Supports hierarchical attribute removal by matching the entire attribute tree.
+    #
+    # @param names [Symbol, String, Array<Symbol, String>] Name(s) of attributes to remove
+    #
+    # @return [AttributeRegistry] Self for method chaining
+    #
+    # @example
+    #   registry.deregister(:name)
+    #   registry.deregister(['name1', 'name2'])
+    def deregister(names)
+      Array(names).each do |name|
+        @registry.reject! { |attribute| matches_attribute_tree?(attribute, name.to_sym) }
+      end
+
+      self
+    end
+
+    # Associates all registered attributes with a task and verifies their definitions.
+    # This method is called during task setup to establish attribute-task relationships
+    # and validate the attribute hierarchy.
+    #
+    # @param task [Task] The task to associate with all attributes
+    def define_and_verify(task)
+      registry.each do |attribute|
+        attribute.task = task
+        attribute.define_and_verify_tree
+      end
+    end
+
+    private
+
+    # Recursively checks if an attribute or any of its children match the given name.
+    #
+    # @param attribute [Attribute] The attribute to check
+    # @param name [Symbol] The name to match against
+    #
+    # @return [Boolean] True if the attribute or any child matches the name
+    def matches_attribute_tree?(attribute, name)
+      return true if attribute.method_name == name
+
+      attribute.children.any? { |child| matches_attribute_tree?(child, name) }
+    end
+
+  end
+end

data/lib/cmdx/attribute_value.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+module CMDx
+  # Manages the value lifecycle for a single attribute within a task.
+  # Handles value sourcing, derivation, coercion, and validation through
+  # a coordinated pipeline that ensures data integrity and type safety.
+  class AttributeValue
+
+    extend Forwardable
+
+    attr_reader :attribute
+
+    def_delegators :attribute, :task, :parent, :name, :options, :types, :source, :method_name, :required?
+    def_delegators :task, :attributes, :errors
+
+    # Creates a new attribute value manager for the given attribute.
+    #
+    # @param attribute [Attribute] The attribute to manage values for
+    #
+    # @example
+    #   attr = Attribute.new(:user_id, required: true)
+    #   attr_value = AttributeValue.new(attr)
+    def initialize(attribute)
+      @attribute = attribute
+    end
+
+    # Retrieves the current value for this attribute from the task's attributes.
+    #
+    # @return [Object, nil] The current attribute value or nil if not set
+    #
+    # @example
+    #   attr_value.value # => "john_doe"
+    def value
+      attributes[method_name]
+    end
+
+    # Generates the attribute value through the complete pipeline:
+    # sourcing, derivation, coercion, and storage.
+    #
+    # @return [Object, nil] The generated value or nil if generation failed
+    #
+    # @example
+    #   attr_value.generate # => 42
+    def generate
+      return value if attributes.key?(method_name)
+
+      sourced_value = source_value
+      return if errors.for?(method_name)
+
+      derived_value = derive_value(sourced_value)
+      return if errors.for?(method_name)
+
+      coerced_value = coerce_value(derived_value)
+      return if errors.for?(method_name)
+
+      attributes[method_name] = coerced_value
+    end
+
+    # Validates the current attribute value against configured validators.
+    #
+    # @raise [ValidationError] When validation fails (handled internally)
+    #
+    # @example
+    #   attr_value.validate
+    #   # Validates value against :presence, :format, etc.
+    def validate
+      registry = task.class.settings[:validators]
+
+      options.slice(*registry.keys).each do |type, opts|
+        registry.validate(type, task, value, opts)
+      rescue ValidationError => e
+        errors.add(method_name, e.message)
+        nil
+      end
+    end
+
+    private
+
+    # Retrieves the source value for this attribute from various sources.
+    #
+    # @return [Object, nil] The sourced value or nil if unavailable
+    #
+    # @raise [NoMethodError] When the source method doesn't exist
+    #
+    # @example
+    #   # Sources from task method, proc, or direct value
+    #   source_value # => "raw_value"
+    def source_value
+      sourced_value =
+        case source
+        when Symbol then task.send(source)
+        when Proc then task.instance_eval(&source)
+        else source.respond_to?(:call) ? source.call(task) : source
+        end
+
+      if required? && (parent.nil? || parent&.required?)
+        case sourced_value
+        when Context, Hash then sourced_value.key?(name)
+        when Proc then true # Cannot be determined
+        else sourced_value.respond_to?(name, true)
+        end || errors.add(method_name, Locale.t("cmdx.attributes.required"))
+      end
+
+      sourced_value
+    rescue NoMethodError
+      errors.add(method_name, Locale.t("cmdx.attributes.undefined", method: source))
+      nil
+    end
+
+    # Retrieves the default value for this attribute if configured.
+    #
+    # @return [Object, nil] The default value or nil if not configured
+    #
+    # @example
+    #   # Default can be symbol, proc, or direct value
+    #   default_value # => "default_value"
+    def default_value
+      default = options[:default]
+
+      if default.is_a?(Symbol) && task.respond_to?(default, true)
+        task.send(default)
+      elsif default.is_a?(Proc)
+        task.instance_eval(&default)
+      elsif default.respond_to?(:call)
+        default.call(task)
+      else
+        default
+      end
+    end
+
+    # Derives the actual value from the source value using various strategies.
+    #
+    # @param source_value [Object] The source value to derive from
+    #
+    # @return [Object, nil] The derived value or nil if derivation failed
+    #
+    # @raise [NoMethodError] When the derivation method doesn't exist
+    #
+    # @example
+    #   # Derives from hash key, method call, or proc execution
+    #   derive_value({user_id: 42}) # => 42
+    def derive_value(source_value)
+      derived_value =
+        case source_value
+        when Context, Hash then source_value[name]
+        when Symbol then source_value.send(name)
+        when Proc then task.instance_exec(name, &source_value)
+        else source_value.call(task, name) if source_value.respond_to?(:call)
+        end
+
+      derived_value.nil? ? default_value : derived_value
+    rescue NoMethodError
+      errors.add(method_name, Locale.t("cmdx.attributes.undefined", method: name))
+      nil
+    end
+
+    # Coerces the derived value to the expected type(s) using the coercion registry.
+    #
+    # @param derived_value [Object] The value to coerce
+    #
+    # @return [Object, nil] The coerced value or nil if coercion failed
+    #
+    # @raise [CoercionError] When coercion fails (handled internally)
+    #
+    # @example
+    #   # Coerces "42" to Integer, "true" to Boolean, etc.
+    #   coerce_value("42") # => 42
+    def coerce_value(derived_value)
+      return derived_value if attribute.types.empty?
+
+      registry = task.class.settings[:coercions]
+      last_idx = attribute.types.size - 1
+
+      attribute.types.find.with_index do |type, i|
+        break registry.coerce(type, task, derived_value, options)
+      rescue CoercionError => e
+        next if i != last_idx
+
+        message =
+          if last_idx.zero?
+            e.message
+          else
+            tl = attribute.types.map { |t| Locale.t("cmdx.types.#{t}") }.join(", ")
+            Locale.t("cmdx.coercions.into_any", types: tl)
+          end
+
+        errors.add(method_name, message)
+        nil
+      end
+    end
+
+  end
+end

data/lib/cmdx/callback_registry.rb

@@ -1,113 +1,105 @@
 # frozen_string_literal: true
 
 module CMDx
-  # Registry for managing callback definitions and execution within tasks.
+  # Registry for managing callbacks that can be executed at various points during task execution.
   #
-  # This registry handles the registration and execution of callbacks at various
-  # points in the task lifecycle, including validation, execution, and outcome
-  # handling phases.
+  # Callbacks are organized by type and can be registered with optional conditions and options.
+  # Each callback type represents a specific execution phase or outcome.
   class CallbackRegistry
 
-    TYPES = [
-      :before_validation,
-      :after_validation,
-      :before_execution,
-      :after_execution,
-      :on_executed,
-      :on_good,
-      :on_bad,
-      *Result::STATUSES.map { |s| :"on_#{s}" },
-      *Result::STATES.map { |s| :"on_#{s}" }
+    TYPES = %i[
+      before_validation
+      before_execution
+      on_complete
+      on_interrupted
+      on_executed
+      on_success
+      on_skipped
+      on_failed
+      on_good
+      on_bad
     ].freeze
 
-    # @return [Hash] hash containing callback type keys and callback definition arrays
     attr_reader :registry
+    alias to_h registry
 
-    # Initializes a new callback registry.
-    #
-    # @param registry [Hash] initial registry hash with callback definitions
-    #
-    # @return [CallbackRegistry] a new callback registry instance
-    #
-    # @example Creating an empty registry
-    #   CallbackRegistry.new
-    #
-    # @example Creating a registry with initial callbacks
-    #   CallbackRegistry.new(before_execution: [[:my_callback, {}]])
+    # @param registry [Hash] Initial registry hash, defaults to empty
     def initialize(registry = {})
-      @registry = registry.to_h
+      @registry = registry
     end
 
-    # Registers one or more callbacks for a specific type.
-    #
-    # @param type [Symbol] the callback type to register
-    # @param callables [Array<Object>] callable objects to register
-    # @param options [Hash] options for conditional callback execution
-    # @param block [Proc] optional block to register as a callback
+    # Creates a deep copy of the registry with duplicated callable sets
     #
-    # @return [CallbackRegistry] returns self for method chaining
-    #
-    # @example Registering a symbol callback
-    #   registry.register(:before_execution, :setup_database)
+    # @return [CallbackRegistry] A new instance with duplicated registry contents
+    def dup
+      self.class.new(registry.transform_values(&:dup))
+    end
+
+    # Registers one or more callables for a specific callback type
     #
-    # @example Registering a Proc callback
-    #   registry.register(:on_good, ->(task) { puts "Task completed: #{task.name}" })
+    # @param type [Symbol] The callback type from TYPES
+    # @param callables [Array<#call>] Callable objects to register
+    # @param options [Hash] Options to pass to the callback
+    # @option options [Hash] :if Condition hash for conditional execution
+    # @option options [Hash] :unless Inverse condition hash for conditional execution
+    # @param block [Proc] Optional block to register as a callable
     #
-    # @example Registering a Callback class
-    #   registry.register(:after_validation, NotificationCallback)
+    # @return [CallbackRegistry] self for method chaining
     #
-    # @example Registering multiple callbacks with options
-    #   registry.register(:on_good, :send_notification, :log_success, if: -> { Rails.env.production? })
+    # @raise [ArgumentError] When type is not a valid callback type
     #
-    # @example Registering a block callback
-    #   registry.register(:after_validation) { |task| puts "Validation complete" }
+    # @example Register a method callback
+    #   registry.register(:before_execution, :validate_inputs)
+    # @example Register a block with conditions
+    #   registry.register(:on_success, if: { status: :completed }) do |task|
+    #     task.log("Success callback executed")
+    #   end
     def register(type, *callables, **options, &block)
       callables << block if block_given?
-      (registry[type] ||= []).push([callables, options]).uniq!
+
+      registry[type] ||= Set.new
+      registry[type] << [callables, options]
       self
     end
 
-    # Executes all registered callbacks for a specific type.
+    # Removes one or more callables for a specific callback type
     #
-    # @param task [Task] the task instance to execute callbacks on
-    # @param type [Symbol] the callback type to execute
+    # @param type [Symbol] The callback type from TYPES
+    # @param callables [Array<#call>] Callable objects to remove
+    # @param options [Hash] Options that were used during registration
+    # @param block [Proc] Optional block to remove
     #
-    # @return [void]
+    # @return [CallbackRegistry] self for method chaining
     #
-    # @raise [UnknownCallbackError] when the callback type is not recognized
+    # @example Remove a specific callback
+    #   registry.deregister(:before_execution, :validate_inputs)
+    def deregister(type, *callables, **options, &block)
+      callables << block if block_given?
+      return self unless registry[type]
+
+      registry[type].delete([callables, options])
+      registry.delete(type) if registry[type].empty?
+      self
+    end
+
+    # Invokes all registered callbacks for a given type
+    #
+    # @param type [Symbol] The callback type to invoke
+    # @param task [Task] The task instance to pass to callbacks
     #
-    # @example Executing before_validation callbacks
-    #   registry.call(task, :before_validation)
+    # @raise [TypeError] When type is not a valid callback type
     #
-    # @example Executing outcome callbacks
-    #   registry.call(task, :on_good)
-    def call(task, type)
-      raise UnknownCallbackError, "unknown callback #{type}" unless TYPES.include?(type)
+    # @example Invoke all before_execution callbacks
+    #   registry.invoke(:before_execution, task)
+    def invoke(type, task)
+      raise TypeError, "unknown callback type #{type.inspect}" unless TYPES.include?(type)
 
       Array(registry[type]).each do |callables, options|
-        next unless task.cmdx_eval(options)
+        next unless Utils::Condition.evaluate(task, options, task)
 
-        Array(callables).each do |callable|
-          case callable
-          when Symbol, String, Proc
-            task.cmdx_try(callable)
-          else
-            callable.call(task)
-          end
-        end
+        Array(callables).each { |callable| Utils::Call.invoke(task, callable, task) }
       end
     end
 
-    # Returns a hash representation of the registry.
-    #
-    # @return [Hash] a deep copy of the registry hash
-    #
-    # @example Getting registry contents
-    #   registry.to_h
-    #   #=> { before_execution: [[:setup, {}]], on_good: [[:notify, { if: -> { true } }]] }
-    def to_h
-      registry.transform_values(&:dup)
-    end
-
   end
 end