sheldon

Fun with (feature) flags!

Usage no npm install needed!

<script type="module">
  import sheldon from 'https://cdn.skypack.dev/sheldon';
</script>

README

Sheldon

Bringing the fun and power of flags to your application

Overview

Sheldon is a feature flag client wrapped around a Redis database. It is designed to handle multiple services and environments for a microservice architecture, while being fairly agnostic about what type of flag you want to keep.

Installation

npm install sheldon --save

Use

const Sheldon = require('sheldon');
const sheldonOptions = {
  redisConnectionString: 'redis://:PASSYWORDY@redis.redis.com:10101',
  appName: 'my-amazing-app-live',
  defaults: {
     'partyTime': 'on'
  }
};

const feature = new Sheldon(sheldonOptions);
feature.readAndStartWatching();

if (feature.flag('partyTime') === 'on') {
  console.log('start the party!');
} else {
  console.log('no party yet');
}

Options

new Sheldon() takes an options object with the following fields:

  • redisConnectionString[required]: the connection string to the Redis database. This can also be a path to a json file for local dev, see below.
  • appName[required]: the unique identifier for the application. I.e. my-app-ci, or great-service-qa
  • pollInterval[optional]: the poll interval for Sheldon to poll the Redis database. Defaults to 15 seconds.
  • defaults[required]: Used when application starts (or restarted) and redis can't be reached. Note that if you dont define all your flags the flag function will return an error for unrecognised flags.
  • logger[required]: Used for logging instead of the console.log (./specs/helpers.js)[see the methods required for logger]
  • statsd[required]: Used to capture metrics around the redis connection for now

API

readAndStartWatching() Reads the current flag states stored in the Redis database for the given appName and starts polling at the pollInterval interval.

flag(String) => String Takes a flag name (a String) and returns its value (also a String - JavaScript, eh?)

Recommended uses

We'd recommend flagging on a match to a string, as in flag === 'on' and having the "safe" setting being the inverse (to guard against typos).

Adding, Updating and Deleting flags

Writing to underlying the Redis database is not handled by Sheldon. Sheldon reads a hash stored at the key of appName, and reads in the fields and values as the flags and settings respectively. To update, add and delete flags we'd recommend using the Redis command line tool (redis-cli), using HSET and HGET to set and get the value of individual flags, and HDEL to delete them.

Local JSON file for dev

If the redisConnectionString is specified as a file url, e.g. file://./sheldon-override.json then it will read flags from that json file instead. If json document should be formatted as an object with a key for the name of the application. That key should point to an object that contains the flags.

E.g. if the application name is 'my-test-app' and you want to set the flag 'cool-stuff' to 'on' and 'old-stuff' to 'off':

{
  "my-test-app": {
    "cool-stuff": "on",
    "old-stuff": "off"
  }
}

Contributing

Feel free to open a pull request.