shadow-blade-tool v3.0.0

Flagger SDK

An opensource JavaScript SDK for feature flagging(feature gating, feature toggles) for browser and nodejs

Adding a dependency

Make sure that all new dependencies are listed in rollup.config.js

Build

Build consist of two phases:

• tsc compiles *.ts to ES2017 target. These files are in temp folder
• rollup creates 3 bundles(umd, ES2017, CommonJS) from that compiled code. Also, rollup overrides VERSION and SDK_NAME accordingly

note: React wrapper for Flagger is no longer a part of this repo

Features

• Blazing fast, requires only 1 backend call to decide what flag to show
• Highly customizable
• Sampling(canary release) and multivariate A/B testing with custom filters
• Auto-updatable configuration(via SSE)
• Records usage analytics as well as custom events
• white- and blacklisting
• 2 level entity support (Manager-Employee, Client-Company)

Quick start

Install dependency

npm i flagger

Import flagger to you application

// In CommonJS
var Flagger = require('flagger')

// In ES2015 modules
import Flagger from 'flagger'

Flagger SDK requires a config to decide what flag to show. Init Flagger with a config from Airdeploy server or from your custom server

// Airdeploy server
await Flagger.init({env: 123})

// Or manually
await Flagger.init({env: 123, sourceURL: 'https://someserver.com'})

Use Flagger to get flag* and control flow of your application code. Flag requires an Entity(object with id) to work. All flag functions are idempotent

const user = {id: '1'}
const isEnabled = Flagger.flagIsEnabled('new-dashboard', user)

if (isEnabled)) {
  // show new dashboard
} else {
  // show old dashboard
}

You can pass Entity to the flagger instance to not specify it in every flag function

Flagger.setEntity({id: '1'})

How it works

Refer to Flagger documentation website

Key concepts

The core of the flagger takes a flaggerConfig, entity and flagName and resolves it to a Flag. Flag has multiple purposes:

• toggle on/off features
• provide an ability to do A/B testing (multivariative features)
• get flag payload
• undestand whether current entity is sampled or not

FAQ

1. How many backend call does Flagger do?

   It only requires 1 call to load config and from then every call to API do not require a call to remote server

2. How can I update flag config on user's device?

   When user open your app, SDK is initializing with new config. When user is already using your app, Flagger holds an SSE connection from server to push new config. This invariant makes sure all users has up to date config

3. How can I know which version of a flag was shown to a user?

   Flagger automatically gathers this data(we call it ingestion data) and sends it to the `Backend`

4. Does flag version idempotent? Will the same user see the same feature when the page is updated?

   Yes

API

Glossary

Flagger - is a singleton object. use .init() function at your app initialization and then just import it whenever you want.

Entity - object with 1 required field: id. Example:

{
    "id": 90843823,
    "name": "Kyle Stroman",
    "attributes": {
      "jobTitle": "Internal Intranet Administrator",
      "email": "kyle62@herzogrobelandebert.com",
      ...
      "country": "South Korea"
    },
    "type": "User",
    "group": {
      "attributes": {
        "emailDomain": "herzogrobelandebert.com",
        ...
        "country": "Greece"
      },
      "id": 84617314,
      "name": "Herzog, Robel and Ebert",
      "type": "Company"
    }
  }

Flag - multipurpose core entity of the Flagger SDK. It helps you with toggling features on/off and deciding, for example, which color of a button to show to what kind of user.

Filter - a child of a subpopulation. You can treat it like a where clause in SQL. It helps to filter out entities by their attributes

Backend - a server for Flagger SDK. It serves a config and takes ingestion data. Could be provided by Airdeploy or you can deploy your own

Tests

npm test

Licence

MIT