flagsmith-nodejs 6.2.0 → 7.0.3

package/build/esm/flagsmith-engine/index.js

@@ -1,62 +1,180 @@
 import { getIdentitySegments } from './segments/evaluators.js';
-import { FeatureStateNotFound } from './utils/errors.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, identity, overrideTraits) {
-    // Get feature states from the environment
-    const featureStates = {};
-    for (const fs of environment.featureStates) {
-        featureStates[fs.feature.id] = fs;
+/**
+ * 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) {
+    const enrichedContext = getEnrichedContext(context);
+    const { segments, segmentOverrides } = evaluateSegments(enrichedContext);
+    const flags = evaluateFeatures(enrichedContext, segmentOverrides);
+    return { flags, segments };
+}
+function getEnrichedContext(context) {
+    const identityKey = getIdentityKey(context);
+    if (!identityKey)
+        return context;
+    return {
+        ...context,
+        ...(context.identity && {
+            identity: {
+                identifier: context.identity.identifier,
+                key: identityKey,
+                traits: context.identity.traits || {}
+            }
+        })
+    };
+}
+/**
+ * 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) {
+    if (!context.identity || !context.segments) {
+        return {
+            segments: [],
+            segmentOverrides: {}
+        };
     }
-    // Override with any feature states defined by matching segments
-    const identitySegments = 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;
+    const identitySegments = getIdentitySegments(context);
+    const segments = identitySegments.map(segment => ({
+        name: segment.name,
+        ...(segment.metadata
+            ? {
+                metadata: {
+                    ...segment.metadata
                 }
             }
-            featureStates[featureState.feature.id] = featureState;
-        }
-    }
-    // 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 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) {
+    const segmentOverrides = {};
+    for (const segment of identitySegments) {
+        if (!segment.overrides)
+            continue;
+        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, identity, featureName, overrideTraits) {
-    const featureStates = getIdentityFeatureStatesDict(environment, identity, overrideTraits);
-    const matchingFeature = Object.values(featureStates).filter(f => f.feature.name === featureName);
-    if (matchingFeature.length === 0) {
-        throw new FeatureStateNotFound('Feature State Not Found');
+/**
+ * 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, segmentOverrides) {
+    const flags = {};
+    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));
+        flags[finalFeature.name] = {
+            name: finalFeature.name,
+            enabled: finalFeature.enabled,
+            value: evaluatedValue,
+            ...(finalFeature.metadata ? { metadata: finalFeature.metadata } : {}),
+            reason: evaluatedReason ??
+                getTargetingMatchReason({ type: 'SEGMENT', override: segmentOverride })
+        };
     }
-    return matchingFeature[0];
+    return flags;
 }
-export function getIdentityFeatureStates(environment, identity, overrideTraits) {
-    const featureStates = Object.values(getIdentityFeatureStatesDict(environment, identity, overrideTraits));
-    if (environment.project.hideDisabledFlags) {
-        return featureStates.filter(fs => !!fs.enabled);
+function evaluateFeatureValue(feature, identityKey) {
+    if (!!feature.variants && feature.variants.length > 0 && !!identityKey) {
+        return getMultivariateFeatureValue(feature, identityKey);
     }
-    return featureStates;
+    return { value: feature.value, reason: undefined };
 }
-export function getEnvironmentFeatureState(environment, featureName) {
-    const featuresStates = environment.featureStates.filter(f => f.feature.name === featureName);
-    if (featuresStates.length === 0) {
-        throw new FeatureStateNotFound('Feature State Not Found');
+/**
+ * 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, identityKey) {
+    const percentageValue = getHashedPercentageForObjIds([feature.key, identityKey]);
+    const sortedVariants = [...(feature?.variants || [])].sort((a, b) => {
+        return (a.priority ?? Infinity) - (b.priority ?? Infinity);
+    });
+    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) {
-    if (environment.project.hideDisabledFlags) {
-        return environment.featureStates.filter(fs => !!fs.enabled);
-    }
-    return environment.featureStates;
+export function shouldApplyOverride(override, existingOverrides) {
+    const currentOverride = existingOverrides[override.name];
+    return (!currentOverride || isHigherPriority(override.priority, currentOverride.feature.priority));
 }
+export function isHigherPriority(priorityA, priorityB) {
+    return (priorityA ?? Infinity) < (priorityB ?? Infinity);
+}
+const getTargetingMatchReason = (matchObject) => {
+    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) => {
+    if (!context.identity)
+        return undefined;
+    return context.identity.key || `${context.environment.key}_${context.identity?.identifier}`;
+};

package/build/esm/flagsmith-engine/segments/constants.d.ts

@@ -2,6 +2,7 @@ export declare const ALL_RULE = "ALL";
 export declare const ANY_RULE = "ANY";
 export declare const NONE_RULE = "NONE";
 export declare const RULE_TYPES: string[];
+export declare const IDENTITY_OVERRIDE_SEGMENT_NAME = "identity_overrides";
 export declare const EQUAL = "EQUAL";
 export declare const GREATER_THAN = "GREATER_THAN";
 export declare const LESS_THAN = "LESS_THAN";

package/build/esm/flagsmith-engine/segments/constants.js

@@ -3,6 +3,7 @@ export const ALL_RULE = 'ALL';
 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';
 export const GREATER_THAN = 'GREATER_THAN';

package/build/esm/flagsmith-engine/segments/evaluators.d.ts

@@ -1,7 +1,41 @@
-import { EnvironmentModel } from '../environments/models.js';
-import { IdentityModel } from '../identities/models.js';
-import { TraitModel } from '../identities/traits/models.js';
-import { SegmentConditionModel, SegmentModel } from './models.js';
-export declare function getIdentitySegments(environment: EnvironmentModel, identity: IdentityModel, overrideTraits?: TraitModel[]): SegmentModel[];
-export declare function evaluateIdentityInSegment(identity: IdentityModel, segment: SegmentModel, overrideTraits?: TraitModel[]): boolean;
-export declare function traitsMatchSegmentCondition(identityTraits: TraitModel[], condition: SegmentConditionModel, segmentId: number | string, identityId: number | string): boolean;
+import { GenericEvaluationContext, InSegmentCondition, SegmentCondition, SegmentContext } from '../evaluation/models.js';
+/**
+ * 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 declare function getIdentitySegments(context: GenericEvaluationContext): SegmentContext[];
+/**
+ * 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 declare function traitsMatchSegmentCondition(condition: SegmentCondition | InSegmentCondition, segmentKey: string, context?: GenericEvaluationContext): boolean;
+/**
+ * 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 declare function getContextValue(jsonPath: string, context?: GenericEvaluationContext): any;

package/build/esm/flagsmith-engine/segments/evaluators.js

@@ -1,31 +1,143 @@
-import { getHashedPercentateForObjIds } from '../utils/hashing/index.js';
-import { PERCENTAGE_SPLIT, IS_SET, IS_NOT_SET } from './constants.js';
-export function getIdentitySegments(environment, identity, overrideTraits) {
-    return environment.project.segments.filter(segment => evaluateIdentityInSegment(identity, segment, overrideTraits));
-}
-export function evaluateIdentityInSegment(identity, segment, overrideTraits) {
-    return (segment.rules.length > 0 &&
-        segment.rules.filter(rule => traitsMatchSegmentRule(overrideTraits || identity.identityTraits, rule, segment.id, identity.djangoID || identity.compositeKey)).length === segment.rules.length);
-}
-function traitsMatchSegmentRule(identityTraits, rule, segmentId, identityId) {
-    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);
-}
-export function traitsMatchSegmentCondition(identityTraits, condition, segmentId, identityId) {
-    if (condition.operator == PERCENTAGE_SPLIT) {
-        var hashedPercentage = getHashedPercentateForObjIds([segmentId, identityId]);
+import * as jsonpathModule from 'jsonpath';
+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.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) {
+    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));
+    });
+}
+/**
+ * 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, segmentKey, context) {
+    if (condition.operator === PERCENTAGE_SPLIT) {
+        let splitKey;
+        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));
     }
-    const traits = identityTraits.filter(t => t.traitKey === condition.property_);
-    const trait = traits.length > 0 ? traits[0] : undefined;
+    if (!condition.property) {
+        return false;
+    }
+    const traitValue = getTraitValue(condition.property, context);
     if (condition.operator === IS_SET) {
-        return !!trait;
+        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, condition.property);
+        return segmentCondition.matchesTraitValue(traitValue);
+    }
+    return false;
+}
+function traitsMatchSegmentRule(rule, segmentKey, context) {
+    const matchesConditions = evaluateConditions(rule, segmentKey, context);
+    const matchesSubRules = evaluateSubRules(rule, segmentKey, context);
+    return matchesConditions && matchesSubRules;
+}
+function evaluateConditions(rule, segmentKey, context) {
+    if (!rule.conditions || rule.conditions.length === 0)
+        return true;
+    const conditionResults = rule.conditions.map((condition) => traitsMatchSegmentCondition(condition, segmentKey, context));
+    return evaluateRuleConditions(rule.type, conditionResults);
+}
+function evaluateSubRules(rule, segmentKey, context) {
+    if (!rule.rules || rule.rules.length === 0)
+        return true;
+    return rule.rules.every((subRule) => traitsMatchSegmentRule(subRule, segmentKey, context));
+}
+function evaluateRuleConditions(ruleType, conditionResults) {
+    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;
+    }
+}
+function getTraitValue(property, context) {
+    if (property.startsWith('$.')) {
+        const contextValue = getContextValue(property, context);
+        if (contextValue !== undefined && isPrimitive(contextValue)) {
+            return contextValue;
+        }
+    }
+    const traits = context?.identity?.traits || {};
+    return traits[property];
+}
+function isPrimitive(value) {
+    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, context) {
+    if (!context || !jsonPath?.startsWith('$.'))
+        return undefined;
+    try {
+        const normalizedPath = normalizeJsonPath(jsonPath);
+        const results = jsonpath.query(context, normalizedPath);
+        return results.length > 0 ? results[0] : undefined;
     }
-    else if (condition.operator === IS_NOT_SET) {
-        return trait == undefined;
+    catch (error) {
+        return undefined;
     }
-    return trait ? condition.matchesTraitValue(trait.traitValue) : false;
+}
+function normalizeJsonPath(jsonPath) {
+    return jsonPath.replace(/\.([^.\[\]]+)$/, "['$1']");
 }

package/build/esm/flagsmith-engine/segments/models.d.ts

@@ -1,11 +1,13 @@
 import { FeatureStateModel } from '../features/models.js';
+import { EvaluationContext } from '../evaluation/evaluationContext/evaluationContext.types.js';
+import { EvaluationResultSegments } from '../evaluation/models.js';
 export declare const all: (iterable: Array<any>) => boolean;
 export declare const any: (iterable: Array<any>) => boolean;
 export declare const matchingFunctions: {
     [x: string]: (thisValue: any, otherValue: any) => any;
 };
 export declare const semverMatchingFunction: {
-    [x: string]: ((thisValue: any, otherValue: any) => any) | ((thisValue: any, otherValue: any) => boolean);
+    [x: string]: ((thisValue: any, otherValue: any) => any) | ((conditionValue: any, traitValue: any) => boolean);
 };
 export declare const getMatchingFunctions: (semver: boolean) => {
     [x: string]: (thisValue: any, otherValue: any) => any;
@@ -15,9 +17,9 @@ export declare class SegmentConditionModel {
         [key: string]: string;
     };
     operator: string;
-    value: string | null | undefined;
-    property_: string | null | undefined;
-    constructor(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 | string[], property?: string | null | undefined);
     matchesTraitValue(traitValue: any): any;
 }
 export declare class SegmentRuleModel {
@@ -34,4 +36,7 @@ export declare class SegmentModel {
     rules: SegmentRuleModel[];
     featureStates: FeatureStateModel[];
     constructor(id: number, name: string);
+    static fromSegmentResult(segmentResults: EvaluationResultSegments, evaluationContext: EvaluationContext): SegmentModel[];
+    private static createFeatureStatesFromOverrides;
+    private static createMultivariateValues;
 }