Unleash Client SDK for Node.js

Unleash Client SDK for Node.js. It is compatible with the Unleash-hosted.com SaaS offering and Unleash Open-Source.

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 unleashContext = {
    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 (required)
• instanceId - an unique identifier, should/could be somewhat unique
• refreshInterval - The poll-intervall to check for updates. Defaults to 15000ms.
• metricsInterval - How often the client should send metrics to Unleash API. Defaults to 60000ms.
• 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
• customHeadersFunction - Provide a function that return a Promise resolving as custom headers to be sent to unleash-server. When options are set, this will take precedence over customHeaders option.
• 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:

Example usage:

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

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

instance.once('registered', () => {
    // Do something after the client has registered with the server api.
    // NB! It might not have recieved updated feature toggles yet.
});

instance.once('changed', () => {
    console.log(`Demo is enabled: ${isEnabled('Demo')}`);
});

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.