launchdarkly-js-sdk-common 5.0.0-alpha.7 → 5.0.1

package/.ldrelease/config.yml

@@ -6,7 +6,8 @@ repo:
 
 branches:
   - name: main
-    description: 4.x
+    description: 5.x
+  - name: 4.x
   - name: 3.x
 
 publications:

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 All notable changes to the `launchdarkly-js-sdk-common` package will be documented in this file. Changes that affect the dependent SDKs such as `launchdarkly-js-client-sdk` should also be logged in those projects, in the next release that uses the updated version of this package. This project adheres to [Semantic Versioning](http://semver.org).
 
+## [5.0.0] - 2022-11-30
+This major version release of `js-sdk-common` corresponds to the upcoming releases of the `js-client-sdk` v3 and `react-client-sdk` v3, and cannot be used with earlier SDK versions.
+
+### Added:
+- Replaced users with contexts. A context is a generalized way of referring to the people, services, machines, or other resources that encounter feature flags in your product. All methods which previously operated on `LDUser` now operate on `LDContext`.
+
+### Changed:
+- `LDClient.getUser` has been replaced with `LDClient.getContext`.
+- `privateAttributeNames` has been replaced with `privateAttributes`. Private attributes now allow using attribute references, which allow for marking nodes in nested JSON private. 
+
+### Removed:
+- Alias events are no longer supported and the `alias` method has been removed from `LDClient`.
+- Support for the `secondary` attribute has been removed from `LDUser`.  If a secondary attribute is included in a context, then it is a normal attribute that can be used in rule evaluation, but it will not affect bucketing.
+- `allowFrequentDuplicateEvents` has been removed from `LDOptions`. This had been deprecated in a previous version. The default behavior is as if this option had been set to true.
+- `autoAliasingOptOut` has been removed from `LDOptions`. This functionality has been superseded by multi-context support.
+- `inlineUsersInEvents` has been removed from `LDOptions`. Changes associated with contexts has removed the needed for this option.
+
+### Deprecated:
+- The `LDUser`  object has been deprecated. Support for `LDUser` is maintained to simplify the upgrade process, but it is recommended to use `LDContext` in the shape of either `LDSingleKindContext` or `LDMultiKindContext`.
+
 ## [4.3.2] - 2022-10-20
 ### Added:
 - Implemented `jitter` and `backoff` for streaming connections. When a connection fails the retry will start at the `streamReconnectDelay` and will double on each unsuccessful consecutive connection attempt (`backoff`) to a max of 30 seconds. The delay will be adjusted from 50%-100% of the calculated delay to prevent many clients from attempting to reconnect at the same time (`jitter`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "launchdarkly-js-sdk-common",
-  "version": "5.0.0-alpha.7",
+  "version": "5.0.1",
   "description": "LaunchDarkly SDK for JavaScript - common code",
   "author": "LaunchDarkly <team@launchdarkly.com>",
   "license": "Apache-2.0",

package/src/InspectorManager.js

@@ -57,12 +57,12 @@ function InspectorManager(inspectors, logger) {
    *
    * @param {string} flagKey The key for the flag.
    * @param {Object} detail The LDEvaluationDetail for the flag.
-   * @param {Object} user The LDUser for the flag.
+   * @param {Object} context The LDContext for the flag.
    */
-  manager.onFlagUsed = (flagKey, detail, user) => {
+  manager.onFlagUsed = (flagKey, detail, context) => {
     if (inspectorsByType[InspectorTypes.flagUsed].length) {
       onNextTick(() => {
-        inspectorsByType[InspectorTypes.flagUsed].forEach(inspector => inspector.method(flagKey, detail, user));
+        inspectorsByType[InspectorTypes.flagUsed].forEach(inspector => inspector.method(flagKey, detail, context));
       });
     }
   };
@@ -99,16 +99,16 @@ function InspectorManager(inspectors, logger) {
   };
 
   /**
-   * Notify the registered inspectors that the user identity has changed.
+   * Notify the registered inspectors that the context identity has changed.
    *
    * The notification itself will be dispatched asynchronously.
    *
-   * @param {Object} user The `LDUser` which is now identified.
+   * @param {Object} context The `LDContext` which is now identified.
    */
-  manager.onIdentityChanged = user => {
+  manager.onIdentityChanged = context => {
     if (inspectorsByType[InspectorTypes.clientIdentityChanged].length) {
       onNextTick(() => {
-        inspectorsByType[InspectorTypes.clientIdentityChanged].forEach(inspector => inspector.method(user));
+        inspectorsByType[InspectorTypes.clientIdentityChanged].forEach(inspector => inspector.method(context));
       });
     }
   };

package/src/__tests__/InspectorManager-test.js

@@ -39,16 +39,16 @@ describe('given an inspector with callbacks of every type', () => {
       {
         type: 'flag-used',
         name: 'my-flag-used-inspector',
-        method: (flagKey, flagDetail, user) => {
-          eventQueue.add({ type: 'flag-used', flagKey, flagDetail, user });
+        method: (flagKey, flagDetail, context) => {
+          eventQueue.add({ type: 'flag-used', flagKey, flagDetail, context });
         },
       },
       // 'flag-used registered twice.
       {
         type: 'flag-used',
         name: 'my-other-flag-used-inspector',
-        method: (flagKey, flagDetail, user) => {
-          eventQueue.add({ type: 'flag-used', flagKey, flagDetail, user });
+        method: (flagKey, flagDetail, context) => {
+          eventQueue.add({ type: 'flag-used', flagKey, flagDetail, context });
         },
       },
       {
@@ -75,10 +75,10 @@ describe('given an inspector with callbacks of every type', () => {
       {
         type: 'client-identity-changed',
         name: 'my-identity-inspector',
-        method: user => {
+        method: context => {
           eventQueue.add({
             type: 'client-identity-changed',
-            user,
+            context,
           });
         },
       },
@@ -137,7 +137,7 @@ describe('given an inspector with callbacks of every type', () => {
           kind: 'OFF',
         },
       },
-      user: { key: 'test-key' },
+      context: { key: 'test-key' },
     };
     const event1 = await eventQueue.take();
     expect(event1).toMatchObject(expectedEvent);
@@ -180,7 +180,7 @@ describe('given an inspector with callbacks of every type', () => {
     const event = await eventQueue.take();
     expect(event).toMatchObject({
       type: 'client-identity-changed',
-      user: { key: 'the-key' },
+      context: { key: 'the-key' },
     });
   });
 });

package/src/__tests__/LDClient-inspectors-test.js

@@ -3,7 +3,7 @@ const { respondJson } = require('./mockHttp');
 const stubPlatform = require('./stubPlatform');
 
 const envName = 'UNKNOWN_ENVIRONMENT_ID';
-const user = { key: 'user' };
+const context = { key: 'context-key' };
 
 describe('given a streaming client with registered inspectors', () => {
   const eventQueue = new AsyncQueue();
@@ -11,15 +11,15 @@ describe('given a streaming client with registered inspectors', () => {
   const inspectors = [
     {
       type: 'flag-used',
-      method: (flagKey, flagDetail, user) => {
-        eventQueue.add({ type: 'flag-used', flagKey, flagDetail, user });
+      method: (flagKey, flagDetail, context) => {
+        eventQueue.add({ type: 'flag-used', flagKey, flagDetail, context });
       },
     },
     // 'flag-used registered twice.
     {
       type: 'flag-used',
-      method: (flagKey, flagDetail, user) => {
-        eventQueue.add({ type: 'flag-used', flagKey, flagDetail, user });
+      method: (flagKey, flagDetail, context) => {
+        eventQueue.add({ type: 'flag-used', flagKey, flagDetail, context });
       },
     },
     {
@@ -43,10 +43,10 @@ describe('given a streaming client with registered inspectors', () => {
     },
     {
       type: 'client-identity-changed',
-      method: user => {
+      method: context => {
         eventQueue.add({
           type: 'client-identity-changed',
-          user,
+          context,
         });
       },
     },
@@ -60,7 +60,7 @@ describe('given a streaming client with registered inspectors', () => {
     const server = platform.testing.http.newServer();
     server.byDefault(respondJson({}));
     const config = { streaming: true, baseUrl: server.url, inspectors, sendEvents: false };
-    client = platform.testing.makeClient(envName, user, config);
+    client = platform.testing.makeClient(envName, context, config);
     await client.waitUntilReady();
   });
 
@@ -81,7 +81,7 @@ describe('given a streaming client with registered inspectors', () => {
     const ident = await eventQueue.take();
     expect(ident).toMatchObject({
       type: 'client-identity-changed',
-      user,
+      context,
     });
     const flagsEvent = await eventQueue.take();
     expect(flagsEvent).toMatchObject({

package/src/__tests__/PersistentFlagStore-test.js

@@ -7,10 +7,10 @@ import PersistentStorage from '../PersistentStorage';
 import * as utils from '../utils';
 
 describe('PersistentFlagStore', () => {
-  const user = { key: 'user' };
-  const ident = Identity(user);
+  const context = { key: 'context-key', kind: 'user' };
+  const ident = Identity(context);
   const env = 'ENVIRONMENT';
-  const lsKey = 'ld:' + env + ':' + utils.btoa(JSON.stringify(user));
+  const lsKey = 'ld:' + env + ':' + utils.btoa(JSON.stringify(context));
 
   it('stores flags', async () => {
     const platform = stubPlatform.defaults();
@@ -73,7 +73,7 @@ describe('PersistentFlagStore', () => {
     expect(platform.testing.getLocalStorageImmediately(lsKey)).toBe(undefined);
   });
 
-  it('uses hash, if present, instead of user properties', async () => {
+  it('uses hash, if present, instead of context properties', async () => {
     const platform = stubPlatform.defaults();
     const storage = PersistentStorage(platform.localStorage, platform.testing.logger);
     const hash = '12345';

package/src/__tests__/stubPlatform.js

@@ -83,14 +83,14 @@ export function defaults() {
 
       eventSourcesCreated,
 
-      makeClient: (env, user, options = {}) => {
+      makeClient: (env, context, options = {}) => {
         const config = { logger: p.testing.logger, ...options };
         // We want to simulate what the platform-specific SDKs will do in their own initialization functions.
         // They will call the common package's LDClient.initialize() and receive the clientVars object which
         // contains both the underlying client (in its "client" property) and some internal methods that the
         // platform-specific SDKs can use to do internal stuff. One of those is start(), which they will
         // call after doing any other initialization things they may need to do.
-        const clientVars = LDClient.initialize(env, user, config, p);
+        const clientVars = LDClient.initialize(env, context, config, p);
         clientVars.start();
         return clientVars.client;
       },

package/src/__tests__/utils-test.js

@@ -66,8 +66,8 @@ describe('utils', () => {
 
   describe('chunkEventsForUrl', () => {
     it('should properly chunk the list of events', () => {
-      const user = { key: 'foo' };
-      const event = { kind: 'identify', key: user.key };
+      const context = { key: 'foo', kind: 'user' };
+      const event = { kind: 'identify', key: context.key };
       const eventLength = base64URLEncode(JSON.stringify(event)).length;
       const events = [event, event, event, event, event];
       const chunks = chunkEventsForUrl(eventLength * 2, events);

package/src/diagnosticEvents.js

@@ -1,6 +1,6 @@
 const { v1: uuidv1 } = require('uuid');
 // Note that in the diagnostic events spec, these IDs are to be generated with UUID v4. However,
-// in JS we were already using v1 for unique user keys, so to avoid bringing in two packages we
+// in JS we were already using v1 for unique context keys, so to avoid bringing in two packages we
 // will use v1 here as well.
 
 const { baseOptionDefs } = require('./configuration');

package/src/index.js

@@ -189,8 +189,8 @@ function initialize(env, context, specifiedOptions, platform, extraOptionDefs) {
     }
   }
 
-  function onIdentifyChange(user) {
-    sendIdentifyEvent(user);
+  function onIdentifyChange(context) {
+    sendIdentifyEvent(context);
     notifyInspectionIdentityChanged();
   }
 

package/typings.d.ts

@@ -327,8 +327,7 @@ declare module 'launchdarkly-js-sdk-common' {
      * 
      * This is a metadata property, rather than an attribute that can be addressed in evaluations:
      * that is, a rule clause that references the attribute name "privateAttributes", will not use
-     * this value, but instead will use whatever value (if any) you have set for that name with a
-     * method such as SetString.
+     * this value, but would use a "privateAttributes" attribute set on the context.
      */
     privateAttributes?: string[];
   }
@@ -338,7 +337,7 @@ declare module 'launchdarkly-js-sdk-common' {
    * parts that compose a multi context. For more information see {@link LDSingleKindContext} and
    * {@link LDMultiKindContext}.
    */
-  interface LDContextCommon {
+  export interface LDContextCommon {
     /**
      * If true, the context will _not_ appear on the Contexts page in the LaunchDarkly dashboard.
      */
@@ -387,7 +386,7 @@ declare module 'launchdarkly-js-sdk-common' {
    * The above context would be a single kind context representing an organization. It has a key
    * for that organization, and a single attribute 'someAttribute'.
    */
-  interface LDSingleKindContext extends LDContextCommon {
+  export interface LDSingleKindContext extends LDContextCommon {
     /**
      * The kind of the context.
      */
@@ -425,7 +424,7 @@ declare module 'launchdarkly-js-sdk-common' {
    * The above multi-context contains both an 'org' and a 'user'. Each with their own key,
    * attributes, and _meta attributes.
    */
-  interface LDMultiKindContext {
+  export interface LDMultiKindContext {
     /**
      * The kind of the context.
      */
@@ -556,7 +555,7 @@ declare module 'launchdarkly-js-sdk-common' {
    * Describes the reason that a flag evaluation produced a particular value. This is
    * part of the {@link LDEvaluationDetail} object returned by {@link LDClient.variationDetail]].
    */
-  interface LDEvaluationReason {
+  export interface LDEvaluationReason {
     /**
      * The general category of the reason:
      *
@@ -997,7 +996,7 @@ declare module 'launchdarkly-js-sdk-common' {
    * This interface should not be used by the application to access flags for the purpose of controlling application
    * flow. It is intended for monitoring, analytics, or debugging purposes.
    */
-  interface LDInspectionFlagUsedHandler {
+  export interface LDInspectionFlagUsedHandler {
     type: 'flag-used',
 
     /**
@@ -1024,7 +1023,7 @@ declare module 'launchdarkly-js-sdk-common' {
    * This interface should not be used by the application to access flags for the purpose of controlling application
    * flow. It is intended for monitoring, analytics, or debugging purposes.
    */
-  interface LDInspectionFlagDetailsChangedHandler {
+  export interface LDInspectionFlagDetailsChangedHandler {
     type: 'flag-details-changed',
 
     /**
@@ -1050,7 +1049,7 @@ declare module 'launchdarkly-js-sdk-common' {
    * This interface should not be used by the application to access flags for the purpose of controlling application
    * flow. It is intended for monitoring, analytics, or debugging purposes.
    */
-  interface LDInspectionFlagDetailChangedHandler {
+  export interface LDInspectionFlagDetailChangedHandler {
     type: 'flag-detail-changed',
 
     /**
@@ -1073,7 +1072,7 @@ declare module 'launchdarkly-js-sdk-common' {
    * This interface should not be used by the application to access flags for the purpose of controlling application
    * flow. It is intended for monitoring, analytics, or debugging purposes.
    */
-  interface LDInspectionIdentifyHandler {
+  export interface LDInspectionIdentifyHandler {
     type: 'client-identity-changed',
 
     /**
@@ -1087,6 +1086,6 @@ declare module 'launchdarkly-js-sdk-common' {
     method: (context: LDContext) => void;
   }
 
-  type LDInspection = LDInspectionFlagUsedHandler | LDInspectionFlagDetailsChangedHandler
+  export type LDInspection = LDInspectionFlagUsedHandler | LDInspectionFlagDetailsChangedHandler
     | LDInspectionFlagDetailChangedHandler | LDInspectionIdentifyHandler;
 }