allow bootstrapping feature definitions

roncohen · roncohen · commit 7b4417b0b3a5 · 2025-03-26T08:47:18.000+01:00
diff --git a/packages/node-sdk/README.md b/packages/node-sdk/README.md
@@ -146,9 +146,9 @@ const client = new BucketClient({
 });
 ```
 
-### Caching
+### Feature definitions
 
-Feature definitions are automatically cached and refreshed in the background. The cache behavior is configurable:
+Feature definitions include the rules needed to determine which features should be enabled and which config values should be applied to any given user/company. Feature definitions are automatically fetched, cached and refreshed in the background. The cache behavior is configurable:
 
 ```typescript
 const client = new BucketClient({
@@ -157,6 +157,23 @@ const client = new BucketClient({
 });
 ```
 
+It's also possible to load the feature definitions from a local file or similar:
+
+```typescript
+import fs from "fs";
+
+const client = new BucketClient({
+  fetchFeatures: false,
+});
+
+const featureDefs = fs.readFileSync("featureDefs.json");
+
+client.bootstrapFeatureDefinitions(featureDefs);
+client.initialize().then(() => {
+  console.log("Bootstrapped feature definitions");
+});
+```
+
 ## Error Handling
 
 The SDK is designed to fail gracefully and never throw exceptions to the caller. Instead, it logs errors and provides
diff --git a/packages/node-sdk/src/cache.ts b/packages/node-sdk/src/cache.ts
@@ -67,5 +67,10 @@ export default function cache<T>(
     return get();
   };
 
-  return { get, refresh };
+  const set = (value: T) => {
+    cachedValue = value;
+    lastUpdate = Date.now();
+  };
+
+  return { get, refresh, set };
 }
diff --git a/packages/node-sdk/src/client.ts b/packages/node-sdk/src/client.ts
@@ -111,17 +111,18 @@ export class BucketClient {
     staleWarningInterval: number;
     headers: Record<string, string>;
     fallbackFeatures?: Record<keyof TypedFeatures, RawFeature>;
-    featuresCache?: Cache<FeaturesAPIResponse>;
+    featuresCache: Cache<FeaturesAPIResponse>;
     batchBuffer: BatchBuffer<BulkEvent>;
     featureOverrides: FeatureOverridesFn;
     rateLimiter: ReturnType<typeof newRateLimiter>;
     offline: boolean;
+    fetchFeatures: boolean;
     configFile?: string;
   };
 
   private _initialize = once(async () => {
-    if (!this._config.offline) {
-      await this.getFeaturesCache().refresh();
+    if (!this._config.offline && this._config.fetchFeatures) {
+      await this._config.featuresCache.refresh();
     }
     this._config.logger?.info("Bucket initialized");
   });
@@ -256,6 +257,7 @@ export class BucketClient {
       rateLimiter: newRateLimiter(FEATURE_EVENT_RATE_LIMITER_WINDOW_SIZE_MS),
       httpClient: options.httpClient || fetchClient,
       refetchInterval: FEATURES_REFETCH_MS,
+      fetchFeatures: options.fetchFeatures ?? true,
       staleWarningInterval: FEATURES_REFETCH_MS * 5,
       fallbackFeatures: fallbackFeatures,
       batchBuffer: new BatchBuffer<BulkEvent>({
@@ -276,6 +278,21 @@ export class BucketClient {
     if (!new URL(this._config.apiBaseUrl).pathname.endsWith("/")) {
       this._config.apiBaseUrl += "/";
     }
+
+    this._config.featuresCache = cache<FeaturesAPIResponse>(
+      this._config.refetchInterval,
+      this._config.staleWarningInterval,
+      this._config.logger,
+      async () => {
+        const res = await this.get<FeaturesAPIResponse>("features");
+
+        if (!isObject(res) || !Array.isArray(res?.features)) {
+          return undefined;
+        }
+
+        return res;
+      },
+    );
   }
 
   /**
@@ -454,6 +471,18 @@ export class BucketClient {
     });
   }
 
+  /**
+   * Updates the feature definitions cache.
+   *
+   * @param features - The features to cache.
+   *
+   * @remarks
+   * Useful when loading feature definitions from a file or other source.
+   **/
+  public bootstrapFeatureDefinitions(features: FeaturesAPIResponse) {
+    this._config.featuresCache.set(features);
+  }
+
   /**
    * Initializes the client by caching the features definitions.
    *
@@ -854,32 +883,6 @@ export class BucketClient {
     }
   }
 
-  /**
-   * Gets the features cache.
-   *
-   * @returns The features cache.
-   **/
-  private getFeaturesCache() {
-    if (!this._config.featuresCache) {
-      this._config.featuresCache = cache<FeaturesAPIResponse>(
-        this._config.refetchInterval,
-        this._config.staleWarningInterval,
-        this._config.logger,
-        async () => {
-          const res = await this.get<FeaturesAPIResponse>("features");
-
-          if (!isObject(res) || !Array.isArray(res?.features)) {
-            return undefined;
-          }
-
-          return res;
-        },
-      );
-    }
-
-    return this._config.featuresCache;
-  }
-
   /**
    * Warns if any features have targeting rules that require context fields that are missing.
    *
diff --git a/packages/node-sdk/src/types.ts b/packages/node-sdk/src/types.ts
@@ -499,6 +499,11 @@ export type Cache<T> = {
    * @returns The value or `undefined` if the value is not available.
    **/
   refresh: () => Promise<T | undefined>;
+
+  /**
+   * Set the value
+   **/
+  set: (value: T) => void;
 };
 
 /**
@@ -610,6 +615,13 @@ export type ClientOptions = {
    */
   offline?: boolean;
 
+  /**
+   * If set to false, feature definitions will not be fetched from the API when the client is initialized.
+   * Useful if you want to manage feature definitions manually through `bootstrapFeatureDefinitions`.
+   * Defaults to true.
+   */
+  fetchFeatures?: boolean;
+
   /**
    * The path to the config file. If supplied, the config file will be loaded.
    * Defaults to `bucket.json` when NODE_ENV is not production. Can also be
