Considering alternatives to the OpenFeature global singleton

[toddbaert]

The OpenFeature API features a global singleton. Though this has advantages (ease-of-use, available everywhere without pollute the call stack, facilitation of transparent 3rd party integrations) it also causes issues. A couple examples:

• can break tests, particularly in languages like Java, where tests mutating the singleton can trample on each-other
• micro-frontends, which combine multiple codebases which each might maniplate the singleton
• server-side programs comprised of multiple submodules, each setting their own provider
• DI frameworks and IoC containers, which inherently don't work well with singletons managed outside their scope

We'd like to explore means of "opting out" or working around the singleton.

OpenFeature Singleton Brainstorming Meeting

Find below resources from our Dec 18th meeting on this topic (LFX account required for some assets):

• Transcript + Recording: https://zoom.us/rec/share/OQUwHFumc1DXRumVxIpD1BKq_epVS9ajj00jJ-7Vt4oLQCLMrW3P7waEvVb_Nw7I.CxKvHOr4meTgZjEd
• AI Meeting Summary: https://zoom-lfx.platform.linuxfoundation.org/meeting/96839205440-1766073600000/summaries?password=db7e61a2-5aa4-4e19-ad42-c34799ce1397

Questions/comments

• In javascript, why did we bind the singleton to window - truely global - vs. binding to the module
  • Todd says because we intentionally wanted to make the API object a true globalton
• Next.js - issues here because server-side rendered code is half-dynamic-context, half-static-context paradigm
• If you can have multiple API objects floating around, what's the value in distinguishing between client and API
  • We could still keep separate interfaces that are backed by the same object instances, even if we did this

Solutions

Option A

Expose ability to create non-singleton instances of the API object

• Benefits
  • Simple solution
  • Potential to allow us to remove "domains" concept
• Drawbacks
  • Could be some gotchas
    • Bit of a fear of unknown-unknowns.
      • Some deep research on where we assume a globalton would be needed
    • ? bugs around shutdown lifecycle
  • Confusing footgun - new user might stumble into newing up when they should use the singleton
    • Could we mitigate this by not exposing the ctor but instead exposing OpenFeature.advanced_use_only_new_instance() or whatever
      • Matt proposes OpenFeature.isolated()
      • Jonathan proposes hiding it in a different class
  • We would need to ensure that a specific provider instance cannot be bound to multiple API instances
    • Event lifecycle etc.
  • If we replaced domains with this then it could make end-user code more complex/boilerplate-y

Option B

Add methods to the singleton that would give you an isolated scope - sort of like "domains" in the client?

• Drawbacks
  • Adds a lot of surface area to the api

Option C

JS-specific solution: bind the singleton at module scope, rather than on window

Option D

Extended API so that you can specify a provider when you create a client
This is what .NET impl does already for DI

• Benefits
  • Seems to be working well in .NET so far (dynamic context only)
• Drawbacks
  • Need to expose more on API surface area in order to support context management in "user land"
    • On client, and possibly also on provider (:scream:)
  • Opening up the option means we have to support it everywhere, which means the value of the API class sort of evaporates

Actions

PoC some of the options and present back findings

• @MattIPv4 offers to PoC Option A
• @jonathannorris offers to PoC Option A where we have a separate class or factory function or whatever, to make the footgun less discoverable
• @lukas-reining wants to PoC ensuring that a provider instance can only be bound to a single API instance (if we went down the Option A path)
• @cupofcat offers to prototype options in Go, starting mid Jan

[MattIPv4]

My PoC for Option A: open-feature/js-sdk#1303

[jonathannorris]

Based on the discussions during the meeting, and some digging through @MattIPv4 PR: open-feature/js-sdk#1303, I worked with Cursor to put together some options for how to isolate this new non-singleton interface from the default existing OpenFeature singleton interface. Thinking through these I agree that Option C of a separate path export is probably the way to get the most seperation from the existing OpenFeature interfaces.

Proposal: Non-Singleton OpenFeature API Access

This document proposes three alternative approaches to support isolated (non-singleton) OpenFeature instances without modifying the core OpenFeatureAPI class interface.

Problem Statement

The current branch adds getIsolated() directly to the singleton, which:

• Modifies the core OpenFeatureAPI class interface
• Makes isolated instances easily discoverable (potentially leading to misuse)
• Blurs the line between singleton and non-singleton usage patterns

Goal

• Keep OpenFeatureAPI class unchanged
• Make isolated instances available but less discoverable
• Clearly separate singleton vs non-singleton usage patterns

---

Option A: Standalone Factory Function

Export a separate factory function that creates new instances.

Interface Changes (packages/web/src/open-feature.ts)

// Keep OpenFeatureAPI class UNCHANGED (revert getInstance changes)
export class OpenFeatureAPI extends OpenFeatureCommonAPI<...> {
  private constructor() { super('client'); }
  
  static getInstance(): OpenFeatureAPI {
    // Only singleton logic, no boolean parameter
  }
}

// Singleton export (unchanged)
export const OpenFeature = OpenFeatureAPI.getInstance();

/**
    * Creates a new isolated OpenFeature API instance.
    * 
    * WARNING: This creates a non-singleton instance that does NOT share state
    * with the global OpenFeature singleton. Only use this in micro-frontend
    * architectures where isolation is explicitly required.
    * 
    * @internal This API is intended for advanced use cases only.
 */
export function createIsolatedOpenFeatureAPI(): OpenFeatureAPI {
  // Requires making constructor accessible or using a factory pattern
  return OpenFeatureAPI['createInstance']();
}

Usage

import { createIsolatedOpenFeatureAPI } from '@openfeature/web-sdk';

// Create an isolated instance for this micro-frontend
const MyOpenFeature = createIsolatedOpenFeatureAPI();
MyOpenFeature.setProvider(myProvider);
const client = MyOpenFeature.getClient();

Cross-Language Compatibility

This option has excellent cross-language support - adding a factory function is trivial in all languages:

Language	Implementation	Complexity
Node.js/Web/React/Angular	export function createIsolatedOpenFeatureAPI()	Trivial
Go	func NewOpenFeatureAPI() *OpenFeatureAPI	Trivial
Java	public static OpenFeatureAPI createIsolated()	Trivial
.NET	public static OpenFeatureApi CreateIsolated()	Trivial
Python	def create_isolated_openfeature_api()	Trivial
Ruby	def self.create_isolated	Trivial
PHP	public static function createIsolated()	Trivial
Rust	pub fn create_isolated() -> OpenFeatureAPI	Trivial
Dart	static OpenFeatureAPI createIsolated()	Trivial
Kotlin	fun createIsolatedOpenFeatureAPI()	Trivial
Swift	static func createIsolated() -> OpenFeatureAPI	Trivial

Pros/Cons

• Pro: Clear separation - users must explicitly import the factory
• Pro: No changes to OpenFeatureAPI class interface
• Pro: Simplest to implement across all SDK languages
• Pro: No build/packaging changes required
• Con: Factory function is still easily discoverable via autocomplete

---

Option B: Separate Factory Class

Create a dedicated factory class for creating instances.

Interface Changes (packages/web/src/open-feature.ts)

// Keep OpenFeatureAPI class UNCHANGED
export class OpenFeatureAPI extends OpenFeatureCommonAPI<...> {
  private constructor() { super('client'); }
  
  static getInstance(): OpenFeatureAPI { /* singleton only */ }
}

// Singleton export (unchanged)
export const OpenFeature = OpenFeatureAPI.getInstance();

/**
    * Factory for creating isolated OpenFeature API instances.
    * 
    * @internal This class is intended for advanced micro-frontend use cases.
    * Most applications should use the global `OpenFeature` singleton instead.
 */
export class OpenFeatureAPIFactory {
  /**
            * Creates a new isolated OpenFeature API instance.
            * 
            * Each instance has its own providers, context, and event emitters.
            * State is NOT shared with the global singleton or other isolated instances.
   */
  static create(): OpenFeatureAPI {
    return OpenFeatureAPI['createInstance']();
  }
}

Usage

import { OpenFeatureAPIFactory } from '@openfeature/web-sdk';

// Create an isolated instance for this micro-frontend
const MyOpenFeature = OpenFeatureAPIFactory.create();
MyOpenFeature.setProvider(myProvider);
const client = MyOpenFeature.getClient();

Cross-Language Compatibility

This option has excellent cross-language support - factory classes are idiomatic in most languages:

Language	Implementation	Complexity
Node.js/Web/React/Angular	class OpenFeatureAPIFactory { static create() }	Trivial
Go	type OpenFeatureAPIFactory struct + method	Easy
Java	class OpenFeatureApiFactory { static create() }	Trivial
.NET	class OpenFeatureApiFactory { static Create() }	Trivial
Python	class OpenFeatureAPIFactory	Trivial
Ruby	class OpenFeatureAPIFactory	Trivial
PHP	class OpenFeatureAPIFactory	Trivial
Rust	struct OpenFeatureAPIFactory + impl	Easy
Dart	class OpenFeatureAPIFactory	Trivial
Kotlin	object OpenFeatureAPIFactory	Trivial
Swift	class OpenFeatureAPIFactory	Trivial

Pros/Cons

• Pro: Factory pattern is a well-known design pattern
• Pro: Groups related functionality (could add createWithProvider() etc later)
• Pro: Easy to implement across all SDK languages
• Con: Additional class export to maintain
• Con: Factory class is still easily discoverable via autocomplete

---

Option C: Separate Sub-path Export

Export isolated functionality from a separate module path.

New File: packages/web/src/isolated.ts

/**
    * @module @openfeature/web-sdk/isolated
    * 
    * WARNING: This module provides non-singleton OpenFeature instances.
    * Only use this in micro-frontend architectures where isolation is required.
    * 
    * For standard applications, use the default export from '@openfeature/web-sdk'.
 */

import { OpenFeatureAPI } from './open-feature';

/**
    * Creates a new isolated OpenFeature API instance.
 */
export function createOpenFeatureAPI(): OpenFeatureAPI {
  return OpenFeatureAPI['createInstance']();
}

// Could also re-export types needed for isolated usage
export type { OpenFeatureAPI } from './open-feature';

Package.json Exports (packages/web/package.json)

{
  "exports": {
    ".": {
      "import": "./dist/esm/index.js",
      "require": "./dist/cjs/index.js"
    },
    "./isolated": {
      "import": "./dist/esm/isolated.js",
      "require": "./dist/cjs/isolated.js"
    }
  }
}

Usage

import { createOpenFeatureAPI } from '@openfeature/web-sdk/isolated';

// Create an isolated instance for this micro-frontend
const MyOpenFeature = createOpenFeatureAPI();
MyOpenFeature.setProvider(myProvider);
const client = MyOpenFeature.getClient();

Cross-Language Compatibility

This option requires different mechanisms per language but is universally achievable:

Language	Mechanism	Complexity	Example Import
Node.js/Web/React/Angular	package.json exports	Easy	@openfeature/web-sdk/isolated
Go	Sub-module	Easy	go.openfeature.dev/sdk/isolated
Java	Separate package or Maven module	Medium	dev.openfeature.sdk.isolated
.NET	Separate namespace or NuGet	Medium	OpenFeature.Isolated
Python	Sub-module	Easy	from openfeature.isolated import ...
Ruby	Separate file require	Easy	require 'openfeature/isolated'
PHP	Separate namespace	Easy	use OpenFeature\Isolated\...
Rust	Feature flag or sub-module	Easy	openfeature::isolated::create()
Dart	Separate library file	Easy	import 'package:openfeature/isolated.dart'
Kotlin	Separate package	Easy	dev.openfeature.sdk.isolated
Swift	Separate module/target	Medium	import OpenFeatureIsolated

Pros/Cons

• Pro: Maximum separation - different import path signals different behavior
• Pro: Not discoverable via autocomplete on the main module
• Pro: Could be tree-shaken if unused
• Pro: Easy to document as "advanced" in separate README section
• Con: Requires package.json/build configuration changes
• Con: Different mechanism per language (less consistency)
• Con: Java/.NET/Swift may need separate packages/assemblies

---

React SDK Changes (All Options)

For all options, the React OpenFeatureProvider would accept an optional prop for passing an isolated instance:

interface ProviderProps {
  domain?: string;
  /** 
            * An isolated OpenFeature API instance to use instead of the global singleton.
            * Only use this in micro-frontend architectures where isolation is required.
            * @see createOpenFeatureAPI from '@openfeature/web-sdk/isolated'
   */
  isolatedInstance?: OpenFeatureAPI;
  children: React.ReactNode;
}

Usage with isolated instance:

import { createOpenFeatureAPI } from '@openfeature/web-sdk/isolated'; // Option C
import { OpenFeatureProvider } from '@openfeature/react-sdk';

const MyOpenFeature = createOpenFeatureAPI();
MyOpenFeature.setProvider(myProvider);

function App() {
  return (
    <OpenFeatureProvider isolatedInstance={MyOpenFeature}>
      {children}
    </OpenFeatureProvider>
  );
}

---

Recommendation Summary

Option	Discoverability Friction	Cross-Language Consistency	Implementation Effort
A: Factory Function	Low	High	Low
B: Factory Class	Low	High	Low
C: Sub-path Export	High	Medium	Medium

• Option A is recommended if simplicity and cross-language consistency are priorities
• Option C is recommended if making isolated instances hard to discover is the priority

Discussion Points

1. Should isolated instances have the exact same type as singleton, or a distinct type?
2. How should React SDK hooks like useContextMutator handle isolated instances?

[MattIPv4]

All of those JS examples seem to rely on calling OpenFeatureAPI['createInstance'](), so this would still be discoverable by doing import { OpenFeatureAPI } from '@openfeature/web-sdk'; OpenFeatureAPI.createInstance() (similar to today, how you can do import { OpenFeatureAPI } from '@openfeature/web-sdk'; OpenFeatureAPI.getInstance() to access the singleton). I'm not sure I see how this is any higher friction than import { OpenFeature } from '@openfeature/web-sdk'; OpenFeature.getIsolated() that I'm currently proposing (or any of the other low-friction suggestions here)? Is there a mechanism we can use to ensure this can only be done through the high-friction import?