refactor: reorganize utils.ts with better code structure and documentation

Author: EmilianoSanchez

MIGRATION-GUIDE.md

@@ -9,7 +9,7 @@ React SDK v2.0.0 has a few breaking changes that you should consider when migrat
 Since v2.6.0, there are 4 hooks variants to evaluate feature flags, to better cover the different evaluation methods available in the JavaScript SDK client:
 
 - `useTreatment`: returns a treatment value for a given feature flag name. It calls `client.getTreatment()` method under the hood.
-- `useTreatmentWithConfig`: returns a single treatment value and its configuration for a given feature flag name. It calls `client.getTreatmentWithConfig()` method under the hood.
+- `useTreatmentWithConfig`: returns a treatment value and its configuration for a given feature flag name. It calls `client.getTreatmentWithConfig()` method under the hood.
 - `useTreatments`: returns an object with treatment values for multiple feature flag names. It calls `client.getTreatments()` or `client.getTreatmentsByFlagSets()` methods under the hood, depending if the `names` or `flagSets` option is provided.
 - `useTreatmentsWithConfig`: returns an object with treatment values and their configurations for multiple feature flag names. It calls `client.getTreatmentsWithConfig()` or `client.getTreatmentsWithConfigByFlagSets()` methods under the hood, depending if the `names` or `flagSets` option is provided.
 

src/utils.ts

@@ -3,14 +3,12 @@ import shallowEqual from 'shallowequal';
 import { CONTROL, CONTROL_WITH_CONFIG } from './constants';
 import { ISplitStatus } from './types';
 
-// Utils used to access singleton instances of Split factories and clients
-
-export interface IFactoryWithLazyInit extends SplitIO.IBrowserSDK {
-  config: SplitIO.IBrowserSettings;
-  init(): void;
+function isString(val: unknown): val is string {
+  return typeof val === 'string' || val instanceof String;
 }
 
-// idempotent operation
+// Utils used to access singleton instances of Split factories and clients:
+
 export function getSplitClient(factory: SplitIO.IBrowserSDK, key?: SplitIO.SplitKey): SplitIO.IBrowserClient {
   // factory.client is an idempotent operation
   const client = key !== undefined ? factory.client(key) : factory.client();
@@ -22,7 +20,6 @@ export function getSplitClient(factory: SplitIO.IBrowserSDK, key?: SplitIO.Split
   return client;
 }
 
-// Util used to get client status.
 export function getStatus(client?: SplitIO.IBrowserClient): ISplitStatus {
   return client ?
     client.getStatus() :
@@ -37,9 +34,18 @@ export function getStatus(client?: SplitIO.IBrowserClient): ISplitStatus {
     };
 }
 
+// Manage client attributes binding
+// @TODO should reset attributes rather than set/merge them, to keep SFP and hooks pure.
+export function initAttributes(client?: SplitIO.IBrowserClient, attributes?: SplitIO.Attributes) {
+  if (client && attributes) client.setAttributes(attributes);
+}
+
+// Utils used to retrieve treatments when the client is not operational:
+
 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 {
+function resolveFallback(flagName: string, withConfig: boolean, factory?: SplitIO.IBrowserSDK): SplitIO.Treatment | SplitIO.TreatmentWithConfig;
+function resolveFallback(flagName: string, withConfig: boolean, factory?: SplitIO.IBrowserSDK) {
   if (factory && factory.settings.fallbackTreatments) {
     const fallbacks = factory.settings.fallbackTreatments;
 
@@ -55,17 +61,9 @@ function resolveFallback(flagName: string, withConfig: boolean, factory?: SplitI
   return withConfig ? CONTROL_WITH_CONFIG : CONTROL;
 }
 
-/**
- * Manage client attributes binding
- */
-// @TODO should reset attributes rather than set/merge them, to keep SFP and hooks pure.
-export function initAttributes(client?: SplitIO.IBrowserClient, attributes?: SplitIO.Attributes) {
-  if (client && attributes) client.setAttributes(attributes);
-}
-
 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 {
+export function getControlTreatments(featureFlagNames: unknown, withConfig: boolean, factory?: SplitIO.IBrowserSDK) {
   // validate feature flag names
   if (!Array.isArray(featureFlagNames)) return {};
 
@@ -76,18 +74,15 @@ export function getControlTreatments(featureFlagNames: unknown, withConfig: bool
 
   // 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;
   }, {});
 }
 
 /**
- * Checks if a given value is a string.
+ * Utils to memoize `client.getTreatments*` method calls to avoid duplicated impressions.
+ * The result treatments are the same given the same `client` instance, `lastUpdate` timestamp, and list of feature flag names and attributes.
  */
-function isString(val: unknown): val is string {
-  return typeof val === 'string' || val instanceof String;
-}
 
 function argsAreEqual(newArgs: any[], lastArgs: any[]): boolean {
   return newArgs[0] === lastArgs[0] && // client
@@ -108,10 +103,6 @@ function evaluateFeatureFlagsWithConfig(client: SplitIO.IBrowserClient | undefin
       {} // empty object when evaluating with flag sets and client is not ready
 }
 
-/**
- * Gets a memoized version of the `client.getTreatmentsWithConfig` method.
- * It is used to avoid duplicated impressions, because the result treatments are the same given the same `client` instance, `lastUpdate` timestamp, and list of feature flag `names` and `attributes`.
- */
 export function memoizeGetTreatmentsWithConfig() {
   return memoizeOne(evaluateFeatureFlagsWithConfig, argsAreEqual);
 }