react-native-nitro-amplitude 0.1.0

package/src/experiment/storage/cache.ts

@@ -0,0 +1,271 @@
+import { EvaluationFlag, GetVariantsOptions } from "@amplitude/experiment-core";
+
+import { Storage } from "../types/storage";
+import { Variant } from "../types/variant";
+
+export const getVariantStorage = (
+  deploymentKey: string,
+  instanceName: string,
+  storage: Storage,
+): LoadStoreCache<Variant> => {
+  const namespace = getNamespace(deploymentKey, instanceName);
+  const legacyNamespace = getLegacyNamespace(deploymentKey, instanceName);
+  return new LoadStoreCache<Variant>(
+    namespace,
+    storage,
+    transformVariantFromStorage,
+    [legacyNamespace],
+  );
+};
+
+export const getFlagStorage = (
+  deploymentKey: string,
+  instanceName: string,
+  storage: Storage,
+): LoadStoreCache<EvaluationFlag> => {
+  const namespace = `${getNamespace(deploymentKey, instanceName)}-flags`;
+  const legacyNamespace = `${getLegacyNamespace(
+    deploymentKey,
+    instanceName,
+  )}-flags`;
+  return new LoadStoreCache<EvaluationFlag>(namespace, storage, undefined, [
+    legacyNamespace,
+  ]);
+};
+
+export const getVariantsOptionsStorage = (
+  deploymentKey: string,
+  instanceName: string,
+  storage: Storage,
+): SingleValueStoreCache<GetVariantsOptions> => {
+  const namespace = `${getNamespace(
+    deploymentKey,
+    instanceName,
+  )}-variants-options`;
+  const legacyNamespace = `${getLegacyNamespace(
+    deploymentKey,
+    instanceName,
+  )}-variants-options`;
+  return new SingleValueStoreCache<GetVariantsOptions>(namespace, storage, [
+    legacyNamespace,
+  ]);
+};
+
+const getNamespace = (deploymentKey: string, instanceName: string): string => {
+  return `amp-exp-${instanceName}-${hashString(deploymentKey)}`;
+};
+
+const getLegacyNamespace = (
+  deploymentKey: string,
+  instanceName: string,
+): string => {
+  const truncatedDeployment = deploymentKey.substring(deploymentKey.length - 6);
+  return `amp-exp-${instanceName}-${truncatedDeployment}`;
+};
+
+const hashString = (value: string): string => {
+  let hash = 2166136261;
+  for (let i = 0; i < value.length; i++) {
+    hash ^= value.charCodeAt(i);
+    hash = Math.imul(hash, 16777619);
+  }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+};
+
+export class SingleValueStoreCache<V> {
+  private readonly namespace: string;
+  private readonly legacyNamespaces: string[];
+  private readonly storage: Storage;
+  private value: V | undefined;
+
+  constructor(
+    namespace: string,
+    storage: Storage,
+    legacyNamespaces: string[] = [],
+  ) {
+    this.namespace = namespace;
+    this.legacyNamespaces = legacyNamespaces;
+    this.storage = storage;
+    this.value = this.get();
+  }
+
+  public get(): V | undefined {
+    return this.value;
+  }
+
+  public put(value: V): void {
+    this.value = value;
+  }
+
+  public async load(): Promise<void> {
+    let value = await this.storage.get(this.namespace);
+    for (const legacyNamespace of this.legacyNamespaces) {
+      if (value) {
+        break;
+      }
+      value = await this.storage.get(legacyNamespace);
+    }
+    if (value) {
+      try {
+        this.value = JSON.parse(value);
+      } catch {
+        this.value = undefined;
+      }
+    }
+  }
+
+  public async store(): Promise<void> {
+    if (this.value === undefined) {
+      // Delete the key if the value is undefined
+      await this.storage.delete(this.namespace);
+    } else {
+      // Also store false or null values
+      await this.storage.put(this.namespace, JSON.stringify(this.value));
+    }
+  }
+}
+
+export class LoadStoreCache<V> {
+  private readonly namespace: string;
+  private readonly legacyNamespaces: string[];
+  private readonly storage: Storage;
+  private readonly transformer?: (value: unknown) => V | undefined;
+  private cache: Record<string, V> = {};
+
+  constructor(
+    namespace: string,
+    storage: Storage,
+    transformer?: (value: unknown) => V | undefined,
+    legacyNamespaces: string[] = [],
+  ) {
+    this.namespace = namespace;
+    this.legacyNamespaces = legacyNamespaces;
+    this.storage = storage;
+    this.transformer = transformer;
+  }
+
+  public get(key: string): V | undefined {
+    return this.cache[key];
+  }
+
+  public getAll(): Record<string, V> {
+    return { ...this.cache };
+  }
+
+  public put(key: string, value: V): void {
+    this.cache[key] = value;
+  }
+
+  public putAll(values: Record<string, V>): void {
+    for (const key of Object.keys(values)) {
+      this.cache[key] = values[key];
+    }
+  }
+
+  public remove(key: string): void {
+    delete this.cache[key];
+  }
+
+  public clear(): void {
+    this.cache = {};
+  }
+
+  public async load(initialValues?: Record<string, V>): Promise<void> {
+    let rawValues = await this.storage.get(this.namespace);
+    for (const legacyNamespace of this.legacyNamespaces) {
+      if (rawValues) {
+        break;
+      }
+      rawValues = await this.storage.get(legacyNamespace);
+    }
+    let jsonValues: Record<string, unknown> = {};
+    if (!rawValues) {
+      this.clear();
+      if (initialValues) {
+        this.putAll(initialValues);
+      }
+      return;
+    }
+    try {
+      jsonValues = (JSON.parse(rawValues) as Record<string, unknown>) || {};
+    } catch {
+      this.clear();
+      if (initialValues) {
+        this.putAll(initialValues);
+      }
+      return;
+    }
+    const values: Record<string, V> = {};
+    for (const key of Object.keys(jsonValues)) {
+      try {
+        const value = this.transformer
+          ? this.transformer(jsonValues[key])
+          : (jsonValues[key] as V);
+        if (value !== undefined) {
+          values[key] = value;
+        }
+      } catch {
+        // Do nothing
+      }
+    }
+    this.clear();
+    if (initialValues) {
+      this.putAll(initialValues);
+    }
+    this.putAll(values);
+  }
+
+  public async store(values: Record<string, V> = this.cache): Promise<void> {
+    await this.storage.put(this.namespace, JSON.stringify(values));
+  }
+}
+
+export const transformVariantFromStorage = (
+  storageValue: unknown,
+): Variant | undefined => {
+  if (typeof storageValue === "string") {
+    // From v0 string format
+    return {
+      key: storageValue,
+      value: storageValue,
+    };
+  } else if (typeof storageValue === "object" && storageValue !== null) {
+    // From v1 or v2 object format
+    const variantRecord = storageValue as Record<string, unknown>;
+    const key = variantRecord.key;
+    const value = variantRecord.value;
+    const payload = variantRecord.payload;
+    const rawMetadata = variantRecord.metadata;
+    let metadata =
+      rawMetadata && typeof rawMetadata === "object"
+        ? ({ ...rawMetadata } as Record<string, unknown>)
+        : undefined;
+    let experimentKey =
+      typeof variantRecord.expKey === "string"
+        ? variantRecord.expKey
+        : undefined;
+    const metadataExperimentKey =
+      metadata && typeof metadata.experimentKey === "string"
+        ? metadata.experimentKey
+        : undefined;
+
+    if (metadataExperimentKey) {
+      experimentKey = metadataExperimentKey;
+    } else if (experimentKey) {
+      metadata = metadata || {};
+      metadata.experimentKey = experimentKey;
+    }
+    const variant: Variant = {};
+    if (typeof key === "string") {
+      variant.key = key;
+    } else if (typeof value === "string") {
+      variant.key = value;
+    }
+    if (typeof value === "string") variant.value = value;
+    if (metadata) variant.metadata = metadata;
+    if (payload) variant.payload = payload;
+    if (experimentKey) variant.expKey = experimentKey;
+    return variant;
+  }
+  return undefined;
+};

package/src/experiment/storage/local-storage.ts

@@ -0,0 +1,23 @@
+import { Storage } from "../types/storage";
+
+export class MemoryStorage implements Storage {
+  private static readonly memoryStorage = new Map<string, string>();
+
+  async get(key: string): Promise<string | null> {
+    return MemoryStorage.memoryStorage.get(key) ?? null;
+  }
+
+  async put(key: string, value: string): Promise<void> {
+    MemoryStorage.memoryStorage.set(key, value);
+  }
+
+  async delete(key: string): Promise<void> {
+    MemoryStorage.memoryStorage.delete(key);
+  }
+
+  async reset(): Promise<void> {
+    MemoryStorage.memoryStorage.clear();
+  }
+}
+
+export class LocalStorage extends MemoryStorage {}

package/src/experiment/stubClient.ts

@@ -0,0 +1,61 @@
+import { Client, FetchOptions } from "./types/client";
+import { Defaults } from "./types/config";
+import { ExperimentUser, ExperimentUserProvider } from "./types/user";
+import { Variant, Variants } from "./types/variant";
+
+/**
+ * A stub {@link Client} implementation that does nothing for all methods
+ */
+export class StubExperimentClient implements Client {
+  public getUser(): ExperimentUser {
+    return {};
+  }
+
+  public async start(_user?: ExperimentUser): Promise<void> {
+    return;
+  }
+
+  public stop(): void {}
+
+  public setUser(_user: ExperimentUser): void {}
+
+  public async fetch(
+    _user?: ExperimentUser,
+    _options?: FetchOptions,
+  ): Promise<StubExperimentClient> {
+    return this;
+  }
+
+  public async fetchOrThrow(
+    _user?: ExperimentUser,
+    _options?: FetchOptions,
+  ): Promise<StubExperimentClient> {
+    return this;
+  }
+
+  public getUserProvider(): ExperimentUserProvider {
+    return {
+      async getUser(): Promise<ExperimentUser> {
+        return {};
+      },
+    };
+  }
+
+  public setUserProvider(
+    _userProvider: ExperimentUserProvider,
+  ): StubExperimentClient {
+    return this;
+  }
+
+  public variant(_key: string, _fallback?: string | Variant): Variant {
+    return Defaults.fallbackVariant ?? {};
+  }
+
+  public all(): Variants {
+    return {};
+  }
+
+  public clear(): void {}
+
+  public exposure(_key: string): void {}
+}

package/src/experiment/transport/http.ts

@@ -0,0 +1,105 @@
+/**
+ * @packageDocumentation
+ * @internal
+ */
+
+import {
+  safeGlobal,
+  HttpClient as CoreHttpClient,
+  HttpRequest,
+  HttpResponse,
+} from "@amplitude/experiment-core";
+import unfetch from "unfetch";
+
+import { HttpClient, SimpleResponse } from "../types/transport";
+
+const getFetch = () => safeGlobal.fetch || unfetch;
+
+type AbortControllerLike = {
+  signal: AbortSignal;
+  abort(): void;
+};
+
+type GlobalScopeWithAbortController = typeof globalThis & {
+  AbortController?: new () => AbortControllerLike;
+};
+
+const getAbortController = (): AbortControllerLike | undefined => {
+  const scope = safeGlobal as GlobalScopeWithAbortController;
+  return typeof scope.AbortController === "function"
+    ? new scope.AbortController()
+    : undefined;
+};
+
+const timeout = (
+  promise: Promise<SimpleResponse>,
+  timeoutMillis?: number,
+  abortController?: AbortControllerLike,
+): Promise<SimpleResponse> => {
+  if (timeoutMillis == null || timeoutMillis <= 0) {
+    return promise;
+  }
+  return new Promise(function (resolve, reject) {
+    const timeoutHandle = safeGlobal.setTimeout(function () {
+      abortController?.abort();
+      reject(Error("Request timeout after " + timeoutMillis + " milliseconds"));
+    }, timeoutMillis);
+    promise.then(
+      (value) => {
+        safeGlobal.clearTimeout(timeoutHandle);
+        resolve(value);
+      },
+      (error) => {
+        safeGlobal.clearTimeout(timeoutHandle);
+        reject(error);
+      },
+    );
+  });
+};
+
+const _request = (
+  requestUrl: string,
+  method: string,
+  headers: Record<string, string>,
+  data: string,
+  timeoutMillis?: number,
+): Promise<SimpleResponse> => {
+  const abortController = getAbortController();
+  const call = async () => {
+    const response = await getFetch()(requestUrl, {
+      method: method,
+      headers: headers,
+      body: data,
+      signal: abortController?.signal,
+    });
+    const simpleResponse: SimpleResponse = {
+      status: response.status,
+      body: await response.text(),
+    };
+    return simpleResponse;
+  };
+  return timeout(call(), timeoutMillis, abortController);
+};
+
+/**
+ * Wrap the exposed HttpClient in a CoreClient implementation to work with
+ * FlagsApi and EvaluationApi.
+ */
+export class WrapperClient implements CoreHttpClient {
+  private readonly client: HttpClient;
+  constructor(client: HttpClient) {
+    this.client = client;
+  }
+
+  async request(request: HttpRequest): Promise<HttpResponse> {
+    return await this.client.request(
+      request.requestUrl,
+      request.method,
+      request.headers,
+      null,
+      request.timeoutMillis,
+    );
+  }
+}
+
+export const FetchHttpClient: HttpClient = { request: _request };

package/src/experiment/types/client.ts

@@ -0,0 +1,38 @@
+import { ExperimentUser, ExperimentUserProvider } from "./user";
+import { Variant, Variants } from "./variant";
+
+/**
+ * Interface for the main client.
+ * @category Core Usage
+ */
+export interface Client {
+  start(user?: ExperimentUser): Promise<void>;
+  stop(): void;
+  fetch(user?: ExperimentUser, options?: FetchOptions): Promise<Client>;
+  fetchOrThrow(user?: ExperimentUser, options?: FetchOptions): Promise<Client>;
+  variant(key: string, fallback?: string | Variant): Variant;
+  all(): Variants;
+  clear(): void;
+  exposure(key: string): void;
+  getUser(): ExperimentUser;
+  setUser(user: ExperimentUser): void;
+
+  /**
+   * @deprecated use ExperimentConfig.userProvider instead
+   */
+  getUserProvider(): ExperimentUserProvider;
+  /**
+   * @deprecated use ExperimentConfig.userProvider instead
+   */
+  setUserProvider(userProvider: ExperimentUserProvider): Client;
+}
+
+/**
+ * Options to modify the behavior of a remote evaluation fetch request.
+ */
+export type FetchOptions = {
+  /**
+   * Specific flag keys to evaluate and set variants for.
+   */
+  flagKeys?: string[];
+};

package/src/experiment/types/config.ts

@@ -0,0 +1,210 @@
+import { nitroHttpClient } from "../../native/http";
+import { NitroMemoryStorage } from "../../native/storage";
+
+import { ExposureTrackingProvider } from "./exposure";
+import { Logger, LogLevel } from "./logger";
+import { Source } from "./source";
+import { Storage } from "./storage";
+import { HttpClient } from "./transport";
+import { ExperimentUserProvider } from "./user";
+import { Variant, Variants } from "./variant";
+
+/**
+ * @category Configuration
+ */
+export interface ExperimentConfig {
+  /**
+   * Debug all assignment requests in the UI Debugger and log additional
+   * information to the console. This should be false for production builds.
+   * @deprecated Use logLevel instead. When debug is true, it sets logLevel to Debug.
+   */
+  debug?: boolean;
+
+  /**
+   * The minimum log level to output. Messages below this level will be ignored.
+   * Supported levels: Disable, Error, Warn, Info, Debug, Verbose.
+   * If the deprecated debug flag is set to true, this will be set to Debug.
+   */
+  logLevel?: LogLevel;
+
+  /**
+   * Custom logger implementation. If not provided, a default ConsoleLogger will be used.
+   * The logger must implement the Logger interface with methods for error, warn, info, debug, and verbose.
+   */
+  loggerProvider?: Logger | null;
+
+  /**
+   * The name of the instance being initialized. Used for initializing separate
+   * instances of experiment or linking the experiment SDK to a specific
+   * instance of the amplitude analytics SDK.
+   */
+  instanceName?: string;
+
+  /**
+   * The default fallback variant for all {@link ExperimentClient.variant}
+   * calls.
+   */
+  fallbackVariant?: Variant;
+
+  /**
+   * Initial values for variants. This is useful for bootstrapping the
+   * client with fallbacks and values evaluated from server-side rendering.
+   * @see Variants
+   */
+  initialVariants?: Variants;
+
+  /**
+   * Initial values for flags. This is useful for bootstrapping the
+   * client with fallbacks for flag configs.
+   */
+  initialFlags?: string;
+
+  /**
+   * Determines the primary source of variants and variants before falling back.
+   * @see Source
+   */
+  source?: Source;
+
+  /**
+   * The domain from which to request variants using remote evaluation.
+   */
+  serverUrl?: string;
+
+  /**
+   * The domain to request flag configurations used in local evaluation from.
+   */
+  flagsServerUrl?: string;
+
+  /**
+   * The amplitude data center to fetch flags and variants from. If set,
+   * automatically sets the {@link serverUrl} and {@link flagsServerUrl}
+   * configurations.
+   */
+  serverZone?: "US" | "EU";
+
+  /**
+   * The request timeout, in milliseconds, when fetching variants.
+   */
+  fetchTimeoutMillis?: number;
+
+  /**
+   * Set to true to retry fetch requests in the background if the initial
+   * requests fails or times out.
+   */
+  retryFetchOnFailure?: boolean;
+
+  /**
+   * If true, automatically tracks exposure events though the
+   * `ExperimentAnalyticsProvider`. If no analytics provider is set, this
+   * option does nothing.
+   */
+  automaticExposureTracking?: boolean;
+
+  /**
+   * Enable or disable local evaluation flag configuration polling on `start()`.
+   */
+  pollOnStart?: boolean;
+
+  /**
+   * Explicitly enable or disable calling {@link fetch()} on {@link start()}:
+   *
+   *  - `true`:      fetch will always be called on start.
+   *  - `false`:     fetch will never be called on start.
+   *  - `undefined`: fetch will always be called on start.
+   */
+  fetchOnStart?: boolean;
+
+  /**
+   * This config only matters if you are using the amplitude analytics SDK
+   * integration initialized by calling
+   * `Experiment.initializeWithAmplitudeAnalytics()`.
+   *
+   * If true, the `ExperimentClient` will automatically fetch variants when the
+   * user's identity changes. The user's identity includes user_id, device_id
+   * and any user properties which are `set`, `unset` or `clearAll`ed via a call
+   * to `identify()`.
+   *
+   * Note: Non-idempotent identify operations `setOnce`, `add`, `append`, and
+   * `prepend` are not counted towards the user identity changing.
+   */
+  automaticFetchOnAmplitudeIdentityChange?: boolean;
+
+  /**
+   * Sets a user provider that will inject identity information into the user
+   * for {@link fetch()} requests. The user provider will only set user fields
+   * in outgoing requests which are null or undefined.
+   *
+   * See {@link ExperimentUserProvider} for more details
+   */
+  userProvider?: ExperimentUserProvider | null;
+
+  /**
+   * Provides the ability to track exposure events through a 3rd party analytics
+   * implementation.
+   */
+  exposureTrackingProvider?: ExposureTrackingProvider | null;
+
+  /**
+   * (Advanced) Use your own http client.
+   */
+  httpClient?: HttpClient;
+
+  /**
+   * (Advanced) Use your own storage implementation.
+   * If not provided, the client will use the built-in shared memory storage implementation.
+   */
+  storage?: Storage | null;
+}
+
+/**
+ Defaults for Experiment Config options
+
+ | **Option**       | **Default**                       |
+ |------------------|-----------------------------------|
+ | **debug**        | `false`                           |
+ | **logLevel**     | `LogLevel.Error`                  |
+ | **logger**       | `null` (ConsoleLogger will be used) |
+ | **instanceName** | `$default_instance` |
+ | **fallbackVariant**         | `null`                 |
+ | **initialVariants**         | `null`                 |
+ | **initialFlags**         | `undefined`                 |
+ | **source** | `Source.LocalStorage` |
+ | **serverUrl**    | `"https://api.lab.amplitude.com"` |
+ | **flagsServerUrl**    | `"https://flag.lab.amplitude.com"` |
+ | **serverZone**    | `"US"` |
+ | **assignmentTimeoutMillis**    | `10000` |
+ | **retryFailedAssignment**    | `true` |
+ | **automaticExposureTracking** | `true` |
+ | **pollOnStart** | `true` |
+ | **fetchOnStart** | `true` |
+ | **automaticFetchOnAmplitudeIdentityChange** | `false` |
+ | **userProvider**    | `null` |
+ | **analyticsProvider**    | `null` |
+ | **exposureTrackingProvider**    | `null` |
+
+ *
+ * @category Configuration
+ */
+export const Defaults: ExperimentConfig = {
+  debug: false,
+  logLevel: LogLevel.Error,
+  loggerProvider: null,
+  instanceName: "$default_instance",
+  fallbackVariant: {},
+  initialVariants: {},
+  initialFlags: undefined,
+  source: Source.LocalStorage,
+  serverUrl: "https://api.lab.amplitude.com",
+  flagsServerUrl: "https://flag.lab.amplitude.com",
+  serverZone: "US",
+  fetchTimeoutMillis: 10000,
+  retryFetchOnFailure: true,
+  automaticExposureTracking: true,
+  pollOnStart: true,
+  fetchOnStart: true,
+  automaticFetchOnAmplitudeIdentityChange: false,
+  userProvider: null,
+  exposureTrackingProvider: null,
+  httpClient: nitroHttpClient,
+  storage: new NitroMemoryStorage("experiment"),
+};