featurevisor 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 202758e9fe9a2c81f67c3ea7456be5d068c1d9aa8ccf35f721a4ca447a94196a
-  data.tar.gz: bf2cae186ce5b6d3b483f4eab14768553cc5d2e09148c16ebbaf3ac60af7d7a0
+  metadata.gz: e7745fb77b8646de51fe54b58c32274829b60b046e6a47d81872e3148107eac6
+  data.tar.gz: ef5f69f50e1af01af4b45aece70603a67dc77f3af08da98b10cf6e50dd3d77df
 SHA512:
-  metadata.gz: aa565646ae2e3b54d018044a79e92d9172e0ac8478dbb2dbee1699605a9457fbea6b694dc42c9027b40d4d2a3358c3146be946cfe307319119ab6ba2d03657ed
-  data.tar.gz: e8e689efcc96ac4ca3bd0ec7469895fbb1c9b4e70737d0f56f87fa9f0733395c0e0de6938a7b6c7c4c6bd7daef9f9818daa9163e508b0242836b750aa83e82f4
+  metadata.gz: 745e81a4af47bc19e0a0bfe550badafb52e7541a067f461bdbc8b73be259399da5ca3fd519e7458ee0afa3ee6f810e0d7e28446add35ee13e970f25ecc7a0d2d
+  data.tar.gz: 44947e427ceb1cf6b87e2e0784e7c77dddcbd8e27677c6794dd885a3a83dec65a4a2a1cec1815198abbe3e47187399700e9ec7e4342fd729428fafb21ab2dadd

data/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2025 Fahad Heylaal (https://fahad19.com)
+Copyright (c) 2026 Fahad Heylaal (https://fahad19.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -89,6 +89,8 @@ f = Featurevisor.create_featurevisor(
 
 Most applications only need this factory and the returned `Featurevisor::Instance`. Public extension and observability APIs include modules, diagnostics, events, and the datafile structures accepted by the factory.
 
+Concurrent evaluations are safe after an instance is configured. Do not mutate or close the same instance concurrently with evaluations. Serialize calls to `set_datafile`, `set_context`, `set_sticky`, `add_module`, `remove_module`, and `close`. Module, event, and diagnostic callbacks must synchronize mutable state that they capture.
+
 ## Initialization
 
 The SDK can be initialized by passing [datafile](https://featurevisor.com/docs/building-datafiles/) content directly:
@@ -697,6 +699,8 @@ f.remove_module('my-custom-module')
 
 ## Child instance
 
+A child snapshots the parent keys that exist when it is spawned. Child values win for those keys. Parent keys introduced later are still inherited. Calling `close` removes both child-owned listeners and subscriptions delegated to the parent.
+
 When dealing with purely client-side applications, it is understandable that there is only one user involved, like in browser or mobile applications.
 
 But when using Featurevisor SDK in server-side applications, where a single server instance can handle multiple user requests simultaneously, it is important to isolate the context for each request.
@@ -722,8 +726,11 @@ Similar to parent SDK, child instances also support several additional methods:
 
 - `set_context`
 - `set_sticky`
+- `evaluate_flag`
 - `is_enabled`
+- `evaluate_variation`
 - `get_variation`
+- `evaluate_variable`
 - `get_variable`
 - `get_variable_boolean`
 - `get_variable_string`
@@ -821,7 +828,7 @@ The provider currently requires Ruby 3.4 or newer because that is the minimum ve
 Install the provider:
 
 ```ruby
-gem "featurevisor-openfeature", "~> 1.1"
+gem "featurevisor-openfeature", "~> 2.0"
 ```
 
 It installs the matching `featurevisor` gem and the official `openfeature-sdk` dependency. The provider and base SDK deliberately share the same version, and the provider requires that exact Featurevisor version.
@@ -901,7 +908,7 @@ The build produces `featurevisor-VERSION.gem` and `featurevisor-openfeature-VERS
 - Run `bundle install`
 - Push commit to `main` branch
 - Wait for CI to complete
-- Tag the release with the same version number, for example `v1.1.0`
+- Tag the release with the same version number, for example `v2.0.0`
 - The workflow verifies that the tag matches the shared version
 - The workflow publishes `featurevisor` first, followed by `featurevisor-openfeature`
 

data/bin/commands/test.rb

@@ -671,7 +671,7 @@ module FeaturevisorCLI
 
         if assertion.key?(:expectedToMatch)
           expected_to_match = assertion[:expectedToMatch]
-          actual = instance.instance_variable_get(:@datafile_reader).all_conditions_are_matched(conditions, context)
+          actual = instance.instance_variable_get(:@datafile).all_conditions_are_matched(conditions, context)
 
           if actual != expected_to_match
             has_error = true

data/lib/featurevisor/bucketer.rb

@@ -30,16 +30,16 @@ module Featurevisor
     #   - feature_key [String] The feature key
     #   - bucket_by [String, Array<String>, Hash] Bucketing strategy
     #   - context [Hash] User context
-    #   - logger [Logger] Logger instance
+    #   - diagnostics [DiagnosticReporter] Diagnostic reporter
     # @return [String] The bucket key
     # @raise [StandardError] If bucket_by is invalid
     def self.get_bucket_key(options)
       feature_key = options[:feature_key]
       bucket_by = options[:bucket_by]
       context = options[:context]
-      logger = options[:logger]
+      diagnostics = options[:diagnostics]
 
-      type, attribute_keys = parse_bucket_by(bucket_by, logger, feature_key)
+      type, attribute_keys = parse_bucket_by(bucket_by, diagnostics, feature_key)
 
       bucket_key = build_bucket_key(attribute_keys, context, type, feature_key)
 
@@ -50,10 +50,10 @@ module Featurevisor
 
     # Parse bucket_by configuration to determine type and attribute keys
     # @param bucket_by [String, Array<String>, Hash] Bucketing strategy
-    # @param logger [Logger] Logger instance
+    # @param diagnostics [DiagnosticReporter] Diagnostic reporter
     # @param feature_key [String] Feature key for error logging
     # @return [Array] Tuple of [type, attribute_keys]
-    def self.parse_bucket_by(bucket_by, logger, feature_key)
+    def self.parse_bucket_by(bucket_by, diagnostics, feature_key)
       if bucket_by.is_a?(String)
         ["plain", [bucket_by]]
       elsif bucket_by.is_a?(Array)
@@ -61,7 +61,7 @@ module Featurevisor
       elsif bucket_by.is_a?(Hash) && bucket_by[:or].is_a?(Array)
         ["or", bucket_by[:or]]
       else
-        logger.error("invalid bucketBy", { feature_key: feature_key, bucket_by: bucket_by })
+        diagnostics.error("invalid bucketBy", { feature_key: feature_key, bucket_by: bucket_by })
         raise StandardError, "invalid bucketBy"
       end
     end
@@ -78,7 +78,7 @@ module Featurevisor
       attribute_keys.each do |attribute_key|
         attribute_value = Featurevisor::Conditions.get_value_from_context(context, attribute_key)
 
-        next if attribute_value.nil?
+        next if attribute_value.nil? && !context_path_exists?(context, attribute_key)
 
         if type == "plain" || type == "and"
           bucket_key << attribute_value
@@ -89,7 +89,61 @@ module Featurevisor
       end
 
       bucket_key << feature_key
-      bucket_key
+      bucket_key.map { |value| javascript_string(value) }
     end
+
+    def self.context_path_exists?(context, path)
+      path.split(".").reduce(context) do |current, key|
+        return false unless current.is_a?(Hash)
+        return false unless current.key?(key.to_sym) || current.key?(key)
+
+        current.key?(key.to_sym) ? current[key.to_sym] : current[key]
+      end
+      true
+    end
+
+    def self.javascript_string(value)
+      return "" if value.nil?
+      return value ? "true" : "false" if value == true || value == false
+      if value.is_a?(Float)
+        return "NaN" if value.nan?
+        return value.positive? ? "Infinity" : "-Infinity" if value.infinite?
+        return "0" if value.zero?
+        return value.to_i.to_s if value == value.to_i && value.abs < 1e21
+        if value.abs >= 1e-6 && value.abs < 1e21
+          return scientific_to_fixed(value.to_s)
+        end
+
+        coefficient, exponent = value.to_s.downcase.split("e")
+        return "#{coefficient.delete_suffix('.0')}e#{Integer(exponent) >= 0 ? '+' : ''}#{Integer(exponent)}"
+      end
+      return value.map { |item| javascript_string(item) }.join(",") if value.is_a?(Array)
+      return "[object Object]" if value.is_a?(Hash)
+
+      value.to_s
+    end
+
+    def self.scientific_to_fixed(value)
+      return value unless value.downcase.include?("e")
+
+      coefficient, exponent_text = value.downcase.split("e")
+      exponent = Integer(exponent_text)
+      negative = coefficient.start_with?("-")
+      digits = coefficient.delete_prefix("-").delete(".")
+      decimal_position = coefficient.delete_prefix("-").index(".") || coefficient.delete_prefix("-").length
+      decimal_position += exponent
+
+      result = if decimal_position <= 0
+                 "0.#{"0" * -decimal_position}#{digits}"
+               elsif decimal_position >= digits.length
+                 "#{digits}#{"0" * (decimal_position - digits.length)}"
+               else
+                 "#{digits[0...decimal_position]}.#{digits[decimal_position..]}"
+               end
+
+      result = result.sub(/(\.\d*?)0+\z/, '\1').delete_suffix(".")
+      negative ? "-#{result}" : result
+    end
+    private_class_method :scientific_to_fixed
   end
 end

data/lib/featurevisor/child_instance.rb

@@ -13,6 +13,7 @@ module Featurevisor
       @context = options[:context] || {}
       @sticky = options[:sticky] || {}
       @emitter = Featurevisor::Emitter.new
+      @parent_unsubscribers = []
     end
 
     # Subscribe to an event
@@ -25,12 +26,25 @@ module Featurevisor
       if event_name == "context_set" || event_name == "sticky_set"
         @emitter.on(event_name, callback)
       else
-        @parent.on(event_name, callback)
+        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
     end
 
     # Close the child instance
     def close
+      @parent_unsubscribers.dup.each(&:call)
+      @parent_unsubscribers.clear
       @emitter.clear_all
     end
 
@@ -98,6 +112,15 @@ module Featurevisor
       )
     end
 
+    # Evaluate a feature flag and return its full evaluation details.
+    def evaluate_flag(feature_key, context = {}, options = {})
+      @parent.evaluate_flag(
+        feature_key,
+        { **@context, **context },
+        { **options, __featurevisor_child_sticky: @sticky }
+      )
+    end
+
     # Get variation value
     # @param feature_key [String] Feature key
     # @param context [Hash] Context
@@ -117,6 +140,15 @@ module Featurevisor
       )
     end
 
+    # Evaluate a variation and return its full evaluation details.
+    def evaluate_variation(feature_key, context = {}, options = {})
+      @parent.evaluate_variation(
+        feature_key,
+        { **@context, **context },
+        { **options, __featurevisor_child_sticky: @sticky }
+      )
+    end
+
     # Get variable value
     # @param feature_key [String] Feature key
     # @param variable_key [String] Variable key
@@ -138,6 +170,16 @@ module Featurevisor
       )
     end
 
+    # Evaluate a variable and return its full evaluation details.
+    def evaluate_variable(feature_key, variable_key, context = {}, options = {})
+      @parent.evaluate_variable(
+        feature_key,
+        variable_key,
+        { **@context, **context },
+        { **options, __featurevisor_child_sticky: @sticky }
+      )
+    end
+
     # Get variable as boolean
     # @param feature_key [String] Feature key
     # @param variable_key [String] Variable key

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