flagsmith-nodejs 5.1.0 → 6.0.0

package/build/cjs/sdk/types.d.ts

@@ -21,24 +21,92 @@ export interface FlagsmithCache {
     set(key: string, value: Flags): Promise<void>;
 }
 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;
 }
 export interface ITraitConfig {

package/build/cjs/sdk/utils.d.ts

@@ -32,5 +32,28 @@ export declare function generateIdentitiesData(identifier: string, traits: Trait
 export declare const delay: (ms: number) => Promise<unknown>;
 export declare const retryFetch: (url: string, fetchOptions: RequestInit & {
     dispatcher?: Dispatcher;
-}, retries: number | undefined, timeoutMs: number | undefined, customFetch: Fetch) => Promise<Response>;
+}, retries: number | undefined, timeoutMs: number | undefined, retryDelayMs: number | undefined, customFetch: Fetch) => Promise<Response>;
+/**
+ * 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 declare class Deferred<T> {
+    readonly promise: Promise<T>;
+    private resolvePromise;
+    private rejectPromise;
+    constructor(initial?: T);
+    resolve(value: T | PromiseLike<T>): void;
+    reject(reason?: unknown): void;
+}
 export {};

package/build/cjs/sdk/utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.retryFetch = exports.delay = exports.generateIdentitiesData = exports.isTraitConfig = void 0;
+exports.Deferred = exports.retryFetch = exports.delay = exports.generateIdentitiesData = exports.isTraitConfig = void 0;
 function isTraitConfig(traitValue) {
     return !!traitValue && typeof traitValue == 'object' && traitValue.value !== undefined;
 }
@@ -39,25 +39,57 @@ exports.delay = delay;
 const retryFetch = (url, 
 // built-in RequestInit type doesn't have dispatcher/agent
 fetchOptions, retries = 3, timeoutMs = 10, // set an overall timeout for this function
-customFetch) => {
-    return new Promise((resolve, reject) => {
-        const retryWrapper = (n) => {
-            customFetch(url, {
+retryDelayMs = 1000, customFetch) => {
+    const retryWrapper = async (n) => {
+        try {
+            return await customFetch(url, {
                 ...fetchOptions,
                 signal: AbortSignal.timeout(timeoutMs)
-            })
-                .then(res => resolve(res))
-                .catch(async (err) => {
-                if (n > 0) {
-                    await (0, exports.delay)(1000);
-                    retryWrapper(--n);
-                }
-                else {
-                    reject(err);
-                }
             });
-        };
-        retryWrapper(retries);
-    });
+        }
+        catch (e) {
+            if (n > 0) {
+                await (0, exports.delay)(retryDelayMs);
+                return await retryWrapper(n - 1);
+            }
+            else {
+                throw e;
+            }
+        }
+    };
+    return retryWrapper(retries);
 };
 exports.retryFetch = retryFetch;
+/**
+ * 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")
+ */
+class Deferred {
+    promise;
+    resolvePromise;
+    rejectPromise;
+    constructor(initial) {
+        this.promise = new Promise((resolve, reject) => {
+            this.resolvePromise = resolve;
+            this.rejectPromise = reject;
+        });
+    }
+    resolve(value) {
+        this.resolvePromise(value);
+    }
+    reject(reason) {
+        this.rejectPromise(reason);
+    }
+}
+exports.Deferred = Deferred;

package/build/esm/sdk/analytics.d.ts

@@ -44,7 +44,7 @@ export declare class AnalyticsProcessor {
     /**
      * Track a single evaluation event for a feature.
      *
-     * This method is called whenever {@link Flags.isFeatureEnabled}, {@link Flags.getFeatureValue} or {@link Flags.getFlag} are called.
+     * @see FlagsmithConfig.enableAnalytics
      */
     trackFeature(featureName: string): void;
 }

package/build/esm/sdk/analytics.js

@@ -64,7 +64,7 @@ export class AnalyticsProcessor {
     /**
      * Track a single evaluation event for a feature.
      *
-     * This method is called whenever {@link Flags.isFeatureEnabled}, {@link Flags.getFeatureValue} or {@link Flags.getFlag} are called.
+     * @see FlagsmithConfig.enableAnalytics
      */
     trackFeature(featureName) {
         this.analyticsData[featureName] = (this.analyticsData[featureName] || 0) + 1;

package/build/esm/sdk/index.d.ts

@@ -11,6 +11,30 @@ export { FlagsmithAPIError, FlagsmithClientError } from './errors.js';
 export { DefaultFlag, Flags } from './models.js';
 export { EnvironmentDataPollingManager } from './polling_manager.js';
 export { FlagsmithCache, FlagsmithConfig } from './types.js';
+/**
+ * A client for evaluating Flagsmith feature flags.
+ *
+ * Flags are evaluated remotely by the Flagsmith API over HTTP by default.
+ * To evaluate flags locally, create the client using {@link FlagsmithConfig.enableLocalEvaluation} and a server-side SDK key.
+ *
+ * @example
+ * import { Flagsmith, Flags, DefaultFlag } from 'flagsmith-nodejs'
+ *
+ * const flagsmith = new Flagsmith({
+ *   environmentKey: 'your_sdk_key',
+ *   defaultFlagHandler: (flagKey: string) => { new DefaultFlag(...) },
+ * });
+ *
+ * // Fetch the current environment flags
+ * const environmentFlags: Flags = flagsmith.getEnvironmentFlags()
+ * const isFooEnabled: boolean = environmentFlags.isFeatureEnabled('foo')
+ *
+ * // Evaluate flags for any identity
+ * const identityFlags: Flags = flagsmith.getIdentityFlags('my_user_123', {'vip': true})
+ * const bannerVariation: string = identityFlags.getFeatureValue('banner_flag')
+ *
+ * @see FlagsmithConfig
+*/
 export declare class Flagsmith {
     environmentKey?: string;
     apiUrl?: string;
@@ -29,53 +53,24 @@ export declare class Flagsmith {
     identitiesUrl?: string;
     environmentUrl?: string;
     environmentDataPollingManager?: EnvironmentDataPollingManager;
-    environment: EnvironmentModel;
+    private environment?;
     offlineMode: boolean;
     offlineHandler?: BaseOfflineHandler;
     identitiesWithOverridesByIdentifier?: Map<string, IdentityModel>;
     private cache?;
-    private onEnvironmentChange?;
+    private onEnvironmentChange;
     private analyticsProcessor?;
     private logger;
     private customFetch;
+    private readonly requestRetryDelayMilliseconds;
     /**
-     * A Flagsmith client.
+     * Creates a new {@link Flagsmith} client.
      *
-     * Provides an interface for interacting with the Flagsmith http API.
-     * Basic Usage::
-     *
-     * import flagsmith from Flagsmith
-     * const flagsmith = new Flagsmith({environmentKey: '<your API key>'});
-     * const environmentFlags = flagsmith.getEnvironmentFlags();
-     * const featureEnabled = environmentFlags.isFeatureEnabled('foo');
-     * const identityFlags = flagsmith.getIdentityFlags('identifier', {'foo': 'bar'});
-     * const featureEnabledForIdentity = identityFlags.isFeatureEnabled("foo")
-     *
-     *  @param {string} data.environmentKey: The environment key obtained from Flagsmith interface
-     *      Required unless offlineMode is True.
-        @param {string} data.apiUrl: Override the URL of the Flagsmith API to communicate with
-        @param  data.customHeaders: Additional headers to add to requests made to the
-            Flagsmith API
-        @param {number} data.requestTimeoutSeconds: Number of seconds to wait for a request to
-            complete before terminating the request
-        @param {boolean} data.enableLocalEvaluation: Enables local evaluation of flags
-        @param {number} data.environmentRefreshIntervalSeconds: If using local evaluation,
-            specify the interval period between refreshes of local environment data
-        @param {number} data.retries: a urllib3.Retry object to use on all http requests to the
-            Flagsmith API
-        @param {boolean} data.enableAnalytics: if enabled, sends additional requests to the Flagsmith
-            API to power flag analytics charts
-        @param data.defaultFlagHandler: callable which will be used in the case where
-            flags cannot be retrieved from the API or a non-existent feature is
-            requested
-        @param data.logger: an instance of the pino Logger class to use for logging
-        @param {boolean} data.offlineMode: sets the client into offline mode. Relies on offlineHandler for
-            evaluating flags.
-        @param {BaseOfflineHandler} data.offlineHandler: provide a handler for offline logic. Used to get environment
-            document from another source when in offlineMode. Works in place of
-            defaultFlagHandler if offlineMode is not set and using remote evaluation.
-    */
-    constructor(data?: FlagsmithConfig);
+     * If using local evaluation, the environment will be fetched lazily when needed by any method. Polling the
+     * environment for updates will start after {@link environmentRefreshIntervalSeconds} once the client is created.
+     * @param data The {@link FlagsmithConfig} options for this client.
+     */
+    constructor(data: FlagsmithConfig);
     /**
      * Get all the default for flags for the current environment.
      *
@@ -110,10 +105,11 @@ export declare class Flagsmith {
     getIdentitySegments(identifier: string, traits?: {
         [key: string]: any;
     }): Promise<SegmentModel[]>;
+    private fetchEnvironment;
     /**
-     * Updates the environment state for local flag evaluation.
-     * Sets a local promise to prevent race conditions in getIdentityFlags / getIdentitySegments.
-     * You only need to call this if you wish to bypass environmentRefreshIntervalSeconds.
+     * Fetch the latest environment state from the Flagsmith API to use for local flag evaluation.
+     *
+     * If the environment is currently being fetched, calling this method will not cause additional fetches.
      */
     updateEnvironment(): Promise<void>;
     close(): Promise<void>;
@@ -121,7 +117,13 @@ export declare class Flagsmith {
     /**
      * This promise ensures that the environment is retrieved before attempting to locally evaluate.
      */
-    private environmentPromise;
+    private environmentPromise?;
+    /**
+     * Returns the current environment, fetching it from the API if needed.
+     *
+     * Calling this method concurrently while the environment is being fetched will not cause additional requests.
+     */
+    getEnvironment(): Promise<EnvironmentModel>;
     private getEnvironmentFromApi;
     private getEnvironmentFlagsFromDocument;
     private getIdentityFlagsFromDocument;