@statsig/js-client 0.0.1-beta.24 → 0.0.1-beta.26

package/src/StatsigClient.js

@@ -15,6 +15,13 @@ const Network_1 = require("./Network");
 const StatsigEvaluationsDataAdapter_1 = require("./StatsigEvaluationsDataAdapter");
 require("./StatsigMetadataAdditions");
 class StatsigClient extends client_core_1.StatsigClientBase {
+    /**
+     * StatsigClient constuctor
+     *
+     * @param {string} sdkKey A Statsig client SDK key. eg "client-xyz123..."
+     * @param {StatsigUser} user StatsigUser object containing various attributes related to a user.
+     * @param {StatsigOptions | null} options StatsigOptions, used to customize the behavior of the SDK.
+     */
     constructor(sdkKey, user, options = null) {
         var _a;
         const network = new Network_1.default(options, (e) => {
@@ -26,6 +33,14 @@ class StatsigClient extends client_core_1.StatsigClientBase {
         this._store = new EvaluationStore_1.default();
         this._user = user;
     }
+    /**
+     * Retrieves an instance of the StatsigClient based on the provided SDK key.
+     *  If no SDK key is provided, the method returns the most recently created instance of the StatsigClient.
+     *  The method ensures that each unique SDK key corresponds to a single instance of StatsigClient, effectively implementing a singleton pattern for each key.
+     *
+     * @param {string} [sdkKey] - Optional. The SDK key used to identify a specific instance of the StatsigClient. If omitted, the method returns the last created instance.
+     * @returns {StatsigClient|undefined} Returns the StatsigClient instance associated with the given SDK key, or undefined if no instance is associated with the key or if no key is provided and no instances exist.
+     */
     static instance(sdkKey) {
         var _a;
         __STATSIG__ = __STATSIG__ !== null && __STATSIG__ !== void 0 ? __STATSIG__ : {};
@@ -34,12 +49,36 @@ class StatsigClient extends client_core_1.StatsigClientBase {
         }
         return (_a = __STATSIG__.instances) === null || _a === void 0 ? void 0 : _a[sdkKey];
     }
+    /**
+     * Initializes the StatsigClient using cached values. This method sets up the client synchronously by utilizing previously cached values.
+     * After initialization, cache values are updated in the background for future use, either in subsequent sessions or when `updateUser` is called.
+     * This is useful for quickly starting with the last-known-good configurations while refreshing data to keep settings up-to-date.
+     *
+     * @see {@link initializeAsync} for the asynchronous version of this method.
+     */
     initializeSync() {
         this.updateUserSync(this._user);
     }
+    /**
+     * Initializes the StatsigClient asynchronously by first using cached values and then updating to the latest values from the network.
+     * Once the network values are fetched, they replace the existing cached values. If this method's promise is not awaited,
+     * there might be a transition from cached to network values during the session, which can affect consistency.
+     * This method is useful when it's acceptable to begin with potentially stale data and switch to the latest configuration as it becomes available.
+     *
+     * @returns {Promise<void>} A promise that resolves once the client is fully initialized with the latest values from the network.
+     * @see {@link initializeSync} for the synchronous version of this method.
+     */
     initializeAsync() {
         return this.updateUserAsync(this._user);
     }
+    /**
+     * Synchronously updates the user in the Statsig client and switches the internal state to use cached values for the newly specified user.
+     * After the initial switch to cached values, this method updates these values in the background, preparing them for future sessions or subsequent calls to updateUser.
+     * This method ensures the client is quickly ready with available data.
+     *
+     * @param {StatsigUser} user - The new StatsigUser for which the client should update its internal state.
+     * @see {@link updateUserAsync} for the asynchronous version of this method.
+     */
     updateUserSync(user) {
         this._resetForUser(user);
         const result = this.dataAdapter.getDataSync(this._user);
@@ -48,6 +87,16 @@ class StatsigClient extends client_core_1.StatsigClientBase {
         this._setStatus('Ready', result);
         this._runPostUpdate(result !== null && result !== void 0 ? result : null, this._user);
     }
+    /**
+     * Asynchronously updates the user in the Statsig client by initially using cached values and then fetching the latest values from the network.
+     * When the latest values are fetched, they replace the cached values. If the promise returned by this method is not awaited,
+     * the client's state may shift from cached to updated network values during the session, potentially affecting consistency.
+     * This method is best used in scenarios where up-to-date configuration is critical and initial delays are acceptable.
+     *
+     * @param {StatsigUser} user - The new StatsigUser for which the client should update its internal state.
+     * @returns {Promise<void>} A promise that resolves once the client is fully updated with the latest network values.
+     * @see {@link updateUserSync} for the synchronous version of this method.
+     */
     updateUserAsync(user) {
         return __awaiter(this, void 0, void 0, function* () {
             this._resetForUser(user);
@@ -64,9 +113,12 @@ class StatsigClient extends client_core_1.StatsigClientBase {
             this._setStatus('Ready', result);
         });
     }
-    checkGate(name, options) {
-        return this.getFeatureGate(name, options).value;
-    }
+    /**
+     * Retrieves a synchronous context containing data currently being used by the SDK. Represented as a {@link PrecomputedEvaluationsContext} object.
+     *
+     * @returns {PrecomputedEvaluationsContext} The current synchronous context for the this StatsigClient instance.
+     * @see {@link getAsyncContext} for the asynchronous version of the context that includes more information.
+     */
     getContext() {
         return {
             sdkKey: this._sdkKey,
@@ -75,51 +127,103 @@ class StatsigClient extends client_core_1.StatsigClientBase {
             user: JSON.parse(JSON.stringify(this._user)),
         };
     }
+    /**
+     * Asynchronously retrieves a context similar to that provided by {@link getContext}, but with additional properties fetched asynchronously, such as session and stable IDs. This is useful for situations where these IDs are required and are not immediately available.
+     *
+     * @returns {PrecomputedEvaluationsAsyncContext} An object containing the current values.
+     * @see {@link getContext} for the synchronous version of the context that this function extends.
+     */
     getAsyncContext() {
         return __awaiter(this, void 0, void 0, function* () {
             return Object.assign(Object.assign({}, this.getContext()), { sessionID: yield client_core_1.SessionID.get(this._sdkKey), stableID: yield client_core_1.StableID.get(this._sdkKey) });
         });
     }
+    /**
+     * Retrieves the value of a feature gate for the current user, represented as a simple boolean.
+     *
+     * @param {string} name - The name of the feature gate to retrieve.
+     * @param {FeatureGateEvaluationOptions} [options] - Optional. Additional options to customize the method call.
+     * @returns {boolean} - The boolean value representing the gate's current evaluation results for the user.
+     */
+    checkGate(name, options) {
+        return this.getFeatureGate(name, options).value;
+    }
+    /**
+     * Retrieves the value of a feature gate for the current user, represented as a {@link FeatureGate} object.
+     *
+     * @param {string} name - The name of the feature gate to retrieve.
+     * @param {FeatureGateEvaluationOptions} [options] - Optional. Additional options to customize the method call.
+     * @returns {FeatureGate} - The {@link FeatureGate} object representing the gate's current evaluation results for the user.
+     */
     getFeatureGate(name, options) {
         var _a, _b;
         const hash = (0, client_core_1.DJB2)(name);
         const { evaluation, details } = this._store.getGate(hash);
-        const gate = (0, client_core_1.makeFeatureGate)(name, details, evaluation);
+        const gate = (0, client_core_1._makeFeatureGate)(name, details, evaluation);
         const overridden = (_b = (_a = this._overrideAdapter) === null || _a === void 0 ? void 0 : _a.getGateOverride) === null || _b === void 0 ? void 0 : _b.call(_a, gate, this._user, options);
         const result = overridden !== null && overridden !== void 0 ? overridden : gate;
         this._enqueueExposure(name, (0, client_core_1.createGateExposure)(this._user, result), options);
         this._emit({ name: 'gate_evaluation', gate: result });
         return result;
     }
+    /**
+     * Retrieves the value of a dynamic config for the current user.
+     *
+     * @param {string} name The name of the dynamic config to get.
+     * @param {DynamicConfigEvaluationOptions} [options] - Optional. Additional options to customize the method call.
+     * @returns {DynamicConfig} - The {@link DynamicConfig} object representing the dynamic configs's current evaluation results for the user.
+     */
     getDynamicConfig(name, options) {
         const dynamicConfig = this._getConfigImpl('dynamic_config', name, options);
         this._emit({ name: 'dynamic_config_evaluation', dynamicConfig });
         return dynamicConfig;
     }
+    /**
+     * Retrieves the value of a experiment for the current user.
+     *
+     * @param {string} name The name of the experiment to get.
+     * @param {ExperimentEvaluationOptions} [options] - Optional. Additional options to customize the method call.
+     * @returns {Experiment} - The {@link Experiment} object representing the experiments's current evaluation results for the user.
+     */
     getExperiment(name, options) {
         const experiment = this._getConfigImpl('experiment', name, options);
         this._emit({ name: 'experiment_evaluation', experiment });
         return experiment;
     }
+    /**
+     * Retrieves the value of a layer for the current user.
+     *
+     * @param {string} name The name of the layer to get.
+     * @param {LayerEvaluationOptions} [options] - Optional. Additional options to customize the method call.
+     * @returns {Layer} - The {@link Layer} object representing the layers's current evaluation results for the user.
+     */
     getLayer(name, options) {
-        var _a, _b;
+        var _a, _b, _c;
         const hash = (0, client_core_1.DJB2)(name);
         const { evaluation, details } = this._store.getLayer(hash);
-        const layer = (0, client_core_1.makeLayer)(name, details, evaluation);
+        const layer = (0, client_core_1._makeLayer)(name, details, evaluation);
         const overridden = (_b = (_a = this._overrideAdapter) === null || _a === void 0 ? void 0 : _a.getLayerOverride) === null || _b === void 0 ? void 0 : _b.call(_a, layer, this._user, options);
-        const result = overridden !== null && overridden !== void 0 ? overridden : layer;
+        const result = (0, client_core_1._mergeOverride)(layer, overridden, (_c = overridden === null || overridden === void 0 ? void 0 : overridden.__value) !== null && _c !== void 0 ? _c : layer.__value, (param) => {
+            this._enqueueExposure(name, (0, client_core_1.createLayerParameterExposure)(this._user, result, param), options);
+        });
         this._emit({ name: 'layer_evaluation', layer: result });
-        return Object.assign(Object.assign({}, result), { getValue: (param) => {
-                var _a;
-                if (!(param in result._value)) {
-                    return null;
-                }
-                const exposure = (0, client_core_1.createLayerParameterExposure)(this._user, result, param);
-                this._enqueueExposure(name, exposure, options);
-                return (_a = result._value[param]) !== null && _a !== void 0 ? _a : null;
-            } });
-    }
-    logEvent(event) {
+        return result;
+    }
+    /**
+     * Logs an event to the internal logging system. This function allows logging by either passing a fully formed event object or by specifying the event name with optional value and metadata.
+     *
+     * @param {StatsigEvent|string} eventOrName - The event object conforming to the StatsigEvent interface, or the name of the event as a string.
+     * @param {string|number} value - Optional. The value associated with the event, which can be a string or a number. This parameter is ignored if the first parameter is a StatsigEvent object.
+     * @param {Record<string, string>} metadata - Optional. A key-value record containing metadata about the event. This is also ignored if the first parameter is an event object.
+     */
+    logEvent(eventOrName, value, metadata) {
+        const event = typeof eventOrName === 'string'
+            ? {
+                eventName: eventOrName,
+                value,
+                metadata,
+            }
+            : eventOrName;
         this._logger.enqueue(Object.assign(Object.assign({}, event), { user: this._user, time: Date.now() }));
     }
     _runPostUpdate(current, user) {
@@ -136,7 +240,7 @@ class StatsigClient extends client_core_1.StatsigClientBase {
         var _a, _b, _c, _d;
         const hash = (0, client_core_1.DJB2)(name);
         const { evaluation, details } = this._store.getConfig(hash);
-        const config = (0, client_core_1.makeDynamicConfig)(name, details, evaluation);
+        const config = (0, client_core_1._makeDynamicConfig)(name, details, evaluation);
         const overridden = kind === 'experiment'
             ? (_b = (_a = this._overrideAdapter) === null || _a === void 0 ? void 0 : _a.getExperimentOverride) === null || _b === void 0 ? void 0 : _b.call(_a, config, this._user, options)
             : (_d = (_c = this._overrideAdapter) === null || _c === void 0 ? void 0 : _c.getDynamicConfigOverride) === null || _d === void 0 ? void 0 : _d.call(_c, config, this._user, options);

package/src/__tests__/MockLocalStorage.d.ts

@@ -1,9 +0,0 @@
-export declare class MockLocalStorage {
-    data: Record<string, string>;
-    static enabledMockStorage(): MockLocalStorage;
-    static disableMockStorage(): void;
-    clear(): void;
-    getItem(key: string): string | null;
-    setItem(key: string, value: string): void;
-    removeItem(key: string): void;
-}

package/src/__tests__/MockLocalStorage.js

@@ -1,36 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.MockLocalStorage = void 0;
-const actualLocalStorage = window.localStorage;
-// todo: move to test-helpers (break circular dep)
-class MockLocalStorage {
-    constructor() {
-        this.data = {};
-    }
-    static enabledMockStorage() {
-        const value = new MockLocalStorage();
-        Object.defineProperty(window, 'localStorage', {
-            value,
-        });
-        return value;
-    }
-    static disableMockStorage() {
-        Object.defineProperty(window, 'localStorage', {
-            value: actualLocalStorage,
-        });
-    }
-    // LocalStorage Functions
-    clear() {
-        this.data = {};
-    }
-    getItem(key) {
-        return this.data[key] ? this.data[key] : null;
-    }
-    setItem(key, value) {
-        this.data[key] = String(value);
-    }
-    removeItem(key) {
-        delete this.data[key];
-    }
-}
-exports.MockLocalStorage = MockLocalStorage;