# n-flags-client

<a href="https://docs.google.com/forms/d/e/1FAIpQLSf5InA7UJK9yNBCzidFKI_WNkfbl6of1eRlIACRspGXUcBx8A/viewform?usp=pp_url&entry.78759464=n-flags-client" target="_blank"><img src="https://i.imgur.com/UmScdZ4.png" alt="Yak button" border="0" align="right" width="150" title="Report a yak shaving incident for this repository"></a>

Provides a mechanism for us to toggle features and services, inspired by [Martin Fowler’s feature toggles](http://martinfowler.com/bliki/FeatureToggle.html). Flags can be overridden using an `x-flags` header or `next-flags` cookie. Also sends reports to Sentry of any expired flags still in use.

## Usage

### Client side

Flags are exposed via [flags.html](https://github.com/Financial-Times/n-flags-client/blob/HEAD/templates/flags.html), which are [consumed by n-ui](https://github.com/Financial-Times/n-ui/blob/HEAD/browser/layout/partials/bootstrapper.html#L4).

### Server side

Any apps using [n-express](https://github.com/Financial-Times/n-express) with the `withFlags` option turned on will get flags added to `res.locals.flags`, via the [middleware it consumes in this repo](https://github.com/Financial-Times/n-flags-client/blob/HEAD/server/middleware.js). By default it will request from FT.com’s set of platinum flag services, but can be overridden using the `setUrls([arr])` method.

The default behaviour when `NODE_ENV=production` is set is to get overrides from the HTTP header that Fastly sets. For apps that are not routed via Fastly, you can set `OVERRIDE_FLAGS_FROM_COOKIE=true` to get overrides from a cookie.

## API

### `init(options)`

Initialises the flag client. Options:

- `timeout`: A length of time (ms) to wait for response from the flag server [default 3000]
- `interval`: An interval (ms) between attempts to fetch fresh flag data [default 30000]
- `retry`: The number of times to retry if a fetch fails [default 1]
- `filter`: a function, returning true or false, that is passed the raw data object fora flag and is used to decide whether or not it should be discarded from the flag set for the current app

Returns a promise that is resolved when flags have been successfully fetched at least once (or that resolves immediately if none of the above options are passed).

### `getArray()`

Returns a simplified array of flags similar to that retrieved from the [flags API](https://github.com/Financial-Times/next-flags-api), but lacking expiry date information.

### `get(name)`

Returns the current state of a flag (or false if the flag doesn’t exist). If no name is provided, it returns a hash of all current flag objects, including information on expiry dates.

### `getModel(name)`

Returns a flag model for the named flag.