Clarify scoped and base flag override APIs

Author: roncohen

packages/node-sdk/README.md

@@ -565,19 +565,19 @@ REFLAG_FLAGS_DISABLED=flag3,flag4
 
 1. Programmatically through the client options:
 
-You can use a simple `Record<string, boolean>` and pass it either in the constructor or by setting `client.flagOverrides`:
+You can use a simple `Record<string, boolean>` and pass it either in the constructor or by replacing the client's base overrides with `setFlagOverrides()`:
 
 ```typescript
 // pass directly in the constructor
 const client = new ReflagClient({ flagOverrides: { myFlag: true } });
-// or set on the client at a later time
-client.flagOverrides = { myFlag: false };
+// or replace the base overrides at a later time
+client.setFlagOverrides({ myFlag: false });
 
-// clear flag overrides. Same as setting to {}.
+// clear only the base overrides
 client.clearFlagOverrides();
 ```
 
-For nested or temporary test overrides, use `pushFlagOverrides()`. It layers on top of the current overrides and returns a restore function that removes only that layer. You can wrap that in a small helper:
+`pushFlagOverrides()` serves a different purpose: it adds a temporary layer on top of the base overrides and returns a restore function that removes only that layer. This is useful for nested tests:
 
 ```typescript
 export const flag = function (name: string, enabled: boolean): void {
@@ -606,6 +606,13 @@ describe("foo", () => {
 });
 ```
 
+The precedence is:
+
+1. Base overrides from the constructor or `setFlagOverrides()`
+2. Temporary layers added by `pushFlagOverrides()`
+
+If the same flag is set in both places, the pushed override wins until its restore function is called.
+
 To get dynamic overrides, use a function which takes a context and returns a boolean or an object with the shape of `{isEnabled, config}`:
 
 ```typescript

packages/node-sdk/src/client.ts

@@ -416,28 +416,35 @@ export class ReflagClient {
   }
 
   /**
-   * Sets the flag overrides.
+   * Replaces the base flag overrides used by the client.
    *
    * @param overrides - The flag overrides.
    *
    * @remarks
-   * The flag overrides are used to override the flag definitions.
-   * This is useful for testing or development.
+   * Base overrides are always applied before any temporary layers added through
+   * `pushFlagOverrides()`.
    *
    * @example
    * ```ts
-   * client.flagOverrides = {
+   * client.setFlagOverrides({
    *   "flag-1": true,
    *   "flag-2": false,
-   * };
+   * });
    * ```
    **/
-  set flagOverrides(overrides: FlagOverridesFn | FlagOverrides) {
+  setFlagOverrides(overrides: FlagOverridesFn | FlagOverrides) {
     this.baseFlagOverrides = normalizeFlagOverrides(overrides);
-    this.flagOverrideLayers = [];
     this.syncFlagOverrides();
   }
 
+  /**
+   * @deprecated
+   * Use `setFlagOverrides()` for replacing the base override set.
+   **/
+  set flagOverrides(overrides: FlagOverridesFn | FlagOverrides) {
+    this.setFlagOverrides(overrides);
+  }
+
   /**
    * Temporarily layers flag overrides on top of the current overrides.
    *
@@ -493,21 +500,18 @@ export class ReflagClient {
   }
 
   /**
-   * Clears the flag overrides.
+   * Clears the base flag overrides.
    *
    * @remarks
-   * This is useful for testing or development.
+   * This does not affect temporary layers added with `pushFlagOverrides()`.
    *
    * @example
    * ```ts
-   * afterAll(() => {
-   *   client.clearFlagOverrides();
-   * });
+   * client.clearFlagOverrides();
    * ```
    **/
   clearFlagOverrides() {
     this.baseFlagOverrides = () => ({});
-    this.flagOverrideLayers = [];
     this.syncFlagOverrides();
   }
 

packages/node-sdk/test/client.test.ts

@@ -1748,7 +1748,7 @@ describe("ReflagClient", () => {
       );
     });
 
-    it("should use flag overrides", async () => {
+    it("should use base flag overrides", async () => {
       await client.initialize();
       const context = { user, company, other: otherContext };
 
@@ -1773,9 +1773,9 @@ describe("ReflagClient", () => {
         },
       });
 
-      client.flagOverrides = {
+      client.setFlagOverrides({
         flag1: false,
-      };
+      });
       const flags = client.getFlags(context);
 
       expect(flags).toStrictEqual({
@@ -1809,7 +1809,7 @@ describe("ReflagClient", () => {
       });
     });
 
-    it("should use flag overrides from function", async () => {
+    it("should use base flag overrides from function", async () => {
       await client.initialize();
       const context = { user, company, other: otherContext };
 
@@ -1834,7 +1834,7 @@ describe("ReflagClient", () => {
         },
       });
 
-      client.flagOverrides = (_context: Context) => {
+      client.setFlagOverrides((_context: Context) => {
         expect(context).toStrictEqual(context);
         return {
           flag1: { isEnabled: false },
@@ -1847,7 +1847,7 @@ describe("ReflagClient", () => {
             },
           },
         };
-      };
+      });
       const flags = client.getFlags(context);
 
       expect(flags).toStrictEqual({
@@ -1911,9 +1911,9 @@ describe("ReflagClient", () => {
       await client.initialize();
       const context = { user, company, other: otherContext };
 
-      client.flagOverrides = () => ({
+      client.setFlagOverrides(() => ({
         flag1: false,
-      });
+      }));
 
       const restore = client.pushFlagOverrides((overrideContext: Context) => {
         expect(overrideContext).toStrictEqual({
@@ -1936,6 +1936,57 @@ describe("ReflagClient", () => {
       expect(client.getFlag(context, "flag1").isEnabled).toBe(false);
       expect(client.getFlag(context, "flag2").isEnabled).toBe(false);
     });
+
+    it("should keep pushed overrides layered on top when replacing base overrides", async () => {
+      await client.initialize();
+      const context = { user, company, other: otherContext };
+
+      client.setFlagOverrides({
+        flag1: false,
+      });
+
+      const restore = client.pushFlagOverrides({
+        flag1: true,
+      });
+
+      expect(client.getFlag(context, "flag1").isEnabled).toBe(true);
+
+      client.setFlagOverrides({
+        flag1: false,
+        flag2: true,
+      });
+
+      expect(client.getFlag(context, "flag1").isEnabled).toBe(true);
+      expect(client.getFlag(context, "flag2").isEnabled).toBe(true);
+
+      restore();
+
+      expect(client.getFlag(context, "flag1").isEnabled).toBe(false);
+      expect(client.getFlag(context, "flag2").isEnabled).toBe(true);
+    });
+
+    it("should only clear the base overrides", async () => {
+      await client.initialize();
+      const context = { user, company, other: otherContext };
+
+      client.setFlagOverrides({
+        flag1: false,
+      });
+
+      const restore = client.pushFlagOverrides({
+        flag2: true,
+      });
+
+      client.clearFlagOverrides();
+
+      expect(client.getFlag(context, "flag1").isEnabled).toBe(true);
+      expect(client.getFlag(context, "flag2").isEnabled).toBe(true);
+
+      restore();
+
+      expect(client.getFlag(context, "flag1").isEnabled).toBe(true);
+      expect(client.getFlag(context, "flag2").isEnabled).toBe(false);
+    });
   });
 
   describe("getFlagsForBootstrap", () => {