Skip to main content

Evaluation API

The Evaluation API is the primary component of OpenFeature that application authors interact with. The Evaluation API allows developers to evaluate feature flags to alter control flow and application characteristics.

Setting a Provider

Before you can start evaluating flags, you must set a provider. The provider is the translation layer between the evaluation API and the flag system you use.

import { OpenFeature } from '@openfeature/js-sdk';

OpenFeature.setProvider(new YourProviderOfChoice());

Creating a client

The OpenFeature client is a lightweight abstraction used to evaluate feature flags. If your application is small, you may use a single client for your whole application. In larger applications, it may be helpful to create multiple clients, each with different configuration to fit the needs of different sub-modules. Clients may also be created dynamically, per each HTTP request, for instance.

const client = OpenFeature.getClient('my-app');

Flag Evaluation

Basic Evaluation

The client can be used to do basic flag evaluation, which simply returns flag values of a particular type. The default value must also be specified. In the case of any error during flag evaluation, the default value will be returned, so give consideration to your default values!

// get a bool value
const boolValue = await client.getBooleanValue('boolFlag', false);

// get a string value
const stringValue = await client.getStringValue('stringFlag', 'default');

// get an numeric value
const numberValue = await client.getNumberValue('intFlag', 1);

// get an object value
const object = await client.getObjectValue<MyObject>('objectFlag', {});

Detailed Evaluation

In addition to basic evaluation, detailed evaluation methods are available. These return the value, as well as additional metadata about the flag evaluation in the Evaluation Details structure.

Evaluation Details Structure Fields

FieldDescription
flag keythe unique identifier for a feature flag
valuethe value returned from a flag evaluation
reason (optional)a string explaining why the flag value was returned
variant (optional)the variant associated with the return flag value
error code (optional)an error code that categorizes flag evaluation errors
error message (optional)a string detailing the error
// get details of boolean evaluation
const boolDetails = await client.getBooleanDetails('boolFlag', false);

// get details of string evaluation
const stringDetails = await client.getStringDetails('stringFlag', 'default');

// get details of numeric evaluation
const numberDetails = await client.getNumberDetails('intFlag', 1);

// get details of object evaluation
const objectDetails = await client.getObjectDetails<MyObject>('objectFlag', {});