@naturalcycles/abba 1.12.1 → 1.13.0

package/dist/abba.js

@@ -110,7 +110,7 @@ class Abba {
         if (existingOnly)
             return null;
         const experiment = await this.experimentDao.requireById(experimentId);
-        if (experiment.status !== types_1.AssignmentStatus.Active)
+        if (!(0, util_1.canGenerateNewAssignments)(experiment))
             return null;
         (0, js_lib_1._assert)(segmentationData, 'Segmentation data required when creating a new assignment');
         const buckets = await this.bucketDao.getBy('experimentId', experimentId);
@@ -149,7 +149,7 @@ class Abba {
                     bucketKey: experiment.buckets.find(b => b.id === existing.bucketId)?.key || null,
                 });
             }
-            else if (!existingOnly && experiment.status === types_1.AssignmentStatus.Active) {
+            else if (!existingOnly && (0, util_1.canGenerateNewAssignments)(experiment)) {
                 const assignment = this.generateUserAssignmentData(experiment, userId, segmentationData);
                 if (assignment) {
                     const created = this.userAssignmentDao.create(assignment);

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

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

package/dist/migrations/init.sql

@@ -16,6 +16,8 @@ CREATE TABLE IF NOT EXISTS `Experiment` (
     `status` INTEGER NOT NULL,
     `sampling` INTEGER NOT NULL,
     `description` VARCHAR(240) NULL,
+    `startDateIncl` DATE NOT NULL,
+    `endDateExcl` DATE NOT NULL,
     `created` INTEGER(11) NOT NULL,
     `updated` INTEGER(11) NOT NULL,
     `rules` JSON NULL,

package/dist/types.d.ts

@@ -1,18 +1,20 @@
 import { CommonDB } from '@naturalcycles/db-lib';
-import { BaseDBEntity, Saved } from '@naturalcycles/js-lib';
+import { BaseDBEntity, IsoDateString, Saved } from '@naturalcycles/js-lib';
 export interface AbbaConfig {
     db: CommonDB;
 }
-export declare type BaseExperiment = BaseDBEntity<number> & {
+export type BaseExperiment = BaseDBEntity<number> & {
     id: number;
     status: number;
     sampling: number;
     description: string | null;
+    startDateIncl: IsoDateString;
+    endDateExcl: IsoDateString;
 };
-export declare type Experiment = BaseExperiment & {
+export type Experiment = BaseExperiment & {
     rules: SegmentationRule[];
 };
-export declare type ExperimentWithBuckets = Saved<Experiment> & {
+export type ExperimentWithBuckets = Saved<Experiment> & {
     buckets: Saved<Bucket>[];
 };
 export interface BucketInput {
@@ -20,23 +22,32 @@ export interface BucketInput {
     key: string;
     ratio: number;
 }
-export declare type Bucket = BaseDBEntity<number> & {
+export type Bucket = BaseDBEntity<number> & {
     experimentId: number;
     key: string;
     ratio: number;
 };
-export declare type UserAssignment = BaseDBEntity<number> & {
+export type UserAssignment = BaseDBEntity<number> & {
     userId: string;
     experimentId: number;
     bucketId: number | null;
 };
-export declare type GeneratedUserAssignment = Saved<UserAssignment> & {
+export type GeneratedUserAssignment = Saved<UserAssignment> & {
     bucketKey: string | null;
 };
-export declare type SegmentationData = Record<string, string | boolean | number>;
+export type SegmentationData = Record<string, string | boolean | number>;
 export declare enum AssignmentStatus {
+    /**
+     * Will return existing assignments and generate new assignments
+     */
     Active = 1,
+    /**
+     * Will return existing assignments but not generate new assignments
+     */
     Paused = 2,
+    /**
+     * Will not return any assignments
+     */
     Inactive = 3
 }
 export interface SegmentationRule {

package/dist/types.js

@@ -3,7 +3,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AssignmentStatus = void 0;
 var AssignmentStatus;
 (function (AssignmentStatus) {
+    /**
+     * Will return existing assignments and generate new assignments
+     */
     AssignmentStatus[AssignmentStatus["Active"] = 1] = "Active";
+    /**
+     * Will return existing assignments but not generate new assignments
+     */
     AssignmentStatus[AssignmentStatus["Paused"] = 2] = "Paused";
+    /**
+     * Will not return any assignments
+     */
     AssignmentStatus[AssignmentStatus["Inactive"] = 3] = "Inactive";
 })(AssignmentStatus = exports.AssignmentStatus || (exports.AssignmentStatus = {}));

package/dist/util.d.ts

@@ -1,5 +1,5 @@
 import { Saved } from '@naturalcycles/js-lib';
-import { Bucket, SegmentationData, SegmentationRule } from './types';
+import { Bucket, Experiment, SegmentationData, SegmentationRule } from './types';
 /**
  * Generate a random number between 0 and 100
  */
@@ -28,3 +28,7 @@ export declare const validateSegmentationRules: (rules: SegmentationRule[], segm
  * Validate a users segmentation data against a single rule
  */
 export declare const validateSegmentationRule: (rule: SegmentationRule, data: SegmentationData) => boolean;
+/**
+ * Returns true if an experiment is able to generate new assignments based on status and start/end dates
+ */
+export declare const canGenerateNewAssignments: (experiment: Experiment) => boolean;

package/dist/util.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.validateSegmentationRule = exports.validateSegmentationRules = exports.validateTotalBucketRatio = exports.determineBucket = exports.determineAssignment = exports.rollDie = void 0;
+exports.canGenerateNewAssignments = exports.validateSegmentationRule = exports.validateSegmentationRules = exports.validateTotalBucketRatio = exports.determineBucket = exports.determineAssignment = exports.rollDie = void 0;
+const js_lib_1 = require("@naturalcycles/js-lib");
 const semver_1 = require("semver");
+const types_1 = require("./types");
 /**
  * Generate a random number between 0 and 100
  */
@@ -89,8 +91,14 @@ const validateSegmentationRule = (rule, data) => {
     else if (operator === 'boolean') {
         return Boolean(value) === data[key];
     }
-    else {
-        return false;
-    }
+    return false;
 };
 exports.validateSegmentationRule = validateSegmentationRule;
+/**
+ * Returns true if an experiment is able to generate new assignments based on status and start/end dates
+ */
+const canGenerateNewAssignments = (experiment) => {
+    return (experiment.status === types_1.AssignmentStatus.Active &&
+        (0, js_lib_1.localDate)().isBetween(experiment.startDateIncl, experiment.endDateExcl, '[)'));
+};
+exports.canGenerateNewAssignments = canGenerateNewAssignments;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@naturalcycles/abba",
-  "version": "1.12.1",
+  "version": "1.13.0",
   "scripts": {
     "prepare": "husky install",
     "build": "build",
@@ -13,10 +13,10 @@
     "semver": "^7.3.5"
   },
   "devDependencies": {
-    "@naturalcycles/dev-lib": "^12.19.2",
-    "@types/node": "^17.0.34",
+    "@naturalcycles/dev-lib": "^13.15.0",
+    "@types/node": "^18.11.18",
     "@types/semver": "^7.3.9",
-    "jest": "^28.1.0"
+    "jest": "^29.3.1"
   },
   "files": [
     "dist",
@@ -29,14 +29,14 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "publishConfig": {
-    "access": "public"
+    "access": "restricted"
   },
   "repository": {
     "type": "git",
     "url": "https://github.com/NaturalCycles/abba"
   },
   "engines": {
-    "node": ">=14.15.0"
+    "node": ">=18.12.0"
   },
   "description": "AB test assignment configuration tool for Node.js",
   "author": "Natural Cycles Team",

package/readme.md

@@ -39,6 +39,8 @@
 - **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
+- **Start/End dates:** The timeframe that assignments will be generated for this experiment when
+  active
 
 <!-- BUILTWITH -->
 

package/src/abba.ts

@@ -10,7 +10,12 @@ import {
   GeneratedUserAssignment,
   UserAssignment,
 } from './types'
-import { determineAssignment, validateSegmentationRules, validateTotalBucketRatio } from './util'
+import {
+  canGenerateNewAssignments,
+  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'
@@ -161,7 +166,7 @@ export class Abba {
     if (existingOnly) return null
 
     const experiment = await this.experimentDao.requireById(experimentId)
-    if (experiment.status !== AssignmentStatus.Active) return null
+    if (!canGenerateNewAssignments(experiment)) return null
 
     _assert(segmentationData, 'Segmentation data required when creating a new assignment')
 
@@ -214,7 +219,7 @@ export class Abba {
           ...existing,
           bucketKey: experiment.buckets.find(b => b.id === existing.bucketId)?.key || null,
         })
-      } else if (!existingOnly && experiment.status === AssignmentStatus.Active) {
+      } else if (!existingOnly && canGenerateNewAssignments(experiment)) {
         const assignment = this.generateUserAssignmentData(experiment, userId, segmentationData)
         if (assignment) {
           const created = this.userAssignmentDao.create(assignment)

package/src/migrations/init.sql

@@ -16,6 +16,8 @@ CREATE TABLE IF NOT EXISTS `Experiment` (
     `status` INTEGER NOT NULL,
     `sampling` INTEGER NOT NULL,
     `description` VARCHAR(240) NULL,
+    `startDateIncl` DATE NOT NULL,
+    `endDateExcl` DATE NOT NULL,
     `created` INTEGER(11) NOT NULL,
     `updated` INTEGER(11) NOT NULL,
     `rules` JSON NULL,

package/src/types.ts

@@ -1,5 +1,5 @@
 import { CommonDB } from '@naturalcycles/db-lib'
-import { BaseDBEntity, Saved } from '@naturalcycles/js-lib'
+import { BaseDBEntity, IsoDateString, Saved } from '@naturalcycles/js-lib'
 
 export interface AbbaConfig {
   db: CommonDB
@@ -18,6 +18,8 @@ export type BaseExperiment = BaseDBEntity<number> & {
   status: number
   sampling: number
   description: string | null
+  startDateIncl: IsoDateString
+  endDateExcl: IsoDateString
 }
 
 export type Experiment = BaseExperiment & {
@@ -53,9 +55,18 @@ export type GeneratedUserAssignment = Saved<UserAssignment> & {
 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
+  /**
+   * Will return existing assignments and generate new assignments
+   */
+  Active = 1,
+  /**
+   * Will return existing assignments but not generate new assignments
+   */
+  Paused = 2,
+  /**
+   * Will not return any assignments
+   */
+  Inactive = 3,
 }
 
 export interface SegmentationRule {

package/src/util.ts

@@ -1,6 +1,6 @@
-import { Saved } from '@naturalcycles/js-lib'
+import { localDate, Saved } from '@naturalcycles/js-lib'
 import { satisfies } from 'semver'
-import { Bucket, SegmentationData, SegmentationRule } from './types'
+import { AssignmentStatus, Bucket, Experiment, SegmentationData, SegmentationRule } from './types'
 
 /**
  * Generate a random number between 0 and 100
@@ -92,7 +92,16 @@ export const validateSegmentationRule = (
     return new RegExp(value.toString()).test(data[key]?.toString() || '')
   } else if (operator === 'boolean') {
     return Boolean(value) === data[key]
-  } else {
-    return false
   }
+  return false
+}
+
+/**
+ * Returns true if an experiment is able to generate new assignments based on status and start/end dates
+ */
+export const canGenerateNewAssignments = (experiment: Experiment): boolean => {
+  return (
+    experiment.status === AssignmentStatus.Active &&
+    localDate().isBetween(experiment.startDateIncl, experiment.endDateExcl, '[)')
+  )
 }