@featurevisor/sdk 1.29.2 → 1.30.1

package/lib/evaluate.d.ts

@@ -0,0 +1,59 @@
+import { Feature, FeatureKey, Context, BucketKey, BucketValue, RuleKey, Traffic, Force, Required, OverrideFeature, Variation, VariationValue, VariableKey, VariableValue, VariableSchema, StickyFeatures, InitialFeatures } from "@featurevisor/types";
+import { Logger } from "./logger";
+import { DatafileReader } from "./datafileReader";
+import { ConfigureBucketKey, ConfigureBucketValue } from "./bucket";
+import type { Statuses, InterceptContext } from "./instance";
+export declare enum EvaluationReason {
+    NOT_FOUND = "not_found",
+    NO_VARIATIONS = "no_variations",
+    NO_MATCH = "no_match",
+    DISABLED = "disabled",
+    REQUIRED = "required",
+    OUT_OF_RANGE = "out_of_range",
+    FORCED = "forced",
+    INITIAL = "initial",
+    STICKY = "sticky",
+    RULE = "rule",
+    ALLOCATED = "allocated",
+    DEFAULTED = "defaulted",
+    OVERRIDE = "override",
+    ERROR = "error"
+}
+type EvaluationType = "flag" | "variation" | "variable";
+export interface Evaluation {
+    featureKey: FeatureKey;
+    reason: EvaluationReason;
+    bucketKey?: BucketKey;
+    bucketValue?: BucketValue;
+    ruleKey?: RuleKey;
+    error?: Error;
+    enabled?: boolean;
+    traffic?: Traffic;
+    forceIndex?: number;
+    force?: Force;
+    required?: Required[];
+    sticky?: OverrideFeature;
+    initial?: OverrideFeature;
+    variation?: Variation;
+    variationValue?: VariationValue;
+    variableKey?: VariableKey;
+    variableValue?: VariableValue;
+    variableSchema?: VariableSchema;
+}
+export interface EvaluateOptions {
+    type: EvaluationType;
+    featureKey: FeatureKey | Feature;
+    variableKey?: VariableKey;
+    context: Context;
+    logger: Logger;
+    datafileReader: DatafileReader;
+    statuses?: Statuses;
+    interceptContext?: InterceptContext;
+    stickyFeatures?: StickyFeatures;
+    initialFeatures?: InitialFeatures;
+    bucketKeySeparator?: string;
+    configureBucketKey?: ConfigureBucketKey;
+    configureBucketValue?: ConfigureBucketValue;
+}
+export declare function evaluate(options: EvaluateOptions): Evaluation;
+export {};

package/lib/index.d.ts

@@ -3,3 +3,4 @@ export * from "./instance";
 export * from "./logger";
 export * from "./conditions";
 export * from "./emitter";
+export * from "./evaluate";

package/lib/instance.d.ts

@@ -1,10 +1,10 @@
-import { Context, BucketKey, BucketValue, DatafileContent, Feature, FeatureKey, InitialFeatures, OverrideFeature, StickyFeatures, Traffic, VariableType, VariableValue, VariationValue, Variation, RuleKey, VariableKey, VariableSchema, Force, Required } from "@featurevisor/types";
+import { Context, DatafileContent, Feature, FeatureKey, InitialFeatures, StickyFeatures, VariableType, VariableValue, VariationValue, VariableKey } from "@featurevisor/types";
 import { Logger, LogLevel } from "./logger";
 import { Emitter } from "./emitter";
+import { ConfigureBucketKey, ConfigureBucketValue } from "./bucket";
+import { Evaluation } from "./evaluate";
 export type ReadyCallback = () => void;
 export type ActivationCallback = (featureName: string, variation: VariationValue, context: Context, captureContext: Context) => void;
-export type ConfigureBucketKey = (feature: any, context: any, bucketKey: BucketKey) => BucketKey;
-export type ConfigureBucketValue = (feature: any, context: any, bucketValue: BucketValue) => BucketValue;
 export interface Statuses {
     ready: boolean;
     refreshInProgress: boolean;
@@ -28,42 +28,6 @@ export interface InstanceOptions {
     stickyFeatures?: StickyFeatures;
 }
 export type DatafileFetchHandler = (datafileUrl: string) => Promise<DatafileContent>;
-export declare enum EvaluationReason {
-    NOT_FOUND = "not_found",
-    NO_VARIATIONS = "no_variations",
-    NO_MATCH = "no_match",
-    DISABLED = "disabled",
-    REQUIRED = "required",
-    OUT_OF_RANGE = "out_of_range",
-    FORCED = "forced",
-    INITIAL = "initial",
-    STICKY = "sticky",
-    RULE = "rule",
-    ALLOCATED = "allocated",
-    DEFAULTED = "defaulted",
-    OVERRIDE = "override",
-    ERROR = "error"
-}
-export interface Evaluation {
-    featureKey: FeatureKey;
-    reason: EvaluationReason;
-    bucketKey?: BucketKey;
-    bucketValue?: BucketValue;
-    ruleKey?: RuleKey;
-    error?: Error;
-    enabled?: boolean;
-    traffic?: Traffic;
-    forceIndex?: number;
-    force?: Force;
-    required?: Required[];
-    sticky?: OverrideFeature;
-    initial?: OverrideFeature;
-    variation?: Variation;
-    variationValue?: VariationValue;
-    variableKey?: VariableKey;
-    variableValue?: VariableValue;
-    variableSchema?: VariableSchema;
-}
 type FieldType = string | VariableType;
 type ValueType = VariableValue;
 export declare function getValueByType(value: ValueType, fieldType: FieldType): ValueType;
@@ -94,11 +58,6 @@ export declare class FeaturevisorInstance {
     setStickyFeatures(stickyFeatures: StickyFeatures | undefined): void;
     getRevision(): string;
     getFeature(featureKey: string | Feature): Feature | undefined;
-    /**
-     * Bucketing
-     */
-    private getBucketKey;
-    private getBucketValue;
     /**
      * Statuses
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@featurevisor/sdk",
-  "version": "1.29.2",
+  "version": "1.30.1",
   "description": "Featurevisor SDK for Node.js and the browser",
   "main": "dist/index.cjs.js",
   "module": "dist/index.mjs",
@@ -53,5 +53,5 @@
     "compare-versions": "^6.0.0-rc.1",
     "murmurhash": "^2.0.1"
   },
-  "gitHead": "2b62bb80bc2eaafd66934f5649da5286542e1af7"
+  "gitHead": "8dc524c8a2a2ccb85661177e37ef1aff7cab8273"
 }

package/src/bucket.ts

@@ -1,5 +1,11 @@
 import * as murmurhash from "murmurhash";
+import { Feature, BucketKey, BucketValue, Context, AttributeValue } from "@featurevisor/types";
 
+import { Logger } from "./logger";
+
+/**
+ * Generic hashing
+ */
 const HASH_SEED = 1;
 const MAX_HASH_VALUE = Math.pow(2, 32);
 
@@ -11,3 +17,123 @@ export function getBucketedNumber(bucketKey: string): number {
 
   return Math.floor(ratio * MAX_BUCKETED_NUMBER);
 }
+
+/**
+ * Feature specific bucketing
+ */
+export type ConfigureBucketKey = (
+  feature: Feature,
+  context: Context,
+  bucketKey: BucketKey,
+) => BucketKey;
+
+export interface BucketKeyOptions {
+  feature: Feature;
+  context: Context;
+  logger: Logger;
+  bucketKeySeparator?: string;
+  configureBucketKey?: ConfigureBucketKey;
+}
+
+export function getBucketKey(options: BucketKeyOptions): BucketKey {
+  const { feature, context, logger, bucketKeySeparator = ".", configureBucketKey } = options;
+
+  const featureKey = feature.key;
+
+  let type;
+  let attributeKeys;
+
+  if (typeof feature.bucketBy === "string") {
+    type = "plain";
+    attributeKeys = [feature.bucketBy];
+  } else if (Array.isArray(feature.bucketBy)) {
+    type = "and";
+    attributeKeys = feature.bucketBy;
+  } else if (typeof feature.bucketBy === "object" && Array.isArray(feature.bucketBy.or)) {
+    type = "or";
+    attributeKeys = feature.bucketBy.or;
+  } else {
+    logger.error("invalid bucketBy", { featureKey, bucketBy: feature.bucketBy });
+
+    throw new Error("invalid bucketBy");
+  }
+
+  const bucketKey: AttributeValue[] = [];
+
+  attributeKeys.forEach((attributeKey) => {
+    const attributeValue = context[attributeKey];
+
+    if (typeof attributeValue === "undefined") {
+      return;
+    }
+
+    if (type === "plain" || type === "and") {
+      bucketKey.push(attributeValue);
+    } else {
+      // or
+      if (bucketKey.length === 0) {
+        bucketKey.push(attributeValue);
+      }
+    }
+  });
+
+  bucketKey.push(featureKey);
+
+  const result = bucketKey.join(bucketKeySeparator);
+
+  if (configureBucketKey) {
+    return configureBucketKey(feature, context, result);
+  }
+
+  return result;
+}
+
+export interface Bucket {
+  bucketKey: BucketKey;
+  bucketValue: BucketValue;
+}
+
+export type ConfigureBucketValue = (
+  feature: Feature,
+  context: Context,
+  bucketValue: BucketValue,
+) => BucketValue;
+
+export interface BucketValueOptions {
+  // common with BucketKeyOptions
+  feature: Feature;
+  context: Context;
+  logger: Logger;
+  bucketKeySeparator?: string;
+  configureBucketKey?: ConfigureBucketKey;
+
+  // specific to BucketValueOptions
+  configureBucketValue?: ConfigureBucketValue;
+}
+
+export function getBucket(options: BucketValueOptions): Bucket {
+  const { feature, context, logger, bucketKeySeparator, configureBucketKey, configureBucketValue } =
+    options;
+  const bucketKey = getBucketKey({
+    feature,
+    context,
+    logger,
+    bucketKeySeparator,
+    configureBucketKey,
+  });
+  const value = getBucketedNumber(bucketKey);
+
+  if (configureBucketValue) {
+    const configuredValue = configureBucketValue(feature, context, value);
+
+    return {
+      bucketKey,
+      bucketValue: configuredValue,
+    };
+  }
+
+  return {
+    bucketKey,
+    bucketValue: value,
+  };
+}