Major improvement on performance - added static context option (#203)

Author: petruki

README.md

@@ -28,7 +28,7 @@ https://github.com/switcherapi/switcher-api
 - Flexible and robust functions that will keep your code clean and maintainable.
 - Able to work locally using a snapshot file downloaded from your remote Switcher-API Domain.
 - Silent mode is a hybrid configuration that automatically enables a contingent sub-process in case of any connectivity issue.
-- Built-in mock implementation for clear and easy implementation of automated testing.
+- Built-in stub implementation for clear and easy implementation of automated testing.
 - Easy to setup. Switcher Context is responsible to manage all the complexity between your application and API.
 
 # Usage
@@ -60,6 +60,7 @@ You can also activate features such as local and silent mode:
 
 ```js
 const local = true;
+const static = true;
 const logger = true;
 const snapshotLocation = './snapshot/';
 const snapshotAutoUpdateInterval = 3;
@@ -69,14 +70,15 @@ const restrictRelay = true;
 const certPath = './certs/ca.pem';
 
 Client.buildContext({ url, apiKey, domain, component, environment }, {
-    local, logger, snapshotLocation, snapshotAutoUpdateInterval, 
+    local, static, logger, snapshotLocation, snapshotAutoUpdateInterval, 
     snapshotWatcher, silentMode, restrictRelay, certPath
 });
 
 const switcher = Client.getSwitcher();
 ```
 
 - **local**: If activated, the client will only fetch the configuration inside your snapshot file. The default value is 'false'
+- **static**: If activated, the client will not perform any API calls and will only use the in-memory snapshot. The default value is 'false'
 - **logger**: If activated, it is possible to retrieve the last results from a given Switcher key using Client.getLogger('KEY')
 - **snapshotLocation**: Location of snapshot files
 - **snapshotAutoUpdateInterval**: Enable Snapshot Auto Update given an interval in seconds (default: 0 disabled)
@@ -91,11 +93,11 @@ const switcher = Client.getSwitcher();
 (*) regexSafe is a feature that prevents your application from being exposed to a reDOS attack. It is recommended to keep this feature enabled.<br>
 
 ## Executing
-There are a few different ways to call the API using the JavaScript module.
+There are a few different ways to call the API.
 Here are some examples:
 
 1. **No parameters**
-Invoking the API can be done by instantiating the switcher and calling *isItOn* passing its key as a parameter.
+This is the simplest way to execute a criteria. It will return a boolean value indicating whether the feature is enabled or not.
 
 ```js
 const switcher = Client.getSwitcher();
@@ -104,36 +106,29 @@ await switcher.isItOn('FEATURE01');
 const { result, reason, metadata } = await switcher.detail().isItOn('FEATURE01');
 ```
 
-2. **Promise**
-Most functions were implemented using async operations. Here it is a differnet way to execute the criteria:
-
-```js
-switcher.isItOn('KEY')
-    .then(result => console.log('Result:', result))
-    .catch(error => console.log(error));
-```
-
-3. **Strategy validation - preparing input**
+2. **Strategy validation - preparing input**
 Loading information into the switcher can be made by using *prepare*, in case you want to include input from a different place of your code. Otherwise, it is also possible to include everything in the same call.
 
 ```js
-switcher.checkValue('USER_1').prepare('FEATURE01');
-switcher.isItOn();
+await switcher.checkValue('USER_1').prepare('FEATURE01');
+await switcher.isItOn();
 ```
 
-4. **Strategy validation - all-in-one execution**
+3. **Strategy validation - all-in-one execution**
 All-in-one method is fast and include everything you need to execute a complex call to the API.
 
 ```js
 await switcher
+    .defaultResult(true)    // Default result to be returned in case of no API response
+    .throttle(1000)         // Throttle the API call to improve performance
     .checkValue('User 1')
     .checkNetwork('192.168.0.1')
     .isItOn('FEATURE01');
 ```
 
-5. **Throttle**
-Throttling is useful when placing Feature Flags at critical code blocks require zero-latency without having to switch to local.
-API calls will happen asynchronously and the result returned is based on the last API response.
+4. **Throttle**
+Throttling is useful when placing Feature Flags at critical code blocks that require zero-latency.
+API calls will be scheduled to be executed after the throttle time has passed.
 
 ```js
 const switcher = Client.getSwitcher();
@@ -150,16 +145,19 @@ Client.subscribeNotifyError((error) => {
 });
 ```
 
-6. **Hybrid mode**
+5. **Hybrid mode**
 Forcing Switchers to resolve remotely can help you define exclusive features that cannot be resolved locally.
 This feature is ideal if you want to run the SDK in local mode but still want to resolve a specific switcher remotely.
+
+A particular use case is when a swithcer has a Relay Strategy that requires a remote call to resolve the value.
+
 ```js
 const switcher = Client.getSwitcher();
 await switcher.remote().isItOn('FEATURE01');
 ```
 
-## Built-in mock feature
-You can also bypass your switcher configuration by invoking 'Client.assume'. This is perfect for your test code where you want to validate both scenarios when the switcher is true and false.
+## Built-in stub feature
+You can also bypass your switcher configuration with 'Client.assume' API. This is perfect for your test code where you want to validate both scenarios when the switcher is true and false.
 
 ```js
 Client.assume('FEATURE01').true();

package.json

@@ -1,6 +1,6 @@
 {
   "name": "switcher-client",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "Client JS SDK for working with Switcher-API",
   "main": "./switcher-client.js",
   "type": "module",
@@ -32,12 +32,12 @@
   ],
   "devDependencies": {
     "@babel/eslint-parser": "^7.27.5",
-    "@typescript-eslint/eslint-plugin": "^8.35.0",
-    "@typescript-eslint/parser": "^8.35.0",
+    "@typescript-eslint/eslint-plugin": "^8.35.1",
+    "@typescript-eslint/parser": "^8.35.1",
     "c8": "^10.1.3",
     "chai": "^5.2.0",
     "env-cmd": "^10.1.0",
-    "eslint": "^9.29.0",
+    "eslint": "^9.30.0",
     "mocha": "^11.7.1",
     "mocha-sonarqube-reporter": "^1.0.2",
     "sinon": "^21.0.0"

sonar-project.properties

@@ -1,7 +1,7 @@
 sonar.projectKey=switcherapi_switcher-client-master
 sonar.projectName=switcher-client-js
 sonar.organization=switcherapi
-sonar.projectVersion=4.2.0
+sonar.projectVersion=4.4.0
 sonar.links.homepage=https://github.com/switcherapi/switcher-client-js
 
 sonar.javascript.lcov.reportPaths=coverage/lcov.info

src/client.d.ts

@@ -180,24 +180,37 @@ export type SwitcherContext = {
 export type SwitcherOptions = {
   /**
    * When enabled it will use the local snapshot (file or in-memory)
+   *
    * If not set, it will use the remote API
    */
   local?: boolean;
 
+  /**
+   * When enabled it will always use in-memory cached results
+   *
+   * This option prevents the scheduling of background updates to improve overall performance
+   *
+   * Use Client.clearLogger() to reset the in-memory cache if snapshot are renewed
+   */
+  static?: boolean;
+
   /**
    * When enabled it allows inspecting the result details with Client.getLogger(key)
+   *
    * If not set, it will not log the result details
    */
   logger?: boolean;
 
   /**
    * The location of the snapshot file
+   *
    * If not set, it will use the in-memory snapshot
    */
   snapshotLocation?: string;
 
   /**
    * The interval in milliseconds to auto-update the snapshot
+   *
    * If not set, it will not auto-update the snapshot
    */
   snapshotAutoUpdateInterval?: number;
@@ -208,36 +221,41 @@ export type SwitcherOptions = {
   snapshotWatcher?: boolean;
 
   /**
-   * Allow local snapshots to ignore or require Relay verification.
+   * Allow local snapshots to ignore or require Relay verification
    */
   restrictRelay?: boolean;
 
   /**
    * When defined it will switch to local during the specified time before it switches back to remote
+   *
    * e.g. 5s (s: seconds - m: minutes - h: hours)
    */
   silentMode?: string;
 
   /**
    * When enabled it will check Regex strategy using background workers
+   *
    * If not set, it will check Regex strategy synchronously
    */
   regexSafe?: boolean;
 
   /**
-   * The regex max black list
+   * The regex max black list.
+   *
    * If not set, it will use the default value
    */
   regexMaxBlackList?: number;
 
   /**
    * The regex max time limit in milliseconds
+   *
    * If not set, it will use the default value
    */
   regexMaxTimeLimit?: number;
 
   /**
    * The certificate path for secure connections
+   *
    * If not set, it will use the default certificate
    */
   certPath?: string;

src/client.js

@@ -9,6 +9,7 @@ import {
   DEFAULT_LOGGER, 
   DEFAULT_REGEX_MAX_BLACKLISTED, 
   DEFAULT_REGEX_MAX_TIME_LIMIT, 
+  DEFAULT_STATIC,
   DEFAULT_TEST_MODE,
   SWITCHER_OPTIONS 
 } from './lib/constants.js';
@@ -38,6 +39,7 @@ export class Client {
       snapshotAutoUpdateInterval: 0,
       snapshotLocation: options?.snapshotLocation,
       local: util.get(options?.local, DEFAULT_LOCAL),
+      static: util.get(options?.static, DEFAULT_STATIC),
       logger: util.get(options?.logger, DEFAULT_LOGGER)
     });
 
@@ -130,18 +132,20 @@ export class Client {
     return false;
   }
 
-  static async loadSnapshot(options = { fetchRemote: false, watchSnapshot: false }) {
+  static async loadSnapshot(options = {}) {
+    const { fetchRemote = false, watchSnapshot = false } = options;
+
     GlobalSnapshot.init(loadDomain(
       util.get(GlobalOptions.snapshotLocation, ''), 
       util.get(Client.#context.environment, DEFAULT_ENVIRONMENT)
     ));
 
     if (GlobalSnapshot.snapshot.data.domain.version == 0 && 
-        (options.fetchRemote || !GlobalOptions.local)) {
+        (fetchRemote || !GlobalOptions.local)) {
       await Client.checkSnapshot();
     }
 
-    if (options.watchSnapshot) {
+    if (watchSnapshot) {
         Client.watchSnapshot();
     }
 

src/lib/constants.js

@@ -1,5 +1,6 @@
 export const DEFAULT_ENVIRONMENT = 'default';
 export const DEFAULT_LOCAL = false;
+export const DEFAULT_STATIC = false;
 export const DEFAULT_LOGGER = false;
 export const DEFAULT_TEST_MODE = false;
 export const DEFAULT_REGEX_MAX_BLACKLISTED = 50;

src/lib/globals/globalOptions.js

@@ -18,6 +18,10 @@ export class GlobalOptions {
     return this.#options.local;
   }
 
+  static get static() {
+    return this.#options.static;
+  }
+
   static get logger() {
     return this.#options.logger;
   }

src/lib/utils/executionLogger.js

@@ -1,3 +1,5 @@
+import { SwitcherResult } from '../result.js';
+
 const logger = new Array();
 
 export default class ExecutionLogger {
@@ -20,7 +22,14 @@ export default class ExecutionLogger {
             }
         }
 
-        logger.push({ key, input, response });
+        logger.push({
+        key,
+        input,
+        response: SwitcherResult.create(response.result, response.reason, {
+            ...response.metadata,
+            cached: true,
+        }),
+        });
     }
 
      /**
@@ -30,11 +39,13 @@ export default class ExecutionLogger {
      * @param input Switcher input
      */
     static getExecution(key, input) {
-        const result = logger.filter(
-            value => value.key === key && 
-            JSON.stringify(value.input) === JSON.stringify(input));
+        for (const log of logger) {
+            if (this.#hasExecution(log, key, input)) {
+                return log;
+            }
+        }
 
-        return result[0];
+        return new ExecutionLogger();
     }
 
      /**
@@ -68,5 +79,20 @@ export default class ExecutionLogger {
             ExecutionLogger.callbackError(error);
         }
     }
+
+    static #hasExecution(log, key, input) {
+        return log.key === key && this.#checkStrategyInputs(log.input, input);
+    }
+
+    static #checkStrategyInputs(loggerInputs, inputs) {
+        for (const [strategy, input] of loggerInputs || []) {
+        const found = inputs?.find((i) => i[0] === strategy && i[1] === input);
+        if (!found) {
+            return false;
+        }
+        }
+
+        return true;
+    }
 
 }

src/switcher.d.ts

@@ -19,10 +19,25 @@ export class Switcher {
 
   /**
    * Execute criteria
-   * 
+   *
    * @returns boolean or SwitcherResult when detail() is used
    */
-  isItOn(key?: string): Promise<boolean | SwitcherResult>;
+  isItOn(key?: string): Promise<boolean | SwitcherResult> | boolean | SwitcherResult;
+
+  /**
+   * Schedules background refresh of the last criteria request
+   */
+  scheduleBackgroundRefresh(): void;
+
+  /**
+   * Execute criteria from remote API
+   */
+  async executeRemoteCriteria(): Promise<boolean | SwitcherResult>
+
+  /**
+   * Execute criteria from local snapshot
+   */
+  async executeLocalCriteria(): Promise<boolean | SwitcherResult>
 
   /**
    * Define a delay (ms) for the next async execution.