feat: refactors the implementation of context caching. You can now s… (#531)

…pecify the maxCachedContexts (default 5) in the LDOptions for
client-side SDKs.

**Requirements**

- [x] I have added test coverage for new or changed functionality


- [x] I have followed the repository's [pull request submission
guidelines](../blob/main/CONTRIBUTING.md#submitting-pull-requests)

- [x] I have validated my changes against all supported platform
versions

TODOs:
- [x] FlagManager and FlagPersistence tests
- [x] need to do some validation on platforms and manual examination of
storage
- [x] implement data migration instructions in FlagPersistence.ts
- [x] need to validate migration of existing data
- [x] [update various namespace concat usages to use static helper
funcs](https://github.com/launchdarkly/js-core/pull/531/files#diff-2ea53243d0cda26506ba1e932279540f87359ef3647357de41dd6961553b3908R6)
- [x] [discuss immutability of return
values](https://github.com/launchdarkly/js-core/pull/531/files#diff-d292bcc848729d6a937835ad9b3aefb2217a4ab9057a1b9caa22eb32b6412cbdR22)
- [x] [add tests for namespace hashing and utf8
encoding](https://github.com/launchdarkly/js-core/pull/531/files#diff-2ea53243d0cda26506ba1e932279540f87359ef3647357de41dd6961553b3908R23)
- [x] [verify deleteFlag
handling](https://github.com/launchdarkly/js-core/pull/531/files#diff-5ab8d43c9c238bf0ca76fae92d46229147658df4640f421264a1f57eebfdde79R215)

**Related issues**

SC-247373

**Describe the solution you've provided**

Introduces FlagManager, FlagUpdater, FlagPersistence, and flag
CacheIndex for creating a LRU for cached flag evaluations. This follows
the implementations of other client SDKs.

Author: tanderson-ld

packages/shared/common/__tests__/Context.test.ts

@@ -177,3 +177,151 @@ describe('given a multi-kind context', () => {
     expect(context?.kindsAndKeys).toEqual({ org: 'OrgKey', user: 'User%:/Key' });
   });
 });
+
+describe('given a user context with private attributes', () => {
+  const input = Context.fromLDContext({
+    key: 'testKey',
+    name: 'testName',
+    custom: { cat: 'calico', dog: 'lab' },
+    anonymous: true,
+    privateAttributeNames: ['/a/b/c', 'cat', 'custom/dog'],
+  });
+
+  const expected = {
+    key: 'testKey',
+    kind: 'user',
+    name: 'testName',
+    cat: 'calico',
+    dog: 'lab',
+    anonymous: true,
+    _meta: {
+      privateAttributes: ['/a/b/c', 'cat', 'custom/dog'],
+    },
+  };
+
+  it('it can convert from LDContext to Context and back to LDContext', () => {
+    expect(Context.toLDContext(input)).toEqual(expected);
+  });
+});
+
+describe('given a user context without private attributes', () => {
+  const input = Context.fromLDContext({
+    key: 'testKey',
+    name: 'testName',
+    custom: { cat: 'calico', dog: 'lab' },
+    anonymous: true,
+  });
+
+  const expected = {
+    key: 'testKey',
+    kind: 'user',
+    name: 'testName',
+    cat: 'calico',
+    dog: 'lab',
+    anonymous: true,
+  };
+
+  it('it can convert from LDContext to Context and back to LDContext', () => {
+    expect(Context.toLDContext(input)).toEqual(expected);
+  });
+});
+
+describe('given a single context with private attributes', () => {
+  const input = Context.fromLDContext({
+    kind: 'org',
+    key: 'testKey',
+    name: 'testName',
+    cat: 'calico',
+    dog: 'lab',
+    anonymous: true,
+    _meta: {
+      privateAttributes: ['/a/b/c', 'cat', 'dog'],
+    },
+  });
+
+  const expected = {
+    kind: 'org',
+    key: 'testKey',
+    name: 'testName',
+    cat: 'calico',
+    dog: 'lab',
+    anonymous: true,
+    _meta: {
+      privateAttributes: ['/a/b/c', 'cat', 'dog'],
+    },
+  };
+
+  it('it can convert from LDContext to Context and back to LDContext', () => {
+    expect(Context.toLDContext(input)).toEqual(expected);
+  });
+});
+
+describe('given a single context without meta', () => {
+  const input = Context.fromLDContext({
+    kind: 'org',
+    key: 'testKey',
+    name: 'testName',
+    cat: 'calico',
+    dog: 'lab',
+    anonymous: true,
+  });
+
+  const expected = {
+    kind: 'org',
+    key: 'testKey',
+    name: 'testName',
+    cat: 'calico',
+    dog: 'lab',
+    anonymous: true,
+  };
+
+  it('it can convert from LDContext to Context and back to LDContext', () => {
+    expect(Context.toLDContext(input)).toEqual(expected);
+  });
+});
+
+describe('given a multi context', () => {
+  const input = Context.fromLDContext({
+    kind: 'multi',
+    org: {
+      key: 'testKey',
+      name: 'testName',
+      cat: 'calico',
+      dog: 'lab',
+      anonymous: true,
+      _meta: {
+        privateAttributes: ['/a/b/c', 'cat', 'custom/dog'],
+      },
+    },
+    customer: {
+      key: 'testKey',
+      name: 'testName',
+      bird: 'party parrot',
+      chicken: 'hen',
+    },
+  });
+
+  const expected = {
+    kind: 'multi',
+    org: {
+      key: 'testKey',
+      name: 'testName',
+      cat: 'calico',
+      dog: 'lab',
+      anonymous: true,
+      _meta: {
+        privateAttributes: ['/a/b/c', 'cat', 'custom/dog'],
+      },
+    },
+    customer: {
+      key: 'testKey',
+      name: 'testName',
+      bird: 'party parrot',
+      chicken: 'hen',
+    },
+  };
+
+  it('it can convert from LDContext to Context and back to LDContext', () => {
+    expect(Context.toLDContext(input)).toEqual(expected);
+  });
+});

packages/shared/common/src/Context.ts

@@ -140,6 +140,11 @@ function legacyToSingleKind(user: LDUser): LDSingleKindContext {
   if (user.country !== null && user.country !== undefined) {
     singleKindContext.country = user.country;
   }
+  if (user.privateAttributeNames !== null && user.privateAttributeNames !== undefined) {
+    singleKindContext._meta = {
+      privateAttributes: user.privateAttributeNames,
+    };
+  }
 
   // We are not pulling private attributes over because we will serialize
   // those from attribute references for events.
@@ -338,6 +343,31 @@ export default class Context {
     return Context.contextForError('unknown', 'Context was not of a valid kind');
   }
 
+  /**
+   * Creates a {@link LDContext} from a {@link Context}.
+   * @param context to be converted
+   * @returns an {@link LDContext} if input was valid, otherwise undefined
+   */
+  public static toLDContext(context: Context): LDContext | undefined {
+    if (!context.valid) {
+      return undefined;
+    }
+
+    const contexts = context.getContexts();
+    if (!context.isMulti) {
+      return contexts[0][1];
+    }
+    const result: LDMultiKindContext = {
+      kind: 'multi',
+    };
+    contexts.forEach((kindAndContext) => {
+      const kind = kindAndContext[0];
+      const nestedContext = kindAndContext[1];
+      result[kind] = nestedContext;
+    });
+    return result;
+  }
+
   /**
    * Attempt to get a value for the given context kind using the given reference.
    * @param reference The reference to the value to get.

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

@@ -1,3 +1,25 @@
+/**
+ * Interface for a data store that holds feature flag data and other SDK
+ * properties in a serialized form.
+ *
+ * This interface should be used for platform-specific integrations that store
+ * data somewhere other than in memory. Each data item is uniquely identified by
+ * a string typically constructed following a namespacing structure that
+ * is then encoded.
+ *
+ * Implementations may not throw exceptions.
+ *
+ * The SDK assumes that the persistence is only being used by a single instance
+ * of the SDK per SDK key (two different SDK instances, with 2 different SDK
+ * keys could use the same persistence instance).
+ *
+ * The SDK, with correct usage, will not have overlapping writes to the same
+ * key.
+ *
+ * This interface does not depend on the ability to list the contents of the
+ * store or namespaces. This is to maintain the simplicity of implementing a
+ * key-value store on many platforms.
+ */
 export interface Storage {
   get: (key: string) => Promise<string | null>;
   set: (key: string, value: string) => Promise<void>;

packages/shared/mocks/src/crypto.ts

@@ -6,7 +6,7 @@ export let hasher: Hasher;
 export const setupCrypto = () => {
   let counter = 0;
   hasher = {
-    update: jest.fn(),
+    update: jest.fn(() => hasher),
     digest: jest.fn(() => '1234567890123456'),
   };
 

packages/shared/sdk-client/src/LDClientImpl.events.test.ts

@@ -9,7 +9,6 @@ import {
 import { InputCustomEvent, InputIdentifyEvent } from '@launchdarkly/js-sdk-common/dist/internal';
 import {
   basicPlatform,
-  hasher,
   logger,
   MockEventProcessor,
   setupMockStreamingProcessor,
@@ -59,7 +58,6 @@ describe('sdk-client object', () => {
     );
     setupMockStreamingProcessor(false, defaultPutResponse);
     basicPlatform.crypto.randomUUID.mockReturnValue('random1');
-    hasher.digest.mockReturnValue('digested1');
 
     ldc = new LDClientImpl(testSdkKey, AutoEnvAttributes.Enabled, basicPlatform, {
       logger,