Merge pull request #353 from splitio/data_loader_for_ssr

[FME-9871] Data loader for server-side rendering

Author: EmilianoSanchez

CHANGES.txt

@@ -1,3 +1,7 @@
+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.1",
+  "version": "2.5.0",
   "description": "Split JavaScript SDK common components",
   "main": "cjs/index.js",
   "module": "esm/index.js",

package.json

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

@@ -8,15 +8,13 @@ import { IMembershipsResponse, IMySegmentsResponse } from '../dtos/types';
 
 /**
  * Gets the rollout plan snapshot from the given synchronous storage.
- * If `keys` are provided, the memberships for those keys is returned, to protect segments data.
- * Otherwise, the segments data is returned.
  */
 export function getRolloutPlan(log: ILogger, storage: IStorageSync, options: SplitIO.RolloutPlanOptions = {}): RolloutPlan {
 
   const { keys, exposeSegments } = options;
   const { splits, segments, rbSegments } = storage;
 
-  log.debug(`storage: get feature flags${keys ? `, and memberships for keys ${keys}` : ''}${exposeSegments ? ', and segments' : ''}`);
+  log.debug(`storage: get feature flags${keys ? `, and memberships for keys: ${keys}` : ''}${exposeSegments ? ', and segments' : ''}`);
 
   return {
     splitChanges: {

src/storages/getRolloutPlan.ts

@@ -17,7 +17,7 @@ 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) {
-  const { log } = settings;
+  const { log, initialRolloutPlan } = settings;
 
   // Check expiration
   const lastUpdatedTimestamp = parseInt(localStorage.getItem(keys.buildLastUpdatedKey()) as string, 10);
@@ -41,7 +41,7 @@ function validateExpiration(options: SplitIO.InLocalStorageOptions, settings: IS
     } catch (e) {
       log.error(LOG_PREFIX + e);
     }
-    if (isThereCache) {
+    if (isThereCache && !initialRolloutPlan) {
       log.info(LOG_PREFIX + 'SDK key, flags filter criteria, or flags spec version has changed. Cleaning up cache');
       return true;
     }

src/storages/inLocalStorage/validateCache.ts

@@ -497,8 +497,6 @@ export interface IStorageAsync extends IStorageBase<
 
 /** StorageFactory */
 
-export type DataLoader = (storage: IStorageSync, matchingKey: string) => void
-
 export interface IStorageFactoryParams {
   settings: ISettings,
   /**

src/storages/types.ts

@@ -7,6 +7,7 @@ import { ISettingsValidationParams } from './types';
 import { ISettings } from '../../types';
 import { validateKey } from '../inputValidation/key';
 import { ERROR_MIN_CONFIG_PARAM, LOG_PREFIX_CLIENT_INSTANTIATION } from '../../logger/constants';
+import { validateRolloutPlan } from '../../storages/setRolloutPlan';
 
 // Exported for telemetry
 export const base = {
@@ -152,6 +153,9 @@ export function settingsValidation(config: unknown, validationParams: ISettingsV
   // @ts-ignore, modify readonly prop
   if (storage) withDefaults.storage = storage(withDefaults);
 
+  // @ts-ignore, modify readonly prop
+  if (withDefaults.initialRolloutPlan) withDefaults.initialRolloutPlan = validateRolloutPlan(log, withDefaults);
+
   // Validate key and TT (for client-side)
   const maybeKey = withDefaults.core.key;
   if (validationParams.acceptKey) {

src/utils/settingsValidation/index.ts

@@ -1594,7 +1594,14 @@ declare namespace SplitIO {
     /**
      * Returns the current snapshot of the SDK rollout plan in cache.
      *
-     * @param keys - Optional list of keys to generate the rollout plan snapshot with the memberships of the given keys, rather than the complete segments data.
+     * Wait for the SDK client to be ready before calling this method.
+     *
+     * ```js
+     * await factory.client().ready();
+     * const rolloutPlan = factory.getRolloutPlan();
+     * ```
+     *
+     * @param options - An object of type RolloutPlanOptions for advanced options.
      * @returns The current snapshot of the SDK rollout plan.
      */
     getRolloutPlan(options?: RolloutPlanOptions): RolloutPlan;