Merge pull request #839 from splitio/migration_guide

Add Migration guide

Author: EmilianoSanchez

.github/workflows/sonar-scan.yml

@@ -19,7 +19,7 @@ jobs:
         with:
           fetch-depth: 0
 
-      - name: Set up nodejs
+      - name: Set up Node.js
         uses: actions/setup-node@v3
         with:
           node-version: 'lts/*'

CHANGES.txt

@@ -7,7 +7,7 @@ Split SDK is an open source project and we welcome feedback and contribution. Th
 ### Development process
 
 1. Fork the repository and create a topic branch from `development` branch. Please use a descriptive name for your branch.
-2. Run `nvm use` to ensure that you are using the right npm and node version, and `npm install` to have the dependencies up to date.
+2. Run `nvm use` to ensure that you are using the right npm and Node.js version, and `npm install` to have the dependencies up to date.
 3. While developing, use descriptive messages in your commits. Avoid short or meaningless sentences like: "fix bug".
 4. Make sure to add tests for both positive and negative cases.
 5. If your changes have any impact on the public API, make sure you update the TypeScript declarations as well as it's related test file.
@@ -46,7 +46,7 @@ Consider running the linter script (`npm run check:lint`) and fixing any issues
 
 If you want to debug your changes consuming it from a test application, you could:
 - For browsers, import the **UMD** bundle from an HTML document. To debug you can use the browser dev tools.
-- For Node, you could use symlinks via [npm link command](https://docs.npmjs.com/cli/link.html) and then import the package as usual. To debug you could use the [Node inspector](https://nodejs.org/en/docs/guides/debugging-getting-started/).
+- For Node.js, you could use symlinks via [npm link command](https://docs.npmjs.com/cli/link.html) and then import the package as usual. To debug you could use the [Node.js inspector](https://nodejs.org/en/docs/guides/debugging-getting-started/).
 
 # Contact
 

CONTRIBUTORS-GUIDE.md

@@ -0,0 +1,70 @@
+# Migrating to JavaScript SDK v11
+
+JavaScript SDK v11.0.0 has a few breaking changes that you should consider when migrating from version 10.x.x.
+
+## Changes that affect server-side API (Node.js)
+
+While JavaScript SDK previously supported Node.js v6 and above, the SDK now requires Node.js v14 or above.
+
+## Changes that affect client-side API (Browser)
+
+Below you will find a list of the changes:
+
+- **Removed the `core.trafficType` configuration option (`SplitIO.IBrowserSettings['core']['trafficType]`) and the `trafficType` parameter from the SDK `client()` method in Browser (`SplitIO.IBrowserSDK['client']`). As a result, traffic types can no longer be bound to SDK clients, and the traffic type must be provided in the `track` method.**
+
+This change was made to align the SDK with the client-side APIs of the [Browser SDK](https://help.split.io/hc/en-us/articles/360058730852-Browser-SDK) and [React Native SDK](https://help.split.io/hc/en-us/articles/4406066357901-React-Native-SDK).
+
+SDK clients cannot be bound to a traffic type anymore, and so the traffic type must be provided when calling the `client.track` method. For example:
+
+```javascript
+// JS SDK v10.x.x
+const factory = SplitFactory({
+  core: {
+    authorizationKey: '...',
+    key: USER_KEY,
+    trafficType: 'user'
+  }
+});
+
+const client = factory.client();
+const accountClient = factory.client(ACCOUNT_ID, 'account');
+
+client.track('my_event');
+accountClient.track('my_event');
+```
+
+should be replaced with:
+
+```javascript
+// JS SDK v11.0.0
+const factory = SplitFactory({
+  core: {
+    authorizationKey: '...',
+    key: USER_KEY
+  }
+});
+
+const client = factory.client();
+const accountClient = factory.client(ACCOUNT_ID);
+
+client.track('usuer', 'my_event');
+accountClient.track('account', 'my_event');
+```
+
+- **Removed the deprecated `GOOGLE_ANALYTICS_TO_SPLIT` and `SPLIT_TO_GOOGLE_ANALYTICS` integrations. The `integrations` configuration option has been removed from the SDK factory configuration, along with the associated interfaces in the TypeScript definitions.**
+
+The Google Analytics integrations were removed since they integrate with the *Google Universal Analytics* library, which was shut down on July 1, 2024, and [replaced by *Google Analytics 4*](https://support.google.com/analytics/answer/11583528?hl=en). Go to Split's [Google Analytics integration guide](https://help.split.io/hc/en-us/articles/360040838752-Google-Analytics) for more information on how to integrate Split with Google Analytics 4.
+
+The integrations have stopped being used and maintained, and were removed from the SDK, together with the `integrations` configuration option. If you were using the `integrations` option, you should remove it from your SDK configuration object.
+
+- **Removed internal polyfills for the `Map` and `Set` global objects, dropping support for IE and other outdated browsers.**
+
+The SDK no longer ships with internal implementations for the `Map` and `Set` global objects, which were used to support old browsers like IE.
+
+If you need to target environments that do not support these features natively, you should provide a polyfill for them. For example, [es6-map](https://github.com/medikoo/es6-map) for `Map`, and [es6-set](https://github.com/medikoo/es6-set) for `Set`.
+
+In addition, the Split SDK depends on support for ES6 promises. Since v10.2.0, the SDK does not pollute any global variable to add the ES6 promise polyfill. If your environment does not support ES6 promises, you can [polyfill](https:/github.com/stefanpenner/es6-promise).
+
+- **Dropped support for Split Proxy below version 5.9.0, when using in the browser (client-side API). The SDK now requires Split Proxy 5.9.0 or above.**
+
+If using the Split Proxy with the SDK in the browser, make sure to update it to version 5.9.0 or above. This is required due to the introduction of Large Segments matchers in the SDK on client-side, which uses a new HTTP endpoint to retrieve the segments data and is only supported by Split Proxy 5.9.0.

MIGRATION-GUIDE.md

@@ -71,7 +71,7 @@ Split has built and maintains SDKs for:
 * Java [Github](https://github.com/splitio/java-client) [Docs](https://help.split.io/hc/en-us/articles/360020405151-Java-SDK)
 * JavaScript [Github](https://github.com/splitio/javascript-client) [Docs](https://help.split.io/hc/en-us/articles/360020448791-JavaScript-SDK)
 * JavaScript for Browser [Github](https://github.com/splitio/javascript-browser-client) [Docs](https://help.split.io/hc/en-us/articles/360058730852-Browser-SDK)
-* Node [Github](https://github.com/splitio/javascript-client) [Docs](https://help.split.io/hc/en-us/articles/360020564931-Node-js-SDK)
+* Node.js [Github](https://github.com/splitio/javascript-client) [Docs](https://help.split.io/hc/en-us/articles/360020564931-Node-js-SDK)
 * PHP [Github](https://github.com/splitio/php-client) [Docs](https://help.split.io/hc/en-us/articles/360020350372-PHP-SDK)
 * PHP thin-client [Github](https://github.com/splitio/php-thin-client) [Docs](https://help.split.io/hc/en-us/articles/18305128673933-PHP-Thin-Client-SDK)
 * Python [Github](https://github.com/splitio/python-client) [Docs](https://help.split.io/hc/en-us/articles/360020359652-Python-SDK)

README.md

@@ -83,7 +83,7 @@ const initializeRedisServer = (mock = '') => {
         exec(`cat ./src/__tests__/mocks/${mockFileName}.txt | redis-cli -p ${redisPort}`, err => {
           if (err) {
             reject(server);
-            // node couldn't execute the command
+            // Node.js couldn't execute the command
             return;
           }
 
@@ -95,7 +95,7 @@ const initializeRedisServer = (mock = '') => {
   return promise;
 };
 
-tape('NodeJS Redis', function (t) {
+tape('Node.js Redis', function (t) {
 
   t.test('Regular usage - DEBUG strategy', assert => {
     initializeRedisServer()

src/__tests__/consumer/node_redis.spec.js

@@ -21,7 +21,7 @@ fetchMock.get(url(settings, '/splitChanges?s=1.1&since=-1'), { status: 200, body
 fetchMock.get(url(settings, '/splitChanges?s=1.1&since=1500492097547'), { status: 200, body: splitChangesMock2 });
 fetchMock.postOnce(url(settings, '/v1/metrics/config'), 200);
 
-tape('SDK destroy for NodeJS', async function (assert) {
+tape('SDK destroy for Node.js', async function (assert) {
   const config = {
     core: {
       authorizationKey: 'fake-key',

src/__tests__/destroy/node.spec.js

@@ -55,7 +55,7 @@ const settingsGenerator = mockFileName => {
 };
 
 
-tape('NodeJS Offline Mode', function (t) {
+tape('Node.js Offline Mode', function (t) {
 
   t.test('Old format evaluations - .split', DotSplitTests);
   t.test('New format evaluations - .yaml extension', DotYAMLTests.bind(null, 'split', 'yaml'));

src/__tests__/offline/node.spec.js

@@ -55,7 +55,7 @@ fetchMock.post(url(settings, '/testImpressions/count'), 200);
 fetchMock.post(url(settings, '/v1/metrics/config'), 200);
 fetchMock.post(url(settings, '/v1/metrics/usage'), 200);
 
-tape('## Node JS - E2E CI Tests ##', async function (assert) {
+tape('## Node.js - E2E CI Tests ##', async function (assert) {
   /* Check client evaluations. */
   assert.test('E2E / In Memory', evaluationsSuite.bind(null, config, key));
   assert.test('E2E / In Memory - Semver', evaluationsSemverSuite.bind(null, fetchMock));

src/__tests__/online/node.spec.js

@@ -13,7 +13,7 @@ fetchMock.config.overwriteRoutes = false;
 fetchMock.post('https://telemetry.split.io/api/v1/metrics/config', 200);
 fetchMock.post('https://telemetry.split.io/api/v1/metrics/usage', 200);
 
-tape('## Node JS - E2E CI Tests for PUSH ##', async function (assert) {
+tape('## Node.js - E2E CI Tests for PUSH ##', async function (assert) {
 
   // Non-recoverable issues on inizialization
   assert.test('E2E / PUSH initialization: auth with push disabled', testAuthWithPushDisabled.bind(null, fetchMock));

src/__tests__/push/node.spec.js

@@ -133,7 +133,7 @@ EventEmitter.prototype.emit = function emit(type) {
       er = args[0];
     if (er instanceof Error) {
       // Note: The comments on the `throw` lines are intentional, they show
-      // up in Node's output if this results in an unhandled exception.
+      // up in Node.js output if this results in an unhandled exception.
       throw er; // Unhandled 'error' event
     }
     // At least give some kind of context to the user

src/platform/EventEmitter.js

@@ -17,7 +17,7 @@ export function __setFetch(fetch) {
 }
 
 /**
- * Retrieves 'node-fetch', a Fetch API polyfill for NodeJS, with fallback to global 'fetch' if available.
+ * Retrieves 'node-fetch', a Fetch API polyfill for Node.js, with fallback to global 'fetch' if available.
  */
 export function getFetch() {
   return nodeFetch;

src/platform/getFetch/node.js

@@ -147,6 +147,6 @@ tape('SETTINGS / Log error and fallback to InMemory storage if no valid storage
 tape('SETTINGS / Consent is not overwritable in server-side', assert => {
   const settings = settingsFactory({ userConsent: 'UNKNOWN' });
 
-  assert.equal(settings.userConsent, undefined, 'userConsent cannot be overwritten in NodeJS.');
+  assert.equal(settings.userConsent, undefined, 'userConsent cannot be overwritten in Node.js.');
   assert.end();
 });

src/settings/__tests__/node.spec.js

@@ -68,7 +68,7 @@ export function validateStorage(settings) {
       };
     }
 
-    // For now, we don't have modifiers or settings for MEMORY in NodeJS
+    // For now, we don't have modifiers or settings for MEMORY in Node.js
     case STORAGE_MEMORY:
     default: {
       // If passing MEMORY storage in consumer mode, throw an error (no way to fallback to REDIS storage)

src/settings/storage/node.js

@@ -2,5 +2,5 @@ import { splitsParserFromFileFactory } from './splitsParserFromFile';
 import { syncManagerOfflineFactory } from '@splitsoftware/splitio-commons/src/sync/offline/syncManagerOffline';
 
 // Singleton instance of the factory function for offline SyncManager from YAML file
-// It uses NodeJS APIs.
+// It uses Node.js APIs.
 export const localhostFromFileFactory = syncManagerOfflineFactory(splitsParserFromFileFactory);

src/sync/offline/LocalhostFromFile.js

@@ -1,6 +1,6 @@
 /* eslint-disable no-redeclare */
 /*
-Trimmed version of "ip" package (https://www.npmjs.com/package/ip) that fixes an error when running in Node v18.
+Trimmed version of "ip" package (https://www.npmjs.com/package/ip) that fixes an error when running in Node.js v18.
 
 This software is licensed under the MIT License.
 

src/utils/ip.js

@@ -1,5 +1,5 @@
 /**
- * Run tests and scripts in Node while transpiling typescript files from `@splitsoftware/splitio-commons/src`
+ * Run tests and scripts in Node.js while transpiling typescript files from `@splitsoftware/splitio-commons/src`
  * https://www.npmjs.com/package/ts-node
  *
  * NOTE: can be used with `npm link @splitsoftware/splitio-commons` or `"@splitsoftware/splitio-commons": "file:../javascript-commons" without extra steps

ts-node.register.js

@@ -141,13 +141,13 @@ splitKey = splitKeyObj;
 
 /**** Tests for ISDK interface ****/
 
-// For node with sync storage
+// For Node.js with sync storage
 nodeSettings = {
   core: {
     authorizationKey: 'key'
   }
 };
-// For node with async storage
+// For Node.js with async storage
 asyncSettings = {
   core: {
     authorizationKey: 'key'
@@ -188,14 +188,14 @@ const instantiatedSettingsVersion: string = SDK.settings.version;
 let instantiatedSettingsFeatures = SDK.settings.features as SplitIO.MockedFeaturesMap;
 // We should be able to write on features prop. The rest are readonly props.
 instantiatedSettingsFeatures.something = 'something';
-SDK.settings.features = 'new_file_path'; // Node
+SDK.settings.features = 'new_file_path'; // Node.js
 SDK.settings.features = { 'split_x': 'on' }; // Browser
 
 // Client and Manager
 client = SDK.client();
 manager = SDK.manager();
 manager = BrowserSDK.manager();
-// Today async clients are only possible on Node. Shared client creation not available here.
+// Today async clients are only possible on Node.js. Shared client creation not available here.
 asyncClient = AsyncSDK.client();
 asyncManager = AsyncSDK.manager();
 // Browser client for attributes binding
@@ -228,7 +228,7 @@ splitEvent = client.Event.SDK_READY_FROM_CACHE;
 splitEvent = client.Event.SDK_READY_TIMED_OUT;
 splitEvent = client.Event.SDK_UPDATE;
 
-// Client implements methods from NodeJS.Events. Testing a few.
+// Client implements methods from Node.js EventEmitter. Testing a few.
 client = client.on(splitEvent, () => { });
 const a: boolean = client.emit(splitEvent);
 client = client.removeAllListeners(splitEvent);
@@ -318,7 +318,7 @@ splitEvent = asyncClient.Event.SDK_READY_FROM_CACHE;
 splitEvent = asyncClient.Event.SDK_READY_TIMED_OUT;
 splitEvent = asyncClient.Event.SDK_UPDATE;
 
-// Client implements methods from NodeJS.Events. (same as for sync client, just for interface checking)
+// Client implements methods from Node.js EventEmitter. (same as for sync client, just for interface checking)
 asyncClient = asyncClient.on(splitEvent, () => { });
 const a1: boolean = asyncClient.emit(splitEvent);
 asyncClient = asyncClient.removeAllListeners(splitEvent);
@@ -389,7 +389,7 @@ splitViews = manager.splits();
 // Manager implements ready promise.
 promise = manager.ready();
 
-// Manager implements methods from NodeJS.Events. Testing a few.
+// Manager implements methods from Node.js EventEmitter. Testing a few.
 manager = manager.on(splitEvent, () => { });
 const aa: boolean = manager.emit(splitEvent);
 manager = manager.removeAllListeners(splitEvent);
@@ -413,7 +413,7 @@ splitViewsAsync = asyncManager.splits();
 // asyncManager implements ready promise.
 promise = asyncManager.ready();
 
-// asyncManager implements methods from NodeJS.Events. Testing a few.
+// asyncManager implements methods from Node.js EventEmitter. Testing a few.
 asyncManager = asyncManager.on(splitEvent, () => { });
 const aaa: boolean = asyncManager.emit(splitEvent);
 asyncManager = asyncManager.removeAllListeners(splitEvent);

ts-tests/index.ts

@@ -1,4 +1,4 @@
-// Declaration file for JavaScript and Node Split Software SDK v8.1.0
+// Declaration file for JavaScript and Node.js Split Software SDK v8.1.0
 // Project: http://www.split.io/
 // Definitions by: Nico Zelaya <https://github.com/NicoZelaya/>