@naturalcycles/abba 2.7.0 → 2.7.2

package/dist/abba.d.ts

@@ -1,6 +1,6 @@
 import type { Unsaved } from '@naturalcycles/js-lib/types';
-import { type GetAllExperimentsOpts } from './dao/experiment.dao.js';
-import type { AbbaConfig, Bucket, DecoratedUserAssignment, Experiment, ExperimentAssignmentStatistics, ExperimentWithBuckets, SegmentationData, UserExperiment } from './types.js';
+import type { GetAllExperimentsOpts } from './dao/experiment.dao.js';
+import type { AbbaConfig, Bucket, BucketInput, DecoratedUserAssignment, Experiment, ExperimentAssignmentStatistics, ExperimentInput, ExperimentWithBuckets, SegmentationData, UserExperiment } from './types.js';
 export declare class Abba {
     cfg: AbbaConfig;
     private experimentDao;
@@ -26,15 +26,12 @@ export declare class Abba {
      * Creates a new experiment.
      * Cold method.
      */
-    createExperiment(experiment: Experiment, buckets: Bucket[]): Promise<ExperimentWithBuckets>;
+    createExperiment(input: ExperimentInput, buckets: BucketInput[]): Promise<ExperimentWithBuckets>;
     /**
      * Update experiment information, will also validate the buckets' ratio if experiment.active is true
      * Cold method.
      */
     saveExperiment(experiment: Experiment, buckets: Unsaved<Bucket>[]): Promise<ExperimentWithBuckets>;
-    /**
-     * Ensures that mutual exclusions are maintained
-     */
     private updateExclusions;
     softDeleteExperiment(experimentId: string): Promise<void>;
     /**

package/dist/abba.js

@@ -15,11 +15,15 @@ import { canGenerateNewAssignments, generateUserAssignmentData, getUserExclusion
  */
 const CACHE_TTL = 600_000;
 export class Abba {
+    cfg;
+    experimentDao;
+    bucketDao;
+    userAssignmentDao;
     constructor(cfg) {
         this.cfg = cfg;
-        this.experimentDao = experimentDao(this.cfg.db);
-        this.bucketDao = bucketDao(this.cfg.db);
-        this.userAssignmentDao = userAssignmentDao(this.cfg.db);
+        this.experimentDao = experimentDao(cfg.db);
+        this.bucketDao = bucketDao(cfg.db);
+        this.userAssignmentDao = userAssignmentDao(cfg.db);
     }
     /**
      * Returns all experiments.
@@ -68,7 +72,7 @@ export class Abba {
     async mergeAssignmentsForUserIds(fromUserId, intoUserId) {
         const fromAssignments = await this.userAssignmentDao.getBy('userId', fromUserId);
         const existingIntoAssignments = await this.userAssignmentDao.getBy('userId', intoUserId);
-        await pMap(fromAssignments, async (from) => {
+        await pMap(fromAssignments, async from => {
             if (!existingIntoAssignments.some(into => into.experimentId === from.experimentId)) {
                 await this.userAssignmentDao.patch(from, { userId: intoUserId });
             }
@@ -78,10 +82,16 @@ export class Abba {
      * Creates a new experiment.
      * Cold method.
      */
-    async createExperiment(experiment, buckets) {
-        if (experiment.status === AssignmentStatus.Active) {
+    async createExperiment(input, buckets) {
+        if (input.status === AssignmentStatus.Active) {
             validateTotalBucketRatio(buckets);
         }
+        const experiment = {
+            ...input,
+            deleted: false,
+            description: input.description ?? null,
+            rules: input.rules ?? [],
+        };
         const created = await this.experimentDao.save(experiment);
         const createdbuckets = await this.bucketDao.saveBatch(buckets.map(b => ({ ...b, experimentId: created.id })));
         await this.updateExclusions(created.id, created.exclusions);
@@ -99,7 +109,7 @@ export class Abba {
             validateTotalBucketRatio(buckets);
         }
         const updatedExperiment = await this.experimentDao.save(experiment, { saveMethod: 'update' });
-        const updatedBuckets = await pMap(buckets, async (bucket) => {
+        const updatedBuckets = await pMap(buckets, async bucket => {
             return await this.bucketDao.save({ ...bucket, experimentId: updatedExperiment.id }, { saveMethod: bucket.id ? 'update' : undefined });
         });
         await this.updateExclusions(updatedExperiment.id, updatedExperiment.exclusions);
@@ -211,7 +221,7 @@ export class Abba {
      */
     async getAllExistingUserAssignments(userId) {
         const assignments = await this.userAssignmentDao.getBy('userId', userId);
-        return await pMap(assignments, async (assignment) => {
+        return await pMap(assignments, async assignment => {
             const experiment = await this.experimentDao.requireById(assignment.experimentId);
             const bucket = await this.bucketDao.getById(assignment.bucketId);
             return {
@@ -278,7 +288,7 @@ export class Abba {
     async getExperimentAssignmentStatistics(experimentId) {
         const totalAssignments = await this.userAssignmentDao.getCountByExperimentId(experimentId);
         const buckets = await this.bucketDao.getByExperimentId(experimentId);
-        const bucketAssignments = await pMap(buckets, async (bucket) => {
+        const bucketAssignments = await pMap(buckets, async bucket => {
             const totalAssignments = await this.userAssignmentDao.getCountByBucketId(bucket.id);
             return {
                 bucketId: bucket.id,

package/dist/dao/experiment.dao.js

@@ -47,7 +47,7 @@ export function experimentDao(db) {
  * For simplicity let's not do that by having this function...
  */
 function parseMySQLDate(date) {
-    // @ts-expect-error
+    // @ts-expect-error MySQL may return Date instead of string
     if (date instanceof Date)
         return localDate(date).toISODate();
     return date;

package/dist/types.d.ts

@@ -39,6 +39,18 @@ export type Experiment = BaseExperiment & {
     exclusions: string[];
     data: AnyObject | null;
 };
+export interface ExperimentInput {
+    id?: string;
+    key: string;
+    status: AssignmentStatus;
+    sampling: number;
+    description?: string | null;
+    rules: SegmentationRule[] | null;
+    startDateIncl: IsoDate;
+    endDateExcl: IsoDate;
+    exclusions: string[];
+    data: AnyObject | null;
+}
 export type ExperimentWithBuckets = Experiment & {
     buckets: Bucket[];
 };
@@ -50,6 +62,13 @@ export type BaseBucket = BaseDBEntity & {
 export type Bucket = BaseBucket & {
     data: AnyObject | null;
 };
+export interface BucketInput {
+    id?: string;
+    key: string;
+    ratio: number;
+    data: AnyObject | null;
+    experimentId?: string;
+}
 export type UserAssignment = BaseDBEntity & {
     userId: string;
     experimentId: string;

package/dist/types.js

@@ -1,4 +1,5 @@
-export var AssignmentStatus;
+export { AssignmentStatus };
+var AssignmentStatus;
 (function (AssignmentStatus) {
     /**
      * Will return existing assignments and generate new assignments
@@ -13,7 +14,8 @@ export var AssignmentStatus;
      */
     AssignmentStatus[AssignmentStatus["Inactive"] = 3] = "Inactive";
 })(AssignmentStatus || (AssignmentStatus = {}));
-export var SegmentationRuleOperator;
+export { SegmentationRuleOperator };
+var SegmentationRuleOperator;
 (function (SegmentationRuleOperator) {
     SegmentationRuleOperator["IsSet"] = "isSet";
     SegmentationRuleOperator["IsNotSet"] = "isNotSet";
@@ -21,7 +23,6 @@ export var SegmentationRuleOperator;
     SegmentationRuleOperator["NotEqualsText"] = "notEqualsText";
     SegmentationRuleOperator["Semver"] = "semver";
     SegmentationRuleOperator["Regex"] = "regex";
-    /* eslint-disable id-denylist */
     SegmentationRuleOperator["Boolean"] = "boolean";
     SegmentationRuleOperator["GreaterThan"] = "greaterThan";
     SegmentationRuleOperator["LessThan"] = "lessThan";

package/dist/util.d.ts

@@ -1,5 +1,5 @@
 import type { Unsaved } from '@naturalcycles/js-lib/types';
-import type { Bucket, ExclusionSet, Experiment, ExperimentWithBuckets, SegmentationData, SegmentationRule, SegmentationRuleFn, UserAssignment, UserExperiment } from './types.js';
+import type { Bucket, BucketInput, ExclusionSet, Experiment, ExperimentWithBuckets, SegmentationData, SegmentationRule, SegmentationRuleFn, UserAssignment, UserExperiment } from './types.js';
 import { SegmentationRuleOperator } from './types.js';
 /**
  * Generate a new assignment for a given user.
@@ -24,7 +24,7 @@ export declare function determineBucket(buckets: Bucket[]): Bucket;
 /**
  * Validate the total ratio of the buckets equals 100
  */
-export declare function validateTotalBucketRatio(buckets: Unsaved<Bucket>[]): void;
+export declare function validateTotalBucketRatio(buckets: (Unsaved<Bucket> | BucketInput)[]): void;
 /**
  * Validate a users segmentation data against multiple rules. Returns false if any fail
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/abba",
   "type": "module",
-  "version": "2.7.0",
+  "version": "2.7.2",
   "dependencies": {
     "@naturalcycles/db-lib": "^10",
     "@naturalcycles/js-lib": "^15",
@@ -11,6 +11,7 @@
   },
   "devDependencies": {
     "@types/semver": "^7",
+    "@typescript/native-preview": "7.0.0-dev.20260301.1",
     "@naturalcycles/dev-lib": "18.4.2"
   },
   "exports": {
@@ -35,7 +36,7 @@
     "directory": "packages/abba"
   },
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=24.10.0"
   },
   "description": "AB test assignment configuration tool for Node.js",
   "author": "Natural Cycles Team",

package/src/abba.ts

@@ -6,15 +6,18 @@ import { pMap } from '@naturalcycles/js-lib/promise/pMap.js'
 import type { Unsaved } from '@naturalcycles/js-lib/types'
 import { LRUMemoCache } from '@naturalcycles/nodejs-lib/lruMemoCache'
 import { bucketDao } from './dao/bucket.dao.js'
-import { experimentDao, type GetAllExperimentsOpts } from './dao/experiment.dao.js'
+import type { GetAllExperimentsOpts } from './dao/experiment.dao.js'
+import { experimentDao } from './dao/experiment.dao.js'
 import { userAssignmentDao } from './dao/userAssignment.dao.js'
 import type {
   AbbaConfig,
   Bucket,
   BucketAssignmentStatistics,
+  BucketInput,
   DecoratedUserAssignment,
   Experiment,
   ExperimentAssignmentStatistics,
+  ExperimentInput,
   ExperimentWithBuckets,
   SegmentationData,
   UserAssignment,
@@ -34,11 +37,15 @@ import {
 const CACHE_TTL = 600_000
 
 export class Abba {
-  private experimentDao = experimentDao(this.cfg.db)
-  private bucketDao = bucketDao(this.cfg.db)
-  private userAssignmentDao = userAssignmentDao(this.cfg.db)
-
-  constructor(public cfg: AbbaConfig) {}
+  private experimentDao
+  private bucketDao
+  private userAssignmentDao
+
+  constructor(public cfg: AbbaConfig) {
+    this.experimentDao = experimentDao(cfg.db)
+    this.bucketDao = bucketDao(cfg.db)
+    this.userAssignmentDao = userAssignmentDao(cfg.db)
+  }
 
   /**
    * Returns all experiments.
@@ -117,13 +124,20 @@ export class Abba {
    * Cold method.
    */
   async createExperiment(
-    experiment: Experiment,
-    buckets: Bucket[],
+    input: ExperimentInput,
+    buckets: BucketInput[],
   ): Promise<ExperimentWithBuckets> {
-    if (experiment.status === AssignmentStatus.Active) {
+    if (input.status === AssignmentStatus.Active) {
       validateTotalBucketRatio(buckets)
     }
 
+    const experiment = {
+      ...input,
+      deleted: false,
+      description: input.description ?? null,
+      rules: input.rules ?? [],
+    } satisfies Unsaved<Experiment>
+
     const created = await this.experimentDao.save(experiment)
     const createdbuckets = await this.bucketDao.saveBatch(
       buckets.map(b => ({ ...b, experimentId: created.id })),

package/src/dao/experiment.dao.ts

@@ -56,7 +56,7 @@ export function experimentDao(db: CommonDB): ExperimentDao {
  * For simplicity let's not do that by having this function...
  */
 function parseMySQLDate(date: string): IsoDate {
-  // @ts-expect-error
+  // @ts-expect-error MySQL may return Date instead of string
   if (date instanceof Date) return localDate(date).toISODate()
   return date as IsoDate
 }

package/src/types.ts

@@ -43,6 +43,19 @@ export type Experiment = BaseExperiment & {
   data: AnyObject | null
 }
 
+export interface ExperimentInput {
+  id?: string
+  key: string
+  status: AssignmentStatus
+  sampling: number
+  description?: string | null
+  rules: SegmentationRule[] | null
+  startDateIncl: IsoDate
+  endDateExcl: IsoDate
+  exclusions: string[]
+  data: AnyObject | null
+}
+
 export type ExperimentWithBuckets = Experiment & {
   buckets: Bucket[]
 }
@@ -57,6 +70,14 @@ export type Bucket = BaseBucket & {
   data: AnyObject | null
 }
 
+export interface BucketInput {
+  id?: string
+  key: string
+  ratio: number
+  data: AnyObject | null
+  experimentId?: string
+}
+
 export type UserAssignment = BaseDBEntity & {
   userId: string
   experimentId: string
@@ -100,7 +121,6 @@ export enum SegmentationRuleOperator {
   NotEqualsText = 'notEqualsText',
   Semver = 'semver',
   Regex = 'regex',
-  /* eslint-disable id-denylist */
   Boolean = 'boolean',
   GreaterThan = 'greaterThan',
   LessThan = 'lessThan',

package/src/util.ts

@@ -3,6 +3,7 @@ import type { Unsaved } from '@naturalcycles/js-lib/types'
 import { satisfies } from 'semver'
 import type {
   Bucket,
+  BucketInput,
   ExclusionSet,
   Experiment,
   ExperimentWithBuckets,
@@ -87,7 +88,7 @@ export function determineBucket(buckets: Bucket[]): Bucket {
 /**
  * Validate the total ratio of the buckets equals 100
  */
-export function validateTotalBucketRatio(buckets: Unsaved<Bucket>[]): void {
+export function validateTotalBucketRatio(buckets: (Unsaved<Bucket> | 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')