flagsmith-nodejs 6.1.0 → 7.0.2

package/flagsmith-engine/segments/evaluators.ts

@@ -1,76 +1,192 @@
-import { EnvironmentModel } from '../environments/models.js';
-import { IdentityModel } from '../identities/models.js';
-import { TraitModel } from '../identities/traits/models.js';
-import { getHashedPercentateForObjIds } from '../utils/hashing/index.js';
-import { PERCENTAGE_SPLIT, IS_SET, IS_NOT_SET } from './constants.js';
-import { SegmentConditionModel, SegmentModel, SegmentRuleModel } from './models.js';
-
-export function getIdentitySegments(
-    environment: EnvironmentModel,
-    identity: IdentityModel,
-    overrideTraits?: TraitModel[]
-): SegmentModel[] {
-    return environment.project.segments.filter(segment =>
-        evaluateIdentityInSegment(identity, segment, overrideTraits)
-    );
+import * as jsonpathModule from 'jsonpath';
+import {
+    GenericEvaluationContext,
+    InSegmentCondition,
+    SegmentCondition,
+    SegmentContext,
+    SegmentRule
+} from '../evaluation/models.js';
+import { getHashedPercentageForObjIds } from '../utils/hashing/index.js';
+import { SegmentConditionModel } from './models.js';
+import { IS_NOT_SET, IS_SET, PERCENTAGE_SPLIT } from './constants.js';
+
+// Handle ESM/CJS interop - jsonpath exports default in ESM
+const jsonpath = (jsonpathModule as any).default || jsonpathModule;
+
+/**
+ * Returns all segments that the identity belongs to based on segment rules evaluation.
+ *
+ * An identity belongs to a segment if it matches ALL of the segment's rules.
+ * If the context has no identity or segments, returns an empty array.
+ *
+ * @param context - Evaluation context containing identity and segment definitions
+ * @returns Array of segments that the identity matches
+ */
+export function getIdentitySegments(context: GenericEvaluationContext): SegmentContext[] {
+    if (!context.identity || !context.segments) return [];
+
+    return Object.values(context.segments).filter(segment => {
+        if (segment.rules.length === 0) return false;
+        return segment.rules.every(rule => traitsMatchSegmentRule(rule, segment.key, context));
+    });
 }
 
-export function evaluateIdentityInSegment(
-    identity: IdentityModel,
-    segment: SegmentModel,
-    overrideTraits?: TraitModel[]
+/**
+ * Evaluates whether a segment condition matches the identity's traits or context values.
+ *
+ * Handles different types of conditions:
+ * - PERCENTAGE_SPLIT: Deterministic percentage-based bucketing using identity key
+ * - IS_SET/IS_NOT_SET: Checks for trait existence
+ * - Standard operators: EQUAL, NOT_EQUAL, etc. via SegmentConditionModel
+ * - JSONPath expressions: $.identity.identifier, $.environment.name, etc.
+ *
+ * @param condition - The condition to evaluate (property, operator, value)
+ * @param segmentKey - Key of the segment (used for percentage split hashing)
+ * @param context - Evaluation context containing identity, traits, and environment
+ * @returns true if the condition matches
+ */
+export function traitsMatchSegmentCondition(
+    condition: SegmentCondition | InSegmentCondition,
+    segmentKey: string,
+    context?: GenericEvaluationContext
 ): boolean {
-    return (
-        segment.rules.length > 0 &&
-        segment.rules.filter(rule =>
-            traitsMatchSegmentRule(
-                overrideTraits || identity.identityTraits,
-                rule,
-                segment.id,
-                identity.djangoID || identity.compositeKey
-            )
-        ).length === segment.rules.length
-    );
+    if (condition.operator === PERCENTAGE_SPLIT) {
+        let splitKey: string | undefined;
+
+        if (!condition.property) {
+            splitKey = context?.identity?.key;
+        } else {
+            splitKey = getContextValue(condition.property, context);
+        }
+
+        if (!splitKey) {
+            return false;
+        }
+        const hashedPercentage = getHashedPercentageForObjIds([segmentKey, splitKey]);
+        return hashedPercentage <= parseFloat(String(condition.value));
+    }
+    if (!condition.property) {
+        return false;
+    }
+
+    const traitValue = getTraitValue(condition.property, context);
+
+    if (condition.operator === IS_SET) {
+        return traitValue !== undefined && traitValue !== null;
+    }
+    if (condition.operator === IS_NOT_SET) {
+        return traitValue === undefined || traitValue === null;
+    }
+
+    if (traitValue !== undefined && traitValue !== null) {
+        const segmentCondition = new SegmentConditionModel(
+            condition.operator,
+            condition.value as string,
+            condition.property
+        );
+        return segmentCondition.matchesTraitValue(traitValue);
+    }
+
+    return false;
 }
 
 function traitsMatchSegmentRule(
-    identityTraits: TraitModel[],
-    rule: SegmentRuleModel,
-    segmentId: number | string,
-    identityId: number | string
+    rule: SegmentRule,
+    segmentKey: string,
+    context?: GenericEvaluationContext
+): boolean {
+    const matchesConditions = evaluateConditions(rule, segmentKey, context);
+    const matchesSubRules = evaluateSubRules(rule, segmentKey, context);
+
+    return matchesConditions && matchesSubRules;
+}
+
+function evaluateConditions(
+    rule: SegmentRule,
+    segmentKey: string,
+    context?: GenericEvaluationContext
 ): boolean {
-    const matchesConditions =
-        rule.conditions.length > 0
-            ? rule.matchingFunction()(
-                  rule.conditions.map(condition =>
-                      traitsMatchSegmentCondition(identityTraits, condition, segmentId, identityId)
-                  )
-              )
-            : true;
-    return (
-        matchesConditions &&
-        rule.rules.filter(rule =>
-            traitsMatchSegmentRule(identityTraits, rule, segmentId, identityId)
-        ).length === rule.rules.length
+    if (!rule.conditions || rule.conditions.length === 0) return true;
+
+    const conditionResults = rule.conditions.map((condition: SegmentCondition) =>
+        traitsMatchSegmentCondition(condition, segmentKey, context)
     );
+
+    return evaluateRuleConditions(rule.type, conditionResults);
 }
 
-export function traitsMatchSegmentCondition(
-    identityTraits: TraitModel[],
-    condition: SegmentConditionModel,
-    segmentId: number | string,
-    identityId: number | string
+function evaluateSubRules(
+    rule: SegmentRule,
+    segmentKey: string,
+    context?: GenericEvaluationContext
 ): boolean {
-    if (condition.operator == PERCENTAGE_SPLIT) {
-        var hashedPercentage = getHashedPercentateForObjIds([segmentId, identityId]);
-        return hashedPercentage <= parseFloat(String(condition.value));
+    if (!rule.rules || rule.rules.length === 0) return true;
+
+    return rule.rules.every((subRule: SegmentRule) =>
+        traitsMatchSegmentRule(subRule, segmentKey, context)
+    );
+}
+
+function evaluateRuleConditions(ruleType: string, conditionResults: boolean[]): boolean {
+    switch (ruleType) {
+        case 'ALL':
+            return conditionResults.length === 0 || conditionResults.every(result => result);
+        case 'ANY':
+            return conditionResults.length > 0 && conditionResults.some(result => result);
+        case 'NONE':
+            return conditionResults.length === 0 || conditionResults.every(result => !result);
+        default:
+            return false;
     }
-    const traits = identityTraits.filter(t => t.traitKey === condition.property_);
-    const trait = traits.length > 0 ? traits[0] : undefined;
-    if (condition.operator === IS_SET) {
-        return !!trait;
-    } else if (condition.operator === IS_NOT_SET) {
-        return trait == undefined;
+}
+
+function getTraitValue(property: string, context?: GenericEvaluationContext): any {
+    if (property.startsWith('$.')) {
+        const contextValue = getContextValue(property, context);
+        if (contextValue !== undefined && isPrimitive(contextValue)) {
+            return contextValue;
+        }
     }
-    return trait ? condition.matchesTraitValue(trait.traitValue) : false;
+    const traits = context?.identity?.traits || {};
+
+    return traits[property];
+}
+
+function isPrimitive(value: any): boolean {
+    if (value === null || value === undefined) {
+        return true;
+    }
+
+    // Objects and arrays are non-primitive
+    return typeof value !== 'object';
+}
+
+/**
+ * Evaluates JSONPath expressions against the evaluation context.
+ *
+ * Supports accessing nested context values using JSONPath syntax.
+ * Commonly used paths:
+ * - $.identity.identifier - User's unique identifier
+ * - $.identity.key - User's internal key
+ * - $.environment.name - Environment name
+ * - $.environment.key - Environment key
+ *
+ * @param jsonPath - JSONPath expression starting with '$.'
+ * @param context - Evaluation context to query against
+ * @returns The resolved value, or undefined if path doesn't exist or is invalid
+ */
+export function getContextValue(jsonPath: string, context?: GenericEvaluationContext): any {
+    if (!context || !jsonPath?.startsWith('$.')) return undefined;
+
+    try {
+        const normalizedPath = normalizeJsonPath(jsonPath);
+        const results = jsonpath.query(context, normalizedPath);
+        return results.length > 0 ? results[0] : undefined;
+    } catch (error) {
+        return undefined;
+    }
+}
+
+function normalizeJsonPath(jsonPath: string): string {
+    return jsonPath.replace(/\.([^.\[\]]+)$/, "['$1']");
 }

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.1.0",
+  "version": "7.0.2",
   "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/release-please-config.json

@@ -0,0 +1,62 @@
+{
+    "bootstrap-sha": "644c5c883ecbb3786507b50cea01903dc2e533bf",
+    "packages": {
+        ".": {
+            "release-type": "node",
+            "changelog-path": "CHANGELOG.md",
+            "bump-minor-pre-major": false,
+            "bump-patch-for-minor-pre-major": false,
+            "draft": false,
+            "prerelease": false,
+            "include-component-in-tag": false
+        }
+    },
+    "$schema": "https://raw.githubusercontent.com/googleapis/release-please/main/schemas/config.json",
+    "changelog-sections": [
+        {
+            "type": "feat",
+            "hidden": false,
+            "section": "Features"
+        },
+        {
+            "type": "fix",
+            "hidden": false,
+            "section": "Bug Fixes"
+        },
+        {
+            "type": "ci",
+            "hidden": false,
+            "section": "CI"
+        },
+        {
+            "type": "docs",
+            "hidden": false,
+            "section": "Docs"
+        },
+        {
+            "type": "deps",
+            "hidden": false,
+            "section": "Dependency Updates"
+        },
+        {
+            "type": "perf",
+            "hidden": false,
+            "section": "Performance Improvements"
+        },
+        {
+            "type": "refactor",
+            "hidden": false,
+            "section": "Refactoring"
+        },
+        {
+            "type": "test",
+            "hidden": false,
+            "section": "Tests"
+        },
+        {
+            "type": "chore",
+            "hidden": false,
+            "section": "Other"
+        }
+    ]
+}

package/sdk/analytics.ts

@@ -1,6 +1,7 @@
 import { pino, Logger } from 'pino';
 import { Fetch } from './types.js';
 import { FlagsmithConfig } from './types.js';
+import { getUserAgent } from './utils.js';
 
 export const ANALYTICS_ENDPOINT = './analytics/flags/';
 
@@ -69,7 +70,8 @@ export class AnalyticsProcessor {
                 signal: AbortSignal.timeout(this.requestTimeoutMs),
                 headers: {
                     'Content-Type': 'application/json',
-                    'X-Environment-Key': this.environmentKey
+                    'X-Environment-Key': this.environmentKey,
+                    'User-Agent': getUserAgent()
                 }
             });
             await this.currentFlush;