@configdirector/react-native-sdk 1.7.0 → 1.9.0

package/dist/{types-P1hoU2Ru.d.mts → types-BBQmjjf5.d.mts}

@@ -23,7 +23,7 @@ interface ConfigDirectorLogger {
 interface ConfigDirectorLogMessageDecorator {
   decorateMessage(message: string): string;
 }
-type EvaluationReason = "found-match" | "config-state-missing" | "client-not-ready" | "type-mismatch" | "value-missing" | "invalid-number" | "invalid-json" | "invalid-boolean";
+type EvaluationReason = "found-match" | "config-state-missing" | "client-not-ready" | "type-mismatch" | "value-missing" | "invalid-number" | "invalid-json" | "invalid-boolean" | "cached";
 type ConfigEvaluation = {
   key: string;
   value: ConfigValueType;
@@ -42,9 +42,11 @@ type ConfigDirectorContext = {
    * The context's identifier. This should be a value that uniquely identifies the user or other
    * entity among contexts of the same {@link kind}.
    * In the case of anonymous users, you could generate a UUID or alternatively not provide
-   * the {@link id} and the SDK will generate a random UUID. However, keep in mind that this
-   * value is used for segmenting contexts in percentage rollouts, and changes to the {@link id}
-   * could result in the context being assigned to a different percentile.
+   * the {@link id}. In a client SDK, ConfigDirector then derives an identifier from an ID the SDK
+   * stores for the app install or the website, so it stays the same until the app is uninstalled
+   * or the site's data is cleared. However, keep in mind that this value is used for segmenting
+   * contexts in percentage rollouts, and changes to the {@link id} could result in the context
+   * being assigned to a different percentile.
    */
   id?: string;
   /**
@@ -88,9 +90,115 @@ type ConfigDirectorMetaContext = {
   appVersion?: string;
   appName?: string;
 };
-type ConnectionMode = "streaming" | "polling";
+type ConnectionMode = "streaming" | "polling" | "offline";
+//#endregion
+//#region ../shared/src/native-values.d.ts
+type NativeJsonValue = boolean | number | string | null | NativeJsonValue[] | {
+  [key: string]: NativeJsonValue;
+};
+type NativeValue = boolean | number | string | NativeJsonValue[] | {
+  [key: string]: NativeJsonValue;
+};
+type NativeValues = Record<string, NativeValue>;
 //#endregion
 //#region ../js-client-core/src/types.d.ts
+/**
+ * A store for the values the client keeps on the device between launches. One provider instance
+ * serves one client: the provider decides where the entry lives, and the SDK owns the entry's
+ * format, which may change between SDK versions.
+ */
+type CachingProvider = {
+  /**
+   * Returns the stored entry, or `null` or `undefined` when nothing is stored.
+   */
+  read(): string | null | undefined | Promise<string | null | undefined>;
+  /**
+   * Replaces the stored entry. The SDK never writes an entry larger than {@link sizeLimit}.
+   */
+  write(value: string): void | Promise<void>;
+  /**
+   * Removes the stored entry.
+   */
+  remove(): void | Promise<void>;
+  /**
+   * The largest entry, in UTF-8 bytes, the provider accepts. When the values received from
+   * ConfigDirector exceed it, the SDK removes the stored entry and keeps nothing on the device.
+   */
+  sizeLimit(): number;
+};
+/**
+ * Options for the values the client keeps on the device, served on the next launch of the same
+ * context until live values arrive. Ignored in `offline` mode.
+ */
+type CachingOptions = {
+  /**
+   * Whether to keep the last values received on the device. Defaults to `true`.
+   */
+  enabled?: boolean;
+  /**
+   * The store for the values. Defaults to the platform's own store: `localStorage` in the
+   * browser, AsyncStorage on React Native.
+   */
+  provider?: CachingProvider;
+};
+/**
+ * One value an offline client serves for a config key. The config type follows from the value: a
+ * boolean, an integral number (`integer`), any other number (`float`), a string, or a plain object
+ * or array (`json`).
+ */
+type OfflineValue = NativeValue;
+/**
+ * The values an offline client serves, keyed by config key. See {@link OfflineValue} for how each
+ * value's config type is decided. Every context receives the same value.
+ */
+type OfflineValues = NativeValues;
+/**
+ * Connection options of the {@link ConfigDirectorClient}
+ */
+type ConnectionOptions = {
+  /**
+   * The connection mode to be used, one of `streaming` (default), `polling` or `offline`.
+   * If set to `streaming`, the connection will remain open and receive updates whenever
+   * config state is updated on the ConfigDirector dashboard.
+   * When set to `polling`, there will be an initial request to retrieve config state during
+   * initialization, and additional requests on a `pollingInterval`.
+   * When set to `offline`, the client never connects to ConfigDirector and sends nothing: it serves
+   * the values given in {@link values} to every context, or the in-code default values when none
+   * are given. No SDK key is needed.
+   *
+   * Defaults to `streaming`
+   */
+  mode?: ConnectionMode;
+  /**
+   * The values to serve in `offline` mode, keyed by config key. A value such as `null` makes
+   * `initialize` reject with a `ConfigDirectorInitializationError`.
+   *
+   * Can be given only in `offline` mode; otherwise `initialize` rejects.
+   */
+  values?: OfflineValues;
+  /**
+   * The polling interval in _seconds_ when the `mode` is set to `polling`. This option has no
+   * effect in the other modes.
+   *
+   * Defaults to 60 seconds. The minimum is 30 seconds. A value below the minimum is raised to the
+   * minimum and a warning is logged.
+   */
+  pollingInterval?: number;
+  /**
+   * The timeout, in _milliseconds_, to be used in initialization and when updating the context.
+   * If streaming is enabled, the operation (initialization or context update) may still succeed
+   * after it times out if no unrecoverable errors are encountered (like an invalid SDK key).
+   * If streaming is disabled, if the operation times out, it will not be retried. This option has
+   * no effect in `offline` mode.
+   */
+  timeout?: number;
+  /**
+   * The base URL to the ConfigDirector SDK server. To be used only when needing to route through a
+   * proxy to connect to the ConfigDirector SDK server. Please refer to the docs on how to configure
+   * a proxy for the client SDK. This option has no effect in `offline` mode.
+   */
+  url?: string;
+};
 /**
  * Configuration options for the {@link ConfigDirectorClient}
  */
@@ -102,39 +210,13 @@ type ConfigDirectorClientOptions = {
   /**
    * Connection options
    */
-  connection?: {
-    /**
-     * The connection mode to be used, one of `streaming` (default) or `polling`.
-     * If set to `streaming`, the connection will remain open and receive updates whenever
-     * config state is updated on the ConfigDirector dashboard.
-     * When set to `polling`, there will be an initial request to retrieve config state during
-     * initialization, and additional requests on a `pollingInterval`.
-     *
-     * Defaults to `streaming`
-     */
-    mode?: ConnectionMode;
-    /**
-     * The polling interval in _seconds_ when the `mode` is set to `polling`. This option has no
-     * effect when the `mode` is set to `streaming`.
-     *
-     * Defaults to 60 seconds. The minimum is 30 seconds. A value below the minimum is raised to the
-     * minimum and a warning is logged.
-     */
-    pollingInterval?: number;
-    /**
-     * The timeout, in _milliseconds_, to be used in initialization and when updating the context.
-     * If streaming is enabled, the operation (initialization or context update) may still succeed
-     * after it times out if no unrecoverable errors are encountered (like an invalid SDK key).
-     * If streaming is disabled, if the operation times out, it will not be retried.
-     */
-    timeout?: number;
-    /**
-     * The base URL to the ConfigDirector SDK server. To be used only when needing to route through a
-     * proxy to connect to the ConfigDirector SDK server. Please refer to the docs on how to configure
-     * a proxy for the client SDK.
-     */
-    url?: string;
-  };
+  connection?: ConnectionOptions;
+  /**
+   * Options for the values the client keeps on the device between launches. The last values
+   * received are kept by default and served, with the evaluation reason `cached`, on the next
+   * launch of the same context until live values arrive. See {@link CachingOptions}.
+   */
+  caching?: CachingOptions;
   /**
    * A logger that implements {@link ConfigDirectorLogger}. It defaults to the ConfigDirector console
    * logger set to 'warn' level.
@@ -172,6 +254,7 @@ type ClientHooks = {
   contextUpdated?: HookHandler<"contextUpdated"> | HookHandler<"contextUpdated">[];
   configEvaluated?: HookHandler<"configEvaluated"> | HookHandler<"configEvaluated">[];
   connectionError?: HookHandler<"connectionError"> | HookHandler<"connectionError">[];
+  cachedValuesLoaded?: HookHandler<"cachedValuesLoaded"> | HookHandler<"cachedValuesLoaded">[];
 };
 type ClientConnectAction = "initialization" | "context update" | "network resume";
 type HookHandler<TEvent extends keyof ClientEvents> = (payload: ClientEvents[TEvent]) => void;
@@ -192,6 +275,7 @@ type ClientEvents = {
   connectionError: {
     error: Error;
   };
+  cachedValuesLoaded: Record<string, never>;
 };
 type WatchHandler<T extends ConfigValueType> = (message: T) => void;
 /**
@@ -313,4 +397,4 @@ interface ConfigDirectorClient extends EventProvider<ClientEvents> {
   dispose(): void;
 }
 //#endregion
-export { ConfigDirectorLogMessageDecorator as a, ConfigValueType as c, ConfigDirectorContext as i, ConnectionMode as l, ConfigDirectorClient as n, ConfigDirectorLogger as o, ConfigDirectorClientOptions as r, ConfigDirectorLoggingLevel as s, ClientHooks as t };
+export { ConfigDirectorClientOptions as a, NativeJsonValue as c, ConfigDirectorContext as d, ConfigDirectorLogMessageDecorator as f, ConnectionMode as g, ConfigValueType as h, ConfigDirectorClient as i, NativeValue as l, ConfigDirectorLoggingLevel as m, CachingProvider as n, OfflineValue as o, ConfigDirectorLogger as p, ClientHooks as r, OfflineValues as s, CachingOptions as t, NativeValues as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@configdirector/react-native-sdk",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "description": "React Native client SDK for ConfigDirector. ConfigDirector is a remote configuration and feature flag service.",
   "license": "MIT",
   "author": "ConfigDirector",