@ninetailed/experience.js-react 7.11.1 → 7.12.0

package/index.cjs.js

@@ -151,6 +151,83 @@ const usePersonalize = (baseline, variants, options = {
   return experience_js.selectVariant(baseline, variants, profile, options);
 };
 
+/**
+ * Custom hook to retrieve a specific feature flag from Ninetailed changes.
+ *
+ * @param flagKey - The key of the feature flag to retrieve
+ * @param defaultValue - The default value to use if the flag is not found
+ * @returns An object containing the flag value and status information
+ */
+function useFlag(flagKey, defaultValue) {
+  const ninetailed = useNinetailed();
+  const lastProcessedState = React.useRef(null);
+  const [result, setResult] = React.useState({
+    value: defaultValue,
+    status: 'loading',
+    error: null
+  });
+  React.useEffect(() => {
+    // Reset state when dependencies change
+    setResult({
+      value: defaultValue,
+      status: 'loading',
+      error: null
+    });
+    lastProcessedState.current = null;
+    const unsubscribe = ninetailed.onChangesChange(changesState => {
+      if (lastProcessedState.current && radash.isEqual(lastProcessedState.current, changesState)) {
+        experience_jsShared.logger.debug('Change State Did Not Change', changesState);
+        return;
+      }
+      lastProcessedState.current = changesState;
+      if (changesState.status === 'loading') {
+        // Don't use a function updater here to avoid type issues
+        setResult({
+          value: defaultValue,
+          status: 'loading',
+          error: null
+        });
+        return;
+      }
+      if (changesState.status === 'error') {
+        setResult({
+          value: defaultValue,
+          status: 'error',
+          error: changesState.error
+        });
+        return;
+      }
+      try {
+        // Find the change with our flag key
+        const change = changesState.changes.find(change => change.key === flagKey);
+        if (change && change.type === experience_jsShared.ChangeTypes.Variable) {
+          const flagValue = change.value;
+          setResult({
+            value: flagValue,
+            status: 'success',
+            error: null
+          });
+        } else {
+          // Flag not found or wrong type, use default
+          setResult({
+            value: defaultValue,
+            status: 'success',
+            error: null
+          });
+        }
+      } catch (error) {
+        setResult({
+          value: defaultValue,
+          status: 'error',
+          error: error instanceof Error ? error : new Error(String(error))
+        });
+      }
+    });
+    return unsubscribe;
+  }, [ninetailed, flagKey, defaultValue]);
+  return result;
+}
+
 const TrackHasSeenComponent = ({
   children,
   variant,
@@ -615,6 +692,7 @@ exports.NinetailedProvider = NinetailedProvider;
 exports.Personalize = Personalize;
 exports.TrackHasSeenComponent = TrackHasSeenComponent;
 exports.useExperience = useExperience;
+exports.useFlag = useFlag;
 exports.useNinetailed = useNinetailed;
 exports.usePersonalize = usePersonalize;
 exports.useProfile = useProfile;

package/index.esm.js

@@ -1,7 +1,7 @@
 import React, { createContext, useMemo, useContext, useState, useRef, useEffect, createElement, forwardRef } from 'react';
 import { Ninetailed, selectVariant, selectHasExperienceVariants } from '@ninetailed/experience.js';
 import { jsx, jsxs, Fragment } from 'react/jsx-runtime';
-import { logger, isBrowser } from '@ninetailed/experience.js-shared';
+import { logger, ChangeTypes, isBrowser } from '@ninetailed/experience.js-shared';
 import { isEqual, get } from 'radash';
 import { isForwardRef } from 'react-is';
 
@@ -132,6 +132,83 @@ const usePersonalize = (baseline, variants, options = {
   return selectVariant(baseline, variants, profile, options);
 };
 
+/**
+ * Custom hook to retrieve a specific feature flag from Ninetailed changes.
+ *
+ * @param flagKey - The key of the feature flag to retrieve
+ * @param defaultValue - The default value to use if the flag is not found
+ * @returns An object containing the flag value and status information
+ */
+function useFlag(flagKey, defaultValue) {
+  const ninetailed = useNinetailed();
+  const lastProcessedState = useRef(null);
+  const [result, setResult] = useState({
+    value: defaultValue,
+    status: 'loading',
+    error: null
+  });
+  useEffect(() => {
+    // Reset state when dependencies change
+    setResult({
+      value: defaultValue,
+      status: 'loading',
+      error: null
+    });
+    lastProcessedState.current = null;
+    const unsubscribe = ninetailed.onChangesChange(changesState => {
+      if (lastProcessedState.current && isEqual(lastProcessedState.current, changesState)) {
+        logger.debug('Change State Did Not Change', changesState);
+        return;
+      }
+      lastProcessedState.current = changesState;
+      if (changesState.status === 'loading') {
+        // Don't use a function updater here to avoid type issues
+        setResult({
+          value: defaultValue,
+          status: 'loading',
+          error: null
+        });
+        return;
+      }
+      if (changesState.status === 'error') {
+        setResult({
+          value: defaultValue,
+          status: 'error',
+          error: changesState.error
+        });
+        return;
+      }
+      try {
+        // Find the change with our flag key
+        const change = changesState.changes.find(change => change.key === flagKey);
+        if (change && change.type === ChangeTypes.Variable) {
+          const flagValue = change.value;
+          setResult({
+            value: flagValue,
+            status: 'success',
+            error: null
+          });
+        } else {
+          // Flag not found or wrong type, use default
+          setResult({
+            value: defaultValue,
+            status: 'success',
+            error: null
+          });
+        }
+      } catch (error) {
+        setResult({
+          value: defaultValue,
+          status: 'error',
+          error: error instanceof Error ? error : new Error(String(error))
+        });
+      }
+    });
+    return unsubscribe;
+  }, [ninetailed, flagKey, defaultValue]);
+  return result;
+}
+
 const TrackHasSeenComponent = ({
   children,
   variant,
@@ -590,4 +667,4 @@ const ESRLoadingComponent = _ref => {
   }));
 };
 
-export { DefaultExperienceLoadingComponent, ESRLoadingComponent, ESRProvider, Experience, MergeTag, NinetailedProvider, Personalize, TrackHasSeenComponent, useExperience, useNinetailed, usePersonalize, useProfile };
+export { DefaultExperienceLoadingComponent, ESRLoadingComponent, ESRProvider, Experience, MergeTag, NinetailedProvider, Personalize, TrackHasSeenComponent, useExperience, useFlag, useNinetailed, usePersonalize, useProfile };

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@ninetailed/experience.js-react",
-  "version": "7.11.1",
+  "version": "7.12.0",
   "description": "Ninetailed SDK for React",
   "dependencies": {
-    "@ninetailed/experience.js": "7.11.1",
-    "@ninetailed/experience.js-shared": "7.11.1",
-    "@ninetailed/experience.js-plugin-analytics": "7.11.1",
+    "@ninetailed/experience.js": "7.12.0",
+    "@ninetailed/experience.js-shared": "7.12.0",
+    "@ninetailed/experience.js-plugin-analytics": "7.12.0",
     "radash": "10.9.0",
     "react-is": "18.2.0"
   },

package/src/lib/index.d.ts

@@ -5,6 +5,7 @@ export type { NinetailedProviderProps, NinetailedProviderInstantiationProps, } f
 export { useNinetailed } from './useNinetailed';
 export { useProfile } from './useProfile';
 export { usePersonalize } from './usePersonalize';
+export { useFlag } from './useFlag';
 export { Personalize } from './Personalize';
 export type { PersonalizedComponent } from './Personalize';
 export { MergeTag } from './MergeTag';

package/src/lib/useFlag.d.ts

@@ -0,0 +1,22 @@
+import { AllowedVariableType } from '@ninetailed/experience.js-shared';
+export type FlagResult<T> = {
+    status: 'loading';
+    value: T;
+    error: null;
+} | {
+    status: 'success';
+    value: T;
+    error: null;
+} | {
+    status: 'error';
+    value: T;
+    error: Error;
+};
+/**
+ * Custom hook to retrieve a specific feature flag from Ninetailed changes.
+ *
+ * @param flagKey - The key of the feature flag to retrieve
+ * @param defaultValue - The default value to use if the flag is not found
+ * @returns An object containing the flag value and status information
+ */
+export declare function useFlag<T extends AllowedVariableType>(flagKey: string, defaultValue: T): FlagResult<T>;