flagsmith-nodejs 6.2.0 → 7.0.3

package/flagsmith-engine/segments/models.ts

@@ -1,6 +1,11 @@
 import * as semver from 'semver';
 
-import { FeatureStateModel } from '../features/models.js';
+import {
+    FeatureModel,
+    FeatureStateModel,
+    MultivariateFeatureOptionModel,
+    MultivariateFeatureStateValueModel
+} from '../features/models.js';
 import { getCastingFunction as getCastingFunction } from '../utils/index.js';
 import {
     ALL_RULE,
@@ -13,6 +18,12 @@ import {
     CONDITION_OPERATORS
 } from './constants.js';
 import { isSemver } from './util.js';
+import {
+    EvaluationContext,
+    Overrides
+} from '../evaluation/evaluationContext/evaluationContext.types.js';
+import { CONSTANTS } from '../features/constants.js';
+import { EvaluationResultSegments, SegmentSource } from '../evaluation/models.js';
 
 export const all = (iterable: Array<any>) => iterable.filter(e => !!e).length === iterable.length;
 export const any = (iterable: Array<any>) => iterable.filter(e => !!e).length > 0;
@@ -26,22 +37,45 @@ export const matchingFunctions = {
     [CONDITION_OPERATORS.LESS_THAN_INCLUSIVE]: (thisValue: any, otherValue: any) =>
         thisValue >= otherValue,
     [CONDITION_OPERATORS.NOT_EQUAL]: (thisValue: any, otherValue: any) => thisValue != otherValue,
-    [CONDITION_OPERATORS.CONTAINS]: (thisValue: any, otherValue: any) =>
-        !!otherValue && otherValue.includes(thisValue)
+    [CONDITION_OPERATORS.CONTAINS]: (thisValue: any, otherValue: any) => {
+        try {
+            return !!otherValue && otherValue.includes(thisValue);
+        } catch {
+            return false;
+        }
+    }
+};
+
+// Semver library throws an error if the version is invalid, in this case, we want to catch and return false
+const safeSemverCompare = (
+    semverMatchingFunction: (conditionValue: any, traitValue: any) => boolean
+) => {
+    return (conditionValue: any, traitValue: any) => {
+        try {
+            return semverMatchingFunction(conditionValue, traitValue);
+        } catch {
+            return false;
+        }
+    };
 };
 
 export const semverMatchingFunction = {
     ...matchingFunctions,
-    [CONDITION_OPERATORS.EQUAL]: (thisValue: any, otherValue: any) =>
-        semver.eq(thisValue, otherValue),
-    [CONDITION_OPERATORS.GREATER_THAN]: (thisValue: any, otherValue: any) =>
-        semver.gt(otherValue, thisValue),
-    [CONDITION_OPERATORS.GREATER_THAN_INCLUSIVE]: (thisValue: any, otherValue: any) =>
-        semver.gte(otherValue, thisValue),
-    [CONDITION_OPERATORS.LESS_THAN]: (thisValue: any, otherValue: any) =>
-        semver.gt(thisValue, otherValue),
-    [CONDITION_OPERATORS.LESS_THAN_INCLUSIVE]: (thisValue: any, otherValue: any) =>
-        semver.gte(thisValue, otherValue)
+    [CONDITION_OPERATORS.EQUAL]: safeSemverCompare((conditionValue, traitValue) =>
+        semver.eq(traitValue, conditionValue)
+    ),
+    [CONDITION_OPERATORS.GREATER_THAN]: safeSemverCompare((conditionValue, traitValue) =>
+        semver.gt(traitValue, conditionValue)
+    ),
+    [CONDITION_OPERATORS.GREATER_THAN_INCLUSIVE]: safeSemverCompare((conditionValue, traitValue) =>
+        semver.gte(traitValue, conditionValue)
+    ),
+    [CONDITION_OPERATORS.LESS_THAN]: safeSemverCompare((conditionValue, traitValue) =>
+        semver.lt(traitValue, conditionValue)
+    ),
+    [CONDITION_OPERATORS.LESS_THAN_INCLUSIVE]: safeSemverCompare((conditionValue, traitValue) =>
+        semver.lte(traitValue, conditionValue)
+    )
 };
 
 export const getMatchingFunctions = (semver: boolean) =>
@@ -56,17 +90,17 @@ export class SegmentConditionModel {
     };
 
     operator: string;
-    value: string | null | undefined;
-    property_: string | null | undefined;
+    value: string | null | undefined | string[];
+    property: string | null | undefined;
 
     constructor(
         operator: string,
-        value?: string | null | undefined,
+        value?: string | null | undefined | string[],
         property?: string | null | undefined
     ) {
         this.operator = operator;
         this.value = value;
-        this.property_ = property;
+        this.property = property;
     }
 
     matchesTraitValue(traitValue: any) {
@@ -79,17 +113,52 @@ export class SegmentConditionModel {
                 );
             },
             evaluateRegex: (traitValue: any) => {
-                return !!this.value && !!traitValue?.toString().match(new RegExp(this.value));
+                try {
+                    if (!this.value) {
+                        return false;
+                    }
+                    const regex = new RegExp(this.value?.toString());
+                    return !!traitValue?.toString().match(regex);
+                } catch {
+                    return false;
+                }
             },
             evaluateModulo: (traitValue: any) => {
-                if (isNaN(parseFloat(traitValue)) || !this.value) {
+                const parsedTraitValue = parseFloat(traitValue);
+                if (isNaN(parsedTraitValue) || !this.value) {
                     return false;
                 }
-                const parts = this.value.split('|');
-                const [divisor, reminder] = [parseFloat(parts[0]), parseFloat(parts[1])];
-                return traitValue % divisor === reminder;
+
+                const parts = this.value.toString().split('|');
+                if (parts.length !== 2) {
+                    return false;
+                }
+
+                const divisor = parseFloat(parts[0]);
+                const remainder = parseFloat(parts[1]);
+
+                if (isNaN(divisor) || isNaN(remainder) || divisor === 0) {
+                    return false;
+                }
+
+                return parsedTraitValue % divisor === remainder;
             },
-            evaluateIn: (traitValue: any) => {
+            evaluateIn: (traitValue: string[] | string) => {
+                if (!traitValue || typeof traitValue === 'boolean') {
+                    return false;
+                }
+                if (Array.isArray(this.value)) {
+                    return this.value.includes(traitValue.toString());
+                }
+
+                if (typeof this.value === 'string') {
+                    try {
+                        const parsed = JSON.parse(this.value);
+                        if (Array.isArray(parsed)) {
+                            return parsed.includes(traitValue.toString());
+                        }
+                    } catch {}
+                }
                 return this.value?.split(',').includes(traitValue.toString());
             }
         };
@@ -144,4 +213,83 @@ export class SegmentModel {
         this.id = id;
         this.name = name;
     }
+
+    static fromSegmentResult(
+        segmentResults: EvaluationResultSegments,
+        evaluationContext: EvaluationContext
+    ): SegmentModel[] {
+        const segmentModels: SegmentModel[] = [];
+        if (!evaluationContext.segments) {
+            return [];
+        }
+
+        for (const segmentResult of segmentResults) {
+            if (segmentResult.metadata?.source === SegmentSource.IDENTITY_OVERRIDE) {
+                continue;
+            }
+            const segmentMetadataId = segmentResult.metadata?.id;
+            if (!segmentMetadataId) {
+                continue;
+            }
+            const segmentContext = evaluationContext.segments[segmentMetadataId.toString()];
+            if (segmentContext) {
+                const segment = new SegmentModel(segmentMetadataId, segmentContext.name);
+                segment.rules = segmentContext.rules.map(rule => new SegmentRuleModel(rule.type));
+                segment.featureStates = SegmentModel.createFeatureStatesFromOverrides(
+                    segmentContext.overrides || []
+                );
+                segmentModels.push(segment);
+            }
+        }
+
+        return segmentModels;
+    }
+
+    private static createFeatureStatesFromOverrides(overrides: Overrides): FeatureStateModel[] {
+        if (!overrides) return [];
+        return overrides
+            .filter(override => {
+                const overrideMetadataId = override?.metadata?.id;
+                return typeof overrideMetadataId === 'number';
+            })
+            .map(override => {
+                const overrideMetadataId = override.metadata!.id as number;
+                const feature = new FeatureModel(
+                    overrideMetadataId,
+                    override.name,
+                    override.variants?.length && override.variants.length > 0
+                        ? CONSTANTS.MULTIVARIATE
+                        : CONSTANTS.STANDARD
+                );
+
+                const featureState = new FeatureStateModel(
+                    feature,
+                    override.enabled,
+                    override.priority || 0
+                );
+
+                if (override.value !== undefined) {
+                    featureState.setValue(override.value);
+                }
+
+                if (override.variants && override.variants.length > 0) {
+                    featureState.multivariateFeatureStateValues = this.createMultivariateValues(
+                        override.variants
+                    );
+                }
+
+                return featureState;
+            });
+    }
+
+    private static createMultivariateValues(variants: any[]): MultivariateFeatureStateValueModel[] {
+        return variants.map(
+            variant =>
+                new MultivariateFeatureStateValueModel(
+                    new MultivariateFeatureOptionModel(variant.value, variant.id as number),
+                    variant.weight as number,
+                    variant.id as number
+                )
+        );
+    }
 }

package/flagsmith-engine/utils/hashing/index.ts

@@ -14,7 +14,7 @@ const makeRepeated = (arr: Array<any>, repeats: number) =>
  * @param  {} iterations=1 num times to include each id in the generated string to hash
  * @returns number number between 0 (inclusive) and 100 (exclusive)
  */
-export function getHashedPercentateForObjIds(objectIds: Array<any>, iterations = 1): number {
+export function getHashedPercentageForObjIds(objectIds: Array<any>, iterations = 1): number {
     let toHash = makeRepeated(objectIds, iterations).join(',');
     const hashedValue = md5(toHash);
     const hashedInt = BigInt('0x' + hashedValue);
@@ -24,7 +24,7 @@ export function getHashedPercentateForObjIds(objectIds: Array<any>, iterations =
     /* istanbul ignore next */
     if (value === 100) {
         /* istanbul ignore next */
-        return getHashedPercentateForObjIds(objectIds, iterations + 1);
+        return getHashedPercentageForObjIds(objectIds, iterations + 1);
     }
 
     return value;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flagsmith-nodejs",
-  "version": "6.2.0",
+  "version": "7.0.3",
   "description": "Flagsmith lets you manage features flags and remote config across web, mobile and server side applications. Deliver true Continuous Integration. Get builds out faster. Control who has access to new features.",
   "main": "./build/cjs/index.js",
   "type": "module",
@@ -51,26 +51,37 @@
   "scripts": {
     "lint": "prettier --write .",
     "test": "vitest --coverage --run",
+    "test:esm-build": "npm run build && ESM_BUILD=true vitest --config vitest.config.esm.ts --run",
     "test:watch": "vitest",
     "test:debug": "vitest --inspect-brk --no-file-parallelism --coverage",
     "prebuild": "rm -rf ./build",
     "build": "tsc -b tsconfig.cjs.json tsconfig.esm.json && echo '{\"type\": \"commonjs\"}'> build/cjs/package.json",
     "deploy": "npm i && npm run build && npm publish",
     "deploy:beta": "npm i && npm run build && npm publish --tag beta",
-    "prepare": "husky install"
+    "prepare": "husky install",
+    "generate-evaluation-result-types": "curl -o evaluation-result.json https://raw.githubusercontent.com/Flagsmith/flagsmith/main/sdk/evaluation-result.json && npx json2ts -i evaluation-result.json -o flagsmith-engine/evaluation/evaluationResult/evaluationResult.types.ts && rm evaluation-result.json",
+    "generate-evaluation-context-types": "curl -o evaluation-context.json https://raw.githubusercontent.com/Flagsmith/flagsmith/main/sdk/evaluation-context.json && npx json2ts -i evaluation-context.json -o flagsmith-engine/evaluation/evaluationContext/evaluationContext.types.ts && rm evaluation-context.json",
+    "generate-engine-types": "npm run generate-evaluation-result-types && npm run generate-evaluation-context-types"
   },
   "dependencies": {
+    "jsonpath": "^1.1.1",
     "pino": "^8.8.0",
     "semver": "^7.3.7",
     "undici-types": "^6.19.8"
   },
   "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/jsonpath": "^0.2.4",
     "@types/node": "^20.16.10",
     "@types/semver": "^7.3.9",
     "@types/uuid": "^8.3.4",
     "@vitest/coverage-v8": "^2.1.2",
     "esbuild": "^0.25.0",
     "husky": "^7.0.4",
+    "install": "^0.13.0",
+    "json-schema-to-typescript": "^15.0.4",
+    "jsonc-parser": "^3.3.1",
+    "npm": "^11.6.1",
     "prettier": "^2.2.1",
     "typescript": "^4.9.5",
     "undici": "^6.19.8",

package/sdk/index.ts

@@ -1,22 +1,21 @@
 import { Dispatcher } from 'undici-types';
-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 { BaseOfflineHandler } from './offline_handlers.js';
-import { FlagsmithAPIError } from './errors.js';
+import { FlagsmithAPIError, FlagsmithClientError } from './errors.js';
 
 import { DefaultFlag, Flags } from './models.js';
 import { EnvironmentDataPollingManager } from './polling_manager.js';
 import { Deferred, generateIdentitiesData, getUserAgent, retryFetch } from './utils.js';
-import { SegmentModel } from '../flagsmith-engine/index.js';
-import { getIdentitySegments } from '../flagsmith-engine/segments/evaluators.js';
+import {
+    SegmentModel,
+    EnvironmentModel,
+    IdentityModel,
+    TraitModel,
+    getEvaluationResult
+} from '../flagsmith-engine/index.js';
 import {
     Fetch,
     FlagsmithCache,
@@ -25,6 +24,8 @@ import {
     TraitConfig
 } from './types.js';
 import { pino, Logger } from 'pino';
+import { getEvaluationContext } from '../flagsmith-engine/evaluation/evaluationContext/mappers.js';
+import { EvaluationContextWithMetadata } from '../flagsmith-engine/evaluation/models.js';
 
 export { AnalyticsProcessor, AnalyticsProcessorOptions } from './analytics.js';
 export { FlagsmithAPIError, FlagsmithClientError } from './errors.js';
@@ -278,7 +279,13 @@ export class Flagsmith {
             }))
         );
 
-        return getIdentitySegments(environment, identityModel);
+        const context = getEvaluationContext(environment, identityModel);
+        if (!context) {
+            throw new FlagsmithClientError('Local evaluation required to obtain identity segments');
+        }
+        const evaluationResult = getEvaluationResult(context as EvaluationContextWithMetadata);
+
+        return SegmentModel.fromSegmentResult(evaluationResult.segments, context);
     }
 
     private async fetchEnvironment(): Promise<EnvironmentModel> {
@@ -443,14 +450,17 @@ export class Flagsmith {
 
     private async getEnvironmentFlagsFromDocument(): Promise<Flags> {
         const environment = await this.getEnvironment();
-        const flags = Flags.fromFeatureStateModels({
-            featureStates: getEnvironmentFeatureStates(environment),
-            analyticsProcessor: this.analyticsProcessor,
-            defaultFlagHandler: this.defaultFlagHandler
-        });
+        const context = getEvaluationContext(environment, undefined, undefined, true);
+        if (!context) {
+            throw new FlagsmithClientError('Unable to get flags. No environment present.');
+        }
+        const evaluationResult = getEvaluationResult(context as EvaluationContextWithMetadata);
+        const flags = Flags.fromEvaluationResult(evaluationResult);
+
         if (!!this.cache) {
             await this.cache.set('flags', flags);
         }
+
         return flags;
     }
 
@@ -468,14 +478,17 @@ export class Flagsmith {
             }))
         );
 
-        const featureStates = getIdentityFeatureStates(environment, identityModel);
+        const context = getEvaluationContext(environment, identityModel);
+        if (!context) {
+            throw new FlagsmithClientError('Unable to get flags. No environment present.');
+        }
+        const evaluationResult = getEvaluationResult(context as EvaluationContextWithMetadata);
 
-        const flags = Flags.fromFeatureStateModels({
-            featureStates: featureStates,
-            analyticsProcessor: this.analyticsProcessor,
-            defaultFlagHandler: this.defaultFlagHandler,
-            identityID: identityModel.djangoID || identityModel.compositeKey
-        });
+        const flags = Flags.fromEvaluationResult(
+            evaluationResult,
+            this.defaultFlagHandler,
+            this.analyticsProcessor
+        );
 
         if (!!this.cache) {
             await this.cache.set(`flags-${identifier}`, flags);

package/sdk/models.ts

@@ -1,7 +1,12 @@
+import {
+    SDKFeatureMetadata,
+    FlagResultWithMetadata,
+    EvaluationResultWithMetadata
+} from '../flagsmith-engine/evaluation/models.js';
 import { FeatureStateModel } from '../flagsmith-engine/features/models.js';
 import { AnalyticsProcessor } from './analytics.js';
 
-type FlagValue = string | number | boolean | undefined;
+type FlagValue = string | number | boolean | undefined | null;
 
 /**
  * A Flagsmith feature. It has an enabled/disabled state, and an optional {@link FlagValue}.
@@ -49,6 +54,10 @@ export class Flag extends BaseFlag {
      * The programmatic name for this feature, unique per Flagsmith project.
      */
     featureName: string;
+    /**
+     * The reason for this feature, unique per Flagsmith project.
+     */
+    reason?: string;
 
     constructor(params: {
         value: FlagValue;
@@ -56,10 +65,12 @@ export class Flag extends BaseFlag {
         isDefault?: boolean;
         featureId: number;
         featureName: string;
+        reason?: string;
     }) {
         super(params.value, params.enabled, !!params.isDefault);
         this.featureId = params.featureId;
         this.featureName = params.featureName;
+        this.reason = params.reason;
     }
 
     static fromFeatureStateModel(
@@ -79,7 +90,8 @@ export class Flag extends BaseFlag {
             enabled: flagData['enabled'],
             value: flagData['feature_state_value'] ?? flagData['value'],
             featureId: flagData['feature']['id'],
-            featureName: flagData['feature']['name']
+            featureName: flagData['feature']['name'],
+            reason: flagData['feature']['reason']
         });
     }
 }
@@ -99,6 +111,36 @@ export class Flags {
         this.analyticsProcessor = data.analyticsProcessor;
     }
 
+    static fromEvaluationResult(
+        evaluationResult: EvaluationResultWithMetadata,
+        defaultFlagHandler?: (v: string) => DefaultFlag,
+        analyticsProcessor?: AnalyticsProcessor
+    ): Flags {
+        const flags: { [key: string]: Flag } = {};
+        for (const flag of Object.values(evaluationResult.flags)) {
+            const flagMetadataId = flag.metadata?.id;
+            if (!flagMetadataId) {
+                throw new Error(
+                    `FlagResult metadata.id is missing for feature "${flag.name}". ` +
+                        `This indicates a bug in the SDK, please report it.`
+                );
+            }
+
+            flags[flag.name] = new Flag({
+                enabled: flag.enabled,
+                value: flag.value ?? null,
+                featureId: flagMetadataId,
+                featureName: flag.name,
+                reason: flag.reason
+            });
+        }
+        return new Flags({
+            flags: flags,
+            defaultFlagHandler: defaultFlagHandler,
+            analyticsProcessor: analyticsProcessor
+        });
+    }
+
     static fromFeatureStateModels(data: {
         featureStates: FeatureStateModel[];
         analyticsProcessor?: AnalyticsProcessor;

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

@@ -1,46 +1,51 @@
-import { getIdentityFeatureStates } from '../../../flagsmith-engine/index.js';
-import { EnvironmentModel } from '../../../flagsmith-engine/environments/models.js';
-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 fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { getEvaluationResult } from '../../../flagsmith-engine/index.js';
+import { Flags } from '../../../sdk/models.js';
+import { EvaluationContext } from '../../../flagsmith-engine/evaluation/evaluationContext/evaluationContext.types.js';
+import { parse as parseJsonc } from 'jsonc-parser';
+import {
+    EvaluationContextWithMetadata,
+    EvaluationResult
+} from '../../../flagsmith-engine/evaluation/models.js';
 
-function extractTestCases(data: any): {
-    environment: EnvironmentModel;
-    identity: IdentityModel;
-    response: any;
-}[] {
-    const environmentModel = buildEnvironmentModel(data['environment']);
-    const test_data = data['identities_and_responses'].map((test_case: any) => {
-        const identity = buildIdentityModel(test_case['identity']);
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const TEST_DATA_DIR = path.join(__dirname, '../engine-tests/engine-test-data/test_cases');
+interface TestCase {
+    context: EvaluationContext;
+    result: EvaluationResult;
+}
 
-        return {
-            environment: environmentModel,
-            identity: identity,
-            response: test_case['response']
-        };
-    });
-    return test_data;
+function getTestFiles(): string[] {
+    const files = fs.readdirSync(TEST_DATA_DIR);
+    return files
+        .filter(f => f.endsWith('.json') || f.endsWith('.jsonc'))
+        .map(f => path.join(TEST_DATA_DIR, f));
 }
 
-test('Test Engine', () => {
-    const testCases = extractTestCases(testData);
-    for (const testCase of testCases) {
-        const engine_response = getIdentityFeatureStates(testCase.environment, testCase.identity);
-        const sortedEngineFlags = engine_response.sort((a, b) =>
-            a.feature.name > b.feature.name ? 1 : -1
-        );
-        const sortedAPIFlags = testCase.response['flags'].sort((a: any, b: any) =>
-            a.feature.name > b.feature.name ? 1 : -1
-        );
+function loadTestFile(filePath: string): TestCase {
+    const content = fs.readFileSync(filePath, 'utf-8');
+    return parseJsonc(content);
+}
 
-        expect(sortedEngineFlags.length).toBe(sortedAPIFlags.length);
+describe('Engine Integration Tests', () => {
+    const testFiles = getTestFiles();
 
-        for (let i = 0; i < sortedEngineFlags.length; i++) {
-            expect(sortedEngineFlags[i].getValue(testCase.identity.djangoID)).toBe(
-                sortedAPIFlags[i]['feature_state_value']
-            );
-            expect(sortedEngineFlags[i].enabled).toBe(sortedAPIFlags[i]['enabled']);
-        }
+    if (testFiles.length === 0) {
+        throw new Error(`No test files found in ${TEST_DATA_DIR}`);
     }
+
+    testFiles.forEach(filePath => {
+        const testName = path.basename(filePath, path.extname(filePath));
+
+        test(testName, () => {
+            const testCase = loadTestFile(filePath);
+            const engine_response = getEvaluationResult(
+                testCase.context as EvaluationContextWithMetadata
+            );
+            expect(engine_response).toStrictEqual(testCase.result);
+        });
+    });
 });