pass subject to assignment function

Author: ploomiz

docs/js-client-sdk.attributevaluetype.md

@@ -18,6 +18,4 @@ export interface IClientConfig
 |  --- | --- | --- |
 |  [apiKey](./js-client-sdk.iclientconfig.apikey.md) | string | Eppo API key |
 |  [baseUrl?](./js-client-sdk.iclientconfig.baseurl.md) | string | <i>(Optional)</i> Base URL of the Eppo API. Clients should use the default setting in most cases. |
-|  [subjectAttributes?](./js-client-sdk.iclientconfig.subjectattributes.md) | Record&lt;string, [AttributeValueType](./js-client-sdk.attributevaluetype.md)<!-- -->&gt; | <i>(Optional)</i> Optional attributes associated with the subject, for example name and email. The subject attributes are used for evaluating any targeting rules tied to the experiment. |
-|  [subjectKey](./js-client-sdk.iclientconfig.subjectkey.md) | string | An identifier of the experiment subject, for example a user ID. |
 

docs/js-client-sdk.iclientconfig.md

@@ -9,14 +9,16 @@ Maps a subject to a variation for a given experiment.
 <b>Signature:</b>
 
 ```typescript
-getAssignment(experimentKey: string): string;
+getAssignment(subjectKey: string, experimentKey: string, subjectAttributes?: Record<string, any>): string;
 ```
 
 ## Parameters
 
 |  Parameter | Type | Description |
 |  --- | --- | --- |
+|  subjectKey | string | an identifier of the experiment subject, for example a user ID. |
 |  experimentKey | string | experiment identifier |
+|  subjectAttributes | Record&lt;string, any&gt; | <i>(Optional)</i> optional attributes associated with the subject, for example name and email. The subject attributes are used for evaluating any targeting rules tied to the experiment. |
 
 <b>Returns:</b>
 

docs/js-client-sdk.iclientconfig.subjectattributes.md

@@ -16,5 +16,5 @@ export interface IEppoClient
 
 |  Method | Description |
 |  --- | --- |
-|  [getAssignment(experimentKey)](./js-client-sdk.ieppoclient.getassignment.md) | Maps a subject to a variation for a given experiment. |
+|  [getAssignment(subjectKey, experimentKey, subjectAttributes)](./js-client-sdk.ieppoclient.getassignment.md) | Maps a subject to a variation for a given experiment. |
 

docs/js-client-sdk.iclientconfig.subjectkey.md

@@ -18,9 +18,3 @@
 |  [IClientConfig](./js-client-sdk.iclientconfig.md) | Configuration used for initializing the Eppo client |
 |  [IEppoClient](./js-client-sdk.ieppoclient.md) | Client for assigning experiment variations. |
 
-## Type Aliases
-
-|  Type Alias | Description |
-|  --- | --- |
-|  [AttributeValueType](./js-client-sdk.attributevaluetype.md) |  |
-

docs/js-client-sdk.ieppoclient.getassignment.md

@@ -4,23 +4,18 @@
 
 ```ts
 
-// @public (undocumented)
-export type AttributeValueType = string | number;
-
 // @public
 export function getInstance(): IEppoClient;
 
 // @public
 export interface IClientConfig {
     apiKey: string;
     baseUrl?: string;
-    subjectAttributes?: Record<string, AttributeValueType>;
-    subjectKey: string;
 }
 
 // @public
 export interface IEppoClient {
-    getAssignment(experimentKey: string): string;
+    getAssignment(subjectKey: string, experimentKey: string, subjectAttributes?: Record<string, any>): string;
 }
 
 // @public

docs/js-client-sdk.ieppoclient.md

@@ -12,10 +12,10 @@ import ExperimentConfigurationRequestor from './experiment/experiment-configurat
 import { IVariation } from './experiment/variation';
 import { OperatorType } from './rule';
 
-import { init } from '.';
+import { getInstance, init } from '.';
 
 describe('EppoClient E2E test', () => {
-  beforeAll(() => {
+  beforeAll(async () => {
     window.sessionStorage.clear();
     mock.setup();
     mock.get(/randomized_assignment\/config*/, (_req, res) => {
@@ -34,6 +34,7 @@ describe('EppoClient E2E test', () => {
       });
       return res.status(200).body(JSON.stringify({ experiments: assignmentConfig }));
     });
+    await init({ apiKey: 'dummy', baseUrl: 'http://127.0.0.1:4000' });
   });
 
   afterAll(() => {
@@ -51,7 +52,7 @@ describe('EppoClient E2E test', () => {
         expectedAssignments,
       }: IAssignmentTestCase) => {
         console.log(`---- Test Case for ${experiment} Experiment ----`);
-        const assignments = await getAssignments(subjects, experiment);
+        const assignments = getAssignments(subjects, experiment);
         // verify the assingments don't change across test runs (deterministic)
         expect(assignments).toEqual(expectedAssignments);
         const expectedVariationSplitPercentage = percentExposure / variations.length;
@@ -99,8 +100,8 @@ describe('EppoClient E2E test', () => {
         a90ea45116d251a43da56e03d3dd7275: 'variant-2',
       },
     });
-    const client = new EppoClient('subject-1', mockConfigRequestor);
-    const assignment = client.getAssignment(experiment);
+    const client = new EppoClient(mockConfigRequestor);
+    const assignment = client.getAssignment('subject-1', experiment);
     expect(assignment).toEqual('variant-2');
   });
 
@@ -141,14 +142,12 @@ describe('EppoClient E2E test', () => {
         },
       ],
     });
-    let client = new EppoClient('subject-1', mockConfigRequestor, { appVersion: 9 });
-    let assignment = client.getAssignment(experiment);
+    const client = new EppoClient(mockConfigRequestor);
+    let assignment = client.getAssignment('subject-1', experiment, { appVersion: 9 });
     expect(assignment).toEqual(null);
-    client = new EppoClient('subject-1', mockConfigRequestor);
-    assignment = client.getAssignment(experiment);
+    assignment = client.getAssignment('subject-1', experiment);
     expect(assignment).toEqual(null);
-    client = new EppoClient('subject-1', mockConfigRequestor, { appVersion: 11 });
-    assignment = client.getAssignment(experiment);
+    assignment = client.getAssignment('subject-1', experiment, { appVersion: 11 });
     expect(assignment).toEqual('control');
   });
 
@@ -172,17 +171,10 @@ describe('EppoClient E2E test', () => {
     expect(percentage).toBeLessThanOrEqual(expectedPercentage + 0.05);
   }
 
-  async function getAssignments(subjects: string[], experiment: string): Promise<string[]> {
-    const assignments: string[] = [];
-    for (const subjectKey of subjects) {
-      const client = await init({
-        apiKey: 'dummy',
-        baseUrl: 'http://127.0.0.1:4000',
-        subjectKey,
-      });
-      const assignment = client.getAssignment(experiment);
-      assignments.push(assignment);
-    }
-    return assignments;
+  function getAssignments(subjects: string[], experiment: string): string[] {
+    const client = getInstance();
+    return subjects.map((subjectKey) => {
+      return client.getAssignment(subjectKey, experiment);
+    });
   }
 });

docs/js-client-sdk.md

@@ -2,7 +2,7 @@ import { createHash } from 'crypto';
 
 import { IExperimentConfiguration } from './experiment/experiment-configuration';
 import ExperimentConfigurationRequestor from './experiment/experiment-configuration-requestor';
-import { Rule } from './experiment/rule';
+import { Rule } from './rule';
 import { matchesAnyRule } from './rule_evaluator';
 import { getShard, isShardInRange } from './shard';
 import { validateNotBlank } from './validation';
@@ -15,48 +15,57 @@ export interface IEppoClient {
   /**
    * Maps a subject to a variation for a given experiment.
    *
+   * @param subjectKey an identifier of the experiment subject, for example a user ID.
    * @param experimentKey experiment identifier
+   * @param subjectAttributes optional attributes associated with the subject, for example name and email.
+   * The subject attributes are used for evaluating any targeting rules tied to the experiment.
    * @returns a variation value if the subject is part of the experiment sample, otherwise null
    * @public
    */
-  getAssignment(experimentKey: string): string;
+  getAssignment(
+    subjectKey: string,
+    experimentKey: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    subjectAttributes?: Record<string, any>,
+  ): string;
 }
 
 export default class EppoClient implements IEppoClient {
-  constructor(
-    private subjectKey: string,
-    private configurationRequestor: ExperimentConfigurationRequestor,
-    private subjectAttributes = {},
-  ) {}
+  constructor(private configurationRequestor: ExperimentConfigurationRequestor) {}
 
-  getAssignment(experimentKey: string): string {
+  getAssignment(subjectKey: string, experimentKey: string, subjectAttributes = {}): string {
+    validateNotBlank(subjectKey, 'Invalid argument: subjectKey cannot be blank');
     validateNotBlank(experimentKey, 'Invalid argument: experimentKey cannot be blank');
     const experimentConfig = this.configurationRequestor.getConfiguration(experimentKey);
     if (
       !experimentConfig?.enabled ||
-      !this.subjectAttributesSatisfyRules(experimentConfig.rules) ||
-      !this.isInExperimentSample(experimentKey, experimentConfig)
+      !this.subjectAttributesSatisfyRules(subjectAttributes, experimentConfig.rules) ||
+      !this.isInExperimentSample(subjectKey, experimentKey, experimentConfig)
     ) {
       return null;
     }
-    const override = this.getSubjectVariationOverride(experimentConfig);
+    const override = this.getSubjectVariationOverride(subjectKey, experimentConfig);
     if (override) {
       return override;
     }
     const { variations, subjectShards } = experimentConfig;
-    const shard = getShard(`assignment-${this.subjectKey}-${experimentKey}`, subjectShards);
+    const shard = getShard(`assignment-${subjectKey}-${experimentKey}`, subjectShards);
     return variations.find((variation) => isShardInRange(shard, variation.shardRange)).name;
   }
 
-  private subjectAttributesSatisfyRules(rules?: Rule[]) {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  private subjectAttributesSatisfyRules(subjectAttributes?: Record<string, any>, rules?: Rule[]) {
     if (!rules || rules.length === 0) {
       return true;
     }
-    return matchesAnyRule(this.subjectAttributes || {}, rules);
+    return matchesAnyRule(subjectAttributes || {}, rules);
   }
 
-  private getSubjectVariationOverride(experimentConfig: IExperimentConfiguration): string {
-    const subjectHash = createHash('md5').update(this.subjectKey).digest('hex');
+  private getSubjectVariationOverride(
+    subjectKey: string,
+    experimentConfig: IExperimentConfiguration,
+  ): string {
+    const subjectHash = createHash('md5').update(subjectKey).digest('hex');
     return experimentConfig.overrides[subjectHash];
   }
 
@@ -66,11 +75,12 @@ export default class EppoClient implements IEppoClient {
    * Given a hash function output (bucket), check whether the bucket is between 0 and exposure_percent * total_buckets.
    */
   private isInExperimentSample(
+    subjectKey: string,
     experimentKey: string,
     experimentConfig: IExperimentConfiguration,
   ): boolean {
     const { percentExposure, subjectShards } = experimentConfig;
-    const shard = getShard(`exposure-${this.subjectKey}-${experimentKey}`, subjectShards);
+    const shard = getShard(`exposure-${subjectKey}-${experimentKey}`, subjectShards);
     return shard <= percentExposure * subjectShards;
   }
 }