feat(node-sdk): add static fallback provider

Author: roncohen

packages/node-sdk/README.md

@@ -256,11 +256,32 @@ The file provider stores one snapshot file per environment in the configured
 You can also access the built-in providers through the `fallbackProviders`
 namespace:
 
+- `fallbackProviders.static(...)`
 - `fallbackProviders.file(...)`
 - `fallbackProviders.redis(...)`
 - `fallbackProviders.s3(...)`
 - `fallbackProviders.gcs(...)`
 
+#### Built-in static provider
+
+If you just want a fixed fallback copy of simple enabled/disabled flags, you can provide a static map:
+
+```typescript
+import { ReflagClient, fallbackProviders } from "@reflag/node-sdk";
+
+const client = new ReflagClient({
+  secretKey: process.env.REFLAG_SECRET_KEY,
+  flagsFallbackProvider: fallbackProviders.static({
+    flags: {
+      huddle: true,
+      "smart-summaries": false,
+    },
+  }),
+});
+
+await client.initialize();
+```
+
 #### Built-in Redis provider
 
 The built-in Redis provider creates a Redis client automatically when omitted and uses `REDIS_URL` from the environment.
@@ -348,12 +369,14 @@ export const staticFallbackProvider: FlagsFallbackProvider = {
 };
 ```
 
-> [!NOTE] > `fallbackFlags` is deprecated. Prefer `flagsFallbackProvider` for startup fallback and outage recovery.
+> [!NOTE]
+>
+> `fallbackFlags` is deprecated. Prefer `flagsFallbackProvider` for startup fallback and outage recovery.
 > `flagsFallbackProvider` is not used in offline mode.
 
 ## Bootstrapping client-side applications
 
-The `getFlagsForBootstrap()` method is designed for server-side rendering (SSR) scenarios where you need to pass flag data to client-side applications. This method returns raw flag data without wrapper functions, making it suitable for serialization and client-side hydration.
+The `getFlagsForBootstrap()` method is useful whenever you need to pass flag data to another runtime or serialize it without wrapper functions. Server-side rendering (SSR) is a common example, but it is also useful for other bootstrapping and hydration flows.
 
 ```typescript
 const client = new ReflagClient();
@@ -556,7 +579,9 @@ current working directory.
 | `flagsFallbackProvider` | `FlagsFallbackProvider` | Optional provider used to load and save raw flag definitions for fallback startup when the initial live fetch fails. Available only through the constructor. Ignored in offline mode.                                                               | -                                           |
 | `configFile`            | string                  | Load this config file from disk. Default: `reflag.config.json`                                                                                                                                                                                      | REFLAG_CONFIG_FILE                          |
 
-> [!NOTE] > `REFLAG_FLAGS_ENABLED` and `REFLAG_FLAGS_DISABLED` are comma separated lists of flags which will be enabled or disabled respectively.
+> [!NOTE]
+>
+> `REFLAG_FLAGS_ENABLED` and `REFLAG_FLAGS_DISABLED` are comma separated lists of flags which will be enabled or disabled respectively.
 
 `reflag.config.json` example:
 

packages/node-sdk/src/flagsFallbackProvider.ts

@@ -83,6 +83,13 @@ export type RedisFallbackProviderOptions = {
   keyPrefix?: string;
 };
 
+export type StaticFallbackProviderOptions = {
+  /**
+   * Static fallback flags keyed by flag key.
+   */
+  flags: Record<string, boolean>;
+};
+
 function defaultSnapshotName(secretKeyHash: string) {
   return `flags-fallback-${secretKeyHash.slice(0, 16)}.json`;
 }
@@ -162,6 +169,24 @@ function parseSnapshot(raw: string) {
   return isFlagsFallbackSnapshot(parsed) ? parsed : undefined;
 }
 
+function staticFlagApiResponse(key: string, isEnabled: boolean): FlagAPIResponse {
+  return {
+    key,
+    description: null,
+    targeting: {
+      version: 1,
+      rules: [
+        {
+          filter: {
+            type: "constant",
+            value: isEnabled,
+          },
+        },
+      ],
+    },
+  };
+}
+
 async function createDefaultS3Client() {
   const { S3Client } = await import("@aws-sdk/client-s3");
   return new S3Client({});
@@ -172,6 +197,26 @@ async function createDefaultGCSClient() {
   return new Storage();
 }
 
+export function createStaticFallbackProvider({
+  flags,
+}: StaticFallbackProviderOptions): FlagsFallbackProvider {
+  return {
+    async load() {
+      return {
+        version: 1,
+        savedAt: new Date().toISOString(),
+        flags: Object.entries(flags).map(([key, isEnabled]) =>
+          staticFlagApiResponse(key, isEnabled),
+        ),
+      };
+    },
+
+    async save() {
+      // no-op
+    },
+  };
+}
+
 export function createFileFallbackProvider({
   directory,
 }: FileFallbackProviderOptions = {}): FlagsFallbackProvider {

packages/node-sdk/src/index.ts

@@ -3,6 +3,7 @@ import {
   createGCSFallbackProvider,
   createRedisFallbackProvider,
   createS3FallbackProvider,
+  createStaticFallbackProvider,
 } from "./flagsFallbackProvider";
 
 export { BoundReflagClient, ReflagClient } from "./client";
@@ -12,9 +13,11 @@ export type {
   GCSFallbackProviderOptions,
   RedisFallbackProviderOptions,
   S3FallbackProviderOptions,
+  StaticFallbackProviderOptions,
 } from "./flagsFallbackProvider";
 
 export const fallbackProviders = {
+  static: createStaticFallbackProvider,
   file: createFileFallbackProvider,
   redis: createRedisFallbackProvider,
   s3: createS3FallbackProvider,

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

@@ -36,6 +36,52 @@ describe("flagsFallbackProvider", () => {
     }
   });
 
+  it("loads static snapshots from a flag map", async () => {
+    const provider = fallbackProviders.static({
+      flags: {
+        "flag-1": true,
+        "flag-2": false,
+      },
+    });
+
+    await expect(provider.load(context)).resolves.toEqual({
+      version: 1,
+      savedAt: expect.any(String),
+      flags: [
+        {
+          key: "flag-1",
+          description: null,
+          targeting: {
+            version: 1,
+            rules: [
+              {
+                filter: {
+                  type: "constant",
+                  value: true,
+                },
+              },
+            ],
+          },
+        },
+        {
+          key: "flag-2",
+          description: null,
+          targeting: {
+            version: 1,
+            rules: [
+              {
+                filter: {
+                  type: "constant",
+                  value: false,
+                },
+              },
+            ],
+          },
+        },
+      ],
+    });
+  });
+
   it("loads undefined when a file snapshot does not exist", async () => {
     tempDir = await mkdtemp(path.join(os.tmpdir(), "reflag-node-sdk-"));
     const provider = fallbackProviders.file({ directory: tempDir });