featurevisor 1.1.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 202758e9fe9a2c81f67c3ea7456be5d068c1d9aa8ccf35f721a4ca447a94196a
-  data.tar.gz: bf2cae186ce5b6d3b483f4eab14768553cc5d2e09148c16ebbaf3ac60af7d7a0
+  metadata.gz: acf664663389bb7b3789a16f0e29c84aeb13e623f26bb38465e3bc8a8dcc984e
+  data.tar.gz: 0ab04bbea29092bcfd22361bda28ab6e36879b346d579b5a204780a3bbfb2eaa
 SHA512:
-  metadata.gz: aa565646ae2e3b54d018044a79e92d9172e0ac8478dbb2dbee1699605a9457fbea6b694dc42c9027b40d4d2a3358c3146be946cfe307319119ab6ba2d03657ed
-  data.tar.gz: e8e689efcc96ac4ca3bd0ec7469895fbb1c9b4e70737d0f56f87fa9f0733395c0e0de6938a7b6c7c4c6bd7daef9f9818daa9163e508b0242836b750aa83e82f4
+  metadata.gz: e123cd15ff03b6230ca26de9cdee003414b59f5b075a116b946f7b90562123980f083a4c670748d71cefcdcee0c96197e13fceb6d8a8b6bd841d0cd419167ba6
+  data.tar.gz: ef355cc9d0f2e6660510545c9f78ccefd031c71a9a52646d36ec28fe4bac1c5d38e18c8b6f2b1d9768f54f695fa7360c5e69e2d89ff9ba2cf0fa877d91a96a56

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

@@ -19,8 +19,9 @@ This SDK is compatible with Featurevisor v3 projects and v2 datafiles.
 - [Getting variation](#getting-variation)
 - [Getting variables](#getting-variables)
   - [Type specific methods](#type-specific-methods)
-- [Getting all evaluations](#getting-all-evaluations)
-- [Sticky](#sticky)
+- [Getting global variables](#getting-global-variables)
+- [Getting aggregate evaluations](#getting-aggregate-evaluations)
+- [Sticky features and variables](#sticky-features-and-variables)
   - [Initialize with sticky](#initialize-with-sticky)
   - [Set sticky afterwards](#set-sticky-afterwards)
 - [Setting datafile](#setting-datafile)
@@ -36,7 +37,7 @@ This SDK is compatible with Featurevisor v3 projects and v2 datafiles.
 - [Events](#events)
   - [`datafile_set`](#datafile_set)
   - [`context_set`](#context_set)
-  - [`sticky_set`](#sticky_set)
+  - [`sticky_features_set` and `sticky_variables_set`](#sticky_features_set-and-sticky_variables_set)
   - [`error`](#error)
 - [Modules](#modules)
   - [Defining a module](#defining-a-module)
@@ -89,6 +90,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_features`, `set_sticky_variables`, `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:
@@ -293,12 +296,24 @@ f.get_variable_json(feature_key, variable_key, context = {})
 
 Type specific methods do not coerce values. `get_variable_integer` returns `nil` for the string `"1"`, and boolean getters return `nil` for non-boolean values.
 
-## Getting all evaluations
+## Getting global variables
+
+Global variables use the same methods with a single variable key:
+
+```ruby
+message = f.get_variable_string('welcomeMessage', context)
+value = f.get_variable('checkoutSettings', context)
+evaluation = f.evaluate_variable('checkoutSettings', context)
+```
+
+Global variables resolve sticky values first, then required features, then the first matching override, and finally their default value.
+
+## Getting aggregate evaluations
 
 You can get evaluations of all features available in the SDK instance:
 
 ```ruby
-all_evaluations = f.get_all_evaluations({})
+all_evaluations = f.get_feature_evaluations({})
 
 puts all_evaluations
 # {
@@ -319,11 +334,17 @@ puts all_evaluations
 
 This is handy especially when you want to pass all evaluations from a backend application to the frontend.
 
-## Sticky
+Global variable values are available separately:
+
+```ruby
+global_variables = f.get_variable_evaluations({})
+```
+
+## Sticky features and variables
 
 For the lifecycle of the SDK instance in your application, you can set some features with sticky values, meaning that they will not be evaluated against the fetched [datafile](https://featurevisor.com/docs/building-datafiles/):
 
-Sticky values belong to an SDK or child instance. Evaluation options do not accept sticky overrides; use `spawn(context, sticky: ...)` when a child needs its own sticky state.
+Sticky values belong to an SDK or child instance. Feature and global variable sticky values are independent.
 
 ### Initialize with sticky
 
@@ -331,7 +352,7 @@ Sticky values belong to an SDK or child instance. Evaluation options do not acce
 require 'featurevisor'
 
 f = Featurevisor.create_featurevisor(
-  sticky: {
+  sticky_features: {
     myFeatureKey: {
       enabled: true,
       # optional
@@ -343,6 +364,9 @@ f = Featurevisor.create_featurevisor(
     anotherFeatureKey: {
       enabled: false
     }
+  },
+  sticky_variables: {
+    welcomeMessage: 'Welcome back'
   }
 )
 ```
@@ -354,7 +378,7 @@ Once initialized with sticky features, the SDK will look for values there first
 You can also set sticky features after the SDK is initialized:
 
 ```ruby
-f.set_sticky({
+f.set_sticky_features({
   myFeatureKey: {
     enabled: true,
     variation: 'treatment',
@@ -366,6 +390,8 @@ f.set_sticky({
     enabled: false
   }
 }, true) # replace existing sticky features (false by default)
+
+f.set_sticky_variables({ welcomeMessage: 'Welcome back' }, true)
 ```
 
 ## Setting datafile
@@ -391,7 +417,7 @@ By default, `set_datafile(datafile)` merges the incoming datafile into the SDK's
 - `segments` are merged, with incoming entries overriding existing ones
 - `features` are merged, with incoming entries overriding existing ones
 
-This means you can call `set_datafile` more than once with different datafiles, and the SDK instance accumulates their features and segments together.
+This means you can call `set_datafile` more than once with different datafiles, and the SDK instance accumulates their features, segments, and global variables together.
 
 ### Replacing
 
@@ -543,15 +569,19 @@ unsubscribe = f.on('context_set') do |event|
 end
 ```
 
-### `sticky_set`
+### `sticky_features_set` and `sticky_variables_set`
 
 ```ruby
-unsubscribe = f.on('sticky_set') do |event|
+feature_unsubscribe = f.on('sticky_features_set') do |event|
   replaced = event[:replaced] # true if sticky features got replaced
   features = event[:features] # list of all affected feature keys
 
   puts 'Sticky features set'
 end
+
+variable_unsubscribe = f.on('sticky_variables_set') do |event|
+  variables = event[:variables]
+end
 ```
 
 ### `error`
@@ -581,11 +611,14 @@ evaluation = f.evaluate_variation(feature_key, context = {})
 
 # variable
 evaluation = f.evaluate_variable(feature_key, variable_key, context = {})
+
+# global variable
+global_evaluation = f.evaluate_variable(variable_key, context = {})
 ```
 
 The returned object will always contain the following properties:
 
-- `feature_key`: the feature key
+- `feature_key`: the feature key when evaluating a feature
 - `reason`: the reason how the value was evaluated
 
 And optionally these properties depending on whether you are evaluating a feature variation or a variable:
@@ -604,6 +637,8 @@ And optionally these properties depending on whether you are evaluating a featur
 
 Modules allow you to intercept the evaluation process and customize SDK behavior.
 
+For feature evaluations, all `before` callbacks run in registration order, followed by all `before_evaluation` callbacks. After evaluation and caller defaults, all `after_evaluation` callbacks run, followed by all `after` callbacks. Global variable evaluations use only `before_evaluation` and `after_evaluation`. Required feature checks run through the complete module pipeline, and transformed defaults are preserved.
+
 ### Defining a module
 
 A module is a simple hash with a unique recommended `name` and optional lifecycle functions:
@@ -637,6 +672,9 @@ my_custom_module = {
     options
   },
 
+  # unified callback for feature and global variable evaluations
+  before_evaluation: ->(options) { options },
+
   # after evaluation
   after: ->(evaluation, options) {
     reason = evaluation[:reason]
@@ -646,6 +684,9 @@ my_custom_module = {
     end
   },
 
+  # unified callback for feature and global variable evaluations
+  after_evaluation: ->(evaluation, options) { evaluation },
+
   # configure bucket key
   bucket_key: ->(options) {
     # return custom bucket key
@@ -697,6 +738,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.
@@ -716,14 +759,19 @@ Now you can pass the child instance where your individual request is being handl
 is_enabled = child_f.is_enabled('my_feature')
 variation = child_f.get_variation('my_feature')
 variable_value = child_f.get_variable('my_feature', 'my_variable')
+global_value = child_f.get_variable('welcomeMessage')
 ```
 
 Similar to parent SDK, child instances also support several additional methods:
 
 - `set_context`
-- `set_sticky`
+- `set_sticky_features`
+- `set_sticky_variables`
+- `evaluate_flag`
 - `is_enabled`
+- `evaluate_variation`
 - `get_variation`
+- `evaluate_variable`
 - `get_variable`
 - `get_variable_boolean`
 - `get_variable_string`
@@ -732,7 +780,8 @@ Similar to parent SDK, child instances also support several additional methods:
 - `get_variable_array`
 - `get_variable_object`
 - `get_variable_json`
-- `get_all_evaluations`
+- `get_feature_evaluations`
+- `get_variable_evaluations`
 - `on`
 - `close`
 
@@ -821,7 +870,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", "~> 3.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.
@@ -845,9 +894,9 @@ enabled = client.fetch_boolean_value(
 )
 ```
 
-Use `checkout` for a flag, `checkout:variation` for its variation, and `checkout:title` for its `title` variable. Boolean variables use the boolean resolver. Arrays, hashes, and JSON variables use the object resolver.
+Use `checkout` for a flag, `checkout:variation` for its variation, `checkout:title` for its `title` variable, and `variable:welcomeMessage` for a global variable. Boolean variables use the boolean resolver. Arrays, hashes, and JSON variables use the object resolver.
 
-OpenFeature's targeting key maps to `userId` by default. `targeting_key_field`, `key_separator`, and `variation_key` can customize the mapping.
+OpenFeature's targeting key maps to `userId` by default. `targeting_key_field`, `key_separator`, `variation_key`, and `global_variable_prefix` can customize the mapping. The global variable prefix defaults to `variable` and cannot contain the separator.
 
 You can pass any Featurevisor initialization options directly to the provider. These options are used to create the Featurevisor instance owned by the provider:
 
@@ -901,7 +950,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 `v3.0.0`
 - The workflow verifies that the tag matches the shared version
 - The workflow publishes `featurevisor` first, followed by `featurevisor-openfeature`
 

data/bin/cli.rb

@@ -43,7 +43,7 @@ module FeaturevisorCLI
           options.environment = v
         end
 
-        opts.on("--feature=FEATURE", "Feature key (required for benchmark)") do |v|
+        opts.on("--feature=FEATURE", "Feature key") do |v|
           options.feature = v
         end
 
@@ -150,6 +150,6 @@ module FeaturevisorCLI
     puts "  featurevisor benchmark --feature=myFeature --environment=dev --n=10000"
     puts "  featurevisor assess-distribution --feature=myFeature --n=10000"
     puts ""
-    puts "Note: benchmark command requires --environment and --feature options"
+    puts "Note: benchmark requires --environment and either --feature or --variable"
   end
 end

data/bin/commands/benchmark.rb

@@ -22,8 +22,8 @@ module FeaturevisorCLI
           exit 1
         end
 
-        unless @options.feature
-          puts "Error: --feature is required for benchmark command"
+        unless @options.feature || @options.variable
+          puts "Error: --feature or --variable is required for benchmark command"
           exit 1
         end
 
@@ -41,7 +41,8 @@ module FeaturevisorCLI
         datafile_build_duration_ms = (datafile_build_duration * 1000).round
 
         puts "\nBenchmark Featurevisor feature"
-        puts "  Feature: #{@options.feature}"
+        puts "  Feature: #{@options.feature}" if @options.feature
+        puts "  Global variable: #{@options.variable}" if @options.variable && !@options.feature
         puts "  Environment: #{@options.environment}"
         puts "  Target: #{target}" if target
         puts "  Iterations: #{@options.n}"
@@ -59,7 +60,10 @@ module FeaturevisorCLI
         puts "Against context: #{context.to_json}"
 
         # Run the appropriate benchmark
-        if @options.variation
+        if @options.variable && !@options.feature
+          puts "Evaluating global variable \"#{@options.variable}\" #{@options.n} times..."
+          output = benchmark_global_variable(instance, @options.variable, context, @options.n)
+        elsif @options.variation
           puts "Evaluating variation #{@options.n} times..."
           output = benchmark_feature_variation(instance, @options.feature, context, @options.n)
         elsif @options.variable
@@ -223,6 +227,12 @@ module FeaturevisorCLI
         end
       end
 
+      def benchmark_global_variable(instance, variable_key, context, n)
+        benchmark_evaluation(n) do
+          instance.get_variable(variable_key, context)
+        end
+      end
+
       def format_value(value)
         if value.nil?
           "null"

data/bin/commands/test.rb

@@ -235,10 +235,12 @@ module FeaturevisorCLI
 
       def create_tester_instance(datafile, level, assertion)
         sticky = parse_sticky(assertion[:sticky])
+        sticky_variables = assertion[:stickyVariables].is_a?(Hash) ? assertion[:stickyVariables] : {}
 
         Featurevisor.create_featurevisor(
           datafile: datafile,
-          sticky: sticky,
+          sticky_features: sticky,
+          sticky_variables: sticky_variables,
           log_level: level,
           modules: [
             {
@@ -265,7 +267,7 @@ module FeaturevisorCLI
         tests.each do |test|
           test_key = test[:key]
           assertions = test[:assertions] || []
-          if test[:feature] && !@options.targets.empty?
+          if (test[:feature] || test[:variable]) && !@options.targets.empty?
             assertions = assertions.select do |assertion|
               assertion[:target].nil? || @options.targets.include?(assertion[:target])
             end
@@ -301,6 +303,14 @@ module FeaturevisorCLI
 
                   test_result = run_test_feature(assertion, test[:feature], instance, level)
                 end
+              elsif test[:variable]
+                datafile = resolve_datafile_for_assertion(assertion, datafiles_by_key)
+                if datafile
+                  instance = create_tester_instance(datafile, level, assertion)
+                  test_result = run_test_variable(assertion, test[:variable], instance)
+                else
+                  test_result = { has_error: true, errors: "      ✘ no datafile found for assertion target/environment combination\n", duration: 0 }
+                end
               elsif test[:segment]
                 segment_key = test[:segment]
                 segment = segments_by_key[segment_key]
@@ -347,6 +357,31 @@ module FeaturevisorCLI
         end
       end
 
+      def run_test_variable(assertion, variable_key, instance)
+        context = parse_context(assertion[:context])
+        options = {}
+        options[:default_variable_value] = assertion[:defaultVariableValue] if assertion.key?(:defaultVariableValue)
+        started = Time.now
+        errors = ""
+
+        if assertion.key?(:expectedValue)
+          actual = instance.get_variable(variable_key, context, options)
+          unless compare_values(actual, assertion[:expectedValue])
+            errors += "      ✘ expectedValue: expected #{assertion[:expectedValue].inspect} but received #{actual.inspect}\n"
+          end
+        end
+
+        if assertion[:expectedEvaluation].is_a?(Hash)
+          evaluation = instance.evaluate_variable(variable_key, context, options)
+          assertion[:expectedEvaluation].each do |key, expected|
+            actual = get_evaluation_value(evaluation, key)
+            errors += "      ✘ expectedEvaluation.#{key}: expected #{expected.inspect} but received #{actual.inspect}\n" unless compare_values(actual, expected)
+          end
+        end
+
+        { has_error: !errors.empty?, errors: errors, duration: Time.now - started }
+      end
+
       def run_test_feature(assertion, feature_key, instance, level)
         context = parse_context(assertion[:context])
         sticky = parse_sticky(assertion[:sticky])
@@ -354,7 +389,7 @@ module FeaturevisorCLI
         # Set context and sticky for this assertion
         instance.set_context(context, false)
         if sticky && !sticky.empty?
-          instance.set_sticky(sticky, false)
+          instance.set_sticky_features(sticky, false)
         end
 
         # Create override options
@@ -492,7 +527,7 @@ module FeaturevisorCLI
               # Create a local copy to ensure it's never nil
               child_sticky = sticky || {}
               if !child_sticky.empty?
-                child_instance.set_sticky(child_sticky, false)
+                child_instance.set_sticky_features(child_sticky, false)
               end
 
               child_result = run_test_feature_child(child, feature_key, child_instance, level)
@@ -671,7 +706,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
@@ -795,6 +830,8 @@ module FeaturevisorCLI
           evaluation[:force]
         when :required
           evaluation[:required]
+        when :requiredFeatures
+          evaluation[:required_features]
         when :sticky
           evaluation[:sticky]
         when :variation
@@ -809,6 +846,10 @@ module FeaturevisorCLI
           evaluation[:variable_schema]
         when :variableOverrideIndex
           evaluation[:variable_override_index]
+        when :variableOverrideKey
+          evaluation[:variable_override_key]
+        when :variableOverridePath
+          evaluation[:variable_override_path]
         else
           nil
         end

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