feat: add support for fallback treatments when client is not operational

Author: EmilianoSanchez

.github/workflows/ci-cd.yml

@@ -49,7 +49,7 @@ jobs:
         run: echo "VERSION=$(cat package.json | jq -r .version)" >> $GITHUB_ENV
 
       - name: SonarQube Scan (Push)
-        if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/development')
+        if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/fallback-treatment-support')
         uses: SonarSource/sonarcloud-github-action@v1.9
         env:
           SONAR_TOKEN: ${{ secrets.SONARQUBE_TOKEN }}
@@ -77,7 +77,7 @@ jobs:
             -Dsonar.pullrequest.base=${{ github.event.pull_request.base.ref }}
 
       - name: Store assets
-        if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/development')
+        if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/fallback-treatment-support')
         uses: actions/upload-artifact@v4
         with:
           name: assets
@@ -88,7 +88,7 @@ jobs:
     name: Upload assets
     runs-on: ubuntu-latest
     needs: build
-    if: github.event_name == 'push' && github.ref == 'refs/heads/development'
+    if: github.event_name == 'push' && github.ref == 'refs/heads/fallback-treatment-support'
     strategy:
       matrix:
         environment:

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@splitsoftware/splitio-react",
-  "version": "2.5.0",
+  "version": "2.5.1-rc.0",
   "description": "A React library to easily integrate and use Split JS SDK",
   "main": "cjs/index.js",
   "module": "esm/index.js",
@@ -63,7 +63,7 @@
   },
   "homepage": "https://github.com/splitio/react-client#readme",
   "dependencies": {
-    "@splitsoftware/splitio": "11.7.2-rc.4",
+    "@splitsoftware/splitio": "11.7.2-rc.5",
     "memoize-one": "^5.1.1",
     "shallowequal": "^1.1.0",
     "tslib": "^2.3.1"

package.json

@@ -19,14 +19,14 @@ import { useSplitClient } from './useSplitClient';
  */
 export function useTreatment(options: IUseTreatmentOptions): IUseTreatmentResult {
   const context = useSplitClient({ ...options, attributes: undefined });
-  const { client, lastUpdate } = context;
+  const { factory, client, lastUpdate } = context;
   const { name, attributes, properties } = options;
 
   const getTreatment = React.useMemo(memoizeGetTreatment, []);
 
   // Shallow copy `client.getAttributes` result for memoization, as it returns the same reference unless `client.clearAttributes` is invoked.
   // Note: the same issue occurs with the `names` and `attributes` arguments if they are mutated directly by the user instead of providing a new object.
-  const treatment = getTreatment(client, lastUpdate, [name], attributes, client ? { ...client.getAttributes() } : {}, undefined, properties && { properties });
+  const treatment = getTreatment(client, lastUpdate, [name], attributes, client ? { ...client.getAttributes() } : {}, undefined, properties && { properties }, factory);
 
   return {
     ...context,

src/useTreatment.ts

@@ -19,14 +19,14 @@ import { useSplitClient } from './useSplitClient';
  */
 export function useTreatmentWithConfig(options: IUseTreatmentOptions): IUseTreatmentWithConfigResult {
   const context = useSplitClient({ ...options, attributes: undefined });
-  const { client, lastUpdate } = context;
+  const { factory, client, lastUpdate } = context;
   const { name, attributes, properties } = options;
 
   const getTreatmentWithConfig = React.useMemo(memoizeGetTreatmentWithConfig, []);
 
   // Shallow copy `client.getAttributes` result for memoization, as it returns the same reference unless `client.clearAttributes` is invoked.
   // Note: the same issue occurs with the `names` and `attributes` arguments if they are mutated directly by the user instead of providing a new object.
-  const treatment = getTreatmentWithConfig(client, lastUpdate, [name], attributes, client ? { ...client.getAttributes() } : {}, undefined, properties && { properties });
+  const treatment = getTreatmentWithConfig(client, lastUpdate, [name], attributes, client ? { ...client.getAttributes() } : {}, undefined, properties && { properties }, factory);
 
   return {
     ...context,

src/useTreatmentWithConfig.ts

@@ -20,14 +20,14 @@ import { useSplitClient } from './useSplitClient';
  */
 export function useTreatments(options: IUseTreatmentsOptions): IUseTreatmentsResult {
   const context = useSplitClient({ ...options, attributes: undefined });
-  const { client, lastUpdate } = context;
+  const { factory, client, lastUpdate } = context;
   const { names, flagSets, attributes, properties } = options;
 
   const getTreatments = React.useMemo(memoizeGetTreatments, []);
 
   // Shallow copy `client.getAttributes` result for memoization, as it returns the same reference unless `client.clearAttributes` is invoked.
   // Note: the same issue occurs with the `names` and `attributes` arguments if they are mutated directly by the user instead of providing a new object.
-  const treatments = getTreatments(client, lastUpdate, names, attributes, client ? { ...client.getAttributes() } : {}, flagSets, properties && { properties });
+  const treatments = getTreatments(client, lastUpdate, names, attributes, client ? { ...client.getAttributes() } : {}, flagSets, properties && { properties }, factory);
 
   return {
     ...context,

src/useTreatments.ts

@@ -20,14 +20,14 @@ import { useSplitClient } from './useSplitClient';
  */
 export function useTreatmentsWithConfig(options: IUseTreatmentsOptions): IUseTreatmentsWithConfigResult {
   const context = useSplitClient({ ...options, attributes: undefined });
-  const { client, lastUpdate } = context;
+  const { factory, client, lastUpdate } = context;
   const { names, flagSets, attributes, properties } = options;
 
   const getTreatmentsWithConfig = React.useMemo(memoizeGetTreatmentsWithConfig, []);
 
   // Shallow copy `client.getAttributes` result for memoization, as it returns the same reference unless `client.clearAttributes` is invoked.
   // Note: the same issue occurs with the `names` and `attributes` arguments if they are mutated directly by the user instead of providing a new object.
-  const treatments = getTreatmentsWithConfig(client, lastUpdate, names, attributes, client ? { ...client.getAttributes() } : {}, flagSets, properties && { properties });
+  const treatments = getTreatmentsWithConfig(client, lastUpdate, names, attributes, client ? { ...client.getAttributes() } : {}, flagSets, properties && { properties }, factory);
 
   return {
     ...context,

src/useTreatmentsWithConfig.ts

@@ -37,6 +37,24 @@ export function getStatus(client?: SplitIO.IBrowserClient): ISplitStatus {
     };
 }
 
+function resolveFallback(flagName: string, withConfig: true, factory?: SplitIO.IBrowserSDK): SplitIO.TreatmentWithConfig;
+function resolveFallback(flagName: string, withConfig: false, factory?: SplitIO.IBrowserSDK): SplitIO.Treatment;
+function resolveFallback(flagName: string, withConfig: boolean, factory?: SplitIO.IBrowserSDK): SplitIO.Treatment | SplitIO.TreatmentWithConfig {
+  if (factory && factory.settings.fallbackTreatments) {
+    const fallbacks = factory.settings.fallbackTreatments;
+
+    const treatment = fallbacks.byFlag?.[flagName] || fallbacks.global;
+
+    if (treatment) {
+      return isString(treatment) ?
+        withConfig ? { treatment, config: null } : treatment :
+        withConfig ? treatment : treatment.treatment;
+    }
+  }
+
+  return withConfig ? CONTROL_WITH_CONFIG : CONTROL;
+}
+
 /**
  * Manage client attributes binding
  */
@@ -45,9 +63,9 @@ export function initAttributes(client?: SplitIO.IBrowserClient, attributes?: Spl
   if (client && attributes) client.setAttributes(attributes);
 }
 
-export function getControlTreatments(featureFlagNames: unknown, withConfig: true): SplitIO.TreatmentsWithConfig;
-export function getControlTreatments(featureFlagNames: unknown, withConfig: false): SplitIO.Treatments;
-export function getControlTreatments(featureFlagNames: unknown, withConfig: boolean): SplitIO.Treatments | SplitIO.TreatmentsWithConfig {
+export function getControlTreatments(featureFlagNames: unknown, withConfig: true, factory?: SplitIO.IBrowserSDK): SplitIO.TreatmentsWithConfig;
+export function getControlTreatments(featureFlagNames: unknown, withConfig: false, factory?: SplitIO.IBrowserSDK): SplitIO.Treatments;
+export function getControlTreatments(featureFlagNames: unknown, withConfig: boolean, factory?: SplitIO.IBrowserSDK): SplitIO.Treatments | SplitIO.TreatmentsWithConfig {
   // validate feature flag names
   if (!Array.isArray(featureFlagNames)) return {};
 
@@ -56,9 +74,10 @@ export function getControlTreatments(featureFlagNames: unknown, withConfig: bool
     .map((featureFlagName) => featureFlagName.trim())
     .filter((featureFlagName) => featureFlagName.length > 0);
 
-  // return control treatments for each validated feature flag name
-  return (featureFlagNames as string[]).reduce((pValue: SplitIO.Treatments | SplitIO.TreatmentsWithConfig, cValue: string) => {
-    pValue[cValue] = withConfig ? CONTROL_WITH_CONFIG : CONTROL;
+  // return control or fallback treatment for each validated feature flag name
+  return (featureFlagNames as string[]).reduce((pValue: SplitIO.Treatments | SplitIO.TreatmentsWithConfig, featureFlagName: string) => {
+    // @ts-expect-error asd
+    pValue[featureFlagName] = resolveFallback(featureFlagName, withConfig, factory);
     return pValue;
   }, {});
 }
@@ -79,13 +98,13 @@ function argsAreEqual(newArgs: any[], lastArgs: any[]): boolean {
     shallowEqual(newArgs[5], lastArgs[5]); // flagSets
 }
 
-function evaluateFeatureFlagsWithConfig(client: SplitIO.IBrowserClient | undefined, _lastUpdate: number, names?: SplitIO.SplitNames, attributes?: SplitIO.Attributes, _clientAttributes?: SplitIO.Attributes, flagSets?: string[], options?: SplitIO.EvaluationOptions) {
+function evaluateFeatureFlagsWithConfig(client: SplitIO.IBrowserClient | undefined, _lastUpdate: number, names?: SplitIO.SplitNames, attributes?: SplitIO.Attributes, _clientAttributes?: SplitIO.Attributes, flagSets?: string[], options?: SplitIO.EvaluationOptions, factory?: SplitIO.IBrowserSDK) {
   return client && client.getStatus().isOperational && (names || flagSets) ?
     names ?
       client.getTreatmentsWithConfig(names, attributes, options) :
       client.getTreatmentsWithConfigByFlagSets(flagSets!, attributes, options) :
     names ?
-      getControlTreatments(names, true) :
+      getControlTreatments(names, true, factory) :
       {} // empty object when evaluating with flag sets and client is not ready
 }
 
@@ -97,34 +116,34 @@ export function memoizeGetTreatmentsWithConfig() {
   return memoizeOne(evaluateFeatureFlagsWithConfig, argsAreEqual);
 }
 
-function evaluateFeatureFlags(client: SplitIO.IBrowserClient | undefined, _lastUpdate: number, names?: SplitIO.SplitNames, attributes?: SplitIO.Attributes, _clientAttributes?: SplitIO.Attributes, flagSets?: string[], options?: SplitIO.EvaluationOptions) {
+function evaluateFeatureFlags(client: SplitIO.IBrowserClient | undefined, _lastUpdate: number, names?: SplitIO.SplitNames, attributes?: SplitIO.Attributes, _clientAttributes?: SplitIO.Attributes, flagSets?: string[], options?: SplitIO.EvaluationOptions, factory?: SplitIO.IBrowserSDK) {
   return client && client.getStatus().isOperational && (names || flagSets) ?
     names ?
       client.getTreatments(names, attributes, options) :
       client.getTreatmentsByFlagSets(flagSets!, attributes, options) :
     names ?
-      getControlTreatments(names, false) :
+      getControlTreatments(names, false, factory) :
       {} // empty object when evaluating with flag sets and client is not ready
 }
 
 export function memoizeGetTreatments() {
   return memoizeOne(evaluateFeatureFlags, argsAreEqual);
 }
 
-function evaluateFeatureFlagWithConfig(client: SplitIO.IBrowserClient | undefined, _lastUpdate: number, names: string[], attributes?: SplitIO.Attributes, _clientAttributes?: SplitIO.Attributes, _flagSets?: undefined, options?: SplitIO.EvaluationOptions) {
+function evaluateFeatureFlagWithConfig(client: SplitIO.IBrowserClient | undefined, _lastUpdate: number, names: string[], attributes?: SplitIO.Attributes, _clientAttributes?: SplitIO.Attributes, _flagSets?: undefined, options?: SplitIO.EvaluationOptions, factory?: SplitIO.IBrowserSDK) {
   return client && client.getStatus().isOperational ?
     client.getTreatmentWithConfig(names[0], attributes, options) :
-    CONTROL_WITH_CONFIG
+    resolveFallback(names[0], true, factory);
 }
 
 export function memoizeGetTreatmentWithConfig() {
   return memoizeOne(evaluateFeatureFlagWithConfig, argsAreEqual);
 }
 
-function evaluateFeatureFlag(client: SplitIO.IBrowserClient | undefined, _lastUpdate: number, names: string[], attributes?: SplitIO.Attributes, _clientAttributes?: SplitIO.Attributes, _flagSets?: undefined, options?: SplitIO.EvaluationOptions) {
+function evaluateFeatureFlag(client: SplitIO.IBrowserClient | undefined, _lastUpdate: number, names: string[], attributes?: SplitIO.Attributes, _clientAttributes?: SplitIO.Attributes, _flagSets?: undefined, options?: SplitIO.EvaluationOptions, factory?: SplitIO.IBrowserSDK) {
   return client && client.getStatus().isOperational ?
     client.getTreatment(names[0], attributes, options) :
-    CONTROL;
+    resolveFallback(names[0], false, factory);
 }
 
 export function memoizeGetTreatment() {