featurevisor 1.1.0 → 3.0.0

data/lib/featurevisor/child_instance.rb

@@ -1,309 +1,126 @@
 # frozen_string_literal: true
 
 module Featurevisor
-  # Child instance class for managing child contexts and sticky features
+  # Child instance with isolated context and sticky state.
   class ChildInstance
-    # Initialize a new child instance
-    # @param options [Hash] Child instance options
-    # @option options [Instance] :parent Parent instance
-    # @option options [Hash] :context Child context
-    # @option options [Hash] :sticky Child sticky features
     def initialize(options)
       @parent = options[:parent]
       @context = options[:context] || {}
-      @sticky = options[:sticky] || {}
+      @sticky_features = options[:sticky_features] || {}
+      @sticky_variables = options[:sticky_variables] || {}
       @emitter = Featurevisor::Emitter.new
+      @parent_unsubscribers = []
     end
 
-    # Subscribe to an event
-    # @param event_name [String] Event name
-    # @param callback [Proc] Callback function
-    # @return [Proc] Unsubscribe function
     def on(event_name, callback = nil, &block)
       callback = block if block_given?
-      
-      if event_name == "context_set" || event_name == "sticky_set"
-        @emitter.on(event_name, callback)
-      else
-        @parent.on(event_name, callback)
+      if %w[context_set sticky_features_set sticky_variables_set].include?(event_name)
+        return @emitter.on(event_name, callback)
+      end
+
+      parent_unsubscribe = @parent.on(event_name, callback)
+      active = true
+      unsubscribe = nil
+      unsubscribe = proc do
+        next unless active
+
+        active = false
+        parent_unsubscribe.call
+        @parent_unsubscribers.delete(unsubscribe)
       end
+      @parent_unsubscribers << unsubscribe
+      unsubscribe
     end
 
-    # Close the child instance
     def close
+      @parent_unsubscribers.dup.each(&:call)
+      @parent_unsubscribers.clear
       @emitter.clear_all
     end
 
-    # Set context
-    # @param context [Hash] Context to set
-    # @param replace [Boolean] Whether to replace existing context
     def set_context(context, replace = false)
-      if replace
-        @context = context
-      else
-        @context = { **@context, **context }
-      end
-
-      @emitter.trigger("context_set", {
-        context: @context,
-        replaced: replace
-      })
+      @context = replace ? context : { **@context, **context }
+      @emitter.trigger("context_set", context: @context, replaced: replace)
     end
 
-    # Get context
-    # @param context [Hash, nil] Additional context to merge
-    # @return [Hash] Merged context
     def get_context(context = nil)
-      @parent.get_context({
-        **@context,
-        **(context || {})
-      })
+      @parent.get_context({ **@context, **(context || {}) })
     end
 
-    # Set sticky features
-    # @param sticky [Hash] Sticky features
-    # @param replace [Boolean] Whether to replace existing sticky features
-    def set_sticky(sticky, replace = false)
-      previous_sticky_features = @sticky || {}
-
-      if replace
-        @sticky = sticky
-      else
-        @sticky = {
-          **@sticky,
-          **sticky
-        }
-      end
+    def set_sticky_features(sticky, replace = false)
+      previous = @sticky_features
+      @sticky_features = replace ? sticky : { **@sticky_features, **sticky }
+      params = Featurevisor::Events.get_params_for_sticky_features_set_event(previous, @sticky_features, replace)
+      @emitter.trigger("sticky_features_set", params)
+    end
 
-      params = Featurevisor::Events.get_params_for_sticky_set_event(previous_sticky_features, @sticky, replace)
-      @emitter.trigger("sticky_set", params)
+    def set_sticky_variables(sticky, replace = false)
+      previous = @sticky_variables
+      @sticky_variables = replace ? sticky : { **@sticky_variables, **sticky }
+      @emitter.trigger(
+        "sticky_variables_set",
+        Featurevisor::Events.get_params_for_sticky_variables_set_event(previous, @sticky_variables, replace)
+      )
     end
 
-    # Check if a feature is enabled
-    # @param feature_key [String] Feature key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [Boolean] True if feature is enabled
     def is_enabled(feature_key, context = {}, options = {})
-      @parent.is_enabled(
-        feature_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+      @parent.is_enabled(feature_key, child_context(context), child_options(options))
     end
 
-    # Get variation value
-    # @param feature_key [String] Feature key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [String, nil] Variation value or nil
-    def get_variation(feature_key, context = {}, options = {})
-      @parent.get_variation(
-        feature_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+    def evaluate_flag(feature_key, context = {}, options = {})
+      @parent.evaluate_flag(feature_key, child_context(context), child_options(options))
     end
 
-    # Get variable value
-    # @param feature_key [String] Feature key
-    # @param variable_key [String] Variable key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [Object, nil] Variable value or nil
-    def get_variable(feature_key, variable_key, context = {}, options = {})
-      @parent.get_variable(
-        feature_key,
-        variable_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+    def get_variation(feature_key, context = {}, options = {})
+      @parent.get_variation(feature_key, child_context(context), child_options(options))
     end
 
-    # Get variable as boolean
-    # @param feature_key [String] Feature key
-    # @param variable_key [String] Variable key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [Boolean, nil] Boolean value or nil
-    def get_variable_boolean(feature_key, variable_key, context = {}, options = {})
-      @parent.get_variable_boolean(
-        feature_key,
-        variable_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+    def evaluate_variation(feature_key, context = {}, options = {})
+      @parent.evaluate_variation(feature_key, child_context(context), child_options(options))
     end
 
-    # Get variable as string
-    # @param feature_key [String] Feature key
-    # @param variable_key [String] Variable key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [String, nil] String value or nil
-    def get_variable_string(feature_key, variable_key, context = {}, options = {})
-      @parent.get_variable_string(
-        feature_key,
-        variable_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+    def get_variable(feature_or_variable_key, variable_key_or_context = nil, context_or_options = {}, options = {})
+      delegate_variable(:get_variable, feature_or_variable_key, variable_key_or_context, context_or_options, options)
     end
 
-    # Get variable as integer
-    # @param feature_key [String] Feature key
-    # @param variable_key [String] Variable key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [Integer, nil] Integer value or nil
-    def get_variable_integer(feature_key, variable_key, context = {}, options = {})
-      @parent.get_variable_integer(
-        feature_key,
-        variable_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+    def evaluate_variable(feature_or_variable_key, variable_key_or_context = nil, context_or_options = {}, options = {})
+      delegate_variable(:evaluate_variable, feature_or_variable_key, variable_key_or_context, context_or_options, options)
     end
 
-    # Get variable as double
-    # @param feature_key [String] Feature key
-    # @param variable_key [String] Variable key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [Float, nil] Float value or nil
-    def get_variable_double(feature_key, variable_key, context = {}, options = {})
-      @parent.get_variable_double(
-        feature_key,
-        variable_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+    %i[boolean string integer double array object json].each do |type|
+      define_method("get_variable_#{type}") do |feature_or_variable_key, variable_key_or_context = nil, context_or_options = {}, options = {}|
+        delegate_variable("get_variable_#{type}".to_sym, feature_or_variable_key, variable_key_or_context, context_or_options, options)
+      end
     end
 
-    # Get variable as array
-    # @param feature_key [String] Feature key
-    # @param variable_key [String] Variable key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [Array, nil] Array value or nil
-    def get_variable_array(feature_key, variable_key, context = {}, options = {})
-      @parent.get_variable_array(
-        feature_key,
-        variable_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+    def get_feature_evaluations(context = {}, feature_keys = [], options = {})
+      @parent.get_feature_evaluations(child_context(context), feature_keys, child_options(options))
     end
 
-    # Get variable as object
-    # @param feature_key [String] Feature key
-    # @param variable_key [String] Variable key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [Hash, nil] Object value or nil
-    def get_variable_object(feature_key, variable_key, context = {}, options = {})
-      @parent.get_variable_object(
-        feature_key,
-        variable_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+    def get_variable_evaluations(context = {}, variable_keys = [], options = {})
+      @parent.get_variable_evaluations(child_context(context), variable_keys, child_options(options))
     end
 
-    # Get variable as JSON
-    # @param feature_key [String] Feature key
-    # @param variable_key [String] Variable key
-    # @param context [Hash] Context
-    # @param options [Hash] Override options
-    # @return [Object, nil] JSON value or nil
-    def get_variable_json(feature_key, variable_key, context = {}, options = {})
-      @parent.get_variable_json(
-        feature_key,
-        variable_key,
-        {
-          **@context,
-          **context
-        },
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+    private
+
+    def child_context(context)
+      { **@context, **context }
     end
 
-    # Get all evaluations
-    # @param context [Hash] Context
-    # @param feature_keys [Array<String>] Feature keys to evaluate
-    # @param options [Hash] Override options
-    # @return [Hash] All evaluations
-    def get_all_evaluations(context = {}, feature_keys = [], options = {})
-      @parent.get_all_evaluations(
-        {
-          **@context,
-          **context
-        },
-        feature_keys,
-        {
-          **options,
-          __featurevisor_child_sticky: @sticky
-        }
-      )
+    def child_options(options)
+      {
+        **options,
+        __featurevisor_child_sticky_features: @sticky_features,
+        __featurevisor_child_sticky_variables: @sticky_variables
+      }
     end
 
-    private
+    def delegate_variable(method, first, second, third, fourth)
+      if second.nil? || second.is_a?(Hash)
+        @parent.public_send(method, first, child_context(second || {}), child_options(third))
+      else
+        @parent.public_send(method, first, second, child_context(third), child_options(fourth))
+      end
+    end
   end
 end

data/lib/featurevisor/conditions.rb

@@ -1,10 +1,14 @@
 # frozen_string_literal: true
 
 require "date"
+require "time"
 
 module Featurevisor
   # Conditions module for evaluating feature flags and segments
   module Conditions
+    MISSING = Object.new.freeze
+    private_constant :MISSING
+
     # Get value from context object using dot notation path
     # @param obj [Hash] Context object
     # @param path [String] Dot-separated path to the value
@@ -12,12 +16,36 @@ module Featurevisor
     def self.get_value_from_context(obj, path)
       return nil if obj.nil? || path.nil?
 
-      if path.index(".") == -1
-        return obj[path.to_sym] || obj[path]
+      value = get_value_with_presence(obj, path)
+      value.equal?(MISSING) ? nil : value
+    end
+
+    def self.get_value_with_presence(obj, path)
+      return MISSING unless obj.is_a?(Hash) && path.is_a?(String)
+
+      path.split(".").reduce(obj) do |current, key|
+        break MISSING unless current.is_a?(Hash)
+
+        if current.key?(key.to_sym)
+          current[key.to_sym]
+        elsif current.key?(key)
+          current[key]
+        else
+          break MISSING
+        end
       end
+    end
+    private_class_method :get_value_with_presence
+
+    def self.strict_equal?(left, right)
+      return true if left.nil? && right.nil?
+      return left.to_f == right.to_f if left.is_a?(Numeric) && right.is_a?(Numeric)
+      return left == right if left.is_a?(String) && right.is_a?(String)
+      return left == right if (left == true || left == false) && (right == true || right == false)
 
-      path.split(".").reduce(obj) { |o, i| o&.[](i.to_sym) || o&.[](i) }
+      false
     end
+    private_class_method :strict_equal?
 
     # Check if a condition is matched against context
     # @param condition [Hash] Condition to evaluate
@@ -30,18 +58,19 @@ module Featurevisor
       value = condition["value"] || condition[:value]
       regex_flags = condition["regexFlags"] || condition[:regexFlags]
 
-      context_value_from_path = get_value_from_context(context, attribute)
+      raw_context_value = get_value_with_presence(context, attribute)
+      context_value_from_path = raw_context_value.equal?(MISSING) ? nil : raw_context_value
+      attribute_exists = !raw_context_value.equal?(MISSING)
 
       case operator
       when "equals"
-        context_value_from_path == value
+        attribute_exists && strict_equal?(context_value_from_path, value)
       when "notEquals"
-        context_value_from_path != value
+        !attribute_exists || !strict_equal?(context_value_from_path, value)
       when "before", "after"
-        # date comparisons
-        value_in_context = context_value_from_path
-        date_in_context = value_in_context.is_a?(Date) ? value_in_context : Date.parse(value_in_context.to_s)
-        date_in_condition = value.is_a?(Date) ? value : Date.parse(value.to_s)
+        date_in_context = portable_date(context_value_from_path)
+        date_in_condition = portable_date(value)
+        return false unless date_in_context && date_in_condition
 
         if operator == "before"
           date_in_context < date_in_condition
@@ -50,21 +79,13 @@ module Featurevisor
         end
       when "in", "notIn"
         # in / notIn (where condition value is an array)
-        if value.is_a?(Array) && (context_value_from_path.is_a?(String) || context_value_from_path.is_a?(Numeric) || context_value_from_path.nil?)
-          # Check if the attribute key actually exists in the context
-          key_exists = context.key?(attribute.to_sym) || context.key?(attribute.to_s)
-
-          # If key doesn't exist, notIn should fail (return false), in should also fail
-          if !key_exists
-            return false
-          end
-
-          value_in_context = context_value_from_path.to_s
-
+        if attribute_exists && value.is_a?(Array) &&
+           (context_value_from_path.is_a?(String) || context_value_from_path.is_a?(Numeric) || context_value_from_path.nil?)
+          matched = value.any? { |candidate| strict_equal?(candidate, context_value_from_path) }
           if operator == "in"
-            value.include?(value_in_context)
+            matched
           else # notIn
-            !value.include?(value_in_context)
+            !matched
           end
         else
           false
@@ -124,18 +145,18 @@ module Featurevisor
           false
         end
       when "exists"
-        context_value_from_path != nil
+        attribute_exists
       when "notExists"
-        context_value_from_path.nil?
+        !attribute_exists
       when "includes", "notIncludes"
         # includes / notIncludes (where context value is an array)
-        if context_value_from_path.is_a?(Array) && value.is_a?(String)
-          value_in_context = context_value_from_path
-
+        if context_value_from_path.is_a?(Array) &&
+           (value.is_a?(String) || value.is_a?(Numeric) || value == true || value == false || value.nil?)
+          matched = context_value_from_path.any? { |candidate| strict_equal?(candidate, value) }
           if operator == "includes"
-            value_in_context.include?(value)
+            matched
           else # notIncludes
-            !value_in_context.include?(value)
+            !matched
           end
         else
           false
@@ -143,10 +164,18 @@ module Featurevisor
       else
         false
       end
-    rescue => e
-      # Log error but don't stop execution
-      warn "Error in condition evaluation: #{e.message}"
-      false
     end
+
+    def self.portable_date(value)
+      return value if value.is_a?(Time) || value.is_a?(DateTime)
+      return value.to_time if value.is_a?(Date)
+      return nil unless value.is_a?(String)
+      return nil unless value.match?(/T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+\-]\d{2}:\d{2})\z/)
+
+      Time.iso8601(value)
+    rescue ArgumentError
+      nil
+    end
+    private_class_method :portable_date
   end
 end

data/lib/featurevisor/{logger.rb → diagnostics.rb}

@@ -1,21 +1,22 @@
 # frozen_string_literal: true
 
 module Featurevisor
-  # Log levels for the logger
+  # Diagnostic severity levels
   LOG_LEVELS = %w[fatal error warn info debug].freeze
   DEFAULT_LOG_LEVEL = "info".freeze
-  LOGGER_PREFIX = "[Featurevisor]".freeze
+  DIAGNOSTIC_PREFIX = "[Featurevisor]".freeze
 
-  # Logger class for handling different log levels
-  class Logger
+  # Private evaluator adapter for structured diagnostics.
+  class DiagnosticReporter
     attr_reader :level, :handler
 
-    # Initialize a new logger
-    # @param options [Hash] Logger options
+    # Initialize a diagnostic reporter.
+    # @param options [Hash] Reporter options
     # @option options [String] :level Log level (default: "info")
-    # @option options [Proc] :handler Custom log handler (default: default_log_handler)
+    # @option options [Proc] :handler Internal structured diagnostic sink
     def initialize(options = {})
       @level = options[:level] || DEFAULT_LOG_LEVEL
+      @filter = !options.key?(:handler)
       @handler = options[:handler] || method(:default_log_handler)
     end
 
@@ -25,12 +26,13 @@ module Featurevisor
       @level = level
     end
 
-    # Log a message at a specific level
-    # @param level [String] Log level
-    # @param message [String] Log message
+    # Forward an evaluator diagnostic. Filtering is performed centrally by
+    # Instance so module subscriptions and error events remain independent.
+    # @param level [String] Diagnostic level
+    # @param message [String] Diagnostic message
     # @param details [Hash, nil] Additional details
     def log(level, message, details = nil)
-      return unless should_handle?(level)
+      return if @filter && !should_handle?(level)
 
       @handler.call(level, message, details)
     end
@@ -72,16 +74,8 @@ module Featurevisor
 
     private
 
-    # Check if the current level should handle the given log level
-    # @param log_level [String] Log level to check
-    # @return [Boolean] True if should handle
-    def should_handle?(log_level)
-      current_index = LOG_LEVELS.index(@level)
-      target_index = LOG_LEVELS.index(log_level)
-
-      return false if current_index.nil? || target_index.nil?
-
-      current_index >= target_index
+    def should_handle?(level)
+      LOG_LEVELS.index(level).to_i <= LOG_LEVELS.index(@level).to_i
     end
 
     # Default log handler that outputs to console
@@ -99,45 +93,18 @@ module Featurevisor
       case method_name
       when "puts"
         if details && !details.empty?
-          Kernel.puts("#{LOGGER_PREFIX} #{message} #{details.inspect}")
+          Kernel.puts("#{DIAGNOSTIC_PREFIX} #{message} #{details.inspect}")
         else
-          Kernel.puts("#{LOGGER_PREFIX} #{message}")
+          Kernel.puts("#{DIAGNOSTIC_PREFIX} #{message}")
         end
       when "warn"
         if details && !details.empty?
-          Kernel.warn("#{LOGGER_PREFIX} #{message} #{details.inspect}")
+          Kernel.warn("#{DIAGNOSTIC_PREFIX} #{message} #{details.inspect}")
         else
-          Kernel.warn("#{LOGGER_PREFIX} #{message}")
+          Kernel.warn("#{DIAGNOSTIC_PREFIX} #{message}")
         end
       end
     end
   end
 
-  # Default log handler function
-  # @param level [String] Log level
-  # @param message [String] Log message
-  # @param details [Hash, nil] Additional details
-  def self.default_log_handler(level, message, details = nil)
-    method_name = case level
-                 when "info" then "puts"
-                 when "warn" then "warn"
-                 when "error", "fatal" then "warn"
-                 else "puts"
-                 end
-
-    case method_name
-    when "puts"
-      if details && !details.empty?
-        Kernel.puts("#{LOGGER_PREFIX} #{message} #{details.inspect}")
-      else
-        Kernel.puts("#{LOGGER_PREFIX} #{message}")
-      end
-    when "warn"
-      if details && !details.empty?
-        Kernel.warn("#{LOGGER_PREFIX} #{message} #{details.inspect}")
-      else
-        Kernel.warn("#{LOGGER_PREFIX} #{message}")
-      end
-    end
-  end
 end

data/lib/featurevisor/emitter.rb

@@ -2,7 +2,7 @@
 
 module Featurevisor
   # Event names for the emitter
-  EVENT_NAMES = %w[datafile_set context_set sticky_set error].freeze
+  EVENT_NAMES = %w[datafile_set context_set sticky_features_set sticky_variables_set error].freeze
 
   # Event emitter class for handling event subscriptions and triggers
   class Emitter