@naturalcycles/abba 1.9.0 → 1.10.0

package/dist/abba.d.ts

@@ -1,88 +1,75 @@
 import { Saved } from '@naturalcycles/js-lib';
-import { AbbaConfig, Bucket, Experiment, ExperimentWithBuckets, UserAssignment } from './types';
+import { AbbaConfig, Bucket, BucketInput, Experiment, ExperimentWithBuckets, GeneratedUserAssignment, UserAssignment } from './types';
 import { SegmentationData, AssignmentStatistics } from '.';
 export declare class Abba {
+    cfg: AbbaConfig;
+    constructor(cfg: AbbaConfig);
     private experimentDao;
     private bucketDao;
     private userAssignmentDao;
-    constructor({ db }: AbbaConfig);
     /**
-     * Returns all experiments
+     * Returns all (active and inactive) experiments.
      *
-     * @returns
+     * Cold method, not cached.
      */
-    getAllExperiments(excludeInactive?: boolean): Promise<ExperimentWithBuckets[]>;
+    getAllExperiments(): Promise<ExperimentWithBuckets[]>;
     /**
-     * Creates a new experiment
-     *
-     * @param experiment
-     * @param buckets
-     * @returns
+     * Returns only active experiments.
+     * Hot method.
+     * Cached in-memory for N minutes (currently 10).
      */
-    createExperiment(experiment: Experiment, buckets: Bucket[]): Promise<ExperimentWithBuckets>;
+    getActiveExperiments(): Promise<ExperimentWithBuckets[]>;
     /**
-     * Update experiment information, will also validate the buckets ratio if experiment.active is true
-     *
-     * @param id
-     * @param experiment
-     * @param rules
-     * @param buckets
-     * @returns
+     * Creates a new experiment.
+     * Cold method.
      */
-    saveExperiment(id: number, experiment: Experiment, buckets: Bucket[]): Promise<ExperimentWithBuckets>;
+    createExperiment(experiment: Experiment, buckets: BucketInput[]): Promise<ExperimentWithBuckets>;
     /**
-     * Delete an experiment. Removes all user assignments and buckets
-     *
-     * @param id
+     * Update experiment information, will also validate the buckets' ratio if experiment.active is true
+     * Cold method.
+     */
+    saveExperiment(experiment: Experiment & {
+        id: number;
+    }, buckets: Bucket[]): Promise<ExperimentWithBuckets>;
+    /**
+     * Delete an experiment. Removes all user assignments and buckets.
+     * Cold method.
      */
     deleteExperiment(id: number): Promise<void>;
     /**
-     * Get an assignment for a given user. If existingOnly is false, it will attempt generate a new assignment
+     * Get an assignment for a given user. If existingOnly is false, it will attempt to generate a new assignment
+     * Cold method.
      *
      * @param experimentId
      * @param userId
      * @param existingOnly Do not generate any new assignments for this experiment
      * @param segmentationData Required if existingOnly is false
-     * @returns
      */
-    getUserAssignment(experimentId: number, userId: string, existingOnly: boolean, segmentationData?: SegmentationData): Promise<Saved<UserAssignment> | null>;
+    getUserAssignment(experimentId: number, userId: string, existingOnly: boolean, segmentationData?: SegmentationData): Promise<GeneratedUserAssignment | null>;
     /**
-     * Get all existing user assignments
-     *
-     * @param userId
-     * @returns
+     * Get all existing user assignments.
+     * Hot method.
+     * Not cached, because Assignments are fast-changing.
      */
     getAllExistingUserAssignments(userId: string): Promise<Saved<UserAssignment>[]>;
     /**
-     * Generate user assignments for all active experiments. Will return any existing and attempt to generate any new assignments.
-     *
-     * @param userId
-     * @param segmentationData
-     * @returns
+     * Generate user assignments for all active experiments.
+     * Will return any existing and attempt to generate any new assignments.
+     * Hot method.
      */
-    generateUserAssignments(userId: string, segmentationData: SegmentationData): Promise<Saved<UserAssignment>[]>;
+    generateUserAssignments(userId: string, segmentationData: SegmentationData): Promise<GeneratedUserAssignment[]>;
     /**
-     * Get assignment statistics for an experiment
-     *
-     * @param experimentId
-     * @returns
+     * Get assignment statistics for an experiment.
+     * Cold method.
      */
     getExperimentAssignmentStatistics(experimentId: number): Promise<AssignmentStatistics>;
     /**
-     * Generate a new assignment for a given user
-     *
-     * @param experimentId
-     * @param userId
-     * @param segmentationData
-     * @returns
+     * Generate a new assignment for a given user.
+     * Doesn't save it.
      */
-    private generateUserAssignment;
+    private generateUserAssignmentData;
     /**
      * Queries to retrieve an existing user assignment for a given experiment
-     *
-     * @param experimentId
-     * @param userId
-     * @returns
      */
     private getExistingUserAssignment;
 }

package/dist/abba.js

@@ -1,30 +1,30 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Abba = void 0;
+const tslib_1 = require("tslib");
 const js_lib_1 = require("@naturalcycles/js-lib");
+const nodejs_lib_1 = require("@naturalcycles/nodejs-lib");
 const types_1 = require("./types");
 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");
+const CACHE_TTL = 600000; // 10 minutes
 class Abba {
-    constructor({ db }) {
+    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);
     }
-    // TODO: Cache me
     /**
-     * Returns all experiments
+     * Returns all (active and inactive) experiments.
      *
-     * @returns
+     * Cold method, not cached.
      */
-    async getAllExperiments(excludeInactive = false) {
-        const query = this.experimentDao.query();
-        if (excludeInactive) {
-            query.filter('status', '!=', types_1.AssignmentStatus.Inactive);
-        }
-        const experiments = await this.experimentDao.runQuery(query);
+    async getAllExperiments() {
+        const experiments = await this.experimentDao.query().runQuery();
         const buckets = await this.bucketDao
             .query()
             .filter('experimentId', 'in', experiments.map(e => e.id))
@@ -35,115 +35,139 @@ class Abba {
         }));
     }
     /**
-     * Creates a new experiment
-     *
-     * @param experiment
-     * @param buckets
-     * @returns
+     * Returns only active experiments.
+     * Hot method.
+     * Cached in-memory for N minutes (currently 10).
+     */
+    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();
+        return experiments.map(experiment => ({
+            ...experiment,
+            buckets: buckets.filter(bucket => bucket.experimentId === experiment.id),
+        }));
+    }
+    /**
+     * Creates a new experiment.
+     * Cold method.
      */
     async createExperiment(experiment, buckets) {
         if (experiment.status === types_1.AssignmentStatus.Active) {
             (0, util_1.validateTotalBucketRatio)(buckets);
         }
-        const created = await this.experimentDao.save(experiment);
+        await this.experimentDao.save(experiment);
         return {
-            ...created,
-            buckets: await this.bucketDao.saveBatch(buckets.map(b => ({ ...b, experimentId: created.id }))),
+            ...experiment,
+            buckets: await this.bucketDao.saveBatch(buckets.map(b => ({ ...b, experimentId: experiment.id }))),
         };
     }
     /**
-     * Update experiment information, will also validate the buckets ratio if experiment.active is true
-     *
-     * @param id
-     * @param experiment
-     * @param rules
-     * @param buckets
-     * @returns
+     * Update experiment information, will also validate the buckets' ratio if experiment.active is true
+     * Cold method.
      */
-    async saveExperiment(id, experiment, buckets) {
+    async saveExperiment(experiment, buckets) {
         if (experiment.status === types_1.AssignmentStatus.Active) {
             (0, util_1.validateTotalBucketRatio)(buckets);
         }
-        const updated = await this.experimentDao.save({
-            ...experiment,
-            id,
-        });
+        await this.experimentDao.save(experiment);
         return {
-            ...updated,
-            buckets: await this.bucketDao.saveBatch(buckets.map(b => ({ ...b, experimentId: id }))),
+            ...experiment,
+            buckets: await this.bucketDao.saveBatch(buckets.map(b => ({ ...b, experimentId: experiment.id }))),
         };
     }
     /**
-     * Delete an experiment. Removes all user assignments and buckets
-     *
-     * @param id
+     * Delete an experiment. Removes all user assignments and buckets.
+     * Cold method.
      */
     async deleteExperiment(id) {
         await this.experimentDao.deleteById(id);
     }
     /**
-     * Get an assignment for a given user. If existingOnly is false, it will attempt generate a new assignment
+     * Get an assignment for a given user. If existingOnly is false, it will attempt to generate a new assignment
+     * Cold method.
      *
      * @param experimentId
      * @param userId
      * @param existingOnly Do not generate any new assignments for this experiment
      * @param segmentationData Required if existingOnly is false
-     * @returns
      */
     async getUserAssignment(experimentId, userId, existingOnly, segmentationData) {
+        const existing = await this.getExistingUserAssignment(experimentId, userId);
+        if (existing) {
+            const experiment = await this.experimentDao.requireById(experimentId);
+            const bucket = await this.bucketDao.getById(existing.bucketId || undefined);
+            return {
+                ...existing,
+                experimentName: experiment.name,
+                bucketKey: bucket?.key || null,
+            };
+        }
+        if (existingOnly)
+            return null;
         const experiment = await this.experimentDao.requireById(experimentId);
-        if (!experiment)
-            throw new Error('Experiment not found');
+        if (experiment.status !== types_1.AssignmentStatus.Active)
+            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 existing = await this.getExistingUserAssignment(experimentId, userId);
-        if (existing)
-            return existing;
-        if (experiment.status !== types_1.AssignmentStatus.Active || existingOnly)
+        const assignment = this.generateUserAssignmentData({ ...experiment, buckets }, userId, segmentationData);
+        if (!assignment)
             return null;
-        if (!segmentationData)
-            throw new Error('Segmentation data required when creating a new assignment');
-        return await this.generateUserAssignment({ ...experiment, buckets }, userId, segmentationData);
+        const saved = await this.userAssignmentDao.save(assignment);
+        return {
+            ...saved,
+            experimentName: experiment.name,
+            bucketKey: buckets.find(b => b.id === saved.bucketId)?.key || null,
+        };
     }
     /**
-     * Get all existing user assignments
-     *
-     * @param userId
-     * @returns
+     * Get all existing user assignments.
+     * Hot method.
+     * Not cached, because Assignments are fast-changing.
      */
     async getAllExistingUserAssignments(userId) {
         return await this.userAssignmentDao.getBy('userId', userId);
     }
     /**
-     * Generate user assignments for all active experiments. Will return any existing and attempt to generate any new assignments.
-     *
-     * @param userId
-     * @param segmentationData
-     * @returns
+     * Generate user assignments for all active experiments.
+     * Will return any existing and attempt to generate any new assignments.
+     * Hot method.
      */
     async generateUserAssignments(userId, segmentationData) {
-        const experiments = await this.getAllExperiments(true);
+        const experiments = await this.getActiveExperiments(); // cached
         const existingAssignments = await this.getAllExistingUserAssignments(userId);
+        const newAssignments = [];
+        for (const experiment of experiments) {
+            const existing = existingAssignments.find(ua => ua.experimentId === experiment.id);
+            if (!existing) {
+                const assignment = this.generateUserAssignmentData(experiment, userId, segmentationData);
+                if (assignment) {
+                    newAssignments.push(assignment);
+                }
+            }
+        }
+        existingAssignments.push(...(await this.userAssignmentDao.saveBatch(newAssignments)));
         const assignments = [];
-        const generatedAssignments = [];
         for (const experiment of experiments) {
             const existing = existingAssignments.find(ua => ua.experimentId === experiment.id);
             if (existing) {
-                assignments.push(existing);
-                continue;
-            }
-            else {
-                generatedAssignments.push(this.generateUserAssignment(experiment, userId, segmentationData));
+                assignments.push({
+                    ...existing,
+                    experimentName: experiment.name,
+                    bucketKey: experiment.buckets.find(i => i.id === existing.bucketId)?.key || null,
+                });
             }
         }
-        const generated = await Promise.all(generatedAssignments);
-        const filtered = generated.filter((ua) => ua !== null);
-        return [...assignments, ...filtered];
+        return assignments;
     }
     /**
-     * Get assignment statistics for an experiment
-     *
-     * @param experimentId
-     * @returns
+     * Get assignment statistics for an experiment.
+     * Cold method.
      */
     async getExperimentAssignmentStatistics(experimentId) {
         const statistics = {
@@ -155,40 +179,41 @@ class Abba {
         };
         const buckets = await this.bucketDao.getBy('experimentId', experimentId);
         await (0, js_lib_1.pMap)(buckets, async (bucket) => {
-            const count = this.userAssignmentDao.query().filterEq('bucketId', bucket.id);
-            statistics[bucket.id] = await this.userAssignmentDao.runQueryCount(count);
+            statistics.buckets[bucket.id] = await this.userAssignmentDao
+                .query()
+                .filterEq('bucketId', bucket.id)
+                .runQueryCount();
         });
         return statistics;
     }
     /**
-     * Generate a new assignment for a given user
-     *
-     * @param experimentId
-     * @param userId
-     * @param segmentationData
-     * @returns
+     * Generate a new assignment for a given user.
+     * Doesn't save it.
      */
-    async generateUserAssignment(experiment, userId, segmentationData) {
+    generateUserAssignmentData(experiment, userId, segmentationData) {
         const segmentationMatch = (0, util_1.validateSegmentationRules)(experiment.rules, segmentationData);
         if (!segmentationMatch)
             return null;
-        return await this.userAssignmentDao.save({
+        const bucket = (0, util_1.determineAssignment)(experiment.sampling, experiment.buckets);
+        return {
             userId,
             experimentId: experiment.id,
-            bucketId: (0, util_1.determineAssignment)(experiment.sampling, experiment.buckets),
-        });
+            bucketId: bucket?.id || null,
+        };
     }
     /**
      * Queries to retrieve an existing user assignment for a given experiment
-     *
-     * @param experimentId
-     * @param userId
-     * @returns
      */
     async getExistingUserAssignment(experimentId, userId) {
-        const assignments = await this.userAssignmentDao.getBy('userId', userId);
-        const assignment = assignments.find(assignment => assignment.experimentId === experimentId);
+        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);
 exports.Abba = Abba;

package/dist/dao/experiment.dao.js

@@ -13,7 +13,7 @@ const experimentDao = (db) => new ExperimentDao({
     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) }),
+        beforeDBMToBM: dbm => ({ ...dbm, rules: (dbm.rules && JSON.parse(dbm.rules)) || [] }),
     },
 });
 exports.experimentDao = experimentDao;

package/dist/types.d.ts

@@ -30,6 +30,10 @@ export declare type UserAssignment = BaseDBEntity<number> & {
     experimentId: number;
     bucketId: number | null;
 };
+export declare type GeneratedUserAssignment = Saved<UserAssignment> & {
+    experimentName: string;
+    bucketKey: string | null;
+};
 export declare type SegmentationData = Record<string, string | boolean | number>;
 export declare enum AssignmentStatus {
     Active = 1,

package/dist/util.d.ts

@@ -2,30 +2,18 @@ import { Saved } from '@naturalcycles/js-lib';
 import { Bucket, SegmentationData, SegmentationRule } from './types';
 /**
  * Generate a random number between 0 and 100
- *
- * @returns
  */
 export declare const rollDie: () => number;
 /**
  * Determines a users assignment for this experiment. Returns null if they are not considered to be in the sampling group
- *
- * @param sampling
- * @param buckets
- * @returns
  */
-export declare const determineAssignment: (sampling: number, buckets: Saved<Bucket>[]) => number | null;
+export declare const determineAssignment: (sampling: number, buckets: Saved<Bucket>[]) => Bucket | null;
 /**
  * Determines which bucket a user assignment will recieve
- *
- * @param buckets
- * @returns
  */
-export declare const determineBucket: (buckets: Saved<Bucket>[]) => number;
+export declare const determineBucket: (buckets: Saved<Bucket>[]) => Bucket;
 /**
  * Validate the total ratio of the buckets equals 100
- *
- * @param buckets
- * @returns
  */
 export declare const validateTotalBucketRatio: (buckets: Bucket[]) => void;
 /**
@@ -38,9 +26,5 @@ export declare const validateTotalBucketRatio: (buckets: Bucket[]) => void;
 export declare const validateSegmentationRules: (rules: SegmentationRule[], segmentationData: SegmentationData) => boolean;
 /**
  * Validate a users segmentation data against a single rule
- *
- * @param rule
- * @param segmentationData
- * @returns
  */
 export declare const validateSegmentationRule: (rule: SegmentationRule, data: SegmentationData) => boolean;

package/dist/util.js

@@ -4,8 +4,6 @@ exports.validateSegmentationRule = exports.validateSegmentationRules = exports.v
 const semver_1 = require("semver");
 /**
  * Generate a random number between 0 and 100
- *
- * @returns
  */
 const rollDie = () => {
     return Math.random() * 100;
@@ -13,10 +11,6 @@ const rollDie = () => {
 exports.rollDie = rollDie;
 /**
  * Determines a users assignment for this experiment. Returns null if they are not considered to be in the sampling group
- *
- * @param sampling
- * @param buckets
- * @returns
  */
 const determineAssignment = (sampling, buckets) => {
     // Should this person be considered for the experiment?
@@ -29,9 +23,6 @@ const determineAssignment = (sampling, buckets) => {
 exports.determineAssignment = determineAssignment;
 /**
  * Determines which bucket a user assignment will recieve
- *
- * @param buckets
- * @returns
  */
 const determineBucket = (buckets) => {
     const bucketRoll = (0, exports.rollDie)();
@@ -50,14 +41,11 @@ const determineBucket = (buckets) => {
     if (!bucket) {
         throw new Error('Could not detetermine bucket from ratios');
     }
-    return bucket.id;
+    return bucket;
 };
 exports.determineBucket = determineBucket;
 /**
  * Validate the total ratio of the buckets equals 100
- *
- * @param buckets
- * @returns
  */
 const validateTotalBucketRatio = (buckets) => {
     const bucketSum = buckets.reduce((sum, current) => sum + current.ratio, 0);
@@ -83,10 +71,6 @@ const validateSegmentationRules = (rules, segmentationData) => {
 exports.validateSegmentationRules = validateSegmentationRules;
 /**
  * Validate a users segmentation data against a single rule
- *
- * @param rule
- * @param segmentationData
- * @returns
  */
 const validateSegmentationRule = (rule, data) => {
     const { key, value, operator } = rule;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/abba",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "scripts": {
     "prepare": "husky install",
     "build": "build",
@@ -9,13 +9,14 @@
   "dependencies": {
     "@naturalcycles/db-lib": "^8.40.1",
     "@naturalcycles/js-lib": "^14.98.2",
+    "@naturalcycles/nodejs-lib": "^12.70.1",
     "semver": "^7.3.5"
   },
   "devDependencies": {
     "@naturalcycles/dev-lib": "^12.19.2",
-    "@types/node": "^16.0.0",
+    "@types/node": "^17.0.34",
     "@types/semver": "^7.3.9",
-    "jest": "^27.5.1"
+    "jest": "^28.1.0"
   },
   "files": [
     "dist",

package/readme.md

@@ -154,7 +154,7 @@ async getUserAssignment(
   userId: string,
   existingOnly: boolean,
   segmentationData?: SegmentationData,
-): Promise<Saved<UserAssignment> | null>
+): Promise<GeneratedUserAssignment | null>
 ```
 
 ### Generate user assignments
@@ -166,7 +166,7 @@ attempt to generate new assignments.
 async generateUserAssignments(
   userId: string,
   segmentationData: SegmentationData,
-): Promise<Saved<UserAssignment>[]>
+): Promise<GeneratedUserAssignment[]>
 ```
 
 ### Getting assignment statistics

package/src/abba.ts

@@ -1,42 +1,43 @@
-import { pMap, Saved } from '@naturalcycles/js-lib'
+import { _assert, _AsyncMemo, pMap, Saved } from '@naturalcycles/js-lib'
+import { LRUMemoCache } from '@naturalcycles/nodejs-lib'
 import {
   AbbaConfig,
   AssignmentStatus,
   Bucket,
+  BucketInput,
   Experiment,
   ExperimentWithBuckets,
+  GeneratedUserAssignment,
   UserAssignment,
 } from './types'
 import { determineAssignment, validateSegmentationRules, 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 { SegmentationData, SegmentationRule, AssignmentStatistics } from '.'
+import { SegmentationData, AssignmentStatistics } from '.'
 
-export class Abba {
-  private experimentDao: ExperimentDao
-  private bucketDao: BucketDao
-  private userAssignmentDao: UserAssignmentDao
+const CACHE_TTL = 600_000 // 10 minutes
 
-  constructor({ db }: AbbaConfig) {
+export class Abba {
+  constructor(public cfg: AbbaConfig) {
+    const { db } = cfg
     this.experimentDao = experimentDao(db)
     this.bucketDao = bucketDao(db)
     this.userAssignmentDao = userAssignmentDao(db)
   }
 
-  // TODO: Cache me
+  private experimentDao: ExperimentDao
+  private bucketDao: BucketDao
+  private userAssignmentDao: UserAssignmentDao
+
   /**
-   * Returns all experiments
+   * Returns all (active and inactive) experiments.
    *
-   * @returns
+   * Cold method, not cached.
    */
-  async getAllExperiments(excludeInactive: boolean = false): Promise<ExperimentWithBuckets[]> {
-    const query = this.experimentDao.query()
-    if (excludeInactive) {
-      query.filter('status', '!=', AssignmentStatus.Inactive)
-    }
+  async getAllExperiments(): Promise<ExperimentWithBuckets[]> {
+    const experiments = await this.experimentDao.query().runQuery()
 
-    const experiments = await this.experimentDao.runQuery(query)
     const buckets = await this.bucketDao
       .query()
       .filter(
@@ -53,149 +54,190 @@ export class Abba {
   }
 
   /**
-   * Creates a new experiment
-   *
-   * @param experiment
-   * @param buckets
-   * @returns
+   * Returns only active experiments.
+   * Hot method.
+   * Cached in-memory for N minutes (currently 10).
+   */
+  @_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()
+
+    return experiments.map(experiment => ({
+      ...experiment,
+      buckets: buckets.filter(bucket => bucket.experimentId === experiment.id),
+    }))
+  }
+
+  /**
+   * Creates a new experiment.
+   * Cold method.
    */
   async createExperiment(
     experiment: Experiment,
-    buckets: Bucket[],
+    buckets: BucketInput[],
   ): Promise<ExperimentWithBuckets> {
     if (experiment.status === AssignmentStatus.Active) {
       validateTotalBucketRatio(buckets)
     }
 
-    const created = await this.experimentDao.save(experiment)
+    await this.experimentDao.save(experiment)
 
     return {
-      ...created,
+      ...(experiment as Saved<Experiment>),
       buckets: await this.bucketDao.saveBatch(
-        buckets.map(b => ({ ...b, experimentId: created.id })),
+        buckets.map(b => ({ ...b, experimentId: experiment.id! })),
       ),
     }
   }
 
   /**
-   * Update experiment information, will also validate the buckets ratio if experiment.active is true
-   *
-   * @param id
-   * @param experiment
-   * @param rules
-   * @param buckets
-   * @returns
+   * Update experiment information, will also validate the buckets' ratio if experiment.active is true
+   * Cold method.
    */
   async saveExperiment(
-    id: number,
-    experiment: Experiment,
+    experiment: Experiment & { id: number },
     buckets: Bucket[],
   ): Promise<ExperimentWithBuckets> {
     if (experiment.status === AssignmentStatus.Active) {
       validateTotalBucketRatio(buckets)
     }
 
-    const updated = await this.experimentDao.save({
-      ...experiment,
-      id,
-    })
+    await this.experimentDao.save(experiment)
 
     return {
-      ...updated,
-      buckets: await this.bucketDao.saveBatch(buckets.map(b => ({ ...b, experimentId: id }))),
+      ...(experiment as Saved<Experiment>),
+      buckets: await this.bucketDao.saveBatch(
+        buckets.map(b => ({ ...b, experimentId: experiment.id })),
+      ),
     }
   }
 
   /**
-   * Delete an experiment. Removes all user assignments and buckets
-   *
-   * @param id
+   * Delete an experiment. Removes all user assignments and buckets.
+   * Cold method.
    */
   async deleteExperiment(id: number): Promise<void> {
     await this.experimentDao.deleteById(id)
   }
 
   /**
-   * Get an assignment for a given user. If existingOnly is false, it will attempt generate a new assignment
+   * Get an assignment for a given user. If existingOnly is false, it will attempt to generate a new assignment
+   * Cold method.
    *
    * @param experimentId
    * @param userId
    * @param existingOnly Do not generate any new assignments for this experiment
    * @param segmentationData Required if existingOnly is false
-   * @returns
    */
   async getUserAssignment(
     experimentId: number,
     userId: string,
     existingOnly: boolean,
     segmentationData?: SegmentationData,
-  ): Promise<Saved<UserAssignment> | null> {
+  ): Promise<GeneratedUserAssignment | null> {
+    const existing = await this.getExistingUserAssignment(experimentId, userId)
+
+    if (existing) {
+      const experiment = await this.experimentDao.requireById(experimentId)
+      const bucket = await this.bucketDao.getById(existing.bucketId || undefined)
+      return {
+        ...existing,
+        experimentName: experiment.name,
+        bucketKey: bucket?.key || null,
+      }
+    }
+
+    if (existingOnly) return null
+
     const experiment = await this.experimentDao.requireById(experimentId)
-    if (!experiment) throw new Error('Experiment not found')
+    if (experiment.status !== AssignmentStatus.Active) return null
 
-    const buckets = await this.bucketDao.getBy('experimentId', experimentId)
+    _assert(segmentationData, 'Segmentation data required when creating a new assignment')
 
-    const existing = await this.getExistingUserAssignment(experimentId, userId)
-    if (existing) return existing
+    const buckets = await this.bucketDao.getBy('experimentId', experimentId)
 
-    if (experiment.status !== AssignmentStatus.Active || existingOnly) return null
+    const assignment = this.generateUserAssignmentData(
+      { ...experiment, buckets },
+      userId,
+      segmentationData,
+    )
+    if (!assignment) return null
 
-    if (!segmentationData)
-      throw new Error('Segmentation data required when creating a new assignment')
+    const saved = await this.userAssignmentDao.save(assignment)
 
-    return await this.generateUserAssignment({ ...experiment, buckets }, userId, segmentationData)
+    return {
+      ...saved,
+      experimentName: experiment.name,
+      bucketKey: buckets.find(b => b.id === saved.bucketId)?.key || null,
+    }
   }
 
   /**
-   * Get all existing user assignments
-   *
-   * @param userId
-   * @returns
+   * Get all existing user assignments.
+   * Hot method.
+   * Not cached, because Assignments are fast-changing.
    */
   async getAllExistingUserAssignments(userId: string): Promise<Saved<UserAssignment>[]> {
     return await this.userAssignmentDao.getBy('userId', userId)
   }
 
   /**
-   * Generate user assignments for all active experiments. Will return any existing and attempt to generate any new assignments.
-   *
-   * @param userId
-   * @param segmentationData
-   * @returns
+   * Generate user assignments for all active experiments.
+   * Will return any existing and attempt to generate any new assignments.
+   * Hot method.
    */
   async generateUserAssignments(
     userId: string,
     segmentationData: SegmentationData,
-  ): Promise<Saved<UserAssignment>[]> {
-    const experiments = await this.getAllExperiments(true)
+  ): Promise<GeneratedUserAssignment[]> {
+    const experiments = await this.getActiveExperiments() // cached
     const existingAssignments = await this.getAllExistingUserAssignments(userId)
 
-    const assignments: Saved<UserAssignment>[] = []
-    const generatedAssignments: Promise<Saved<UserAssignment> | null>[] = []
+    const newAssignments: UserAssignment[] = []
+    for (const experiment of experiments) {
+      const existing = existingAssignments.find(ua => ua.experimentId === experiment.id)
+      if (!existing) {
+        const assignment = this.generateUserAssignmentData(experiment, userId, segmentationData)
+        if (assignment) {
+          newAssignments.push(assignment)
+        }
+      }
+    }
+
+    existingAssignments.push(...(await this.userAssignmentDao.saveBatch(newAssignments)))
 
+    const assignments: GeneratedUserAssignment[] = []
     for (const experiment of experiments) {
       const existing = existingAssignments.find(ua => ua.experimentId === experiment.id)
       if (existing) {
-        assignments.push(existing)
-        continue
-      } else {
-        generatedAssignments.push(this.generateUserAssignment(experiment, userId, segmentationData))
+        assignments.push({
+          ...existing,
+          experimentName: experiment.name,
+          bucketKey: experiment.buckets.find(i => i.id === existing.bucketId)?.key || null,
+        })
       }
     }
-
-    const generated = await Promise.all(generatedAssignments)
-    const filtered = generated.filter((ua): ua is Saved<UserAssignment> => ua !== null)
-    return [...assignments, ...filtered]
+    return assignments
   }
 
   /**
-   * Get assignment statistics for an experiment
-   *
-   * @param experimentId
-   * @returns
+   * Get assignment statistics for an experiment.
+   * Cold method.
    */
   async getExperimentAssignmentStatistics(experimentId: number): Promise<AssignmentStatistics> {
-    const statistics = {
+    const statistics: AssignmentStatistics = {
       sampled: await this.userAssignmentDao
         .query()
         .filterEq('experimentId', experimentId)
@@ -205,52 +247,49 @@ export class Abba {
 
     const buckets = await this.bucketDao.getBy('experimentId', experimentId)
     await pMap(buckets, async bucket => {
-      const count = this.userAssignmentDao.query().filterEq('bucketId', bucket.id)
-      statistics[bucket.id] = await this.userAssignmentDao.runQueryCount(count)
+      statistics.buckets[bucket.id] = await this.userAssignmentDao
+        .query()
+        .filterEq('bucketId', bucket.id)
+        .runQueryCount()
     })
 
     return statistics
   }
 
   /**
-   * Generate a new assignment for a given user
-   *
-   * @param experimentId
-   * @param userId
-   * @param segmentationData
-   * @returns
+   * Generate a new assignment for a given user.
+   * Doesn't save it.
    */
-  private async generateUserAssignment(
+  private generateUserAssignmentData(
     experiment: ExperimentWithBuckets,
     userId: string,
     segmentationData: SegmentationData,
-  ): Promise<Saved<UserAssignment> | null> {
-    const segmentationMatch = validateSegmentationRules(
-      experiment.rules as unknown as SegmentationRule[],
-      segmentationData,
-    )
+  ): UserAssignment | null {
+    const segmentationMatch = validateSegmentationRules(experiment.rules, segmentationData)
     if (!segmentationMatch) return null
 
-    return await this.userAssignmentDao.save({
+    const bucket = determineAssignment(experiment.sampling, experiment.buckets)
+
+    return {
       userId,
       experimentId: experiment.id,
-      bucketId: determineAssignment(experiment.sampling, experiment.buckets),
-    })
+      bucketId: bucket?.id || null,
+    }
   }
 
   /**
    * Queries to retrieve an existing user assignment for a given experiment
-   *
-   * @param experimentId
-   * @param userId
-   * @returns
    */
   private async getExistingUserAssignment(
     experimentId: number,
     userId: string,
   ): Promise<Saved<UserAssignment> | null> {
-    const assignments = await this.userAssignmentDao.getBy('userId', userId)
-    const assignment = assignments.find(assignment => assignment.experimentId === experimentId)
+    const [assignment] = await this.userAssignmentDao
+      .query()
+      .filterEq('userId', userId)
+      .filterEq('experimentId', experimentId)
+      .runQuery()
+
     return assignment || null
   }
 }

package/src/dao/experiment.dao.ts

@@ -17,6 +17,6 @@ export const experimentDao = (db: CommonDB): ExperimentDao =>
     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) }),
+      beforeDBMToBM: dbm => ({ ...dbm, rules: (dbm.rules && JSON.parse(dbm.rules)) || [] }),
     },
   })

package/src/types.ts

@@ -3,6 +3,14 @@ import { 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> & {
@@ -38,6 +46,11 @@ export type UserAssignment = BaseDBEntity<number> & {
   bucketId: number | null
 }
 
+export type GeneratedUserAssignment = Saved<UserAssignment> & {
+  experimentName: string
+  bucketKey: string | null
+}
+
 export type SegmentationData = Record<string, string | boolean | number>
 
 export enum AssignmentStatus {

package/src/util.ts

@@ -4,8 +4,6 @@ import { Bucket, SegmentationData, SegmentationRule } from './types'
 
 /**
  * Generate a random number between 0 and 100
- *
- * @returns
  */
 export const rollDie = (): number => {
   return Math.random() * 100
@@ -13,12 +11,8 @@ export const rollDie = (): number => {
 
 /**
  * Determines a users assignment for this experiment. Returns null if they are not considered to be in the sampling group
- *
- * @param sampling
- * @param buckets
- * @returns
  */
-export const determineAssignment = (sampling: number, buckets: Saved<Bucket>[]): number | null => {
+export const determineAssignment = (sampling: number, buckets: Saved<Bucket>[]): Bucket | null => {
   // Should this person be considered for the experiment?
   if (rollDie() > sampling) {
     return null
@@ -30,11 +24,8 @@ export const determineAssignment = (sampling: number, buckets: Saved<Bucket>[]):
 
 /**
  * Determines which bucket a user assignment will recieve
- *
- * @param buckets
- * @returns
  */
-export const determineBucket = (buckets: Saved<Bucket>[]): number => {
+export const determineBucket = (buckets: Saved<Bucket>[]): Bucket => {
   const bucketRoll = rollDie()
   let range: [number, number] | undefined
   const bucket = buckets.find(b => {
@@ -53,14 +44,11 @@ export const determineBucket = (buckets: Saved<Bucket>[]): number => {
     throw new Error('Could not detetermine bucket from ratios')
   }
 
-  return bucket.id
+  return bucket
 }
 
 /**
  * Validate the total ratio of the buckets equals 100
- *
- * @param buckets
- * @returns
  */
 export const validateTotalBucketRatio = (buckets: Bucket[]): void => {
   const bucketSum = buckets.reduce((sum, current) => sum + current.ratio, 0)
@@ -88,10 +76,6 @@ export const validateSegmentationRules = (
 
 /**
  * Validate a users segmentation data against a single rule
- *
- * @param rule
- * @param segmentationData
- * @returns
  */
 export const validateSegmentationRule = (
   rule: SegmentationRule,