featurevisor 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42c8ec3e5bf6293eeae189365b0383588a8cf7fdd5a5ee249a6fd44a2676403c
-  data.tar.gz: ce5794865b3dd5a057b9e0841814dab1c276b52237f230e23da6317f8dea3f70
+  metadata.gz: 5951351cf7893e83e9f3994999f48389e1998bb8dec84092f3e7627f986bfd02
+  data.tar.gz: 3d24e02b8fd0708084b7716863396119728bcd83cbd0ac209b7a1c62fb982f68
 SHA512:
-  metadata.gz: 41aefa056806a97bc1f5bf13d847007fd4b38fb176f97d1a09868434644fda2ed8cd58698ad9f5002a6ef5d30f7fc105accf7d505eb41fb71abe28a5bda6e47c
-  data.tar.gz: e4376d46699b8fe730d4dc4f73890fd43c6e879c446bc484dc6a47cc6b2c31f715af41b83b5f6189f9b8eeed3fd61b48213ec589855d909fe7ebccb702c04303
+  metadata.gz: 368e45cb26cb6a98d13bc14b4fe9116bd36af47acadad3fbc99fc1926c8ce768edf5c9ade31aa36dd3c85ff95fc6dab2d3433d4d607bbeee99076a21838e0dae
+  data.tar.gz: 160b9eb960915113e3f9dfa3507b9f06664224ac3517d7a84432ec64d2d26d26c2ba379a09aeba64efe78a310972b5f497ad5d5ef1bbef1cc41ffa1408ffa70f

data/README.md

@@ -1,12 +1,13 @@
 # Featurevisor Ruby SDK <!-- omit in toc -->
 
-This is a port of Featurevisor [JavaScript SDK](https://featurevisor.com/docs/sdks/javascript/) v2.x to Ruby, providing a way to evaluate feature flags, variations, and variables in your Ruby applications.
+This is a port of Featurevisor [JavaScript SDK](https://featurevisor.com/docs/sdks/javascript/) v3.x to Ruby, providing a way to evaluate feature flags, variations, and variables in your Ruby applications.
 
-This SDK is compatible with [Featurevisor](https://featurevisor.com/) v2.0 projects and above.
+This SDK is compatible with Featurevisor v3 projects and v2 datafiles.
 
 ## Table of contents <!-- omit in toc -->
 
 - [Installation](#installation)
+- [Public API](#public-api)
 - [Initialization](#initialization)
 - [Evaluation types](#evaluation-types)
 - [Context](#context)
@@ -23,20 +24,23 @@ This SDK is compatible with [Featurevisor](https://featurevisor.com/) v2.0 proje
   - [Initialize with sticky](#initialize-with-sticky)
   - [Set sticky afterwards](#set-sticky-afterwards)
 - [Setting datafile](#setting-datafile)
+  - [Merging by default](#merging-by-default)
+  - [Replacing](#replacing)
+  - [Loading datafiles on demand](#loading-datafiles-on-demand)
   - [Updating datafile](#updating-datafile)
   - [Interval-based update](#interval-based-update)
-- [Logging](#logging)
+- [Evaluation details](#evaluation-details)
+- [Diagnostics](#diagnostics)
   - [Levels](#levels)
-  - [Customizing levels](#customizing-levels)
   - [Handler](#handler)
 - [Events](#events)
   - [`datafile_set`](#datafile_set)
   - [`context_set`](#context_set)
   - [`sticky_set`](#sticky_set)
-- [Evaluation details](#evaluation-details)
-- [Hooks](#hooks)
-  - [Defining a hook](#defining-a-hook)
-  - [Registering hooks](#registering-hooks)
+  - [`error`](#error)
+- [Modules](#modules)
+  - [Defining a module](#defining-a-module)
+  - [Registering modules](#registering-modules)
 - [Child instance](#child-instance)
 - [Close](#close)
 - [CLI usage](#cli-usage)
@@ -72,6 +76,18 @@ Or install it yourself as:
 $ gem install featurevisor
 ```
 
+## Public API
+
+The main runtime API is `Featurevisor.create_featurevisor`:
+
+```ruby
+f = Featurevisor.create_featurevisor(
+  datafile: datafile_content
+)
+```
+
+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.
+
 ## Initialization
 
 The SDK can be initialized by passing [datafile](https://featurevisor.com/docs/building-datafiles/) content directly:
@@ -89,7 +105,7 @@ response = Net::HTTP.get_response(URI(datafile_url))
 datafile_content = JSON.parse(response.body, symbolize_names: true)
 
 # Create SDK instance
-f = Featurevisor.create_instance(
+f = Featurevisor.create_featurevisor(
   datafile: datafile_content
 )
 ```
@@ -101,10 +117,10 @@ Alternatively, you can pass a JSON string directly and the SDK will parse it aut
 ```ruby
 # Option 1: Parse JSON yourself (recommended)
 datafile_content = JSON.parse(json_string, symbolize_names: true)
-f = Featurevisor.create_instance(datafile: datafile_content)
+f = Featurevisor.create_featurevisor(datafile: datafile_content)
 
 # Option 2: Pass JSON string directly (automatic parsing)
-f = Featurevisor.create_instance(datafile: json_string)
+f = Featurevisor.create_featurevisor(datafile: json_string)
 ```
 
 ## Evaluation types
@@ -142,7 +158,7 @@ You can set context at the time of initialization:
 ```ruby
 require 'featurevisor'
 
-f = Featurevisor.create_instance(
+f = Featurevisor.create_featurevisor(
   context: {
     deviceId: '123',
     country: 'nl'
@@ -274,6 +290,8 @@ f.get_variable_object(feature_key, variable_key, context = {})
 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
 
 You can get evaluations of all features available in the SDK instance:
@@ -304,12 +322,14 @@ This is handy especially when you want to pass all evaluations from a backend ap
 
 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.
+
 ### Initialize with sticky
 
 ```ruby
 require 'featurevisor'
 
-f = Featurevisor.create_instance(
+f = Featurevisor.create_featurevisor(
   sticky: {
     myFeatureKey: {
       enabled: true,
@@ -362,6 +382,49 @@ f.set_datafile(json_string)
 
 **Important**: When calling `set_datafile()`, ensure JSON is parsed with `symbolize_names: true` if you're parsing it yourself.
 
+### Merging by default
+
+By default, `set_datafile(datafile)` merges the incoming datafile into the SDK's current datafile:
+
+- top-level metadata such as `schemaVersion`, `revision`, and `featurevisorVersion` comes from the incoming datafile
+- `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.
+
+### Replacing
+
+To fully replace the stored datafile, pass `true` as the second argument:
+
+```ruby
+f.set_datafile(datafile_content, true)
+```
+
+### Loading datafiles on demand
+
+Because merging is the default, a single SDK instance can start with a small datafile and load more datafiles later as your application needs them, instead of downloading every feature upfront.
+
+This pairs well with [targets](https://featurevisor.com/docs/targets/), where each target produces a smaller datafile for a specific part of your application:
+
+```ruby
+require "open-uri"
+
+f = Featurevisor.create_featurevisor({})
+
+def load_datafile(f, target)
+  url = "https://cdn.yoursite.com/production/featurevisor-#{target}.json"
+  datafile = JSON.parse(URI.open(url).read, symbolize_names: true)
+
+  # merges into whatever was loaded before
+  f.set_datafile(datafile)
+end
+
+load_datafile(f, "products")
+
+# later, when the user reaches checkout
+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.
@@ -400,65 +463,38 @@ end
 Thread.new { update_datafile(f, datafile_url) }
 ```
 
-## Logging
+## Diagnostics
 
-By default, Featurevisor SDKs will print out logs to the console for `info` level and above.
+By default, Featurevisor reports diagnostics to the console for `info` level and above with a `[Featurevisor]` prefix.
 
 ### Levels
 
-These are all the available log levels:
-
-- `error`
-- `warn`
-- `info`
-- `debug`
-
-### Customizing levels
-
-If you choose `debug` level to make the logs more verbose, you can set it at the time of SDK initialization.
-
-Setting `debug` level will print out all logs, including `info`, `warn`, and `error` levels.
+Available diagnostic levels are `fatal`, `error`, `warn`, `info`, and `debug`.
 
-```ruby
-require 'featurevisor'
-
-f = Featurevisor.create_instance(
-  logger: Featurevisor.create_logger(level: 'debug')
-)
-```
-
-Alternatively, you can also set `log_level` directly:
+Set the level during initialization or update it afterwards:
 
 ```ruby
-f = Featurevisor.create_instance(
-  log_level: 'debug'
-)
-```
-
-You can also set log level from SDK instance afterwards:
-
-```ruby
-f.set_log_level('debug')
+f = Featurevisor.create_featurevisor(log_level: "debug")
+f.set_log_level("info")
 ```
 
 ### Handler
 
-You can also pass your own log handler, if you do not wish to print the logs to the console:
+Use `on_diagnostic` to send structured diagnostics to your observability system:
 
 ```ruby
-require 'featurevisor'
-
-f = Featurevisor.create_instance(
-  logger: Featurevisor.create_logger(
-    level: 'info',
-    handler: ->(level, message, details) {
-      # do something with the log
-    }
-  )
+f = Featurevisor.create_featurevisor(
+  log_level: "info",
+  on_diagnostic: ->(diagnostic) {
+    puts "#{diagnostic[:level]} #{diagnostic[:code]} #{diagnostic[:message]}"
+  }
 )
 ```
 
-Further log levels like `info` and `debug` will help you understand how the feature variations and variables are evaluated in the runtime against given context.
+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.
+
 
 ## Events
 
@@ -471,8 +507,8 @@ You can listen to these events that can occur at various stages in your applicat
 ```ruby
 unsubscribe = f.on('datafile_set') do |event|
   revision = event[:revision]        # new revision
-  previous_revision = event[:previous_revision]
-  revision_changed = event[:revision_changed] # true if revision has changed
+  previous_revision = event[:previousRevision]
+  revision_changed = event[:revisionChanged] # true if revision has changed
 
   # list of feature keys that have new updates,
   # and you should re-evaluate them
@@ -493,6 +529,8 @@ The `features` array will contain keys of features that have either been:
 
 compared to the previous datafile content that existed in the SDK instance.
 
+The event also includes `replaced`, which is `true` when the datafile replaced the previous content instead of merging into it.
+
 ### `context_set`
 
 ```ruby
@@ -515,6 +553,20 @@ unsubscribe = f.on('sticky_set') do |event|
 end
 ```
 
+### `error`
+
+```ruby
+unsubscribe = f.on('error') do |event|
+  diagnostic = event[:diagnostic]
+  code = diagnostic[:code]
+  message = diagnostic[:message]
+
+  puts "Featurevisor error: #{code} #{message}"
+end
+```
+
+The `error` event is emitted for diagnostics reported with `level: "error"`.
+
 ## Evaluation details
 
 Besides logging with debug level enabled, you can also get more details about how the feature variations and variables are evaluated in the runtime against given context:
@@ -547,22 +599,33 @@ And optionally these properties depending on whether you are evaluating a featur
 - `variable_value`: the variable value
 - `variable_schema`: the variable schema
 
-## Hooks
+## Modules
+
+Modules allow you to intercept the evaluation process and customize SDK behavior.
 
-Hooks allow you to intercept the evaluation process and customize it further as per your needs.
+### Defining a module
 
-### Defining a hook
+A module is a simple hash with a unique recommended `name` and optional lifecycle functions:
 
-A hook is a simple hash with a unique required `name` and optional functions:
+If `setup` raises an exception, the module is not registered. Featurevisor removes subscriptions created during setup, reports `module_setup_error`, and calls `close` when present.
 
 ```ruby
 require 'featurevisor'
 
-my_custom_hook = {
-  # only required property
-  name: 'my-custom-hook',
+my_custom_module = {
+  # recommended, and used for duplicate detection/removal
+  name: 'my-custom-module',
+
+  # rest of the properties below are all optional per module
+
+  # setup once, when the module is registered
+  setup: ->(api) {
+    revision = api[:get_revision].call
 
-  # rest of the properties below are all optional per hook
+    api[:on_diagnostic].call(->(diagnostic) {
+      puts diagnostic[:message]
+    })
+  },
 
   # before evaluation
   before: ->(options) {
@@ -592,26 +655,43 @@ my_custom_hook = {
   bucket_value: ->(options) {
     # return custom bucket value
     options[:bucket_value]
+  },
+
+  # cleanup when module is removed or SDK is closed
+  close: -> {
+    # cleanup here
   }
 }
 ```
 
-### Registering hooks
+The module API passed to `setup` exposes:
+
+- `get_revision`
+- `on_diagnostic`
+- `report_diagnostic`
 
-You can register hooks at the time of SDK initialization:
+### Registering modules
+
+You can register modules at the time of SDK initialization:
 
 ```ruby
 require 'featurevisor'
 
-f = Featurevisor.create_instance(
-  hooks: [my_custom_hook]
+f = Featurevisor.create_featurevisor(
+  modules: [my_custom_module]
 )
 ```
 
 Or after initialization:
 
 ```ruby
-f.add_hook(my_custom_hook)
+remove_module = f.add_module(my_custom_module)
+
+# remove later by calling the returned function
+remove_module.call
+
+# or remove by name
+f.remove_module('my-custom-module')
 ```
 
 ## Child instance
@@ -687,29 +767,24 @@ $ bundle exec featurevisor test \
   --quiet|--verbose \
   --onlyFailures \
   --keyPattern="myFeatureKey" \
-  --assertionPattern="#1" \
-  --with-scopes \
-  --with-tags
+  --assertionPattern="#1"
 ```
 
-`--with-scopes` and `--with-tags` make the Ruby test runner build scoped/tagged datafiles in memory (via `npx featurevisor build --json`) and evaluate matching assertions against those exact datafiles.
-
-If an assertion references `scope` and `--with-scopes` is not provided, the runner still evaluates the assertion by merging that scope's configured context into the assertion context (without building scoped datafiles).
+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.
 
-For compatibility, camelCase aliases are also supported: `--withScopes` and `--withTags`.
+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.
 
 ### Test against local monorepo's example-1
 
 ```bash
 $ cd /absolute/path/to/featurevisor-ruby
-$ bundle exec featurevisor test --projectDirectoryPath=./monorepo/examples/example-1
-$ bundle exec featurevisor test --projectDirectoryPath=./monorepo/examples/example-1 --with-scopes
-$ bundle exec featurevisor test --projectDirectoryPath=./monorepo/examples/example-1 --with-tags
+$ bundle exec ruby bin/featurevisor test --projectDirectoryPath=/Users/fahad/Projects/featurevisor/featurevisor/examples/example-1 --onlyFailures
+$ make test-example-1
 ```
 
 ### Benchmark
 
-Learn more about benchmarking [here](https://featurevisor.com/docs/cmd/#benchmarking).
+Learn more about benchmarking [here](https://featurevisor.com/docs/cli/#benchmarking).
 
 ```bash
 $ bundle exec featurevisor benchmark \
@@ -722,7 +797,7 @@ $ bundle exec featurevisor benchmark \
 
 ### Assess distribution
 
-Learn more about assessing distribution [here](https://featurevisor.com/docs/cmd/#assess-distribution).
+Learn more about assessing distribution [here](https://featurevisor.com/docs/cli/#assess-distribution).
 
 ```bash
 $ bundle exec featurevisor assess-distribution \

data/bin/cli.rb

@@ -7,12 +7,13 @@ module FeaturevisorCLI
     attr_accessor :command, :assertion_pattern, :context, :environment, :feature,
                  :key_pattern, :n, :only_failures, :quiet, :variable, :variation,
                  :verbose, :inflate, :show_datafile, :schema_version, :project_directory_path,
-                 :populate_uuid, :with_scopes, :with_tags
+                 :populate_uuid, :with_scopes, :with_tags, :targets
 
     def initialize
       @n = 1000
       @project_directory_path = Dir.pwd
       @populate_uuid = []
+      @targets = []
     end
   end
 
@@ -82,15 +83,15 @@ module FeaturevisorCLI
           options.show_datafile = true
         end
 
-        opts.on("--schemaVersion=VERSION", "Schema version") do |v|
+        opts.on("--schemaVersion=VERSION", "--schema-version=VERSION", "Legacy schema version option accepted and ignored") do |v|
           options.schema_version = v
         end
 
-        opts.on("--with-scopes", "--withScopes", "Test scoped assertions against scoped datafiles") do
+        opts.on("--with-scopes", "--withScopes", "Legacy scope option accepted and ignored") do
           options.with_scopes = true
         end
 
-        opts.on("--with-tags", "--withTags", "Test tagged assertions against tagged datafiles") do
+        opts.on("--with-tags", "--withTags", "Legacy tag option accepted and ignored") do
           options.with_tags = true
         end
 
@@ -102,6 +103,10 @@ module FeaturevisorCLI
           options.populate_uuid << v
         end
 
+        opts.on("--target=TARGET", "Target datafile; repeat for multiple targets") do |v|
+          options.targets << v unless options.targets.include?(v)
+        end
+
         opts.on("-h", "--help", "Show this help message") do
           puts opts
           exit

data/bin/commands/assess_distribution.rb

@@ -29,13 +29,21 @@ module FeaturevisorCLI
           exit 1
         end
 
-        puts ""
-        puts "Assessing distribution for feature: \"#{@options.feature}\"..."
-        puts ""
-
-        # Parse context if provided
         context = parse_context
 
+        targets = resolve_targets
+        (targets.empty? ? [nil] : targets).each { |target| run_for_target(context, target) }
+      end
+
+      private
+
+      def run_for_target(context, target)
+        puts "\nAssess Featurevisor distribution"
+        puts "  Feature: #{@options.feature}"
+        puts "  Environment: #{@options.environment}"
+        puts "  Target: #{target}" if target
+        puts "  Iterations: #{@options.n}"
+
         # Print context information
         if @options.context
           puts "Against context: #{@options.context}"
@@ -47,10 +55,10 @@ module FeaturevisorCLI
         puts ""
 
         # Build datafile
-        datafile = build_datafile(@options.environment)
+        datafile = build_datafile(@options.environment, target)
 
         # Create SDK instance
-        instance = create_instance(datafile)
+        instance = create_featurevisor(datafile)
 
         # Check if feature has variations
         feature = instance.get_feature(@options.feature)
@@ -104,7 +112,21 @@ module FeaturevisorCLI
         end
       end
 
-      private
+      def resolve_targets
+        return [] if @options.targets.empty?
+        stdout, stderr, status = Open3.capture3("npx", "featurevisor", "list", "--targets", "--json", chdir: @project_path)
+        unless status.success?
+          puts stderr
+          exit 1
+        end
+        available = JSON.parse(stdout).map { |item| item.is_a?(Hash) ? (item["key"] || item["name"]) : item }
+        unknown = @options.targets.find { |target| !available.include?(target) }
+        if unknown
+          puts "Unknown target \"#{unknown}\". Available targets: #{available.empty? ? "none" : available.join(", ")}."
+          exit 1
+        end
+        @options.targets
+      end
 
       def parse_context
         if @options.context
@@ -121,15 +143,12 @@ module FeaturevisorCLI
         end
       end
 
-      def build_datafile(environment)
+      def build_datafile(environment, target = nil)
         puts "Building datafile for environment: #{environment}..."
 
         # Build the command similar to Go implementation
         command_parts = ["cd", @project_path, "&&", "npx", "featurevisor", "build", "--environment=#{environment}", "--json"]
-
-        if @options.schema_version
-          command_parts << "--schemaVersion=#{@options.schema_version}"
-        end
+        command_parts << "--target=#{target}" if target
 
         if @options.inflate
           command_parts << "--inflate=#{@options.inflate}"
@@ -159,9 +178,9 @@ module FeaturevisorCLI
         [stdout, stderr, exit_status.exitstatus]
       end
 
-      def create_instance(datafile)
+      def create_featurevisor(datafile)
         # Create SDK instance
-        Featurevisor.create_instance(
+        Featurevisor.create_featurevisor(
           datafile: datafile,
           log_level: get_logger_level
         )