@splitsoftware/splitio-commons 2.4.2-rc.1 → 2.4.2-rc.3

package/src/storages/inLocalStorage/storageAdapter.ts

@@ -0,0 +1,62 @@
+import { ILogger } from '../../logger/types';
+import SplitIO from '../../../types/splitio';
+import { LOG_PREFIX } from './constants';
+import { StorageAdapter } from '../types';
+
+
+export function storageAdapter(log: ILogger, prefix: string, wrapper: SplitIO.SyncStorageWrapper | SplitIO.AsyncStorageWrapper): Required<StorageAdapter> {
+  let keys: string[] = [];
+  let cache: Record<string, string> = {};
+
+  let loadPromise: Promise<void> | undefined;
+  let savePromise = Promise.resolve();
+
+  return {
+    load() {
+      return loadPromise || (loadPromise = Promise.resolve().then(() => {
+        return wrapper.getItem(prefix);
+      }).then((storedCache) => {
+        cache = JSON.parse(storedCache || '{}');
+        keys = Object.keys(cache);
+      }).catch((e) => {
+        log.error(LOG_PREFIX + 'Rejected promise calling wrapper `getItem` method, with error: ' + e);
+      }));
+    },
+
+    save() {
+      return savePromise = savePromise.then(() => {
+        return Promise.resolve(wrapper.setItem(prefix, JSON.stringify(cache)));
+      }).catch((e) => {
+        log.error(LOG_PREFIX + 'Rejected promise calling wrapper `setItem` method, with error: ' + e);
+      });
+    },
+
+    whenSaved() {
+      return savePromise;
+    },
+
+    get length() {
+      return keys.length;
+    },
+
+    getItem(key: string) {
+      return cache[key] || null;
+    },
+
+    key(index: number) {
+      return keys[index] || null;
+    },
+
+    removeItem(key: string) {
+      const index = keys.indexOf(key);
+      if (index === -1) return;
+      keys.splice(index, 1);
+      delete cache[key];
+    },
+
+    setItem(key: string, value: string) {
+      if (keys.indexOf(key) === -1) keys.push(key);
+      cache[key] = value;
+    }
+  };
+}

package/src/storages/inLocalStorage/validateCache.ts

@@ -7,6 +7,7 @@ import type { RBSegmentsCacheInLocal } from './RBSegmentsCacheInLocal';
 import type { MySegmentsCacheInLocal } from './MySegmentsCacheInLocal';
 import { KeyBuilderCS } from '../KeyBuilderCS';
 import SplitIO from '../../../types/splitio';
+import { StorageAdapter } from '../types';
 
 const DEFAULT_CACHE_EXPIRATION_IN_DAYS = 10;
 const MILLIS_IN_A_DAY = 86400000;
@@ -16,11 +17,11 @@ const MILLIS_IN_A_DAY = 86400000;
  *
  * @returns `true` if cache should be cleared, `false` otherwise
  */
-function validateExpiration(options: SplitIO.InLocalStorageOptions, settings: ISettings, keys: KeyBuilderCS, currentTimestamp: number, isThereCache: boolean) {
+function validateExpiration(options: SplitIO.InLocalStorageOptions, storage: StorageAdapter, settings: ISettings, keys: KeyBuilderCS, currentTimestamp: number, isThereCache: boolean) {
   const { log } = settings;
 
   // Check expiration
-  const lastUpdatedTimestamp = parseInt(localStorage.getItem(keys.buildLastUpdatedKey()) as string, 10);
+  const lastUpdatedTimestamp = parseInt(storage.getItem(keys.buildLastUpdatedKey()) as string, 10);
   if (!isNaNNumber(lastUpdatedTimestamp)) {
     const cacheExpirationInDays = isFiniteNumber(options.expirationDays) && options.expirationDays >= 1 ? options.expirationDays : DEFAULT_CACHE_EXPIRATION_IN_DAYS;
     const expirationTimestamp = currentTimestamp - MILLIS_IN_A_DAY * cacheExpirationInDays;
@@ -32,12 +33,12 @@ function validateExpiration(options: SplitIO.InLocalStorageOptions, settings: IS
 
   // Check hash
   const storageHashKey = keys.buildHashKey();
-  const storageHash = localStorage.getItem(storageHashKey);
+  const storageHash = storage.getItem(storageHashKey);
   const currentStorageHash = getStorageHash(settings);
 
   if (storageHash !== currentStorageHash) {
     try {
-      localStorage.setItem(storageHashKey, currentStorageHash);
+      storage.setItem(storageHashKey, currentStorageHash);
     } catch (e) {
       log.error(LOG_PREFIX + e);
     }
@@ -50,7 +51,7 @@ function validateExpiration(options: SplitIO.InLocalStorageOptions, settings: IS
 
   // Clear on init
   if (options.clearOnInit) {
-    const lastClearTimestamp = parseInt(localStorage.getItem(keys.buildLastClear()) as string, 10);
+    const lastClearTimestamp = parseInt(storage.getItem(keys.buildLastClear()) as string, 10);
 
     if (isNaNNumber(lastClearTimestamp) || lastClearTimestamp < currentTimestamp - MILLIS_IN_A_DAY) {
       log.info(LOG_PREFIX + 'clearOnInit was set and cache was not cleared in the last 24 hours. Cleaning up cache');
@@ -67,27 +68,32 @@ function validateExpiration(options: SplitIO.InLocalStorageOptions, settings: IS
  *
  * @returns `true` if cache is ready to be used, `false` otherwise (cache was cleared or there is no cache)
  */
-export function validateCache(options: SplitIO.InLocalStorageOptions, settings: ISettings, keys: KeyBuilderCS, splits: SplitsCacheInLocal, rbSegments: RBSegmentsCacheInLocal, segments: MySegmentsCacheInLocal, largeSegments: MySegmentsCacheInLocal): boolean {
+export function validateCache(options: SplitIO.InLocalStorageOptions, storage: StorageAdapter, settings: ISettings, keys: KeyBuilderCS, splits: SplitsCacheInLocal, rbSegments: RBSegmentsCacheInLocal, segments: MySegmentsCacheInLocal, largeSegments: MySegmentsCacheInLocal): Promise<boolean> {
 
-  const currentTimestamp = Date.now();
-  const isThereCache = splits.getChangeNumber() > -1;
+  return Promise.resolve(storage.load && storage.load()).then(() => {
+    const currentTimestamp = Date.now();
+    const isThereCache = splits.getChangeNumber() > -1;
 
-  if (validateExpiration(options, settings, keys, currentTimestamp, isThereCache)) {
-    splits.clear();
-    rbSegments.clear();
-    segments.clear();
-    largeSegments.clear();
+    if (validateExpiration(options, storage, settings, keys, currentTimestamp, isThereCache)) {
+      splits.clear();
+      rbSegments.clear();
+      segments.clear();
+      largeSegments.clear();
 
-    // Update last clear timestamp
-    try {
-      localStorage.setItem(keys.buildLastClear(), currentTimestamp + '');
-    } catch (e) {
-      settings.log.error(LOG_PREFIX + e);
-    }
+      // Update last clear timestamp
+      try {
+        storage.setItem(keys.buildLastClear(), currentTimestamp + '');
+      } catch (e) {
+        settings.log.error(LOG_PREFIX + e);
+      }
 
-    return false;
-  }
+      // Persist clear
+      if (storage.save) storage.save();
+
+      return false;
+    }
 
-  // Check if ready from cache
-  return isThereCache;
+    // Check if ready from cache
+    return isThereCache;
+  });
 }

package/src/storages/types.ts

@@ -4,6 +4,23 @@ import { MySegmentsData } from '../sync/polling/types';
 import { EventDataType, HttpErrors, HttpLatencies, ImpressionDataType, LastSync, Method, MethodExceptions, MethodLatencies, MultiMethodExceptions, MultiMethodLatencies, MultiConfigs, OperationType, StoredEventWithMetadata, StoredImpressionWithMetadata, StreamingEvent, UniqueKeysPayloadCs, UniqueKeysPayloadSs, TelemetryUsageStatsPayload, UpdatesFromSSEEnum } from '../sync/submitters/types';
 import { ISettings } from '../types';
 
+/**
+ * Internal interface based on a subset of the Web Storage API interface
+ * (https://developer.mozilla.org/en-US/docs/Web/API/Storage) used by the SDK
+ */
+export interface StorageAdapter {
+  // Methods to support async storages
+  load?: () => Promise<void>;
+  save?: () => Promise<void>;
+  whenSaved?: () => Promise<void>;
+  // Methods based on https://developer.mozilla.org/en-US/docs/Web/API/Storage
+  readonly length: number;
+  key(index: number): string | null;
+  getItem(key: string): string | null;
+  removeItem(key: string): void;
+  setItem(key: string, value: string): void;
+}
+
 /**
  * Interface of a pluggable storage wrapper.
  */
@@ -466,6 +483,7 @@ export interface IStorageBase<
   uniqueKeys: TUniqueKeysCache,
   destroy(): void | Promise<void>,
   shared?: (matchingKey: string, onReadyCb: (error?: any) => void) => this
+  save?: () => void | Promise<void>,
 }
 
 export interface IStorageSync extends IStorageBase<
@@ -479,7 +497,7 @@ export interface IStorageSync extends IStorageBase<
   IUniqueKeysCacheSync
 > {
   // Defined in client-side
-  validateCache?: () => boolean, // @TODO support async
+  validateCache?: () => Promise<boolean>,
   largeSegments?: ISegmentsCacheSync,
 }
 

package/src/sync/offline/syncTasks/fromObjectSyncTask.ts

@@ -59,8 +59,7 @@ export function fromObjectUpdaterFactory(
 
         if (startingUp) {
           startingUp = false;
-          const isCacheLoaded = storage.validateCache ? storage.validateCache() : false;
-          Promise.resolve().then(() => {
+          Promise.resolve(storage.validateCache ? storage.validateCache() : false).then((isCacheLoaded) => {
             // Emits SDK_READY_FROM_CACHE
             if (isCacheLoaded) readiness.splits.emit(SDK_SPLITS_CACHE_LOADED);
             // Emits SDK_READY

package/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)

package/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;
 
@@ -50,8 +51,10 @@ export function mySegmentsUpdaterFactory(
       shouldNotifyUpdate = largeSegments!.resetSegments((segmentsData as IMembershipsResponse).ls || {}) || shouldNotifyUpdate;
     }
 
+    if (storage.save) storage.save();
+
     // Notify update if required
-    if ((splits.usesSegments() || rbSegments.usesSegments()) && (shouldNotifyUpdate || readyOnAlreadyExistentState)) {
+    if (usesSegmentsSync(storage) && (shouldNotifyUpdate || readyOnAlreadyExistentState)) {
       readyOnAlreadyExistentState = false;
       segmentsEventEmitter.emit(SDK_SEGMENTS_ARRIVED);
     }

package/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
@@ -117,7 +117,7 @@ export function computeMutation<T extends ISplit | IRBSegment>(rules: Array<T>,
 export function splitChangesUpdaterFactory(
   log: ILogger,
   splitChangesFetcher: ISplitChangesFetcher,
-  storage: Pick<IStorageBase, 'splits' | 'rbSegments' | 'segments'>,
+  storage: Pick<IStorageBase, 'splits' | 'rbSegments' | 'segments' | 'save'>,
   splitFiltersValidation: ISplitFiltersValidation,
   splitsEventEmitter?: ISplitsEventEmitter,
   requestTimeoutBeforeReady: number = 0,
@@ -185,6 +185,8 @@ export function splitChangesUpdaterFactory(
             // @TODO if at least 1 segment fetch fails due to 404 and other segments are updated in the storage, SDK_UPDATE is not emitted
             segments.registerSegments(setToArray(usedSegments))
           ]).then(([ffChanged, rbsChanged]) => {
+            if (storage.save) storage.save();
+
             if (splitsEventEmitter) {
               // To emit SDK_SPLITS_ARRIVED for server-side SDK, we must check that all registered segments have been fetched
               return Promise.resolve(!splitsEventEmitter.splitsArrived || ((ffChanged || rbsChanged) && (isClientSide || checkAllSegmentsExist(segments))))

package/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.
@@ -88,36 +89,41 @@ export function syncManagerOnlineFactory(
       start() {
         running = true;
 
-        if (startFirstTime) {
-          const isCacheLoaded = storage.validateCache ? storage.validateCache() : false;
-          if (isCacheLoaded) Promise.resolve().then(() => { readiness.splits.emit(SDK_SPLITS_CACHE_LOADED); });
-        }
+        // @TODO once event, impression and telemetry storages support persistence, call when `validateCache` promise is resolved
+        submitterManager.start(!isConsentGranted(settings));
 
-        // start syncing splits and segments
-        if (pollingManager) {
+        return Promise.resolve(storage.validateCache ? storage.validateCache() : false).then((isCacheLoaded) => {
+          if (!running) return;
 
-          // If synchronization is disabled pushManager and pollingManager should not start
-          if (syncEnabled) {
-            if (pushManager) {
-              // Doesn't call `syncAll` when the syncManager is resuming
+          if (startFirstTime) {
+            // Emits SDK_READY_FROM_CACHE
+            if (isCacheLoaded) readiness.splits.emit(SDK_SPLITS_CACHE_LOADED);
+
+          }
+
+          // start syncing splits and segments
+          if (pollingManager) {
+
+            // If synchronization is disabled pushManager and pollingManager should not start
+            if (syncEnabled) {
+              if (pushManager) {
+                // Doesn't call `syncAll` when the syncManager is resuming
+                if (startFirstTime) {
+                  pollingManager.syncAll();
+                }
+                pushManager.start();
+              } else {
+                pollingManager.start();
+              }
+            } else {
               if (startFirstTime) {
                 pollingManager.syncAll();
               }
-              pushManager.start();
-            } else {
-              pollingManager.start();
-            }
-          } else {
-            if (startFirstTime) {
-              pollingManager.syncAll();
             }
           }
-        }
-
-        // start periodic data recording (events, impressions, telemetry).
-        submitterManager.start(!isConsentGranted(settings));
 
-        startFirstTime = false;
+          startFirstTime = false;
+        });
       },
 
       /**
@@ -155,14 +161,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();

package/src/trackers/impressionsTracker.ts

@@ -20,7 +20,7 @@ export function impressionsTrackerFactory(
   telemetryCache?: ITelemetryCacheSync | ITelemetryCacheAsync,
 ): IImpressionsTracker {
 
-  const { log, runtime: { ip, hostname }, version } = settings;
+  const { log, impressionListener, runtime: { ip, hostname }, version } = settings;
 
   return {
     track(impressions: ImpressionDecorated[], attributes?: SplitIO.Attributes) {
@@ -56,7 +56,7 @@ export function impressionsTrackerFactory(
       }
 
       // @TODO next block might be handled by the integration manager. In that case, the metadata object doesn't need to be passed in the constructor
-      if (settings.impressionListener || integrationsManager) {
+      if (impressionListener || integrationsManager) {
         for (let i = 0; i < impressionsLength; i++) {
           const impressionData: SplitIO.ImpressionData = {
             // copy of impression, to avoid unexpected behavior if modified by integrations or impressionListener
@@ -74,7 +74,7 @@ export function impressionsTrackerFactory(
               if (integrationsManager) integrationsManager.handleImpression(impressionData);
 
               try { // @ts-ignore. An exception on the listeners should not break the SDK.
-                if (settings.impressionListener) settings.impressionListener.logImpression(impressionData);
+                if (impressionListener) impressionListener.logImpression(impressionData);
               } catch (err) {
                 log.error(ERROR_IMPRESSIONS_LISTENER, [err]);
               }

package/src/utils/env/isLocalStorageAvailable.ts

@@ -1,11 +1,32 @@
-/* eslint-disable no-undef */
 export function isLocalStorageAvailable(): boolean {
+  try {
+    // eslint-disable-next-line no-undef
+    return isValidStorageWrapper(localStorage);
+  } catch (e) {
+    return false;
+  }
+}
+
+export function isValidStorageWrapper(wrapper: any): boolean {
   var mod = '__SPLITSOFTWARE__';
   try {
-    localStorage.setItem(mod, mod);
-    localStorage.removeItem(mod);
+    wrapper.setItem(mod, mod);
+    wrapper.getItem(mod);
+    wrapper.removeItem(mod);
     return true;
   } catch (e) {
     return false;
   }
 }
+
+export function isWebStorage(wrapper: any): boolean {
+  if (typeof wrapper.length === 'number') {
+    try {
+      wrapper.key(0);
+      return true;
+    } catch (e) {
+      return false;
+    }
+  }
+  return false;
+}

package/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.
  */

package/src/utils/settingsValidation/storage/storageCS.ts

@@ -8,7 +8,7 @@ import { IStorageFactoryParams, IStorageSync } from '../../../storages/types';
 
 export function __InLocalStorageMockFactory(params: IStorageFactoryParams): IStorageSync {
   const result = InMemoryStorageCSFactory(params);
-  result.validateCache = () => true; // to emit SDK_READY_FROM_CACHE
+  result.validateCache = () => Promise.resolve(true); // to emit SDK_READY_FROM_CACHE
   return result;
 }
 __InLocalStorageMockFactory.type = STORAGE_MEMORY;

package/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>;
@@ -449,6 +458,36 @@ interface IClientSideSyncSharedSettings extends IClientSideSharedSettings, ISync
  */
 declare namespace SplitIO {
 
+  interface SyncStorageWrapper {
+    /**
+     * Returns the value associated with the given key, or null if the key does not exist.
+     */
+    getItem(key: string): string | null;
+    /**
+     * Sets the value for the given key, creating a new key/value pair if key does not exist.
+     */
+    setItem(key: string, value: string): void;
+    /**
+     * Removes the key/value pair for the given key, if the key exists.
+     */
+    removeItem(key: string): void;
+  }
+
+  interface AsyncStorageWrapper {
+    /**
+     * Returns a promise that resolves to the value associated with the given key, or null if the key does not exist.
+     */
+    getItem(key: string): Promise<string | null>;
+    /**
+     * Returns a promise that resolves when the value of the pair identified by key is set to value, creating a new key/value pair if key does not exist.
+     */
+    setItem(key: string, value: string): Promise<void>;
+    /**
+     * Returns a promise that resolves when the key/value pair for the given key is removed, if the key exists.
+     */
+    removeItem(key: string): Promise<void>;
+  }
+
   /**
    * EventEmitter interface based on a subset of the Node.js EventEmitter methods.
    */
@@ -952,7 +991,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`
      */
@@ -963,6 +1002,12 @@ declare namespace SplitIO {
      * @defaultValue `false`
      */
     clearOnInit?: boolean;
+    /**
+     * Optional storage wrapper to persist rollout plan related data. If not provided, the SDK will use the default localStorage Web API.
+     *
+     * @defaultValue `window.localStorage`
+     */
+    wrapper?: SyncStorageWrapper | AsyncStorageWrapper;
   }
   /**
    * Storage for asynchronous (consumer) SDK.
@@ -1130,7 +1175,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 +1337,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`
        */
@@ -1303,6 +1348,12 @@ declare namespace SplitIO {
        * @defaultValue `false`
        */
       clearOnInit?: boolean;
+      /**
+       * Optional storage wrapper to persist rollout plan related data. If not provided, the SDK will use the default localStorage Web API.
+       *
+       * @defaultValue `window.localStorage`
+       */
+      wrapper?: SyncStorageWrapper | AsyncStorageWrapper;
     };
   }
   /**
@@ -1350,12 +1401,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>;