@naturalcycles/abba 1.13.1 → 1.14.0

package/dist/abba.d.ts

@@ -3,22 +3,19 @@ import { AbbaConfig, Bucket, BucketInput, Experiment, ExperimentWithBuckets, Gen
 import { SegmentationData, AssignmentStatistics } from '.';
 export declare class Abba {
     cfg: AbbaConfig;
-    constructor(cfg: AbbaConfig);
     private experimentDao;
     private bucketDao;
     private userAssignmentDao;
+    constructor(cfg: AbbaConfig);
     /**
-     * Returns all (active and inactive) experiments.
-     *
-     * Cold method, not cached.
+     * Returns all experiments.
+     * Cached (see CACHE_TTL)
      */
     getAllExperiments(): Promise<ExperimentWithBuckets[]>;
     /**
-     * Returns only active experiments.
-     * Hot method.
-     * Cached in-memory for N minutes (currently 10).
+     * Returns all experiments.
      */
-    getActiveExperiments(): Promise<ExperimentWithBuckets[]>;
+    getAllExperimentsNoCache(): Promise<ExperimentWithBuckets[]>;
     /**
      * Creates a new experiment.
      * Cold method.
@@ -31,11 +28,15 @@ export declare class Abba {
     saveExperiment(experiment: Experiment & {
         id: number;
     }, buckets: Bucket[]): Promise<ExperimentWithBuckets>;
+    /**
+     * Ensures that mutual exclusions are maintained
+     */
+    private updateExclusions;
     /**
      * Delete an experiment. Removes all user assignments and buckets.
      * Cold method.
      */
-    deleteExperiment(id: number): Promise<void>;
+    deleteExperiment(experimentId: number): Promise<void>;
     /**
      * Get an assignment for a given user. If existingOnly is false, it will attempt to generate a new assignment
      * Cold method.
@@ -63,13 +64,4 @@ export declare class Abba {
      * Cold method.
      */
     getExperimentAssignmentStatistics(experimentId: number): Promise<AssignmentStatistics>;
-    /**
-     * Generate a new assignment for a given user.
-     * Doesn't save it.
-     */
-    private generateUserAssignmentData;
-    /**
-     * Queries to retrieve an existing user assignment for a given experiment
-     */
-    private getExistingUserAssignment;
 }

package/dist/abba.js

@@ -9,45 +9,30 @@ const util_1 = require("./util");
 const experiment_dao_1 = require("./dao/experiment.dao");
 const userAssignment_dao_1 = require("./dao/userAssignment.dao");
 const bucket_dao_1 = require("./dao/bucket.dao");
+/**
+ * 10 minutes
+ */
 const CACHE_TTL = 600000; // 10 minutes
 class Abba {
     constructor(cfg) {
         this.cfg = cfg;
-        const { db } = cfg;
-        this.experimentDao = (0, experiment_dao_1.experimentDao)(db);
-        this.bucketDao = (0, bucket_dao_1.bucketDao)(db);
-        this.userAssignmentDao = (0, userAssignment_dao_1.userAssignmentDao)(db);
+        this.experimentDao = (0, experiment_dao_1.experimentDao)(this.cfg.db);
+        this.bucketDao = (0, bucket_dao_1.bucketDao)(this.cfg.db);
+        this.userAssignmentDao = (0, userAssignment_dao_1.userAssignmentDao)(this.cfg.db);
     }
     /**
-     * Returns all (active and inactive) experiments.
-     *
-     * Cold method, not cached.
+     * Returns all experiments.
+     * Cached (see CACHE_TTL)
      */
     async getAllExperiments() {
-        const experiments = await this.experimentDao.query().runQuery();
-        const buckets = await this.bucketDao
-            .query()
-            .filter('experimentId', 'in', experiments.map(e => e.id))
-            .runQuery();
-        return experiments.map(experiment => ({
-            ...experiment,
-            buckets: buckets.filter(bucket => bucket.experimentId === experiment.id),
-        }));
+        return await this.getAllExperimentsNoCache();
     }
     /**
-     * Returns only active experiments.
-     * Hot method.
-     * Cached in-memory for N minutes (currently 10).
+     * Returns all experiments.
      */
-    async getActiveExperiments() {
-        const experiments = await this.experimentDao
-            .query()
-            .filter('status', '!=', types_1.AssignmentStatus.Inactive)
-            .runQuery();
-        const buckets = await this.bucketDao
-            .query()
-            .filter('experimentId', 'in', experiments.map(e => e.id))
-            .runQuery();
+    async getAllExperimentsNoCache() {
+        const experiments = await this.experimentDao.getAll();
+        const buckets = await this.bucketDao.getAll();
         return experiments.map(experiment => ({
             ...experiment,
             buckets: buckets.filter(bucket => bucket.experimentId === experiment.id),
@@ -61,10 +46,12 @@ class Abba {
         if (experiment.status === types_1.AssignmentStatus.Active) {
             (0, util_1.validateTotalBucketRatio)(buckets);
         }
-        await this.experimentDao.save(experiment);
+        const created = await this.experimentDao.save(experiment);
+        const createdbuckets = await this.bucketDao.saveBatch(buckets.map(b => ({ ...b, experimentId: experiment.id })));
+        await this.updateExclusions(created.id, created.exclusions);
         return {
-            ...experiment,
-            buckets: await this.bucketDao.saveBatch(buckets.map(b => ({ ...b, experimentId: experiment.id }))),
+            ...created,
+            buckets: createdbuckets,
         };
     }
     /**
@@ -75,18 +62,43 @@ class Abba {
         if (experiment.status === types_1.AssignmentStatus.Active) {
             (0, util_1.validateTotalBucketRatio)(buckets);
         }
-        await this.experimentDao.save(experiment);
+        const updatedExperiment = await this.experimentDao.save(experiment);
+        const updatedBuckets = await this.bucketDao.saveBatch(buckets.map(b => ({ ...b, experimentId: experiment.id })));
+        await this.updateExclusions(updatedExperiment.id, updatedExperiment.exclusions);
         return {
-            ...experiment,
-            buckets: await this.bucketDao.saveBatch(buckets.map(b => ({ ...b, experimentId: experiment.id }))),
+            ...updatedExperiment,
+            buckets: updatedBuckets,
         };
     }
+    /**
+     * Ensures that mutual exclusions are maintained
+     */
+    async updateExclusions(experimentId, updatedExclusions) {
+        const experiments = await this.experimentDao.getAll();
+        const requiresUpdating = [];
+        experiments.map(experiment => {
+            // Make sure it's mutual
+            if (updatedExclusions.includes(experiment.id) &&
+                !experiment.exclusions.includes(experimentId)) {
+                experiment.exclusions.push(experimentId);
+                requiresUpdating.push(experiment);
+            }
+            // Make sure it's mutual
+            if (!updatedExclusions.includes(experiment.id) &&
+                experiment.exclusions.includes(experimentId)) {
+                experiment.exclusions = experiment.exclusions.filter(id => id !== experimentId);
+                requiresUpdating.push(experiment);
+            }
+        });
+        await this.experimentDao.saveBatch(requiresUpdating);
+    }
     /**
      * Delete an experiment. Removes all user assignments and buckets.
      * Cold method.
      */
-    async deleteExperiment(id) {
-        await this.experimentDao.deleteById(id);
+    async deleteExperiment(experimentId) {
+        await this.experimentDao.deleteById(experimentId);
+        await this.updateExclusions(experimentId, []);
     }
     /**
      * Get an assignment for a given user. If existingOnly is false, it will attempt to generate a new assignment
@@ -98,7 +110,8 @@ class Abba {
      * @param segmentationData Required if existingOnly is false
      */
     async getUserAssignment(experimentId, userId, existingOnly, segmentationData) {
-        const existing = await this.getExistingUserAssignment(experimentId, userId);
+        const existingAssignments = await this.getAllExistingUserAssignments(userId);
+        const existing = existingAssignments.find(a => a.experimentId === experimentId);
         if (existing) {
             let bucketKey = null;
             if (existing.bucketId) {
@@ -109,18 +122,20 @@ class Abba {
         }
         if (existingOnly)
             return null;
-        const experiment = await this.experimentDao.requireById(experimentId);
-        if (!(0, util_1.canGenerateNewAssignments)(experiment))
+        const experiments = await this.getAllExperiments();
+        const experiment = experiments.find(e => e.id === experimentId);
+        (0, js_lib_1._assert)(experiment, `Experiment does not exist: ${experimentId}`);
+        const exclusionSet = (0, util_1.getUserExclusionSet)(experiments, existingAssignments);
+        if (!(0, util_1.canGenerateNewAssignments)(experiment, exclusionSet))
             return null;
         (0, js_lib_1._assert)(segmentationData, 'Segmentation data required when creating a new assignment');
-        const buckets = await this.bucketDao.getBy('experimentId', experimentId);
-        const assignment = this.generateUserAssignmentData({ ...experiment, buckets }, userId, segmentationData);
+        const assignment = (0, util_1.generateUserAssignmentData)(experiment, userId, segmentationData);
         if (!assignment)
             return null;
         const saved = await this.userAssignmentDao.save(assignment);
         return {
             ...saved,
-            bucketKey: buckets.find(b => b.id === saved.bucketId)?.key || null,
+            bucketKey: experiment.buckets.find(b => b.id === saved.bucketId)?.key || null,
         };
     }
     /**
@@ -137,11 +152,16 @@ class Abba {
      * Hot method.
      */
     async generateUserAssignments(userId, segmentationData, existingOnly = false) {
-        const experiments = await this.getActiveExperiments(); // cached
+        const experiments = await this.getAllExperiments();
+        const existingAssignments = await this.getAllExistingUserAssignments(userId);
+        const exclusionSet = (0, util_1.getUserExclusionSet)(experiments, existingAssignments);
         const assignments = [];
         const newAssignments = [];
-        const existingAssignments = await this.getAllExistingUserAssignments(userId);
-        for (const experiment of experiments) {
+        // Shuffling means that randomisation occurs in the mutual exclusion
+        // as experiments are looped through sequentially, this removes the risk of the same experiment always being assigned first in the list of mutually exclusive experiments
+        // This is simmpler than trying to resolve after assignments have already been determined
+        const availableExperiments = (0, js_lib_1._shuffle)(experiments.filter(e => e.status === types_1.AssignmentStatus.Active || e.status === types_1.AssignmentStatus.Paused));
+        for (const experiment of availableExperiments) {
             const existing = existingAssignments.find(ua => ua.experimentId === experiment.id);
             if (existing) {
                 assignments.push({
@@ -149,8 +169,8 @@ class Abba {
                     bucketKey: experiment.buckets.find(b => b.id === existing.bucketId)?.key || null,
                 });
             }
-            else if (!existingOnly && (0, util_1.canGenerateNewAssignments)(experiment)) {
-                const assignment = this.generateUserAssignmentData(experiment, userId, segmentationData);
+            else if (!existingOnly && (0, util_1.canGenerateNewAssignments)(experiment, exclusionSet)) {
+                const assignment = (0, util_1.generateUserAssignmentData)(experiment, userId, segmentationData);
                 if (assignment) {
                     const created = this.userAssignmentDao.create(assignment);
                     newAssignments.push(created);
@@ -158,6 +178,8 @@ class Abba {
                         ...created,
                         bucketKey: experiment.buckets.find(b => b.id === created.bucketId)?.key || null,
                     });
+                    // Prevent future exclusion clashes
+                    experiment.exclusions.forEach(experimentId => exclusionSet.add(experimentId));
                 }
             }
         }
@@ -185,34 +207,8 @@ class Abba {
         });
         return statistics;
     }
-    /**
-     * Generate a new assignment for a given user.
-     * Doesn't save it.
-     */
-    generateUserAssignmentData(experiment, userId, segmentationData) {
-        const segmentationMatch = (0, util_1.validateSegmentationRules)(experiment.rules, segmentationData);
-        if (!segmentationMatch)
-            return null;
-        const bucket = (0, util_1.determineAssignment)(experiment.sampling, experiment.buckets);
-        return {
-            userId,
-            experimentId: experiment.id,
-            bucketId: bucket?.id || null,
-        };
-    }
-    /**
-     * Queries to retrieve an existing user assignment for a given experiment
-     */
-    async getExistingUserAssignment(experimentId, userId) {
-        const [assignment] = await this.userAssignmentDao
-            .query()
-            .filterEq('userId', userId)
-            .filterEq('experimentId', experimentId)
-            .runQuery();
-        return assignment || null;
-    }
 }
 tslib_1.__decorate([
     (0, js_lib_1._AsyncMemo)({ cacheFactory: () => new nodejs_lib_1.LRUMemoCache({ ttl: CACHE_TTL, max: 1 }) })
-], Abba.prototype, "getActiveExperiments", null);
+], Abba.prototype, "getAllExperiments", null);
 exports.Abba = Abba;

package/dist/dao/experiment.dao.d.ts

@@ -3,6 +3,7 @@ import { Saved } from '@naturalcycles/js-lib';
 import { BaseExperiment, Experiment } from '../types';
 type ExperimentDBM = Saved<BaseExperiment> & {
     rules: string | null;
+    exclusions: string | null;
 };
 export declare class ExperimentDao extends CommonDao<Experiment, ExperimentDBM> {
 }

package/dist/dao/experiment.dao.js

@@ -12,8 +12,16 @@ const experimentDao = (db) => new ExperimentDao({
     idType: 'number',
     assignGeneratedIds: true,
     hooks: {
-        beforeBMToDBM: bm => ({ ...bm, rules: bm.rules.length ? JSON.stringify(bm.rules) : null }),
-        beforeDBMToBM: dbm => ({ ...dbm, rules: (dbm.rules && JSON.parse(dbm.rules)) || [] }),
+        beforeBMToDBM: bm => ({
+            ...bm,
+            rules: bm.rules.length ? JSON.stringify(bm.rules) : null,
+            exclusions: bm.exclusions.length ? JSON.stringify(bm.exclusions) : null,
+        }),
+        beforeDBMToBM: dbm => ({
+            ...dbm,
+            rules: (dbm.rules && JSON.parse(dbm.rules)) || [],
+            exclusions: (dbm.exclusions && JSON.parse(dbm.exclusions)) || [],
+        }),
     },
 });
 exports.experimentDao = experimentDao;

package/dist/migrations/init.sql

@@ -21,6 +21,7 @@ CREATE TABLE IF NOT EXISTS `Experiment` (
     `created` INTEGER(11) NOT NULL,
     `updated` INTEGER(11) NOT NULL,
     `rules` JSON NULL,
+    `exclusions` JSON NULL,
 
     PRIMARY KEY (`id`)
 ) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import { CommonDB } from '@naturalcycles/db-lib';
-import { BaseDBEntity, Saved } from '@naturalcycles/js-lib';
+import { AnyObject, BaseDBEntity, Saved } from '@naturalcycles/js-lib';
 export interface AbbaConfig {
     db: CommonDB;
 }
@@ -13,6 +13,7 @@ export type BaseExperiment = BaseDBEntity<number> & {
 };
 export type Experiment = BaseExperiment & {
     rules: SegmentationRule[];
+    exclusions: number[];
 };
 export type ExperimentWithBuckets = Saved<Experiment> & {
     buckets: Saved<Bucket>[];
@@ -22,11 +23,7 @@ export interface BucketInput {
     key: string;
     ratio: number;
 }
-export type Bucket = BaseDBEntity<number> & {
-    experimentId: number;
-    key: string;
-    ratio: number;
-};
+export type Bucket = BaseDBEntity<number> & BucketInput;
 export type UserAssignment = BaseDBEntity<number> & {
     userId: string;
     experimentId: number;
@@ -35,7 +32,7 @@ export type UserAssignment = BaseDBEntity<number> & {
 export type GeneratedUserAssignment = Saved<UserAssignment> & {
     bucketKey: string | null;
 };
-export type SegmentationData = Record<string, string | boolean | number>;
+export type SegmentationData = AnyObject;
 export declare enum AssignmentStatus {
     /**
      * Will return existing assignments and generate new assignments
@@ -61,3 +58,4 @@ export interface AssignmentStatistics {
         [id: string]: number;
     };
 }
+export type ExclusionSet = Set<number>;

package/dist/util.d.ts

@@ -1,5 +1,10 @@
 import { Saved } from '@naturalcycles/js-lib';
-import { Bucket, Experiment, SegmentationData, SegmentationRule } from './types';
+import { Bucket, ExclusionSet, Experiment, ExperimentWithBuckets, SegmentationData, SegmentationRule, UserAssignment } from './types';
+/**
+ * Generate a new assignment for a given user.
+ * Doesn't save it.
+ */
+export declare const generateUserAssignmentData: (experiment: ExperimentWithBuckets, userId: string, segmentationData: SegmentationData) => UserAssignment | null;
 /**
  * Generate a random number between 0 and 100
  */
@@ -31,4 +36,9 @@ export declare const validateSegmentationRule: (rule: SegmentationRule, data: Se
 /**
  * Returns true if an experiment is able to generate new assignments based on status and start/end dates
  */
-export declare const canGenerateNewAssignments: (experiment: Experiment) => boolean;
+export declare const canGenerateNewAssignments: (experiment: Experiment, exclusionSet: ExclusionSet) => boolean;
+/**
+ * Returns an object that includes keys of all experimentIds a user should not be assigned to
+ * based on a combination of existing assignments and mutual exclusion configuration
+ */
+export declare const getUserExclusionSet: (experiments: Experiment[], existingAssignments: UserAssignment[]) => ExclusionSet;

package/dist/util.js

@@ -1,9 +1,25 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.canGenerateNewAssignments = exports.validateSegmentationRule = exports.validateSegmentationRules = exports.validateTotalBucketRatio = exports.determineBucket = exports.determineAssignment = exports.rollDie = void 0;
+exports.getUserExclusionSet = exports.canGenerateNewAssignments = exports.validateSegmentationRule = exports.validateSegmentationRules = exports.validateTotalBucketRatio = exports.determineBucket = exports.determineAssignment = exports.rollDie = exports.generateUserAssignmentData = void 0;
 const js_lib_1 = require("@naturalcycles/js-lib");
 const semver_1 = require("semver");
 const types_1 = require("./types");
+/**
+ * Generate a new assignment for a given user.
+ * Doesn't save it.
+ */
+const generateUserAssignmentData = (experiment, userId, segmentationData) => {
+    const segmentationMatch = (0, exports.validateSegmentationRules)(experiment.rules, segmentationData);
+    if (!segmentationMatch)
+        return null;
+    const bucket = (0, exports.determineAssignment)(experiment.sampling, experiment.buckets);
+    return {
+        userId,
+        experimentId: experiment.id,
+        bucketId: bucket?.id || null,
+    };
+};
+exports.generateUserAssignmentData = generateUserAssignmentData;
 /**
  * Generate a random number between 0 and 100
  */
@@ -97,8 +113,22 @@ exports.validateSegmentationRule = validateSegmentationRule;
 /**
  * Returns true if an experiment is able to generate new assignments based on status and start/end dates
  */
-const canGenerateNewAssignments = (experiment) => {
-    return (experiment.status === types_1.AssignmentStatus.Active &&
+const canGenerateNewAssignments = (experiment, exclusionSet) => {
+    return (!exclusionSet.has(experiment.id) &&
+        experiment.status === types_1.AssignmentStatus.Active &&
         (0, js_lib_1.localDate)().isBetween((0, js_lib_1.localDate)(experiment.startDateIncl.toISOString()), (0, js_lib_1.localDate)(experiment.endDateExcl.toISOString()), '[)'));
 };
 exports.canGenerateNewAssignments = canGenerateNewAssignments;
+/**
+ * Returns an object that includes keys of all experimentIds a user should not be assigned to
+ * based on a combination of existing assignments and mutual exclusion configuration
+ */
+const getUserExclusionSet = (experiments, existingAssignments) => {
+    const exclusionSet = new Set();
+    existingAssignments.forEach(assignment => {
+        const experiment = experiments.find(e => e.id === assignment.experimentId);
+        experiment?.exclusions.forEach(experimentId => exclusionSet.add(experimentId));
+    });
+    return exclusionSet;
+};
+exports.getUserExclusionSet = getUserExclusionSet;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/abba",
-  "version": "1.13.1",
+  "version": "1.14.0",
   "scripts": {
     "prepare": "husky install",
     "build": "build",

package/readme.md

@@ -27,6 +27,7 @@
     </li>
     <li><a href="#usage">Usage</a></li>
     <li><a href="#segmentation">Segmentation</a></li>
+    <li><a href="#exclusion">Mutual Exclusion</a></li>
   </ol>
 </details>
 
@@ -41,6 +42,8 @@
 - **Bucket:** An allocation that defines what variant of a particular experience the user will have
 - **Start/End dates:** The timeframe that assignments will be generated for this experiment when
   active
+- **Mutual Exclusion:**
+  [See here](https://docs.developers.optimizely.com/full-stack-experimentation/docs/mutually-exclusive-experiments)
 
 <!-- BUILTWITH -->
 
@@ -287,3 +290,13 @@ Example segmentation data:
 ```
 
 <p align="right">(<a href="#top">back to top</a>)</p>
+
+<div id="exclusion"></div>
+
+## Mutual Excluusion
+
+Mutual exclusion is configured per-experiment. If an experiment is listed as mutually exclusive with
+another experiment(s) then new assignments will only be generated with one of the experiments and
+will never be created for the other(s)
+
+<p align="right">(<a href="#top">back to top</a>)</p>

package/src/abba.ts

@@ -1,4 +1,4 @@
-import { _assert, _AsyncMemo, pMap, Saved } from '@naturalcycles/js-lib'
+import { _assert, _AsyncMemo, _shuffle, pMap, Saved } from '@naturalcycles/js-lib'
 import { LRUMemoCache } from '@naturalcycles/nodejs-lib'
 import {
   AbbaConfig,
@@ -12,72 +12,42 @@ import {
 } from './types'
 import {
   canGenerateNewAssignments,
-  determineAssignment,
-  validateSegmentationRules,
+  generateUserAssignmentData,
+  getUserExclusionSet,
   validateTotalBucketRatio,
 } from './util'
-import { ExperimentDao, experimentDao } from './dao/experiment.dao'
-import { UserAssignmentDao, userAssignmentDao } from './dao/userAssignment.dao'
-import { BucketDao, bucketDao } from './dao/bucket.dao'
+import { experimentDao } from './dao/experiment.dao'
+import { userAssignmentDao } from './dao/userAssignment.dao'
+import { bucketDao } from './dao/bucket.dao'
 import { SegmentationData, AssignmentStatistics } from '.'
 
+/**
+ * 10 minutes
+ */
 const CACHE_TTL = 600_000 // 10 minutes
 
 export class Abba {
-  constructor(public cfg: AbbaConfig) {
-    const { db } = cfg
-    this.experimentDao = experimentDao(db)
-    this.bucketDao = bucketDao(db)
-    this.userAssignmentDao = userAssignmentDao(db)
-  }
+  private experimentDao = experimentDao(this.cfg.db)
+  private bucketDao = bucketDao(this.cfg.db)
+  private userAssignmentDao = userAssignmentDao(this.cfg.db)
 
-  private experimentDao: ExperimentDao
-  private bucketDao: BucketDao
-  private userAssignmentDao: UserAssignmentDao
+  constructor(public cfg: AbbaConfig) {}
 
   /**
-   * Returns all (active and inactive) experiments.
-   *
-   * Cold method, not cached.
+   * Returns all experiments.
+   * Cached (see CACHE_TTL)
    */
+  @_AsyncMemo({ cacheFactory: () => new LRUMemoCache({ ttl: CACHE_TTL, max: 1 }) })
   async getAllExperiments(): Promise<ExperimentWithBuckets[]> {
-    const experiments = await this.experimentDao.query().runQuery()
-
-    const buckets = await this.bucketDao
-      .query()
-      .filter(
-        'experimentId',
-        'in',
-        experiments.map(e => e.id),
-      )
-      .runQuery()
-
-    return experiments.map(experiment => ({
-      ...experiment,
-      buckets: buckets.filter(bucket => bucket.experimentId === experiment.id),
-    }))
+    return await this.getAllExperimentsNoCache()
   }
 
   /**
-   * Returns only active experiments.
-   * Hot method.
-   * Cached in-memory for N minutes (currently 10).
+   * Returns all experiments.
    */
-  @_AsyncMemo({ cacheFactory: () => new LRUMemoCache({ ttl: CACHE_TTL, max: 1 }) })
-  async getActiveExperiments(): Promise<ExperimentWithBuckets[]> {
-    const experiments = await this.experimentDao
-      .query()
-      .filter('status', '!=', AssignmentStatus.Inactive)
-      .runQuery()
-
-    const buckets = await this.bucketDao
-      .query()
-      .filter(
-        'experimentId',
-        'in',
-        experiments.map(e => e.id),
-      )
-      .runQuery()
+  async getAllExperimentsNoCache(): Promise<ExperimentWithBuckets[]> {
+    const experiments = await this.experimentDao.getAll()
+    const buckets = await this.bucketDao.getAll()
 
     return experiments.map(experiment => ({
       ...experiment,
@@ -97,13 +67,16 @@ export class Abba {
       validateTotalBucketRatio(buckets)
     }
 
-    await this.experimentDao.save(experiment)
+    const created = await this.experimentDao.save(experiment)
+    const createdbuckets = await this.bucketDao.saveBatch(
+      buckets.map(b => ({ ...b, experimentId: experiment.id })),
+    )
+
+    await this.updateExclusions(created.id, created.exclusions)
 
     return {
-      ...(experiment as Saved<Experiment>),
-      buckets: await this.bucketDao.saveBatch(
-        buckets.map(b => ({ ...b, experimentId: experiment.id })),
-      ),
+      ...created,
+      buckets: createdbuckets,
     }
   }
 
@@ -119,22 +92,56 @@ export class Abba {
       validateTotalBucketRatio(buckets)
     }
 
-    await this.experimentDao.save(experiment)
+    const updatedExperiment = await this.experimentDao.save(experiment)
+    const updatedBuckets = await this.bucketDao.saveBatch(
+      buckets.map(b => ({ ...b, experimentId: experiment.id })),
+    )
+
+    await this.updateExclusions(updatedExperiment.id, updatedExperiment.exclusions)
 
     return {
-      ...(experiment as Saved<Experiment>),
-      buckets: await this.bucketDao.saveBatch(
-        buckets.map(b => ({ ...b, experimentId: experiment.id })),
-      ),
+      ...updatedExperiment,
+      buckets: updatedBuckets,
     }
   }
 
+  /**
+   * Ensures that mutual exclusions are maintained
+   */
+  private async updateExclusions(experimentId: number, updatedExclusions: number[]): Promise<void> {
+    const experiments = await this.experimentDao.getAll()
+
+    const requiresUpdating: Experiment[] = []
+    experiments.map(experiment => {
+      // Make sure it's mutual
+      if (
+        updatedExclusions.includes(experiment.id) &&
+        !experiment.exclusions.includes(experimentId)
+      ) {
+        experiment.exclusions.push(experimentId)
+        requiresUpdating.push(experiment)
+      }
+
+      // Make sure it's mutual
+      if (
+        !updatedExclusions.includes(experiment.id) &&
+        experiment.exclusions.includes(experimentId)
+      ) {
+        experiment.exclusions = experiment.exclusions.filter(id => id !== experimentId)
+        requiresUpdating.push(experiment)
+      }
+    })
+
+    await this.experimentDao.saveBatch(requiresUpdating)
+  }
+
   /**
    * Delete an experiment. Removes all user assignments and buckets.
    * Cold method.
    */
-  async deleteExperiment(id: number): Promise<void> {
-    await this.experimentDao.deleteById(id)
+  async deleteExperiment(experimentId: number): Promise<void> {
+    await this.experimentDao.deleteById(experimentId)
+    await this.updateExclusions(experimentId, [])
   }
 
   /**
@@ -152,8 +159,9 @@ export class Abba {
     existingOnly: boolean,
     segmentationData?: SegmentationData,
   ): Promise<GeneratedUserAssignment | null> {
-    const existing = await this.getExistingUserAssignment(experimentId, userId)
+    const existingAssignments = await this.getAllExistingUserAssignments(userId)
 
+    const existing = existingAssignments.find(a => a.experimentId === experimentId)
     if (existing) {
       let bucketKey = null
       if (existing.bucketId) {
@@ -165,25 +173,23 @@ export class Abba {
 
     if (existingOnly) return null
 
-    const experiment = await this.experimentDao.requireById(experimentId)
-    if (!canGenerateNewAssignments(experiment)) return null
+    const experiments = await this.getAllExperiments()
+    const experiment = experiments.find(e => e.id === experimentId)
+    _assert(experiment, `Experiment does not exist: ${experimentId}`)
 
-    _assert(segmentationData, 'Segmentation data required when creating a new assignment')
+    const exclusionSet = getUserExclusionSet(experiments, existingAssignments)
+    if (!canGenerateNewAssignments(experiment, exclusionSet)) return null
 
-    const buckets = await this.bucketDao.getBy('experimentId', experimentId)
+    _assert(segmentationData, 'Segmentation data required when creating a new assignment')
 
-    const assignment = this.generateUserAssignmentData(
-      { ...experiment, buckets },
-      userId,
-      segmentationData,
-    )
+    const assignment = generateUserAssignmentData(experiment, userId, segmentationData)
     if (!assignment) return null
 
     const saved = await this.userAssignmentDao.save(assignment)
 
     return {
       ...saved,
-      bucketKey: buckets.find(b => b.id === saved.bucketId)?.key || null,
+      bucketKey: experiment.buckets.find(b => b.id === saved.bucketId)?.key || null,
     }
   }
 
@@ -206,21 +212,31 @@ export class Abba {
     segmentationData: SegmentationData,
     existingOnly = false,
   ): Promise<GeneratedUserAssignment[]> {
-    const experiments = await this.getActiveExperiments() // cached
+    const experiments = await this.getAllExperiments()
+    const existingAssignments = await this.getAllExistingUserAssignments(userId)
+    const exclusionSet = getUserExclusionSet(experiments, existingAssignments)
 
     const assignments: GeneratedUserAssignment[] = []
     const newAssignments: UserAssignment[] = []
-    const existingAssignments = await this.getAllExistingUserAssignments(userId)
 
-    for (const experiment of experiments) {
+    // Shuffling means that randomisation occurs in the mutual exclusion
+    // as experiments are looped through sequentially, this removes the risk of the same experiment always being assigned first in the list of mutually exclusive experiments
+    // This is simmpler than trying to resolve after assignments have already been determined
+    const availableExperiments = _shuffle(
+      experiments.filter(
+        e => e.status === AssignmentStatus.Active || e.status === AssignmentStatus.Paused,
+      ),
+    )
+
+    for (const experiment of availableExperiments) {
       const existing = existingAssignments.find(ua => ua.experimentId === experiment.id)
       if (existing) {
         assignments.push({
           ...existing,
           bucketKey: experiment.buckets.find(b => b.id === existing.bucketId)?.key || null,
         })
-      } else if (!existingOnly && canGenerateNewAssignments(experiment)) {
-        const assignment = this.generateUserAssignmentData(experiment, userId, segmentationData)
+      } else if (!existingOnly && canGenerateNewAssignments(experiment, exclusionSet)) {
+        const assignment = generateUserAssignmentData(experiment, userId, segmentationData)
         if (assignment) {
           const created = this.userAssignmentDao.create(assignment)
           newAssignments.push(created)
@@ -228,6 +244,8 @@ export class Abba {
             ...created,
             bucketKey: experiment.buckets.find(b => b.id === created.bucketId)?.key || null,
           })
+          // Prevent future exclusion clashes
+          experiment.exclusions.forEach(experimentId => exclusionSet.add(experimentId))
         }
       }
     }
@@ -259,41 +277,4 @@ export class Abba {
 
     return statistics
   }
-
-  /**
-   * Generate a new assignment for a given user.
-   * Doesn't save it.
-   */
-  private generateUserAssignmentData(
-    experiment: ExperimentWithBuckets,
-    userId: string,
-    segmentationData: SegmentationData,
-  ): UserAssignment | null {
-    const segmentationMatch = validateSegmentationRules(experiment.rules, segmentationData)
-    if (!segmentationMatch) return null
-
-    const bucket = determineAssignment(experiment.sampling, experiment.buckets)
-
-    return {
-      userId,
-      experimentId: experiment.id,
-      bucketId: bucket?.id || null,
-    }
-  }
-
-  /**
-   * Queries to retrieve an existing user assignment for a given experiment
-   */
-  private async getExistingUserAssignment(
-    experimentId: number,
-    userId: string,
-  ): Promise<Saved<UserAssignment> | null> {
-    const [assignment] = await this.userAssignmentDao
-      .query()
-      .filterEq('userId', userId)
-      .filterEq('experimentId', experimentId)
-      .runQuery()
-
-    return assignment || null
-  }
 }

package/src/dao/experiment.dao.ts

@@ -4,6 +4,7 @@ import { BaseExperiment, Experiment } from '../types'
 
 type ExperimentDBM = Saved<BaseExperiment> & {
   rules: string | null
+  exclusions: string | null
 }
 
 export class ExperimentDao extends CommonDao<Experiment, ExperimentDBM> {}
@@ -16,7 +17,15 @@ export const experimentDao = (db: CommonDB): ExperimentDao =>
     idType: 'number',
     assignGeneratedIds: true,
     hooks: {
-      beforeBMToDBM: bm => ({ ...bm, rules: bm.rules.length ? JSON.stringify(bm.rules) : null }),
-      beforeDBMToBM: dbm => ({ ...dbm, rules: (dbm.rules && JSON.parse(dbm.rules)) || [] }),
+      beforeBMToDBM: bm => ({
+        ...bm,
+        rules: bm.rules.length ? JSON.stringify(bm.rules) : null,
+        exclusions: bm.exclusions.length ? JSON.stringify(bm.exclusions) : null,
+      }),
+      beforeDBMToBM: dbm => ({
+        ...dbm,
+        rules: (dbm.rules && JSON.parse(dbm.rules)) || [],
+        exclusions: (dbm.exclusions && JSON.parse(dbm.exclusions)) || [],
+      }),
     },
   })

package/src/migrations/init.sql

@@ -21,6 +21,7 @@ CREATE TABLE IF NOT EXISTS `Experiment` (
     `created` INTEGER(11) NOT NULL,
     `updated` INTEGER(11) NOT NULL,
     `rules` JSON NULL,
+    `exclusions` JSON NULL,
 
     PRIMARY KEY (`id`)
 ) DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

package/src/types.ts

@@ -1,16 +1,8 @@
 import { CommonDB } from '@naturalcycles/db-lib'
-import { BaseDBEntity, Saved } from '@naturalcycles/js-lib'
+import { AnyObject, BaseDBEntity, Saved } from '@naturalcycles/js-lib'
 
 export interface AbbaConfig {
   db: CommonDB
-
-  /**
-   * Determines for how long to cache "hot" requests.
-   * Caches in memory.
-   * Default is 10.
-   * Set to 0 to disable cache (every request will hit the DB).
-   */
-  // cacheMinutes?: number
 }
 
 export type BaseExperiment = BaseDBEntity<number> & {
@@ -24,6 +16,7 @@ export type BaseExperiment = BaseDBEntity<number> & {
 
 export type Experiment = BaseExperiment & {
   rules: SegmentationRule[]
+  exclusions: number[]
 }
 
 export type ExperimentWithBuckets = Saved<Experiment> & {
@@ -36,11 +29,7 @@ export interface BucketInput {
   ratio: number
 }
 
-export type Bucket = BaseDBEntity<number> & {
-  experimentId: number
-  key: string
-  ratio: number
-}
+export type Bucket = BaseDBEntity<number> & BucketInput
 
 export type UserAssignment = BaseDBEntity<number> & {
   userId: string
@@ -52,7 +41,7 @@ export type GeneratedUserAssignment = Saved<UserAssignment> & {
   bucketKey: string | null
 }
 
-export type SegmentationData = Record<string, string | boolean | number>
+export type SegmentationData = AnyObject
 
 export enum AssignmentStatus {
   /**
@@ -81,3 +70,5 @@ export interface AssignmentStatistics {
     [id: string]: number
   }
 }
+
+export type ExclusionSet = Set<number>

package/src/util.ts

@@ -1,6 +1,36 @@
 import { localDate, Saved } from '@naturalcycles/js-lib'
 import { satisfies } from 'semver'
-import { AssignmentStatus, Bucket, Experiment, SegmentationData, SegmentationRule } from './types'
+import {
+  AssignmentStatus,
+  Bucket,
+  ExclusionSet,
+  Experiment,
+  ExperimentWithBuckets,
+  SegmentationData,
+  SegmentationRule,
+  UserAssignment,
+} from './types'
+
+/**
+ * Generate a new assignment for a given user.
+ * Doesn't save it.
+ */
+export const generateUserAssignmentData = (
+  experiment: ExperimentWithBuckets,
+  userId: string,
+  segmentationData: SegmentationData,
+): UserAssignment | null => {
+  const segmentationMatch = validateSegmentationRules(experiment.rules, segmentationData)
+  if (!segmentationMatch) return null
+
+  const bucket = determineAssignment(experiment.sampling, experiment.buckets)
+
+  return {
+    userId,
+    experimentId: experiment.id,
+    bucketId: bucket?.id || null,
+  }
+}
 
 /**
  * Generate a random number between 0 and 100
@@ -99,8 +129,12 @@ export const validateSegmentationRule = (
 /**
  * Returns true if an experiment is able to generate new assignments based on status and start/end dates
  */
-export const canGenerateNewAssignments = (experiment: Experiment): boolean => {
+export const canGenerateNewAssignments = (
+  experiment: Experiment,
+  exclusionSet: ExclusionSet,
+): boolean => {
   return (
+    !exclusionSet.has(experiment.id) &&
     experiment.status === AssignmentStatus.Active &&
     localDate().isBetween(
       localDate(experiment.startDateIncl.toISOString()),
@@ -109,3 +143,19 @@ export const canGenerateNewAssignments = (experiment: Experiment): boolean => {
     )
   )
 }
+
+/**
+ * Returns an object that includes keys of all experimentIds a user should not be assigned to
+ * based on a combination of existing assignments and mutual exclusion configuration
+ */
+export const getUserExclusionSet = (
+  experiments: Experiment[],
+  existingAssignments: UserAssignment[],
+): ExclusionSet => {
+  const exclusionSet: ExclusionSet = new Set()
+  existingAssignments.forEach(assignment => {
+    const experiment = experiments.find(e => e.id === assignment.experimentId)
+    experiment?.exclusions.forEach(experimentId => exclusionSet.add(experimentId))
+  })
+  return exclusionSet
+}