unleash-client

What is unleash-client?

The unleash-client npm package is a feature toggle system that allows you to control the release of features in your application. It helps you manage feature flags, enabling or disabling features without deploying new code.

What are unleash-client's main functionalities?

Initialize Unleash Client

This code initializes the Unleash client with the necessary configuration, including the URL of the Unleash server, the application name, and the instance ID.

const { UnleashClient } = require('unleash-client');

const unleash = new UnleashClient({
  url: 'http://unleash.herokuapp.com/api/',
  appName: 'my-app',
  instanceId: 'my-instance-id',
});
unleash.start();

Check if a feature is enabled

This code checks if a specific feature toggle (in this case, 'someFeature') is enabled and logs the result.

const isEnabled = unleash.isEnabled('someFeature');
console.log(`Feature is enabled: ${isEnabled}`);

Register custom strategies

This code demonstrates how to register a custom strategy with the Unleash client. Custom strategies allow you to define your own logic for enabling or disabling features.

unleash.on('ready', () => {
  unleash.registerStrategy(new CustomStrategy());
});

class CustomStrategy {
  constructor() {
    this.name = 'custom';
  }

  isEnabled(parameters, context) {
    // Custom logic to determine if the feature is enabled
    return true;
  }
}

Other packages similar to unleash-client

launchdarkly-node-client-sdk

LaunchDarkly is a feature management platform that provides feature flags as a service. It offers more advanced targeting and segmentation capabilities compared to Unleash, but it is a paid service.

flagr

Flagr is an open-source feature flagging and A/B testing service. It provides a web UI for managing flags and supports various targeting rules. It is similar to Unleash in terms of being open-source but offers a different set of features and a different user interface.

fflip

fflip is a lightweight feature flagging library for Node.js. It is simpler and more lightweight compared to Unleash, making it suitable for smaller projects or those with simpler feature flagging needs.

README

unleash-client-node

This is the node client for Unleash. Read more about the Unleash project

Version 3.x of the client requires unleash-server >= v3.x

Getting started

1. Install the unleash-client into your project

$ npm install unleash-client --save

2. Initialize unleash-client

You should as early as possible in your node (web) app initialize the unleash-client. The unleash-client will set-up a in-memory repository, and poll updates from the unleash-server at regular intervals.

const { initialize } = require('unleash-client');
const instance = initialize({
    url: 'http://unleash.herokuapp.com/api/',
    appName: 'my-app-name',
    instanceId: 'my-unique-instance-id',
});

// optional events
instance.on('error', console.error);
instance.on('warn', console.warn);
instance.on('ready', console.log);

// metrics hooks
instance.on('registered', clientData => console.log('registered', clientData));
instance.on('sent', payload => console.log('metrics bucket/payload sent', payload));
instance.on('count', (name, enabled) => console.log(`isEnabled(${name}) returned ${enabled}`));

3. Use unleash

After you have initialized the unleash-client you can easily check if a feature toggle is enabled or not.

const {
    isEnabled,
    getVariant,
    getFeatureToggleDefinition,
    getFeatureToggleDefinitions,
} = require('unleash-client');

isEnabled('app.ToggleX');

const { enabled, name, payload } = getVariant('app.ToggleY', { userId: '1234' });

const featureToogleX = getFeatureToggleDefinition('app.ToggleX');
const featureToggles = getFeatureToggleDefinitions();

4. Stop unleash

To shut down the client (turn off the polling) you can simply call the destroy-method. This is typically not required.

const { destroy } = require('unleash-client');
destroy();

Built in activation strategies

The client comes with implementations for the built-in activation strategies provided by unleash.

• DefaultStrategy
• UserIdStrategy
• GradualRolloutUserIdStrategy
• GradualRolloutSessionIdStrategy
• GradualRolloutRandomStrategy
• RemoteAddressStrategy
• ApplicationHostnameStrategy

Read more about the strategies in activation-strategy.md.

Unleash context

In order to use some of the common activation strategies you must provide a unleash-context. This client SDK allows you to send in the unleash context as part of the isEnabled call:

const context = {
    userId: '123',
    sessionId: 'some-session-id',
    remoteAddress: '127.0.0.1',
};
unleash.isEnabled('someToggle', unleashContext);

Advanced usage

The initialize method takes the following arguments:

• url - the url to fetch toggles from. (required)
• appName - the application name / codebase name
• instanceId - an unique identifier, should/could be somewhat unique
• refreshInterval - The poll-intervall to check for updates. Defaults to 15s.
• metricsInterval - How often the client should send metrics to Unleash API
• strategies - Custom activation strategies to be used.
• disableMetrics - disable metrics
• customHeaders - Provide a map(object) of custom headers to be sent to the unleash-server
• timeout - specify a timeout in milliseconds for outgoing HTTP requests. Defaults to 10000ms.
• repository - Provide a custom repository implementation to manage the underlying data

Custom strategies

1. implement the custom strategy:

const { Strategy, initialize } = require('unleash-client');
class ActiveForUserWithEmailStrategy extends Strategy {
    constructor() {
        super('ActiveForUserWithEmail');
    }

    isEnabled(parameters, context) {
        return parameters.emails.indexOf(context.email) !== -1;
    }
}

2. register your custom strategy:

initialize({
    url: 'http://unleash.herokuapp.com',
    strategies: [new ActiveForUserWithEmailStrategy()],
});

Alternative usage

Its also possible to ship the unleash instance around yourself, instead of using on the default require.cache to have share one instance.

const { Unleash } = require('unleash-client');

const instance = new Unleash({
    appName: 'my-app-name',
    url: 'http://unleash.herokuapp.com',
});

instance.on('ready', console.log.bind(console, 'ready'));
// required error handling when using instance directly
instance.on('error', console.error);

Events

The unleash instance object implements the EventEmitter class and emits the following events:

event	payload	description
ready	-	is emitted once the fs-cache is ready. if no cache file exists it will still be emitted.
registered	-	is emitted after the app has been registered at the api server
sent	object data	key/value pair of delivered metrics
count	string name, boolean enabled	is emitted when a feature is evaluated
warn	string msg	is emitted on a warning
error	Error err	is emitted on a error

Example usage:

const { Unleash, isEnabled } = require('unleash-client');

const instance = new Unleash({
    appName: 'my-app-name',
    url: 'http://unleash.herokuapp.com',
});

await instance.once('ready');
// do something

Custom repository

You can manage the underlying data layer yourself if you want to. This enables you to use unleash offline, from a browser environment or implement your own caching layer. See example.

Unleash depends on a ready event of the repository you pass in. Be sure that you emit the event after you've initialized unleash.

Changelog

3.2.5

• feature: Allow user to implement custom toggle repository
• feat: Drop node 6 support (EOL)
• feat: Get all feature toggle definitions at once
• fix: Update lint-staged to the latest version 8.1.7
• fix: Update nock to version 10.0.6
• fix: Update @types/node to version 12.0.2
• fix: Update husky to version 2.3.0
• fix: Update ava to version 1.4.1
• fix: Update eslint to version 5.16.0
• fix: Update nyc to version 14.1.1