Merge pull request #413 from splitio/refactor_usesSegmentsSync

EmilianoSanchez · web-flow · commit 134869ecc332 · 2025-07-24T13:50:28.000-03:00
Refactor: fix Type Definition comments and add `usesSegmentsSync` utility function for reusability
diff --git a/CHANGES.txt b/CHANGES.txt
@@ -9,7 +9,7 @@
  - Updated the Redis storage to:
     - Avoid lazy require of the `ioredis` dependency when the SDK is initialized, and
     - Flag the SDK as ready from cache immediately to allow queueing feature flag evaluations before SDK_READY event is emitted (Reverted in v1.7.0).
- - Bugfix - Enhanced HTTP client module to implement timeouts for failing requests that might otherwise remain pending indefinitely on some Fetch API implementations.
+ - Bugfix - Enhanced HTTP client module to implement timeouts for failing requests that might otherwise remain pending indefinitely on some Fetch API implementations, pausing the SDK synchronization process.
 
 2.2.0 (March 28, 2025)
  - Added a new optional argument to the client `getTreatment` methods to allow passing additional evaluation options, such as a map of properties to append to the generated impressions sent to Split backend. Read more in our docs.
diff --git a/package-lock.json b/package-lock.json
diff --git a/src/logger/messages/error.ts b/src/logger/messages/error.ts
@@ -14,7 +14,7 @@ export const codesError: [number, string][] = [
   [c.ERROR_SYNC_OFFLINE_LOADING, c.LOG_PREFIX_SYNC_OFFLINE + 'There was an issue loading the mock feature flags data. No changes will be applied to the current cache. %s'],
   [c.ERROR_STREAMING_SSE, c.LOG_PREFIX_SYNC_STREAMING + 'Failed to connect or error on streaming connection, with error message: %s'],
   [c.ERROR_STREAMING_AUTH, c.LOG_PREFIX_SYNC_STREAMING + 'Failed to authenticate for streaming. Error: %s.'],
-  [c.ERROR_HTTP, 'Response status is not OK. Status: %s. URL: %s. Message: %s'],
+  [c.ERROR_HTTP, 'HTTP request failed with %s. URL: %s. Message: %s'],
   // client status
   [c.ERROR_CLIENT_LISTENER, 'A listener was added for %s on the SDK, which has already fired and won\'t be emitted again. The callback won\'t be executed.'],
   [c.ERROR_CLIENT_DESTROYED, '%s: Client has already been destroyed - no calls possible.'],
diff --git a/src/services/splitHttpClient.ts b/src/services/splitHttpClient.ts
@@ -70,7 +70,7 @@ export function splitHttpClientFactory(settings: ISettings, { getOptions, getFet
         }
 
         if (!resp || resp.status !== 403) { // 403's log we'll be handled somewhere else.
-          log[logErrorsAsInfo ? 'info' : 'error'](ERROR_HTTP, [resp ? resp.status : 'NO_STATUS', url, msg]);
+          log[logErrorsAsInfo ? 'info' : 'error'](ERROR_HTTP, [resp ? 'status code ' + resp.status : 'no status code', url, msg]);
         }
 
         const networkError: NetworkError = new Error(msg);
diff --git a/src/storages/AbstractSplitsCacheSync.ts b/src/storages/AbstractSplitsCacheSync.ts
@@ -1,4 +1,4 @@
-import { ISplitsCacheSync } from './types';
+import { ISplitsCacheSync, IStorageSync } from './types';
 import { IRBSegment, ISplit } from '../dtos/types';
 import { objectAssign } from '../utils/lang/objectAssign';
 import { IN_SEGMENT, IN_LARGE_SEGMENT } from '../utils/constants';
@@ -88,3 +88,7 @@ export function usesSegments(ruleEntity: ISplit | IRBSegment) {
 
   return false;
 }
+
+export function usesSegmentsSync(storage: Pick<IStorageSync, 'splits' | 'rbSegments'>) {
+  return storage.splits.usesSegments() || storage.rbSegments.usesSegments();
+}
diff --git a/src/storages/inLocalStorage/__tests__/SplitsCacheInLocal.spec.ts b/src/storages/inLocalStorage/__tests__/SplitsCacheInLocal.spec.ts
@@ -173,6 +173,9 @@ test('SPLITS CACHE / LocalStorage / flag set cache tests', () => {
   ], [], -1);
   cache.addSplit(featureFlagWithEmptyFS);
 
+  // Adding an existing FF should not affect the cache
+  cache.update([featureFlagTwo], [], -1);
+
   expect(cache.getNamesByFlagSets(['o'])).toEqual([new Set(['ff_one', 'ff_two'])]);
   expect(cache.getNamesByFlagSets(['n'])).toEqual([new Set(['ff_one'])]);
   expect(cache.getNamesByFlagSets(['e'])).toEqual([new Set(['ff_one', 'ff_three'])]);
diff --git a/src/storages/inMemory/__tests__/SplitsCacheInMemory.spec.ts b/src/storages/inMemory/__tests__/SplitsCacheInMemory.spec.ts
@@ -135,6 +135,9 @@ test('SPLITS CACHE / In Memory / flag set cache tests', () => {
   ], [], -1);
   cache.addSplit(featureFlagWithEmptyFS);
 
+  // Adding an existing FF should not affect the cache
+  cache.update([featureFlagTwo], [], -1);
+
   expect(cache.getNamesByFlagSets(['o'])).toEqual([new Set(['ff_one', 'ff_two'])]);
   expect(cache.getNamesByFlagSets(['n'])).toEqual([new Set(['ff_one'])]);
   expect(cache.getNamesByFlagSets(['e'])).toEqual([new Set(['ff_one', 'ff_three'])]);
diff --git a/src/sync/polling/pollingManagerCS.ts b/src/sync/polling/pollingManagerCS.ts
@@ -8,6 +8,7 @@ import { getMatching } from '../../utils/key';
 import { SDK_SPLITS_ARRIVED, SDK_SEGMENTS_ARRIVED } from '../../readiness/constants';
 import { POLLING_SMART_PAUSING, POLLING_START, POLLING_STOP } from '../../logger/constants';
 import { ISdkFactoryContextSync } from '../../sdkFactory/types';
+import { usesSegmentsSync } from '../../storages/AbstractSplitsCacheSync';
 
 /**
  * Expose start / stop mechanism for polling data from services.
@@ -43,7 +44,7 @@ export function pollingManagerCSFactory(
   // smart pausing
   readiness.splits.on(SDK_SPLITS_ARRIVED, () => {
     if (!splitsSyncTask.isRunning()) return; // noop if not doing polling
-    const usingSegments = storage.splits.usesSegments() || storage.rbSegments.usesSegments();
+    const usingSegments = usesSegmentsSync(storage);
     if (usingSegments !== mySegmentsSyncTask.isRunning()) {
       log.info(POLLING_SMART_PAUSING, [usingSegments ? 'ON' : 'OFF']);
       if (usingSegments) {
@@ -59,9 +60,9 @@ export function pollingManagerCSFactory(
 
     // smart ready
     function smartReady() {
-      if (!readiness.isReady() && !storage.splits.usesSegments() && !storage.rbSegments.usesSegments()) readiness.segments.emit(SDK_SEGMENTS_ARRIVED);
+      if (!readiness.isReady() && !usesSegmentsSync(storage)) readiness.segments.emit(SDK_SEGMENTS_ARRIVED);
     }
-    if (!storage.splits.usesSegments() && !storage.rbSegments.usesSegments()) setTimeout(smartReady, 0);
+    if (!usesSegmentsSync(storage)) setTimeout(smartReady, 0);
     else readiness.splits.once(SDK_SPLITS_ARRIVED, smartReady);
 
     mySegmentsSyncTasks[matchingKey] = mySegmentsSyncTask;
@@ -77,7 +78,7 @@ export function pollingManagerCSFactory(
       log.info(POLLING_START);
 
       splitsSyncTask.start();
-      if (storage.splits.usesSegments() || storage.rbSegments.usesSegments()) startMySegmentsSyncTasks();
+      if (usesSegmentsSync(storage)) startMySegmentsSyncTasks();
     },
 
     // Stop periodic fetching (polling)
diff --git a/src/sync/polling/updaters/mySegmentsUpdater.ts b/src/sync/polling/updaters/mySegmentsUpdater.ts
@@ -8,6 +8,7 @@ import { SYNC_MYSEGMENTS_FETCH_RETRY } from '../../../logger/constants';
 import { MySegmentsData } from '../types';
 import { IMembershipsResponse } from '../../../dtos/types';
 import { MEMBERSHIPS_LS_UPDATE } from '../../streaming/constants';
+import { usesSegmentsSync } from '../../../storages/AbstractSplitsCacheSync';
 
 type IMySegmentsUpdater = (segmentsData?: MySegmentsData, noCache?: boolean, till?: number) => Promise<boolean>
 
@@ -27,7 +28,7 @@ export function mySegmentsUpdaterFactory(
   matchingKey: string
 ): IMySegmentsUpdater {
 
-  const { splits, rbSegments, segments, largeSegments } = storage;
+  const { segments, largeSegments } = storage;
   let readyOnAlreadyExistentState = true;
   let startingUp = true;
 
@@ -51,7 +52,7 @@ export function mySegmentsUpdaterFactory(
     }
 
     // Notify update if required
-    if ((splits.usesSegments() || rbSegments.usesSegments()) && (shouldNotifyUpdate || readyOnAlreadyExistentState)) {
+    if (usesSegmentsSync(storage) && (shouldNotifyUpdate || readyOnAlreadyExistentState)) {
       readyOnAlreadyExistentState = false;
       segmentsEventEmitter.emit(SDK_SEGMENTS_ARRIVED);
     }
diff --git a/src/sync/polling/updaters/splitChangesUpdater.ts b/src/sync/polling/updaters/splitChangesUpdater.ts
@@ -59,7 +59,7 @@ interface ISplitMutations<T extends ISplit | IRBSegment> {
 
 /**
  * If there are defined filters and one feature flag doesn't match with them, its status is changed to 'ARCHIVE' to avoid storing it
- * If there are set filter defined, names filter is ignored
+ * If there is `bySet` filter, `byName` and `byPrefix` filters are ignored
  *
  * @param featureFlag - feature flag to be evaluated
  * @param filters - splitFiltersValidation bySet | byName
diff --git a/src/sync/syncManagerOnline.ts b/src/sync/syncManagerOnline.ts
@@ -10,6 +10,7 @@ import { isConsentGranted } from '../consent';
 import { POLLING, STREAMING, SYNC_MODE_UPDATE } from '../utils/constants';
 import { ISdkFactoryContextSync } from '../sdkFactory/types';
 import { SDK_SPLITS_CACHE_LOADED } from '../readiness/constants';
+import { usesSegmentsSync } from '../storages/AbstractSplitsCacheSync';
 
 /**
  * Online SyncManager factory.
@@ -155,14 +156,14 @@ export function syncManagerOnlineFactory(
             if (pushManager) {
               if (pollingManager.isRunning()) {
                 // if doing polling, we must start the periodic fetch of data
-                if (storage.splits.usesSegments() || storage.rbSegments.usesSegments()) mySegmentsSyncTask.start();
+                if (usesSegmentsSync(storage)) mySegmentsSyncTask.start();
               } else {
                 // if not polling, we must execute the sync task for the initial fetch
                 // of segments since `syncAll` was already executed when starting the main client
                 mySegmentsSyncTask.execute();
               }
             } else {
-              if (storage.splits.usesSegments() || storage.rbSegments.usesSegments()) mySegmentsSyncTask.start();
+              if (usesSegmentsSync(storage)) mySegmentsSyncTask.start();
             }
           } else {
             if (!readinessManager.isReady()) mySegmentsSyncTask.execute();
diff --git a/src/utils/settingsValidation/splitFilters.ts b/src/utils/settingsValidation/splitFilters.ts
@@ -69,12 +69,6 @@ function validateSplitFilter(log: ILogger, type: SplitIO.SplitFilterType, values
 /**
  * Returns a string representing the URL encoded query component of /splitChanges URL.
  *
- * The possible formats of the query string are:
- *  - null: if all filters are empty
- *  - '&names=<comma-separated-values>': if only `byPrefix` filter is undefined
- *  - '&prefixes=<comma-separated-values>': if only `byName` filter is undefined
- *  - '&names=<comma-separated-values>&prefixes=<comma-separated-values>': if no one is undefined
- *
  * @param groupedFilters - object of filters. Each filter must be a list of valid, unique and ordered string values.
  * @returns null or string with the `split filter query` component of the URL.
  */
diff --git a/types/splitio.d.ts b/types/splitio.d.ts
@@ -24,7 +24,11 @@ interface ISharedSettings {
   sync?: {
     /**
      * List of feature flag filters. These filters are used to fetch a subset of the feature flag definitions in your environment, in order to reduce the delay of the SDK to be ready.
-     * This configuration is only meaningful when the SDK is working in "standalone" mode.
+     *
+     * NOTES:
+     * - This configuration is only meaningful when the SDK is working in `"standalone"` mode.
+     * - If `bySet` filter is provided, `byName` and `byPrefix` filters are ignored.
+     * - If both `byName` and `byPrefix` filters are provided, the intersection of the two groups of feature flags is fetched.
      *
      * Example:
      * ```
@@ -66,12 +70,17 @@ interface ISharedSettings {
        *
        * @example
        * ```
-       * const getHeaderOverrides = (context) => {
-       *   return {
-       *     'Authorization': context.headers['Authorization'] + ', other-value',
-       *     'custom-header': 'custom-value'
-       *   };
-       * };
+       * const factory = SplitFactory({
+       *   ...
+       *   sync: {
+       *     getHeaderOverrides: (context) => {
+       *       return {
+       *         'Authorization': context.headers['Authorization'] + ', other-value',
+       *         'custom-header': 'custom-value'
+       *       };
+       *     }
+       *   }
+       * });
        * ```
        */
       getHeaderOverrides?: (context: { headers: Record<string, string> }) => Record<string, string>;
@@ -952,7 +961,7 @@ declare namespace SplitIO {
      */
     prefix?: string;
     /**
-     * Number of days before cached data expires if it was not updated. If cache expires, it is cleared on initialization.
+     * Number of days before cached data expires if it was not successfully synchronized (i.e., last SDK_READY or SDK_UPDATE event emitted). If cache expires, it is cleared on initialization.
      *
      * @defaultValue `10`
      */
@@ -1130,7 +1139,7 @@ declare namespace SplitIO {
      */
     type: SplitFilterType;
     /**
-     * List of values: feature flag names for 'byName' filter type, and feature flag name prefixes for 'byPrefix' type.
+     * List of values: flag set names for 'bySet' filter type, feature flag names for 'byName' filter type, and feature flag name prefixes for 'byPrefix' type.
      */
     values: string[];
   }
@@ -1292,7 +1301,7 @@ declare namespace SplitIO {
        */
       prefix?: string;
       /**
-       * Optional settings for the 'LOCALSTORAGE' storage type. It specifies the number of days before cached data expires if it was not updated. If cache expires, it is cleared on initialization.
+       * Optional settings for the 'LOCALSTORAGE' storage type. It specifies the number of days before cached data expires if it was not successfully synchronized (i.e., last SDK_READY or SDK_UPDATE event emitted). If cache expires, it is cleared on initialization.
        *
        * @defaultValue `10`
        */
@@ -1350,12 +1359,17 @@ declare namespace SplitIO {
          *
          * @example
          * ```
-         * const getHeaderOverrides = (context) => {
-         *   return {
-         *     'Authorization': context.headers['Authorization'] + ', other-value',
-         *     'custom-header': 'custom-value'
-         *   };
-         * };
+         * const factory = SplitFactory({
+         *   ...
+         *   sync: {
+         *     getHeaderOverrides: (context) => {
+         *       return {
+         *         'Authorization': context.headers['Authorization'] + ', other-value',
+         *         'custom-header': 'custom-value'
+         *       };
+         *     }
+         *   }
+         * });
          * ```
          */
         getHeaderOverrides?: (context: { headers: Record<string, string> }) => Record<string, string>;

Original file line number	Diff line number	Diff line change
`@@ -70,7 +70,7 @@ export function splitHttpClientFactory(settings: ISettings, { getOptions, getFet`
`70`	`70`	`}`
`71`	`71`
`72`	`72`	`if (!resp \|\| resp.status !== 403) { // 403's log we'll be handled somewhere else.`
`73`		`- log[logErrorsAsInfo ? 'info' : 'error'](ERROR_HTTP, [resp ? resp.status : 'NO_STATUS', url, msg]);`
	`73`	`+ log[logErrorsAsInfo ? 'info' : 'error'](ERROR_HTTP, [resp ? 'status code ' + resp.status : 'no status code', url, msg]);`
`74`	`74`	`}`
`75`	`75`
`76`	`76`	`const networkError: NetworkError = new Error(msg);`
Original file line number	Diff line number	Diff line change
`@@ -59,7 +59,7 @@ interface ISplitMutations<T extends ISplit \| IRBSegment> {`
`59`	`59`
`60`	`60`	`/**`
`61`	`61`	`* If there are defined filters and one feature flag doesn't match with them, its status is changed to 'ARCHIVE' to avoid storing it`
`62`		`- * If there are set filter defined, names filter is ignored`
	`62`	+ * If there is `bySet` filter, `byName` and `byPrefix` filters are ignored
`63`	`63`	`*`
`64`	`64`	`* @param featureFlag - feature flag to be evaluated`
`65`	`65`	`* @param filters - splitFiltersValidation bySet \| byName`