feat: Add experimental debug override functionality. (#132)

**Requirements**

- [x] I have added test coverage for new or changed functionality
- [x] I have followed the repository's [pull request submission
guidelines](../blob/master/CONTRIBUTING.md#submitting-pull-requests)
- [ ] I have validated my changes against all supported platform
versions

**Describe the solution you've provided**

This PR adds debug override capability to the LaunchDarkly SDK, allowing
developers to override flag values during local development and testing
without affecting production flag configurations.

Key features:
- Flag Override Interface: New `LDDebugOverride` interface with methods
to set, remove, and manage flag overrides.
- Plugin Integration: Extended `LDPlugin` interface with optional
`registerDebug` method for plugins to access override functionality.
- Runtime Override Management: Override values take precedence over
remote flag values while preserving original flag evaluation logic.
- Testing: Added test coverage for all override methods and edge cases.

**Additional context**

This feature is designed primarily for development and testing workflows
where developers need to:
- Test different flag variations without modifying remote
configurations.
- Debug applications with specific flag states.
- Validate feature behavior across different flag combinations.

The implementation maintains backward compatibility and follows the
existing plugin architecture patterns. Override functionality is only
available when explicitly enabled through plugins, ensuring it doesn't
impact production performance or security.

---------

Co-authored-by: Subhav Gautam <[email protected]>

Author: pranjal-jately-ld

package.json

@@ -44,8 +44,8 @@
     "launchdarkly-js-test-helpers": "1.1.0",
     "prettier": "1.19.1",
     "readline-sync": "^1.4.9",
-    "typescript": "~5.4.5",
-    "typedoc": "^0.25.13"
+    "typedoc": "^0.25.13",
+    "typescript": "~5.4.5"
   },
   "dependencies": {
     "base64-js": "^1.3.0",

src/FlagStore.js

@@ -0,0 +1,144 @@
+const utils = require('./utils');
+
+/**
+ * FlagStore - Centralized flag store and access point for all feature flags
+ *
+ * This module manages two types of feature flags:
+ * 1. Regular flags - Retrieved from LaunchDarkly servers or bootstrap data
+ * 2. Override flags - Local overrides for debugging/testing
+ *
+ * When a flag is requested:
+ * - If an override exists for that flag, the override value is returned
+ * - Otherwise, the regular flag value is returned
+ */
+function FlagStore() {
+  let flags = {};
+  // The flag overrides are set lazily to allow bypassing property checks when no overrides are present.
+  let flagOverrides;
+
+  /**
+   * Gets a single flag by key, with overrides taking precedence over regular flags
+   * @param {string} key The flag key to retrieve
+   * @returns {Object|null} The flag object or null if not found
+   */
+  function get(key) {
+    // Check overrides first, then real flags
+    if (flagOverrides && utils.objectHasOwnProperty(flagOverrides, key) && flagOverrides[key]) {
+      return flagOverrides[key];
+    }
+
+    if (flags && utils.objectHasOwnProperty(flags, key) && flags[key] && !flags[key].deleted) {
+      return flags[key];
+    }
+
+    return null;
+  }
+
+  /**
+   * Gets all flags with overrides applied
+   * @returns {Object} Object containing all flags with any overrides applied
+   */
+  function getFlagsWithOverrides() {
+    const result = {};
+
+    // Add all flags first
+    for (const key in flags) {
+      const flag = get(key);
+      if (flag) {
+        result[key] = flag;
+      }
+    }
+
+    // Override with any flagOverrides (they take precedence)
+    if (flagOverrides) {
+      for (const key in flagOverrides) {
+        const override = get(key);
+        if (override) {
+          result[key] = override;
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Replaces all flags with new flag data
+   * @param {Object} newFlags - Object containing the new flag data
+   */
+  function setFlags(newFlags) {
+    flags = { ...newFlags };
+  }
+
+  /**
+   * Sets an override value for a specific flag
+   * @param {string} key The flag key to override
+   * @param {*} value The override value for the flag
+   */
+  function setOverride(key, value) {
+    if (!flagOverrides) {
+      flagOverrides = {};
+    }
+    flagOverrides[key] = { value };
+  }
+
+  /**
+   * Removes an override for a specific flag
+   * @param {string} key The flag key to remove the override for
+   */
+  function removeOverride(key) {
+    if (!flagOverrides || !flagOverrides[key]) {
+      return; // No override to remove
+    }
+
+    delete flagOverrides[key];
+
+    // If no more overrides, reset to undefined for performance
+    if (Object.keys(flagOverrides).length === 0) {
+      flagOverrides = undefined;
+    }
+  }
+
+  /**
+   * Clears all flag overrides and returns the cleared overrides
+   * @returns {Object} The overrides that were cleared, useful for tracking what was removed
+   */
+  function clearAllOverrides() {
+    if (!flagOverrides) {
+      return {}; // No overrides to clear, return empty object for consistency
+    }
+
+    const clearedOverrides = { ...flagOverrides };
+    flagOverrides = undefined; // Reset to undefined
+    return clearedOverrides;
+  }
+
+  /**
+   * Gets the internal flag state without overrides applied
+   * @returns {Object} The internal flag data structure
+   */
+  function getFlags() {
+    return flags;
+  }
+
+  /**
+   * Gets the flag overrides data
+   * @returns {Object} The flag overrides object, or empty object if no overrides exist
+   */
+  function getFlagOverrides() {
+    return flagOverrides || {};
+  }
+
+  return {
+    clearAllOverrides,
+    get,
+    getFlagOverrides,
+    getFlags,
+    getFlagsWithOverrides,
+    removeOverride,
+    setFlags,
+    setOverride,
+  };
+}
+
+module.exports = FlagStore;