feat: add ability to bootstrap flags on server and populate clients

Author: Swiftwork

packages/browser-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reflag/browser-sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "packageManager": "yarn@4.1.1",
   "license": "MIT",
   "repository": {

packages/browser-sdk/src/client.ts

@@ -10,6 +10,7 @@ import * as feedbackLib from "./feedback/ui";
 import {
   CheckEvent,
   FallbackFlagOverride,
+  FetchedFlags,
   FlagsClient,
   RawFlags,
 } from "./flag/flags";
@@ -238,6 +239,12 @@ export type InitOptions = {
    */
   offline?: boolean;
 
+  /**
+   * An object containing pre-fetched flags to be used instead of fetching them from the server.
+   * This is intended to be used with the Node-SDK getFlagsForBootstrap method.
+   */
+  flags?: FetchedFlags;
+
   /**
    * Flag keys for which `isEnabled` should fallback to true
    * if SDK fails to fetch flags from Reflag servers. If a record
@@ -431,6 +438,7 @@ export class ReflagClient {
       },
       this.logger,
       {
+        flags: opts.flags,
         expireTimeMs: opts.expireTimeMs,
         staleTimeMs: opts.staleTimeMs,
         fallbackFlags: opts.fallbackFlags,
@@ -482,8 +490,10 @@ export class ReflagClient {
    * Initialize the Reflag SDK.
    *
    * Must be called before calling other SDK methods.
+   *
+   * @param bootstrap - Whether to bootstrap the client, fetching flags, sending user, and company events.
    */
-  async initialize() {
+  async initialize(bootstrap = true) {
     const start = Date.now();
     if (this.autoFeedback) {
       // do not block on automated feedback surveys initialization
@@ -492,17 +502,20 @@ export class ReflagClient {
       });
     }
 
-    await this.flagsClient.initialize();
-    if (this.context.user && this.config.enableTracking) {
-      this.user().catch((e) => {
-        this.logger.error("error sending user", e);
-      });
-    }
+    if (bootstrap) {
+      await this.flagsClient.initialize();
 
-    if (this.context.company && this.config.enableTracking) {
-      this.company().catch((e) => {
-        this.logger.error("error sending company", e);
-      });
+      if (this.context.user && this.config.enableTracking) {
+        this.user().catch((e) => {
+          this.logger.error("error sending user", e);
+        });
+      }
+
+      if (this.context.company && this.config.enableTracking) {
+        this.company().catch((e) => {
+          this.logger.error("error sending company", e);
+        });
+      }
     }
 
     this.logger.info(

packages/browser-sdk/src/flag/flags.ts

@@ -68,9 +68,6 @@ export type FetchedFlag = {
 
 const FLAGS_UPDATED_EVENT = "flagsUpdated";
 
-/**
- * @internal
- */
 export type FetchedFlags = Record<string, FetchedFlag | undefined>;
 
 export type RawFlag = FetchedFlag & {
@@ -176,7 +173,7 @@ export interface CheckEvent {
   missingContextFields?: string[];
 }
 
-type context = {
+type Context = {
   user?: Record<string, any>;
   company?: Record<string, any>;
   other?: Record<string, any>;
@@ -207,8 +204,9 @@ function getOverridesCache(): OverridesFlags {
  * @internal
  */
 export class FlagsClient {
+  private initialized = false;
   private cache: FlagCache;
-  private fetchedFlags: FetchedFlags;
+  private fetchedFlags: FetchedFlags = {};
   private flagOverrides: OverridesFlags = {};
 
   private flags: RawFlags = {};
@@ -222,9 +220,10 @@ export class FlagsClient {
 
   constructor(
     private httpClient: HttpClient,
-    private context: context,
+    private context: Context,
     logger: Logger,
     options?: {
+      flags?: FetchedFlags;
       fallbackFlags?: Record<string, FallbackFlagOverride> | string[];
       timeoutMs?: number;
       staleTimeMs?: number;
@@ -234,7 +233,6 @@ export class FlagsClient {
       offline?: boolean;
     },
   ) {
-    this.fetchedFlags = {};
     this.logger = loggerWithPrefix(logger, "[Flags]");
     this.cache = options?.cache
       ? options.cache
@@ -280,14 +278,22 @@ export class FlagsClient {
       this.logger.warn("error getting flag overrides from cache", e);
       this.flagOverrides = {};
     }
+
+    if (options?.flags) {
+      this.initialized = true;
+      this.fetchedFlags = options.flags;
+      this.flags = this.mergeFlags(this.fetchedFlags, this.flagOverrides);
+    }
   }
 
   async initialize() {
-    const flags = (await this.maybeFetchFlags()) || {};
-    this.setFetchedFlags(flags);
+    if (!this.initialized) {
+      this.initialized = true;
+      this.setFetchedFlags((await this.maybeFetchFlags()) || {});
+    }
   }
 
-  async setContext(context: context) {
+  async setContext(context: Context) {
     this.context = context;
     await this.initialize();
   }
@@ -397,21 +403,20 @@ export class FlagsClient {
     return checkEvent.value;
   }
 
-  private triggerFlagsUpdated() {
+  private mergeFlags(fetchedFlags: FetchedFlags, overrides: OverridesFlags) {
     const mergedFlags: RawFlags = {};
-
     // merge fetched flags with overrides into `this.flags`
-    for (const key in this.fetchedFlags) {
-      const fetchedFlag = this.fetchedFlags[key];
+    for (const key in fetchedFlags) {
+      const fetchedFlag = fetchedFlags[key];
       if (!fetchedFlag) continue;
-      const isEnabledOverride = this.flagOverrides[key] ?? null;
-      mergedFlags[key] = {
-        ...fetchedFlag,
-        isEnabledOverride,
-      };
+      const isEnabledOverride = overrides[key] ?? null;
+      mergedFlags[key] = { ...fetchedFlag, isEnabledOverride };
     }
+    return mergedFlags;
+  }
 
-    this.flags = mergedFlags;
+  private triggerFlagsUpdated() {
+    this.flags = this.mergeFlags(this.fetchedFlags, this.flagOverrides);
 
     this.eventTarget.dispatchEvent(new Event(FLAGS_UPDATED_EVENT));
   }

packages/browser-sdk/src/index.ts

@@ -32,6 +32,7 @@ export type {
   CheckEvent,
   FallbackFlagOverride,
   FetchedFlag,
+  FetchedFlags,
   RawFlag,
   RawFlags,
 } from "./flag/flags";

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

@@ -171,4 +171,114 @@ describe("ReflagClient", () => {
       expect(httpClientGet).not.toHaveBeenCalled();
     });
   });
+
+  describe("bootstrap parameter", () => {
+    const flagsClientInitialize = vi.spyOn(FlagsClient.prototype, "initialize");
+
+    beforeEach(() => {
+      flagsClientInitialize.mockClear();
+    });
+
+    it("should skip flagsClient.initialize() when bootstrap is false", async () => {
+      client = new ReflagClient({
+        publishableKey: "test-key",
+        user: { id: "user1" },
+        company: { id: "company1" },
+        feedback: { enableAutoFeedback: false }, // Disable to avoid HTTP calls
+      });
+
+      await client.initialize(false);
+
+      expect(flagsClientInitialize).not.toHaveBeenCalled();
+      expect(httpClientPost).not.toHaveBeenCalled(); // No user/company tracking
+    });
+
+    it("should use pre-fetched flags and skip initialization when flags are provided", async () => {
+      const preFetchedFlags = {
+        testFlag: {
+          key: "testFlag",
+          isEnabled: true,
+          targetingVersion: 1,
+        },
+      };
+
+      // Create a spy to monitor maybeFetchFlags which should not be called if already initialized
+      const maybeFetchFlags = vi.spyOn(
+        FlagsClient.prototype as any,
+        "maybeFetchFlags",
+      );
+
+      client = new ReflagClient({
+        publishableKey: "test-key",
+        user: { id: "user1" },
+        company: { id: "company1" },
+        flags: preFetchedFlags,
+        feedback: { enableAutoFeedback: false }, // Disable to avoid HTTP calls
+      });
+
+      // FlagsClient should be initialized in constructor when flags are provided
+      expect(client["flagsClient"]["initialized"]).toBe(true);
+      expect(client.getFlags()).toEqual({
+        testFlag: {
+          key: "testFlag",
+          isEnabled: true,
+          targetingVersion: 1,
+          isEnabledOverride: null,
+        },
+      });
+
+      maybeFetchFlags.mockClear();
+
+      await client.initialize();
+
+      // maybeFetchFlags should not be called since flagsClient is already initialized
+      expect(maybeFetchFlags).not.toHaveBeenCalled();
+    });
+
+    it("should combine pre-fetched flags with bootstrap=false correctly", async () => {
+      const preFetchedFlags = {
+        testFlag: {
+          key: "testFlag",
+          isEnabled: true,
+          targetingVersion: 1,
+          config: {
+            key: "config1",
+            version: 1,
+            payload: { value: "test" },
+          },
+        },
+      };
+
+      client = new ReflagClient({
+        publishableKey: "test-key",
+        user: { id: "user1" },
+        company: { id: "company1" },
+        flags: preFetchedFlags,
+        feedback: { enableAutoFeedback: false }, // Disable to avoid HTTP calls
+      });
+
+      await client.initialize(false);
+
+      // Should not call flagsClient.initialize() because bootstrap is false
+      expect(flagsClientInitialize).not.toHaveBeenCalled();
+      // Should not make any HTTP calls for user/company tracking
+      expect(httpClientPost).not.toHaveBeenCalled();
+      // Should have the pre-fetched flags available
+      expect(client.getFlags()).toEqual({
+        testFlag: {
+          key: "testFlag",
+          isEnabled: true,
+          targetingVersion: 1,
+          config: {
+            key: "config1",
+            version: 1,
+            payload: { value: "test" },
+          },
+          isEnabledOverride: null,
+        },
+      });
+      // Should be able to use the flag
+      expect(client.getFlag("testFlag").isEnabled).toBe(true);
+    });
+  });
 });