flagsmith-nodejs 6.1.0 → 7.0.2

package/flagsmith-engine/evaluation/evaluationResult/evaluationResult.types.ts

@@ -0,0 +1,71 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated by json-schema-to-typescript.
+ * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
+ * and run json-schema-to-typescript to regenerate this file.
+ */
+
+/**
+ * Feature name.
+ */
+export type Name = string;
+/**
+ * Indicates if the feature flag is enabled.
+ */
+export type Enabled = boolean;
+/**
+ * Feature flag value.
+ */
+export type Value = string | number | boolean | null;
+/**
+ * Reason for the feature flag evaluation.
+ */
+export type Reason = string;
+/**
+ * Segment name.
+ */
+export type Name1 = string;
+/**
+ * List of segments which the provided context belongs to.
+ */
+export type Segments = SegmentResult[];
+
+/**
+ * Evaluation result object containing the used context, flag evaluation results, and segments used in the evaluation.
+ */
+export interface EvaluationResult {
+    flags: Flags;
+    segments: Segments;
+    [k: string]: unknown;
+}
+/**
+ * Feature flags evaluated for the context, mapped by feature names.
+ */
+export interface Flags {
+    [k: string]: FlagResult;
+}
+export interface FlagResult {
+    name: Name;
+    enabled: Enabled;
+    value: Value;
+    reason: Reason;
+    metadata?: FeatureMetadata;
+    [k: string]: unknown;
+}
+/**
+ * Additional metadata associated with the feature.
+ */
+export interface FeatureMetadata {
+    [k: string]: unknown;
+}
+export interface SegmentResult {
+    name: Name1;
+    metadata?: SegmentMetadata;
+    [k: string]: unknown;
+}
+/**
+ * Additional metadata associated with the segment.
+ */
+export interface SegmentMetadata {
+    [k: string]: unknown;
+}

package/flagsmith-engine/evaluation/models.ts

@@ -0,0 +1,96 @@
+// This file is the entry point for the evaluation module types
+// All types from evaluations should be at least imported here and re-exported
+// Do not use types directly from generated files
+
+import type {
+    EvaluationResult as EvaluationContextResult,
+    FlagResult,
+    FeatureMetadata,
+    SegmentMetadata
+} from './evaluationResult/evaluationResult.types.js';
+
+import type {
+    FeatureContext,
+    EnvironmentContext,
+    IdentityContext,
+    SegmentContext
+} from './evaluationContext/evaluationContext.types.js';
+
+export * from './evaluationContext/evaluationContext.types.js';
+
+export enum SegmentSource {
+    API = 'api',
+    IDENTITY_OVERRIDE = 'identity_override'
+}
+
+// Feature types
+export interface SDKFeatureMetadata extends FeatureMetadata {
+    id: number;
+}
+
+export interface FeatureContextWithMetadata<T extends FeatureMetadata = FeatureMetadata>
+    extends FeatureContext {
+    metadata: T;
+    [k: string]: unknown;
+}
+
+export type FeaturesWithMetadata<T extends FeatureMetadata = FeatureMetadata> = {
+    [k: string]: FeatureContextWithMetadata<T>;
+};
+
+export type FlagResultWithMetadata<T extends FeatureMetadata = FeatureMetadata> = FlagResult & {
+    metadata: T;
+};
+
+export type EvaluationResultFlags<T extends FeatureMetadata = FeatureMetadata> = Record<
+    string,
+    FlagResultWithMetadata<T>
+>;
+
+// Segment types
+export interface SDKSegmentMetadata extends SegmentMetadata {
+    id?: number;
+    source?: SegmentSource;
+}
+
+export interface SegmentContextWithMetadata<T extends SegmentMetadata = SegmentMetadata>
+    extends SegmentContext {
+    metadata: T;
+    overrides?: FeatureContextWithMetadata<FeatureMetadata>[];
+}
+
+export type SegmentsWithMetadata<T extends SegmentMetadata = SegmentMetadata> = {
+    [k: string]: SegmentContextWithMetadata<T>;
+};
+
+export interface SegmentResultWithMetadata {
+    name: string;
+    metadata: SDKSegmentMetadata;
+}
+
+export type EvaluationResultSegments = SegmentResultWithMetadata[];
+
+// Evaluation context types
+export interface GenericEvaluationContext<
+    T extends FeatureMetadata = FeatureMetadata,
+    S extends SegmentMetadata = SegmentMetadata
+> {
+    environment: EnvironmentContext;
+    identity?: IdentityContext | null;
+    segments?: SegmentsWithMetadata<S>;
+    features?: FeaturesWithMetadata<T>;
+    [k: string]: unknown;
+}
+
+export type EvaluationContextWithMetadata = GenericEvaluationContext<
+    SDKFeatureMetadata,
+    SDKSegmentMetadata
+>;
+
+// Evaluation result types
+export type EvaluationResult<T extends FeatureMetadata = FeatureMetadata> = {
+    flags: EvaluationResultFlags<T>;
+    segments: EvaluationResultSegments;
+};
+
+export type EvaluationResultWithMetadata = EvaluationResult<SDKFeatureMetadata>;

package/flagsmith-engine/features/models.ts

@@ -1,5 +1,5 @@
 import { randomUUID as uuidv4 } from 'node:crypto';
-import { getHashedPercentateForObjIds } from '../utils/hashing/index.js';
+import { getHashedPercentageForObjIds } from '../utils/hashing/index.js';
 
 export class FeatureModel {
     id: number;
@@ -103,6 +103,7 @@ export class FeatureStateModel {
         const sortedF = this.multivariateFeatureStateValues.sort((a, b) => {
             return a.id - b.id;
         });
+
         for (const myValue of sortedF) {
             switch (myValue.percentageAllocation) {
                 case 0:
@@ -111,7 +112,7 @@ export class FeatureStateModel {
                     return myValue.multivariateFeatureOption.value;
                 default:
                     if (percentageValue === undefined) {
-                        percentageValue = getHashedPercentateForObjIds([
+                        percentageValue = getHashedPercentageForObjIds([
                             this.djangoID || this.featurestateUUID,
                             identityID
                         ]);

package/flagsmith-engine/features/types.ts

@@ -0,0 +1,5 @@
+export enum TARGETING_REASONS {
+    DEFAULT = 'DEFAULT',
+    TARGETING_MATCH = 'TARGETING_MATCH',
+    SPLIT = 'SPLIT'
+}

package/flagsmith-engine/features/util.ts

@@ -46,3 +46,7 @@ export function buildFeatureStateModel(featuresStateModelJSON: any): FeatureStat
 export function buildFeatureSegment(featureSegmentJSON: any): FeatureSegment {
     return new FeatureSegment(featureSegmentJSON.priority);
 }
+
+export function uuidToBigInt(uuid: string): BigInt {
+    return BigInt('0x' + uuid.replace(/-/g, ''));
+}

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';