npm package: @nuskin/ns-feature-flags
Description: This library is used to load the feature flags and check if they are enabled
Author: Kelvin Lau
Latest version: 1.5.0

# ns-feature-flags

> A simple library to retrieve feature flags and check if they are enabled or not.  This project will be pushed to NPM repo at @nuskin/ns-feature-flags.

## Installation
```sh
npm install @nuskin/ns-feature-flags
```
For adding @nuskin/ns-feature-flags to the package.json:
```sh
npm install @nuskin/ns-feature-flags --save
```
Or
```sh
yarn add @nuskin/ns-feature-flags
```

## Usage
```javascript
// You can also use import as in ES6
const {retrieveToggles, isEnabled} = require('@nuskin/ns-feature-flags');

// Note that it will return a promise when you call retrieveToggles (You can use await or then)
await retrieveToggles(url);

// Once the retrieveToggles are done, you can call isEnabled
let isFeature1Enabled = isEnabled('feature1');
```

If you want to retrieve the toggles for a particular user, you can pass it an optional userId to retrieveToggles:
```javascript
// Note that 'qa' is the userId (an optional field)
await retrieveToggles(url, 'qa');
```

If you want to always retrieve the toggles for Production without providing the URL, you can do the following:
```javascript
// Note that 'qa' is the userId (an optional field)
await retrieveProductionToggles('qa');
```

## Retrieving Toggles Based on the Environment

---

If you want to retrive the toggles based on the current environment, there is a way to do that.

The **retrieveTogglesBasedOnEnvironment** takes up to 3 parameters **in an options object**, all of them optional:
- hostname - String (optional): The hostname of the current url. Examples: "dev.nuskin.com", "api.cloud.nuskin.com", "localhost". **Do NOT use in Node.**
- environment - String (optional): The environment name. Examples: "dev", "test", "stage", "prod". **Use for Node.**
- userId - String (optional): Feature toggles will be constrained to this user id.

If you don't provide either the hostname or environment option, the functional will look for "window.location.hostname" and use that.

The default environment toggles that this function will return is production.

**Node Example:**
```javascript
// The options object is optional.
const options = {
  environment: proccess.env.ENVIRONMENT
  userId: 'qa'
};

await retrieveTogglesBasedOnEnvironment(options);
```

**Non-Node Example:**
```javascript
// The options object is optional.
const options = {
  userId: 'qa'
};

await retrieveTogglesBasedOnEnvironment(options);
```

---

**Important**: Developer should NOT invoke retrieveToggles()/retrieveProductionToggles() repeatedly in an application because it will incur network cost by hitting the feature flags endpoint.  It is expected to call retrieveToggles()/retrieveProductionToggles() at the start, then call it again as needed (e.g., polling).  However, we have implemented a safe guard such that it will NOT initiate additional network call if retrieveToggles()/retrieveProductionToggles() is called repeatedly within five seconds.  Note that this does not prevent multiple network calls if more than one versions of ns-feature-flags are included.

## Session Storage User id

To toggle a feature flag in the browser using a user id, you can define a user id in the feature flag dashboard and toggle it setting a key value pair in session storage. 

### Example

To enable a feature flag that has a `userId` defined in the dashboard run the following command in your devtools console:

```js
sessionStorage.setItem('$featureFlagUserId',`{userId}`)
```

## Overriding Flag Values

To explicitly set a flag value, like in an integration test or local development, you can
set a value in the query string or in session storage.

Both the query string and session storage values use the same key names. To enable flags,
the key is `$enableFeatureFlags`; to disable them, it is `$disableFeatureFlags`. Both of
these values are a comma-separated list of the flags you want to enable or disable.

### Examples

To enable the flags 'foo' and 'bar' and disable the flag 'baz' in the query string,
add this to the URL: `?$enableFeatureFlags=foo,bar&$disableFeatureFlags=baz`.

To do the same in session storage, run the following command in your devtools console:

```js
sessionStorage.setItem('$enableFeatureFlags', 'foo,bar');
sessionStorage.setItem('$disableFeatureFlags', 'baz');
```