@microsoft/feature-management 1.0.0 → 2.0.0-preview.2

package/dist/umd/index.js

@@ -22,6 +22,119 @@
         }
     }
 
+    // Copyright (c) Microsoft Corporation.
+    // Licensed under the MIT license.
+    /**
+     * Determines if the user is part of the audience, based on the user id and the percentage range.
+     *
+     * @param userId user id from app context
+     * @param hint hint string to be included in the context id
+     * @param from percentage range start
+     * @param to percentage range end
+     * @returns true if the user is part of the audience, false otherwise
+     */
+    async function isTargetedPercentile(userId, hint, from, to) {
+        if (from < 0 || from > 100) {
+            throw new Error("The 'from' value must be between 0 and 100.");
+        }
+        if (to < 0 || to > 100) {
+            throw new Error("The 'to' value must be between 0 and 100.");
+        }
+        if (from > to) {
+            throw new Error("The 'from' value cannot be larger than the 'to' value.");
+        }
+        const audienceContextId = constructAudienceContextId(userId, hint);
+        // Cryptographic hashing algorithms ensure adequate entropy across hash values.
+        const contextMarker = await stringToUint32(audienceContextId);
+        const contextPercentage = (contextMarker / 0xFFFFFFFF) * 100;
+        // Handle edge case of exact 100 bucket
+        if (to === 100) {
+            return contextPercentage >= from;
+        }
+        return contextPercentage >= from && contextPercentage < to;
+    }
+    /**
+     * Determines if the user is part of the audience, based on the groups they belong to.
+     *
+     * @param sourceGroups user groups from app context
+     * @param targetedGroups targeted groups from feature configuration
+     * @returns true if the user is part of the audience, false otherwise
+     */
+    function isTargetedGroup(sourceGroups, targetedGroups) {
+        if (sourceGroups === undefined) {
+            return false;
+        }
+        return sourceGroups.some(group => targetedGroups.includes(group));
+    }
+    /**
+     * Determines if the user is part of the audience, based on the user id.
+     * @param userId user id from app context
+     * @param users targeted users from feature configuration
+     * @returns true if the user is part of the audience, false otherwise
+     */
+    function isTargetedUser(userId, users) {
+        if (userId === undefined) {
+            return false;
+        }
+        return users.includes(userId);
+    }
+    /**
+     * Constructs the context id for the audience.
+     * The context id is used to determine if the user is part of the audience for a feature.
+     *
+     * @param userId userId from app context
+     * @param hint hint string to be included in the context id
+     * @returns a string that represents the context id for the audience
+     */
+    function constructAudienceContextId(userId, hint) {
+        return `${userId ?? ""}\n${hint}`;
+    }
+    /**
+     * Converts a string to a uint32 in little-endian encoding.
+     * @param str the string to convert.
+     * @returns a uint32 value.
+     */
+    async function stringToUint32(str) {
+        let crypto;
+        // Check for browser environment
+        if (typeof window !== "undefined" && window.crypto && window.crypto.subtle) {
+            crypto = window.crypto;
+        }
+        // Check for Node.js environment
+        else if (typeof global !== "undefined" && global.crypto) {
+            crypto = global.crypto;
+        }
+        // Fallback to native Node.js crypto module
+        else {
+            try {
+                if (typeof module !== "undefined" && module.exports) {
+                    crypto = require("crypto");
+                }
+                else {
+                    crypto = await import('crypto');
+                }
+            }
+            catch (error) {
+                console.error("Failed to load the crypto module:", error.message);
+                throw error;
+            }
+        }
+        // In the browser, use crypto.subtle.digest
+        if (crypto.subtle) {
+            const data = new TextEncoder().encode(str);
+            const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+            const dataView = new DataView(hashBuffer);
+            const uint32 = dataView.getUint32(0, true);
+            return uint32;
+        }
+        // In Node.js, use the crypto module's hash function
+        else {
+            const hash = crypto.createHash("sha256").update(str).digest();
+            const uint32 = hash.readUInt32LE(0);
+            return uint32;
+        }
+    }
+
     // Copyright (c) Microsoft Corporation.
     // Licensed under the MIT license.
     class TargetingFilter {
@@ -60,26 +173,16 @@
                 parameters.Audience.Groups !== undefined) {
                 for (const group of parameters.Audience.Groups) {
                     if (appContext.groups.includes(group.Name)) {
-                        const audienceContextId = constructAudienceContextId(featureName, appContext.userId, group.Name);
-                        const rolloutPercentage = group.RolloutPercentage;
-                        if (await TargetingFilter.#isTargeted(audienceContextId, rolloutPercentage)) {
+                        const hint = `${featureName}\n${group.Name}`;
+                        if (await isTargetedPercentile(appContext.userId, hint, 0, group.RolloutPercentage)) {
                             return true;
                         }
                     }
                 }
             }
             // check if the user is being targeted by a default rollout percentage
-            const defaultContextId = constructAudienceContextId(featureName, appContext?.userId);
-            return TargetingFilter.#isTargeted(defaultContextId, parameters.Audience.DefaultRolloutPercentage);
-        }
-        static async #isTargeted(audienceContextId, rolloutPercentage) {
-            if (rolloutPercentage === 100) {
-                return true;
-            }
-            // Cryptographic hashing algorithms ensure adequate entropy across hash values.
-            const contextMarker = await stringToUint32(audienceContextId);
-            const contextPercentage = (contextMarker / 0xFFFFFFFF) * 100;
-            return contextPercentage < rolloutPercentage;
+            const hint = featureName;
+            return isTargetedPercentile(appContext?.userId, hint, 0, parameters.Audience.DefaultRolloutPercentage);
         }
         static #validateParameters(parameters) {
             if (parameters.Audience.DefaultRolloutPercentage < 0 || parameters.Audience.DefaultRolloutPercentage > 100) {
@@ -95,64 +198,15 @@
             }
         }
     }
-    /**
-     * Constructs the context id for the audience.
-     * The context id is used to determine if the user is part of the audience for a feature.
-     * If groupName is provided, the context id is constructed as follows:
-     *  userId + "\n" + featureName + "\n" + groupName
-     * Otherwise, the context id is constructed as follows:
-     *  userId + "\n" + featureName
-     *
-     * @param featureName name of the feature
-     * @param userId userId from app context
-     * @param groupName group name from app context
-     * @returns a string that represents the context id for the audience
-     */
-    function constructAudienceContextId(featureName, userId, groupName) {
-        let contextId = `${userId ?? ""}\n${featureName}`;
-        if (groupName !== undefined) {
-            contextId += `\n${groupName}`;
-        }
-        return contextId;
-    }
-    async function stringToUint32(str) {
-        let crypto;
-        // Check for browser environment
-        if (typeof window !== "undefined" && window.crypto && window.crypto.subtle) {
-            crypto = window.crypto;
-        }
-        // Check for Node.js environment
-        else if (typeof global !== "undefined" && global.crypto) {
-            crypto = global.crypto;
-        }
-        // Fallback to native Node.js crypto module
-        else {
-            try {
-                if (typeof module !== "undefined" && module.exports) {
-                    crypto = require("crypto");
-                }
-                else {
-                    crypto = await import('crypto');
-                }
-            }
-            catch (error) {
-                console.error("Failed to load the crypto module:", error.message);
-                throw error;
-            }
-        }
-        // In the browser, use crypto.subtle.digest
-        if (crypto.subtle) {
-            const data = new TextEncoder().encode(str);
-            const hashBuffer = await crypto.subtle.digest("SHA-256", data);
-            const dataView = new DataView(hashBuffer);
-            const uint32 = dataView.getUint32(0, true);
-            return uint32;
-        }
-        // In Node.js, use the crypto module's hash function
-        else {
-            const hash = crypto.createHash("sha256").update(str).digest();
-            const uint32 = hash.readUInt32LE(0);
-            return uint32;
+
+    // Copyright (c) Microsoft Corporation.
+    // Licensed under the MIT license.
+    class Variant {
+        name;
+        configuration;
+        constructor(name, configuration) {
+            this.name = name;
+            this.configuration = configuration;
         }
     }
 
@@ -161,6 +215,7 @@
     class FeatureManager {
         #provider;
         #featureFilters = new Map();
+        #onFeatureEvaluated;
         constructor(provider, options) {
             this.#provider = provider;
             const builtinFilters = [new TimeWindowFilter(), new TargetingFilter()];
@@ -168,6 +223,7 @@
             for (const filter of [...builtinFilters, ...(options?.customFilters ?? [])]) {
                 this.#featureFilters.set(filter.name, filter);
             }
+            this.#onFeatureEvaluated = options?.onFeatureEvaluated;
         }
         async listFeatureNames() {
             const features = await this.#provider.getFeatureFlags();
@@ -176,13 +232,42 @@
         }
         // If multiple feature flags are found, the first one takes precedence.
         async isEnabled(featureName, context) {
-            const featureFlag = await this.#provider.getFeatureFlag(featureName);
-            if (featureFlag === undefined) {
-                // If the feature is not found, then it is disabled.
-                return false;
+            const result = await this.#evaluateFeature(featureName, context);
+            return result.enabled;
+        }
+        async getVariant(featureName, context) {
+            const result = await this.#evaluateFeature(featureName, context);
+            return result.variant;
+        }
+        async #assignVariant(featureFlag, context) {
+            // user allocation
+            if (featureFlag.allocation?.user !== undefined) {
+                for (const userAllocation of featureFlag.allocation.user) {
+                    if (isTargetedUser(context.userId, userAllocation.users)) {
+                        return getVariantAssignment(featureFlag, userAllocation.variant, exports.VariantAssignmentReason.User);
+                    }
+                }
             }
-            // Ensure that the feature flag is in the correct format. Feature providers should validate the feature flags, but we do it here as a safeguard.
-            validateFeatureFlagFormat(featureFlag);
+            // group allocation
+            if (featureFlag.allocation?.group !== undefined) {
+                for (const groupAllocation of featureFlag.allocation.group) {
+                    if (isTargetedGroup(context.groups, groupAllocation.groups)) {
+                        return getVariantAssignment(featureFlag, groupAllocation.variant, exports.VariantAssignmentReason.Group);
+                    }
+                }
+            }
+            // percentile allocation
+            if (featureFlag.allocation?.percentile !== undefined) {
+                for (const percentileAllocation of featureFlag.allocation.percentile) {
+                    const hint = featureFlag.allocation.seed ?? `allocation\n${featureFlag.id}`;
+                    if (await isTargetedPercentile(context.userId, hint, percentileAllocation.from, percentileAllocation.to)) {
+                        return getVariantAssignment(featureFlag, percentileAllocation.variant, exports.VariantAssignmentReason.Percentile);
+                    }
+                }
+            }
+            return { variant: undefined, reason: exports.VariantAssignmentReason.None };
+        }
+        async #isEnabled(featureFlag, context) {
             if (featureFlag.enabled !== true) {
                 // If the feature is not explicitly enabled, then it is disabled by default.
                 return false;
@@ -201,7 +286,7 @@
             const shortCircuitEvaluationResult = requirementType === "Any";
             for (const clientFilter of clientFilters) {
                 const matchedFeatureFilter = this.#featureFilters.get(clientFilter.name);
-                const contextWithFeatureName = { featureName, parameters: clientFilter.parameters };
+                const contextWithFeatureName = { featureName: featureFlag.id, parameters: clientFilter.parameters };
                 if (matchedFeatureFilter === undefined) {
                     console.warn(`Feature filter ${clientFilter.name} is not found.`);
                     return false;
@@ -213,11 +298,153 @@
             // If we get here, then we have not found a client filter that matches the requirement type.
             return !shortCircuitEvaluationResult;
         }
+        async #evaluateFeature(featureName, context) {
+            const featureFlag = await this.#provider.getFeatureFlag(featureName);
+            const result = new EvaluationResult(featureFlag);
+            if (featureFlag === undefined) {
+                return result;
+            }
+            // Ensure that the feature flag is in the correct format. Feature providers should validate the feature flags, but we do it here as a safeguard.
+            // TODO: move to the feature flag provider implementation.
+            validateFeatureFlagFormat(featureFlag);
+            // Evaluate if the feature is enabled.
+            result.enabled = await this.#isEnabled(featureFlag, context);
+            const targetingContext = context;
+            result.targetingId = targetingContext?.userId;
+            // Determine Variant
+            let variantDef;
+            let reason = exports.VariantAssignmentReason.None;
+            // featureFlag.variant not empty
+            if (featureFlag.variants !== undefined && featureFlag.variants.length > 0) {
+                if (!result.enabled) {
+                    // not enabled, assign default if specified
+                    if (featureFlag.allocation?.default_when_disabled !== undefined) {
+                        variantDef = featureFlag.variants.find(v => v.name == featureFlag.allocation?.default_when_disabled);
+                        reason = exports.VariantAssignmentReason.DefaultWhenDisabled;
+                    }
+                    else {
+                        // no default specified
+                        variantDef = undefined;
+                        reason = exports.VariantAssignmentReason.DefaultWhenDisabled;
+                    }
+                }
+                else {
+                    // enabled, assign based on allocation
+                    if (context !== undefined && featureFlag.allocation !== undefined) {
+                        const variantAndReason = await this.#assignVariant(featureFlag, targetingContext);
+                        variantDef = variantAndReason.variant;
+                        reason = variantAndReason.reason;
+                    }
+                    // allocation failed, assign default if specified
+                    if (variantDef === undefined && reason === exports.VariantAssignmentReason.None) {
+                        if (featureFlag.allocation?.default_when_enabled !== undefined) {
+                            variantDef = featureFlag.variants.find(v => v.name == featureFlag.allocation?.default_when_enabled);
+                            reason = exports.VariantAssignmentReason.DefaultWhenEnabled;
+                        }
+                        else {
+                            variantDef = undefined;
+                            reason = exports.VariantAssignmentReason.DefaultWhenEnabled;
+                        }
+                    }
+                }
+            }
+            result.variant = variantDef !== undefined ? new Variant(variantDef.name, variantDef.configuration_value) : undefined;
+            result.variantAssignmentReason = reason;
+            // Status override for isEnabled
+            if (variantDef !== undefined && featureFlag.enabled) {
+                if (variantDef.status_override === "Enabled") {
+                    result.enabled = true;
+                }
+                else if (variantDef.status_override === "Disabled") {
+                    result.enabled = false;
+                }
+            }
+            // The callback will only be executed if telemetry is enabled for the feature flag
+            if (featureFlag.telemetry?.enabled && this.#onFeatureEvaluated !== undefined) {
+                this.#onFeatureEvaluated(result);
+            }
+            return result;
+        }
     }
+    class EvaluationResult {
+        feature;
+        enabled;
+        targetingId;
+        variant;
+        variantAssignmentReason;
+        constructor(
+        // feature flag definition
+        feature, 
+        // enabled state
+        enabled = false, 
+        // variant assignment
+        targetingId = undefined, variant = undefined, variantAssignmentReason = exports.VariantAssignmentReason.None) {
+            this.feature = feature;
+            this.enabled = enabled;
+            this.targetingId = targetingId;
+            this.variant = variant;
+            this.variantAssignmentReason = variantAssignmentReason;
+        }
+    }
+    exports.VariantAssignmentReason = void 0;
+    (function (VariantAssignmentReason) {
+        /**
+         * Variant allocation did not happen. No variant is assigned.
+         */
+        VariantAssignmentReason["None"] = "None";
+        /**
+         * The default variant is assigned when a feature flag is disabled.
+         */
+        VariantAssignmentReason["DefaultWhenDisabled"] = "DefaultWhenDisabled";
+        /**
+         * The default variant is assigned because of no applicable user/group/percentile allocation when a feature flag is enabled.
+         */
+        VariantAssignmentReason["DefaultWhenEnabled"] = "DefaultWhenEnabled";
+        /**
+         * The variant is assigned because of the user allocation when a feature flag is enabled.
+         */
+        VariantAssignmentReason["User"] = "User";
+        /**
+         * The variant is assigned because of the group allocation when a feature flag is enabled.
+         */
+        VariantAssignmentReason["Group"] = "Group";
+        /**
+         * The variant is assigned because of the percentile allocation when a feature flag is enabled.
+         */
+        VariantAssignmentReason["Percentile"] = "Percentile";
+    })(exports.VariantAssignmentReason || (exports.VariantAssignmentReason = {}));
+    /**
+     * Validates the format of the feature flag definition.
+     *
+     * FeatureFlag data objects are from IFeatureFlagProvider, depending on the implementation.
+     * Thus the properties are not guaranteed to have the expected types.
+     *
+     * @param featureFlag The feature flag definition to validate.
+     */
     function validateFeatureFlagFormat(featureFlag) {
         if (featureFlag.enabled !== undefined && typeof featureFlag.enabled !== "boolean") {
             throw new Error(`Feature flag ${featureFlag.id} has an invalid 'enabled' value.`);
         }
+        // TODO: add more validations.
+        // TODO: should be moved to the feature flag provider.
+    }
+    /**
+     * Try to get the variant assignment for the given variant name. If the variant is not found, override the reason with VariantAssignmentReason.None.
+     *
+     * @param featureFlag feature flag definition
+     * @param variantName variant name
+     * @param reason variant assignment reason
+     * @returns variant assignment containing the variant definition and the reason
+     */
+    function getVariantAssignment(featureFlag, variantName, reason) {
+        const variant = featureFlag.variants?.find(v => v.name == variantName);
+        if (variant !== undefined) {
+            return { variant, reason };
+        }
+        else {
+            console.warn(`Variant ${variantName} not found for feature ${featureFlag.id}.`);
+            return { variant: undefined, reason: exports.VariantAssignmentReason.None };
+        }
     }
 
     // Copyright (c) Microsoft Corporation.
@@ -239,7 +466,7 @@
         }
         async getFeatureFlag(featureName) {
             const featureConfig = this.#configuration.get(FEATURE_MANAGEMENT_KEY);
-            return featureConfig?.[FEATURE_FLAGS_KEY]?.findLast((feature) => feature.id === featureName);
+            return featureConfig?.[FEATURE_FLAGS_KEY]?.find((feature) => feature.id === featureName);
         }
         async getFeatureFlags() {
             const featureConfig = this.#configuration.get(FEATURE_MANAGEMENT_KEY);
@@ -256,7 +483,7 @@
         }
         async getFeatureFlag(featureName) {
             const featureFlags = this.#configuration[FEATURE_MANAGEMENT_KEY]?.[FEATURE_FLAGS_KEY];
-            return featureFlags?.findLast((feature) => feature.id === featureName);
+            return featureFlags?.find((feature) => feature.id === featureName);
         }
         async getFeatureFlags() {
             return this.#configuration[FEATURE_MANAGEMENT_KEY]?.[FEATURE_FLAGS_KEY] ?? [];
@@ -265,10 +492,11 @@
 
     // Copyright (c) Microsoft Corporation.
     // Licensed under the MIT license.
-    const VERSION = "1.0.0";
+    const VERSION = "2.0.0-preview.2";
 
     exports.ConfigurationMapFeatureFlagProvider = ConfigurationMapFeatureFlagProvider;
     exports.ConfigurationObjectFeatureFlagProvider = ConfigurationObjectFeatureFlagProvider;
+    exports.EvaluationResult = EvaluationResult;
     exports.FeatureManager = FeatureManager;
     exports.VERSION = VERSION;