@featbit/js-client-sdk 2.0.1 → 3.0.0

package/README.md

@@ -1,8 +1,12 @@
-# FeatBit Client-Side SDK for JavaScript
+> **Attention**
+>
+> If you are using the v1 or v2 of the SDK, please refer to this [doc](https://github.com/featbit/featbit-js-client-sdk/tree/v2)
+
+# FeatBit Client SDK for JavaScript
 
 ## Introduction
 
-This is the client side SDK for the feature management platform [FeatBit](https://github.com/featbit/featbit). 
+This is the Client-Side SDK for the 100% open-source feature flags management platform [FeatBit](https://github.com/featbit/featbit).
 
 Be aware, this is a client side SDK, it is intended for use in a single-user context, which can be mobile, desktop or embedded applications. This SDK can only be ran in a browser environment, it is not suitable for NodeJs applications.
 
@@ -11,127 +15,137 @@ Be aware, this is a client side SDK, it is intended for use in a single-user con
 ### Installation
 
 ```bash
-npm install @featbit/js-client-sdk
+npm install --save @featbit/js-client-sdk
 ```
-
 ### Prerequisite
 
-Before using the SDK, you need to obtain the environment secret and SDK URLs. 
+Before using the SDK, you need to obtain the environment secret (the sdkKey) and SDK URLs.
 
 Follow the documentation below to retrieve these values
-
-- [How to get the environment secret](https://docs.featbit.co/sdk/faq#how-to-get-the-environment-secret)
-- [How to get the SDK URLs](https://docs.featbit.co/sdk/faq#how-to-get-the-sdk-urls)
+- [How to get environment secret](https://docs.featbit.co/sdk/faq#how-to-get-the-environment-secret)
+- [How to get SDK URLs](https://docs.featbit.co/sdk/faq#how-to-get-the-sdk-urls)
 
 ### Quick Start
 
-The following code demonstrates:
-1. Initialize the SDK
-2. Evaluate flag
-3. Subscribe to flag change
+The following code demonstrates the basic usage of `@featbit/js-client-sdk`.
 
 ```javascript
-import fbClient from '@featbit/js-client-sdk';
-
-const option = {
-  secret: "your env secret",
-  api:"http://localhost:5100", // the Streaming URL
-  user: {
-    name: "Bot",
-    keyId: "bot-id",
-    customizedProperties: [
-      {
-        "name": "level",
-        "value": "high"
-      }
-    ]
+import { FbClientBuilder, UserBuilder } from "@featbit/js-client-sdk";
+
+const bob = new UserBuilder('a-unique-key-of-user')
+    .name('bob')
+    .custom('age', '18')
+    .custom('country', 'FR')
+    .build();
+
+// setup SDK client with websocket streaming
+const fbClient = new FbClientBuilder()
+    .sdkKey("your_sdk_key")
+    .streamingUri('ws://localhost:5100')
+    .eventsUri("http://localhost:5100")
+    .user(bob)
+    .build();
+
+(async () => {
+  // wait for the SDK to be initialized
+  try {
+    await fbClient.waitForInitialization();
+  } catch(err) {
+    // failed to initialize the SDK
+    console.log(err);
   }
-};
 
-// initialization
-fbClient.init(option);
+  // flag to be evaluated
+  const flagKey = "game-runner";
 
-// evaluation
-const flagValue = fbClient.variation("YOUR_FEATURE_KEY", defaultValue);
+  // evaluate a feature flag for a given user
+  const boolVariation = await fbClient.boolVariation(flagKey, false);
 
-// subscribe to flag change
-fbClient.on('ff_update:YOUR_FEATURE_KEY', (change) => {
-  // change has this structure {id: 'the feature_flag_key', oldValue: theOldValue, newValue: theNewValue }
-  // the type of theOldValue and theNewValue is defined on FeatBit
-
-  // defaultValue should have the same type as theOldValue and theNewValue
-  const myFeature = fbClient.variation('YOUR_FEATURE_KEY', defaultValue);
-});
+  // switch user
+  const alice = new UserBuilder('another-unique-key-of-user')
+      .name('alice')
+      .custom('country', 'UK')
+      .custom('age', 36)
+      .build();
+  
+  await fbClient.identify(alice);
+})();
 ```
 
 ## Examples
-
-- [Vue](https://github.com/featbit/featbit-samples/tree/main/samples/dino-game/interactive-demo-vue)
+- [web App](./examples/console-app)
 - For how to use FeatBit with React, please refer to the [react-client-sdk](https://github.com/featbit/featbit-react-client-sdk)
 
 ## SDK
 
-### Initialization
+### FbClient
 
-Before initializing the SDK, you need to get the client-side env secret of your environment from FeatBit.
+The `FbClient` is the heart of the SDK which provides access to FeatBit server. Applications should instantiate a single instance for the lifetime of the application.
 
-```javascript
-const option = {
-  secret: "your env secret",
-  streamingUri:"ws://localhost:5100",
-  eventsUri:"http://localhost:5100",
-  user: {
-    name: "Bot",
-    keyId: "bot-id",
-    customizedProperties: [
-      {
-          "name": "level",
-          "value": "high"
-      }
-    ]
-  }
-};
+`FbClientBuilder` is used to construct a `FbClient` instance. The builder exposes methods to configure the SDK, and finally to create the `FbClient` instance.
+
+#### FbClient Using Streaming
 
-fbClient.init(option);
+```javascript
+import { FbClientBuilder, UserBuilder } from "@featbit/js-client-sdk";
+
+const user = new UserBuilder('a-unique-key-of-user')
+    .name('bob')
+    .build();
+    
+const fbClient = new FbClientBuilder()
+    .sdkKey("your_sdk_key")
+    .streamingUri('ws://localhost:5100')
+    .eventsUri("http://localhost:5100")
+    .user(user)
+    .build();
 ```
+#### FbClient Using Polling
 
-The user has three properties:
-- name(**requried**):  The user's name, useful when viewing users in the portal.
-- keyId(**requried**): The unique user identifier.
-- streamingUri: The streaming URL.
-- eventsUri: The events URL.
-- customizedProperties(**optional**): Any other customized properties. Users can be targeted by these customized properties. Here is the format definition:
-```json
- [
-   {
-     "name": "the name of the property",
-     "value": "the value of the property"
-   }
-]
+```javascript
+import { FbClientBuilder, UserBuilder, DataSyncMode } from "@featbit/browser-server-sdk";
+
+const user = new UserBuilder('a-unique-key-of-user')
+    .name('bob')
+    .build();
+
+const fbClient = new FbClientBuilder()
+    .sdkKey("your_sdk_key")
+    .dataSyncMode(DataSyncMode.POLLING)
+    .pollingUri('http://localhost:5100')
+    .eventsUri("http://localhost:5100")
+    .pollingInterval(10000)
+    .build();
 ```
 
-This table lists all available options
+#### IUser
+
+`IUser` defines the attributes of a user for whom you are evaluating feature flags. IUser has two built-in attributes: key and name. The only mandatory attribute of a IUser is the key, which must uniquely identify each user.
+
+Besides these built-in properties, you can define any additional attributes associated with the user using `custom(string key, string value)` method on UserBuilder. Both built-in attributes and custom attributes can be referenced in targeting rules, and are included in analytics data.
+
+`UserBuilder` is used to construct a `IUser` instance. The builder exposes methods to configure the IUser, and finally to create the IUser instance.
 
-| Options               | Defaults     | Description                                                                                                                                                                                              |
-|-----------------------|--------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| secret (**required**) | -            | The client side secret of your environment.                                                                                                                                                              |
-| user   (**required**) | -            | The user connected to your APP, can be ignored if anonymous equals to true.                                                                                                                              |
-| anonymous             | `false`      | Set to true if you want to use a anonymous user, which is the case before user login to your APP. If that is your case, the user can be set later with the identify method after the user has logged in. |
-| enableDataSync        | `true`       | Set to false if you do not want to sync data with remote server, in this case feature flags must be set to bootstrap option or be passed to the method bootstrap.                                        |
-| bootstrap             | `[ ]`        | Init the SDK with feature flags, this will trigger the ready event immediately instead of requesting from the remote.                                                                                    |
-| streamingUri          | ``           | The evaluation server streaming URL.                                                                                                                                                                     |
-| eventsUri             | ``           | The evaluation server events URL.                                                                                                                                                                        |
-| appType               | `javascript` | The app type.                                                                                                                                                                                            |
+```javascript
+import { UserBuilder } from "@featbit/js-client-sdk";
+
+const bob = new UserBuilder("unique_key_for_bob")
+    .name("Bob")
+    .custom('age', 18)
+    .custom('country', 'FR')
+    .build();
+```
 
 ### Bootstrap
-If you already have the feature flags available, two ways to pass them to the SDK instead of requesting from the remote.
-- By the **init** method
+If you already have the feature flags available, you can pass them to the SDK instead of requesting from the remote.
+
+
+> **_NOTE:_** The bootstrapped flags will be overridden by the remote flags if they are available.
 
 ```javascript
 // define the option with the bootstrap parameter
-const option = {
+const options = {
   ...
-  // the array should contain all your feature flags
   bootstrap = [{
     // feature flag key name
     id: string,
@@ -139,41 +153,57 @@ const option = {
     variation: string,
     // variation data type, string will be used if not specified
     variationType: VariationDataType
-  }],
-  ...
+  }]
 }
 
-fbClient.init(option);
+const fbClient = new FbClientBuilder(options).build();
+// or
+const fbClient = new FbClientBuilder()
+    //... other options
+    .bootstrap(options.bootstrap)
+    .build();
 ```
 
-- By the **bootstrap** method
+### Evaluation
+
+After initialization, the SDK has all the feature flags locally, and it does not need to request the remote server for any feature flag evaluation. All evaluation is done locally and synchronously, the average evaluation time is less than 1 ms.
+
+There is a `variation` method that returns a flag value, and a `variationDetail` method that returns an object
+describing how the value was determined for each type.
+
+- boolVariation/boolVariationDetail
+- stringVariation/stringVariationDetail
+- numberVariation/numberVariationDetail
+- jsonVariation/jsonVariationDetail
+
+Variation calls take the feature flag key and a default value. If any error makes it impossible to
+evaluate the flag (for instance, the feature flag key does not match any existing flag), default value is returned.
 
 ```javascript
-// this array should contain all your feature flags
-const featureflags = [{
-  // feature flag key name
-  id: string,
-  // variation value
-  variation: string,
-  // variation data type, string will used if not specified
-  variationType: VariationDataType
-}]
-
-fbClient.bootstrap(featureflags);
-```
+// flag to be evaluated
+const flagKey = "game-runner";
 
-**If you want to disable the synchronization with remote server, set enableDataSync to false in option**. In this case, bootstrap option must be set or bootstrap method must be called with feature flags.
+// evaluate a feature flag for a given user
+const boolVariation = await fbClient.boolVariation(flagKey, false);
 
-### Evaluation
+// evaluate a boolean flag for a given user with evaluation detail
+const boolVariationDetail = await fbClient.boolVariationDetail(flagKey, false);
+```
 
-After initialization, the SDK has all the feature flags locally, and it does not need to request the remote server for any feature flag evaluation. All evaluation is done locally and synchronously, the average evaluation time is about **1** ms.
+### Offline Mode
 
+In some situations, you might want to stop making remote calls to FeatBit. Here is how:
 ```javascript
-// Use this method for all cases
-// This method supports type inspection, it returns the value with the type defined on FeatBit,
-// so defaultValue should have the same type as defined on FeatBit
-const flagValue = fbClient.variation("YOUR_FEATURE_KEY", defaultValue);
+import { FbClientBuilder } from "@featbit/browser-server-sdk";
+
+const fbClient = new FbClientBuilder()
+    //... other options
+    .offline(true)
+    .build();
+
 ```
+When Offline mode is enabled, you should provide the flags with the [bootstrap](#bootstrap) option,
+otherwise, the SDK would return the defaul value you passed to the `variation` method.
 
 ### Events
 
@@ -184,27 +214,25 @@ To find out when the client is ready, you can use one of two mechanisms: events
 The client object can emit JavaScript events. It emits a ready event when it receives initial flag values from the server. You can listen for this event to determine when the client is ready to evaluate flags.
 
 ```javascript
-fbClient.on('ready', (data) => {
-  // data has the following structure [ {id: 'featureFlagKey', variation: variationValue} ]
-  // variationValue has the type as defined on remote
+fbClient.on('ready', () => {
   var flagValue = fbClient.variation("YOUR_FEATURE_KEY", defaultValue);
 });
 ```
 
-Or, you can use a promise instead of an event. The SDK has a method that return a promise for initialization: waitUntilReady(). The behavior of waitUntilReady() is equivalent to the ready event. The promise resolves when the client receives its initial flag data. As with all promises, you can either use .then() to provide a callback, or use await if you are writing asynchronous code.
+Or, you can use a promise instead of an event. The SDK has a method that returns a promise for initialization: **waitForInitialization()**. The behavior of waitUntilReady() is equivalent to the ready event. The promise resolves when the client receives its initial flag data. As with all promises, you can either use .then() to provide a callback, or use await if you are writing asynchronous code.
 
 ```javascript
-fbClient.waitUntilReady().then((data) => {
+fbClient.waitForInitialization().then((data) => {
   // data has the following structure [ {id: 'featureFlagKey', variation: variationValue } ]
   // variationValue has the type as defined on remote
   // initialization succeeded, flag values are now available
 });
 // or, with await:
-const featureFlags = await fbClient.waitUntilReady();
+const featureFlags = await fbClient.waitForInitialization();
 // initialization succeeded, flag values are now available
 ```
 
-The SDK only decides initialization has failed if it receives an error response indicating that the environment ID is invalid. If it has trouble connecting to feature-flags.co, it will keep retrying until it succeeds.
+The SDK only decides initialization has failed if it receives an error response indicating that the environment ID is invalid. If it has trouble connecting to FeatBit, it will keep retrying until it succeeds.
 
 #### Subscribe to flag(s) changes
 
@@ -212,10 +240,7 @@ To get notified when a feature flag is changed, we offer two methods
 - subscribe to the changes of any feature flag(s)
 
 ```javascript
-fbClient.on('ff_update', (changes) => {
-  // changes has this structure [{id: 'the feature_flag_key', oldValue: theOldValue, newValue: theNewValue }]
-  // the type of theOldValue and theNewValue is defined on FeatBit
-  
+fbClient.on('update', (keys: string[]) => {
   // do something when any feature flag changes
 });
 
@@ -224,66 +249,53 @@ fbClient.on('ff_update', (changes) => {
 
 ```javascript
 // replace feature_flag_key with your feature flag key
-fbClient.on('ff_update:feature_flag_key', (change) => {
-  // change has this structure {id: 'the feature_flag_key', oldValue: theOldValue, newValue: theNewValue }
-  // the type of theOldValue and theNewValue is defined on FeatBit
-
-  // defaultValue should have the same type as theOldValue and theNewValue
-  // this is the prefered way than calling change.newValue as each time you call fbClient.variation,
-  // the insight data is sent to server automatically
+fbClient.on('update:feature_flag_key', (key) => {
   const myFeature = fbClient.variation('feature_flag_key', defaultValue);
 });
 
 ```
 
 ### Switch user after initialization
-If the user parameter cannot be passed by the init method, the following method can be used to set the user after initialization.
+If the user changed after some process, login for example, the following method can be used to set the user after initialization.
 
 ```javascript
 await fbClient.identify(user);
 ```
 
-We can manually call the method logout, which will switch the current user back to anonymous user if exists already or create a new anonymous user.
-
-```javascript
-fbClient.logout(user);
-```
 
 ### Data synchronization
 
-We use websocket to make the local data synchronized with the server, and then store them in memory by default. Whenever there is any change to a feature flag or its related data, this change will be pushed to the SDK, the average synchronization time is less than 100ms. Be aware the websocket connection may be interrupted due to internet outage, but it will be resumed automatically once the problem is gone.
+We use **WebSocket** or **Polling** to make the local data synchronized with the server, and then store them in localStorage by default. Whenever there is any change to a feature flag or its related data, this change will be pushed to the SDK, the average synchronization time is less than **100ms** if WebSocket is configured. Be aware the WebSocket/Polling connection may be interrupted due to internet outage, but it will be resumed automatically once the problem is gone.
 
 ### Network failure handling
 
 As all data is stored locally in the localStorage, in the following situations, the SDK would still work when there is temporarily no internet connection:
 - it has already received the data from previous connections
-- the fbClient.bootstrap(featureFlags) method is called with all necessary feature flags
+- the `fbClient.bootstrap(featureFlags)` method is called with all necessary feature flags
 
 In the meantime, the SDK would try to reconnect to the server by an incremental interval, this makes sure that the websocket would be restored when the internet connection is back.
 
-
 ### Experiments (A/B/n Testing)
 
-We support automatic experiments for page views and clicks, you just need to set your experiment on FeatBit portal, then you should be able to see the result in near real time after the experiment is started.
+We support automatic experiments for pageviews and clicks, you just need to set your experiment on our SaaS platform,
+then you should be able to see the result in near real time after the experiment is started.
 
 In case you need more control over the experiment data sent to our server, we offer a method to send custom event.
 
 ```javascript
-fbClient.sendCustomEvent([{
-  eventName: 'your event name',
-  numericValue: 1
-}])
+fbClient.track(eventName, numericValue);
 ```
 
-**numericValue** is not mandatory, the default value is **1**.
+**numericValue** is not mandatory, the default value is **1.0**.
 
-Make sure sendCustomEvent is called after the related feature flag is called by simply calling **fbClient.variation('featureFlagKeyName', 'default value')**, otherwise, the custom event won't be included into the experiment result.
+Make sure `track` is called after the related feature flag is called, otherwise the custom event won't be included
+into the experiment result.
 
 ## Getting support
-
-- If you have a specific question about using this SDK, we encourage you to [ask it in Slack](https://join.slack.com/t/featbit/shared_invite/zt-1ew5e2vbb-x6Apan1xZOaYMnFzqZkGNQ).
-- If you encounter a bug or would like to request a feature, [submit an issue](https://github.com/featbit/featbit-js-client-sdk/issues).
+- If you have a specific question about using this sdk, we encourage you
+  to [ask it in our slack](https://join.slack.com/t/featbit/shared_invite/zt-1ew5e2vbb-x6Apan1xZOaYMnFzqZkGNQ).
+- If you encounter a bug or would like to request a
+  feature, [submit an issue](https://github.com/featbit/dotnet-server-sdk/issues/new).
 
 ## See Also
-
-- [Connect To JavaScript Sdk](https://docs.featbit.co/getting-started/connect-an-sdk#javascript)
+- [Connect To JavaScript Sdk](https://docs.featbit.co/getting-started/connect-an-sdk#javascript)

package/dist/esm/Configuration.d.ts

@@ -0,0 +1,35 @@
+import { IOptions } from "./options/IOptions";
+import { ILogger } from "./logging/ILogger";
+import { IValidatedOptions } from "./options/IValidatedOptions";
+import { IStore } from "./platform/IStore";
+import { IClientContext } from "./options/IClientContext";
+import { IDataSynchronizer } from "./data-sync/IDataSynchronizer";
+import { IDataSourceUpdates } from "./store/IDataSourceUpdates";
+import { VoidFunction } from "./utils/VoidFunction";
+import { IBootstrapProvider } from "./bootstrap/IBootstrapProvider";
+import { DataSyncModeEnum } from "./data-sync/DataSyncMode";
+import { IUser } from "./options/IUser";
+/**
+ * @internal
+ */
+export declare const defaultValues: IValidatedOptions;
+export default class Configuration {
+    readonly startWaitTime: number;
+    readonly sdkKey: string;
+    readonly streamingUri: string;
+    readonly pollingUri: string;
+    readonly eventsUri: string;
+    readonly webSocketPingInterval: number;
+    readonly logger?: ILogger;
+    readonly flushInterval: number;
+    readonly maxEventsInQueue: number;
+    readonly pollingInterval: number;
+    readonly offline: boolean;
+    readonly dataSyncMode: DataSyncModeEnum;
+    readonly bootstrapProvider: IBootstrapProvider;
+    readonly user: IUser;
+    readonly storeFactory: (clientContext: IClientContext) => IStore;
+    readonly dataSynchronizerFactory?: (clientContext: IClientContext, store: IStore, dataSourceUpdates: IDataSourceUpdates, initSuccessHandler: VoidFunction, errorHandler?: (e: Error) => void) => IDataSynchronizer;
+    constructor(options?: IOptions);
+}
+//# sourceMappingURL=Configuration.d.ts.map

package/dist/esm/Configuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Configuration.d.ts","sourceRoot":"","sources":["../../src/Configuration.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAC;AAGhE,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAC1D,OAAO,EAAE,iBAAiB,EAAE,MAAM,+BAA+B,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAEhE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AAGpE,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAgCxC;;GAEG;AACH,eAAO,MAAM,aAAa,EAAE,iBAgB3B,CAAC;AAiEF,MAAM,CAAC,OAAO,OAAO,aAAa;IAChC,SAAgB,aAAa,EAAE,MAAM,CAAC;IAEtC,SAAgB,MAAM,EAAE,MAAM,CAAC;IAE/B,SAAgB,YAAY,EAAE,MAAM,CAAC;IAErC,SAAgB,UAAU,EAAE,MAAM,CAAC;IAEnC,SAAgB,SAAS,EAAE,MAAM,CAAC;IAElC,SAAgB,qBAAqB,EAAE,MAAM,CAAC;IAE9C,SAAgB,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjC,SAAgB,aAAa,EAAE,MAAM,CAAC;IAEtC,SAAgB,gBAAgB,EAAE,MAAM,CAAC;IAEzC,SAAgB,eAAe,EAAE,MAAM,CAAC;IAExC,SAAgB,OAAO,EAAE,OAAO,CAAC;IAEjC,SAAgB,YAAY,EAAE,gBAAgB,CAAC;IAE/C,SAAgB,iBAAiB,EAAE,kBAAkB,CAA+B;IAEpF,SAAgB,IAAI,EAAE,KAAK,CAAC;IAE5B,SAAgB,YAAY,EAAE,CAAC,aAAa,EAAE,cAAc,KAAK,MAAM,CAAC;IAExE,SAAgB,uBAAuB,CAAC,EAAE,CACxC,aAAa,EAAE,cAAc,EAC7B,KAAK,EAAE,MAAM,EACb,iBAAiB,EAAE,kBAAkB,EACrC,kBAAkB,EAAE,YAAY,EAChC,YAAY,CAAC,EAAE,CAAC,CAAC,EAAE,KAAK,KAAK,IAAI,KAC9B,iBAAiB,CAAC;gBAEX,OAAO,GAAE,QAAa;CA6DnC"}