Feature Flag SDK

A flexible and extensible feature flag SDK that supports multiple providers and caching.

Features

- Support for multiple feature flag providers (Amplitude, Flagsmith)
- In-memory caching with customizable TTL
- TypeScript support
- Easy to extend with new providers
- Local evaluation support

Basic Usage

The SDK uses remote evaluation by default. Before using any feature flag functions, you must first initialize the SDK using initFeatureFlagClient. Once initialized, the SDK provides four main functions for interacting with feature flags:

- isFeatureEnabled - Check if a feature is enabled (cached)
- getFeatureValue - Get the value of a feature flag (cached)
- isFeatureEnabledLatest - Check if a feature is enabled (real-time)
- getFeatureValueLatest - Get the value of a feature flag (real-time)

``javascript
import {
isFeatureEnabled,
getFeatureValue,
isFeatureEnabledLatest,
getFeatureValueLatest,
updateEnvironment,
initFeatureFlagClient,
FeatureFlagSDKError,
} from '@rudderstack/featureflag-sdk-node';

// initialize feature flag client
initFeatureFlagClient({
provider: {
type: 'flagsmith',
apiKey: 'test-api-key',
},
});

// Using cached functions (recommended for most use cases)
async function processEvent(event) {
try {
const isEnabled = await isFeatureEnabled('workspaceId', 'myFeature');
if (isEnabled) {
// process event
}
} catch (error) {
if (error instanceof FeatureFlagSDKError) {
// handle feature flag error
console.error(Feature flag error: ${error.message});
}
}
}

// Using latest functions (for startup or critical real-time updates)
async function start() {
try {
// Get fresh values during startup
const features = await Promise.all([
getFeatureValueLatest('workspaceId', 'routing'),
getFeatureValueLatest('workspaceId', 'theme'),
]);
// Initialize app with latest values and start
} catch (error) {
if (error instanceof FeatureFlagSDKError) {
// handle feature flag error
console.error(Feature flag error: ${error.message});
}
}
}
`

SDK Configuration

The SDK configuration follows the FeatureFlagClientConfig interface, which includes the following options:

$3

| Configuration Option | Description | Default Value |
| -------------------- | --------------------------------------------------------------------------------------------------- | ------------- |
| cache.enabled | Enable/disable feature flag caching. Note: Cache must be disabled when local evaluation is enabled. | true |
| cache.ttlInSeconds | Time-to-live in seconds for cached values | 60 |

$3

| Configuration Option | Description | Default Value |
| -------------------------------- | --------------------------------------------------------------------------------------- | ------------- |
| provider.type | The feature flag provider to use (required) | - |
| provider.apiKey | API key for the feature flag provider (required) | - |
| provider.timeoutInSeconds | Timeout in seconds for provider API calls | 60 |
| provider.retryAttempts | Number of retry attempts for failed API calls | 3 |
| provider.enableLocalEvaluation | Enable/disable local evaluation of feature flags. When enabled, cache must be disabled. | false |
| provider.enableAnalytics | Enable/disable analytics reporting to the provider | true |

$3

| Configuration Option | Description | Default Value |
| -------------------- | ------------------------------------------------- | ------------- |
| defaultTraits | Default traits to use for feature flag evaluation | new Map() |

Local Evaluation

The SDK supports local evaluation of feature flags, which allows you to evaluate flags without making a network request to the feature flag provider every time. Only an initial download of the flag definitions and targeting rules is required. The SDK will keep refreshing the flag definitions and targeting rules from the provider periodically.

Note: When local evaluation is enabled, caching is disabled.
We implemented caching in combination with remote evaluation to reduce the number of API calls made to the feature flag provider and to increase the performance of the SDK.
However, with local evaluation, all flags are evaluated locally without making network requests to the feature flag provider. Therefore, it does not make sense to have both caching and local evaluation enabled. We internally disable caching when local evaluation is enabled. Since caching is disabled, the behavior of cached and latest functions will be the same.

$3

To enable local evaluation, you need to set provider.enableLocalEvaluation to true while calling the init function.

$3

When using local evaluation, you need to pass user traits when evaluating flags. These traits are used to determine the flag value based on targeting rules.

You can pass traits when evaluating feature flags by providing an optional third parameter along with the workspace ID and feature name.

`typescript
const isEnabled = await isFeatureEnabled('test-workspace', 'test-feature', {
[TRAIT_KEYS.ORGANIZATION_ID]: 'test-org-id',
});
`

Note: When local evaluation is enabled, passing user traits becomes necessary for proper flag evaluation, especially for flags that use targeting rules based on these traits.

$3

- Reduced Latency: Evaluates flags without network requests
- Offline Support: Can work without an internet connection
- Improved Performance: Faster flag evaluations for high-volume applications
- Reduced API Usage: Minimizes calls to the feature flag provider

$3

- Requires initial download of flag definitions
- May not have the most up-to-date flag configurations

Cached vs Latest Functions

$3

Recommended for:

- Regular feature checks during runtime
- Feature checks while processing events
- Frequent feature flag queries
- Performance-critical operations

Benefits:

- Faster response times
- Lower latency
- Reduced server load
- Better user experience

$3

Using latest functions only makes sense if the SDK is configured to use remote evaluation. See Local Evaluation for more details on how caching is disabled when local evaluation is enabled.

Best for:

- Application startup configuration
- Features that need guaranteed latest values
- One-time initialization
- Critical business logic requiring real-time values

Note: These functions make direct calls to the feature flag provider and may have higher latency. Use them sparingly and only when necessary.

When to Use Latest Functions

1. Application Initialization

`javascript
async function startupConfig() {
// Get fresh values during startup
const features = await Promise.all([
getFeatureValueLatest('workspaceId', 'routing'),
getFeatureValueLatest('workspaceId', 'theme'),
]);
// Initialize app with latest values
}
`

2. Critical Business Features
`javascript
async function processPayment() {
// Check latest feature state for critical operations
const paymentConfig = await getFeatureValueLatest('workspaceId', 'paymentProcessing');
// Process payment using latest configuration
}
`

Remember: While latest functions provide real-time values, they come with additional latency and server load. Use them judiciously and prefer cached functions for regular operations.

Refreshing Feature Flags

$3

The updateEnvironment() function forces an immediate refresh of the locally cached environment data from the feature flag provider. This is useful when you know that feature flags have been updated on the server and want to ensure your application has the latest configuration.

Important Notes:

- Currently implemented for the Flagsmith provider with local evaluation enabled (other providers use a no-op implementation)
- Only effective when enableLocalEvaluation: true - without local evaluation, there's no local environment cache to refresh
- It's a global operation that affects all workspaces
- The provider manages cache invalidation internally
- Safe to call with any provider or configuration - will no-op when not applicable

When to use:

1. External notification of flag changes

`javascript
// Webhook handler for flag updates
app.post('/webhooks/flagsmith', async (req, res) => {
// Flag was updated in Flagsmith
await updateEnvironment();
res.status(200).send('OK');
});
`

2. Scheduled cache refresh

`javascript
// Refresh flags every 5 minutes
setInterval(async () => {
try {
await updateEnvironment();
} catch (error) {
console.error('Failed to update environment:', error);
}
}, 5 60 1000);
`

3. Manual cache invalidation

`javascript
import { updateEnvironment } from '@rudderstack/featureflag-sdk-node';

async function refreshFlags() {
try {
await updateEnvironment();
console.log('Feature flags refreshed successfully');
} catch (error) {
console.error('Failed to refresh feature flags:', error);
}
}
`

Usage with Local Evaluation:

When using local evaluation mode (enableLocalEvaluation: true), updateEnvironment() is particularly useful because the SDK caches the environment document locally. Calling this function ensures your local cache is synchronized with the latest configuration from Flagsmith.

Testing Feature Flags

The SDK allows you to mock feature flags and test your application against different feature flag combinations using the provided testing utilities.To test your code with different feature flag settings, you can use the MockFeatureFlagClient to define a list of flags to test against and their combinations, and itTestAllFeatureCombinations to run your tests against all those combinations automatically.

$3

This client allows you to configure a list of feature flags to test against, you can also specify predefined combinations of those feature flags. If no combinations are provided, it will test your code against all possible combinations of the given feature flags:

`typescript
// Test all possible combinations
const mockClient = new MockFeatureFlagClient({
flags: [{ name: 'feature1' }, { name: 'feature2' }],
});

// Test specific combinations
const mockClient = new MockFeatureFlagClient({
flags: [{ name: 'feature1' }, { name: 'feature2' }],
combinations: [
[
{ name: 'feature1', enabled: true },
{ name: 'feature2', enabled: false },
],
[
{ name: 'feature1', enabled: false },
{ name: 'feature2', enabled: true },
],
],
});
`

$3

This is a utility function that will run your tests against all possible combinations of the feature flags you have configured in the MockFeatureFlagClient. It is a jest.It like utility function that takes a test case and runs it multiple times, once for each possible combination of feature flags.

The utility automatically:

- Mocks the feature flag client
- Cycles through all combinations
- Resets state between test suites

`typescript
describe('My Feature Tests', () => {
const mockClient = new MockFeatureFlagClient({
flags: [{ name: 'feature1' }, { name: 'feature2' }],
});

itTestAllFeatureCombinations(mockClient, 'should handle all combinations', async () => {
// Your test code here
// Will run once for each possible combination
});
});
``

A sample test case can be found in the sampleApp.test.ts file.