@naturalcycles/abba 2.8.0 → 2.10.0

package/dist/abba.d.ts

@@ -41,6 +41,7 @@ export declare class Abba {
      * Cold method.
      */
     deleteExperiment(experimentId: string): Promise<void>;
+    getExperimentWithBuckets(experimentId: string): Promise<ExperimentWithBuckets | undefined>;
     /**
      * Get an assignment for a given user. If existingOnly is false, it will attempt to generate a new assignment
      * Cold method.

package/dist/abba.js

@@ -8,7 +8,7 @@ import { LRUMemoCache } from '@naturalcycles/nodejs-lib/lruMemoCache';
 import { bucketDao } from './dao/bucket.dao.js';
 import { experimentDao } from './dao/experiment.dao.js';
 import { userAssignmentDao } from './dao/userAssignment.dao.js';
-import { AssignmentStatus } from './types.js';
+import { AbbaErrorCode, AssignmentStatus } from './types.js';
 import { canGenerateNewAssignments, generateUserAssignmentData, getUserExclusionSet, validateTotalBucketRatio, } from './util.js';
 /**
  * 10 minutes
@@ -150,12 +150,22 @@ export class Abba {
         const experiment = await this.experimentDao.requireById(experimentId);
         const hasBeenInactiveFor15Mins = experiment.status === AssignmentStatus.Inactive &&
             localTime(experiment.updated).isOlderThan(15, 'minute');
-        _assert(hasBeenInactiveFor15Mins, 'Experiment must be inactive for at least 15 minutes before deletion');
+        _assert(hasBeenInactiveFor15Mins, 'Experiment must be inactive for at least 15 minutes before deletion', { code: AbbaErrorCode.ExperimentDeletionTooSoon });
         await this.userAssignmentDao.deleteByExperimentId(experimentId);
         await this.bucketDao.deleteByExperimentId(experimentId);
         await this.experimentDao.deleteById(experimentId);
         await this.updateExclusions(experimentId, []);
     }
+    async getExperimentWithBuckets(experimentId) {
+        const experiment = await this.experimentDao.getById(experimentId);
+        if (!experiment)
+            return;
+        const buckets = await this.bucketDao.getByExperimentId(experiment.id);
+        return {
+            ...experiment,
+            buckets,
+        };
+    }
     /**
      * Get an assignment for a given user. If existingOnly is false, it will attempt to generate a new assignment
      * Cold method.
@@ -167,7 +177,9 @@ export class Abba {
      */
     async getUserAssignment(experimentKey, userId, existingOnly, segmentationData) {
         const experiment = await this.experimentDao.getByKey(experimentKey);
-        _assert(experiment, `Experiment does not exist: ${experimentKey}`);
+        _assert(experiment, `Experiment does not exist: ${experimentKey}`, {
+            code: AbbaErrorCode.ExperimentNotFound,
+        });
         // Inactive experiments should never return an assignment
         if (experiment.status === AssignmentStatus.Inactive) {
             return null;
@@ -193,7 +205,9 @@ export class Abba {
         if (!canGenerateNewAssignments(experiment, exclusionSet)) {
             return null;
         }
-        _assert(segmentationData, 'Segmentation data required when creating a new assignment');
+        _assert(segmentationData, 'Segmentation data required when creating a new assignment', {
+            code: AbbaErrorCode.SegmentationDataRequired,
+        });
         const experimentWithBuckets = { ...experiment, buckets };
         const assignment = generateUserAssignmentData(experimentWithBuckets, userId, segmentationData);
         if (!assignment) {

package/dist/types.d.ts

@@ -1,5 +1,12 @@
 import type { CommonDB } from '@naturalcycles/db-lib';
 import type { AnyObject, BaseDBEntity, IsoDate } from '@naturalcycles/js-lib/types';
+export declare const AbbaErrorCode: {
+    readonly ExperimentNotFound: 'abba/experimentNotFound';
+    readonly ExperimentDeletionTooSoon: 'abba/experimentDeletionTooSoon';
+    readonly SegmentationDataRequired: 'abba/segmentationDataRequired';
+    readonly InvalidBucketRatio: 'abba/invalidBucketRatio';
+    readonly BucketDeterminationFailed: 'abba/bucketDeterminationFailed';
+};
 export interface AbbaConfig {
     db: CommonDB;
 }

package/dist/types.js

@@ -1,3 +1,10 @@
+export const AbbaErrorCode = {
+    ExperimentNotFound: 'abba/experimentNotFound',
+    ExperimentDeletionTooSoon: 'abba/experimentDeletionTooSoon',
+    SegmentationDataRequired: 'abba/segmentationDataRequired',
+    InvalidBucketRatio: 'abba/invalidBucketRatio',
+    BucketDeterminationFailed: 'abba/bucketDeterminationFailed',
+};
 export var AssignmentStatus;
 (function (AssignmentStatus) {
     /**

package/dist/util.js

@@ -1,6 +1,7 @@
 import { localDate } from '@naturalcycles/js-lib/datetime';
+import { _assert } from '@naturalcycles/js-lib/error/assert.js';
 import { satisfies } from 'semver';
-import { AssignmentStatus, SegmentationRuleOperator } from './types.js';
+import { AbbaErrorCode, AssignmentStatus, SegmentationRuleOperator } from './types.js';
 /**
  * Generate a new assignment for a given user.
  * Doesn't save it.
@@ -53,9 +54,9 @@ export function determineBucket(buckets) {
             return b;
         }
     });
-    if (!bucket) {
-        throw new Error('Could not detetermine bucket from ratios');
-    }
+    _assert(bucket, 'Could not determine bucket from ratios', {
+        code: AbbaErrorCode.BucketDeterminationFailed,
+    });
     return bucket;
 }
 /**
@@ -63,9 +64,7 @@ export function determineBucket(buckets) {
  */
 export function validateTotalBucketRatio(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');
-    }
+    _assert(bucketSum === 100, 'Total bucket ratio must be 100 before you can activate an experiment', { code: AbbaErrorCode.InvalidBucketRatio });
 }
 /**
  * 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.8.0",
+  "version": "2.10.0",
   "dependencies": {
     "@naturalcycles/db-lib": "^10",
     "@naturalcycles/js-lib": "^15",
@@ -11,8 +11,8 @@
   },
   "devDependencies": {
     "@types/semver": "^7",
-    "@typescript/native-preview": "7.0.0-dev.20260401.1",
-    "@naturalcycles/dev-lib": "20.42.0"
+    "@typescript/native-preview": "7.0.0-dev.20260415.1",
+    "@naturalcycles/dev-lib": "18.4.2"
   },
   "exports": {
     ".": "./dist/index.js"

package/src/abba.ts

@@ -23,7 +23,7 @@ import type {
   UserAssignment,
   UserExperiment,
 } from './types.js'
-import { AssignmentStatus } from './types.js'
+import { AbbaErrorCode, AssignmentStatus } from './types.js'
 import {
   canGenerateNewAssignments,
   generateUserAssignmentData,
@@ -233,6 +233,7 @@ export class Abba {
     _assert(
       hasBeenInactiveFor15Mins,
       'Experiment must be inactive for at least 15 minutes before deletion',
+      { code: AbbaErrorCode.ExperimentDeletionTooSoon },
     )
 
     await this.userAssignmentDao.deleteByExperimentId(experimentId)
@@ -241,6 +242,17 @@ export class Abba {
     await this.updateExclusions(experimentId, [])
   }
 
+  async getExperimentWithBuckets(experimentId: string): Promise<ExperimentWithBuckets | undefined> {
+    const experiment = await this.experimentDao.getById(experimentId)
+    if (!experiment) return
+
+    const buckets = await this.bucketDao.getByExperimentId(experiment.id)
+    return {
+      ...experiment,
+      buckets,
+    }
+  }
+
   /**
    * Get an assignment for a given user. If existingOnly is false, it will attempt to generate a new assignment
    * Cold method.
@@ -257,7 +269,9 @@ export class Abba {
     segmentationData?: SegmentationData,
   ): Promise<DecoratedUserAssignment | null> {
     const experiment = await this.experimentDao.getByKey(experimentKey)
-    _assert(experiment, `Experiment does not exist: ${experimentKey}`)
+    _assert(experiment, `Experiment does not exist: ${experimentKey}`, {
+      code: AbbaErrorCode.ExperimentNotFound,
+    })
 
     // Inactive experiments should never return an assignment
     if (experiment.status === AssignmentStatus.Inactive) {
@@ -291,7 +305,9 @@ export class Abba {
       return null
     }
 
-    _assert(segmentationData, 'Segmentation data required when creating a new assignment')
+    _assert(segmentationData, 'Segmentation data required when creating a new assignment', {
+      code: AbbaErrorCode.SegmentationDataRequired,
+    })
 
     const experimentWithBuckets = { ...experiment, buckets }
     const assignment = generateUserAssignmentData(experimentWithBuckets, userId, segmentationData)

package/src/types.ts

@@ -1,6 +1,14 @@
 import type { CommonDB } from '@naturalcycles/db-lib'
 import type { AnyObject, BaseDBEntity, IsoDate } from '@naturalcycles/js-lib/types'
 
+export const AbbaErrorCode = {
+  ExperimentNotFound: 'abba/experimentNotFound',
+  ExperimentDeletionTooSoon: 'abba/experimentDeletionTooSoon',
+  SegmentationDataRequired: 'abba/segmentationDataRequired',
+  InvalidBucketRatio: 'abba/invalidBucketRatio',
+  BucketDeterminationFailed: 'abba/bucketDeterminationFailed',
+} as const
+
 export interface AbbaConfig {
   db: CommonDB
 }

package/src/util.ts

@@ -1,4 +1,5 @@
 import { localDate } from '@naturalcycles/js-lib/datetime'
+import { _assert } from '@naturalcycles/js-lib/error/assert.js'
 import type { Unsaved } from '@naturalcycles/js-lib/types'
 import { satisfies } from 'semver'
 import type {
@@ -13,7 +14,7 @@ import type {
   UserAssignment,
   UserExperiment,
 } from './types.js'
-import { AssignmentStatus, SegmentationRuleOperator } from './types.js'
+import { AbbaErrorCode, AssignmentStatus, SegmentationRuleOperator } from './types.js'
 
 /**
  * Generate a new assignment for a given user.
@@ -78,9 +79,9 @@ export function determineBucket(buckets: Bucket[]): Bucket {
     }
   })
 
-  if (!bucket) {
-    throw new Error('Could not detetermine bucket from ratios')
-  }
+  _assert(bucket, 'Could not determine bucket from ratios', {
+    code: AbbaErrorCode.BucketDeterminationFailed,
+  })
 
   return bucket
 }
@@ -90,9 +91,11 @@ export function determineBucket(buckets: Bucket[]): Bucket {
  */
 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')
-  }
+  _assert(
+    bucketSum === 100,
+    'Total bucket ratio must be 100 before you can activate an experiment',
+    { code: AbbaErrorCode.InvalidBucketRatio },
+  )
 }
 
 /**