Merge branch 'inlocalstorage_storageAdapter' into inlocalstorage_sessionStorage

Author: EmilianoSanchez

CHANGES.txt

@@ -1,6 +1,10 @@
-2.5.0 (August XX, 2025)
+2.6.0 (September 19, 2025)
  - Added `storage.wrapper` configuration option to allow the SDK to use a custom storage wrapper for the storage type `LOCALSTORAGE`. Default value is `window.localStorage`.
 
+2.5.0 (September 10, 2025)
+ - Added `factory.getRolloutPlan()` method for standalone server-side SDKs, which returns the rollout plan snapshot from the storage.
+ - Added `initialRolloutPlan` configuration option for standalone client-side SDKs, which allows preloading the SDK storage with a snapshot of the rollout plan.
+
 2.4.1 (June 3, 2025)
  - Bugfix - Improved the Proxy fallback to flag spec version 1.2 to handle cases where the Proxy does not return an end-of-stream marker in 400 status code responses.
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@splitsoftware/splitio-commons",
-  "version": "2.4.2-rc.3",
+  "version": "2.5.0",
   "description": "Split JavaScript SDK common components",
   "main": "cjs/index.js",
   "module": "esm/index.js",

package.json

@@ -1,7 +1,17 @@
+import { IBetweenMatcherData } from '../../dtos/types';
+
 export function zeroSinceHH(millisSinceEpoch: number): number {
   return new Date(millisSinceEpoch).setUTCHours(0, 0, 0, 0);
 }
 
 export function zeroSinceSS(millisSinceEpoch: number): number {
   return new Date(millisSinceEpoch).setUTCSeconds(0, 0);
 }
+
+export function betweenDateTimeTransform(betweenMatcherData: IBetweenMatcherData): IBetweenMatcherData {
+  return {
+    dataType: betweenMatcherData.dataType,
+    start: zeroSinceSS(betweenMatcherData.start),
+    end: zeroSinceSS(betweenMatcherData.end)
+  };
+}

src/evaluator/convertions/index.ts

@@ -3,7 +3,7 @@ import { matcherTypes, matcherTypesMapper, matcherDataTypes } from '../matchers/
 import { segmentTransform } from './segment';
 import { whitelistTransform } from './whitelist';
 import { numericTransform } from './unaryNumeric';
-import { zeroSinceHH, zeroSinceSS } from '../convertions';
+import { zeroSinceHH, zeroSinceSS, betweenDateTimeTransform } from '../convertions';
 import { IBetweenMatcherData, IInLargeSegmentMatcherData, IInSegmentMatcherData, ISplitMatcher, IUnaryNumericMatcherData } from '../../dtos/types';
 import { IMatcherDto } from '../types';
 
@@ -32,7 +32,7 @@ export function matchersTransform(matchers: ISplitMatcher[]): IMatcherDto[] {
     let type = matcherTypesMapper(matcherType);
     // As default input data type we use string (even for ALL_KEYS)
     let dataType = matcherDataTypes.STRING;
-    let value = undefined;
+    let value;
 
     if (type === matcherTypes.IN_SEGMENT) {
       value = segmentTransform(userDefinedSegmentMatcherData as IInSegmentMatcherData);
@@ -60,8 +60,7 @@ export function matchersTransform(matchers: ISplitMatcher[]): IMatcherDto[] {
       dataType = matcherDataTypes.NUMBER;
 
       if (value.dataType === 'DATETIME') {
-        value.start = zeroSinceSS(value.start);
-        value.end = zeroSinceSS(value.end);
+        value = betweenDateTimeTransform(value);
         dataType = matcherDataTypes.DATETIME;
       }
     } else if (type === matcherTypes.BETWEEN_SEMVER) {

src/evaluator/matchersTransform/index.ts

@@ -9,13 +9,15 @@ import { RETRIEVE_CLIENT_DEFAULT, NEW_SHARED_CLIENT, RETRIEVE_CLIENT_EXISTING, L
 import { SDK_SEGMENTS_ARRIVED } from '../readiness/constants';
 import { ISdkFactoryContext } from '../sdkFactory/types';
 import { buildInstanceId } from './identity';
+import { setRolloutPlan } from '../storages/setRolloutPlan';
+import { ISegmentsCacheSync } from '../storages/types';
 
 /**
  * Factory of client method for the client-side API variant where TT is ignored.
  * Therefore, clients don't have a bound TT for the track method.
  */
 export function sdkClientMethodCSFactory(params: ISdkFactoryContext): (key?: SplitIO.SplitKey) => SplitIO.IBrowserClient {
-  const { clients, storage, syncManager, sdkReadinessManager, settings: { core: { key }, log } } = params;
+  const { clients, storage, syncManager, sdkReadinessManager, settings: { core: { key }, log, initialRolloutPlan } } = params;
 
   const mainClientInstance = clientCSDecorator(
     log,
@@ -56,6 +58,10 @@ export function sdkClientMethodCSFactory(params: ISdkFactoryContext): (key?: Spl
         sharedSdkReadiness.readinessManager.segments.emit(SDK_SEGMENTS_ARRIVED);
       });
 
+      if (sharedStorage && initialRolloutPlan) {
+        setRolloutPlan(log, initialRolloutPlan, { segments: sharedStorage.segments as ISegmentsCacheSync, largeSegments: sharedStorage.largeSegments as ISegmentsCacheSync }, matchingKey);
+      }
+
       // 3 possibilities:
       // - Standalone mode: both syncManager and sharedSyncManager are defined
       // - Consumer mode: both syncManager and sharedSyncManager are undefined

src/sdkClient/sdkClientMethodCS.ts

@@ -14,6 +14,9 @@ import { strategyOptimizedFactory } from '../trackers/strategy/strategyOptimized
 import { strategyNoneFactory } from '../trackers/strategy/strategyNone';
 import { uniqueKeysTrackerFactory } from '../trackers/uniqueKeysTracker';
 import { DEBUG, OPTIMIZED } from '../utils/constants';
+import { setRolloutPlan } from '../storages/setRolloutPlan';
+import { IStorageSync } from '../storages/types';
+import { getMatching } from '../utils/key';
 
 /**
  * Modular SDK factory
@@ -24,7 +27,7 @@ export function sdkFactory(params: ISdkFactoryParams): SplitIO.ISDK | SplitIO.IA
     syncManagerFactory, SignalListener, impressionsObserverFactory,
     integrationsManagerFactory, sdkManagerFactory, sdkClientMethodFactory,
     filterAdapterFactory, lazyInit } = params;
-  const { log, sync: { impressionsMode } } = settings;
+  const { log, sync: { impressionsMode }, initialRolloutPlan, core: { key } } = settings;
 
   // @TODO handle non-recoverable errors, such as, global `fetch` not available, invalid SDK Key, etc.
   // On non-recoverable errors, we should mark the SDK as destroyed and not start synchronization.
@@ -43,7 +46,7 @@ export function sdkFactory(params: ISdkFactoryParams): SplitIO.ISDK | SplitIO.IA
 
   const storage = storageFactory({
     settings,
-    onReadyCb: (error) => {
+    onReadyCb(error) {
       if (error) {
         // If storage fails to connect, SDK_READY_TIMED_OUT event is emitted immediately. Review when timeout and non-recoverable errors are reworked
         readiness.timeout();
@@ -52,11 +55,16 @@ export function sdkFactory(params: ISdkFactoryParams): SplitIO.ISDK | SplitIO.IA
       readiness.splits.emit(SDK_SPLITS_ARRIVED);
       readiness.segments.emit(SDK_SEGMENTS_ARRIVED);
     },
-    onReadyFromCacheCb: () => {
+    onReadyFromCacheCb() {
       readiness.splits.emit(SDK_SPLITS_CACHE_LOADED);
     }
   });
-  // @TODO add support for dataloader: `if (params.dataLoader) params.dataLoader(storage);`
+
+  if (initialRolloutPlan) {
+    setRolloutPlan(log, initialRolloutPlan, storage as IStorageSync, key && getMatching(key));
+    if ((storage as IStorageSync).splits.getChangeNumber() > -1) readiness.splits.emit(SDK_SPLITS_CACHE_LOADED);
+  }
+
   const clients: Record<string, SplitIO.IBasicClient> = {};
   const telemetryTracker = telemetryTrackerFactory(storage.telemetry, platform.now);
   const integrationsManager = integrationsManagerFactory && integrationsManagerFactory({ settings, storage, telemetryTracker });

src/sdkFactory/index.ts

@@ -0,0 +1,133 @@
+import { InMemoryStorageFactory } from '../inMemory/InMemoryStorage';
+import { InMemoryStorageCSFactory } from '../inMemory/InMemoryStorageCS';
+import { fullSettings } from '../../utils/settingsValidation/__tests__/settings.mocks';
+import { loggerMock } from '../../logger/__tests__/sdkLogger.mock';
+import { IRBSegment, ISplit } from '../../dtos/types';
+
+import { validateRolloutPlan, setRolloutPlan } from '../setRolloutPlan';
+import { getRolloutPlan } from '../getRolloutPlan';
+
+const otherKey = 'otherKey';
+const expectedRolloutPlan = {
+  splitChanges: {
+    ff: { d: [{ name: 'split1' }], t: 123, s: -1 },
+    rbs: { d: [{ name: 'rbs1' }], t: 321, s: -1 }
+  },
+  memberships: {
+    [fullSettings.core.key as string]: { ms: { k: [{ n: 'segment1' }] }, ls: { k: [] } },
+    [otherKey]: { ms: { k: [{ n: 'segment1' }] }, ls: { k: [] } }
+  },
+  segmentChanges: [{
+    name: 'segment1',
+    added: [fullSettings.core.key as string, otherKey],
+    removed: [],
+    since: -1,
+    till: 123
+  }]
+};
+
+describe('validateRolloutPlan', () => {
+  afterEach(() => {
+    loggerMock.mockClear();
+  });
+
+  test('valid rollout plan and mode', () => {
+    expect(validateRolloutPlan(loggerMock, { mode: 'standalone', initialRolloutPlan: expectedRolloutPlan } as any)).toEqual(expectedRolloutPlan);
+    expect(loggerMock.error).not.toHaveBeenCalled();
+  });
+
+  test('invalid rollout plan', () => {
+    expect(validateRolloutPlan(loggerMock, { mode: 'standalone', initialRolloutPlan: {} } as any)).toBeUndefined();
+    expect(loggerMock.error).toHaveBeenCalledWith('storage: invalid rollout plan provided');
+  });
+
+  test('invalid mode', () => {
+    expect(validateRolloutPlan(loggerMock, { mode: 'consumer', initialRolloutPlan: expectedRolloutPlan } as any)).toBeUndefined();
+    expect(loggerMock.warn).toHaveBeenCalledWith('storage: initial rollout plan is ignored in consumer mode');
+  });
+});
+
+describe('getRolloutPlan & setRolloutPlan (client-side)', () => {
+  // @ts-expect-error Load server-side storage
+  const serverStorage = InMemoryStorageFactory({ settings: fullSettings });
+  serverStorage.splits.update([{ name: 'split1' } as ISplit], [], 123);
+  serverStorage.rbSegments.update([{ name: 'rbs1' } as IRBSegment], [], 321);
+  serverStorage.segments.update('segment1', [fullSettings.core.key as string, otherKey], [], 123);
+
+  afterEach(() => {
+    jest.clearAllMocks();
+  });
+
+  test('using preloaded data (no memberships, no segments)', () => {
+    const rolloutPlan = getRolloutPlan(loggerMock, serverStorage);
+
+    // @ts-expect-error Load client-side storage with preloaded data
+    const clientStorage = InMemoryStorageCSFactory({ settings: fullSettings });
+    setRolloutPlan(loggerMock, rolloutPlan, clientStorage, fullSettings.core.key as string);
+
+    // Shared client storage
+    const sharedClientStorage = clientStorage.shared!(otherKey);
+    setRolloutPlan(loggerMock, rolloutPlan, { segments: sharedClientStorage.segments, largeSegments: sharedClientStorage.largeSegments }, otherKey);
+
+    expect(clientStorage.segments.getRegisteredSegments()).toEqual([]);
+    expect(sharedClientStorage.segments.getRegisteredSegments()).toEqual([]);
+
+    // Get preloaded data from client-side storage
+    expect(getRolloutPlan(loggerMock, clientStorage)).toEqual(rolloutPlan);
+    expect(rolloutPlan).toEqual({ ...expectedRolloutPlan, memberships: undefined, segmentChanges: undefined });
+  });
+
+  test('using preloaded data with memberships', () => {
+    const rolloutPlan = getRolloutPlan(loggerMock, serverStorage, { keys: [fullSettings.core.key as string, otherKey] });
+
+    // @ts-expect-error Load client-side storage with preloaded data
+    const clientStorage = InMemoryStorageCSFactory({ settings: fullSettings });
+    setRolloutPlan(loggerMock, rolloutPlan, clientStorage, fullSettings.core.key as string);
+
+    // Shared client storage
+    const sharedClientStorage = clientStorage.shared!(otherKey);
+    setRolloutPlan(loggerMock, rolloutPlan, { segments: sharedClientStorage.segments, largeSegments: sharedClientStorage.largeSegments }, otherKey);
+
+    expect(clientStorage.segments.getRegisteredSegments()).toEqual(['segment1']);
+    expect(sharedClientStorage.segments.getRegisteredSegments()).toEqual(['segment1']);
+
+    // @TODO requires internal storage cache for `shared` storages
+    // // Get preloaded data from client-side storage
+    // expect(getRolloutPlan(loggerMock, clientStorage, { keys: [fullSettings.core.key as string, otherKey] })).toEqual(rolloutPlan);
+    // expect(rolloutPlan).toEqual({ ...expectedRolloutPlan, segmentChanges: undefined });
+  });
+
+  test('using preloaded data with segments', () => {
+    const rolloutPlan = getRolloutPlan(loggerMock, serverStorage, { exposeSegments: true });
+
+    // @ts-expect-error Load client-side storage with preloaded data
+    const clientStorage = InMemoryStorageCSFactory({ settings: fullSettings });
+    setRolloutPlan(loggerMock, rolloutPlan, clientStorage, fullSettings.core.key as string);
+
+    // Shared client storage
+    const sharedClientStorage = clientStorage.shared!(otherKey);
+    setRolloutPlan(loggerMock, rolloutPlan, { segments: sharedClientStorage.segments, largeSegments: sharedClientStorage.largeSegments }, otherKey);
+
+    expect(clientStorage.segments.getRegisteredSegments()).toEqual(['segment1']);
+    expect(sharedClientStorage.segments.getRegisteredSegments()).toEqual(['segment1']);
+
+    expect(rolloutPlan).toEqual({ ...expectedRolloutPlan, memberships: undefined });
+  });
+
+  test('using preloaded data with memberships and segments', () => {
+    const rolloutPlan = getRolloutPlan(loggerMock, serverStorage, { keys: [fullSettings.core.key as string], exposeSegments: true });
+
+    // @ts-expect-error Load client-side storage with preloaded data
+    const clientStorage = InMemoryStorageCSFactory({ settings: fullSettings });
+    setRolloutPlan(loggerMock, rolloutPlan, clientStorage, fullSettings.core.key as string);
+
+    // Shared client storage
+    const sharedClientStorage = clientStorage.shared!(otherKey);
+    setRolloutPlan(loggerMock, rolloutPlan, { segments: sharedClientStorage.segments, largeSegments: sharedClientStorage.largeSegments }, otherKey);
+
+    expect(clientStorage.segments.getRegisteredSegments()).toEqual(['segment1']); // main client membership is set via the rollout plan `memberships` field
+    expect(sharedClientStorage.segments.getRegisteredSegments()).toEqual(['segment1']); // shared client membership is set via the rollout plan `segmentChanges` field
+
+    expect(rolloutPlan).toEqual({ ...expectedRolloutPlan, memberships: { [fullSettings.core.key as string]: expectedRolloutPlan.memberships![fullSettings.core.key as string] } });
+  });
+});