feat: Implement common client side support for auto environment attributes. (#356)

This is a follow up to #355. This PR implements client-sdk support for
auto env. In addition, the mocks internal api have been updated to work
better with crypto and mock resets. Server sdks are impacted by the
mocks api changes so these are fixed in this PR as well.

### Note
#357 Fixes react-native build and tests.
#358 adds application name and versionName to LDOptions.

Author: yusinto

packages/shared/common/jest.config.js

@@ -4,4 +4,5 @@ module.exports = {
   testEnvironment: 'node',
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
   collectCoverageFrom: ['src/**/*.ts'],
+  setupFilesAfterEnv: ['@launchdarkly/private-js-mocks/setup'],
 };

packages/shared/common/package.json

@@ -24,7 +24,9 @@
     "build": "npx tsc",
     "clean": "npx tsc --build --clean",
     "lint": "npx eslint . --ext .ts",
-    "lint:fix": "yarn run lint --fix"
+    "lint:fix": "yarn run lint --fix",
+    "prettier": "prettier --write 'src/*.@(js|ts|tsx|json)'",
+    "check": "yarn && yarn prettier && yarn lint && tsc && yarn test"
   },
   "license": "Apache-2.0",
   "devDependencies": {

packages/shared/common/src/api/platform/AutoEnv.ts

@@ -1,3 +1,19 @@
+/* eslint-disable import/prefer-default-export */
+/**
+ * Enable / disable Auto environment attributes. When enabled, the SDK will automatically
+ * provide data about the mobile environment where the application is running. This data makes it simpler to target
+ * your mobile customers based on application name or version, or on device characteristics including manufacturer,
+ * model, operating system, locale, and so on. We recommend enabling this when you configure the SDK. To learn more,
+ * read [Automatic environment attributes](https://docs.launchdarkly.com/sdk/features/environment-attributes).
+ * for more documentation.
+ *
+ * The default is disabled.
+ */
+export enum AutoEnvAttributes {
+  Disabled,
+  Enabled,
+}
+
 interface AutoEnvCommon {
   /**
    * Unique key for the context kind.
@@ -30,8 +46,8 @@ export interface LDDevice extends AutoEnvCommon {
     /**
      * The family of operating system.
      */
-    family: string;
-    name: string;
-    version: string;
+    family?: string;
+    name?: string;
+    version?: string;
   };
 }

packages/shared/common/src/utils/deepCompact.test.ts

@@ -0,0 +1,39 @@
+import deepCompact from './deepCompact';
+
+describe('deepCompact', () => {
+  test('if arg is undefined, return it', () => {
+    const compacted = deepCompact(undefined);
+    expect(compacted).toBeUndefined();
+  });
+
+  test('should remove all falsy, {} and ignored values', () => {
+    const data = {
+      ld_application: {
+        key: '',
+        envAttributesVersion: '1.0',
+        id: 'com.testapp.ld',
+        name: 'LDApplication.TestApp',
+        version: '1.1.1',
+      },
+      ld_device: {
+        key: '',
+        envAttributesVersion: '1.0',
+        os: {},
+        manufacturer: 'coconut',
+        model: null,
+        storageBytes: undefined,
+      },
+    };
+    const compacted = deepCompact(data, ['key', 'envAttributesVersion']);
+    expect(compacted).toEqual({
+      ld_application: {
+        id: 'com.testapp.ld',
+        name: 'LDApplication.TestApp',
+        version: '1.1.1',
+      },
+      ld_device: {
+        manufacturer: 'coconut',
+      },
+    });
+  });
+});

packages/shared/common/src/utils/deepCompact.ts

@@ -0,0 +1,24 @@
+import isEmptyObject from './isEmptyObject';
+
+/**
+ * Strips all falsy and empty {} from a given object. Returns a new object with only truthy values.
+ * Sourced from below but modified to include checks for empty object and ignoring keys.
+ * https://www.w3resource.com/javascript-exercises/javascript-array-exercise-47.php
+ *
+ * @param obj
+ * @param ignoreKeys
+ */
+const deepCompact = <T extends Object>(obj?: T, ignoreKeys?: string[]) => {
+  if (!obj) {
+    return obj;
+  }
+
+  return Object.entries(obj).reduce((acc: any, [key, value]) => {
+    if (Boolean(value) && !isEmptyObject(value) && !ignoreKeys?.includes(key)) {
+      acc[key] = typeof value === 'object' ? deepCompact(value, ignoreKeys) : value;
+    }
+    return acc;
+  }, {}) as T;
+};
+
+export default deepCompact;

packages/shared/common/src/utils/index.ts

@@ -1,5 +1,6 @@
 import clone from './clone';
 import { secondsToMillis } from './date';
+import deepCompact from './deepCompact';
 import fastDeepEqual from './fast-deep-equal';
 import { base64UrlEncode, defaultHeaders, httpErrorMessage, LDHeaders, shouldRetry } from './http';
 import noop from './noop';
@@ -9,6 +10,7 @@ import { VoidFunction } from './VoidFunction';
 export {
   base64UrlEncode,
   clone,
+  deepCompact,
   defaultHeaders,
   fastDeepEqual,
   httpErrorMessage,

packages/shared/common/src/utils/isEmptyObject.ts

@@ -0,0 +1,3 @@
+const isEmptyObject = (obj: any) => JSON.stringify(obj) === '{}';
+
+export default isEmptyObject;

packages/shared/mocks/README.md

@@ -2,9 +2,111 @@
 
 [![Actions Status][mocks-ci-badge]][mocks-ci]
 
-**Internal use only.**
+> [!CAUTION]
+> Internal use only.
+> This project contains JavaScript mocks that are consumed in unit tests in client-side and server-side JavaScript SDKs.
 
-This project contains JavaScript mocks that are consumed in unit tests in client-side and server-side JavaScript SDKs.
+## Installation
+
+This package is not published publicly. To use it internally, add the following line to your project's package.json
+devDependencies. yarn workspace has been setup to recognize this package so this dependency should automatically work:
+
+```bash
+  "devDependencies": {
+    "@launchdarkly/private-js-mocks": "0.0.1",
+    ...
+```
+
+Then in your jest config add `@launchdarkly/private-js-mocks/setup` to setupFilesAfterEnv:
+
+```js
+// jest.config.js or jest.config.json
+module.exports = {
+  setupFilesAfterEnv: ['@launchdarkly/private-js-mocks/setup'],
+  ...
+}
+```
+
+## Usage
+
+> [!IMPORTANT]  
+> basicPlatform and clientContext must be used inside a test because it's setup before each test.
+
+- `basicPlatform`: a concrete but basic implementation of [Platform](https://github.com/launchdarkly/js-core/blob/main/packages/shared/common/src/api/platform/Platform.ts). This is setup beforeEach so it must be used inside a test.
+
+- `clientContext`: ClientContext object including `basicPlatform` above. This is setup beforeEach so it must be used inside a test as well.
+
+- `hasher`: a Hasher object returned by `Crypto.createHash`. All functions in this object are jest mocks. This is exported
+  separately as a top level export because `Crypto` does not expose this publicly and we want to respect that.
+
+## Example
+
+```tsx
+import { basicPlatform, clientContext, hasher } from '@launchdarkly/private-js-mocks';
+
+// DOES NOT WORK: crypto is undefined because basicPlatform must be inside a test
+// because it's setup by the package in beforeEach.
+const { crypto } = basicPlatform; // DON'T DO THIS HERE
+
+// DOES NOT WORK: clientContext must be used inside a test. Otherwise all properties
+// of it will be undefined.
+const {
+  basicConfiguration: { serviceEndpoints, tags },
+  platform: { info },
+} = clientContext; // DON'T DO THIS HERE
+
+describe('button', () => {
+  // DOES NOT WORK: again must be inside an actual test. At the test suite,
+  // level, beforeEach has not been run.
+  const { crypto } = basicPlatform; // DON'T DO THIS HERE
+
+  // DO THIS
+  let crypto: Crypto;
+  let info: Info;
+  let serviceEndpoints: ServiceEndpoints;
+  let tags: ApplicationTags;
+
+  beforeEach(() => {
+    // WORKS: basicPlatform and clientContext have been setup by the package.
+    ({ crypto, info } = basicPlatform);
+
+    // WORKS
+    ({
+      basicConfiguration: { serviceEndpoints, tags },
+      platform: { info },
+    } = clientContext);
+  });
+
+  afterEach(() => {
+    jest.resetAllMocks();
+  });
+
+  it('hashes the correct string', () => {
+    // arrange
+    const bucketer = new Bucketer(crypto);
+
+    // act
+    const [bucket, hadContext] = bucketer.bucket();
+
+    // assert
+    // WORKS
+    expect(crypto.createHash).toHaveBeenCalled();
+
+    // WORKS: alternatively you can just use the full path to access the properties
+    // of basicPlatform
+    expect(basicPlatform.crypto.createHash).toHaveBeenCalled();
+
+    // GOTCHA: hasher is a separte import from crypto to respect
+    // the public Crypto interface.
+    expect(hasher.update).toHaveBeenCalledWith(expected);
+    expect(hasher.digest).toHaveBeenCalledWith('hex');
+  });
+});
+```
+
+## Developing this package
+
+If you make changes to this package, you'll need to run `yarn build` in the `mocks` directory for changes to take effect.
 
 ## Contributing
 

packages/shared/mocks/package.json

@@ -5,6 +5,12 @@
   "type": "commonjs",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "exports": {
+    ".": "./dist/index.js",
+    "./setup": {
+      "default": "./dist/setupMocks.js"
+    }
+  },
   "homepage": "https://github.com/launchdarkly/js-core/tree/main/packages/shared/common",
   "repository": {
     "type": "git",

packages/shared/mocks/src/clientContext.ts

@@ -1,20 +1,22 @@
 import type { ClientContext } from '@common';
 
-import basicPlatform from './platform';
+import { basicPlatform } from './platform';
 
-const clientContext: ClientContext = {
-  basicConfiguration: {
-    sdkKey: 'testSdkKey',
-    serviceEndpoints: {
-      events: '',
-      polling: '',
-      streaming: 'https://mockstream.ld.com',
-      diagnosticEventPath: '/diagnostic',
-      analyticsEventPath: '/bulk',
-      includeAuthorizationHeader: true,
+// eslint-disable-next-line import/no-mutable-exports
+export let clientContext: ClientContext;
+export const setupClientContext = () => {
+  clientContext = {
+    basicConfiguration: {
+      sdkKey: 'testSdkKey',
+      serviceEndpoints: {
+        events: '',
+        polling: '',
+        streaming: 'https://mockstream.ld.com',
+        diagnosticEventPath: '/diagnostic',
+        analyticsEventPath: '/bulk',
+        includeAuthorizationHeader: true,
+      },
     },
-  },
-  platform: basicPlatform,
+    platform: basicPlatform,
+  };
 };
-
-export default clientContext;