@rudderstack/featureflag-sdk-node

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)

import {
  isFeatureEnabled,
  getFeatureValue,
  isFeatureEnabledLatest,
  getFeatureValueLatest,
  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:

Cache Configuration

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

Provider Configuration

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

Default Traits Configuration

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.

Enabling Local Evaluation

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

Passing User Traits

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.

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.

Benefits of Local Evaluation

• 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

Limitations

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

Cached vs Latest Functions

Cached Functions (isFeatureEnabled, getFeatureValue)

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

Latest Functions (isFeatureEnabledLatest, getFeatureValueLatest)

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

• Application Initialization

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

• Critical Business Features

  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.

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.

MockFeatureFlagClient

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:

// 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 },
    ],
  ],
});

itTestAllFeatureCombinations

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

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.