Merge pull request #169 from splitio/fme-12310

update commons - events with metadata

Author: ZamoraEmmanuel

CHANGES.txt

@@ -1,3 +1,7 @@
+1.7.0 (January 28, 2026)
+ - Updated @splitsoftware/splitio-commons package to version 2.11.0, which:
+    - Added functionality to provide metadata alongside SDK update and READY events. Read more in our docs.
+
 1.6.1 (December 30, 2025)
  - Updated @splitsoftware/splitio-commons package to version 2.10.1 and other transitive dependencies for vulnerability fixes.
  - Updated the order of storage operations to prevent inconsistent states when using the `InLocalStorage` module and the browser’s `localStorage` fails due to quota limits.

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@splitsoftware/splitio-browserjs",
-  "version": "1.6.1",
+  "version": "1.7.0",
   "description": "Split SDK for JavaScript on Browser",
   "main": "cjs/index.js",
   "module": "esm/index.js",
@@ -59,7 +59,7 @@
   "bugs": "https://github.com/splitio/javascript-browser-client/issues",
   "homepage": "https://github.com/splitio/javascript-browser-client#readme",
   "dependencies": {
-    "@splitsoftware/splitio-commons": "2.10.1",
+    "@splitsoftware/splitio-commons": "2.11.0",
     "tslib": "^2.3.1",
     "unfetch": "^4.2.0"
   },

package.json

@@ -96,7 +96,7 @@ export function testSplitKillOnReadyFromCache(fetchMock, assert) {
   });
   client.on(client.Event.SDK_READY, () => {
     const lapse = Date.now() - start;
-    assert.true(nearlyEqual(lapse, MILLIS_SPLIT_CHANGES_RESPONSE), 'SDK_READY once split changes arrives');
+    assert.true(nearlyEqual(lapse, MILLIS_SPLIT_CHANGES_RESPONSE, 200), 'SDK_READY once split changes arrives');
 
     client.destroy().then(() => { assert.end(); });
   });

src/__tests__/browserSuites/push-corner-cases.spec.js

@@ -282,7 +282,7 @@ export default function (fetchMock, assert) {
       events: 'https://events.baseurl/readyFromCacheWithData3'
     };
     localStorage.clear();
-    t.plan(12 * 2 + 5);
+    t.plan(12 * 2 + 5 + 4); // +4 for SdkReadyMetadata assertions on SDK_READY_FROM_CACHE and SDK_READY
 
     fetchMock.get(testUrls.sdk + '/splitChanges?s=1.3&since=25&rbSince=-1', () => {
       t.equal(localStorage.getItem('readyFromCache_3.SPLITIO.split.always_on'), alwaysOnSplitInverted, 'feature flags must not be cleaned from cache');
@@ -330,9 +330,13 @@ export default function (fetchMock, assert) {
       t.end();
     });
 
-    client.on(client.Event.SDK_READY_FROM_CACHE, () => {
+    client.on(client.Event.SDK_READY_FROM_CACHE, (metadata) => {
       t.true(Date.now() - startTime < 400, 'It should emit SDK_READY_FROM_CACHE on every client if there was data in the cache and we subscribe on time. Should be considerably faster than actual readiness from the cloud.');
       t.equal(client.getTreatment('always_on'), 'off', 'It should evaluate treatments with data from cache instead of control due to Input Validation');
+      // SdkReadyMetadata: when ready from cache, initialCacheLoad is false; lastUpdateTimestamp is number or undefined
+      t.true(metadata != null && typeof metadata.initialCacheLoad === 'boolean', 'SDK_READY_FROM_CACHE must receive SdkReadyMetadata with initialCacheLoad');
+      t.true(metadata.initialCacheLoad === false, 'When ready from existing cache, initialCacheLoad must be false');
+      t.true(metadata.lastUpdateTimestamp === undefined || typeof metadata.lastUpdateTimestamp === 'number', 'SdkReadyMetadata.lastUpdateTimestamp must be number or undefined');
 
       const client4 = splitio.client('nicolas4@split.io');
       t.equal(client4.getTreatment('always_on'), 'off', 'It should evaluate treatments with data from cache instead of control');
@@ -350,9 +354,10 @@ export default function (fetchMock, assert) {
       t.equal(client3.getTreatment('always_on'), 'off', 'It should evaluate treatments with data from cache instead of control due to Input Validation');
     });
 
-    client.on(client.Event.SDK_READY, () => {
+    client.on(client.Event.SDK_READY, (metadata) => {
       t.true(Date.now() - startTime >= 400, 'It should emit SDK_READY too but after syncing with the cloud.');
       t.equal(client.getTreatment('always_on'), 'on', 'It should evaluate treatments with updated data after syncing with the cloud.');
+      t.true(metadata != null && typeof metadata.initialCacheLoad === 'boolean', 'SDK_READY must receive SdkReadyMetadata with initialCacheLoad');
     });
     client.ready().then(() => {
       t.true(Date.now() - startTime >= 400, 'It should resolve ready promise after syncing with the cloud.');

src/__tests__/browserSuites/ready-from-cache.spec.js

@@ -119,7 +119,9 @@ export default function readyPromiseAssertions(fetchMock, assert) {
     const manager = splitio.manager();
 
     manager.whenReady()
-      .then(() => {
+      .then((metadata) => {
+        t.true(metadata != null && typeof metadata.initialCacheLoad === 'boolean', 'whenReady must resolve with SdkReadyMetadata.initialCacheLoad');
+        t.true(metadata.lastUpdateTimestamp === undefined || typeof metadata.lastUpdateTimestamp === 'number', 'whenReady SdkReadyMetadata.lastUpdateTimestamp must be number or undefined');
         t.pass('### SDK IS READY - the retry request is under the limits.');
         assertGetTreatmentWhenReady(t, client);
 
@@ -521,7 +523,10 @@ export default function readyPromiseAssertions(fetchMock, assert) {
 
     consoleSpy.log.resetHistory();
     setTimeout(() => {
-      client.whenReadyFromCache().then((isReady) => t.true(isReady, 'SDK IS READY (& READY FROM CACHE) - Should resolve')).catch(() => t.fail('SDK TIMED OUT - Should not reject'));
+      client.whenReadyFromCache().then((metadata) => {
+        t.true(metadata != null && typeof metadata.initialCacheLoad === 'boolean', 'whenReadyFromCache must resolve with SdkReadyMetadata');
+        t.true(metadata.lastUpdateTimestamp === undefined || typeof metadata.lastUpdateTimestamp === 'number', 'whenReadyFromCache SdkReadyMetadata.lastUpdateTimestamp must be number or undefined');
+      }).catch(() => t.fail('SDK TIMED OUT - Should not reject'));
 
       assertGetTreatmentWhenReady(t, client);
 

src/__tests__/browserSuites/ready-promise.spec.js

@@ -100,14 +100,17 @@ tape('Browser offline mode', function (assert) {
   for (let i = 0; i < factories.length; i++) {
     const factory = factories[i], client = factory.client(), manager = factory.manager(), client2 = factory.client('other');
 
-    client.on(client.Event.SDK_READY, () => {
+    client.on(client.Event.SDK_READY, (metadata) => {
       assert.deepEqual(manager.names(), ['testing_split', 'testing_split_with_config']);
       assert.equal(client.getTreatment('testing_split_with_config'), 'off');
+      assert.true(metadata != null && typeof metadata.initialCacheLoad === 'boolean', 'SDK_READY must receive SdkReadyMetadata with initialCacheLoad');
       readyCount++;
     });
-    client.on(client.Event.SDK_UPDATE, () => {
+    client.on(client.Event.SDK_UPDATE, (metadata) => {
       assert.deepEqual(manager.names().sort(), ['testing_split', 'testing_split_2', 'testing_split_3', 'testing_split_with_config']);
       assert.equal(client.getTreatment('testing_split_with_config'), 'nope');
+      assert.true(metadata != null && typeof metadata.type === 'string' && ['FLAGS_UPDATE', 'SEGMENTS_UPDATE'].includes(metadata.type), 'SDK_UPDATE must receive SdkUpdateMetadata with type FLAGS_UPDATE or SEGMENTS_UPDATE');
+      assert.true(Array.isArray(metadata.names), 'SDK_UPDATE must receive SdkUpdateMetadata with names array');
       updateCount++;
     });
     client.on(client.Event.SDK_READY_TIMED_OUT, () => {
@@ -252,8 +255,10 @@ tape('Browser offline mode', function (assert) {
     setTimeout(() => { factory.settings.features = { testing_split: 'on', testing_split_with_config: { treatment: 'off', config: '{ "color": "blue" }' } }; }, 750);
 
     // once updated, test again.
-    client.once(client.Event.SDK_UPDATE, function () {
+    client.once(client.Event.SDK_UPDATE, function (metadata) {
       assert.true((Date.now() - readyTimestamp) > 1000, 'Should only emit SDK_UPDATE after a real update.');
+      assert.true(metadata != null && typeof metadata.type === 'string' && ['FLAGS_UPDATE', 'SEGMENTS_UPDATE'].includes(metadata.type), 'SDK_UPDATE must receive SdkUpdateMetadata with type');
+      assert.true(Array.isArray(metadata.names), 'SDK_UPDATE must receive SdkUpdateMetadata with names array');
 
       client.once(client.Event.SDK_UPDATE, function () { assert.fail('Should not emit a second SDK_UPDATE event'); });
 

src/__tests__/offline/browser.spec.js

@@ -2,7 +2,7 @@ import type SplitIO from '@splitsoftware/splitio-commons/types/splitio';
 import { LogLevels, isLogLevelString } from '@splitsoftware/splitio-commons/src/logger/index';
 import { CONSENT_GRANTED } from '@splitsoftware/splitio-commons/src/utils/constants';
 
-const packageVersion = '1.6.1';
+const packageVersion = '1.7.0';
 
 /**
  * In browser, the default debug level, can be set via the `localStorage.splitio_debug` item.

src/settings/defaults.ts

@@ -278,12 +278,12 @@ client = client.removeAllListeners();
 
 // Ready and destroy
 let promise: Promise<void> = client.ready();
-promise = client.whenReady();
 promise = client.destroy();
 promise = SDK.destroy();
 // @TODO not public yet
 // promise = client.flush();
-const promiseWhenReadyFromCache: Promise<boolean> = client.whenReadyFromCache();
+let promiseWithMetadata: Promise<SplitIO.SdkReadyMetadata> = client.whenReady();
+promiseWithMetadata = client.whenReadyFromCache();
 
 // Get readiness status
 let status: SplitIO.ReadinessStatus = client.getStatus();
@@ -374,6 +374,63 @@ tracked = client.track('myTrafficType', 'myEventType', 10);
 tracked = client.track('myTrafficType', 'myEventType', null, { prop1: 1, prop2: '2', prop3: false, prop4: null });
 // tracked = client.track('myEventType', undefined, { prop1: 1, prop2: '2', prop3: false, prop4: null }); // Not valid in Browser JS SDK
 
+/*** Tests for SDK Update Metadata ***/
+
+// Using addListener with typed metadata
+client.addListener(client.Event.SDK_UPDATE, (metadata: SplitIO.SdkUpdateMetadata) => {
+  const type: SplitIO.SdkUpdateMetadataType = metadata.type;
+  const names: string[] = metadata.names;
+});
+client.addListener(client.Event.SDK_READY, (metadata: SplitIO.SdkReadyMetadata) => {
+  const fromCache: boolean = metadata.initialCacheLoad;
+  const timestamp: number = metadata.lastUpdateTimestamp;
+});
+client.addListener(client.Event.SDK_READY_FROM_CACHE, (metadata: SplitIO.SdkReadyMetadata) => {
+  const fromCache: boolean = metadata.initialCacheLoad;
+  const timestamp: number = metadata.lastUpdateTimestamp;
+});
+client.addListener(client.Event.SDK_UPDATE, () => { });
+client.addListener(client.Event.SDK_READY, () => { });
+client.addListener(client.Event.SDK_READY_FROM_CACHE, () => { });
+
+// Using once with typed metadata
+client.once(client.Event.SDK_UPDATE, (metadata: SplitIO.SdkUpdateMetadata) => {
+  const type: SplitIO.SdkUpdateMetadataType = metadata.type;
+  const names: string[] = metadata.names;
+});
+client.once(client.Event.SDK_READY, (metadata: SplitIO.SdkReadyMetadata) => {
+  const fromCache: boolean = metadata.initialCacheLoad;
+  const timestamp: number = metadata.lastUpdateTimestamp;
+});
+client.once(client.Event.SDK_READY_FROM_CACHE, (metadata: SplitIO.SdkReadyMetadata) => {
+  const fromCache: boolean = metadata.initialCacheLoad;
+  const timestamp: number = metadata.lastUpdateTimestamp;
+});
+client.once(client.Event.SDK_UPDATE, () => { });
+client.once(client.Event.SDK_READY, () => { });
+client.once(client.Event.SDK_READY_FROM_CACHE, () => { });
+
+// SDK_READY event listener with metadata
+client.on(client.Event.SDK_READY, (metadata: SplitIO.SdkReadyMetadata) => {
+  const fromCache: boolean = metadata.initialCacheLoad;
+  const timestamp: number = metadata.lastUpdateTimestamp;
+});
+
+// SDK_READY_FROM_CACHE event listener with metadata
+client.on(client.Event.SDK_READY_FROM_CACHE, (metadata: SplitIO.SdkReadyMetadata) => {
+  const fromCache: boolean = metadata.initialCacheLoad;
+  const timestamp: number = metadata.lastUpdateTimestamp;
+});
+
+// SDK_UPDATE event listener with metadata
+client.on(client.Event.SDK_UPDATE, (metadata: SplitIO.SdkUpdateMetadata) => {
+  const type: SplitIO.SdkUpdateMetadataType = metadata.type;
+  const names: string[] = metadata.names;
+});
+client.on(client.Event.SDK_UPDATE, () => { });
+client.on(client.Event.SDK_READY, () => { });
+client.on(client.Event.SDK_READY_FROM_CACHE, () => { });
+
 /*** Repeating tests for Async Client ***/
 
 // Events constants we get (same as for sync client, just for interface checking)