plutonium 0.14.0 → 0.15.0.pre.rc1

data/lib/plutonium/interaction/base.rb

@@ -0,0 +1,75 @@
+require "active_model"
+
+module Plutonium
+  module Interaction
+    # Base class for all interactions.
+    # Provides core functionality for validations, execution, and result handling.
+    #
+    # @example
+    #   class MyInteraction < Plutonium::Interaction::Base
+    #     attribute :user_id, :integer
+    #     validates :user_id, presence: true
+    #
+    #     private
+    #
+    #     def execute
+    #       user = User.find(user_id)
+    #       success(user)
+    #     end
+    #   end
+    #
+    # @note Subclasses must implement the #execute method.
+    class Base
+      include ActiveModel::Model
+      include ActiveModel::Attributes
+      # include Concerns::Presentable
+      # include Concerns::WorkflowDSL
+
+      # Executes the interaction with the given arguments.
+      #
+      # @param args [Hash] The arguments to initialize the interaction.
+      # @return [Plutonium::Interaction::Outcome] The result of the interaction.
+      def self.call(**args)
+        new(**args).call
+      end
+
+      # Executes the interaction.
+      #
+      # @return [Plutonium::Interaction::Outcome] The result of the interaction.
+      def call
+        if valid?
+          execute
+        else
+          failure(errors)
+        end
+      end
+
+      private
+
+      # Implement the main logic of the interaction.
+      #
+      # @abstract Subclass and override {#execute} to implement the interaction logic.
+      # @return [Plutonium::Interaction::Outcome] The result of the interaction.
+      # @raise [NotImplementedError] If the subclass doesn't implement this method.
+      def execute
+        raise NotImplementedError, "#{self.class} must implement #execute"
+      end
+
+      # Creates a successful outcome.
+      #
+      # @param value [Object] The value to be wrapped in the successful outcome.
+      # @return [Plutonium::Interaction::Success] A successful outcome.
+      def success(value)
+        Success.new(value)
+      end
+
+      # Creates a failure outcome.
+      #
+      # @param errors [ActiveModel::Errors, Array<String>] The errors to be wrapped in the failure outcome.
+      # @return [Plutonium::Interaction::Failure] A failure outcome.
+      def failure(errors)
+        Failure.new(errors)
+      end
+    end
+  end
+end

data/lib/plutonium/interaction/concerns/presentable.rb

@@ -0,0 +1,61 @@
+module Plutonium
+  module Interaction
+    module Concerns
+      # Provides presentation-related functionality for interactions.
+      #
+      # This module allows interactions to define metadata such as labels, icons,
+      # and descriptions, which can be used for UI generation or documentation.
+      #
+      # @example
+      #   class MyInteraction < Plutonium::Interaction::Base
+      #     include Plutonium::Interaction::Concerns::Presentable
+      #
+      #     presents label: "My Interaction",
+      #              icon: "star",
+      #              description: "Does something awesome"
+      #
+      #     # ... rest of the interaction
+      #   end
+      module Presentable
+        extend ActiveSupport::Concern
+
+        included do
+          class_attribute :presentation_metadata, default: {}
+        end
+
+        class_methods do
+          # Defines presentation metadata for the interaction.
+          #
+          # @param options [Hash] The presentation options.
+          # @option options [String] :label The label for the interaction.
+          # @option options [String] :icon The icon for the interaction.
+          # @option options [String] :description The description of the interaction.
+          def presents(**options)
+            self.presentation_metadata = options
+          end
+        end
+
+        # Returns the label for the interaction.
+        #
+        # @return [String] The label defined in the presentation metadata or a default generated from the class name.
+        def label
+          self.class.presentation_metadata[:label] || self.class.name.demodulize.titleize
+        end
+
+        # Returns the icon for the interaction.
+        #
+        # @return [String, nil] The icon defined in the presentation metadata.
+        def icon
+          self.class.presentation_metadata[:icon]
+        end
+
+        # Returns the description for the interaction.
+        #
+        # @return [String, nil] The description defined in the presentation metadata.
+        def description
+          self.class.presentation_metadata[:description]
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/interaction/concerns/workflow_dsl.rb

@@ -0,0 +1,82 @@
+module Plutonium
+  module Interaction
+    module Concerns
+      # DO NOT USE
+      #
+      # Provides a Domain Specific Language (DSL) for defining workflows in interactions.
+      #
+      # This module allows interactions to define a series of steps that can be executed
+      # in sequence, with optional conditions for each step.
+      #
+      # @example
+      #   class MyWorkflow < Plutonium::Interaction::Base
+      #     include Plutonium::Interaction::Concerns::WorkflowDSL
+      #
+      #     workflow do
+      #       step :validate_input, ValidateInputInteraction
+      #       step :process_data, ProcessDataInteraction, if: ->(ctx) { ctx[:data_valid] }
+      #       step :send_notification, SendNotificationInteraction
+      #     end
+      #
+      #     private
+      #
+      #     def execute
+      #       execute_workflow(attributes.to_h)
+      #     end
+      #   end
+      module WorkflowDSL
+        extend ActiveSupport::Concern
+
+        included do
+          class_attribute :workflow_steps, default: []
+        end
+
+        class_methods do
+          # Defines the workflow for the interaction.
+          #
+          # @yield The block where workflow steps are defined.
+          def workflow(&block)
+            WorkflowBuilder.new(self).instance_eval(&block)
+          end
+        end
+
+        # Helper class for building workflows.
+        class WorkflowBuilder
+          # @param use_case_class [Class] The interaction class where the workflow is being defined.
+          def initialize(use_case_class)
+            @use_case_class = use_case_class
+          end
+
+          # Adds a step to the workflow.
+          #
+          # @param name [Symbol] The name of the step.
+          # @param use_case [Class] The interaction class to be executed for this step.
+          # @param if [Proc, nil] An optional condition for executing the step.
+          def step(name, use_case, if: nil)
+            @use_case_class.workflow_steps << {
+              name:,
+              use_case:,
+              condition: binding.local_variable_get(:if)
+            }
+          end
+        end
+
+        # Executes the defined workflow.
+        #
+        # @param context [Hash] The initial context for the workflow.
+        # @return [Plutonium::Interaction::Outcome] The outcome of the last executed step.
+        def execute_workflow(context = {})
+          self.class.workflow_steps.reduce(Success.new(context)) do |result, step|
+            result.and_then do |ctx|
+              if step[:condition].nil? || instance_exec(ctx, &step[:condition])
+                step[:use_case].call(context: ctx).map { |outcome| ctx[step[:name]] = outcome }
+              else
+                Success.new(ctx)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/interaction/outcome.rb

@@ -0,0 +1,129 @@
+module Plutonium
+  module Interaction
+    # Base class for interaction outcomes.
+    #
+    # This class provides a common interface for both successful and failed outcomes
+    # of an interaction.
+    #
+    # @abstract Subclass and override {#and_then}, {#map}, and {#to_response} to implement
+    class Outcome
+      # @return [Array<Array(String, Symbol)>] Messages associated with the outcome.
+      attr_reader :messages
+
+      # Checks if the outcome is successful.
+      #
+      # @return [Boolean] true if the outcome is a Success, false otherwise.
+      def success?
+        is_a?(Success)
+      end
+
+      # Checks if the outcome is a failure.
+      #
+      # @return [Boolean] true if the outcome is a Failure, false otherwise.
+      def failure?
+        is_a?(Failure)
+      end
+
+      # Adds a message to the outcome.
+      #
+      # @param msg [String] The message to add.
+      # @param type [Symbol] The type of the message (e.g., :notice, :error).
+      # @return [self]
+      def with_message(msg, type = :notice)
+        @messages ||= []
+        @messages << [msg, type]
+        self
+      end
+
+      # Sets the response for the outcome.
+      #
+      # @param response [Plutonium::Interaction::Response::Base] The response to set.
+      #
+      # @abstract
+      # @raise [NotImplementedError] if not implemented in subclass.
+      def with_response(response)
+        raise NotImplementedError, "#{self.class} must implement #with_response"
+      end
+
+      # Chains another operation to be executed if this outcome is successful.
+      #
+      # @abstract
+      # @raise [NotImplementedError] if not implemented in subclass.
+      def and_then
+        raise NotImplementedError, "#{self.class} must implement #and_then"
+      end
+
+      # Converts the outcome to a response object.
+      #
+      # @abstract
+      # @raise [NotImplementedError] if not implemented in subclass.
+      def to_response
+        raise NotImplementedError, "#{self.class} must implement #to_response"
+      end
+    end
+
+    # Represents a successful outcome of an interaction.
+    class Success < Outcome
+      # @return [Object] The value wrapped by this successful outcome.
+      attr_reader :value
+
+      # @param value [Object] The value to be wrapped in this successful outcome.
+      def initialize(value)
+        @value = value
+      end
+
+      # Chains another operation to be executed with the value of this outcome.
+      #
+      # @yield [Object] The value wrapped by this outcome.
+      # @return [Outcome] The result of the yielded block.
+      def and_then
+        yield value
+      end
+
+      # Sets the response for this successful outcome.
+      #
+      # @param response [Plutonium::Interaction::Response::Base] The response to set.
+      # @return [self]
+      def with_response(response)
+        @to_response = nil
+        @response = response
+        self
+      end
+
+      # Converts this successful outcome to a response object.
+      #
+      # @return [Plutonium::Interaction::Response::Base] The response object.
+      def to_response
+        @to_response ||= begin
+          @response ||= Response::Null.new(value)
+          @response.with_flash(messages)
+        end
+      end
+    end
+
+    # Represents a failed outcome of an interaction.
+    class Failure < Outcome
+      # @return [ActiveModel::Errors, Array<String>] The errors associated with this failure.
+      attr_reader :errors
+
+      # @param errors [ActiveModel::Errors, Array<String>] The errors to be wrapped in this failure.
+      def initialize(errors)
+        @errors = errors
+      end
+
+      # Returns self without executing the given block, propagating the failure.
+      #
+      # @return [self]
+      def and_then
+        self
+      end
+
+      # Returns self without setting a response.
+      #
+      # @return [self]
+      def with_response(response)
+        self
+      end
+    end
+  end
+end

data/lib/plutonium/interaction/response/base.rb

@@ -0,0 +1,63 @@
+module Plutonium
+  module Interaction
+    module Response
+      # Base class for interaction responses.
+      #
+      # This class provides common functionality for handling flash messages
+      # and processing responses in controllers.
+      #
+      # @abstract Subclass and override {#execute} to implement
+      #   specific response behavior.
+      class Base
+        # @return [Array<Array(String, Symbol)>] Flash messages associated with the response.
+        attr_reader :flash
+
+        # Initializes a new Response::Base instance.
+        def initialize
+          @flash = []
+        end
+
+        # Processes the response in the context of a controller.
+        #
+        # @param controller [ActionController::Base] The controller instance.
+        # @yield [Object] Executed if the response doesn't handle its own rendering.
+        # @return [void]
+        def process(controller, &)
+          set_flash(controller)
+          execute(controller, &)
+        end
+
+        # Adds flash messages to the response.
+        #
+        # @param messages [Array<Array(String, Symbol)>] The messages to add.
+        # @return [self]
+        def with_flash(messages)
+          @flash.concat(messages) unless messages.blank?
+          self
+        end
+
+        private
+
+        # Sets flash messages in the controller.
+        #
+        # @param controller [ActionController::Base] The controller instance.
+        # @return [void]
+        def set_flash(controller)
+          @flash.each do |message, type|
+            controller.flash[type] = message
+          end
+        end
+
+        # Executes the response logic.
+        #
+        # @abstract
+        # @param controller [ActionController::Base] The controller instance.
+        # @yield [Object] Executed if the response doesn't handle its own rendering.
+        # @raise [NotImplementedError] if not implemented in subclass.
+        def execute(controller, &)
+          raise NotImplementedError, "#{self.class} must implement #execute"
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/interaction/response/null.rb

@@ -0,0 +1,33 @@
+module Plutonium
+  module Interaction
+    module Response
+      # Represents a null response, which doesn't perform any specific action.
+      #
+      # This class is used when an interaction doesn't produce a specific response
+      # type but still needs to wrap a result value.
+      class Null < Base
+        # @return [Object] The result value wrapped by this null response.
+        attr_reader :result
+
+        # Initializes a new Null response.
+        #
+        # @param result [Object] The result value to be wrapped.
+        def initialize(result)
+          super()
+          @result = result
+        end
+
+        private
+
+        # Executes the null response by yielding the result value.
+        #
+        # @param controller [ActionController::Base] The controller instance (unused).
+        # @yield [Object] The result value wrapped by this response.
+        # @return [void]
+        def execute(controller, &)
+          yield @result
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/interaction/response/redirect.rb

@@ -0,0 +1,30 @@
+module Plutonium
+  module Interaction
+    module Response
+      # Represents a redirect response.
+      #
+      # This class is used to perform redirects as a result of an interaction.
+      class Redirect < Base
+        # Initializes a new Redirect response.
+        #
+        # @param path [String, Symbol] The path or named route to redirect to.
+        # @param options [Hash] Additional options to pass to the redirect_to method.
+        def initialize(path, options = {})
+          super()
+          @path = path
+          @options = options
+        end
+
+        private
+
+        # Executes the redirect response.
+        #
+        # @param controller [ActionController::Base] The controller instance.
+        # @return [void]
+        def execute(controller)
+          controller.redirect_to @path, @options
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/interaction/response/render.rb

@@ -0,0 +1,28 @@
+module Plutonium
+  module Interaction
+    module Response
+      # Represents a render response.
+      #
+      # This class is used to render views as a result of an interaction.
+      class Render < Base
+        # Initializes a new Render response.
+        #
+        # @param options [Hash] Options to pass to the render method.
+        def initialize(options = {})
+          super()
+          @options = options
+        end
+
+        private
+
+        # Executes the render response.
+        #
+        # @param controller [ActionController::Base] The controller instance.
+        # @return [void]
+        def execute(controller)
+          controller.render @options
+        end
+      end
+    end
+  end
+end

data/lib/plutonium/lib/bit_flags.rb

@@ -1,35 +1,96 @@
 module Plutonium
   module Lib
+    # The BitFlags class provides a convenient way to work with bit flags.
+    # It allows setting, checking, and extracting flags using a more
+    # readable interface. It supports both symbols and strings as flags.
+    #
+    # @example Usage
+    #   flags = BitFlags.new(:read, 'write', :execute)
+    #   value = flags[:read, 'write']  # => 3
+    #   flags.set?(value, :read)       # => true
+    #   flags.set?(value, 'execute')   # => false
+    #   flags.extract(value)           # => [:read, :write]
+    #
     class BitFlags
-      delegate :sum, to: :indices
+      # @return [Array<Symbol>] An array of all defined flags.
+      attr_reader :flags
 
+      # @return [Array<Integer>] An array of all defined bit values.
+      attr_reader :indices
+
+      # Initializes a new BitFlags object with the given flags.
+      #
+      # @param flags [Array<Symbol, String>] The flags to be used in this BitFlags object.
+      # @example
+      #   BitFlags.new(:read, 'write', :execute)
       def initialize(*flags)
-        @map = flags.each_with_index.map { |flag, index| [flag, 2.pow(index)] }.to_h
+        @flags = normalize_flags(flags).uniq.freeze
+        @indices = @flags.each_index.map { |index| 1 << index }.freeze
+        @map = @flags.zip(@indices).to_h.freeze
+        @all_bits = calculate_all_bits
       end
 
+      # Checks if the given value has all the specified flags set.
+      #
+      # @param value [Integer] The value to check against.
+      # @param flags [Array<Symbol, String>] The flags to check for.
+      # @return [Boolean] True if all specified flags are set and valid, false otherwise.
+      # @example
+      #   flags.set?(3, :read, 'write')  # => true
       def set?(value, *flags)
-        check = bits(*flags)
+        normalized_flags = normalize_flags(flags)
+        return false if normalized_flags.any? { |flag| !@map.key?(flag) }
+        check = bits(*normalized_flags)
         value & check == check
       end
 
+      # Extracts the flags that are set in the given value.
+      #
+      # @param value [Integer] The value to extract flags from.
+      # @return [Array<Symbol>] An array of flags that are set in the value.
+      # @example
+      #   flags.extract(3)  # => [:read, :write]
       def extract(value)
-        @map.select { |_flag, bit| value & bit == bit }.keys
+        value &= @all_bits
+        @map.select { |_, bit| value & bit != 0 }.keys
       end
 
+      # Returns the bit value for the given flags.
+      #
+      # @param flags [Array<Symbol, String>] The flags to get the bit value for.
+      # @return [Integer] The combined bit value of the given flags.
+      # @example
+      #   flags[:read, 'write']  # => 3
       def [](*flags)
         bits(*flags)
       end
 
+      # Calculates the combined bit value for the given flags.
+      #
+      # @param flags [Array<Symbol, String>] The flags to calculate the bit value for.
+      # @return [Integer] The combined bit value of the given flags.
+      # @example
+      #   flags.bits(:read, 'write')  # => 3
       def bits(*flags)
-        @map.slice(*flags).values.sum
+        normalized_flags = normalize_flags(flags)
+        normalized_flags.sum { |flag| @map[flag] || 0 }
+      end
+
+      # Calculates the sum of all bit values.
+      #
+      # @return [Integer] The sum of all bit values.
+      def sum
+        @all_bits
       end
 
-      def flags
-        @flags ||= @map.keys
+      private
+
+      def calculate_all_bits
+        @indices.inject(:|) || 0
       end
 
-      def indices
-        @indices ||= @map.values
+      def normalize_flags(flags)
+        flags.map(&:to_sym)
       end
     end
   end

data/lib/plutonium/lib/overlayed_hash.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Lib
+    # OverlayedHash provides a hash-like structure that overlays values on top of a base hash.
+    #
+    # This class allows you to create a new hash-like object that uses a base hash for default values,
+    # but can be modified without affecting the original base hash. When a key is accessed, it first
+    # checks if the key exists in the overlay; if not, it falls back to the base hash.
+    #
+    # @example Usage
+    #   base = { a: 1, b: 2 }
+    #   overlay = OverlayedHash.new(base)
+    #   overlay[:b] = 3
+    #   overlay[:c] = 4
+    #
+    #   overlay[:a] # => 1 (from base)
+    #   overlay[:b] # => 3 (from overlay)
+    #   overlay[:c] # => 4 (from overlay)
+    #   base[:b]    # => 2 (unchanged)
+    class OverlayedHash
+      # Initialize a new OverlayedHash with a base hash.
+      #
+      # @param base [Hash] The base hash to use for fallback values.
+      def initialize(base)
+        @base = base
+        @overlay = {}
+      end
+
+      # Retrieve a value from the overlay hash or the base hash.
+      #
+      # @param key The key to look up.
+      # @return The value associated with the key, or nil if not found.
+      def [](key)
+        @overlay.key?(key) ? @overlay[key] : @base[key]
+      end
+
+      # Set a value in the overlay hash.
+      #
+      # @param key The key to set.
+      # @param value The value to associate with the key.
+      def []=(key, value)
+        @overlay[key] = value
+      end
+
+      # Check if a key exists in either the overlay or base hash.
+      #
+      # @param key The key to check for.
+      # @return [Boolean] true if the key exists, false otherwise.
+      def key?(key)
+        @overlay.key?(key) || @base.key?(key)
+      end
+
+      # Enumerate over all keys in both the overlay and base hash.
+      #
+      # @yield [key] Gives each key to the block.
+      # @return [Enumerator] If no block is given.
+      def each_key
+        return to_enum(:each_key) unless block_given?
+
+        keys.each { |key| yield key }
+      end
+
+      # Retrieve all keys from both the overlay and base hash.
+      #
+      # @return [Array] An array of all unique keys.
+      def keys
+        (@overlay.keys + @base.keys).uniq
+      end
+
+      # Retrieve all values, prioritizing the overlay over the base.
+      #
+      # @return [Array] An array of values corresponding to all keys.
+      def values
+        keys.map { |key| self[key] }
+      end
+
+      # Convert the OverlayedHash to a regular Hash.
+      #
+      # @return [Hash] A new Hash with all keys and values from the OverlayedHash.
+      def to_h
+        keys.each_with_object({}) { |key, hash| hash[key] = self[key] }
+      end
+    end
+  end
+end