feat: Add ODP/ATS VuidManager (#776)

* Add VuidManager tests and empty class file

* Move tests location, Typescript, & jest

* Initial implementation VuidManager (1 test WIP)

* Add persistence cache

* Implement cache into VuidManager

* Correct persistentKeyValueCache's types

* Update persistent cache func descriptions

* Adjust VuidManager tests

* Add React Native and browser persistence classes

* Add React Native and browser persistence classes

* Testing for ReactNativeAsyncStorageCache

* More testing for ReactNativeAsyncStorageCache

* Update to a getter instance()

* BrowserAsyncStorageCache tests

* Bug fix VuidManager and tests

* Add @react-native-async-storage/async-storage

* Update packages/optimizely-sdk/lib/plugins/vuid_manager/index.ts

Co-authored-by: Jae Kim <45045038+jaeopt@users.noreply.github.com>

* Add test around and correct load()

* Delete inMemoryAsyncStorageCache

* Add dev packages react-native-async-storage & jest-ts-auto-mock

* Refactor to use async/await + simplifying returns

* Change to ts-mockito for stubs/mocks

* Add _reset() for testing

* Refactor VUID Manager tests using ts-mockito

* Un-nest vuid stored in cache

* Add JSDoc

* Corrections to accessibility and interface

* Corrections to tests

* Update to package-lock

* Fix to AsyncStorageCache types and tests

Co-authored-by: Jae Kim <45045038+jaeopt@users.noreply.github.com>

Author: mikechu-optimizely

packages/optimizely-sdk/lib/plugins/key_value_cache/browserAsyncStorageCache.ts

@@ -0,0 +1,40 @@
+/**
+ * Copyright 2022, Optimizely
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import PersistentKeyValueCache from './persistentKeyValueCache';
+
+export default class BrowserAsyncStorageCache implements PersistentKeyValueCache {
+  async contains(key: string): Promise<boolean> {
+    return localStorage.getItem(key) !== null;
+  }
+
+  async get(key: string): Promise<string | null> {
+    return localStorage.getItem(key);
+  }
+
+  async remove(key: string): Promise<boolean> {
+    if (await this.contains(key)) {
+        localStorage.removeItem(key);
+        return true;
+      } else {
+        return false;
+      }
+  }
+
+  async set(key: string, val: string): Promise<void> {
+    return localStorage.setItem(key, val);
+  }
+}

packages/optimizely-sdk/lib/plugins/key_value_cache/persistentKeyValueCache.ts

@@ -0,0 +1,64 @@
+/**
+ * Copyright 2022, Optimizely
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * An Interface to implement a persistent key value cache which supports strings as keys and value objects.
+ */
+export default interface PersistentKeyValueCache {
+  /**
+   * Checks if a key exists in the cache
+   * @param key
+   * Resolves promise with
+   * 1. true if the key exists
+   * 2. false if the key does not exist
+   * Rejects the promise in case of an error
+   */
+  contains(key: string): Promise<boolean>;
+
+  /**
+   * Returns value stored against a key or undefined if not found.
+   * @param key
+   * @returns
+   * Resolves promise with
+   * 1. object as value if found.
+   * 2. undefined if the key does not exist in the cache.
+   * Rejects the promise in case of an error
+   */
+  // eslint-disable-next-line  @typescript-eslint/no-explicit-any
+  get(key: string): Promise<any>;
+
+  /**
+   * Removes the key value pair from cache.
+   * @param key   *
+   * @returns
+   * Resolves promise with
+   * 1. true if key-value was removed or
+   * 2. false if key not found
+   * Rejects the promise in case of an error
+   */
+  remove(key: string): Promise<boolean>;
+
+  /**
+   * Stores any object in the persistent cache against a key
+   * @param key
+   * @param val
+   * @returns
+   * Resolves promise without a value if successful
+   * Rejects the promise in case of an error
+   */
+  // eslint-disable-next-line  @typescript-eslint/no-explicit-any
+  set(key: string, val: any): Promise<void>;
+}

packages/optimizely-sdk/lib/plugins/key_value_cache/reactNativeAsyncStorageCache.ts

@@ -0,0 +1,40 @@
+/**
+ * Copyright 2020, 2022, Optimizely
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import PersistentKeyValueCache from './persistentKeyValueCache';
+
+export default class ReactNativeAsyncStorageCache implements PersistentKeyValueCache {
+  async contains(key: string): Promise<boolean> {
+    return await AsyncStorage.getItem(key) !== null;
+  }
+
+  async get(key: string): Promise<string | null> {
+    return await AsyncStorage.getItem(key);
+  }
+
+  async remove(key: string): Promise<boolean> {
+    if (await this.contains(key)) {
+      await AsyncStorage.removeItem(key);
+      return true;
+    }
+    return false;
+  }
+
+  set(key: string, val: string): Promise<void> {
+    return AsyncStorage.setItem(key, val);
+  }
+}

packages/optimizely-sdk/lib/plugins/vuid_manager/index.ts

@@ -0,0 +1,136 @@
+/**
+ * Copyright 2022, Optimizely
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { uuid } from '../../utils/fns';
+import PersistentKeyValueCache from '../key_value_cache/persistentKeyValueCache';
+
+export interface IVuidManager {
+  readonly vuid: string;
+}
+
+/**
+ * Manager for creating, persisting, and retrieving a Visitor Unique Identifier
+ */
+export class VuidManager implements IVuidManager {
+  /**
+   * Unique key used within the persistent value cache against which to
+   * store the VUID
+   * @private
+   */
+  private _keyForVuid = 'optimizely-vuid';
+
+  /**
+   * Prefix used as part of the VUID format
+   * @private
+   */
+  private readonly _prefix: string = `vuid_`;
+
+  /**
+   * Current VUID value being used
+   * @private
+   */
+  private _vuid: string;
+
+  /**
+   * Get the current VUID value being used
+   */
+  public get vuid(): string {
+    return this._vuid;
+  }
+
+  private constructor() {
+    this._vuid = '';
+  }
+
+  /**
+   * Instance of the VUID Manager
+   * @private
+   */
+  private static _instance: VuidManager;
+
+  /**
+   * Gets the current instance of the VUID Manager, initializing if needed
+   * @param cache Caching mechanism to use for persisting the VUID outside working memory   *
+   * @returns An instance of VuidManager
+   */
+  public static async instance(cache: PersistentKeyValueCache): Promise<VuidManager> {
+    if (!this._instance) {
+      this._instance = new VuidManager();
+    }
+
+    if (!this._instance._vuid) {
+      await this._instance.load(cache);
+    }
+
+    return this._instance;
+  }
+
+  /**
+   * Attempts to load a VUID from persistent cache or generates a new VUID
+   * @param cache Caching mechanism to use for persisting the VUID outside working memory
+   * @returns Current VUID stored in the VuidManager
+   */
+  private async load(cache: PersistentKeyValueCache): Promise<string> {
+    const cachedValue = await cache.get(this._keyForVuid);
+    if (cachedValue && this.isVuid(cachedValue)) {
+      this._vuid = cachedValue;
+    } else {
+      this._vuid = this.makeVuid();
+      await this.save(this._vuid, cache);
+    }
+
+    return this._vuid;
+  }
+
+  /**
+   * Creates a new VUID
+   * @returns A new visitor unique identifier
+   */
+  private makeVuid(): string {
+    const maxLength = 32;   // required by ODP server
+
+    // make sure UUIDv4 is used (not UUIDv1 or UUIDv6) since the trailing 5 chars will be truncated. See TDD for details.
+    const uuidV4 = uuid();
+    const formatted = uuidV4.replace(/-/g, '').toLowerCase();
+    const vuidFull = `${(this._prefix)}${formatted}`;
+
+    return (vuidFull.length <= maxLength) ? vuidFull : vuidFull.substring(0, maxLength);
+  }
+
+  /**
+   * Saves a VUID to a persistent cache
+   * @param vuid VUID to be stored
+   * @param cache Caching mechanism to use for persisting the VUID outside working memory
+   */
+  private async save(vuid: string, cache: PersistentKeyValueCache): Promise<void> {
+    await cache.set(this._keyForVuid, vuid);
+  }
+
+  /**
+   * Validates the format of a Visitor Unique Identifier
+   * @param vuid VistorId to check
+   * @returns *true* if the VisitorId is valid otherwise *false* for invalid
+   */
+  private isVuid = (vuid: string): boolean => vuid.startsWith(this._prefix);
+
+  /**
+   * Function used in unit testing to reset the VuidManager
+   * **Important**: This should not to be used in production code
+   */
+  private static _reset(): void {
+    this._instance._vuid = '';
+  }
+}