flagsmith-nodejs 5.1.0 → 6.0.0

package/sdk/types.ts

@@ -3,6 +3,7 @@ import { EnvironmentModel } from '../flagsmith-engine/index.js';
 import { Dispatcher } from 'undici-types';
 import { Logger } from 'pino';
 import { BaseOfflineHandler } from './offline_handlers.js';
+import { Flagsmith } from './index.js'
 
 export type IFlagsmithValue<T = string | number | boolean | null> = T;
 
@@ -27,22 +28,92 @@ export interface FlagsmithCache {
 
 export type Fetch = typeof fetch
 
+/**
+ * The configuration options for a {@link Flagsmith} client.
+ */
 export interface FlagsmithConfig {
+    /**
+     * The environment's client-side or server-side key.
+     */
     environmentKey?: string;
+    /**
+     * The Flagsmith API URL. Set this if you are not using Flagsmith's public service, i.e. https://app.flagsmith.com.
+     *
+     * @default https://edge.api.flagsmith.com/api/v1/
+     */
     apiUrl?: string;
+    /**
+     * A custom {@link Dispatcher} to use when making HTTP requests.
+     */
     agent?: Dispatcher;
+    /**
+     * A custom {@link fetch} implementation to use when making HTTP requests.
+     */
     fetch?: Fetch;
-    customHeaders?: { [key: string]: any };
+    /**
+     * Custom headers to use in all HTTP requests.
+     */
+    customHeaders?: HeadersInit
+    /**
+     * The network request timeout duration, in seconds.
+     *
+     * @default 10
+     */
     requestTimeoutSeconds?: number;
+    /**
+     * The amount of time, in milliseconds, to wait before retrying failed network requests.
+     */
+    requestRetryDelayMilliseconds?: number;
+    /**
+     * If enabled, flags are evaluated locally using the environment state cached in memory.
+     *
+     * The client will lazily fetch the environment from the Flagsmith API, and poll it every {@link environmentRefreshIntervalSeconds}.
+     */
     enableLocalEvaluation?: boolean;
+    /**
+     * The time, in seconds, to wait before refreshing the cached environment state.
+     * @default 60
+     */
     environmentRefreshIntervalSeconds?: number;
+    /**
+     * How many times to retry any failed network request before giving up.
+     * @default 3
+     */
     retries?: number;
+    /**
+     * If enabled, the client will keep track of any flags evaluated using {@link Flags.isFeatureEnabled},
+     * {@link Flags.getFeatureValue} or {@link Flags.getFlag}, and periodically flush this data to the Flagsmith API.
+     */
     enableAnalytics?: boolean;
-    defaultFlagHandler?: (featureName: string) => DefaultFlag;
+    /**
+     * Used to return fallback values for flags when evaluation fails for any reason. If not provided and flag
+     * evaluation fails, an error will be thrown intsead.
+     *
+     * @param flagKey The key of the flag that failed to evaluate.
+     *
+     * @example
+     * // All flags disabled and with no value by default
+     * const defaultHandler = () => new DefaultFlag(undefined, false)
+     *
+     * // Enable only VIP flags by default
+     * const vipDefaultHandler = (key: string) => new Default(undefined, key.startsWith('vip_'))
+     */
+    defaultFlagHandler?: (flagKey: string) => DefaultFlag;
     cache?: FlagsmithCache;
-    onEnvironmentChange?: (error: Error | null, result: EnvironmentModel) => void;
+    /**
+     * A callback function to invoke whenever the cached environment is updated.
+     * @param error The error that occurred when the environment state failed to update, if any.
+     * @param result The updated environment state, if no error was thrown.
+     */
+    onEnvironmentChange?: (error: Error | null, result?: EnvironmentModel) => void;
     logger?: Logger;
+    /**
+     * If enabled, the client will work offline and not make any network requests. Requires {@link offlineHandler}.
+     */
     offlineMode?: boolean;
+    /**
+     * If {@link offlineMode} is enabled, this handler is used to calculate the values of all flags.
+     */
     offlineHandler?: BaseOfflineHandler;
 }
 

package/sdk/utils.ts

@@ -46,25 +46,59 @@ export const retryFetch = (
     fetchOptions: RequestInit & { dispatcher?: Dispatcher },
     retries: number = 3,
     timeoutMs: number = 10, // set an overall timeout for this function
+    retryDelayMs: number = 1000,
     customFetch: Fetch,
 ): Promise<Response> => {
-    return new Promise((resolve, reject) => {
-        const retryWrapper = (n: number) => {
-            customFetch(url, {
+    const retryWrapper = async (n: number): Promise<Response> => {
+        try {
+            return await customFetch(url, {
                 ...fetchOptions,
                 signal: AbortSignal.timeout(timeoutMs)
-            })
-            .then(res => resolve(res))
-            .catch(async err => {
-                if (n > 0) {
-                    await delay(1000);
-                    retryWrapper(--n);
-                } else {
-                    reject(err);
-                }
             });
-        };
-
-        retryWrapper(retries);
-    });
+        } catch (e) {
+            if (n > 0) {
+                await delay(retryDelayMs);
+                return await retryWrapper(n - 1);
+            } else {
+                throw e;
+            }
+        }
+    };
+    return retryWrapper(retries);
 };
+
+/**
+ * A deferred promise can be resolved or rejected outside its creation scope.
+ *
+ * @template T The type of the value that the deferred promise will resolve to.
+ *
+ * @example
+ * const deferred = new Deferred<string>()
+ *
+ * // Pass the promise somewhere
+ * performAsyncOperation(deferred.promise)
+ *
+ * // Resolve it when ready from anywhere
+ * deferred.resolve("Operation completed")
+ * deferred.failed("Error")
+ */
+export class Deferred<T> {
+    public readonly promise: Promise<T>;
+    private resolvePromise!: (value: T | PromiseLike<T>) => void;
+    private rejectPromise!: (reason?: unknown) => void;
+
+    constructor(initial?: T) {
+        this.promise = new Promise<T>((resolve, reject) => {
+            this.resolvePromise = resolve;
+            this.rejectPromise = reject;
+        });
+    }
+
+    public resolve(value: T | PromiseLike<T>): void {
+        this.resolvePromise(value);
+    }
+
+    public reject(reason?: unknown): void {
+        this.rejectPromise(reason);
+    }
+}

package/tests/sdk/analytics.test.ts

@@ -1,9 +1,5 @@
 import {analyticsProcessor, fetch} from './utils.js';
 
-afterEach(() => {
-    vi.resetAllMocks();
-});
-
 test('test_analytics_processor_track_feature_updates_analytics_data', () => {
     const aP = analyticsProcessor();
     aP.trackFeature("myFeature");

package/tests/sdk/flagsmith-cache.test.ts

@@ -1,12 +1,6 @@
 import { fetch, environmentJSON, environmentModel, flagsJSON, flagsmith, identitiesJSON, TestCache } from './utils.js';
 
-beforeEach(() => {
-  vi.clearAllMocks();
-});
-
 test('test_empty_cache_not_read_but_populated', async () => {
-  fetch.mockResolvedValue(new Response(flagsJSON));
-
   const cache = new TestCache();
   const set = vi.spyOn(cache, 'set');
 
@@ -23,8 +17,6 @@ test('test_empty_cache_not_read_but_populated', async () => {
 });
 
 test('test_api_not_called_when_cache_present', async () => {
-  fetch.mockResolvedValue(new Response(flagsJSON));
-
   const cache = new TestCache();
   const set = vi.spyOn(cache, 'set');
 
@@ -56,27 +48,25 @@ test('test_api_called_twice_when_no_cache', async () => {
 });
 
 test('test_get_environment_flags_uses_local_environment_when_available', async () => {
-  fetch.mockResolvedValue(new Response(flagsJSON));
-
   const cache = new TestCache();
   const set = vi.spyOn(cache, 'set');
 
-  const flg = flagsmith({ cache });
+  const flg = flagsmith({ cache, environmentKey: 'ser.key', enableLocalEvaluation: true });
   const model = environmentModel(JSON.parse(environmentJSON));
-  flg.environment = model;
+  const getEnvironment = vi.spyOn(flg, 'getEnvironment')
+  getEnvironment.mockResolvedValue(model)
 
-  const allFlags = await (await flg.getEnvironmentFlags()).allFlags();
+  const allFlags = (await flg.getEnvironmentFlags()).allFlags();
 
   expect(set).toBeCalled();
   expect(fetch).toBeCalledTimes(0);
+  expect(getEnvironment).toBeCalledTimes(1);
   expect(allFlags[0].enabled).toBe(model.featureStates[0].enabled);
   expect(allFlags[0].value).toBe(model.featureStates[0].getValue());
   expect(allFlags[0].featureName).toBe(model.featureStates[0].feature.name);
 });
 
 test('test_cache_used_for_identity_flags', async () => {
-  fetch.mockResolvedValue(new Response(identitiesJSON));
-
   const cache = new TestCache();
   const set = vi.spyOn(cache, 'set');
 
@@ -98,8 +88,6 @@ test('test_cache_used_for_identity_flags', async () => {
 });
 
 test('test_cache_used_for_identity_flags_local_evaluation', async () => {
-  fetch.mockResolvedValue(new Response(environmentJSON));
-
   const cache = new TestCache();
   const set = vi.spyOn(cache, 'set');
 

package/tests/sdk/flagsmith-environment-flags.test.ts

@@ -4,13 +4,7 @@ import { DefaultFlag } from '../../sdk/models.js';
 
 vi.mock('../../sdk/polling_manager');
 
-beforeEach(() => {
-    vi.clearAllMocks();
-});
-
 test('test_get_environment_flags_calls_api_when_no_local_environment', async () => {
-  fetch.mockResolvedValue(new Response(flagsJSON));
-
   const flg = flagsmith();
   const allFlags = await (await flg.getEnvironmentFlags()).allFlags();
 
@@ -20,20 +14,6 @@ test('test_get_environment_flags_calls_api_when_no_local_environment', async ()
   expect(allFlags[0].featureName).toBe('some_feature');
 });
 
-test('test_get_environment_flags_uses_local_environment_when_available', async () => {
-  fetch.mockResolvedValue(new Response(flagsJSON));
-
-  const flg = flagsmith();
-  const model = environmentModel(JSON.parse(environmentJSON));
-  flg.environment = model;
-
-  const allFlags = await (await flg.getEnvironmentFlags()).allFlags();
-  expect(fetch).toBeCalledTimes(0);
-  expect(allFlags[0].enabled).toBe(model.featureStates[0].enabled);
-  expect(allFlags[0].value).toBe(model.featureStates[0].getValue());
-  expect(allFlags[0].featureName).toBe(model.featureStates[0].feature.name);
-});
-
 test('test_default_flag_is_used_when_no_environment_flags_returned', async () => {
   fetch.mockResolvedValue(new Response(JSON.stringify([])));
 
@@ -57,8 +37,6 @@ test('test_default_flag_is_used_when_no_environment_flags_returned', async () =>
 });
 
 test('test_analytics_processor_tracks_flags', async () => {
-  fetch.mockResolvedValue(new Response(flagsJSON));
-
   const defaultFlag = new DefaultFlag('some-default-value', true);
 
   const defaultFlagHandler = (featureName: string) => defaultFlag;
@@ -78,8 +56,6 @@ test('test_analytics_processor_tracks_flags', async () => {
 });
 
 test('test_getFeatureValue', async () => {
-  fetch.mockResolvedValue(new Response(flagsJSON));
-
   const defaultFlag = new DefaultFlag('some-default-value', true);
 
   const defaultFlagHandler = (featureName: string) => defaultFlag;
@@ -106,7 +82,7 @@ test('test_throws_when_no_default_flag_handler_after_multiple_API_errors', async
   await expect(async () => {
       const flags = await flg.getEnvironmentFlags();
       const flag = flags.getFlag('some_feature');
-  }).rejects.toThrow('Error during fetching the API response');
+  }).rejects.toThrow('getEnvironmentFlags failed and no default flag handler was provided');
 });
 
 test('test_non_200_response_raises_flagsmith_api_error', async () => {
@@ -122,8 +98,6 @@ test('test_non_200_response_raises_flagsmith_api_error', async () => {
   await expect(flg.getEnvironmentFlags()).rejects.toThrow();
 });
 test('test_default_flag_is_not_used_when_environment_flags_returned', async () => {
-  fetch.mockResolvedValue(new Response(flagsJSON));
-
   const defaultFlag = new DefaultFlag('some-default-value', true);
 
   const defaultFlagHandler = (featureName: string) => defaultFlag;
@@ -161,8 +135,6 @@ test('test_default_flag_is_used_when_bad_api_response_happens', async () => {
 });
 
 test('test_local_evaluation', async () => {
-  fetch.mockResolvedValue(new Response(environmentJSON));
-
   const defaultFlag = new DefaultFlag('some-default-value', true);
 
   const defaultFlagHandler = (featureName: string) => defaultFlag;

package/tests/sdk/flagsmith-identity-flags.test.ts

@@ -1,16 +1,18 @@
 import Flagsmith from '../../sdk/index.js';
-import { fetch, environmentJSON, flagsmith, identitiesJSON, identityWithTransientTraitsJSON, transientIdentityJSON } from './utils.js';
+import {
+  fetch,
+  environmentJSON,
+  flagsmith,
+  identitiesJSON,
+  identityWithTransientTraitsJSON,
+  transientIdentityJSON,
+  badFetch
+} from './utils.js';
 import { DefaultFlag } from '../../sdk/models.js';
 
 vi.mock('../../sdk/polling_manager');
 
-beforeEach(() => {
-  vi.clearAllMocks();
-});
-
-
 test('test_get_identity_flags_calls_api_when_no_local_environment_no_traits', async () => {
-  fetch.mockResolvedValue(new Response(identitiesJSON));
   const identifier = 'identifier';
 
   const flg = flagsmith();
@@ -23,7 +25,6 @@ test('test_get_identity_flags_calls_api_when_no_local_environment_no_traits', as
 });
 
 test('test_get_identity_flags_uses_environment_when_local_environment_no_traits', async () => {
-  fetch.mockResolvedValue(new Response(environmentJSON))
   const identifier = 'identifier';
 
   const flg = flagsmith({
@@ -40,7 +41,6 @@ test('test_get_identity_flags_uses_environment_when_local_environment_no_traits'
 });
 
 test('test_get_identity_flags_calls_api_when_no_local_environment_with_traits', async () => {
-  fetch.mockResolvedValue(new Response(identitiesJSON))
   const identifier = 'identifier';
   const traits = { some_trait: 'some_value' };
   const flg = flagsmith();
@@ -53,8 +53,6 @@ test('test_get_identity_flags_calls_api_when_no_local_environment_with_traits',
 });
 
 test('test_default_flag_is_not_used_when_identity_flags_returned', async () => {
-  fetch.mockResolvedValue(new Response(identitiesJSON))
-
   const defaultFlag = new DefaultFlag('some-default-value', true);
 
   const defaultFlagHandler = (featureName: string) => defaultFlag;
@@ -125,7 +123,6 @@ test('test_default_flag_is_used_when_no_identity_flags_returned_and_no_custom_de
   expect(flag.enabled).toBe(false);
 });
 
-
 test('test_get_identity_flags_multivariate_value_with_local_evaluation_enabled', async () => {
   fetch.mockResolvedValue(new Response(environmentJSON));
   const identifier = 'identifier';
@@ -133,7 +130,6 @@ test('test_get_identity_flags_multivariate_value_with_local_evaluation_enabled',
   const flg = flagsmith({
       environmentKey: 'ser.key',
       enableLocalEvaluation: true,
-
   });
 
   const identityFlags = (await flg.getIdentityFlags(identifier))
@@ -170,10 +166,10 @@ test('test_transient_identity', async () => {
 test('test_identity_with_transient_traits', async () => {
   fetch.mockResolvedValue(new Response(identityWithTransientTraitsJSON));
   const identifier = 'transient_trait_identifier';
-  const traits = { 
+  const traits = {
     some_trait: 'some_value',
     another_trait: {value: 'another_value', transient: true},
-    explicitly_non_transient_trait: {value: 'non_transient_value', transient: false} 
+    explicitly_non_transient_trait: {value: 'non_transient_value', transient: false}
   }
   const traitsInRequest = [
     {
@@ -206,3 +202,12 @@ test('test_identity_with_transient_traits', async () => {
   expect(identityFlags[0].value).toBe('some-identity-with-transient-trait-value');
   expect(identityFlags[0].featureName).toBe('some_feature');
 });
+
+test('getIdentityFlags fails if API call failed and no default flag handler was provided', async () => {
+  const flg = flagsmith({
+    fetch: badFetch,
+  })
+  await expect(flg.getIdentityFlags('user'))
+      .rejects
+      .toThrow('getIdentityFlags failed and no default flag handler was provided')
+})