@ops-ai/feature-flags-toggly 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+## 0.0.1
+
+2022-11-21 (Date of Last Commit)
+
+* Toggly classe & models
+* Allow usage without Toggly service (by providing flagDefaults)
+* Allow usage with Toggly service (by providing your App Key & Environment name)
+* Feature evaluation methods unit tests
+* Documentation
+* License
+
+
+

package/LICENSE

@@ -0,0 +1,11 @@
+Copyright 2022 opsAI LLC
+
+Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -0,0 +1,134 @@
+Lightweight package that provides feature flags support for javascript applications allowing you to check feature status and enable/disable them easily.
+
+Can be used *WITH* or *WITHOUT* [Toggly.io](https://toggly.io).
+
+## What is a Feature Flag
+
+A feature flag (or toggle) in software development provides an alternative to maintaining multiple feature branches in source code. A condition within the code enables or disables a feature during runtime.
+
+In agile settings the feature flag is used in production, to switch on the feature on demand, for some or all the users. Thus, feature flags make it easier to release often. Advanced roll out strategies such as canary roll out and A/B testing are easier to handle.
+
+## Installation
+
+Simply embed our latest bundle from the following CDN.
+
+```html
+<script src="..."></script>
+```
+
+Alternatively, you can use NPM to manually build the bundled *.js file.
+
+```shell
+$ npm install @ops-ai/feature-flags-toggly
+$ cd node_modules/@ops-ai/feature-flags-toggly && npm run build
+```
+
+And then grab the generated bundled file from the */dist directory.
+
+## Basic Usage (with Toggly.io)
+
+Initialize Toggly by running the Toggly.init method and by providing your App Key from your [Toggly application page](https://app.toggly.io)
+
+```js
+var featureFlagsDefaults = {
+  "SignUpButton": true,
+  "DemoScreenshot": true
+};
+
+Toggly.init({
+  appKey: '<YOUR_APP_KEY>',
+  environment: '<YOUR_APP_ENVIRONMENT>'
+})
+  .then(function () {
+    // Now you can check if a feature (or more) is Enabled/Disabled
+    
+    if (Toggly.isFeatureOn('SignUpButton')) {
+      // SignUpButton is ON
+    }
+
+    if (Toggly.isFeatureOff('DemoScreenshot')) {
+      // DemoScreenshot is OFF
+    }
+});
+```
+
+You can also check multiple feature keys and make use of the *requirement* (FeatureRequirement.all, FeatureRequirement.any) and *negate* (bool) options.
+
+```js
+if (Toggly.evaluateFeatureGate(['ExampleFeatureKey1', 'ExampleFeatureKey2'], FeatureRequirement.all)) {
+  // ALL the provided feature keys are TRUE
+}
+```
+
+```js
+if (Toggly.evaluateFeatureGate(['ExampleFeatureKey1', 'ExampleFeatureKey2'], FeatureRequirement.any)) {
+  // AT LEAST ONE the provided feature keys is TRUE
+}
+```
+
+```js
+if (Toggly.evaluateFeatureGate(['ExampleFeatureKey1', 'ExampleFeatureKey2'], FeatureRequirement.all, true)) {
+  // ALL the provided feature keys are FALSE
+}
+```
+
+Lastly, you can set how often you would like to synchronize (re-fetch from Toggly) the feature flags values by setting the *.featureFlagsRefreshInterval when runnint *.init.
+
+```js
+Toggly.init({
+  appKey: '<YOUR_APP_KEY>',
+  environment: '<YOUR_APP_ENVIRONMENT>',
+  featureFlagsRefreshInterval: 3 * 60 * 1000
+})
+  .then(function () {
+    // Now you can check if a feature (or more) is Enabled/Disabled ...
+  });
+```
+
+## Basic Usage (without Toggly.io)
+
+Initialize Toggly by running the Toggly.init method
+
+```js
+var featureFlagsDefaults = {
+  "SignUpButton": true,
+  "DemoScreenshot": true
+};
+
+Toggly.init({ flagDefaults: featureFlagsDefaults }).then(function () {
+
+  // Now you can check if a feature (or more) is Enabled/Disabled
+  
+  if (Toggly.isFeatureOn('SignUpButton')) {
+    // SignUpButton is ON
+  }
+
+  if (Toggly.isFeatureOff('DemoScreenshot')) {
+    // DemoScreenshot is OFF
+  }
+});
+```
+
+You can also check multiple feature keys and make use of the *requirement* (FeatureRequirement.all, FeatureRequirement.any) and *negate* (bool) options.
+
+```js
+if (Toggly.evaluateFeatureGate(['ExampleFeatureKey1', 'ExampleFeatureKey2'], FeatureRequirement.all)) {
+  // ALL the provided feature keys are TRUE
+}
+```
+
+```js
+if (Toggly.evaluateFeatureGate(['ExampleFeatureKey1', 'ExampleFeatureKey2'], FeatureRequirement.any)) {
+  // AT LEAST ONE the provided feature keys is TRUE
+}
+```
+
+```js
+if (Toggly.evaluateFeatureGate(['ExampleFeatureKey1', 'ExampleFeatureKey2'], FeatureRequirement.all, true)) {
+  // ALL the provided feature keys are FALSE
+}
+```
+
+## Find out more about Toggly.io
+
+Visit [our official website](https://toggly.io) or [check out a video overview of our product](https://docs.toggly.io/).

package/example/index.html

@@ -0,0 +1,65 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+  <meta charset="UTF-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Feature Flags Example</title>
+
+  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.2/dist/css/bootstrap.min.css" rel="stylesheet"
+    integrity="sha384-Zenh87qX5JnK2Jl0vWa8Ck2rdkQ2Bzep5IDxbcnCeuOxjzrPF/et3URy9Bv1WTRi" crossorigin="anonymous">
+  <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.2.2/dist/js/bootstrap.bundle.min.js"
+    integrity="sha384-OERcA2EqjJCMA+/3y+gxIOqMEjwtxJY7qPCqsdltbNJuaOe923+mo//f6V8Qbsw3"
+    crossorigin="anonymous"></script>
+</head>
+
+<body>
+  <div class="px-4 pt-5 my-5 text-center border-bottom">
+    <h1 class="display-5 fw-bold mb-5">What is a Feature Flag?</h1>
+    <div class="col-lg-6 mx-auto">
+      <p class="lead mb-4">A feature flag (or toggle) in software development provides an alternative to maintaining
+        multiple feature branches in source code. A condition within the code enables or disables a feature during
+        runtime.</p>
+      <p class="lead mb-4">In agile settings the feature flag is used in production, to switch on the feature on demand,
+        for some or all the users. Thus, feature flags make it easier to release often. Advanced roll out strategies
+        such as canary roll out and A/B testing are easier to handle.</p>
+      <div class="d-grid gap-2 d-sm-flex justify-content-sm-center">
+        <a href="https://app.toggly.io/register" id="signUpButton" type="button"
+          class="d-none btn btn-primary btn-lg px-4 gap-3" style="background: #556ee6; border: #556ee6;">Sign up for
+          FREE</a>
+        <a href="https://toggly.io" type="button" class="btn btn-outline-secondary btn-lg px-4">Find out more on
+          Toggly.io</a>
+      </div>
+      <small class="d-block text-muted my-3">Note: You can use this library <strong>WITH</strong> or
+        <strong>WITHOUT</strong> Toggly.io</small>
+    </div>
+    <div id="demoScreenshot" class="overflow-hidden" style="max-height: 30vh;">
+      <div class="container px-5">
+        <img src="./demo-app-screenshot.png" class="img-fluid border rounded-3 shadow-lg mb-4" alt="Example image"
+          width="700" height="500" loading="lazy">
+      </div>
+    </div>
+  </div>
+
+  <script src="../dist/feature-flags-toggly.bundle.js"></script>
+  <script>
+    var featureFlagsDefaults = {
+      "SignUpButton": true,
+      "DemoScreenshot": true
+    };
+
+    Toggly.init({ flagDefaults: featureFlagsDefaults }).then(function () {
+
+      // Now you can check if a feature (or more) is Enabled/Disabled
+      if (Toggly.isFeatureOn('SignUpButton')) {
+        document.querySelector('#signUpButton').classList.remove('d-none');
+      }
+      if (Toggly.isFeatureOff('DemoScreenshot')) {
+        document.querySelector('#demoScreenshot').classList.add('d-none');
+      }
+    });
+  </script>
+</body>
+
+</html>

package/jest.config.js

@@ -0,0 +1,5 @@
+/** @type {import('ts-jest').JestConfigWithTsJest} */
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'jsdom',
+};

package/lib/models/feature-requirement.ts

@@ -0,0 +1,4 @@
+export enum FeatureRequirement {
+  all,
+  any
+}

package/lib/models/index.ts

@@ -0,0 +1,4 @@
+export * from './toggly-config';
+export * from './toggly-init-response';
+export * from './feature-requirement';
+export * from './storage-keys';

package/lib/models/storage-keys.ts

@@ -0,0 +1,4 @@
+export enum StorageKeys {
+  togglyIdentityKey,
+  togglyFeatureFlagsKey,
+}

package/lib/models/toggly-config.ts

@@ -0,0 +1,11 @@
+export interface TogglyConfig {
+  baseURI?: string;
+  reloadOnFeatureFlagValidation?: boolean;
+  connectTimeout?: number;
+  featureFlagsRefreshInterval?: number;
+  isDebug?: boolean;
+
+  appKey?: string;
+  environment?: string;
+  flagDefaults?: { [key: string]: boolean };
+}

package/lib/models/toggly-init-response.ts

@@ -0,0 +1,14 @@
+export enum TogglyLoadFeatureFlagsResponse {
+  fetched,
+  cached,
+  defaults,
+  error,
+}
+
+export class TogglyInitResponse {
+  status: TogglyLoadFeatureFlagsResponse;
+
+  constructor(status: TogglyLoadFeatureFlagsResponse) {
+    this.status = status;
+  }
+}

package/lib/toggly.ts

@@ -0,0 +1,150 @@
+import { v4 as uuidv4 } from 'uuid';
+import { FeatureRequirement, StorageKeys, TogglyConfig } from './models';
+
+export class Toggly {
+  private static _config: TogglyConfig;
+  private static _refreshInterval: number | undefined;
+
+  static init(config: TogglyConfig = {} as TogglyConfig): Promise<{ [key: string]: boolean }> {
+    Toggly._config = Object.assign({
+      baseURI: 'https://client.toggly.io',
+      reloadOnFeatureFlagValidation: false,
+      connectTimeout: 5 * 1000,
+      featureFlagsRefreshInterval: 3 * 60 * 1000,
+      isDebug: false,
+      environment: 'Production',
+      flagDefaults: {}
+    }, config);
+
+    if (!Toggly.identity) {
+      Toggly.identity = uuidv4();
+    }
+
+    Toggly.clearFeatureFlagsCache();
+    Toggly.startRefreshInterval();
+
+    return Toggly.refresh();
+  }
+
+  static get featureFlagsValue(): { [key: string]: boolean } {
+    var cachedFlags = JSON.parse(localStorage.getItem(StorageKeys.togglyFeatureFlagsKey.toString()) ?? null);
+    return Toggly._config?.appKey && cachedFlags ? cachedFlags : Toggly._config?.flagDefaults ?? {};
+  }
+
+  static get identity(): string {
+    return localStorage.getItem(StorageKeys.togglyIdentityKey.toString());
+  }
+
+  static set identity(v: string) {
+    localStorage.setItem(StorageKeys.togglyIdentityKey.toString(), v);
+  }
+
+  static clearIdentity() {
+    localStorage.removeItem(StorageKeys.togglyIdentityKey.toString());
+  }
+
+  private static get _cachedFeatureFlags(): { [key: string]: boolean } {
+    return JSON.parse(localStorage.getItem(StorageKeys.togglyFeatureFlagsKey.toString()) ?? null);
+  }
+
+  static cacheFeatureFlags(flags: { [key: string]: boolean }) {
+    localStorage.setItem(StorageKeys.togglyFeatureFlagsKey.toString(), JSON.stringify(flags));
+  }
+
+  static clearFeatureFlagsCache() {
+    localStorage.removeItem(StorageKeys.togglyFeatureFlagsKey.toString());
+  }
+
+  static fetchFeatureFlags(): Promise<{ [key: string]: boolean }> {
+    return new Promise((resolve, reject) => {
+      var url = `${Toggly._config.baseURI}/${Toggly._config.appKey}-${Toggly._config.environment}/defs`;
+
+      if (Toggly.identity) {
+        url += `?u=${Toggly.identity}`;
+      }
+
+      fetch(url)
+        .then((response) => response.json())
+        .then((flags) => {
+          // Cache flags on successful response
+          Toggly.cacheFeatureFlags(flags);
+          resolve(flags);
+
+          if (Toggly._config.isDebug) { console.log(`Toggly.fetchFeatureFlags - ${JSON.stringify(flags)}`); }
+        })
+        .catch((error) => {
+          // Try to use flags from cache, otherwise use provided default flags
+          var flags = Toggly._cachedFeatureFlags ?? Toggly._config.flagDefaults;
+          resolve(flags);
+
+          if (Toggly._config.isDebug) { console.log(`Toggly.loadedFromCache - ${JSON.stringify(flags)}`); }
+        });
+    });
+  }
+
+  static refresh(): Promise<{ [key: string]: boolean }> {
+    if (Toggly._config.isDebug) { console.log('Toggly.refresh'); }
+
+    // In case there is no API key provided, only the flag defaults shall be used
+    if (!Toggly._config.appKey) {
+      if (Toggly._config.isDebug) { console.log(`Toggly.usedFlagDefaults - ${JSON.stringify(Toggly._config.flagDefaults)}`); }
+
+      return new Promise((resolve, reject) => {
+        resolve(Toggly._config.flagDefaults);
+      });
+    }
+
+    // Try to fetch flags from the API
+    return Toggly.fetchFeatureFlags();
+  }
+
+  private static _evaluateFeatureGate(flags: { [key: string]: boolean } = {}, featureGate: string[], requirement: FeatureRequirement = FeatureRequirement.all, negate: boolean = false) {
+    var isEnabled: boolean;
+
+    if (requirement === FeatureRequirement.any) {
+      isEnabled = featureGate.reduce((isEnabled, featureKey) => {
+        return isEnabled ||
+          (flags[featureKey] && flags[featureKey] === true);
+      }, false);
+    } else {
+      isEnabled = featureGate.reduce((isEnabled, featureKey) => {
+        return isEnabled &&
+          (flags[featureKey] && flags[featureKey] === true);
+      }, true);
+    }
+
+    if (Toggly._config.isDebug) { console.log(`Toggly._evaluateFeatureGate - ${JSON.stringify(featureGate)}`); }
+
+    isEnabled = negate ? !isEnabled : isEnabled;
+
+    return isEnabled;
+  }
+
+  static evaluateFeatureGate(featureGate: string[], requirement: FeatureRequirement = FeatureRequirement.all, negate: boolean = false): boolean {
+    return Toggly._evaluateFeatureGate(Toggly.featureFlagsValue, featureGate, requirement, negate);
+  }
+
+  static isFeatureOn(featureKey: string): boolean {
+    return Toggly._evaluateFeatureGate(Toggly.featureFlagsValue, [featureKey]);
+  }
+
+  static isFeatureOff(featureKey: string): boolean {
+    return Toggly._evaluateFeatureGate(Toggly.featureFlagsValue, [featureKey], FeatureRequirement.all, true);
+  }
+
+  static cancelRefreshInterval() {
+    window.clearInterval(Toggly._refreshInterval);
+    Toggly._refreshInterval = undefined;
+  }
+
+  static startRefreshInterval() {
+    Toggly.cancelRefreshInterval();
+
+    if (Toggly._config.appKey && Toggly._config.featureFlagsRefreshInterval > 0) {
+      Toggly._refreshInterval = window.setInterval(() => Toggly.refresh(), Toggly._config.featureFlagsRefreshInterval);
+    }
+  }
+}
+
+(window as any).Toggly = Toggly;
+

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@ops-ai/feature-flags-toggly",
+  "version": "1.0.0",
+  "description": "Provides feature flags support for Javascript applications allowing you to enable and disable features easily. Can be used with or without Toggly.io.",
+  "main": "index.js",
+  "scripts": {
+    "build": "webpack",
+    "dev": "npx webpack -w",
+    "test": "npx jest"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ops-ai/Toggly.FeatureManagement.git#develop"
+  },
+  "author": {
+    "name": "Cosmin Atomei",
+    "email": "cosmin.atomei@gmail.com"
+  },
+  "license": "BSD-3-Clause",
+  "bugs": {
+    "url": "https://github.com/ops-ai/Toggly.FeatureManagement/issues"
+  },
+  "homepage": "https://github.com/ops-ai/Toggly.FeatureManagement/tree/develop#readme",
+  "dependencies": {
+    "rxjs": "^7.5.7",
+    "uuid": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.2.3",
+    "@types/uuid": "^8.3.4",
+    "jest": "^29.3.1",
+    "jest-environment-jsdom": "^29.3.1",
+    "ts-jest": "^29.0.3",
+    "ts-loader": "^9.4.1",
+    "typescript": "^4.9.3",
+    "webpack": "^5.75.0",
+    "webpack-cli": "^5.0.0"
+  }
+}

package/spec/toggly.spec.ts

@@ -0,0 +1,33 @@
+import { FeatureRequirement } from '../lib/models';
+import { Toggly } from '../lib/toggly';
+
+beforeAll(() => {
+  return Toggly.init({
+    flagDefaults: {
+      "ExampleFeatureKey1": true,
+      "ExampleFeatureKey2": false
+    }
+  });
+});
+
+test('Check (isFeatureOn) result based on provided *.flagDefaults', () => {
+  expect(Toggly.isFeatureOn('ExampleFeatureKey1')).toBe(true);
+  expect(Toggly.isFeatureOn('ExampleFeatureKey2')).toBe(false);
+});
+
+test('Check (isFeatureOff) result based on provided *.flagDefaults', () => {
+  expect(Toggly.isFeatureOff('ExampleFeatureKey1')).toBe(false);
+  expect(Toggly.isFeatureOff('ExampleFeatureKey2')).toBe(true);
+});
+
+test('Check (evaluateFeatureGate, requirement: All) result based on provided *.flagDefaults', () => {
+  return expect(Toggly.evaluateFeatureGate(['ExampleFeatureKey1', 'ExampleFeatureKey2'], FeatureRequirement.all)).toBe(false);
+});
+
+test('Check (evaluateFeatureGate, requirement: Any) result based on provided *.flagDefaults', () => {
+  return expect(Toggly.evaluateFeatureGate(['ExampleFeatureKey1', 'ExampleFeatureKey2'], FeatureRequirement.any)).toBe(true);
+});
+
+test('Check (evaluateFeatureGate, negate) result based on provided *.flagDefaults', () => {
+  return expect(Toggly.evaluateFeatureGate(['ExampleFeatureKey1'], FeatureRequirement.all, true)).toBe(false);
+});

package/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "compilerOptions": {
+    "target": "es5",
+    "lib": ["es2016", "DOM"],
+    "rootDir": "./",
+    "sourceMap": true
+  }
+}

package/webpack.config.js

@@ -0,0 +1,23 @@
+const path = require('path');
+
+module.exports = {
+  mode: "production",
+  entry: {
+    main: "./lib/toggly.ts",
+  },
+  output: {
+    path: path.resolve(__dirname, './dist'),
+    filename: "feature-flags-toggly.bundle.js"
+  },
+  resolve: {
+    extensions: [".ts", ".tsx", ".js"],
+  },
+  module: {
+    rules: [
+      {
+        test: /\.tsx?$/,
+        loader: "ts-loader"
+      }
+    ]
+  }
+};