plutonium 0.14.1 → 0.15.0.pre.rc1

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/{config → lib}/overlayed_hash.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Plutonium
-  module Config
+  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,

data/lib/plutonium/lib/smart_cache.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module Plutonium
+  module Lib
+    # The SmartCache module provides flexible caching mechanisms for classes and objects,
+    # allowing for both inline caching and method-level memoization.
+    #
+    # This module is designed to optimize performance by caching results
+    # when class caching is enabled (typically in production),
+    # while ensuring fresh results when caching is disabled (typically in development).
+    #
+    # This implementation is thread-safe.
+    #
+    # @example Including SmartCache in a class
+    #   class MyClass
+    #     include Plutonium::Lib::SmartCache
+    #
+    #     def my_method(arg)
+    #       cache_unless_reloading("my_method_#{arg}") { expensive_operation(arg) }
+    #     end
+    #
+    #     def another_method(arg)
+    #       # Method implementation
+    #     end
+    #     memoize_unless_reloading :another_method
+    #   end
+    module SmartCache
+      extend ::ActiveSupport::Concern
+
+      # Class-level thread-local storage for force caching (useful for testing)
+      thread_mattr_accessor :force_caching
+
+      included do
+        mattr_accessor :_smart_cache, instance_writer: false, default: Concurrent::Map.new
+      end
+
+      private
+
+      # Caches the result of the given block unless class caching is disabled.
+      #
+      # @param cache_key [String] A unique key to identify the cached result
+      # @yield The block whose result will be cached
+      # @return [Object] The result of the block, either freshly computed or from cache
+      #
+      # @example Using cache_unless_reloading inline
+      #   def fetch_user_data(user_id)
+      #     cache_unless_reloading("user_data_#{user_id}") do
+      #       UserDataService.fetch(user_id)
+      #     end
+      #   end
+      def cache_unless_reloading(cache_key, &block)
+        return yield unless should_smart_cache?
+
+        self.class._smart_cache.compute_if_absent(cache_key.to_sym) { yield }
+      end
+
+      # Flushes the smart cache for the specified keys or all keys if none are specified.
+      #
+      # @param keys [Array<Symbol, String>, Symbol, String] The cache key(s) to flush
+      # @return [void]
+      #
+      # @example Flushing specific cache keys
+      #   flush_smart_cache([:user_data, :product_list])
+      #
+      # @example Flushing all cache keys
+      #   flush_smart_cache
+      def flush_smart_cache(keys = nil)
+        self.class.flush_smart_cache(keys)
+      end
+
+      # Determines whether caching should be performed based on the current Rails configuration
+      # or the force_caching flag.
+      #
+      # @return [Boolean] true if caching should be performed, false otherwise
+      def should_smart_cache?
+        Plutonium::Lib::SmartCache.force_caching.nil? ? Rails.application.config.cache_classes : Plutonium::Lib::SmartCache.force_caching
+      end
+
+      class_methods do
+        # Memoizes the result of the specified method unless class caching is disabled.
+        #
+        # @param method_name [Symbol] The name of the method to memoize
+        # @return [void]
+        #
+        # @example Memoizing a method
+        #   class User
+        #     include Plutonium::Lib::SmartCache
+        #
+        #     def expensive_full_name_calculation
+        #       # Complex name calculation
+        #     end
+        #     memoize_unless_reloading :expensive_full_name_calculation
+        #   end
+        def memoize_unless_reloading(method_name)
+          return if method_defined?(:"#{method_name}_without_memoization")
+
+          original_method = instance_method(method_name)
+          alias_method :"#{method_name}_without_memoization", method_name
+
+          define_method(method_name) do |*args|
+            if should_smart_cache?
+              cache = self.class._smart_cache.compute_if_absent(method_name.to_sym) { Concurrent::Map.new }
+              if args.empty?
+                cache.compute_if_absent(:no_args) { original_method.bind_call(self) }
+              else
+                cache.compute_if_absent(args.hash.to_s) { original_method.bind_call(self, *args) }
+              end
+            else
+              original_method.bind_call(self, *args)
+            end
+          end
+        end
+
+        # Flushes the smart cache for the specified keys or all keys if none are specified.
+        #
+        # @param keys [Array<Symbol, String>, Symbol, String] The cache key(s) to flush
+        # @return [void]
+        #
+        # @example Flushing specific cache keys
+        #   flush_smart_cache([:user_data, :product_list])
+        #
+        # @example Flushing all cache keys
+        #   flush_smart_cache
+        def flush_smart_cache(keys = nil)
+          keys = Array(keys).map(&:to_sym)
+          if keys.present?
+            keys.each { |key| _smart_cache.delete(key) }
+          else
+            _smart_cache.clear
+          end
+        end
+      end
+    end
+
+    # Configuration:
+    #  The caching behavior is controlled by the Rails configuration option config.cache_classes
+    #  or can be overridden using the SmartCache.force_caching flag:
+    #
+    #  - When false (typical in development):
+    #    - Classes are reloaded on each request.
+    #    - cache_unless_reloading always yields fresh results.
+    #    - memoize_unless_reloading always calls the original method.
+    #
+    #  - When true (typical in production):
+    #    - Classes are cached.
+    #    - cache_unless_reloading uses cached results.
+    #    - memoize_unless_reloading uses memoized results, caching for each unique set of arguments.
+    #
+    # Best Practices:
+    #  - Use meaningful and unique cache keys to avoid collisions.
+    #  - Be mindful of memory usage, especially with large cached results.
+    #  - Consider cache expiration strategies for long-running processes.
+    #  - Use cache_unless_reloading for fine-grained control within methods.
+    #  - Use memoize_unless_reloading for entire methods, especially those with expensive computations.
+    #
+    # Thread Safety:
+    #  - This implementation is thread-safe.
+    #  - It uses Concurrent::Map from the concurrent-ruby gem for thread-safe caching.
+    #
+    # Testing:
+    #  - In your test environment, you can control caching behavior explicitly using SmartCache.force_caching.
+    #  - Example:
+    #      describe "MyClass" do
+    #        before { Plutonium::Lib::SmartCache.force_caching = true }
+    #        after { Plutonium::Lib::SmartCache.force_caching = nil }
+    #        it "caches results" do
+    #          # Test caching behavior
+    #        end
+    #      end
+  end
+end