docs: enhance typings and FlagStore documentation

Added experimental annotations to LDPlugin and LDDebugOverride
interfaces in typings.d.ts.
Add JSDoc comments to all FlagStore functions

Author: pranjal-jately-ld

src/FlagStore.js

@@ -1,9 +1,26 @@
 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]) {
@@ -17,6 +34,10 @@ function FlagStore() {
     return null;
   }
 
+  /**
+   * Gets all flags with overrides applied
+   * @returns {Object} Object containing all flags with any overrides applied
+   */
   function getFlagsWithOverrides() {
     const result = {};
 
@@ -41,17 +62,30 @@ function FlagStore() {
     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
@@ -65,6 +99,10 @@ function FlagStore() {
     }
   }
 
+  /**
+   * 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
@@ -75,10 +113,18 @@ function FlagStore() {
     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 || {};
   }

typings.d.ts

@@ -368,6 +368,9 @@ export interface LDPlugin {
    * This method allows plugins to receive a debug override interface for
    * temporarily overriding flag values during development and testing.
    *
+   * @experimental This interface is experimental and intended for use by LaunchDarkly tools at this time.
+   * The API may change in future versions.
+   *
    * @param debugOverride The debug override interface instance
    */
   registerDebug?(debugOverride: LDDebugOverride): void;
@@ -378,6 +381,9 @@ export interface LDPlugin {
  * This interface provides methods to temporarily override flag values that take
  * precedence over the actual flag values from LaunchDarkly. These overrides are
  * useful for testing, development, and debugging scenarios.
+ *
+ * @experimental This interface is experimental and intended for use by LaunchDarkly tools at this time.
+ * The API may change in future versions.
  */
 export interface LDDebugOverride {
   /**