@splitsoftware/splitio-commons 2.5.0 → 2.5.1-rc.0

package/src/storages/inLocalStorage/index.ts

@@ -1,10 +1,10 @@
 import { ImpressionsCacheInMemory } from '../inMemory/ImpressionsCacheInMemory';
 import { ImpressionCountsCacheInMemory } from '../inMemory/ImpressionCountsCacheInMemory';
 import { EventsCacheInMemory } from '../inMemory/EventsCacheInMemory';
-import { IStorageFactoryParams, IStorageSync, IStorageSyncFactory } from '../types';
+import { IStorageFactoryParams, IStorageSync, IStorageSyncFactory, StorageAdapter } from '../types';
 import { validatePrefix } from '../KeyBuilder';
 import { KeyBuilderCS, myLargeSegmentsKeyBuilder } from '../KeyBuilderCS';
-import { isLocalStorageAvailable } from '../../utils/env/isLocalStorageAvailable';
+import { isLocalStorageAvailable, isValidStorageWrapper, isWebStorage } from '../../utils/env/isLocalStorageAvailable';
 import { SplitsCacheInLocal } from './SplitsCacheInLocal';
 import { RBSegmentsCacheInLocal } from './RBSegmentsCacheInLocal';
 import { MySegmentsCacheInLocal } from './MySegmentsCacheInLocal';
@@ -15,7 +15,24 @@ import { shouldRecordTelemetry, TelemetryCacheInMemory } from '../inMemory/Telem
 import { UniqueKeysCacheInMemoryCS } from '../inMemory/UniqueKeysCacheInMemoryCS';
 import { getMatching } from '../../utils/key';
 import { validateCache } from './validateCache';
+import { ILogger } from '../../logger/types';
 import SplitIO from '../../../types/splitio';
+import { storageAdapter } from './storageAdapter';
+
+function validateStorage(log: ILogger, prefix: string, wrapper?: SplitIO.StorageWrapper): StorageAdapter | undefined {
+  if (wrapper) {
+    if (isValidStorageWrapper(wrapper)) {
+      return isWebStorage(wrapper) ?
+        wrapper as StorageAdapter: // localStorage and sessionStorage don't need adapter
+        storageAdapter(log, prefix, wrapper);
+    }
+    log.warn(LOG_PREFIX + 'Invalid storage provided. Falling back to LocalStorage API');
+  }
+
+  if (isLocalStorageAvailable()) return localStorage;
+
+  log.warn(LOG_PREFIX + 'LocalStorage API is unavailable. Falling back to default MEMORY storage');
+}
 
 /**
  * InLocal storage factory for standalone client-side SplitFactory
@@ -25,21 +42,19 @@ export function InLocalStorage(options: SplitIO.InLocalStorageOptions = {}): ISt
   const prefix = validatePrefix(options.prefix);
 
   function InLocalStorageCSFactory(params: IStorageFactoryParams): IStorageSync {
+    const { settings, settings: { log, scheduler: { impressionsQueueSize, eventsQueueSize } } } = params;
 
-    // Fallback to InMemoryStorage if LocalStorage API is not available
-    if (!isLocalStorageAvailable()) {
-      params.settings.log.warn(LOG_PREFIX + 'LocalStorage API is unavailable. Falling back to default MEMORY storage');
-      return InMemoryStorageCSFactory(params);
-    }
+    const storage = validateStorage(log, prefix, options.wrapper);
+    if (!storage) return InMemoryStorageCSFactory(params);
 
-    const { settings, settings: { log, scheduler: { impressionsQueueSize, eventsQueueSize } } } = params;
     const matchingKey = getMatching(settings.core.key);
     const keys = new KeyBuilderCS(prefix, matchingKey);
 
-    const splits = new SplitsCacheInLocal(settings, keys);
-    const rbSegments = new RBSegmentsCacheInLocal(settings, keys);
-    const segments = new MySegmentsCacheInLocal(log, keys);
-    const largeSegments = new MySegmentsCacheInLocal(log, myLargeSegmentsKeyBuilder(prefix, matchingKey));
+    const splits = new SplitsCacheInLocal(settings, keys, storage);
+    const rbSegments = new RBSegmentsCacheInLocal(settings, keys, storage);
+    const segments = new MySegmentsCacheInLocal(log, keys, storage);
+    const largeSegments = new MySegmentsCacheInLocal(log, myLargeSegmentsKeyBuilder(prefix, matchingKey), storage);
+    let validateCachePromise: Promise<boolean> | undefined;
 
     return {
       splits,
@@ -53,10 +68,16 @@ export function InLocalStorage(options: SplitIO.InLocalStorageOptions = {}): ISt
       uniqueKeys: new UniqueKeysCacheInMemoryCS(),
 
       validateCache() {
-        return validateCache(options, settings, keys, splits, rbSegments, segments, largeSegments);
+        return validateCachePromise || (validateCachePromise = validateCache(options, storage, settings, keys, splits, rbSegments, segments, largeSegments));
       },
 
-      destroy() { },
+      save() {
+        return storage.save && storage.save();
+      },
+
+      destroy() {
+        return storage.whenSaved && storage.whenSaved();
+      },
 
       // When using shared instantiation with MEMORY we reuse everything but segments (they are customer per key).
       shared(matchingKey: string) {
@@ -64,8 +85,8 @@ export function InLocalStorage(options: SplitIO.InLocalStorageOptions = {}): ISt
         return {
           splits: this.splits,
           rbSegments: this.rbSegments,
-          segments: new MySegmentsCacheInLocal(log, new KeyBuilderCS(prefix, matchingKey)),
-          largeSegments: new MySegmentsCacheInLocal(log, myLargeSegmentsKeyBuilder(prefix, matchingKey)),
+          segments: new MySegmentsCacheInLocal(log, new KeyBuilderCS(prefix, matchingKey), storage),
+          largeSegments: new MySegmentsCacheInLocal(log, myLargeSegmentsKeyBuilder(prefix, matchingKey), storage),
           impressions: this.impressions,
           impressionCounts: this.impressionCounts,
           events: this.events,

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.StorageWrapper): 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, initialRolloutPlan } = 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.
  */
@@ -467,6 +484,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<
@@ -480,7 +498,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/updaters/mySegmentsUpdater.ts

@@ -51,6 +51,8 @@ export function mySegmentsUpdaterFactory(
       shouldNotifyUpdate = largeSegments!.resetSegments((segmentsData as IMembershipsResponse).ls || {}) || shouldNotifyUpdate;
     }
 
+    if (storage.save) storage.save();
+
     // Notify update if required
     if (usesSegmentsSync(storage) && (shouldNotifyUpdate || readyOnAlreadyExistentState)) {
       readyOnAlreadyExistentState = false;

package/src/sync/polling/updaters/splitChangesUpdater.ts

@@ -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

@@ -89,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;
+        });
       },
 
       /**

package/src/utils/env/isLocalStorageAvailable.ts

@@ -9,3 +9,23 @@ export function isLocalStorageAvailable(): boolean {
     return false;
   }
 }
+
+export function isValidStorageWrapper(wrapper: any): boolean {
+  return wrapper !== null &&
+    typeof wrapper === 'object' &&
+    typeof wrapper.setItem === 'function' &&
+    typeof wrapper.getItem === 'function' &&
+    typeof wrapper.removeItem === 'function';
+}
+
+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/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

@@ -463,6 +463,24 @@ interface IClientSideSyncSharedSettings extends IClientSideSharedSettings, ISync
  */
 declare namespace SplitIO {
 
+  interface StorageWrapper {
+    /**
+     * Returns the value associated with the given key, or null if the key does not exist.
+     * If the operation is asynchronous, returns a Promise.
+     */
+    getItem(key: string): string | null | Promise<string | null>;
+    /**
+     * Sets the value for the given key, creating a new key/value pair if key does not exist.
+     * If the operation is asynchronous, returns a Promise.
+     */
+    setItem(key: string, value: string): void | Promise<void>;
+    /**
+     * Removes the key/value pair for the given key, if the key exists.
+     * If the operation is asynchronous, returns a Promise.
+     */
+    removeItem(key: string): void | Promise<void>;
+  }
+
   /**
    * EventEmitter interface based on a subset of the Node.js EventEmitter methods.
    */
@@ -978,6 +996,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?: StorageWrapper;
   }
   /**
    * Storage for asynchronous (consumer) SDK.
@@ -1339,6 +1363,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?: StorageWrapper;
     };
   }
   /**