diff --git a/.github/workflows/sonar-scan.yml b/.github/workflows/sonar-scan.yml index b10b26a..c114c56 100644 --- a/.github/workflows/sonar-scan.yml +++ b/.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/*' diff --git a/CHANGES.txt b/CHANGES.txt index 916ccad..aa54aa4 100644 --- a/CHANGES.txt +++ b/CHANGES.txt @@ -1,9 +1,15 @@ +1.0.1 (November 11, 2024) + - Bugfixing - Revert removal of TypeScript `SplitIO` namespace at `/types/splitio.d.ts` to allow explicit imports of types from the Browser SDK package. E.g., `import type { IClientSideSettings } from '@splitsoftware/splitio-browserjs/types/splitio';`. + 1.0.0 (November 1, 2024) - Added support for targeting rules based on large segments. - Added `factory.destroy()` method, which invokes the `destroy` method of all clients created by the factory. - Updated @splitsoftware/splitio-commons package to version 2.0.0 that includes major updates and updated some transitive dependencies for vulnerability fixes. - BREAKING CHANGES: + - NOTE: Refer to ./MIGRATION-GUIDE.md for instructions on how to migrate your codebase from version 0.x to 1.0.0. - Dropped support for Split Proxy below version 5.9.0. The SDK now requires Split Proxy 5.9.0 or above. + - Renamed some TypeScript definitions in the `SplitIO` namespace to avoid conflicts with other Split packages: `IBrowserSettings`, `IBrowserAsyncSettings`, `ISDK`, `IAsyncSDK`, `IClient`, and `IAsyncClient` were renamed to `IClientSideSettings`, `IClientSideAsyncSettings`, `IBrowserSDK`, `IBrowserAsyncSDK`, `IBrowserClient` and `IBrowserAsyncClient` respectively. + - Removed TypeScript `SplitIO` namespace from `@splitsoftware/splitio-browserjs/types/splitio`. Reverted in 1.0.1. - Removed internal ponyfills for the `Map` and `Set` global objects, dropping support for IE and other outdated browsers. The SDK now requires the runtime environment to support these features natively or provide a polyfill. - Removed the deprecated `GoogleAnalyticsToSplit` and `SplitToGoogleAnalytics` pluggable integration modules, along with the related interfaces in the TypeScript definitions. - Removed the `LocalhostFromObject` export from the default import (`import { LocalhostFromObject } from '@splitsoftware/splitio-browserjs'`). It is no longer necessary to manually import and configure it in the `sync.localhostMode` option to enable localhost mode. diff --git a/MIGRATION-GUIDE.md b/MIGRATION-GUIDE.md new file mode 100644 index 0000000..b3f4eab --- /dev/null +++ b/MIGRATION-GUIDE.md @@ -0,0 +1,85 @@ +# Migrating to JavaScript Browser SDK v1 + +JavaScript Browser SDK v1.0.0 has a few breaking changes that you should consider when migrating from version 0.x.x. + +## Renamed some TypeScript definitions in the `SplitIO` namespace to avoid conflicts with other Split packages + +The renamed types are: +- `SplitIO.IBrowserSettings` -> `SplitIO.IClientSideSettings` +- `SplitIO.IBrowserAsyncSettings` -> `SplitIO.IClientSideAsyncSettings` +- `SplitIO.ISDK` -> `SplitIO.IBrowserSDK` +- `SplitIO.IAsyncSDK` -> `SplitIO.IBrowserAsyncSDK` +- `SplitIO.IClient` -> `SplitIO.IBrowserClient` +- `SplitIO.IAsyncClient` -> `SplitIO.IBrowserAsyncClient` + +For example, you should replace: + +```ts +import { SplitFactory } from '@splitsoftware/splitio-browserjs'; + +const config: SplitIO.IBrowserSettings = { ... }; +const factory: SplitIO.ISDK = SplitFactory(config); +``` + +with: + +```ts +import { SplitFactory } from '@splitsoftware/splitio-browserjs'; + +const config: SplitIO.IClientSideSettings = { ... }; +const factory: SplitIO.IBrowserSDK = SplitFactory(config); +``` + + +## Removed the `LocalhostFromObject` export from the default import + +In order to simplify the SDK API, the `LocalhostFromObject` export was removed from the default import (`import { LocalhostFromObject } from '@splitsoftware/splitio-browserjs'`), and it is no longer necessary to manually pass it to the `sync.localhostMode` configuration option to enable localhost mode. + +If you were using the `LocalhostFromObject` export, you should remove it from your code. For example, replace: + +```js +import { SplitFactory, LocalhostFromObject } from '@splitsoftware/splitio-browserjs'; + +const factory = SplitFactory({ + core: { + authorizationKey: 'localhost', + key: SOME_KEY + }, + features: { + 'feature1': 'on' + }, + sync: { + localhostMode: LocalhostFromObject() + } +}); +``` + +with: + +```js +import { SplitFactory } from '@splitsoftware/splitio-browserjs'; + +const factory = SplitFactory({ + core: { + authorizationKey: 'localhost', + key: SOME_KEY + }, + features: { + 'feature1': 'on' + } +}); +``` + +## Removed the deprecated `GoogleAnalyticsToSplit` and `SplitToGoogleAnalytics` pluggable integration modules, along with the related 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). Check [this docs](https://help.split.io/hc/en-us/articles/360040838752-Google-Analytics#google-analytics-4-ga4) for more information on how to integrate Split with Google Analytics 4. + +## 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`. + +## Dropped support for Split Proxy below version 5.9.0. The SDK now requires Split Proxy 5.9.0 or above + +If using the Split Proxy with the SDK, 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, which uses a new HTTP endpoint to retrieve the segments data and is only supported by Split Proxy 5.9.0. diff --git a/README.md b/README.md index cc2d9c1..2c68837 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,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) diff --git a/package-lock.json b/package-lock.json index c395c58..5485e80 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@splitsoftware/splitio-browserjs", - "version": "1.0.0", + "version": "1.0.1", "lockfileVersion": 2, "requires": true, "packages": { "": { "name": "@splitsoftware/splitio-browserjs", - "version": "1.0.0", + "version": "1.0.1", "license": "Apache-2.0", "dependencies": { "@splitsoftware/splitio-commons": "2.0.0", diff --git a/package.json b/package.json index d685b0b..322a961 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@splitsoftware/splitio-browserjs", - "version": "1.0.0", + "version": "1.0.1", "description": "Split SDK for JavaScript on Browser", "main": "cjs/index.js", "module": "esm/index.js", diff --git a/src/settings/defaults.ts b/src/settings/defaults.ts index fd82a4e..7d76258 100644 --- a/src/settings/defaults.ts +++ b/src/settings/defaults.ts @@ -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.0.0'; +const packageVersion = '1.0.1'; /** * In browser, the default debug level, can be set via the `localStorage.splitio_debug` item. diff --git a/ts-tests/index.ts b/ts-tests/index.ts index 6195c90..bdc4073 100644 --- a/ts-tests/index.ts +++ b/ts-tests/index.ts @@ -11,6 +11,8 @@ * @author Nico Zelaya */ +import type * as SplitTypes from '../types/splitio'; + import { SplitFactory as SplitFactoryFull, InLocalStorage as InLocalStorageFull, DebugLogger as DebugLoggerFull, InfoLogger as InfoLoggerFull, WarnLogger as WarnLoggerFull, ErrorLogger as ErrorLoggerFull, PluggableStorage as PluggableStorageFull } from '../types/full'; import { SplitFactory, InLocalStorage, DebugLogger, InfoLogger, WarnLogger, ErrorLogger, PluggableStorage } from '../types/index'; @@ -19,6 +21,11 @@ let splitFactory = SplitFactory; splitFactory = SplitFactoryFull; let inLocalStorage = InLocalStorage; inLocalStorage = InLocalStorageFull; let pluggableStorage = PluggableStorage; pluggableStorage = PluggableStorageFull; +// Validate that the SplitIO namespace is available and matches the types when imported explicitly +let ambientType: SplitIO.ISDK; +let importedType: SplitTypes.ISDK; +ambientType = importedType; + let stringPromise: Promise; let splitNamesPromise: Promise; let splitViewPromise: Promise; @@ -149,13 +156,13 @@ splitKey = 'someKey'; /**** 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' @@ -210,9 +217,7 @@ SDK.settings.features = { 'split_x': 'on' }; // Client and Manager client = SDK.client(); client = SDK.client('a customer key'); -// client = SDK.client('a customer key', 'a traffic type'); // Not valid in Browser JS SDK manager = SDK.manager(); -// // Today async clients are only possible on Node. Shared client creation not available here. asyncClient = AsyncSDK.client(); asyncManager = AsyncSDK.manager(); @@ -242,7 +247,7 @@ splitEvent = client.Event.SDK_READY_FROM_CACHE; splitEvent = client.Event.SDK_READY_TIMED_OUT; splitEvent = client.Event.SDK_UPDATE; -// Client implements methods from IEventEmitter that is a subset of NodeJS.Events. Testing a few. +// Client implements methods from IEventEmitter that is a subset of Node.js EventEmitter. Testing a few. client = client.on(splitEvent, () => { }); const a: boolean = client.emit(splitEvent); client = client.removeAllListeners(splitEvent); @@ -334,7 +339,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); @@ -421,7 +426,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); @@ -444,7 +449,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); diff --git a/types/full/index.d.ts b/types/full/index.d.ts index 521c48a..7ce5b8b 100644 --- a/types/full/index.d.ts +++ b/types/full/index.d.ts @@ -2,7 +2,7 @@ // Project: http://www.split.io/ // Definitions by: Nico Zelaya -import '@splitsoftware/splitio-commons'; +/// export = JsSdk; diff --git a/types/index.d.ts b/types/index.d.ts index 796120d..040dfaa 100644 --- a/types/index.d.ts +++ b/types/index.d.ts @@ -2,7 +2,7 @@ // Project: http://www.split.io/ // Definitions by: Nico Zelaya -import '@splitsoftware/splitio-commons'; +/// export = JsSdk; diff --git a/types/splitio.d.ts b/types/splitio.d.ts new file mode 100644 index 0000000..16290bd --- /dev/null +++ b/types/splitio.d.ts @@ -0,0 +1,6 @@ +// Type definitions for JavaScript Browser Split Software SDK + +import '@splitsoftware/splitio-commons'; + +export as namespace SplitIO; +export = SplitIO;