JavaScript (Node)

The Hyphen Toggle Provider for Node.js is an OpenFeature provider implementation that enables seamless feature flag evaluation. This section covers setup, usage, and configuration specific to the JavaScript implementation.

Installation

Install the provider and the OpenFeature server SDK:

npm install @openfeature/server-sdk @hyphen/openfeature-server-provider

Setup and Initialization

To begin using the Hyphen Provider, follow these steps:

Import the required modules.
Configure the provider with your publicKey , application name and environment.
You can specify the environment in one of two formats:
- Alternate ID (e.g., "production", "staging") — the environment in which your application is running.
- Project Environment ID (e.g., pevr_abc123) — useful for internal references.
Register the provider with OpenFeature.

import { OpenFeature } from '@openfeature/server-sdk';  
import { HyphenProvider, type HyphenProviderOptions } from '@hyphen/openfeature-server-provider';

const publicKey = "your-public-key-here";

const options: HyphenProviderOptions = {
  application: 'your-application-name',
  environment: 'production', // or project environment ID
};

await OpenFeature.setProviderAndWait(new HyphenProvider(publicKey, options));

Configure the context needed for feature targeting evaluations, incorporating user or application context.

const context: HyphenEvaluationContext = {  
  targetingKey: 'user-123',  
  ipAddress: '203.0.113.42',  
  customAttributes: {  
    subscriptionLevel: 'premium',  
    region: 'us-east',  
  },  
  user: {  
    id: 'user-123',  
    email: '[email protected]',  
    name: 'John Doe',  
    customAttributes: {  
      role: 'admin',  
    },  
  },  
};

Usage

Evaluation Context Example

Evaluate a feature flag using the OpenFeature client and context information:

const client = OpenFeature.getClient();
const flagDetailsWithContext = await client.getBooleanDetails('feature-flag-key', false, context);

console.log(flagDetailsWithContext.value); // true or false

Configuration

Options

Option	Type	Required	Description
`application`	`string`	Yes	The application id or alternate ID.
`environment`	`string`	Yes	The environment identifier for the Hyphen project (project environment ID or alternateId).
`horizonUrls`	`string[]`	No	Hyphen Horizon URLs for fetching flags.
`enableToggleUsage`	`boolean`	No	Enable/disable telemetry (default: true).
`cache`	object	No	Configuration for caching feature flag evaluations.

Cache Configuration

The cache option accepts the following properties:

Property	Type	Default	Description
`ttlSeconds`	number	300	Time-to-live in seconds for cached flag evaluations.
`generateCacheKeyFn`	Function	-	Custom function to generate cache keys from evaluation context.

Example with cache configuration:

const options: HyphenProviderOptions = {
  application: 'your-application-name',
  environment: 'production',
  cache: {
    ttlSeconds: 600, // 10 minutes
    generateCacheKeyFn: (context: HyphenEvaluationContext) => {
      return `${context.targetingKey}-${context.user?.id}`;
    },
  },
};

Context

Provide an EvaluationContext to pass contextual data for feature evaluation.

Field	Type	Required	Description
`targetingKey`	`string`	Yes	The key used for caching the evaluation response.
`ipAddress`	`string`	No	The IP address of the user making the request.
`customAttributes`	`Record<string, any>`	No	Custom attributes for additional contextual information.
`user`	`object`	No	An object containing user-specific information for the evaluation.
`user.id`	`string`	No	The unique identifier of the user.
`user.email`	`string`	No	The email address of the user.
`user.name`	`string`	No	The name of the user.
`user.customAttributes`	`Record<string, any>`	No	Custom attributes specific to the user.

Example

const context: HyphenEvaluationContext = {  
  targetingKey: 'user-456',  
  customAttributes: {  
    subscriptionLevel: 'premium',  
  },  
};

const flagDetails = await client.getBooleanDetails('enable-discounts', false, context);

if (flagDetails.value) {  
  console.log('Discounts enabled for premium users.');  
} else {  
  console.log('No discounts available.');  
}