@naturalcycles/abba 1.9.1 → 1.11.0

package/dist/abba.d.ts

@@ -1,5 +1,5 @@
 import { Saved } from '@naturalcycles/js-lib';
-import { AbbaConfig, Bucket, BucketInput, 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;
@@ -45,7 +45,7 @@ export declare class Abba {
      * @param existingOnly Do not generate any new assignments for this experiment
      * @param segmentationData Required if existingOnly is false
      */
-    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.
      * Hot method.
@@ -57,7 +57,7 @@ export declare class Abba {
      * 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.
      * Cold method.

package/dist/abba.js

@@ -99,8 +99,14 @@ class Abba {
      */
     async getUserAssignment(experimentId, userId, existingOnly, segmentationData) {
         const existing = await this.getExistingUserAssignment(experimentId, userId);
-        if (existing)
-            return existing;
+        if (existing) {
+            let bucketKey = null;
+            if (existing.bucketId) {
+                const { key } = await this.bucketDao.requireById(existing.bucketId);
+                bucketKey = key;
+            }
+            return { ...existing, bucketKey };
+        }
         if (existingOnly)
             return null;
         const experiment = await this.experimentDao.requireById(experimentId);
@@ -111,7 +117,11 @@ class Abba {
         const assignment = this.generateUserAssignmentData({ ...experiment, buckets }, userId, segmentationData);
         if (!assignment)
             return null;
-        return await this.userAssignmentDao.save(assignment);
+        const saved = await this.userAssignmentDao.save(assignment);
+        return {
+            ...saved,
+            bucketKey: buckets.find(b => b.id === saved.bucketId)?.key || null,
+        };
     }
     /**
      * Get all existing user assignments.
@@ -129,22 +139,28 @@ class Abba {
     async generateUserAssignments(userId, segmentationData) {
         const experiments = await this.getActiveExperiments(); // cached
         const existingAssignments = await this.getAllExistingUserAssignments(userId);
-        const allAssignments = [];
-        const generatedAssignments = [];
+        const newAssignments = [];
         for (const experiment of experiments) {
             const existing = existingAssignments.find(ua => ua.experimentId === experiment.id);
-            if (existing) {
-                allAssignments.push(existing);
-            }
-            else {
+            if (!existing) {
                 const assignment = this.generateUserAssignmentData(experiment, userId, segmentationData);
                 if (assignment) {
-                    generatedAssignments.push(assignment);
+                    newAssignments.push(assignment);
                 }
             }
         }
-        await this.userAssignmentDao.saveBatch(generatedAssignments);
-        return [...allAssignments, ...generatedAssignments];
+        existingAssignments.push(...(await this.userAssignmentDao.saveBatch(newAssignments)));
+        const assignments = [];
+        for (const experiment of experiments) {
+            const existing = existingAssignments.find(ua => ua.experimentId === experiment.id);
+            if (existing) {
+                assignments.push({
+                    ...existing,
+                    bucketKey: experiment.buckets.find(i => i.id === existing.bucketId)?.key || null,
+                });
+            }
+        }
+        return assignments;
     }
     /**
      * Get assignment statistics for an experiment.
@@ -160,7 +176,7 @@ class Abba {
         };
         const buckets = await this.bucketDao.getBy('experimentId', experimentId);
         await (0, js_lib_1.pMap)(buckets, async (bucket) => {
-            statistics[bucket.id] = await this.userAssignmentDao
+            statistics.buckets[bucket.id] = await this.userAssignmentDao
                 .query()
                 .filterEq('bucketId', bucket.id)
                 .runQueryCount();
@@ -175,10 +191,11 @@ class Abba {
         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: (0, util_1.determineAssignment)(experiment.sampling, experiment.buckets),
+            bucketId: bucket?.id || null,
         };
     }
     /**

package/dist/migrations/init.sql

@@ -13,7 +13,6 @@ CREATE TABLE IF NOT EXISTS `Bucket` (
 -- CreateTable
 CREATE TABLE IF NOT EXISTS `Experiment` (
     `id` INTEGER NOT NULL AUTO_INCREMENT,
-    `name` VARCHAR(191) NOT NULL,
     `status` INTEGER NOT NULL,
     `sampling` INTEGER NOT NULL,
     `description` VARCHAR(240) NULL,

package/dist/types.d.ts

@@ -4,7 +4,7 @@ export interface AbbaConfig {
     db: CommonDB;
 }
 export declare type BaseExperiment = BaseDBEntity<number> & {
-    name: string;
+    id: number;
     status: number;
     sampling: number;
     description: string | null;
@@ -30,6 +30,9 @@ export declare type UserAssignment = BaseDBEntity<number> & {
     experimentId: number;
     bucketId: number | null;
 };
+export declare type GeneratedUserAssignment = Saved<UserAssignment> & {
+    bucketKey: string | null;
+};
 export declare type SegmentationData = Record<string, string | boolean | number>;
 export declare enum AssignmentStatus {
     Active = 1,

package/dist/util.d.ts

@@ -7,11 +7,11 @@ 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
  */
-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
  */
-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
  */

package/dist/util.js

@@ -41,7 +41,7 @@ const determineBucket = (buckets) => {
     if (!bucket) {
         throw new Error('Could not detetermine bucket from ratios');
     }
-    return bucket.id;
+    return bucket;
 };
 exports.determineBucket = determineBucket;
 /**

package/package.json

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

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

@@ -7,6 +7,7 @@ import {
   BucketInput,
   Experiment,
   ExperimentWithBuckets,
+  GeneratedUserAssignment,
   UserAssignment,
 } from './types'
 import { determineAssignment, validateSegmentationRules, validateTotalBucketRatio } from './util'
@@ -96,7 +97,7 @@ export class Abba {
     return {
       ...(experiment as Saved<Experiment>),
       buckets: await this.bucketDao.saveBatch(
-        buckets.map(b => ({ ...b, experimentId: experiment.id! })),
+        buckets.map(b => ({ ...b, experimentId: experiment.id })),
       ),
     }
   }
@@ -145,9 +146,18 @@ export class Abba {
     userId: string,
     existingOnly: boolean,
     segmentationData?: SegmentationData,
-  ): Promise<Saved<UserAssignment> | null> {
+  ): Promise<GeneratedUserAssignment | null> {
     const existing = await this.getExistingUserAssignment(experimentId, userId)
-    if (existing) return existing
+
+    if (existing) {
+      let bucketKey = null
+      if (existing.bucketId) {
+        const { key } = await this.bucketDao.requireById(existing.bucketId)
+        bucketKey = key
+      }
+      return { ...existing, bucketKey }
+    }
+
     if (existingOnly) return null
 
     const experiment = await this.experimentDao.requireById(experimentId)
@@ -164,7 +174,12 @@ export class Abba {
     )
     if (!assignment) return null
 
-    return await this.userAssignmentDao.save(assignment)
+    const saved = await this.userAssignmentDao.save(assignment)
+
+    return {
+      ...saved,
+      bucketKey: buckets.find(b => b.id === saved.bucketId)?.key || null,
+    }
   }
 
   /**
@@ -184,28 +199,34 @@ export class Abba {
   async generateUserAssignments(
     userId: string,
     segmentationData: SegmentationData,
-  ): Promise<Saved<UserAssignment>[]> {
+  ): Promise<GeneratedUserAssignment[]> {
     const experiments = await this.getActiveExperiments() // cached
     const existingAssignments = await this.getAllExistingUserAssignments(userId)
 
-    const allAssignments: Saved<UserAssignment>[] = []
-    const generatedAssignments: UserAssignment[] = []
-
+    const newAssignments: UserAssignment[] = []
     for (const experiment of experiments) {
       const existing = existingAssignments.find(ua => ua.experimentId === experiment.id)
-      if (existing) {
-        allAssignments.push(existing)
-      } else {
+      if (!existing) {
         const assignment = this.generateUserAssignmentData(experiment, userId, segmentationData)
         if (assignment) {
-          generatedAssignments.push(assignment)
+          newAssignments.push(assignment)
         }
       }
     }
 
-    await this.userAssignmentDao.saveBatch(generatedAssignments)
+    existingAssignments.push(...(await this.userAssignmentDao.saveBatch(newAssignments)))
 
-    return [...allAssignments, ...(generatedAssignments as Saved<UserAssignment>[])]
+    const assignments: GeneratedUserAssignment[] = []
+    for (const experiment of experiments) {
+      const existing = existingAssignments.find(ua => ua.experimentId === experiment.id)
+      if (existing) {
+        assignments.push({
+          ...existing,
+          bucketKey: experiment.buckets.find(i => i.id === existing.bucketId)?.key || null,
+        })
+      }
+    }
+    return assignments
   }
 
   /**
@@ -213,7 +234,7 @@ export class Abba {
    * Cold method.
    */
   async getExperimentAssignmentStatistics(experimentId: number): Promise<AssignmentStatistics> {
-    const statistics = {
+    const statistics: AssignmentStatistics = {
       sampled: await this.userAssignmentDao
         .query()
         .filterEq('experimentId', experimentId)
@@ -223,7 +244,7 @@ export class Abba {
 
     const buckets = await this.bucketDao.getBy('experimentId', experimentId)
     await pMap(buckets, async bucket => {
-      statistics[bucket.id] = await this.userAssignmentDao
+      statistics.buckets[bucket.id] = await this.userAssignmentDao
         .query()
         .filterEq('bucketId', bucket.id)
         .runQueryCount()
@@ -244,10 +265,12 @@ export class Abba {
     const segmentationMatch = validateSegmentationRules(experiment.rules, segmentationData)
     if (!segmentationMatch) return null
 
+    const bucket = determineAssignment(experiment.sampling, experiment.buckets)
+
     return {
       userId,
       experimentId: experiment.id,
-      bucketId: determineAssignment(experiment.sampling, experiment.buckets),
+      bucketId: bucket?.id || null,
     }
   }
 

package/src/migrations/init.sql

@@ -13,7 +13,6 @@ CREATE TABLE IF NOT EXISTS `Bucket` (
 -- CreateTable
 CREATE TABLE IF NOT EXISTS `Experiment` (
     `id` INTEGER NOT NULL AUTO_INCREMENT,
-    `name` VARCHAR(191) NOT NULL,
     `status` INTEGER NOT NULL,
     `sampling` INTEGER NOT NULL,
     `description` VARCHAR(240) NULL,

package/src/types.ts

@@ -14,7 +14,7 @@ export interface AbbaConfig {
 }
 
 export type BaseExperiment = BaseDBEntity<number> & {
-  name: string
+  id: number
   status: number
   sampling: number
   description: string | null
@@ -46,6 +46,10 @@ export type UserAssignment = BaseDBEntity<number> & {
   bucketId: number | null
 }
 
+export type GeneratedUserAssignment = Saved<UserAssignment> & {
+  bucketKey: string | null
+}
+
 export type SegmentationData = Record<string, string | boolean | number>
 
 export enum AssignmentStatus {

package/src/util.ts

@@ -12,7 +12,7 @@ export const rollDie = (): number => {
 /**
  * Determines a users assignment for this experiment. Returns null if they are not considered to be in the sampling group
  */
-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
@@ -25,7 +25,7 @@ export const determineAssignment = (sampling: number, buckets: Saved<Bucket>[]):
 /**
  * Determines which bucket a user assignment will recieve
  */
-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 => {
@@ -44,7 +44,7 @@ export const determineBucket = (buckets: Saved<Bucket>[]): number => {
     throw new Error('Could not detetermine bucket from ratios')
   }
 
-  return bucket.id
+  return bucket
 }
 
 /**