@eventvisor/sdk 0.0.2

package/src/attributesManager.ts

@@ -0,0 +1,181 @@
+import type { AttributeName, Value } from "@eventvisor/types";
+
+import type { GetDatafileReader } from "./datafileReader";
+import type { GetConditionsChecker } from "./conditions";
+import type { ModulesManager } from "./modulesManager";
+import type { Emitter } from "./emitter";
+import type { Logger } from "./logger";
+import type { GetTransformer } from "./transformer";
+import type { Validator } from "./validator";
+import { initializeFromStorage, persistEntity, removeEntity } from "./persister";
+
+export type AttributesMap = Record<AttributeName, Value>;
+
+export interface AttributesManagerOptions {
+  logger: Logger;
+  emitter: Emitter;
+  getDatafileReader: GetDatafileReader;
+  getTransformer: GetTransformer;
+  getConditionsChecker: GetConditionsChecker;
+  validator: Validator;
+  modulesManager: ModulesManager;
+}
+
+export class AttributesManager {
+  private logger: Logger;
+  private getDatafileReader: GetDatafileReader;
+  private emitter: Emitter;
+  private getTransformer: GetTransformer;
+  private getConditionsChecker: GetConditionsChecker;
+  private validator: Validator;
+  private modulesManager: ModulesManager;
+
+  private attributesMap: AttributesMap;
+
+  constructor(options: AttributesManagerOptions) {
+    const {
+      logger,
+      getDatafileReader,
+      emitter,
+      getTransformer,
+      getConditionsChecker,
+      validator,
+      modulesManager,
+    } = options;
+
+    this.logger = logger;
+    this.getDatafileReader = getDatafileReader;
+    this.emitter = emitter;
+    this.getTransformer = getTransformer;
+    this.getConditionsChecker = getConditionsChecker;
+    this.validator = validator;
+    this.modulesManager = modulesManager;
+
+    // @TODO: initial attributes from SDK options
+    this.attributesMap = {};
+  }
+
+  async initialize(): Promise<void> {
+    // read form storage
+    await this.initializeFromStorage();
+  }
+
+  private async initializeFromStorage(): Promise<void> {
+    const datafileReader = this.getDatafileReader();
+
+    const result = await initializeFromStorage({
+      datafileReader,
+      conditionsChecker: this.getConditionsChecker(),
+      modulesManager: this.modulesManager,
+      storageKeyPrefix: "attributes_",
+      getEntityNames: () => datafileReader.getAttributeNames(),
+      getEntity: (entityName: string) => datafileReader.getAttribute(entityName),
+    });
+
+    this.attributesMap = result;
+  }
+
+  async setAttribute(attributeName: AttributeName, value: Value): Promise<Value | null> {
+    const datafileReader = this.getDatafileReader();
+
+    /**
+     * Find
+     */
+    const attributeSchema = datafileReader.getAttribute(attributeName);
+
+    if (!attributeSchema) {
+      this.logger.error(`Attribute schema not found`, {
+        attributeName,
+      });
+
+      return null;
+    }
+
+    /**
+     * Deprecated
+     */
+    if (attributeSchema.deprecated) {
+      this.logger.warn(`Attribute is deprecated`, { attributeName });
+    }
+
+    /**
+     * Validate
+     */
+    const validationResult = await this.validator.validate(attributeSchema, value);
+
+    if (!validationResult.valid) {
+      this.logger.warn(`Attribute validation failed`, {
+        attributeName,
+        errors: validationResult.errors,
+      });
+
+      return null;
+    }
+
+    const validatedValue = validationResult.value;
+
+    /**
+     * Transform
+     */
+    const transformedValue = attributeSchema.transforms
+      ? await this.getTransformer().applyAll(validatedValue, attributeSchema.transforms, {
+          payload: validatedValue,
+          attributeName,
+        })
+      : validatedValue;
+
+    /**
+     * Set
+     */
+    this.attributesMap[attributeName] = transformedValue;
+
+    this.emitter.trigger("attribute_set", { attributeName });
+    this.logger.debug(`Attribute set`, { attributeName });
+
+    /**
+     * Persist
+     */
+    await persistEntity({
+      datafileReader,
+      conditionsChecker: this.getConditionsChecker(),
+      modulesManager: this.modulesManager,
+      storageKeyPrefix: "attributes_",
+      entityName: attributeName,
+      entity: attributeSchema,
+      value,
+    });
+
+    return transformedValue;
+  }
+
+  isAttributeSet(attributeName: AttributeName): boolean {
+    return this.attributesMap[attributeName] !== undefined;
+  }
+
+  getAttributesMap(): AttributesMap {
+    return this.attributesMap;
+  }
+
+  getAttributeValue(attributeName: AttributeName): Value | null {
+    return this.attributesMap[attributeName] || null;
+  }
+
+  async removeAttribute(attributeName: AttributeName): Promise<void> {
+    const datafileReader = this.getDatafileReader();
+
+    await removeEntity({
+      datafileReader,
+      conditionsChecker: this.getConditionsChecker(),
+      modulesManager: this.modulesManager,
+      storageKeyPrefix: "attributes_",
+      entityName: attributeName,
+      entity: datafileReader.getAttribute(attributeName),
+    });
+
+    delete this.attributesMap[attributeName];
+
+    this.emitter.trigger("attribute_removed", {
+      attributeName,
+    });
+  }
+}

package/src/bucketer.spec.ts

@@ -0,0 +1,156 @@
+import { Transformer } from "./transformer";
+import { emptyDatafile, DatafileReader } from "./datafileReader";
+import { createLogger } from "./logger";
+import { ModulesManager } from "./modulesManager";
+import { EffectsManager } from "./effectsManager";
+import { AttributesManager } from "./attributesManager";
+import { SourceResolver } from "./sourceResolver";
+import { ConditionsChecker } from "./conditions";
+import { Emitter } from "./emitter";
+import { Validator } from "./validator";
+import { Bucketer } from "./bucketer";
+
+describe("Bucketer", () => {
+  // initialize the dependencies
+  const emitter = new Emitter();
+
+  const logger = createLogger({ level: "fatal" });
+
+  const datafileReader = new DatafileReader({
+    datafile: {
+      ...emptyDatafile,
+      attributes: {
+        ...emptyDatafile.attributes,
+        userId: {
+          type: "string",
+        },
+        deviceId: {
+          type: "string",
+        },
+      },
+    },
+    logger,
+  });
+
+  const modulesManager = new ModulesManager({
+    logger,
+    getDatafileReader: () => datafileReader,
+    getSourceResolver: () => sourceResolver,
+  });
+
+  const validator = new Validator({
+    logger,
+    getSourceResolver: () => sourceResolver,
+  });
+
+  const attributesManager = new AttributesManager({
+    logger,
+    emitter,
+    validator,
+    getDatafileReader: () => datafileReader,
+    getTransformer: () => transformer,
+    getConditionsChecker: () => conditionsChecker,
+    modulesManager,
+  });
+
+  const effectsManager = new EffectsManager({
+    logger,
+    getDatafileReader: () => datafileReader,
+    getTransformer: () => transformer,
+    getConditionsChecker: () => conditionsChecker,
+    modulesManager: modulesManager,
+  });
+
+  const sourceResolver = new SourceResolver({
+    logger,
+    modulesManager,
+    attributesManager,
+    effectsManager,
+  });
+
+  const conditionsChecker = new ConditionsChecker({
+    logger,
+    getRegex: (regexString, regexFlags) => new RegExp(regexString, regexFlags),
+    sourceResolver,
+  });
+
+  const transformer = new Transformer({
+    logger,
+    conditionsChecker,
+    sourceResolver,
+  });
+
+  const bucketer = new Bucketer({
+    logger,
+    sourceResolver,
+    conditionsChecker,
+    transformer,
+  });
+
+  /**
+   * Get bucket key
+   */
+  describe("getBucketKey", () => {
+    it("should get bucket key: plain string", async () => {
+      expect(
+        await bucketer.getBucketKey(
+          // sampleBy
+          { source: "payload.age" },
+
+          // inputs
+          { payload: { age: 25 } },
+        ),
+      ).toEqual("25");
+    });
+
+    it("should get bucket key: multiple plain strings", async () => {
+      expect(
+        await bucketer.getBucketKey(
+          // sampleBy
+          [{ source: "payload.age" }, { source: "payload.name" }],
+
+          // inputs
+          { payload: { age: 25, name: "John" } },
+        ),
+      ).toEqual("25.John");
+    });
+
+    it("should get bucket key: from attributes", async () => {
+      await attributesManager.setAttribute("userId", "user-123");
+      await attributesManager.setAttribute("deviceId", "device-234");
+
+      // single attribute
+      expect(
+        await bucketer.getBucketKey(
+          // sampleBy
+          { attribute: "userId" },
+
+          // inputs
+          {},
+        ),
+      ).toEqual("user-123");
+
+      // multiple attributes
+      expect(
+        await bucketer.getBucketKey(
+          // sampleBy
+          [{ attribute: "userId" }, { attribute: "deviceId" }],
+
+          // inputs
+          {},
+        ),
+      ).toEqual("user-123.device-234");
+
+      // or
+      expect(
+        await bucketer.getBucketKey(
+          // sampleBy
+          { or: [{ attribute: "userId" }, { attribute: "deviceId" }] },
+
+          // inputs
+          {},
+        ),
+      ).toEqual("user-123");
+    });
+  });
+});

package/src/bucketer.ts

@@ -0,0 +1,152 @@
+import type { Sample, SampleBy, Inputs } from "@eventvisor/types";
+
+import type { Logger } from "./logger";
+import { MurmurHashV3 } from "./murmurhash";
+import type { SourceResolver } from "./sourceResolver";
+import type { ConditionsChecker } from "./conditions";
+import type { Transformer } from "./transformer";
+
+export type BucketKey = string;
+export type BucketValue = number; // 0 to 100,000 (100% * 1000 to include three decimal places in same integer)
+
+/**
+ * Generic hashing
+ */
+const HASH_SEED = 1;
+const MAX_HASH_VALUE = Math.pow(2, 32);
+
+export const MAX_BUCKETED_NUMBER = 100000; // 100% * 1000 to include three decimal places in the same integer value
+
+export function getBucketedNumber(bucketKey: string): BucketValue {
+  const hashValue = MurmurHashV3(bucketKey, HASH_SEED);
+  const ratio = hashValue / MAX_HASH_VALUE;
+
+  return Math.floor(ratio * MAX_BUCKETED_NUMBER);
+}
+
+/**
+ * Bucket key
+ */
+const DEFAULT_BUCKET_KEY_SEPARATOR = ".";
+
+export class BucketerOptions {
+  logger: Logger;
+  sourceResolver: SourceResolver;
+  conditionsChecker: ConditionsChecker;
+  transformer: Transformer;
+}
+
+export interface SampleResult {
+  isSampled: boolean;
+  matchedSample?: Sample;
+  bucketedNumber?: number;
+  bucketKey?: BucketKey;
+}
+
+export class Bucketer {
+  private logger: Logger;
+  private sourceResolver: SourceResolver;
+  private conditionsChecker: ConditionsChecker;
+  private transformer: Transformer;
+
+  constructor(options: BucketerOptions) {
+    this.logger = options.logger;
+    this.sourceResolver = options.sourceResolver;
+    this.conditionsChecker = options.conditionsChecker;
+    this.transformer = options.transformer;
+  }
+
+  async getBucketKey(sampleBy: SampleBy, inputs: Inputs): Promise<BucketKey> {
+    let type;
+    let sources;
+
+    if (typeof sampleBy === "string") {
+      type = "plain";
+      sources = [sampleBy];
+    } else if (Array.isArray(sampleBy)) {
+      type = "and";
+      sources = sampleBy;
+    } else if (typeof sampleBy === "object" && "or" in sampleBy && Array.isArray(sampleBy.or)) {
+      type = "or";
+      sources = sampleBy.or;
+    } else if (typeof sampleBy === "object") {
+      type = "and";
+      sources = [sampleBy];
+    } else {
+      this.logger.error("invalid sampleBy", { sampleBy });
+
+      throw new Error("invalid sampleBy");
+    }
+
+    const bucketKey: string[] = [];
+
+    for (const source of sources) {
+      const sourceValue = await this.sourceResolver.resolve(source, inputs);
+
+      if (typeof sourceValue === "undefined") {
+        continue;
+      }
+
+      if (type === "plain" || type === "and") {
+        bucketKey.push(String(sourceValue));
+      } else {
+        // or
+        if (bucketKey.length === 0) {
+          bucketKey.push(String(sourceValue));
+        }
+      }
+    }
+
+    return bucketKey.join(DEFAULT_BUCKET_KEY_SEPARATOR);
+  }
+
+  async isSampled(sample: Sample | Sample[], inputs: Inputs): Promise<SampleResult> {
+    const samples = Array.isArray(sample) ? sample : [sample];
+
+    const matchedSample = samples.find(async (sample) => {
+      if (!sample.conditions) {
+        return true;
+      }
+
+      const isMatched = await this.conditionsChecker.allAreMatched(sample.conditions, inputs);
+
+      return isMatched;
+    });
+
+    if (matchedSample) {
+      const bucketKey = await this.getBucketKey(matchedSample.by, inputs);
+
+      const bucketedNumber = getBucketedNumber(bucketKey);
+
+      if (
+        matchedSample.percentage &&
+        matchedSample.percentage > 0 &&
+        bucketedNumber < matchedSample.percentage
+      ) {
+        return {
+          isSampled: false,
+          matchedSample,
+          bucketedNumber,
+          bucketKey,
+        };
+      }
+
+      if (
+        matchedSample.range &&
+        bucketedNumber < matchedSample.range[0] &&
+        bucketedNumber > matchedSample.range[1]
+      ) {
+        return {
+          isSampled: false,
+          matchedSample,
+          bucketedNumber,
+          bucketKey,
+        };
+      }
+    }
+
+    return {
+      isSampled: true,
+    };
+  }
+}

package/src/compareVersions.ts

@@ -0,0 +1,93 @@
+// taken from: https://github.com/omichelsen/compare-versions
+// this is done to avoid loading the whole package
+
+/*
+The MIT License (MIT)
+
+Copyright (c) 2015-2021 Ole Michelsen
+
+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.
+ */
+
+export const semver =
+  /^[v^~<>=]*?(\d+)(?:\.([x*]|\d+)(?:\.([x*]|\d+)(?:\.([x*]|\d+))?(?:-([\da-z\-]+(?:\.[\da-z\-]+)*))?(?:\+[\da-z\-]+(?:\.[\da-z\-]+)*)?)?)?$/i;
+
+export const validateAndParse = (version: string) => {
+  if (typeof version !== "string") {
+    throw new TypeError("Invalid argument expected string");
+  }
+  const match = version.match(semver);
+  if (!match) {
+    throw new Error(`Invalid argument not valid semver ('${version}' received)`);
+  }
+  match.shift();
+  return match;
+};
+
+const isWildcard = (s: string) => s === "*" || s === "x" || s === "X";
+
+const forceType = (a: string | number, b: string | number) =>
+  typeof a !== typeof b ? [String(a), String(b)] : [a, b];
+
+const tryParse = (v: string) => {
+  const n = parseInt(v, 10);
+  return isNaN(n) ? v : n;
+};
+
+const compareStrings = (a: string, b: string) => {
+  if (isWildcard(a) || isWildcard(b)) return 0;
+  const [ap, bp] = forceType(tryParse(a), tryParse(b));
+  if (ap > bp) return 1;
+  if (ap < bp) return -1;
+  return 0;
+};
+
+export const compareSegments = (
+  a: string | string[] | RegExpMatchArray,
+  b: string | string[] | RegExpMatchArray,
+) => {
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const r = compareStrings(a[i] || "0", b[i] || "0");
+    if (r !== 0) return r;
+  }
+  return 0;
+};
+
+export const compareVersions = (v1: string, v2: string) => {
+  // validate input and split into segments
+  const n1 = validateAndParse(v1);
+  const n2 = validateAndParse(v2);
+
+  // pop off the patch
+  const p1 = n1.pop();
+  const p2 = n2.pop();
+
+  // validate numbers
+  const r = compareSegments(n1, n2);
+  if (r !== 0) return r;
+
+  // validate pre-release
+  if (p1 && p2) {
+    return compareSegments(p1.split("."), p2.split("."));
+  } else if (p1 || p2) {
+    return p1 ? -1 : 1;
+  }
+
+  return 0;
+};