Skip to content

Commit

Permalink
Update readme with Unleash description, fix minor typos (#707)
Browse files Browse the repository at this point in the history
  • Loading branch information
@melindafekete
melindafekete authored Feb 5, 2025
1 parent 8fd088e commit 6eaff7e
Showing 1 changed file with 35 additions and 33 deletions.
68 changes: 35 additions & 33 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,14 @@

[![Unleash node SDK on npm](https://img.shields.io/npm/v/unleash-client)](https://www.npmjs.com/package/unleash-client)
![npm downloads](https://img.shields.io/npm/dm/unleash-client)
[![Build Status](https://github.com/Unleash/unleash-client-node/workflows/Build/badge.svg)](https://github.com/Unleash/unleash-client-node/actions)
[![Build Status](https://github.com/Unleash/unleash-client-node/actions/workflows/build-and-test.yaml/badge.svg)](https://github.com/Unleash/unleash-client-node/actions)
[![Code Climate](https://codeclimate.com/github/Unleash/unleash-client-node/badges/gpa.svg)](https://codeclimate.com/github/Unleash/unleash-client-node)
[![Coverage Status](https://coveralls.io/repos/github/Unleash/unleash-client-node/badge.svg?branch=main)](https://coveralls.io/github/Unleash/unleash-client-node?branch=main)

The official Unleash client SDK for Node.js.
Unleash is a private, secure, and scalable [feature management platform](https://www.getunleash.io/) built to reduce the risk of releasing new features and accelerate software development. This server-side Node.js SDK is designed to help you integrate with Unleash and evaluate feature flags inside your application.

You can use this client with [Unleash Enterprise](https://www.getunleash.io/pricing?utm_source=readme&utm_medium=nodejs) or [Unleash Open Source](https://github.com/Unleash/unleash).


## Getting started

Expand All @@ -31,7 +34,7 @@ is asynchronous, but if you need it to be synchronous, you can
[block until the SDK has synchronized with the server](#synchronous-initialization).

Note that until the SDK has synchronized with the API, all features will evaluate to `false` unless
you a [bootstrapped configuration](#bootstrap).
you have a [bootstrapped configuration](#bootstrap).

---

Expand Down Expand Up @@ -118,7 +121,7 @@ const unleash = await startUnleash({
customHeaders: { Authorization: '<YOUR_API_TOKEN>' },
});

// Unleash SDK has now fresh state from the unleash-api
// The Unleash SDK now has a fresh state from the Unleash API
const isEnabled = unleash.isEnabled('Demo');
```

Expand All @@ -142,8 +145,8 @@ setInterval(() => {
```

👀 **Note**: In this example, we've wrapped the `isEnabled` call inside a `setInterval` function. In
the event that all your app does is to start the SDK and check a feature status, this is will keep a
node app running until the SDK has synchronized with the Unleash API. It is **not** required in
the event that all your app does is start the SDK and check a feature status, this setup ensures that the
node app keeps running until the SDK has synchronized with the Unleash API. It is **not** required in
normal apps.

#### Check variants
Expand Down Expand Up @@ -187,17 +190,17 @@ const enabled = unleash.isEnabled('someToggle', unleashContext);

### 4. Stop unleash

To shut down the client (turn off the polling) you can simply call the destroy-method. This is
To shut down the client (turn off the polling) you can simply call the `destroy` method. This is
typically not required.

```js
import { destroy } from 'unleash-client';
destroy();
```

### Built in activation strategies
### Built-in activation strategies

The client comes supports all built-in activation strategies provided by Unleash.
The client supports all built-in activation strategies provided by Unleash.

Read more about
[activation strategies in the official docs](https://docs.getunleash.io/reference/activation-strategies).
Expand Down Expand Up @@ -233,20 +236,19 @@ The initialize method takes the following arguments:
- **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
- **customHeadersFunction** - Provide a function that returns 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.
- **httpOptions** - Provide custom http options such as `rejectUnauthorized` - be careful with these
- **httpOptions** - Provide custom HTTP options such as `rejectUnauthorized` - be careful with these
options as they may compromise your application security.
- **namePrefix** - Only fetch feature toggles with the provided name prefix.
- **tags** - Only fetch feature toggles tagged with the list of tags. E.g.:
`[{type: 'simple', value: 'proxy'}]`.
- **tags** - Only fetch feature toggles tagged with the list of tags, such as: `[{type: 'simple', value: 'proxy'}]`.

## Custom strategies

### 1. implement the custom strategy:
### 1. Implement the custom strategy

```js
import { initialize, Strategy } from 'unleash-client';
Expand All @@ -261,7 +263,7 @@ class ActiveForUserWithEmailStrategy extends Strategy {
}
```

### 2. register your custom strategy:
### 2. Register your custom strategy

```js
initialize({
Expand All @@ -281,13 +283,13 @@ The unleash instance object implements the EventEmitter class and **emits** the
| ------------ | -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ready | - | is emitted once the fs-cache is ready. if no cache file exists it will still be emitted. The client is ready to use, but might not have synchronized with the Unleash API yet. This means the SDK still can operate on stale configurations. |
| synchronized | - | is emitted when the SDK has successfully synchronized with the Unleash API, or when it has been bootstrapped, and has all the latest feature toggle configuration available. |
| registered | - | is emitted after the app has been registered at the api server |
| registered | - | is emitted after the app has been registered at the API server |
| sent | `object` data | key/value pair of delivered metrics |
| count | `string` name, `boolean` enabled | is emitted when a feature is evaluated |
| warn | `string` msg | is emitted on a warning |
| error | `Error` err | is emitted on a error |
| error | `Error` err | is emitted on an error |
| unchanged | - | is emitted each time the client gets new toggle state from server, but nothing has changed |
| changed | `object` data | is emitted each time the client gets new toggle state from server and changes has been made |
| changed | `object` data | is emitted each time the client gets new toggle state from server and changes have been made |
| impression | `object` data | is emitted for every user impression (isEnabled / getVariant) |

Example usage:
Expand All @@ -310,8 +312,8 @@ unleash.on('error', console.error);
unleash.on('warn', console.warn);

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

unleash.once('changed', () => {
Expand All @@ -323,15 +325,15 @@ unleash.on('count', (name, enabled) => console.log(`isEnabled(${name})`));

## Bootstrap

(Available from v3.11.x)
> Available from v3.11.x
The Node.js SDK supports a bootstrap parameter, allowing you to load the initial feature toggle
configuration from somewhere else than the Unleash API. The bootstrap `data` can be provided as an
argument directly to the SDK, as a `filePath` to load or as a `url` to fetch the content from.
argument directly to the SDK, as a `filePath` to load, or as a `url` to fetch the content from.
Bootstrap is a convenient way to increase resilience, where the SDK can still load fresh toggle
configuration from the bootstrap location, even if the Unleash API should be unavailable at startup.

**1. Bootstrap with data passed as an argument**
### 1. Bootstrap with data passed as an argument

```js
const client = initialize({
Expand All @@ -355,7 +357,7 @@ const client = initialize({
});
```

**2. Bootstrap via a URL**
### 2. Bootstrap via a URL

```js
const client = initialize({
Expand All @@ -371,7 +373,7 @@ const client = initialize({
});
```

**3. Bootstrap from a File**
### 3. Bootstrap from a file

```js
const client = initialize({
Expand Down Expand Up @@ -406,16 +408,16 @@ const featureToggleX = getFeatureToggleDefinition('app.ToggleX');
const featureToggles = getFeatureToggleDefinitions();
```

## Custom Store Provider
## Custom store provider

(Available from v3.11.x)

By default this SDK will use a store provider that writes a backup of the feature toggle
By default, this SDK will use a store provider that writes a backup of the feature toggle
configuration to a **file on disk**. This happens every time it receives updated configuration from
the Unleash API. You can swap out the store provider with either the provided in-memory store
provider or a custom store provider implemented by you.

**1. Use InMemStorageProvider**
### 1. Use `InMemStorageProvider`

```js
import { initialize, InMemStorageProvider } from 'unleash-client';
Expand All @@ -428,7 +430,7 @@ const client = initialize({
});
```

**2. Custom Store Provider backed by redis**
### 2. Custom store provider backed by Redis

```js
import { initialize, InMemStorageProvider } from 'unleash-client';
Expand Down Expand Up @@ -461,17 +463,17 @@ const client = initialize({

## 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
You can manage the underlying data layer yourself if you want to. This enables you to use Unleash
offline, from a browser environment, or by implement your own caching layer. See
[example](examples/custom_repository.js).

Unleash depends on a `ready` event of the repository you pass in. Be sure that you emit the event
**after** you've initialized unleash.
**after** you've initialized Unleash.

## Usage with HTTP and HTTPS proxies

You can connect to the Unleash API through the corporate proxy by setting one of the environment
variables: `HTTP_PROXY` or `HTTPS_PROXY`
variables: `HTTP_PROXY` or `HTTPS_PROXY`.

## Design philosophy

Expand Down

0 comments on commit 6eaff7e

Please sign in to comment.