@naturalcycles/abba 2.0.1 → 2.1.0

package/src/types.ts

@@ -1,5 +1,5 @@
 import type { CommonDB } from '@naturalcycles/db-lib'
-import type { AnyObject, BaseDBEntity, IsoDate, Saved } from '@naturalcycles/js-lib'
+import type { AnyObject, BaseDBEntity, IsoDate } from '@naturalcycles/js-lib'
 
 export interface AbbaConfig {
   db: CommonDB
@@ -31,6 +31,10 @@ export type BaseExperiment = BaseDBEntity & {
    * Date range end for the experiment assignments
    */
   endDateExcl: IsoDate
+  /**
+   * Whether the experiment is flagged as deleted. This acts as a soft delete only.
+   */
+  deleted: boolean
 }
 
 export type Experiment = BaseExperiment & {
@@ -39,8 +43,8 @@ export type Experiment = BaseExperiment & {
   data: AnyObject | null
 }
 
-export type ExperimentWithBuckets = Saved<Experiment> & {
-  buckets: Saved<Bucket>[]
+export type ExperimentWithBuckets = Experiment & {
+  buckets: Bucket[]
 }
 
 export type BaseBucket = BaseDBEntity & {
@@ -59,15 +63,11 @@ export type UserAssignment = BaseDBEntity & {
   bucketId: string | null
 }
 
-export interface GeneratedUserAssignment {
-  assignment:
-    | (Saved<UserAssignment> & {
-        experimentKey: string
-        bucketKey: string | null
-        bucketData: AnyObject | null
-      })
-    | null
-  experiment: Saved<Experiment>
+export type DecoratedUserAssignment = UserAssignment & {
+  experimentKey: Experiment['key']
+  experimentData: Experiment['data']
+  bucketKey: Bucket['key'] | null
+  bucketData: Bucket['data']
 }
 
 export type SegmentationData = AnyObject
@@ -127,3 +127,7 @@ export interface BucketAssignmentStatistics {
 }
 
 export type ExclusionSet = Set<string>
+
+export interface UserExperiment extends ExperimentWithBuckets {
+  userAssignment?: DecoratedUserAssignment
+}

package/src/util.ts

@@ -10,6 +10,7 @@ import type {
   SegmentationRule,
   SegmentationRuleFn,
   UserAssignment,
+  UserExperiment,
 } from './types.js'
 import { AssignmentStatus, SegmentationRuleOperator } from './types.js'
 
@@ -17,11 +18,11 @@ import { AssignmentStatus, SegmentationRuleOperator } from './types.js'
  * Generate a new assignment for a given user.
  * Doesn't save it.
  */
-export const generateUserAssignmentData = (
+export function generateUserAssignmentData(
   experiment: ExperimentWithBuckets,
   userId: string,
   segmentationData: SegmentationData,
-): UserAssignment | null => {
+): Unsaved<UserAssignment> | null {
   const segmentationMatch = validateSegmentationRules(experiment.rules, segmentationData)
   if (!segmentationMatch) return null
 
@@ -31,7 +32,7 @@ export const generateUserAssignmentData = (
     userId,
     experimentId: experiment.id,
     bucketId: bucket?.id || null,
-  } as UserAssignment
+  }
 }
 
 class RandomService {
@@ -48,7 +49,7 @@ export const randomService = new RandomService()
 /**
  * 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: Bucket[]): Bucket | null => {
+export function determineAssignment(sampling: number, buckets: Bucket[]): Bucket | null {
   // Should this person be considered for the experiment?
   if (randomService.rollDie() > sampling) {
     return null
@@ -61,7 +62,7 @@ export const determineAssignment = (sampling: number, buckets: Bucket[]): Bucket
 /**
  * Determines which bucket a user assignment will recieve
  */
-export const determineBucket = (buckets: Bucket[]): Bucket => {
+export function determineBucket(buckets: Bucket[]): Bucket {
   const bucketRoll = randomService.rollDie()
   let range: [number, number] | undefined
   const bucket = buckets.find(b => {
@@ -86,7 +87,7 @@ export const determineBucket = (buckets: Bucket[]): Bucket => {
 /**
  * Validate the total ratio of the buckets equals 100
  */
-export const validateTotalBucketRatio = (buckets: Unsaved<Bucket>[]): void => {
+export function validateTotalBucketRatio(buckets: Unsaved<Bucket>[]): void {
   const bucketSum = buckets.reduce((sum, current) => sum + current.ratio, 0)
   if (bucketSum !== 100) {
     throw new Error('Total bucket ratio must be 100 before you can activate an experiment')
@@ -100,10 +101,10 @@ export const validateTotalBucketRatio = (buckets: Unsaved<Bucket>[]): void => {
  * @param segmentationData
  * @returns
  */
-export const validateSegmentationRules = (
+export function validateSegmentationRules(
   rules: SegmentationRule[],
   segmentationData: SegmentationData,
-): boolean => {
+): boolean {
   for (const rule of rules) {
     const { key, value, operator } = rule
     if (!segmentationRuleMap[operator](segmentationData[key], value)) return false
@@ -144,10 +145,10 @@ export const segmentationRuleMap: Record<SegmentationRuleOperator, SegmentationR
 /**
  * Returns true if an experiment is able to generate new assignments based on status and start/end dates
  */
-export const canGenerateNewAssignments = (
+export function canGenerateNewAssignments(
   experiment: Experiment,
   exclusionSet: ExclusionSet,
-): boolean => {
+): boolean {
   return (
     !exclusionSet.has(experiment.id) &&
     experiment.status === AssignmentStatus.Active &&
@@ -159,18 +160,15 @@ export const 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
  */
-export const getUserExclusionSet = (
-  experiments: Experiment[],
-  existingAssignments: UserAssignment[],
-): ExclusionSet => {
+export function getUserExclusionSet(experiments: UserExperiment[]): ExclusionSet {
   const exclusionSet: ExclusionSet = new Set()
-  existingAssignments.forEach(assignment => {
+  experiments.forEach(experiment => {
+    const { userAssignment } = experiment
     // Users who are excluded from an experiment due to sampling
     // should not prevent potential assignment to other mutually exclusive experiments
-    if (assignment.bucketId === null) return
+    if (!userAssignment || userAssignment?.bucketId === null) return
 
-    const experiment = experiments.find(e => e.id === assignment.experimentId)
-    experiment?.exclusions.forEach(experimentId => exclusionSet.add(experimentId))
+    experiment.exclusions.forEach(experimentId => exclusionSet.add(experimentId))
   })
   return exclusionSet
 }