featurevisor 2.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7745fb77b8646de51fe54b58c32274829b60b046e6a47d81872e3148107eac6
-  data.tar.gz: ef5f69f50e1af01af4b45aece70603a67dc77f3af08da98b10cf6e50dd3d77df
+  metadata.gz: 2cc7d95c6c897b09f4092c105b73b9776c6e4b6d1851dad7c2108ea8cced6b2b
+  data.tar.gz: 9b06c4ac0e499345af18967d161ef102b5636edd82dbf2013e15ae790ad7e832
 SHA512:
-  metadata.gz: 745e81a4af47bc19e0a0bfe550badafb52e7541a067f461bdbc8b73be259399da5ca3fd519e7458ee0afa3ee6f810e0d7e28446add35ee13e970f25ecc7a0d2d
-  data.tar.gz: 44947e427ceb1cf6b87e2e0784e7c77dddcbd8e27677c6794dd885a3a83dec65a4a2a1cec1815198abbe3e47187399700e9ec7e4342fd729428fafb21ab2dadd
+  metadata.gz: b2df8d3afe705ea850e4a77458c17d8090f4bf3b0ec27da761ef3447f8952ba0e2f970d0b1f75962c0c3402f01a2c8fe10b341a694eda2d17d5e004730f3aa51
+  data.tar.gz: ebd5698bbd941fbd2778350e6b7602375912a8455f0bd6af8ecd3034ca56d97b23c5803089c57a3a956fb638062838e65adeb3d38126bf4e72f5468512a54634

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,7 +90,7 @@ 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.
+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
 
@@ -295,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
 # {
@@ -321,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
 
@@ -333,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
@@ -345,6 +364,9 @@ f = Featurevisor.create_featurevisor(
     anotherFeatureKey: {
       enabled: false
     }
+  },
+  sticky_variables: {
+    welcomeMessage: 'Welcome back'
   }
 )
 ```
@@ -356,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',
@@ -368,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
@@ -393,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
 
@@ -430,7 +454,7 @@ load_datafile(f, "checkout")
 
 ### Updating datafile
 
-You can set the datafile as many times as you want in your application, which will result in emitting a [`datafile_set`](#datafile_set) event that you can listen and react to accordingly.
+You can set the datafile as many times as you want in your application, which will result in emitting a [`datafile_set`](#datafile-set) event that you can listen and react to accordingly.
 
 The triggers for setting the datafile again can be:
 
@@ -496,7 +520,7 @@ f = Featurevisor.create_featurevisor(
 
 Every diagnostic has `:level`, `:code`, `:message`, and an object-shaped `:details` hash. Optional `:module`, `:moduleName`, and `:originalError` fields describe provenance. Evaluation metadata belongs in `:details`.
 
-Diagnostic handlers are isolated from SDK behavior. An exception in a handler does not stop other handlers or evaluations.
+Diagnostic handlers are isolated from SDK behaviour. An exception in a handler does not stop other handlers or evaluations.
 
 
 ## Events
@@ -545,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`
@@ -583,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,7 +635,11 @@ And optionally these properties depending on whether you are evaluating a featur
 
 ## Modules
 
-Modules allow you to intercept the evaluation process and customize SDK behavior.
+Modules allow you to intercept the evaluation process and customize SDK behaviour.
+
+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.
+
+`before` and `after` remain available as deprecated feature-only compatibility callbacks. Use `before_evaluation` and `after_evaluation` for new modules so the same callbacks can handle feature and global variable evaluations.
 
 ### Defining a module
 
@@ -630,8 +665,8 @@ my_custom_module = {
     })
   },
 
-  # before evaluation
-  before: ->(options) {
+  # before feature or global variable evaluation
+  before_evaluation: ->(options) {
     # update context before evaluation
     options[:context] = options[:context].merge({
       someAdditionalAttribute: 'value'
@@ -639,13 +674,13 @@ my_custom_module = {
     options
   },
 
-  # after evaluation
-  after: ->(evaluation, options) {
+  # after feature or global variable evaluation
+  after_evaluation: ->(evaluation, options) {
     reason = evaluation[:reason]
     if reason == 'error'
       # log error
-      return
     end
+    evaluation
   },
 
   # configure bucket key
@@ -720,12 +755,14 @@ 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`
@@ -739,7 +776,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`
 
@@ -780,7 +818,7 @@ $ bundle exec featurevisor test \
 
 The Ruby test runner builds base datafiles and Target datafiles in memory via `npx featurevisor build --json`. When an assertion contains `target`, it is evaluated against the matching Target datafile.
 
-All three commands accept repeatable `--target=<target>` options. `test` builds only the selected Target datafiles and runs untargeted assertions plus assertions for those targets. `benchmark` and `assess-distribution` run independently against every selected Target datafile. Without `--target`, existing project-wide behavior is preserved. Project definitions, test specs, Target discovery, and datafile generation continue to come from the Node.js CLI.
+All three commands accept repeatable `--target=<target>` options. `test` builds only the selected Target datafiles and runs untargeted assertions plus assertions for those targets. `benchmark` and `assess-distribution` run independently against every selected Target datafile. Without `--target`, existing project-wide behaviour is preserved. Project definitions, test specs, Target discovery, and datafile generation continue to come from the Node.js CLI.
 
 ### Test against local monorepo's example-1
 
@@ -828,7 +866,7 @@ The provider currently requires Ruby 3.4 or newer because that is the minimum ve
 Install the provider:
 
 ```ruby
-gem "featurevisor-openfeature", "~> 2.0"
+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.
@@ -852,9 +890,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:
 
@@ -908,7 +946,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 `v2.0.0`
+- Tag the release with the same version number, for example `v3.1.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

@@ -223,22 +223,19 @@ module FeaturevisorCLI
         environment = assertion.key?(:environment) ? assertion[:environment] : false
         environment = false if environment.nil?
 
-        target_key = assertion[:target] ? target_datafile_key(environment, assertion[:target]) : nil
-        base_key = base_datafile_key(environment)
+        return datafiles_by_key[target_datafile_key(environment, assertion[:target])] if assertion[:target]
 
-        if target_key && datafiles_by_key.key?(target_key)
-          return datafiles_by_key[target_key]
-        end
-
-        datafiles_by_key[base_key]
+        datafiles_by_key[base_datafile_key(environment)]
       end
 
       def create_tester_instance(datafile, level, assertion)
-        sticky = parse_sticky(assertion[:sticky])
+        sticky = parse_sticky(assertion[:stickyFeatures] || 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 +262,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
@@ -299,7 +296,28 @@ module FeaturevisorCLI
                     puts ""
                   end
 
-                  test_result = run_test_feature(assertion, test[:feature], instance, level)
+                  begin
+                    test_result = run_test_feature(assertion, test[:feature], instance, level)
+                  ensure
+                    instance.close
+                  end
+                end
+              elsif test[:variable]
+                datafile = resolve_datafile_for_assertion(assertion, datafiles_by_key)
+                if datafile
+                  if @options.show_datafile
+                    puts ""
+                    puts JSON.pretty_generate(datafile)
+                    puts ""
+                  end
+                  instance = create_tester_instance(datafile, level, assertion)
+                  begin
+                    test_result = run_test_variable(assertion, test[:variable], instance)
+                  ensure
+                    instance.close
+                  end
+                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]
@@ -347,6 +365,64 @@ module FeaturevisorCLI
         end
       end
 
+      def run_test_variable(assertion, variable_key, instance)
+        instance.set_context(parse_context(assertion[:context]), true)
+        options = {}
+        options[:default_variable_value] = assertion[:defaultVariableValue] if assertion.key?(:defaultVariableValue)
+        started = Time.now
+        errors = ""
+
+        errors += test_variable_expectation(assertion, variable_key, instance, options)
+
+        Array(assertion[:children]).each_with_index do |child_assertion, child_index|
+          child = instance.spawn(
+            parse_context(child_assertion[:context]),
+            sticky_features: parse_sticky(child_assertion[:stickyFeatures]),
+            sticky_variables: child_assertion[:stickyVariables].is_a?(Hash) ? child_assertion[:stickyVariables] : {}
+          )
+          begin
+            child_options = {}
+            if child_assertion.key?(:defaultVariableValue)
+              child_options[:default_variable_value] = child_assertion[:defaultVariableValue]
+            end
+            errors += test_variable_expectation(
+              child_assertion,
+              variable_key,
+              child,
+              child_options,
+              "children[#{child_index}]."
+            )
+          ensure
+            child.close
+          end
+        end
+
+        { has_error: !errors.empty?, errors: errors, duration: Time.now - started }
+      end
+
+      def test_variable_expectation(assertion, variable_key, evaluator, options, prefix = "")
+        evaluation = evaluator.evaluate_variable(variable_key, {}, options)
+        errors = ""
+        if assertion.key?(:expectedValue) && !compare_values(evaluation[:variable_value], assertion[:expectedValue])
+          errors += "      ✘ #{prefix}expectedValue: expected #{format_test_value(assertion[:expectedValue])} but received #{format_test_value(evaluation[:variable_value])}\n"
+        end
+        if assertion[:expectedEvaluation].is_a?(Hash)
+          assertion[:expectedEvaluation].each do |key, expected|
+            actual = get_evaluation_value(evaluation, key)
+            unless compare_values(actual, expected)
+              errors += "      ✘ #{prefix}expectedEvaluation.#{key}: expected #{format_test_value(expected)} but received #{format_test_value(actual)}\n"
+            end
+          end
+        end
+        errors
+      end
+
+      def format_test_value(value)
+        JSON.generate(value)
+      rescue JSON::GeneratorError
+        value.inspect
+      end
+
       def run_test_feature(assertion, feature_key, instance, level)
         context = parse_context(assertion[:context])
         sticky = parse_sticky(assertion[:sticky])
@@ -354,7 +430,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
@@ -483,20 +559,16 @@ module FeaturevisorCLI
               child_context = parse_context(child[:context])
 
               # Create override options for child with sticky values
-              child_override_options = create_override_options(child)
-
-              # Pass sticky values to child instance
-              child_instance = instance.spawn(child_context, child_override_options)
-
-              # Set sticky values for child if they exist
-              # 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 = instance.spawn(
+                child_context,
+                sticky_features: sticky || {}
+              )
+              begin
+                child_result = run_test_feature_child(child, feature_key, child_instance, level)
+              ensure
+                child_instance.close
               end
 
-              child_result = run_test_feature_child(child, feature_key, child_instance, level)
-
               if child_result[:has_error]
                 has_error = true
                 errors += child_result[:errors]
@@ -795,6 +867,8 @@ module FeaturevisorCLI
           evaluation[:force]
         when :required
           evaluation[:required]
+        when :requiredFeatures
+          evaluation[:required_features]
         when :sticky
           evaluation[:sticky]
         when :variation
@@ -809,6 +883,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