Dipswitch NPM | npm.io

`dipswitch`

Dipswitch is a multi-tenant feature toggle library.

Installation (via npm)

$ npm install dipswitch --save

If you wish to use redis to store this data, also install dipswitch-redis. Otherwise, an in-memory store will be used.

Usage

The Basics

var Dipswitch = require('dipswitch'),
  dipswitch = new Dipswitch({
    redis: require('redis').createClient(),

    getTenantId: function (tenant) { // default is `return tenant.id;`
      return tenant.tenantId;
    },

    getUserId: function (user) { // default is `return user.id;`
      return user.userId;
    },

    getUserGroups: function (user) { // default is `return user.groups || [];`
      if (user.isAdmin) {
        return ['admins'];
      }
      return [];
    }
  });

// ADDING & REMOVING FEATURES --------------------------------------------------

// add & remove a feature
dipswitch.features.add('EXAMPLE_FEATURE').then(function () { /* ... */ });
dipswitch.features.remove('EXAMPLE_FEATURE').then(function () { /* ... */ });

// and another syntax for registering many features at once
dipswitch.features.add(['FEATURE_1', 'FEATURE_2']).then(function () { /* ... */ });

// and unregister many features at once as well
dipswitch.features.remove(['EXAMPLE_FEATURE1', 'EXAMPLE_FEATURE2']).then(function () { /* ... */ });

// retrieve all registered features
dipswitch.features.find().then(function (features) {
  /* ... */
});

// ENABLING FEATURES -----------------------------------------------------------

// enable a feature globally
dipswitch.features.enable('EXAMPLE_FEATURE').then(function () { /* ... */ });

// enable a feature for an entire tenant
dipswitch.tenant(tenant).enable('EXAMPLE_FEATURE').then(function () { /* ... */ });

// enable a feature for a group within a tenant
dipswitch.tenant(tenant).group('admins').enable('EXAMPLE_FEATURE').then(function () { /* ... */ });

// enable a feature a group across all tenants
dipswitch.group('admins').enable('EXAMPLE_FEATURE').then(function () { /* ... */ });

// enable a feature for a user within a tenant
dipswitch.tenant(tenant).user(user).enable('EXAMPLE_FEATURE').then(function () { /* ... */ });

// enable a feature for a user across all tenants
dipswitch.user(user).enable('EXAMPLE_FEATURE').then(function () { /* ... */ });

// SCHEDULING FEATURES ---------------------------------------------------------

// when enabling a feature you may optionally pass a `start` and/or `end` date
dipswitch.features.enable('LOL_OMG_CATFACTS', {
  start: new Date(2015, 3, 1), // April 1st
  end: new Date(2015, 3, 2) // April 2nd
}).then(function () { /* ... */ });

// CHECKING FEATURES -----------------------------------------------------------

// retrieve all features and whether they're enabled or not for a user
dipswitch.tenant(tenant).user(user).features().then(function (features) {
  console.log(features.EXAMPLE_FEATURE); // `true`
});

// check a single feature and whether it is enabled or not for a user
dipswitch.tenant(tenant).user(user).feature('EXAMPLE_FEATURE').then(function (isEnabled) {
  console.log(isEnabled); // `true`
});

// DISABLING FEATURES ----------------------------------------------------------

// anywhere that you can call #enable, you can also call #disable
dipswitch.tenant(tenant).user(user).disable('EXAMPLE_FEATURE').then(function () { /* ... */ });

Unregistering Out-of-Date Features

Rather than having to have an admin UI for unregistering features you no longer care about, you can use a bit of underscore/lodash magic to automate the process:

var _ = require('underscore'),
  Dipswitch = require('dipswitch'),
  dipswitch = new Dipswitch(options);

// note that FEATURE_2 was removed at some point
var desiredFeatures = ['FEATURE_1', 'FEATURE_3'];

dipswitch.register(desiredFeatures)
  .then(function () {
    return dipswitch.features(); // lets say this returns ['FEATURE_1', 'FEATURE_2', 'FEATURE_3']
  })
  .then(function (registeredFeatures) {
    var outOfDateFeatures = _.without(registeredFeatures, desiredFeatures);
    return dipswitch.unregister(outOfDateFeatures); // will remove ['FEATURE_2']
  });

Interacting With Unregistered Features

When enabling or disabling a feature that has never been registered, that feature is automatically registered. When testing to see the value of a feature that isn't registered, the result will be false.