@hyphen/sdk

Hyphen Node.js SDK

The Hyphen Node.js SDK is a JavaScript library that allows developers to easily integrate Hyphen's feature flag service Toggle, secret management service ENV, and geo information service Net Info into their Node.js applications.

Table of Contents

• Installation
• Basic Usage
• Toggle
  • Toggle Options
  • Toggle API
  • Toggle Hooks
  • Toggle Error Handling
  • Toggle Caching
  • Toggle Environment Variables
  • Toggle Self-Hosted
• ENV
  • Loading Environment Variables
• Net Info
• Contributing
• Testing Your Changes
• License and Copyright

Installation

To install the Hyphen Node.js SDK, you can use npm or yarn. Run the following command in your terminal:

npm install @hyphen/sdk

Basic Usage

There are many ways to use the Hyphen Node.js SDK. Because of this we have created examples for each of the different ways in each secton of the documentation.

Toggle

Toggle is our feature flag service that allows you to control the rollout of new features to your users. You can access your feature flags using the Toggle class.

import { Toggle, ToggleContext } from '@hyphen/sdk';

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

const toggleOptions = {
  publicApiKey: 'your_public_api_key',
  applicationId: 'your_application_id',
  context: context,
};

const toggle = new Toggle(toggleOptions);

const result = await toggle.getBoolean('hyphen-sdk-boolean', false);

console.log('Boolean toggle value:', result); // true

if you want to set the context you can do it like this:

import { Toggle, ToggleContext } from '@hyphen/sdk';

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

const toggleOptions = {
  publicApiKey: 'your_public_api_key',
  applicationId: 'your_application_id',
};

const toggle = new Toggle(toggleOptions);

toggle.setContext(context);

const result = await toggle.getBoolean('hyphen-sdk-boolean', false);

console.log('Boolean toggle value:', result); // true

if you would like to override the context for a single request you can do it like this:

import { Toggle, ToggleContext } from '@hyphen/sdk';

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

const toggleOptions = {
  publicApiKey: 'your_public_api_key',
  applicationId: 'your_application_id',
  context: context,
};

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

const toggle = new Toggle(toggleOptions);

const result = await toggle.getBoolean('hyphen-sdk-boolean', false, { context: overrideContext });

console.log('Boolean toggle value:', result); // true

Toggle Options

Option	Type	Description
publicApiKey	string	The public API key for your Hyphen project. You can find this in the Hyphen dashboard.
applicationId	string	The application ID for your Hyphen project. You can find this in the Hyphen dashboard.
environment?	string	The environment for your Hyphen project such as production. Default uses process.env.NODE_ENV
context?	ToggleContext	The context object that contains the user and custom attributes. This is optional.
caching?	{ ttl: number, generateCacheKeyFn: (context?: ToggleContext) => string}	Whether to use the cache or not and a function to set the key. The ttl is in seconds

Toggle API

Method	Parameters	Description
setContext	context: ToggleContext	Set the context for the toggle. This is optional.
get	key: string, defaultValue: T, options?: ToggleGetOptions	Get the value of a toggle. This is a generic method that can be used to get any type from toggle.
getBoolean	key: string, defaultValue: boolean, options?: ToggleGetOptions	Get the value of a boolean toggle.
getNumber	key: string, defaultValue: number, options?: ToggleGetOptions	Get the value of a number toggle.
getString	key: string, defaultValue: string, options?: ToggleGetOptions	Get the value of a string toggle.
getObject	key: string, defaultValue: any, options?: ToggleGetOptions	Get the value of a object toggle.

Toggle Hooks

The following hooks are available for Toggle:

Hook	object	Description
beforeGetBoolean	{ key: string, defaultValue:boolean, options?: ToggleGetOptions }	Called before the boolean toggle is fetched.
afterGetBoolean	{ key: string, defaultValue:boolean, options?: ToggleGetOptions, result: boolean }	Called after the boolean toggle is fetched.
beforeGetNumber	{ key: string, defaultValue:number, options?: ToggleGetOptions }	Called before the number toggle is fetched.
afterGetNumber	{ key: string, defaultValue:number, options?: ToggleGetOptions, result: number }	Called after the number toggle is fetched.
beforeGetString	{ key: string, defaultValue:string, options?: ToggleGetOptions }	Called before the string toggle is fetched.
afterGetString	{ key: string, defaultValue:string, options?: ToggleGetOptions, result: string }	Called after the string toggle is fetched.
beforeGetObject	{ key: string, defaultValue:any, options?: ToggleGetOptions }	Called before the object toggle is fetched.
afterGetObject	{ key: string, defaultValue:any, options?: ToggleGetOptions, result: any }	Called after the object toggle is fetched.

You can use the hooks to modify the request or the response. For example, you can use the beforeGetBoolean hook to log the request before it is sent to the server.

import { Toggle, ToggleHooks, ToggleContext } from '@hyphen/sdk';

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

const toggleOptions = {
  publicApiKey: 'your_public_api_key',
  applicationId: 'your_application_id',
  context: context,
};

const toggle = new Toggle(toggleOptions);

toggle.onHook(ToggleHooks.beforeGetBoolean, (data) => {
  console.log('Before get boolean toggle:', data); // { key: 'hyphen-sdk-boolean', defaultValue: false }
});

const result = await toggle.getBoolean('hyphen-sdk-boolean', false);

console.log('Boolean toggle value:', result); // true

Toggle Error Handling

The SDK provides a way to handle errors that occur during the toggle request. You can use the .on method to handle errors globally.

import { Toggle, ToggleContext } from '@hyphen/sdk';

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

const toggleOptions = {
  publicApiKey: 'your_public_api_key',
  applicationId: 'your_application_id',
  context: context,
};

const toggle = new Toggle(toggleOptions);
toggle.on('error', (error) => {
  console.error('Error fetching toggle:', error);
});

const result = await toggle.getBoolean('hyphen-sdk-boolean', false);
console.log('Boolean toggle value:', result); // true

If you would like to have the errors thrown you can use the throwErrors option in the constructor:

import { Toggle, ToggleContext } from '@hyphen/sdk';

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

const toggleOptions = {
  publicApiKey: 'your_public_api_key',
  applicationId: 'your_application_id',
  context: context,
  throwErrors: true,
};

const toggle = new Toggle(toggleOptions);

try {
  const result = await toggle.getBoolean('hyphen-sdk-boolean', false);
  console.log('Boolean toggle value:', result); // true
} catch (error) {
  console.error('Error fetching toggle:', error);
}

Toggle Caching

The SDK supports caching of toggle values to improve performance and reduce the number of requests made to the server. You can enable caching by providing a caching option in the constructor.

import { Toggle, ToggleContext } from '@hyphen/sdk';

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

const toggleOptions = {
  publicApiKey: 'your_public_api_key',
  applicationId: 'your_application_id',
  context: context,
  uris: [
	'https://your-self-hosted-horizon-url',
  ],
  caching: {
	ttl: 60, // Cache for 60 seconds
};

const toggle = new Toggle(toggleOptions);

const result = await toggle.getBoolean('hyphen-sdk-boolean', false);
console.log('Boolean toggle value:', result); // true

If you want to use a custom cache key generation function, you can provide a generateCacheKeyFn function in the caching option:

import { Toggle, ToggleContext } from '@hyphen/sdk';

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

const toggleOptions = {
  publicApiKey: 'your_public_api_key',
  applicationId: 'your_application_id',
  context: context,
  uris: [
	'https://your-self-hosted-horizon-url',
  ],
  caching: {
	ttl: 60, // Cache for 60 seconds
	generateCacheKeyFn: (context) => {
		return `toggle-${context?.targetingKey || 'default'}-hyphen-sdk-boolean`;
	},
  },
};

const toggle = new Toggle(toggleOptions);

const result = await toggle.getBoolean('hyphen-sdk-boolean', false);
console.log('Boolean toggle value:', result); // true

Toggle Environment Variables

You can also use environment variables to set the publicApiKey and applicationId. This is useful for keeping your API keys secure and not hardcoding them in your code. To do this just set your .env file with the following variables:

HYPHEN_PUBLIC_API_KEY=your_public_api_key
HYPHEN_APPLICATION_ID=your_application_id

On initialization of the Toggle class, the SDK will automatically check for these environment variables and use them if they are set. If they are not set, you will need to provide them in the constructor.

Toggle Self-Hosted

Toggle uses Horizon to fetch the feature flags. If you are using a self-hosted version of Hyphen you can use the uris option in the constructor to set the url of your self-hosted version:

import { Toggle, ToggleContext } from '@hyphen/sdk';

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

const toggleOptions = {
  publicApiKey: 'your_public_api_key',
  applicationId: 'your_application_id',
  context: context,
  uris: [
	'https://your-self-hosted-horizon-url',
  ],
};

const toggle = new Toggle(toggleOptions);

const result = await toggle.getBoolean('hyphen-sdk-boolean', false);
console.log('Boolean toggle value:', result); // true

If you want to use your self-hosted version of Horizon as a primary and fallback to our hosted version you can do it like this:

import { Toggle, ToggleContext } from '@hyphen/sdk';

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

const toggleOptions = {
  publicApiKey: 'your_public_api_key',
  applicationId: 'your_application_id',
  context: context,
  uris: [
	'https://your-self-hosted-horizon-url',
	'https://toggle.hyphen.cloud',
  ],
};

const toggle = new Toggle(toggleOptions);

const result = await toggle.getBoolean('hyphen-sdk-boolean', false);
console.log('Boolean toggle value:', result); // true

ENV

Hyphens secret management service known as ENV allows you to manage your environment variables in a secure way. The Hyphen Node.js SDK provides a simple way to access your environment variables.

Loading Environment Variables

To load your environment variables, you can use the loadEnv function from the SDK. This function will automatically load your environment variables from the .env file and then override them with the environment based environment file if it exists (ex: .env.development). This is useful for managing different environments such as development, staging, and production.

The following override path is:

.env -> .env.local -> .env.<environment> -> .env.<environment>.local

Here is an example of how to use the loadEnv function:

import { loadEnv } from '@hyphen/sdk';

//load your default environment variables and envrionment variables
loadEnv();

If your environment variables are not stored in the root of your project you can specify the path to your .env file:

import { loadEnv } from '@hyphen/sdk';
//load your default environment variables and envrionment variables
loadEnv({ path: '/path/to/your/env/files/' });

You can also specify the environment variables to load by passing an array of variable names:

import { loadEnv } from '@hyphen/sdk';
//load your default environment variables and envrionment variables
loadEnv({ environment: 'development' });

if you want to turn off the local environment variables you can do it like this:

import { loadEnv } from '@hyphen/sdk';
//load your default environment variables and envrionment variables
loadEnv({ local: false });

Net Info (https://net.info)

The Hyphen Node.js SDK also provides a NetInfo class that allows you to fetch geo information about an IP address. This can be useful for debugging or logging purposes. You can read more about it:

• Website
• Quick Start Guide

To use the NetInfo class, you can do the following:

import { NetInfo } from '@hyphen/sdk';
const netInfo = new NetInfo({
  apiKey: 'your_api_key',
});

const ipInfo = await netInfo.getIpInfo('8.8.8.8');
console.log('IP Info:', ipInfo);

You can also set the API key using the HYPHEN_API_KEY environment variable. This is useful for keeping your API key secure and not hardcoding it in your code.

Contributing

We welcome contributions to the Hyphen Node.js SDK! If you have an idea for a new feature, bug fix, or improvement, please follow these steps:

1. Fork the repository.

2. Create a new branch for your feature or bug fix.

3. Install pnpm by running npm install -g pnpm if you don't have it already.

4. Run the installation and tests to ensure everything is working correctly pnpm i && pnpm test.

5. Make your changes and commit them with a clear message. In the following format:

   • feat: <describe the feature>
   • fix: <describe the bug fix>
   • chore: updgrading xxx to version x.x.x

6. Push your changes to your forked repository.

7. Create a pull request to the main repository.

8. Describe your changes and why they are necessary.

Testing Your Changes

To test your changes locally you will need to create an account on Hyphen and do the following:

1. Create a new project in the Hyphen dashboard. This will give you a project ID and an Public API key.
2. On the project please add the following toggles:

Name	Type	Value
hyphen-sdk-boolean	boolean	true
hyphen-sdk-number	number	42
hyphen-sdk-string	string	"Hyphen!"
hyphen-sdk-json	json	{ "id": "Hello World!"}

Then, create a new application in the project. This will give you an application ID.

Once you have created the project, added the toggles, and created your application you can run the tests then create an .env file in the root of the project with the following content:

HYPHEN_PUBLIC_API_KEY=your_public_api_key
HYPHEN_API_KEY=your_api_key
HYPHEN_APPLICATION_ID=your_project_id

The HYPHEN_PUBLIC_API_KEY is the public API key for your Hyphen project, HYPHEN_API_KEY is the API key used for things such as NetInfo and is located under settings in the dashboard, and HYPHEN_APPLICATION_ID is the application ID for your Hyphen project.

Then run the tests with the following command:

pnpm i && pnpm test

License and Copyright

This project is licensed under the MIT License. See the LICENSE file for details. The copyright for this project is held by Hyphen, Inc. All rights reserved.