flagsmith-nodejs 6.0.0 → 6.1.0

package/sdk/analytics.ts

@@ -1,13 +1,13 @@
 import { pino, Logger } from 'pino';
-import { Fetch } from "./types.js";
-import { FlagsmithConfig } from "./types.js";
+import { Fetch } from './types.js';
+import { FlagsmithConfig } from './types.js';
 
 export const ANALYTICS_ENDPOINT = './analytics/flags/';
 
 /** Duration in seconds to wait before trying to flush collected data after {@link trackFeature} is called. **/
 const ANALYTICS_TIMER = 10;
 
-const DEFAULT_REQUEST_TIMEOUT_MS = 3000
+const DEFAULT_REQUEST_TIMEOUT_MS = 3000;
 
 export interface AnalyticsProcessorOptions {
     /** URL of the Flagsmith analytics events API endpoint
@@ -20,7 +20,7 @@ export interface AnalyticsProcessorOptions {
     requestTimeoutMs?: number;
     logger?: Logger;
     /** Custom {@link fetch} implementation to use for API requests. **/
-    fetch?: Fetch
+    fetch?: Fetch;
 
     /** @deprecated Use {@link analyticsUrl} instead. **/
     baseApiUrl?: string;
@@ -76,7 +76,9 @@ export class AnalyticsProcessor {
         } catch (error) {
             // We don't want failing to write analytics to cause any exceptions in the main
             // thread so we just swallow them here.
-            this.logger.warn('Failed to post analytics to Flagsmith API. Not clearing data, will retry.')
+            this.logger.warn(
+                'Failed to post analytics to Flagsmith API. Not clearing data, will retry.'
+            );
             return;
         } finally {
             this.currentFlush = undefined;

package/sdk/index.ts

@@ -1,11 +1,14 @@
 import { Dispatcher } from 'undici-types';
-import { getEnvironmentFeatureStates, getIdentityFeatureStates } from '../flagsmith-engine/index.js';
+import {
+    getEnvironmentFeatureStates,
+    getIdentityFeatureStates
+} from '../flagsmith-engine/index.js';
 import { EnvironmentModel } from '../flagsmith-engine/index.js';
 import { buildEnvironmentModel } from '../flagsmith-engine/environments/util.js';
 import { IdentityModel } from '../flagsmith-engine/index.js';
 import { TraitModel } from '../flagsmith-engine/index.js';
 
-import {ANALYTICS_ENDPOINT, AnalyticsProcessor} from './analytics.js';
+import { ANALYTICS_ENDPOINT, AnalyticsProcessor } from './analytics.js';
 import { BaseOfflineHandler } from './offline_handlers.js';
 import { FlagsmithAPIError } from './errors.js';
 
@@ -14,13 +17,19 @@ import { EnvironmentDataPollingManager } from './polling_manager.js';
 import { Deferred, generateIdentitiesData, retryFetch } from './utils.js';
 import { SegmentModel } from '../flagsmith-engine/index.js';
 import { getIdentitySegments } from '../flagsmith-engine/segments/evaluators.js';
-import { Fetch, FlagsmithCache, FlagsmithConfig, FlagsmithTraitValue, ITraitConfig } from './types.js';
+import {
+    Fetch,
+    FlagsmithCache,
+    FlagsmithConfig,
+    FlagsmithTraitValue,
+    TraitConfig
+} from './types.js';
 import { pino, Logger } from 'pino';
 
 export { AnalyticsProcessor, AnalyticsProcessorOptions } from './analytics.js';
 export { FlagsmithAPIError, FlagsmithClientError } from './errors.js';
 
-export { DefaultFlag, Flags } from './models.js';
+export { BaseFlag, DefaultFlag, Flags } from './models.js';
 export { EnvironmentDataPollingManager } from './polling_manager.js';
 export { FlagsmithCache, FlagsmithConfig } from './types.js';
 
@@ -50,7 +59,7 @@ const DEFAULT_REQUEST_TIMEOUT_SECONDS = 10;
  * const bannerVariation: string = identityFlags.getFeatureValue('banner_flag')
  *
  * @see FlagsmithConfig
-*/
+ */
 export class Flagsmith {
     environmentKey?: string = undefined;
     apiUrl?: string = undefined;
@@ -128,20 +137,23 @@ export class Flagsmith {
 
             const apiUrl = data.apiUrl || DEFAULT_API_URL;
             this.apiUrl = apiUrl.endsWith('/') ? apiUrl : `${apiUrl}/`;
-            this.analyticsUrl = this.analyticsUrl || new URL(ANALYTICS_ENDPOINT, new Request(this.apiUrl).url).href
+            this.analyticsUrl =
+                this.analyticsUrl || new URL(ANALYTICS_ENDPOINT, new Request(this.apiUrl).url).href;
             this.environmentFlagsUrl = `${this.apiUrl}flags/`;
             this.identitiesUrl = `${this.apiUrl}identities/`;
             this.environmentUrl = `${this.apiUrl}environment-document/`;
 
             if (this.enableLocalEvaluation) {
                 if (!this.environmentKey.startsWith('ser.')) {
-                    throw new Error('Using local evaluation requires a server-side environment key');
+                    throw new Error(
+                        'Using local evaluation requires a server-side environment key'
+                    );
                 }
-                if (this.environmentRefreshIntervalSeconds > 0){
+                if (this.environmentRefreshIntervalSeconds > 0) {
                     this.environmentDataPollingManager = new EnvironmentDataPollingManager(
                         this,
                         this.environmentRefreshIntervalSeconds,
-                        this.logger,
+                        this.logger
                     );
                     this.environmentDataPollingManager.start();
                 }
@@ -152,8 +164,8 @@ export class Flagsmith {
                     environmentKey: this.environmentKey,
                     analyticsUrl: this.analyticsUrl,
                     requestTimeoutMs: this.requestTimeoutMs,
-                    logger: this.logger,
-                })
+                    logger: this.logger
+                });
             }
         }
     }
@@ -174,7 +186,10 @@ export class Flagsmith {
             return await this.getEnvironmentFlagsFromApi();
         } catch (error) {
             if (!this.defaultFlagHandler) {
-                throw new Error('getEnvironmentFlags failed and no default flag handler was provided', { cause: error });
+                throw new Error(
+                    'getEnvironmentFlags failed and no default flag handler was provided',
+                    { cause: error }
+                );
             }
             this.logger.error(error, 'getEnvironmentFlags failed');
             return new Flags({
@@ -191,13 +206,13 @@ export class Flagsmith {
      *
      * @param  {string} identifier a unique identifier for the identity in the current
             environment, e.g. email address, username, uuid
-     * @param  {{[key:string]:any | ITraitConfig}} traits? a dictionary of traits to add / update on the identity in
+     * @param  {{[key:string]:any | TraitConfig}} traits? a dictionary of traits to add / update on the identity in
             Flagsmith, e.g. {"num_orders": 10} or {age: {value: 30, transient: true}}
      * @returns Flags object holding all the flags for the given identity.
      */
     async getIdentityFlags(
         identifier: string,
-        traits?: { [key: string]: FlagsmithTraitValue | ITraitConfig },
+        traits?: { [key: string]: FlagsmithTraitValue | TraitConfig },
         transient: boolean = false
     ): Promise<Flags> {
         if (!identifier) {
@@ -216,7 +231,10 @@ export class Flagsmith {
             return await this.getIdentityFlagsFromApi(identifier, traits, transient);
         } catch (error) {
             if (!this.defaultFlagHandler) {
-                throw new Error('getIdentityFlags failed and no default flag handler was provided', { cause: error })
+                throw new Error(
+                    'getIdentityFlags failed and no default flag handler was provided',
+                    { cause: error }
+                );
             }
             this.logger.error(error, 'getIdentityFlags failed');
             return new Flags({
@@ -292,8 +310,8 @@ export class Flagsmith {
     async updateEnvironment(): Promise<void> {
         try {
             if (this.environmentPromise) {
-                await this.environmentPromise
-                return
+                await this.environmentPromise;
+                return;
             }
             const environment = await this.fetchEnvironment();
             this.onEnvironmentChange(null, environment);
@@ -334,7 +352,7 @@ export class Flagsmith {
             this.retries,
             this.requestTimeoutMs,
             this.requestRetryDelayMilliseconds,
-            this.customFetch,
+            this.customFetch
         );
 
         if (data.status !== 200) {
@@ -438,7 +456,7 @@ export class Flagsmith {
 
     private async getIdentityFlagsFromApi(
         identifier: string,
-        traits: { [key: string]: FlagsmithTraitValue | ITraitConfig },
+        traits: { [key: string]: FlagsmithTraitValue | TraitConfig },
         transient: boolean = false
     ) {
         if (!this.identitiesUrl) {
@@ -463,8 +481,7 @@ export class Flagsmith {
         traits: { key: string; value: any }[]
     ) {
         const traitModels = traits.map(trait => new TraitModel(trait.key, trait.value));
-        let identityWithOverrides =
-            this.identitiesWithOverridesByIdentifier?.get(identifier);
+        let identityWithOverrides = this.identitiesWithOverridesByIdentifier?.get(identifier);
         if (identityWithOverrides) {
             identityWithOverrides.updateTraits(traitModels);
             return identityWithOverrides;

package/sdk/models.ts

@@ -1,34 +1,57 @@
 import { FeatureStateModel } from '../flagsmith-engine/features/models.js';
 import { AnalyticsProcessor } from './analytics.js';
 
+type FlagValue = string | number | boolean | undefined;
+
+/**
+ * A Flagsmith feature. It has an enabled/disabled state, and an optional {@link FlagValue}.
+ */
 export class BaseFlag {
+    /**
+     * Indicates whether this feature is enabled.
+     */
     enabled: boolean;
-    value: string | number | boolean | undefined;
+    /**
+     * An optional {@link FlagValue} for this feature.
+     */
+    value: FlagValue;
+    /**
+     * If true, the state for this feature was determined by a default flag handler. See {@link DefaultFlag}.
+     */
     isDefault: boolean;
 
-    constructor(
-        value: string | number | boolean | undefined,
-        enabled: boolean,
-        isDefault: boolean
-    ) {
+    constructor(value: FlagValue, enabled: boolean, isDefault: boolean) {
         this.value = value;
         this.enabled = enabled;
         this.isDefault = isDefault;
     }
 }
 
+/**
+ * A {@link BaseFlag} returned by a default flag handler when flag evaluation fails.
+ * @see FlagsmithConfig#defaultFlagHandler
+ */
 export class DefaultFlag extends BaseFlag {
-    constructor(value: string | number | boolean | undefined, enabled: boolean) {
+    constructor(value: FlagValue, enabled: boolean) {
         super(value, enabled, true);
     }
 }
 
+/**
+ * A Flagsmith feature retrieved from a successful flag evaluation.
+ */
 export class Flag extends BaseFlag {
+    /**
+     * An identifier for this feature, unique in a single Flagsmith installation.
+     */
     featureId: number;
+    /**
+     * The programmatic name for this feature, unique per Flagsmith project.
+     */
     featureName: string;
 
     constructor(params: {
-        value: string | number | boolean | undefined;
+        value: FlagValue;
         enabled: boolean;
         isDefault?: boolean;
         featureId: number;
@@ -82,7 +105,7 @@ export class Flags {
         defaultFlagHandler?: (f: string) => DefaultFlag;
         identityID?: string | number;
     }): Flags {
-        const flags: { [key: string]: any } = {};
+        const flags: { [key: string]: Flag } = {};
         for (const fs of data.featureStates) {
             flags[fs.feature.name] = Flag.fromFeatureStateModel(fs, data.identityID);
         }
@@ -98,7 +121,7 @@ export class Flags {
         analyticsProcessor?: AnalyticsProcessor;
         defaultFlagHandler?: (v: string) => DefaultFlag;
     }): Flags {
-        const flags: { [key: string]: any } = {};
+        const flags: { [key: string]: Flag } = {};
 
         for (const flagData of data.apiFlags) {
             flags[flagData['feature']['name']] = Flag.fromAPIFlag(flagData);
@@ -124,7 +147,6 @@ export class Flags {
             }
 
             return { enabled: false, isDefault: true, value: undefined };
-
         }
 
         if (this.analyticsProcessor && flag.featureId) {
@@ -134,7 +156,7 @@ export class Flags {
         return flag;
     }
 
-    getFeatureValue(featureName: string): any {
+    getFeatureValue(featureName: string): FlagValue {
         return this.getFlag(featureName).value;
     }
 

package/sdk/offline_handlers.ts

@@ -3,7 +3,7 @@ import { buildEnvironmentModel } from '../flagsmith-engine/environments/util.js'
 import { EnvironmentModel } from '../flagsmith-engine/environments/models.js';
 
 export class BaseOfflineHandler {
-    getEnvironment() : EnvironmentModel {
+    getEnvironment(): EnvironmentModel {
         throw new Error('Not implemented');
     }
 }

package/sdk/types.ts

@@ -3,10 +3,12 @@ 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;
+import { Flagsmith } from './index.js';
 
+/**
+ * A concrete type for the possible values of a feature.
+ */
+export type FlagsmithValue<T = string | number | boolean | null> = T;
 
 /**
  * Stores and retrieves {@link Flags} from a cache.
@@ -26,7 +28,7 @@ export interface FlagsmithCache {
     set(key: string, value: Flags): Promise<void>;
 }
 
-export type Fetch = typeof fetch
+export type Fetch = typeof fetch;
 
 /**
  * The configuration options for a {@link Flagsmith} client.
@@ -53,7 +55,7 @@ export interface FlagsmithConfig {
     /**
      * Custom headers to use in all HTTP requests.
      */
-    customHeaders?: HeadersInit
+    customHeaders?: HeadersInit;
     /**
      * The network request timeout duration, in seconds.
      *
@@ -96,7 +98,7 @@ export interface FlagsmithConfig {
      * const defaultHandler = () => new DefaultFlag(undefined, false)
      *
      * // Enable only VIP flags by default
-     * const vipDefaultHandler = (key: string) => new Default(undefined, key.startsWith('vip_'))
+     * const vipDefaultHandler = (key: string) => new DefaultFlag(undefined, key.startsWith('vip_'))
      */
     defaultFlagHandler?: (flagKey: string) => DefaultFlag;
     cache?: FlagsmithCache;
@@ -117,9 +119,16 @@ export interface FlagsmithConfig {
     offlineHandler?: BaseOfflineHandler;
 }
 
-export interface ITraitConfig {
+/**
+ * Represents the configuration for a trait in Flagsmith.
+ *
+ * @property value The {@link FlagsmithTraitValue} for this trait.
+ * @property [transient] Indicates whether the trait should be persisted when used in a remote flag evaluation context.
+ * Defaults to false.
+ */
+export interface TraitConfig {
     value: FlagsmithTraitValue;
     transient?: boolean;
 }
 
-export declare type FlagsmithTraitValue = IFlagsmithValue;
+export declare type FlagsmithTraitValue = FlagsmithValue;

package/sdk/utils.ts

@@ -1,11 +1,11 @@
-import {Fetch, FlagsmithTraitValue, ITraitConfig} from './types.js';
-import {Dispatcher} from "undici-types";
+import { Fetch, FlagsmithTraitValue, TraitConfig } from './types.js';
+import { Dispatcher } from 'undici-types';
 
-type Traits = { [key: string]: ITraitConfig | FlagsmithTraitValue };
+type Traits = { [key: string]: TraitConfig | FlagsmithTraitValue };
 
 export function isTraitConfig(
-    traitValue: ITraitConfig | FlagsmithTraitValue
-): traitValue is ITraitConfig {
+    traitValue: TraitConfig | FlagsmithTraitValue
+): traitValue is TraitConfig {
     return !!traitValue && typeof traitValue == 'object' && traitValue.value !== undefined;
 }
 
@@ -15,12 +15,12 @@ export function generateIdentitiesData(identifier: string, traits: Traits, trans
             return {
                 trait_key: key,
                 trait_value: value?.value,
-                transient: value?.transient,
+                transient: value?.transient
             };
         } else {
             return {
                 trait_key: key,
-                trait_value: value,
+                trait_value: value
             };
         }
     });
@@ -47,7 +47,7 @@ export const retryFetch = (
     retries: number = 3,
     timeoutMs: number = 10, // set an overall timeout for this function
     retryDelayMs: number = 1000,
-    customFetch: Fetch,
+    customFetch: Fetch
 ): Promise<Response> => {
     const retryWrapper = async (n: number): Promise<Response> => {
         try {

package/tests/engine/e2e/engine.test.ts

@@ -3,11 +3,9 @@ import { EnvironmentModel } from '../../../flagsmith-engine/environments/models.
 import { buildEnvironmentModel } from '../../../flagsmith-engine/environments/util.js';
 import { IdentityModel } from '../../../flagsmith-engine/identities/models.js';
 import { buildIdentityModel } from '../../../flagsmith-engine/identities/util.js';
-import * as testData from '../engine-tests/engine-test-data/data/environment_n9fbf9h3v4fFgH3U3ngWhb.json'
+import * as testData from '../engine-tests/engine-test-data/data/environment_n9fbf9h3v4fFgH3U3ngWhb.json';
 
-function extractTestCases(
-    data: any
-): {
+function extractTestCases(data: any): {
     environment: EnvironmentModel;
     identity: IdentityModel;
     response: any;

package/tests/engine/unit/engine.test.ts

@@ -73,11 +73,7 @@ test('test_identity_get_all_feature_states_with_traits_hideDisabledFlags', () =>
     const env = environmentWithSegmentOverride();
     env.project.hideDisabledFlags = true;
 
-    const featureStates = getIdentityFeatureStates(
-        env,
-        identityInSegment(),
-        [trait_models]
-    );
+    const featureStates = getIdentityFeatureStates(env, identityInSegment(), [trait_models]);
     expect(featureStates.length).toBe(0);
 });
 

package/tests/engine/unit/features/models.test.ts

@@ -66,11 +66,11 @@ test('test_feature_state_get_value_mv_values', () => {
         const mvFeatureState = new FeatureStateModel(myFeature, true, 1);
         mvFeatureState.multivariateFeatureStateValues = [
             mvFeatureStateValue1,
-            mvFeatureStateValue2,
+            mvFeatureStateValue2
         ];
 
         mvFeatureState.setValue(mvFeatureControlValue);
 
-        expect(mvFeatureState.getValue("test")).toBe(mvFeatureValue2);
+        expect(mvFeatureState.getValue('test')).toBe(mvFeatureValue2);
     }
 });

package/tests/engine/unit/identities/identities_builders.test.ts

@@ -47,7 +47,7 @@ test('test_build_identity_model_from_dictionary_uses_identity_feature_list_for_i
         id: 1,
         identifier: 'test-identity',
         environment_api_key: 'api-key',
-        created_date: '2021-08-22T06:25:23.406995Z',
+        created_date: '2021-08-22T06:25:23.406995Z'
     };
 
     const identityModel = buildIdentityModel(identity_dict);

package/tests/engine/unit/segments/segment_evaluators.test.ts

@@ -1,44 +1,70 @@
 import {
     ALL_RULE,
     CONDITION_OPERATORS,
-    PERCENTAGE_SPLIT,
+    PERCENTAGE_SPLIT
 } from '../../../../flagsmith-engine/segments/constants.js';
-import {SegmentConditionModel} from '../../../../flagsmith-engine/segments/models.js';
-import {traitsMatchSegmentCondition, evaluateIdentityInSegment} from "../../../../flagsmith-engine/segments/evaluators.js";
-import {TraitModel, IdentityModel} from "../../../../flagsmith-engine/index.js";
-import {environment} from "../utils.js";
+import { SegmentConditionModel } from '../../../../flagsmith-engine/segments/models.js';
+import {
+    traitsMatchSegmentCondition,
+    evaluateIdentityInSegment
+} from '../../../../flagsmith-engine/segments/evaluators.js';
+import { TraitModel, IdentityModel } from '../../../../flagsmith-engine/index.js';
+import { environment } from '../utils.js';
 import { buildSegmentModel } from '../../../../flagsmith-engine/segments/util.js';
 import { getHashedPercentateForObjIds } from '../../../../flagsmith-engine/utils/hashing/index.js';
 
-
 // todo: work out how to implement this in a test function or before hook
 vi.mock('../../../../flagsmith-engine/utils/hashing', () => ({
     getHashedPercentateForObjIds: vi.fn(() => 1)
 }));
 
-
-let traitExistenceTestCases: [string, string | null | undefined, string | null | undefined, TraitModel [],boolean][] = [
-    [CONDITION_OPERATORS.IS_SET,'foo', null,[] , false],
-    [CONDITION_OPERATORS.IS_SET, 'foo',undefined , [new TraitModel('foo','bar')], true],
-    [CONDITION_OPERATORS.IS_SET, 'foo',undefined , [new TraitModel('foo','bar'), new TraitModel('fooBaz','baz')], true],
+let traitExistenceTestCases: [
+    string,
+    string | null | undefined,
+    string | null | undefined,
+    TraitModel[],
+    boolean
+][] = [
+    [CONDITION_OPERATORS.IS_SET, 'foo', null, [], false],
+    [CONDITION_OPERATORS.IS_SET, 'foo', undefined, [new TraitModel('foo', 'bar')], true],
+    [
+        CONDITION_OPERATORS.IS_SET,
+        'foo',
+        undefined,
+        [new TraitModel('foo', 'bar'), new TraitModel('fooBaz', 'baz')],
+        true
+    ],
     [CONDITION_OPERATORS.IS_NOT_SET, 'foo', undefined, [], true],
-    [CONDITION_OPERATORS.IS_NOT_SET, 'foo', null, [new TraitModel('foo','bar')], false],
-    [CONDITION_OPERATORS.IS_NOT_SET, 'foo', null, [new TraitModel('foo','bar'), new TraitModel('fooBaz','baz')], false]
+    [CONDITION_OPERATORS.IS_NOT_SET, 'foo', null, [new TraitModel('foo', 'bar')], false],
+    [
+        CONDITION_OPERATORS.IS_NOT_SET,
+        'foo',
+        null,
+        [new TraitModel('foo', 'bar'), new TraitModel('fooBaz', 'baz')],
+        false
+    ]
 ];
 
 test('test_traits_match_segment_condition_for_trait_existence_operators', () => {
     for (const testCase of traitExistenceTestCases) {
-        const [operator, conditionProperty, conditionValue, traits, expectedResult] = testCase
-        let segmentModel = new SegmentConditionModel(operator, conditionValue, conditionProperty)
-        expect(
-           traitsMatchSegmentCondition (traits, segmentModel, 'any','any')
-        ).toBe(expectedResult);
+        const [operator, conditionProperty, conditionValue, traits, expectedResult] = testCase;
+        let segmentModel = new SegmentConditionModel(operator, conditionValue, conditionProperty);
+        expect(traitsMatchSegmentCondition(traits, segmentModel, 'any', 'any')).toBe(
+            expectedResult
+        );
     }
 });
 
-
 test('evaluateIdentityInSegment uses django ID for hashed percentage when present', () => {
-    var identityModel = new IdentityModel(Date.now().toString(), [], [], environment().apiKey, 'identity_1', undefined, 1);
+    var identityModel = new IdentityModel(
+        Date.now().toString(),
+        [],
+        [],
+        environment().apiKey,
+        'identity_1',
+        undefined,
+        1
+    );
     const segmentDefinition = {
         id: 1,
         name: 'percentage_split_segment',
@@ -49,7 +75,7 @@ test('evaluateIdentityInSegment uses django ID for hashed percentage when presen
                     {
                         operator: PERCENTAGE_SPLIT,
                         property_: null,
-                        value: "10"
+                        value: '10'
                     }
                 ],
                 rules: []
@@ -62,6 +88,9 @@ test('evaluateIdentityInSegment uses django ID for hashed percentage when presen
     var result = evaluateIdentityInSegment(identityModel, segmentModel);
 
     expect(result).toBe(true);
-    expect(getHashedPercentateForObjIds).toHaveBeenCalledTimes(1)
-    expect(getHashedPercentateForObjIds).toHaveBeenCalledWith([segmentModel.id, identityModel.djangoID])
+    expect(getHashedPercentateForObjIds).toHaveBeenCalledTimes(1);
+    expect(getHashedPercentateForObjIds).toHaveBeenCalledWith([
+        segmentModel.id,
+        identityModel.djangoID
+    ]);
 });