@naturalcycles/abba 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Natural Cycles
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/abba.d.ts

@@ -0,0 +1,102 @@
+import { UserAssignment } from '../prisma/generated/output';
+import { BucketInput, ExperimentWithBuckets, ExperimentInput, SegmentationData, AssignmentStatistics } from '.';
+export declare class Abba {
+    private client;
+    constructor();
+    /**
+     * Returns all experiments
+     *
+     * @returns
+     */
+    getAllExperiments(excludeInactive?: boolean): Promise<ExperimentWithBuckets[]>;
+    /**
+     * Creates a new experiment
+     *
+     * @param experiment
+     * @param buckets
+     * @returns
+     */
+    createExperiment(experiment: ExperimentInput, buckets: BucketInput[]): 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
+     */
+    saveExperiment(id: number, experiment: ExperimentInput, buckets: BucketInput[]): Promise<ExperimentWithBuckets>;
+    /**
+     * Delete an experiment. Removes all user assignments and buckets
+     *
+     * @param id
+     */
+    deleteExperiment(id: number): Promise<void>;
+    /**
+     * Get an assignment for a given user. If existingOnly is false, it will attempt generate a new assignment
+     *
+     * @param experimentId
+     * @param userId
+     * @param createNew
+     * @param segmentationData
+     * @returns
+     */
+    getUserAssignment(experimentId: number, userId: string, existingOnly: boolean, segmentationData?: SegmentationData): Promise<UserAssignment | null>;
+    /**
+     * Get all existing user assignments
+     *
+     * @param userId G
+     * @returns
+     */
+    getAllExistingUserAssignments(userId: string): Promise<UserAssignment[]>;
+    /**
+     * Generate user assignments for all active experiments. Will return any existing and attempt to generate any new assignments.
+     *
+     * @param userId
+     * @param segmentationData
+     * @returns
+     */
+    generateUserAssignments(userId: string, segmentationData: SegmentationData): Promise<UserAssignment[]>;
+    /**
+     * Get assignment statistics for an experiment
+     *
+     * @param experimentId
+     * @returns
+     */
+    getExperimentAssignmentStatistics(experimentId: number): Promise<AssignmentStatistics>;
+    /**
+     * Generate a new assignment for a given user
+     *
+     * @param experimentId
+     * @param userId
+     * @param segmentationData
+     * @returns
+     */
+    private generateUserAssignment;
+    /**
+     * Queries to retrieve an existing user assignment for a given experiment
+     *
+     * @param experimentId
+     * @param userId
+     * @returns
+     */
+    private getExistingUserAssignment;
+    /**
+     * Update experiment information
+     *
+     * @param id
+     * @param experiment
+     * @param rules
+     * @returns
+     */
+    private updateExperiment;
+    /**
+     * Upserts bucket info
+     *
+     * @param id
+     * @param experiment
+     * @returns
+     */
+    private saveBuckets;
+}

package/dist/abba.js

@@ -0,0 +1,239 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Abba = void 0;
+const output_1 = require("../prisma/generated/output");
+const types_1 = require("./types");
+const util_1 = require("./util");
+// Note: Schema currently contains an output dir which generates all the files to the prisma dir
+// it would be tidier not to include it here when possible later on:
+// Explanation is here: https://github.com/prisma/prisma/issues/9435#issuecomment-960290681
+class Abba {
+    constructor() {
+        this.client = new output_1.PrismaClient();
+    }
+    /**
+     * Returns all experiments
+     *
+     * @returns
+     */
+    async getAllExperiments(excludeInactive = false) {
+        return await this.client.experiment.findMany({
+            where: excludeInactive ? { NOT: { status: types_1.AssignmentStatus.Inactive } } : undefined,
+            include: { buckets: true },
+        });
+    }
+    /**
+     * Creates a new experiment
+     *
+     * @param experiment
+     * @param buckets
+     * @returns
+     */
+    async createExperiment(experiment, buckets) {
+        if (experiment.status === types_1.AssignmentStatus.Active) {
+            (0, util_1.validateBuckets)(buckets);
+        }
+        const created = await this.client.experiment.create({
+            data: {
+                ...experiment,
+                rules: experiment.rules,
+                buckets: {
+                    createMany: {
+                        data: buckets,
+                    },
+                },
+            },
+            include: {
+                buckets: true,
+            },
+        });
+        return created;
+    }
+    /**
+     * Update experiment information, will also validate the buckets ratio if experiment.active is true
+     *
+     * @param id
+     * @param experiment
+     * @param rules
+     * @param buckets
+     * @returns
+     */
+    async saveExperiment(id, experiment, buckets) {
+        if (experiment.status === types_1.AssignmentStatus.Active) {
+            (0, util_1.validateBuckets)(buckets);
+        }
+        const updatedExperiment = await this.updateExperiment(id, experiment);
+        const updatedBuckets = await this.saveBuckets(buckets);
+        return {
+            ...updatedExperiment,
+            buckets: updatedBuckets,
+        };
+    }
+    /**
+     * Delete an experiment. Removes all user assignments and buckets
+     *
+     * @param id
+     */
+    async deleteExperiment(id) {
+        await this.client.experiment.delete({ where: { id } });
+    }
+    /**
+     * Get an assignment for a given user. If existingOnly is false, it will attempt generate a new assignment
+     *
+     * @param experimentId
+     * @param userId
+     * @param createNew
+     * @param segmentationData
+     * @returns
+     */
+    async getUserAssignment(experimentId, userId, existingOnly, segmentationData) {
+        const experiment = await this.client.experiment.findUnique({
+            where: { id: experimentId },
+            include: { buckets: true },
+        });
+        if (!experiment)
+            throw new Error('Experiment not found');
+        const existing = await this.getExistingUserAssignment(experimentId, userId);
+        if (existing)
+            return existing;
+        if (experiment.status !== types_1.AssignmentStatus.Active || existingOnly)
+            return null;
+        if (!segmentationData)
+            throw new Error('Segmentation data required when creating a new assignment');
+        return await this.generateUserAssignment(experiment, userId, segmentationData);
+    }
+    /**
+     * Get all existing user assignments
+     *
+     * @param userId G
+     * @returns
+     */
+    async getAllExistingUserAssignments(userId) {
+        return await this.client.userAssignment.findMany({ where: { userId } });
+    }
+    /**
+     * Generate user assignments for all active experiments. Will return any existing and attempt to generate any new assignments.
+     *
+     * @param userId
+     * @param segmentationData
+     * @returns
+     */
+    async generateUserAssignments(userId, segmentationData) {
+        const experiments = await this.getAllExperiments(true);
+        const existingAssignments = await this.getAllExistingUserAssignments(userId);
+        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));
+            }
+        }
+        const generated = await Promise.all(generatedAssignments);
+        const filtered = generated.filter((ua) => ua !== null);
+        return [...assignments, ...filtered];
+    }
+    /**
+     * Get assignment statistics for an experiment
+     *
+     * @param experimentId
+     * @returns
+     */
+    async getExperimentAssignmentStatistics(experimentId) {
+        const statistics = {
+            sampled: await this.client.userAssignment.count({ where: { experimentId } }),
+            buckets: {},
+        };
+        const buckets = await this.client.bucket.findMany({ where: { experimentId } });
+        const assignmentCounts = await this.client.userAssignment.groupBy({
+            where: { experimentId },
+            by: ['bucketId'],
+            _count: {
+                _all: true,
+            },
+        });
+        buckets.forEach(({ id }) => {
+            statistics.buckets[`${id}`] = assignmentCounts.find(i => i.bucketId === id)?._count?._all || 0;
+        });
+        return statistics;
+    }
+    /**
+     * Generate a new assignment for a given user
+     *
+     * @param experimentId
+     * @param userId
+     * @param segmentationData
+     * @returns
+     */
+    async generateUserAssignment(experiment, userId, segmentationData) {
+        const segmentationMatch = (0, util_1.validateSegmentationRules)(experiment.rules, segmentationData);
+        if (!segmentationMatch)
+            return null;
+        const bucketId = (0, util_1.determineAssignment)(experiment.sampling, experiment.buckets);
+        return await this.client.userAssignment.create({
+            data: { userId, experimentId: experiment.id, bucketId },
+        });
+    }
+    /**
+     * Queries to retrieve an existing user assignment for a given experiment
+     *
+     * @param experimentId
+     * @param userId
+     * @returns
+     */
+    async getExistingUserAssignment(experimentId, userId) {
+        return await this.client.userAssignment.findFirst({ where: { userId, experimentId } });
+    }
+    /**
+     * Update experiment information
+     *
+     * @param id
+     * @param experiment
+     * @param rules
+     * @returns
+     */
+    async updateExperiment(id, experiment) {
+        return await this.client.experiment.update({
+            where: { id },
+            data: {
+                ...experiment,
+                rules: experiment.rules,
+            },
+        });
+    }
+    /**
+     * Upserts bucket info
+     *
+     * @param id
+     * @param experiment
+     * @returns
+     */
+    async saveBuckets(buckets) {
+        const savedBuckets = [];
+        for (const bucket of buckets) {
+            const { id, ...data } = bucket;
+            if (id) {
+                savedBuckets.push(this.client.bucket.update({ where: { id }, data }));
+            }
+            else {
+                savedBuckets.push(this.client.bucket.create({
+                    data: {
+                        key: data.key,
+                        ratio: data.ratio,
+                        experiment: {
+                            connect: {
+                                id: data.experimentId,
+                            },
+                        },
+                    },
+                }));
+            }
+        }
+        return await Promise.all(savedBuckets);
+    }
+}
+exports.Abba = Abba;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { Bucket, Experiment, UserAssignment } from '../prisma/generated/output';
+export * from './types';
+export { Abba } from './abba';

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Abba = void 0;
+const tslib_1 = require("tslib");
+(0, tslib_1.__exportStar)(require("./types"), exports);
+var abba_1 = require("./abba");
+Object.defineProperty(exports, "Abba", { enumerable: true, get: function () { return abba_1.Abba; } });

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+import { Bucket, Experiment } from '../prisma/generated/output';
+export declare type Unsaved<T> = Omit<T, 'createdAt' | 'updatedAt'> & {
+    id?: number;
+};
+export declare type ExperimentWithBuckets = Experiment & {
+    buckets: Bucket[];
+};
+export declare type ExperimentInput = Unsaved<Experiment>;
+export declare type BucketInput = Unsaved<Bucket>;
+export declare type SegmentationData = Record<string, string | boolean | number>;
+export declare enum AssignmentStatus {
+    Active = 1,
+    Paused = 2,
+    Inactive = 3
+}
+export interface SegmentationRule {
+    key: string;
+    operator: '==' | '!=' | 'semver' | 'regex' | 'boolean';
+    value: string | boolean | number;
+}
+export interface AssignmentStatistics {
+    sampled: number;
+    buckets: {
+        [id: string]: number;
+    };
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AssignmentStatus = void 0;
+var AssignmentStatus;
+(function (AssignmentStatus) {
+    AssignmentStatus[AssignmentStatus["Active"] = 1] = "Active";
+    AssignmentStatus[AssignmentStatus["Paused"] = 2] = "Paused";
+    AssignmentStatus[AssignmentStatus["Inactive"] = 3] = "Inactive";
+})(AssignmentStatus = exports.AssignmentStatus || (exports.AssignmentStatus = {}));

package/dist/util.d.ts

@@ -0,0 +1,53 @@
+import { Bucket, Experiment } from '../prisma/generated/output';
+import { BucketInput, SegmentationData, SegmentationRule } from '.';
+/**
+ * Generate a random number between 0 and 100
+ *
+ * @returns
+ */
+export declare function 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 function determineAssignment(sampling: number, buckets: Bucket[]): number | null;
+/**
+ * Determines whether a user will be considered for a bucket assignment based on the experiment sampling rate
+ *
+ * @param experiment
+ * @returns
+ */
+export declare function determineExperiment(experiment: Experiment): boolean;
+/**
+ * Determines which bucket a user assignment will recieve
+ *
+ * @param buckets
+ * @returns
+ */
+export declare function determineBucket(buckets: Bucket[]): number;
+/**
+ * Validate the total ratio of the buckets equals 100
+ *
+ * @param buckets
+ * @returns
+ */
+export declare function validateBuckets(buckets: BucketInput[]): void;
+/**
+ * Validate a users segmentation data against multiple rules. Returns false if any fail
+ *
+ * @param rules
+ * @param segmentationData
+ * @returns
+ */
+export declare function validateSegmentationRules(rules: SegmentationRule[], segmentationData: SegmentationData): boolean;
+/**
+ * Validate a users segmentation data against a single rule
+ *
+ * @param rule
+ * @param segmentationData
+ * @returns
+ */
+export declare function validateSegmentationRule(rule: SegmentationRule, data: SegmentationData): boolean;

package/dist/util.js

@@ -0,0 +1,123 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateSegmentationRule = exports.validateSegmentationRules = exports.validateBuckets = exports.determineBucket = exports.determineExperiment = exports.determineAssignment = exports.rollDie = void 0;
+const semver_1 = require("semver");
+/**
+ * Generate a random number between 0 and 100
+ *
+ * @returns
+ */
+function rollDie() {
+    return Math.random() * 100;
+}
+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
+ */
+function determineAssignment(sampling, buckets) {
+    // Should this person be considered for the experiment?
+    const isIncludedInSample = rollDie() <= sampling;
+    if (!isIncludedInSample) {
+        return null;
+    }
+    // get their bucket
+    return determineBucket(buckets);
+}
+exports.determineAssignment = determineAssignment;
+/**
+ * Determines whether a user will be considered for a bucket assignment based on the experiment sampling rate
+ *
+ * @param experiment
+ * @returns
+ */
+function determineExperiment(experiment) {
+    return rollDie() <= experiment.sampling; // between 0 and 100
+}
+exports.determineExperiment = determineExperiment;
+/**
+ * Determines which bucket a user assignment will recieve
+ *
+ * @param buckets
+ * @returns
+ */
+function determineBucket(buckets) {
+    const bucketRoll = rollDie();
+    let range;
+    const bucket = buckets.find(b => {
+        if (!range) {
+            range = [0, b.ratio];
+        }
+        else {
+            range = [range[1], range[1] + b.ratio];
+        }
+        if (bucketRoll > range[0] && bucketRoll <= range[1]) {
+            return b;
+        }
+    });
+    if (!bucket) {
+        throw new Error('Could not detetermine bucket from ratios');
+    }
+    return bucket.id;
+}
+exports.determineBucket = determineBucket;
+/**
+ * Validate the total ratio of the buckets equals 100
+ *
+ * @param buckets
+ * @returns
+ */
+function validateBuckets(buckets) {
+    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');
+    }
+}
+exports.validateBuckets = validateBuckets;
+/**
+ * Validate a users segmentation data against multiple rules. Returns false if any fail
+ *
+ * @param rules
+ * @param segmentationData
+ * @returns
+ */
+function validateSegmentationRules(rules, segmentationData) {
+    for (const rule of rules) {
+        if (!validateSegmentationRule(rule, segmentationData))
+            return false;
+    }
+    return true;
+}
+exports.validateSegmentationRules = validateSegmentationRules;
+/**
+ * Validate a users segmentation data against a single rule
+ *
+ * @param rule
+ * @param segmentationData
+ * @returns
+ */
+function validateSegmentationRule(rule, data) {
+    const { key, value, operator } = rule;
+    if (operator === '==') {
+        return data[key] === value;
+    }
+    else if (operator === '!=') {
+        return data[key] !== value;
+    }
+    else if (operator === 'semver') {
+        return (0, semver_1.satisfies)(data[key]?.toString() || '', value.toString());
+    }
+    else if (operator === 'regex') {
+        return new RegExp(value.toString()).test(data[key]?.toString() || '');
+    }
+    else if (operator === 'boolean') {
+        return Boolean(value) === data[key];
+    }
+    else {
+        return false;
+    }
+}
+exports.validateSegmentationRule = validateSegmentationRule;

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@naturalcycles/abba",
+  "version": "1.0.0",
+  "scripts": {
+    "prepare": "husky install"
+  },
+  "dependencies": {
+    "@prisma/client": "^3.9.2",
+    "semver": "^7.3.5"
+  },
+  "devDependencies": {
+    "@naturalcycles/dev-lib": "^12.0.0",
+    "@types/json-logic-js": "^1.2.1",
+    "@types/node": "^16.0.0",
+    "@types/semver": "^7.3.9",
+    "jest": "^27.5.1",
+    "prisma": "^3.9.2"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/test",
+    "!src/**/*.test.ts",
+    "!src/**/__snapshots__",
+    "!src/**/__exclude"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/NaturalCycles/abba"
+  },
+  "engines": {
+    "node": ">=14.15.0"
+  },
+  "description": "AB test assignment configuration tool for Node.js",
+  "author": "Natural Cycles Team",
+  "license": "MIT"
+}

package/readme.md

@@ -0,0 +1,284 @@
+<div id="top"></div>
+
+<!-- PROJECT LOGO -->
+<br />
+<div align="center">
+  <h3 align="center">ABBA</h3>
+
+  <p align="center">
+    A tool for generating and persisting AB test assignments
+    <br />
+  </p>
+</div>
+
+<!-- TABLE OF CONTENTS -->
+<details>
+  <summary>Table of Contents</summary>
+  <ol>
+    <li>
+      <a href="#concepts">Concepts</a>
+    </li>
+    <li>
+      <a href="#getting-started">Getting Started</a>
+      <ul>
+        <li><a href="#prerequisites">Prerequisites</a></li>
+        <li><a href="#installation">Installation</a></li>
+      </ul>
+    </li>
+    <li><a href="#usage">Usage</a></li>
+    <li><a href="#segmentation">Segmentation</a></li>
+  </ol>
+</details>
+
+<!-- CONCEPTS -->
+
+## Concepts
+
+- **Experiment:** An individual experiment that will test a hypothesis
+- **Segmentation:** The target audience for the experiment
+- **Sampling:** Restrictions on what proportion of the target audience will be involved in the
+  experiment
+- **Bucket:** An allocation that defines what variant of a particular experience the user will have
+
+<!-- BUILTWITH -->
+
+### Built With
+
+- [Prisma](https://www.prisma.io/)
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+<!-- GETTING STARTED -->
+
+## Getting Started
+
+<div id="gettingStarted"></div>
+
+### Prerequisites
+
+<div id="prerequisites"></div>
+
+- A running MYSQL instance
+
+### Installation
+
+<div id="installation"></div>
+
+_Below is an example of how you can instruct your audience on installing and setting up your app.
+This template doesn't rely on any external dependencies or services._
+
+1. Install NPM packages<br/>
+
+   ```sh
+   yarn add @naturalcyles/abba
+
+   or
+
+   npm install @naturalcyles/abba
+   ```
+
+2. Execute the [sql script found here](/src/prisma/migrations/init.md) to generate the required DB
+   Schema
+
+3. Create a `.env` file add add your Database Url using the following key:
+   ```sh
+   EXPERIMENT_MANAGER_DB_URL="{{insert your instance url}}"
+   ```
+4. Create a new instance of the AssignmentManager class
+   ```js
+   const manager = new AssignmentManager()
+   ```
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+<!-- USAGE EXAMPLES -->
+
+## Usage
+
+<div id="usage"></div>
+
+### Create a new experiment
+
+Creates a new experiment
+
+```js
+async manager.createExperiment(
+	input: ExperimentInput,
+	buckets: BucketInput[]
+): Promise<Experiment>
+```
+
+### Update an experiment
+
+Updates an existing experiment.
+
+```js
+async manager.updateExperiment(
+	id: number,
+	input: ExperimentInput,
+	buckets: BucketInput[]
+): Promise<Experiment>
+```
+
+### Delete an experiment
+
+Delete an experiment. Removes all users assignments and buckets
+
+```js
+async manager.deleteExperiment(
+	id: number
+): Promise<void>
+```
+
+### Get all existing user assignments
+
+Gets all existing user assignments
+
+```js
+async getAllExistingUserAssignments(
+	userId: string
+): Promise<UserAssignment[]>
+```
+
+### Get a users assignment
+
+Get an assignment for a given user. If `existingOnly` is false, it will attempt generate a new
+assignment. `segmentationData` becomse required when `existingOnly` is false
+
+```js
+async getUserAssignment(
+  experimentId: number,
+  userId: string,
+  existingOnly: boolean,
+  segmentationData?: SegmentationData,
+): Promise<UserAssignment | null>
+```
+
+### Generate user assignments
+
+Generate user assignments for all active experiments. Will return any existing assignments and
+attempt to generate new assignments.
+
+```js
+async generateUserAssignments(
+  userId: string,
+  segmentationData: SegmentationData,
+): Promise<UserAssignment[]>
+```
+
+### Getting assignment statistics
+
+Get assignment statistics for an experiment.
+
+```js
+async getExperimentAssignmentStatistics(
+  experimentId: number
+): Promise<AssignmentStatistics>
+```
+
+<p align="right">(<a href="#top">back to top</a>)</p>
+
+## Segmentation
+
+<div id="segmentation"></div>
+
+Experiments can be configured to target specific audiences using segmentation rules. When generating
+assignments it is possible to test these rules using user segmentation data which is an object
+containing key/value pairs unique to each user. (Allowed value types: `string`, `number`,
+`boolean`). A segmentation rule consist of the following properties:
+
+```js
+  key: string, // the key of the corresponding segmentationData property.
+  operator: '==' | '!=' | 'semver' | 'regex' | 'boolean', // the operator that will be used to execute the rule
+  value: string | number | boolean, // the value the operator will be executed against
+```
+
+## Segmentation rule operators
+
+### Equals (==)
+
+Rule:
+
+```js
+  { key: 'country', operator: '==', value: 'SE }
+```
+
+Example segmentation data:
+
+```js
+{
+  country: 'SE', // valid
+  country: 'NO' // not valid
+}
+```
+
+### Not equals (!=)
+
+Rule:
+
+```js
+  { key: 'country', operator: '!=', value: 'SE' }
+```
+
+Example segmentation data:
+
+```js
+{
+  country: 'NO', // valid
+  country: 'SE' // not valid
+}
+```
+
+### Boolean (boolean)
+
+Rule:
+
+```js
+  { key: 'isEligible', operator: 'boolean', value: true }
+```
+
+Example segmentation data:
+
+```js
+{
+  isEligible: true, // valid
+  isEligible: false // not valid
+}
+```
+
+### Semver (semver)
+
+Rule:
+
+```js
+  { key: 'appVersion', operator: 'semver', value: '>1.1.0' }
+```
+
+Example segmentation data:
+
+```js
+{
+  appVersion: '1.2.0', // valid
+  appVersion: '1' // not valid
+}
+```
+
+### Regex (regex)
+
+Rule:
+
+```js
+  { key: 'country', operator: 'regex', value: 'SE|NO' }
+```
+
+Example segmentation data:
+
+```js
+{
+  country: 'SE', // valid
+  country: 'NO', // valid
+  country: 'GB' // not valid
+}
+```
+
+<p align="right">(<a href="#top">back to top</a>)</p>

package/src/abba.ts

@@ -0,0 +1,300 @@
+import {
+  Bucket,
+  Experiment,
+  Prisma,
+  PrismaClient,
+  UserAssignment,
+} from '../prisma/generated/output'
+import { AssignmentStatus } from './types'
+import { determineAssignment, validateSegmentationRules, validateBuckets } from './util'
+import {
+  BucketInput,
+  ExperimentWithBuckets,
+  ExperimentInput,
+  SegmentationData,
+  SegmentationRule,
+  AssignmentStatistics,
+} from '.'
+
+// Note: Schema currently contains an output dir which generates all the files to the prisma dir
+// it would be tidier not to include it here when possible later on:
+// Explanation is here: https://github.com/prisma/prisma/issues/9435#issuecomment-960290681
+
+export class Abba {
+  private client: PrismaClient
+
+  constructor() {
+    this.client = new PrismaClient()
+  }
+  /**
+   * Returns all experiments
+   *
+   * @returns
+   */
+  async getAllExperiments(excludeInactive: boolean = false): Promise<ExperimentWithBuckets[]> {
+    return await this.client.experiment.findMany({
+      where: excludeInactive ? { NOT: { status: AssignmentStatus.Inactive } } : undefined,
+      include: { buckets: true },
+    })
+  }
+
+  /**
+   * Creates a new experiment
+   *
+   * @param experiment
+   * @param buckets
+   * @returns
+   */
+  async createExperiment(
+    experiment: ExperimentInput,
+    buckets: BucketInput[],
+  ): Promise<ExperimentWithBuckets> {
+    if (experiment.status === AssignmentStatus.Active) {
+      validateBuckets(buckets)
+    }
+
+    const created = await this.client.experiment.create({
+      data: {
+        ...experiment,
+        rules: experiment.rules as Prisma.InputJsonArray,
+        buckets: {
+          createMany: {
+            data: buckets,
+          },
+        },
+      },
+      include: {
+        buckets: true,
+      },
+    })
+    return created
+  }
+
+  /**
+   * Update experiment information, will also validate the buckets ratio if experiment.active is true
+   *
+   * @param id
+   * @param experiment
+   * @param rules
+   * @param buckets
+   * @returns
+   */
+  async saveExperiment(
+    id: number,
+    experiment: ExperimentInput,
+    buckets: BucketInput[],
+  ): Promise<ExperimentWithBuckets> {
+    if (experiment.status === AssignmentStatus.Active) {
+      validateBuckets(buckets)
+    }
+
+    const updatedExperiment = await this.updateExperiment(id, experiment)
+    const updatedBuckets = await this.saveBuckets(buckets)
+
+    return {
+      ...updatedExperiment,
+      buckets: updatedBuckets,
+    }
+  }
+
+  /**
+   * Delete an experiment. Removes all user assignments and buckets
+   *
+   * @param id
+   */
+  async deleteExperiment(id: number): Promise<void> {
+    await this.client.experiment.delete({ where: { id } })
+  }
+
+  /**
+   * Get an assignment for a given user. If existingOnly is false, it will attempt generate a new assignment
+   *
+   * @param experimentId
+   * @param userId
+   * @param createNew
+   * @param segmentationData
+   * @returns
+   */
+  async getUserAssignment(
+    experimentId: number,
+    userId: string,
+    existingOnly: boolean,
+    segmentationData?: SegmentationData,
+  ): Promise<UserAssignment | null> {
+    const experiment = await this.client.experiment.findUnique({
+      where: { id: experimentId },
+      include: { buckets: true },
+    })
+    if (!experiment) throw new Error('Experiment not found')
+
+    const existing = await this.getExistingUserAssignment(experimentId, userId)
+    if (existing) return existing
+
+    if (experiment.status !== AssignmentStatus.Active || existingOnly) return null
+
+    if (!segmentationData)
+      throw new Error('Segmentation data required when creating a new assignment')
+
+    return await this.generateUserAssignment(experiment, userId, segmentationData)
+  }
+
+  /**
+   * Get all existing user assignments
+   *
+   * @param userId G
+   * @returns
+   */
+  async getAllExistingUserAssignments(userId: string): Promise<UserAssignment[]> {
+    return await this.client.userAssignment.findMany({ where: { userId } })
+  }
+
+  /**
+   * Generate user assignments for all active experiments. Will return any existing and attempt to generate any new assignments.
+   *
+   * @param userId
+   * @param segmentationData
+   * @returns
+   */
+  async generateUserAssignments(
+    userId: string,
+    segmentationData: SegmentationData,
+  ): Promise<UserAssignment[]> {
+    const experiments = await this.getAllExperiments(true)
+    const existingAssignments = await this.getAllExistingUserAssignments(userId)
+
+    const assignments: UserAssignment[] = []
+    const generatedAssignments: Promise<UserAssignment | null>[] = []
+
+    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))
+      }
+    }
+
+    const generated = await Promise.all(generatedAssignments)
+    const filtered = generated.filter((ua): ua is UserAssignment => ua !== null)
+    return [...assignments, ...filtered]
+  }
+
+  /**
+   * Get assignment statistics for an experiment
+   *
+   * @param experimentId
+   * @returns
+   */
+  async getExperimentAssignmentStatistics(experimentId: number): Promise<AssignmentStatistics> {
+    const statistics = {
+      sampled: await this.client.userAssignment.count({ where: { experimentId } }),
+      buckets: {},
+    }
+
+    const buckets = await this.client.bucket.findMany({ where: { experimentId } })
+    const assignmentCounts = await this.client.userAssignment.groupBy({
+      where: { experimentId },
+      by: ['bucketId'],
+      _count: {
+        _all: true,
+      },
+    })
+
+    buckets.forEach(({ id }) => {
+      statistics.buckets[`${id}`] = assignmentCounts.find(i => i.bucketId === id)?._count?._all || 0
+    })
+
+    return statistics
+  }
+
+  /**
+   * Generate a new assignment for a given user
+   *
+   * @param experimentId
+   * @param userId
+   * @param segmentationData
+   * @returns
+   */
+  private async generateUserAssignment(
+    experiment: ExperimentWithBuckets,
+    userId: string,
+    segmentationData: SegmentationData,
+  ): Promise<UserAssignment | null> {
+    const segmentationMatch = validateSegmentationRules(
+      experiment.rules as unknown as SegmentationRule[],
+      segmentationData,
+    )
+    if (!segmentationMatch) return null
+
+    const bucketId = determineAssignment(experiment.sampling, experiment.buckets)
+    return await this.client.userAssignment.create({
+      data: { userId, experimentId: experiment.id, bucketId },
+    })
+  }
+
+  /**
+   * Queries to retrieve an existing user assignment for a given experiment
+   *
+   * @param experimentId
+   * @param userId
+   * @returns
+   */
+  private async getExistingUserAssignment(
+    experimentId: number,
+    userId: string,
+  ): Promise<UserAssignment | null> {
+    return await this.client.userAssignment.findFirst({ where: { userId, experimentId } })
+  }
+
+  /**
+   * Update experiment information
+   *
+   * @param id
+   * @param experiment
+   * @param rules
+   * @returns
+   */
+  private async updateExperiment(id: number, experiment: Partial<Experiment>): Promise<Experiment> {
+    return await this.client.experiment.update({
+      where: { id },
+      data: {
+        ...experiment,
+        rules: experiment.rules as Prisma.InputJsonObject,
+      },
+    })
+  }
+
+  /**
+   * Upserts bucket info
+   *
+   * @param id
+   * @param experiment
+   * @returns
+   */
+  private async saveBuckets(buckets: BucketInput[]): Promise<Bucket[]> {
+    const savedBuckets: Promise<Bucket>[] = []
+    for (const bucket of buckets) {
+      const { id, ...data } = bucket
+      if (id) {
+        savedBuckets.push(this.client.bucket.update({ where: { id }, data }))
+      } else {
+        savedBuckets.push(
+          this.client.bucket.create({
+            data: {
+              key: data.key,
+              ratio: data.ratio,
+              experiment: {
+                connect: {
+                  id: data.experimentId,
+                },
+              },
+            },
+          }),
+        )
+      }
+    }
+
+    return await Promise.all(savedBuckets)
+  }
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export type { Bucket, Experiment, UserAssignment } from '../prisma/generated/output'
+
+export * from './types'
+
+export { Abba } from './abba'

package/src/types.ts

@@ -0,0 +1,34 @@
+import { Bucket, Experiment } from '../prisma/generated/output'
+
+export type Unsaved<T> = Omit<T, 'createdAt' | 'updatedAt'> & {
+  id?: number
+}
+
+export type ExperimentWithBuckets = Experiment & {
+  buckets: Bucket[]
+}
+
+export type ExperimentInput = Unsaved<Experiment>
+
+export type BucketInput = Unsaved<Bucket>
+
+export type SegmentationData = Record<string, string | boolean | number>
+
+export enum AssignmentStatus {
+  Active = 1, // Generating assignments
+  Paused = 2, // Not generating new assignments, still returning existing
+  Inactive = 3, // Will not return any assignments
+}
+
+export interface SegmentationRule {
+  key: string
+  operator: '==' | '!=' | 'semver' | 'regex' | 'boolean'
+  value: string | boolean | number
+}
+
+export interface AssignmentStatistics {
+  sampled: number
+  buckets: {
+    [id: string]: number
+  }
+}

package/src/util.ts

@@ -0,0 +1,122 @@
+import { satisfies } from 'semver'
+import { Bucket, Experiment } from '../prisma/generated/output'
+import { BucketInput, SegmentationData, SegmentationRule } from '.'
+
+/**
+ * Generate a random number between 0 and 100
+ *
+ * @returns
+ */
+export function rollDie(): number {
+  return Math.random() * 100
+}
+
+/**
+ * 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 function determineAssignment(sampling: number, buckets: Bucket[]): number | null {
+  // Should this person be considered for the experiment?
+  const isIncludedInSample = rollDie() <= sampling
+  if (!isIncludedInSample) {
+    return null
+  }
+
+  // get their bucket
+  return determineBucket(buckets)
+}
+
+/**
+ * Determines whether a user will be considered for a bucket assignment based on the experiment sampling rate
+ *
+ * @param experiment
+ * @returns
+ */
+export function determineExperiment(experiment: Experiment): boolean {
+  return rollDie() <= experiment.sampling // between 0 and 100
+}
+
+/**
+ * Determines which bucket a user assignment will recieve
+ *
+ * @param buckets
+ * @returns
+ */
+export function determineBucket(buckets: Bucket[]): number {
+  const bucketRoll = rollDie()
+  let range: [number, number] | undefined
+  const bucket = buckets.find(b => {
+    if (!range) {
+      range = [0, b.ratio]
+    } else {
+      range = [range[1], range[1] + b.ratio]
+    }
+
+    if (bucketRoll > range[0] && bucketRoll <= range[1]) {
+      return b
+    }
+  })
+
+  if (!bucket) {
+    throw new Error('Could not detetermine bucket from ratios')
+  }
+
+  return bucket.id
+}
+
+/**
+ * Validate the total ratio of the buckets equals 100
+ *
+ * @param buckets
+ * @returns
+ */
+export function validateBuckets(buckets: BucketInput[]): 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')
+  }
+}
+
+/**
+ * Validate a users segmentation data against multiple rules. Returns false if any fail
+ *
+ * @param rules
+ * @param segmentationData
+ * @returns
+ */
+export function validateSegmentationRules(
+  rules: SegmentationRule[],
+  segmentationData: SegmentationData,
+): boolean {
+  for (const rule of rules) {
+    if (!validateSegmentationRule(rule, segmentationData)) return false
+  }
+  return true
+}
+
+/**
+ * Validate a users segmentation data against a single rule
+ *
+ * @param rule
+ * @param segmentationData
+ * @returns
+ */
+export function validateSegmentationRule(rule: SegmentationRule, data: SegmentationData): boolean {
+  const { key, value, operator } = rule
+  if (operator === '==') {
+    return data[key] === value
+  } else if (operator === '!=') {
+    return data[key] !== value
+  } else if (operator === 'semver') {
+    return satisfies(data[key]?.toString() || '', value.toString())
+  } else if (operator === 'regex') {
+    return new RegExp(value.toString()).test(data[key]?.toString() || '')
+  } else if (operator === 'boolean') {
+    return Boolean(value) === data[key]
+  } else {
+    return false
+  }
+}