flagsmith-nodejs 6.2.0 → 7.0.3

package/flagsmith-engine/index.ts

@@ -1,102 +1,259 @@
-import { EnvironmentModel } from './environments/models.js';
-import { FeatureStateModel } from './features/models.js';
-import { IdentityModel } from './identities/models.js';
-import { TraitModel } from './identities/traits/models.js';
+import {
+    EvaluationContextWithMetadata,
+    EvaluationResultSegments,
+    EvaluationResultWithMetadata,
+    FeatureContextWithMetadata,
+    SDKFeatureMetadata,
+    FlagResultWithMetadata,
+    GenericEvaluationContext
+} from './evaluation/models.js';
 import { getIdentitySegments } from './segments/evaluators.js';
-import { SegmentModel } from './segments/models.js';
-import { FeatureStateNotFound } from './utils/errors.js';
-
+import { EvaluationResultFlags } from './evaluation/models.js';
+import { TARGETING_REASONS } from './features/types.js';
+import { getHashedPercentageForObjIds } from './utils/hashing/index.js';
 export { EnvironmentModel } from './environments/models.js';
-export { FeatureModel, FeatureStateModel } from './features/models.js';
 export { IdentityModel } from './identities/models.js';
 export { TraitModel } from './identities/traits/models.js';
 export { SegmentModel } from './segments/models.js';
+export { FeatureModel, FeatureStateModel } from './features/models.js';
 export { OrganisationModel } from './organisations/models.js';
 
-function getIdentityFeatureStatesDict(
-    environment: EnvironmentModel,
-    identity: IdentityModel,
-    overrideTraits?: TraitModel[]
-) {
-    // Get feature states from the environment
-    const featureStates: { [key: number]: FeatureStateModel } = {};
-    for (const fs of environment.featureStates) {
-        featureStates[fs.feature.id] = fs;
-    }
+type SegmentOverride = {
+    feature: FeatureContextWithMetadata<SDKFeatureMetadata>;
+    segmentName: string;
+};
 
-    // Override with any feature states defined by matching segments
-    const identitySegments: SegmentModel[] = getIdentitySegments(
-        environment,
-        identity,
-        overrideTraits
-    );
-    for (const matchingSegment of identitySegments) {
-        for (const featureState of matchingSegment.featureStates) {
-            if (featureStates[featureState.feature.id]) {
-                if (featureStates[featureState.feature.id].isHigherSegmentPriority(featureState)) {
-                    continue;
-                }
+export type SegmentOverrides = Record<string, SegmentOverride>;
+
+/**
+ * Evaluates flags and segments for the given context.
+ *
+ * This is the main entry point for the evaluation engine. It processes segments,
+ * applies feature overrides based on segment priority, and returns the final flag states with
+ * evaluation reasons.
+ *
+ * @param context - EvaluationContext containing environment, identity, and segment data
+ * @returns EvaluationResult with flags, segments, and original context
+ */
+export function getEvaluationResult(
+    context: EvaluationContextWithMetadata
+): EvaluationResultWithMetadata {
+    const enrichedContext = getEnrichedContext(context);
+    const { segments, segmentOverrides } = evaluateSegments(enrichedContext);
+    const flags = evaluateFeatures(enrichedContext, segmentOverrides);
+
+    return { flags, segments };
+}
+
+function getEnrichedContext(context: EvaluationContextWithMetadata): EvaluationContextWithMetadata {
+    const identityKey = getIdentityKey(context);
+    if (!identityKey) return context;
+
+    return {
+        ...context,
+        ...(context.identity && {
+            identity: {
+                identifier: context.identity.identifier,
+                key: identityKey,
+                traits: context.identity.traits || {}
             }
-            featureStates[featureState.feature.id] = featureState;
-        }
+        })
+    };
+}
+
+/**
+ * Evaluates which segments the identity belongs to and collects feature overrides.
+ *
+ * @param context - EvaluationContext containing identity and segment definitions
+ * @returns Object containing segments the identity belongs to and any feature overrides
+ */
+export function evaluateSegments(context: EvaluationContextWithMetadata): {
+    segments: EvaluationResultSegments;
+    segmentOverrides: Record<string, SegmentOverride>;
+} {
+    if (!context.identity || !context.segments) {
+        return {
+            segments: [],
+            segmentOverrides: {} as Record<string, SegmentOverride>
+        };
     }
+    const identitySegments = getIdentitySegments(context);
+
+    const segments = identitySegments.map(segment => ({
+        name: segment.name,
+        ...(segment.metadata
+            ? {
+                  metadata: {
+                      ...segment.metadata
+                  }
+              }
+            : {})
+    })) as EvaluationResultSegments;
+    const segmentOverrides = processSegmentOverrides(identitySegments);
+
+    return { segments, segmentOverrides };
+}
+
+/**
+ * Processes feature overrides from segments, applying priority rules.
+ *
+ * When multiple segments override the same feature, the segment with
+ * higher priority (lower numeric value) takes precedence.
+ *
+ * @param identitySegments - Segments that the identity belongs to
+ * @returns Map of feature keys to their highest-priority segment overrides
+ */
+export function processSegmentOverrides(identitySegments: any[]): Record<string, SegmentOverride> {
+    const segmentOverrides: Record<string, SegmentOverride> = {};
+
+    for (const segment of identitySegments) {
+        if (!segment.overrides) continue;
 
-    // Override with any feature states defined directly the identity
-    for (const fs of identity.identityFeatures) {
-        if (featureStates[fs.feature.id]) {
-            featureStates[fs.feature.id] = fs;
+        const overridesList = Array.isArray(segment.overrides) ? segment.overrides : [];
+
+        for (const override of overridesList) {
+            if (shouldApplyOverride(override, segmentOverrides)) {
+                segmentOverrides[override.name] = {
+                    feature: override,
+                    segmentName: segment.name
+                };
+            }
         }
     }
-    return featureStates;
+
+    return segmentOverrides;
 }
 
-export function getIdentityFeatureState(
-    environment: EnvironmentModel,
-    identity: IdentityModel,
-    featureName: string,
-    overrideTraits?: TraitModel[]
-): FeatureStateModel {
-    const featureStates = getIdentityFeatureStatesDict(environment, identity, overrideTraits);
+/**
+ * Evaluates all features in the context, applying segment overrides where applicable.
+ * For each feature:
+ * - Checks if a segment override exists
+ * - Uses override values if present, otherwise evaluates the base feature
+ * - Determines appropriate evaluation reason
+ * - Handles multivariate evaluation for features without overrides
+ *
+ * @param context - EvaluationContext containing features and identity
+ * @param segmentOverrides - Map of feature keys to their segment overrides
+ * @returns EvaluationResultFlags containing evaluated flag results
+ */
+export function evaluateFeatures(
+    context: EvaluationContextWithMetadata,
+    segmentOverrides: Record<string, SegmentOverride>
+): EvaluationResultFlags<SDKFeatureMetadata> {
+    const flags: EvaluationResultFlags<SDKFeatureMetadata> = {};
 
-    const matchingFeature = Object.values(featureStates).filter(
-        f => f.feature.name === featureName
-    );
+    for (const feature of Object.values(context.features || {})) {
+        const segmentOverride = segmentOverrides[feature.name];
+        const finalFeature = segmentOverride ? segmentOverride.feature : feature;
+
+        const { value: evaluatedValue, reason: evaluatedReason } = evaluateFeatureValue(
+            finalFeature,
+            getIdentityKey(context)
+        );
 
-    if (matchingFeature.length === 0) {
-        throw new FeatureStateNotFound('Feature State Not Found');
+        flags[finalFeature.name] = {
+            name: finalFeature.name,
+            enabled: finalFeature.enabled,
+            value: evaluatedValue,
+            ...(finalFeature.metadata ? { metadata: finalFeature.metadata } : {}),
+            reason:
+                evaluatedReason ??
+                getTargetingMatchReason({ type: 'SEGMENT', override: segmentOverride })
+        } as FlagResultWithMetadata<SDKFeatureMetadata>;
     }
 
-    return matchingFeature[0];
+    return flags;
 }
 
-export function getIdentityFeatureStates(
-    environment: EnvironmentModel,
-    identity: IdentityModel,
-    overrideTraits?: TraitModel[]
-): FeatureStateModel[] {
-    const featureStates = Object.values(
-        getIdentityFeatureStatesDict(environment, identity, overrideTraits)
-    );
-
-    if (environment.project.hideDisabledFlags) {
-        return featureStates.filter(fs => !!fs.enabled);
+function evaluateFeatureValue(
+    feature: FeatureContextWithMetadata,
+    identityKey?: string
+): { value: any; reason?: string } {
+    if (!!feature.variants && feature.variants.length > 0 && !!identityKey) {
+        return getMultivariateFeatureValue(feature, identityKey);
     }
-    return featureStates;
+
+    return { value: feature.value, reason: undefined };
 }
 
-export function getEnvironmentFeatureState(environment: EnvironmentModel, featureName: string) {
-    const featuresStates = environment.featureStates.filter(f => f.feature.name === featureName);
+/**
+ * Evaluates a multivariate feature flag to determine which variant value to return for a given identity.
+ *
+ * Uses deterministic hashing to ensure the same identity always receives the same variant,
+ * while distributing variants according to their configured weight percentages.
+ *
+ * @param feature - The feature context containing variants and their weights
+ * @param identityKey - The identity key used for deterministic variant selection
+ * @returns The variant value if the identity falls within a variant's range, otherwise the default feature value
+ */
+function getMultivariateFeatureValue(
+    feature: FeatureContextWithMetadata,
+    identityKey?: string
+): { value: any; reason?: string } {
+    const percentageValue = getHashedPercentageForObjIds([feature.key, identityKey]);
+    const sortedVariants = [...(feature?.variants || [])].sort((a, b) => {
+        return (a.priority ?? Infinity) - (b.priority ?? Infinity);
+    });
 
-    if (featuresStates.length === 0) {
-        throw new FeatureStateNotFound('Feature State Not Found');
+    let startPercentage = 0;
+    for (const variant of sortedVariants) {
+        const limit = startPercentage + variant.weight;
+        if (startPercentage <= percentageValue && percentageValue < limit) {
+            return {
+                value: variant.value,
+                reason: getTargetingMatchReason({ type: 'SPLIT', weight: variant.weight })
+            };
+        }
+        startPercentage = limit;
     }
 
-    return featuresStates[0];
+    return { value: feature.value, reason: undefined };
 }
 
-export function getEnvironmentFeatureStates(environment: EnvironmentModel): FeatureStateModel[] {
-    if (environment.project.hideDisabledFlags) {
-        return environment.featureStates.filter(fs => !!fs.enabled);
-    }
-    return environment.featureStates;
+export function shouldApplyOverride(
+    override: any,
+    existingOverrides: Record<string, SegmentOverride>
+): boolean {
+    const currentOverride = existingOverrides[override.name];
+    return (
+        !currentOverride || isHigherPriority(override.priority, currentOverride.feature.priority)
+    );
 }
+
+export function isHigherPriority(
+    priorityA: number | undefined,
+    priorityB: number | undefined
+): boolean {
+    return (priorityA ?? Infinity) < (priorityB ?? Infinity);
+}
+
+export type TargetingMatchReason =
+    | {
+          type: 'SEGMENT';
+          override: SegmentOverride;
+      }
+    | {
+          type: 'SPLIT';
+          weight: number;
+      };
+
+const getTargetingMatchReason = (matchObject: TargetingMatchReason) => {
+    const { type } = matchObject;
+
+    if (type === 'SEGMENT') {
+        return matchObject.override
+            ? `${TARGETING_REASONS.TARGETING_MATCH}; segment=${matchObject.override.segmentName}`
+            : TARGETING_REASONS.DEFAULT;
+    }
+
+    if (type === 'SPLIT') {
+        return `${TARGETING_REASONS.SPLIT}; weight=${matchObject.weight}`;
+    }
+
+    return TARGETING_REASONS.DEFAULT;
+};
+
+const getIdentityKey = (context: GenericEvaluationContext): string | undefined => {
+    if (!context.identity) return undefined;
+    return context.identity.key || `${context.environment.key}_${context.identity?.identifier}`;
+};

package/flagsmith-engine/segments/constants.ts

@@ -4,6 +4,7 @@ export const ANY_RULE = 'ANY';
 export const NONE_RULE = 'NONE';
 
 export const RULE_TYPES = [ALL_RULE, ANY_RULE, NONE_RULE];
+export const IDENTITY_OVERRIDE_SEGMENT_NAME = 'identity_overrides';
 
 // Segment Condition Operators
 export const EQUAL = 'EQUAL';

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']");
 }