@dotcms/experiments 0.0.1-alpha.37 → 0.0.1-alpha.39

package/src/lib/shared/{models.d.ts → models.ts}

@@ -26,6 +26,7 @@ export interface DotExperimentConfig {
      */
     redirectFn?: (url: string) => void;
 }
+
 /**
  * Represents the configuration for the LookBackWindow.
  *
@@ -36,15 +37,18 @@ export interface LookBackWindow {
      * Defines the time period in milliseconds when the LookBackWindow should expire.
      */
     expireMillis: number;
+
     /**
      * A value indicating the expiration timestamp of the experiment.
      */
     expireTime?: number;
+
     /**
      * Represents the associated value with the LookBackWindow.
      */
     value: string;
 }
+
 /**
  * Represents the configurations for checking whether the current page is an Experiment page, or a target.
  *
@@ -55,11 +59,13 @@ interface Regexs {
      * A regular expression for validating if the page is an Experiment page.
      */
     isExperimentPage: string;
+
     /**
      * A regular expression for validating if the page is the target page. This can be null.
      */
     isTargetPage: string | null;
 }
+
 /**
  * Represents a variant that is applied when a request is made.
  *
@@ -70,11 +76,13 @@ export interface Variant {
      * The name of the variant.
      */
     name: string;
+
     /**
      * The fully qualified URL where the variant is being applied, with query parameters already set.
      */
     url: string;
 }
+
 /**
  * Represents an experiment with all its configurations.
  *
@@ -85,31 +93,38 @@ export interface Experiment {
      * The unique identifier for the experiment.
      */
     id: string;
+
     /**
      * The lookback window object for the experiment.
      */
     lookBackWindow: LookBackWindow;
+
     /**
      * The name of the experiment.
      */
     name: string;
+
     /**
      * The URL of the page where the experiment is applied.
      */
     pageUrl: string;
+
     /**
      * The object containing regular expressions for validating pages.
      */
     regexs: Regexs;
+
     /**
      * The unique running identifier for the experiment.
      */
     runningId: string;
+
     /**
      * The variant applied to the user making the request.
      */
     variant: Variant;
 }
+
 /**
  * Represents the experiments assigned and their details.
  *
@@ -120,23 +135,31 @@ export interface AssignedExperiments {
      * The ids of the experiments that are excluded in the assignment.
      */
     excludedExperimentIds: string[];
+
     /**
      * An array representing the assigned experiments.
      */
     experiments: Experiment[];
+
     /**
      * The ids of the experiments included in the assignment.
      */
     includedExperimentIds: string[];
+
     /**
      * The ids of the experiments that are excluded in the request and have ended.
      */
     excludedExperimentIdsEnded: string[];
 }
+
 /**
  * Represents the response from the backend when fetching an experiment and the excludedExperimentIdsEnded.
  */
-export type FetchExperiments = Pick<AssignedExperiments, 'excludedExperimentIdsEnded' | 'experiments'>;
+export type FetchExperiments = Pick<
+    AssignedExperiments,
+    'excludedExperimentIdsEnded' | 'experiments'
+>;
+
 /**
  * Represents the response from backend holding information about running experiments and variant assignment.
  *
@@ -147,19 +170,23 @@ export interface IsUserIncludedApiResponse {
      * The object holding all experiment-related information.
      */
     entity: AssignedExperiments;
+
     /**
      * An array holding possible error messages.
      */
     errors: string[];
+
     /**
      * A map that holds internationalization (i18n) messages.
      */
     i18nMessagesMap: Record<string, string>;
+
     /**
      * An array of generic messages.
      */
     messages: string[];
 }
+
 /**
  * Represents a single experiment event.
  *
@@ -170,27 +197,33 @@ export interface ExperimentEvent {
      * The name or identifier of the experiment.
      */
     experiment: string;
+
     /**
      * The unique running identifier of the experiment.
      */
     runningId: string;
+
     /**
      * A flag that determines if the current page is the one where the experiment is conducted.
      */
     isExperimentPage: boolean;
+
     /**
      * A flag that determines if the current page is the target page of the experiment.
      */
     isTargetPage: boolean;
+
     /**
      * Represents the time period for which the experiment is valid or should be considered.
      */
     lookBackWindow: string;
+
     /**
      * Represents the variant of the experiment to specify different versions of an experiment.
      */
     variant: string;
 }
+
 /**
  * Represents parsed data of an experiment that is ready to be sent to Analytics.
  *
@@ -201,9 +234,9 @@ export interface ExperimentParsed {
      * The URL of the experiment. It helps track the location or origin of the experiment.
      */
     href: string;
+
     /**
      * An array holding details of individual experiments being conducted.
      */
     experiments: ExperimentEvent[];
 }
-export {};

package/src/lib/shared/parser/parse.spec.ts

@@ -0,0 +1,187 @@
+import { parseData, parseDataForAnalytics } from './parser';
+
+import {
+    IsUserIncludedResponse,
+    LocationMock,
+    MOCK_CURRENT_TIMESTAMP,
+    MockDataStoredIndexDB,
+    MockDataStoredIndexDBWithNew,
+    MockDataStoredIndexDBWithNew15DaysLater,
+    NewIsUserIncludedResponse,
+    TIME_15_DAYS_MILLISECONDS,
+    TIME_5_DAYS_MILLISECONDS
+} from '../mocks/mock';
+import { Experiment, ExperimentParsed, FetchExperiments } from '../models';
+
+const assignedExperiments: Experiment[] = IsUserIncludedResponse.entity.experiments;
+
+const experimentMock = IsUserIncludedResponse.entity.experiments[0];
+
+describe('Parsers', () => {
+    describe('parseData For Analytics', () => {
+        it('returns `isExperimentPage` true and `isTargetPage` false when location is /blog', () => {
+            const expectedURL = 'http://localhost/blog';
+
+            const expectedExperimentsParsed: ExperimentParsed = {
+                href: expectedURL,
+                experiments: [
+                    {
+                        experiment: experimentMock.id,
+                        runningId: experimentMock.runningId,
+                        variant: experimentMock.variant.name,
+                        lookBackWindow: experimentMock.lookBackWindow.value,
+                        isExperimentPage: true,
+                        isTargetPage: false
+                    }
+                ]
+            };
+
+            const location: Location = { ...LocationMock, href: expectedURL };
+
+            const parsedData: ExperimentParsed = parseDataForAnalytics(
+                assignedExperiments,
+                location
+            );
+
+            expect(parsedData).toStrictEqual(expectedExperimentsParsed);
+        });
+
+        it('returns `isExperimentPage` false and `isTargetPage` true when location is /destinations', () => {
+            const expectedURL = 'http://localhost/destinations';
+
+            const expectedExperimentsParsed: ExperimentParsed = {
+                href: expectedURL,
+                experiments: [
+                    {
+                        experiment: experimentMock.id,
+                        runningId: experimentMock.runningId,
+                        variant: experimentMock.variant.name,
+                        lookBackWindow: experimentMock.lookBackWindow.value,
+                        isExperimentPage: false,
+                        isTargetPage: true
+                    }
+                ]
+            };
+
+            const location: Location = { ...LocationMock, href: expectedURL };
+
+            const parsedData: ExperimentParsed = parseDataForAnalytics(
+                assignedExperiments,
+                location
+            );
+
+            expect(parsedData).toStrictEqual(expectedExperimentsParsed);
+        });
+
+        it('returns `isExperimentPage` false and `isTargetPage` false when location is /other-url', () => {
+            const expectedURL = 'http://localhost/other-url';
+
+            const expectedExperimentsParsed: ExperimentParsed = {
+                href: expectedURL,
+                experiments: [
+                    {
+                        experiment: experimentMock.id,
+                        runningId: experimentMock.runningId,
+                        variant: experimentMock.variant.name,
+                        lookBackWindow: experimentMock.lookBackWindow.value,
+                        isExperimentPage: false,
+                        isTargetPage: false
+                    }
+                ]
+            };
+
+            const location: Location = { ...LocationMock, href: expectedURL };
+
+            const parsedData: ExperimentParsed = parseDataForAnalytics(
+                assignedExperiments,
+                location
+            );
+
+            expect(parsedData).toStrictEqual(expectedExperimentsParsed);
+        });
+    });
+
+    describe('parseData For Store', () => {
+        const mockNow = jest.spyOn(Date, 'now');
+
+        mockNow.mockImplementation(() => MOCK_CURRENT_TIMESTAMP);
+
+        beforeEach(() => {
+            jest.clearAllMocks();
+        });
+
+        it('should handle case where only NEW data is available', () => {
+            // First request, expire in now + experiment.lookBackWindow.expireMillis
+            const newData: FetchExperiments = {
+                experiments: IsUserIncludedResponse.entity.experiments,
+                excludedExperimentIdsEnded: []
+            };
+
+            const dataFromIndexDB: Experiment[] | undefined = undefined;
+
+            const parsedData = parseData(newData, dataFromIndexDB);
+
+            expect(parsedData).toStrictEqual(MockDataStoredIndexDB);
+            expect(newData.experiments.length).toBe(parsedData.length);
+        });
+
+        it('should handle case where only OLD data is available', () => {
+            //No new request, not touch anything if not expired
+
+            const newData: FetchExperiments = {
+                experiments: [],
+                excludedExperimentIdsEnded: []
+            };
+
+            const dataFromIndexDB: Experiment[] | undefined = MockDataStoredIndexDB;
+
+            const parsedData = parseData(newData, dataFromIndexDB);
+
+            expect(parsedData).toStrictEqual(MockDataStoredIndexDB);
+            expect(MockDataStoredIndexDB.length).toBe(parsedData.length);
+        });
+
+        it('should handle case where both OLD and NEW data are available', () => {
+            //new request, stored data + new data. No delete anything only 5 days passed, 2 to store
+
+            const nowPlus5Days = MOCK_CURRENT_TIMESTAMP + TIME_5_DAYS_MILLISECONDS;
+
+            mockNow.mockImplementation(() => nowPlus5Days);
+
+            const newData: FetchExperiments = {
+                experiments: NewIsUserIncludedResponse.entity.experiments,
+                excludedExperimentIdsEnded: [
+                    ...NewIsUserIncludedResponse.entity.excludedExperimentIdsEnded
+                ]
+            };
+
+            const dataFromIndexDB: Experiment[] | undefined = MockDataStoredIndexDB;
+
+            const parsedData = parseData(newData, dataFromIndexDB);
+
+            expect(parsedData).toStrictEqual(MockDataStoredIndexDBWithNew);
+
+            expect(parsedData.length).toBe(MockDataStoredIndexDBWithNew.length);
+        });
+
+        it('should remove from stored experiment the experiments expired', () => {
+            // no new request, 15 days later, so expireTime is 15 days from MOCK_CURRENT_TIMESTAMP
+            // 1st experiment expired, so only 1 to store
+            const now15Days = MOCK_CURRENT_TIMESTAMP + TIME_15_DAYS_MILLISECONDS;
+
+            mockNow.mockImplementation(() => now15Days);
+
+            const newData: FetchExperiments = {
+                experiments: [],
+                excludedExperimentIdsEnded: []
+            };
+
+            const dataFromIndexDB: Experiment[] | undefined = MockDataStoredIndexDBWithNew;
+
+            const parsedData = parseData(newData, dataFromIndexDB);
+
+            expect(parsedData.length).toBe(MockDataStoredIndexDBWithNew15DaysLater.length);
+            expect(parsedData).toStrictEqual(MockDataStoredIndexDBWithNew15DaysLater);
+        });
+    });
+});

package/src/lib/shared/parser/parser.ts

@@ -0,0 +1,171 @@
+import { Experiment, ExperimentParsed, FetchExperiments } from '../models';
+
+/**
+ * This arrow function parses a given set of assigned experiments for analytics.
+ *
+ * This process involves iterating over the experiments, which are currently in the "Running" state as received from the DotCMS endpoint,
+ * analyzing each experiment's relevant data such as running ID, variant name, and look back window value.
+ * It also performs regular expression verification for both 'isExperimentPage' and 'isTargetPage' against the current URL.
+ *
+ * The parsed data is useful for tracking and understanding the user's interaction with the experiment-targeted components during their visit.
+ *
+ * Contains an object with experiments information.
+ *
+ * @param experiments
+ * @param {Location} location - This parameter is the object representing the current location (URL) of the user.
+ * Mostly employed for matching the regular expressions to detect whether the current page is an 'ExperimentPage' or a 'TargetPage'.
+ *
+ * @returns {ExperimentParsed} - The function returns an object with the original URL and an array of each experiment's comprehensive detail.
+ * The return object is suitable for further analytical operations. Each experiment's detail includes the experiment ID, running ID, variant name,
+ * look back window value, and booleans that represent whether current URL is 'isExperimentPage' or 'isTargetPage' for the respective experiment.
+ */
+export const parseDataForAnalytics = (
+    experiments: Experiment[],
+    location: Location
+): ExperimentParsed => {
+    const currentHref = location.href;
+
+    return {
+        href: currentHref,
+        experiments: experiments.map((experiment) => ({
+            experiment: experiment.id,
+            runningId: experiment.runningId,
+            variant: experiment.variant.name,
+            lookBackWindow: experiment.lookBackWindow.value,
+            isExperimentPage: verifyRegex(experiment.regexs.isExperimentPage, currentHref),
+            isTargetPage: verifyRegex(experiment.regexs.isTargetPage, currentHref)
+        }))
+    };
+};
+
+/**
+ * This utility function performs regular expression (regex) matching on a supplied URL.
+ *
+ * @param {string | null} regexToCheck - The regular expression to match against the URL.
+ * @param {string} href - This is the target URL, which is aimed to be matched against the provided regular expression.
+ * @returns {boolean} -The function returns a Boolean value.
+ */
+export const verifyRegex = (regexToCheck: string | null, href: string): boolean => {
+    if (regexToCheck === null || href === null) {
+        return false;
+    }
+
+    try {
+        const regexExp = new RegExp(regexToCheck);
+
+        const url = new URL(href);
+
+        const sanitizedHref = `${url.origin}${url.pathname.toLowerCase()}${url.search}`;
+
+        return regexExp.test(sanitizedHref);
+    } catch (error) {
+        console.warn(`The regex ${regexToCheck} it is not a valid regex to check. ${error}`);
+
+        return false;
+    }
+};
+
+/**
+ * This function merges newly fetched data with the data stored from IndexedDB, preparing it for re-storage in IndexedDB.
+ *
+ * @param { AssignedExperiments | null } fetchExperiments - The experiment data fetched from the API.
+ * @param { AssignedExperiments | null } storedExperiments - The experiment data currently stored in IndexedDB.
+ *
+ * @returns { AssignedExperiments } - The parsed experiment data ready for storing.
+ *
+ * Following cases are handled -
+ * 1) When new Data is received without Old data. This is assumed to be the first time data is received.
+ * 2) When only old data is received, implying that the timestamp hasn't expired and the data is available in IndexedDB.
+ *    The data is verified and any expired experiment is removed before being assigned to dataToStorage.
+ * 3) When both old data and new data is present. This implies that the record existed in IndexedDB but was fetched because the flag had expired.
+ *    Additional operations are performed to add expiry time to experiments, merging all experiments, and storing them.
+ *
+ * There could be scenarios where none of these conditions are met, in that case, dataToStorage will be the default empty object.
+ */
+export const parseData = (
+    fetchExperiments: FetchExperiments,
+    storedExperiments: Experiment[] | undefined
+): Experiment[] => {
+    let dataToStorage: Experiment[] = {} as Experiment[];
+
+    const { excludedExperimentIdsEnded } = fetchExperiments;
+
+    if (fetchExperiments && !storedExperiments) {
+        // TODO: Use fetchExperiment instead fetchExperimentsNoNoneExperimentID when the endpoint dont retrieve NONE experiment
+        // https://github.com/dotCMS/core/issues/27905
+        const fetchExperimentsNoNoneExperimentID: Experiment[] = fetchExperiments.experiments
+            ? fetchExperiments.experiments.filter((experiment) => experiment.id !== 'NONE')
+            : [];
+
+        dataToStorage = addExpireTimeToExperiments(fetchExperimentsNoNoneExperimentID);
+    }
+
+    if (!fetchExperiments && storedExperiments) {
+        dataToStorage = getUnexpiredExperiments(storedExperiments, excludedExperimentIdsEnded);
+    }
+
+    if (fetchExperiments && storedExperiments) {
+        // TODO: Use fetchExperiment instead fetchExperimentsNoNoneExperimentID when the endpoint dont retrieve NONE experiment
+        // https://github.com/dotCMS/core/issues/27905
+        const fetchExperimentsNoNoneExperimentID: Experiment[] = fetchExperiments.experiments
+            ? fetchExperiments.experiments.filter((experiment) => experiment.id !== 'NONE')
+            : [];
+
+        dataToStorage = [
+            ...addExpireTimeToExperiments(fetchExperimentsNoNoneExperimentID),
+            ...getUnexpiredExperiments(storedExperiments, excludedExperimentIdsEnded)
+        ];
+    }
+
+    return dataToStorage;
+};
+
+/**
+ * Retrieves the array of experiment IDs from the given AssignedExperiments..
+ *
+ * @returns {string[]} Returns an array of experiment IDs if available, otherwise an empty array.
+ * @param experiments
+ */
+export const getExperimentsIds = (experiments: Experiment[]): string[] =>
+    experiments.map((experiment: Experiment) => experiment.id) || [];
+
+/**
+ * Sets the expire time for new experiments based on the current time.
+ * The expire time is calculated by adding the expireMillis value of each experiment's lookBackWindow to the current time (Date.now()).
+ *
+ * @param {Array<Experiment>} experiments - An array of experiments to set the expire time for.
+ * @returns {Array<Experiment>} - An updated array of experiments with expire time set.
+ */
+const addExpireTimeToExperiments = (experiments: Experiment[]): Experiment[] => {
+    const now = Date.now();
+
+    return experiments.map((experiment) => ({
+        ...experiment,
+        lookBackWindow: {
+            ...experiment.lookBackWindow,
+            expireTime: now + experiment.lookBackWindow.expireMillis
+        }
+    }));
+};
+
+/**
+ * Returns an array of experiments that have not expired yet.
+ *
+ * @param {Experiment[]} experiments - An array of experiments to filter.
+ * @param excludedExperimentIdsEnded -  Array of Experiments ids that have been manually ended.
+ * @returns {Experiment[]} An array of unexpired experiments.
+ */
+const getUnexpiredExperiments = (
+    experiments: Experiment[],
+    excludedExperimentIdsEnded: string[]
+): Experiment[] => {
+    const now = Date.now();
+
+    return experiments.filter((experiment) => {
+        const expireTime = experiment.lookBackWindow?.expireTime;
+
+        return expireTime
+            ? expireTime > now && !excludedExperimentIdsEnded.includes(experiment.id)
+            : false;
+    });
+};

package/src/lib/shared/persistence/index-db-database-handler.spec.ts

@@ -0,0 +1,100 @@
+import fakeIndexedDB from 'fake-indexeddb';
+
+import { IndexDBDatabaseHandler } from './index-db-database-handler';
+
+import {
+    EXPERIMENT_ALREADY_CHECKED_KEY,
+    EXPERIMENT_DB_KEY_PATH,
+    EXPERIMENT_DB_STORE_NAME
+} from '../constants';
+import { IsUserIncludedResponse } from '../mocks/mock';
+import { checkFlagExperimentAlreadyChecked } from '../utils/utils';
+
+if (!globalThis.structuredClone) {
+    globalThis.structuredClone = function (obj) {
+        return JSON.parse(JSON.stringify(obj));
+    };
+}
+
+let persistDatabaseHandler: IndexDBDatabaseHandler;
+
+beforeAll(() => {
+    Object.defineProperty(window, 'indexedDB', {
+        writable: true,
+        value: fakeIndexedDB
+    });
+
+    persistDatabaseHandler = new IndexDBDatabaseHandler({
+        db_store: EXPERIMENT_DB_STORE_NAME,
+        db_name: EXPERIMENT_DB_STORE_NAME,
+        db_key_path: EXPERIMENT_DB_KEY_PATH
+    });
+});
+
+describe('IndexedDB tests', () => {
+    it('saveData successfully saves data to the store', async () => {
+        const key = await persistDatabaseHandler.persistData(IsUserIncludedResponse.entity);
+
+        expect(key).toBe(EXPERIMENT_DB_KEY_PATH);
+    });
+
+    it('getDataByKey successfully retrieves data from the store', async () => {
+        await persistDatabaseHandler.persistData(IsUserIncludedResponse.entity);
+
+        const data = await persistDatabaseHandler.getData();
+
+        expect(data).toEqual(IsUserIncludedResponse.entity);
+    });
+});
+
+describe('SessionStorage EXPERIMENT_ALREADY_CHECKED_KEY handle', () => {
+    Object.defineProperty(window, 'sessionStorage', {
+        value: {
+            setItem: jest.fn(),
+            getItem: jest.fn()
+        },
+        writable: true
+    });
+    it('should set true to sessionStorage key `EXPERIMENT_ALREADY_CHECKED_KEY` ', () => {
+        const value = 'true';
+
+        persistDatabaseHandler.setFlagExperimentAlreadyChecked();
+
+        expect(window.sessionStorage.setItem).toHaveBeenLastCalledWith(
+            EXPERIMENT_ALREADY_CHECKED_KEY,
+            value
+        );
+    });
+
+    it('should set true to sessionStorage key `EXPERIMENT_ALREADY_CHECKED_KEY` ', () => {
+        const value = 'true';
+
+        persistDatabaseHandler.setFlagExperimentAlreadyChecked();
+
+        expect(window.sessionStorage.setItem).toHaveBeenLastCalledWith(
+            EXPERIMENT_ALREADY_CHECKED_KEY,
+            value
+        );
+    });
+
+    describe('checkFlagExperimentAlreadyChecked', () => {
+        const getItemMock = window.sessionStorage.getItem as jest.MockedFunction<
+            typeof window.sessionStorage.getItem
+        >;
+
+        const testCases = [
+            { value: '', expected: false, description: 'sessionStorage value is ""' },
+            { value: 'true', expected: true, description: 'sessionStorage value is "true"' },
+            { value: null, expected: false, description: 'sessionStorage value is null' }
+        ];
+
+        testCases.forEach(({ description, value, expected }) => {
+            it(`returns ${expected} when ${description}`, () => {
+                getItemMock.mockReturnValue(value);
+
+                expect(checkFlagExperimentAlreadyChecked()).toBe(expected);
+                expect(getItemMock).toHaveBeenCalledWith(EXPERIMENT_ALREADY_CHECKED_KEY);
+            });
+        });
+    });
+});