@contractspec/lib.feature-flags 1.56.1 → 1.58.0

package/dist/evaluation/index.js

@@ -1,221 +1,224 @@
-//#region src/evaluation/index.ts
-/**
-* Simple hash function for consistent bucketing.
-* Uses a deterministic algorithm so the same input always produces the same bucket.
-*/
+// @bun
+// src/evaluation/index.ts
 function hashToBucket(value, seed = "") {
-	const input = `${seed}:${value}`;
-	let hash = 0;
-	for (let i = 0; i < input.length; i++) {
-		const char = input.charCodeAt(i);
-		hash = (hash << 5) - hash + char;
-		hash = hash & hash;
-	}
-	return Math.abs(hash % 100);
+  const input = `${seed}:${value}`;
+  let hash = 0;
+  for (let i = 0;i < input.length; i++) {
+    const char = input.charCodeAt(i);
+    hash = (hash << 5) - hash + char;
+    hash = hash & hash;
+  }
+  return Math.abs(hash % 100);
 }
-/**
-* Get subject identifier from context for consistent hashing.
-*/
 function getSubjectId(context) {
-	return context.userId || context.sessionId || context.orgId || "anonymous";
+  return context.userId || context.sessionId || context.orgId || "anonymous";
 }
-/**
-* Evaluate a single targeting rule condition.
-*/
 function evaluateRuleCondition(rule, context) {
-	const attributeValue = getAttributeValue(rule.attribute, context);
-	switch (rule.operator) {
-		case "EQ": return attributeValue === rule.value;
-		case "NEQ": return attributeValue !== rule.value;
-		case "IN":
-			if (!Array.isArray(rule.value)) return false;
-			return rule.value.includes(attributeValue);
-		case "NIN":
-			if (!Array.isArray(rule.value)) return true;
-			return !rule.value.includes(attributeValue);
-		case "CONTAINS":
-			if (typeof attributeValue !== "string" || typeof rule.value !== "string") return false;
-			return attributeValue.includes(rule.value);
-		case "NOT_CONTAINS":
-			if (typeof attributeValue !== "string" || typeof rule.value !== "string") return true;
-			return !attributeValue.includes(rule.value);
-		case "GT":
-			if (typeof attributeValue !== "number" || typeof rule.value !== "number") return false;
-			return attributeValue > rule.value;
-		case "GTE":
-			if (typeof attributeValue !== "number" || typeof rule.value !== "number") return false;
-			return attributeValue >= rule.value;
-		case "LT":
-			if (typeof attributeValue !== "number" || typeof rule.value !== "number") return false;
-			return attributeValue < rule.value;
-		case "LTE":
-			if (typeof attributeValue !== "number" || typeof rule.value !== "number") return false;
-			return attributeValue <= rule.value;
-		case "PERCENTAGE": return hashToBucket(getSubjectId(context), rule.attribute) < (typeof rule.value === "number" ? rule.value : 0);
-		default: return false;
-	}
+  const attributeValue = getAttributeValue(rule.attribute, context);
+  switch (rule.operator) {
+    case "EQ":
+      return attributeValue === rule.value;
+    case "NEQ":
+      return attributeValue !== rule.value;
+    case "IN":
+      if (!Array.isArray(rule.value))
+        return false;
+      return rule.value.includes(attributeValue);
+    case "NIN":
+      if (!Array.isArray(rule.value))
+        return true;
+      return !rule.value.includes(attributeValue);
+    case "CONTAINS":
+      if (typeof attributeValue !== "string" || typeof rule.value !== "string")
+        return false;
+      return attributeValue.includes(rule.value);
+    case "NOT_CONTAINS":
+      if (typeof attributeValue !== "string" || typeof rule.value !== "string")
+        return true;
+      return !attributeValue.includes(rule.value);
+    case "GT":
+      if (typeof attributeValue !== "number" || typeof rule.value !== "number")
+        return false;
+      return attributeValue > rule.value;
+    case "GTE":
+      if (typeof attributeValue !== "number" || typeof rule.value !== "number")
+        return false;
+      return attributeValue >= rule.value;
+    case "LT":
+      if (typeof attributeValue !== "number" || typeof rule.value !== "number")
+        return false;
+      return attributeValue < rule.value;
+    case "LTE":
+      if (typeof attributeValue !== "number" || typeof rule.value !== "number")
+        return false;
+      return attributeValue <= rule.value;
+    case "PERCENTAGE":
+      return hashToBucket(getSubjectId(context), rule.attribute) < (typeof rule.value === "number" ? rule.value : 0);
+    default:
+      return false;
+  }
 }
-/**
-* Get attribute value from context.
-*/
 function getAttributeValue(attribute, context) {
-	switch (attribute) {
-		case "userId": return context.userId;
-		case "orgId": return context.orgId;
-		case "plan": return context.plan;
-		case "segment": return context.segment;
-		case "sessionId": return context.sessionId;
-		default: return context.attributes?.[attribute];
-	}
+  switch (attribute) {
+    case "userId":
+      return context.userId;
+    case "orgId":
+      return context.orgId;
+    case "plan":
+      return context.plan;
+    case "segment":
+      return context.segment;
+    case "sessionId":
+      return context.sessionId;
+    default:
+      return context.attributes?.[attribute];
+  }
+}
+
+class FlagEvaluator {
+  repository;
+  logger;
+  logEvaluations;
+  constructor(options) {
+    this.repository = options.repository;
+    this.logger = options.logger;
+    this.logEvaluations = options.logEvaluations ?? false;
+  }
+  async evaluate(key, context) {
+    const orgId = context.orgId;
+    const flag = await this.repository.getFlag(key, orgId);
+    if (!flag) {
+      return this.makeResult(false, "FLAG_NOT_FOUND");
+    }
+    if (flag.status === "OFF") {
+      return this.logAndReturn(flag, context, this.makeResult(false, "FLAG_OFF"));
+    }
+    if (flag.status === "ON") {
+      return this.logAndReturn(flag, context, this.makeResult(true, "FLAG_ON"));
+    }
+    const rules = await this.repository.getRules(flag.id);
+    const sortedRules = [...rules].filter((r) => r.enabled).sort((a, b) => a.priority - b.priority);
+    for (const rule of sortedRules) {
+      if (evaluateRuleCondition(rule, context)) {
+        if (rule.rolloutPercentage !== undefined && rule.rolloutPercentage !== null) {
+          const bucket = hashToBucket(getSubjectId(context), flag.key);
+          if (bucket >= rule.rolloutPercentage) {
+            continue;
+          }
+        }
+        const enabled = rule.serveValue ?? true;
+        return this.logAndReturn(flag, context, this.makeResult(enabled, "RULE_MATCH", rule.serveVariant, rule.id));
+      }
+    }
+    const experiment = await this.repository.getActiveExperiment(flag.id);
+    if (experiment && experiment.status === "RUNNING") {
+      const result = await this.evaluateExperiment(experiment, context);
+      if (result) {
+        return this.logAndReturn(flag, context, result);
+      }
+    }
+    return this.logAndReturn(flag, context, this.makeResult(flag.defaultValue, "DEFAULT_VALUE"));
+  }
+  async evaluateExperiment(experiment, context) {
+    const subjectId = getSubjectId(context);
+    const subjectType = context.userId ? "user" : context.orgId ? "org" : "session";
+    const audienceBucket = hashToBucket(subjectId, `${experiment.key}:audience`);
+    if (audienceBucket >= experiment.audiencePercentage) {
+      return null;
+    }
+    let variant = await this.repository.getExperimentAssignment(experiment.id, subjectType, subjectId);
+    if (!variant) {
+      const variantBucket = hashToBucket(subjectId, experiment.key);
+      variant = this.assignVariant(experiment.variants, variantBucket);
+      await this.repository.saveExperimentAssignment(experiment.id, subjectType, subjectId, variant, variantBucket);
+    }
+    const enabled = variant !== "control";
+    return this.makeResult(enabled, "EXPERIMENT_VARIANT", variant, undefined, experiment.id);
+  }
+  assignVariant(variants, bucket) {
+    let cumulative = 0;
+    for (const variant of variants) {
+      cumulative += variant.percentage;
+      if (bucket < cumulative) {
+        return variant.key;
+      }
+    }
+    return variants[variants.length - 1]?.key ?? "control";
+  }
+  makeResult(enabled, reason, variant, ruleId, experimentId) {
+    return {
+      enabled,
+      variant,
+      reason,
+      ruleId,
+      experimentId
+    };
+  }
+  logAndReturn(flag, context, result) {
+    if (this.logEvaluations && this.logger) {
+      const subjectId = getSubjectId(context);
+      const subjectType = context.userId ? "user" : context.orgId ? "org" : "session";
+      this.logger.log({
+        flagId: flag.id,
+        flagKey: flag.key,
+        subjectType,
+        subjectId,
+        result: result.enabled,
+        variant: result.variant,
+        reason: result.reason,
+        ruleId: result.ruleId,
+        experimentId: result.experimentId,
+        context
+      });
+    }
+    return result;
+  }
 }
-/**
-* Feature flag evaluator.
-*
-* Evaluates flags based on:
-* 1. Flag status (OFF/ON/GRADUAL)
-* 2. Targeting rules (in priority order)
-* 3. Experiments (if running)
-* 4. Default value (fallback)
-*/
-var FlagEvaluator = class {
-	repository;
-	logger;
-	logEvaluations;
-	constructor(options) {
-		this.repository = options.repository;
-		this.logger = options.logger;
-		this.logEvaluations = options.logEvaluations ?? false;
-	}
-	/**
-	* Evaluate a feature flag.
-	*/
-	async evaluate(key, context) {
-		const orgId = context.orgId;
-		const flag = await this.repository.getFlag(key, orgId);
-		if (!flag) return this.makeResult(false, "FLAG_NOT_FOUND");
-		if (flag.status === "OFF") return this.logAndReturn(flag, context, this.makeResult(false, "FLAG_OFF"));
-		if (flag.status === "ON") return this.logAndReturn(flag, context, this.makeResult(true, "FLAG_ON"));
-		const sortedRules = [...await this.repository.getRules(flag.id)].filter((r) => r.enabled).sort((a, b) => a.priority - b.priority);
-		for (const rule of sortedRules) if (evaluateRuleCondition(rule, context)) {
-			if (rule.rolloutPercentage !== void 0 && rule.rolloutPercentage !== null) {
-				if (hashToBucket(getSubjectId(context), flag.key) >= rule.rolloutPercentage) continue;
-			}
-			const enabled = rule.serveValue ?? true;
-			return this.logAndReturn(flag, context, this.makeResult(enabled, "RULE_MATCH", rule.serveVariant, rule.id));
-		}
-		const experiment = await this.repository.getActiveExperiment(flag.id);
-		if (experiment && experiment.status === "RUNNING") {
-			const result = await this.evaluateExperiment(experiment, context);
-			if (result) return this.logAndReturn(flag, context, result);
-		}
-		return this.logAndReturn(flag, context, this.makeResult(flag.defaultValue, "DEFAULT_VALUE"));
-	}
-	/**
-	* Evaluate experiment and assign variant.
-	*/
-	async evaluateExperiment(experiment, context) {
-		const subjectId = getSubjectId(context);
-		const subjectType = context.userId ? "user" : context.orgId ? "org" : "session";
-		if (hashToBucket(subjectId, `${experiment.key}:audience`) >= experiment.audiencePercentage) return null;
-		let variant = await this.repository.getExperimentAssignment(experiment.id, subjectType, subjectId);
-		if (!variant) {
-			const variantBucket = hashToBucket(subjectId, experiment.key);
-			variant = this.assignVariant(experiment.variants, variantBucket);
-			await this.repository.saveExperimentAssignment(experiment.id, subjectType, subjectId, variant, variantBucket);
-		}
-		const enabled = variant !== "control";
-		return this.makeResult(enabled, "EXPERIMENT_VARIANT", variant, void 0, experiment.id);
-	}
-	/**
-	* Assign a variant based on bucket and variant percentages.
-	*/
-	assignVariant(variants, bucket) {
-		let cumulative = 0;
-		for (const variant of variants) {
-			cumulative += variant.percentage;
-			if (bucket < cumulative) return variant.key;
-		}
-		return variants[variants.length - 1]?.key ?? "control";
-	}
-	/**
-	* Create evaluation result.
-	*/
-	makeResult(enabled, reason, variant, ruleId, experimentId) {
-		return {
-			enabled,
-			variant,
-			reason,
-			ruleId,
-			experimentId
-		};
-	}
-	/**
-	* Log evaluation and return result.
-	*/
-	logAndReturn(flag, context, result) {
-		if (this.logEvaluations && this.logger) {
-			const subjectId = getSubjectId(context);
-			const subjectType = context.userId ? "user" : context.orgId ? "org" : "session";
-			this.logger.log({
-				flagId: flag.id,
-				flagKey: flag.key,
-				subjectType,
-				subjectId,
-				result: result.enabled,
-				variant: result.variant,
-				reason: result.reason,
-				ruleId: result.ruleId,
-				experimentId: result.experimentId,
-				context
-			});
-		}
-		return result;
-	}
-};
-/**
-* In-memory flag repository for testing and development.
-*/
-var InMemoryFlagRepository = class {
-	flags = /* @__PURE__ */ new Map();
-	rules = /* @__PURE__ */ new Map();
-	experiments = /* @__PURE__ */ new Map();
-	assignments = /* @__PURE__ */ new Map();
-	addFlag(flag) {
-		this.flags.set(flag.key, flag);
-	}
-	addRule(flagId, rule) {
-		const existing = this.rules.get(flagId) || [];
-		existing.push(rule);
-		this.rules.set(flagId, existing);
-	}
-	addExperiment(experiment, flagId) {
-		this.experiments.set(flagId, experiment);
-	}
-	async getFlag(key) {
-		return this.flags.get(key) || null;
-	}
-	async getRules(flagId) {
-		return this.rules.get(flagId) || [];
-	}
-	async getActiveExperiment(flagId) {
-		return this.experiments.get(flagId) || null;
-	}
-	async getExperimentAssignment(experimentId, subjectType, subjectId) {
-		const key = `${experimentId}:${subjectType}:${subjectId}`;
-		return this.assignments.get(key) || null;
-	}
-	async saveExperimentAssignment(experimentId, subjectType, subjectId, variant) {
-		const key = `${experimentId}:${subjectType}:${subjectId}`;
-		this.assignments.set(key, variant);
-	}
-	clear() {
-		this.flags.clear();
-		this.rules.clear();
-		this.experiments.clear();
-		this.assignments.clear();
-	}
-};
 
-//#endregion
-export { FlagEvaluator, InMemoryFlagRepository, evaluateRuleCondition, getSubjectId, hashToBucket };
-//# sourceMappingURL=index.js.map
+class InMemoryFlagRepository {
+  flags = new Map;
+  rules = new Map;
+  experiments = new Map;
+  assignments = new Map;
+  addFlag(flag) {
+    this.flags.set(flag.key, flag);
+  }
+  addRule(flagId, rule) {
+    const existing = this.rules.get(flagId) || [];
+    existing.push(rule);
+    this.rules.set(flagId, existing);
+  }
+  addExperiment(experiment, flagId) {
+    this.experiments.set(flagId, experiment);
+  }
+  async getFlag(key) {
+    return this.flags.get(key) || null;
+  }
+  async getRules(flagId) {
+    return this.rules.get(flagId) || [];
+  }
+  async getActiveExperiment(flagId) {
+    return this.experiments.get(flagId) || null;
+  }
+  async getExperimentAssignment(experimentId, subjectType, subjectId) {
+    const key = `${experimentId}:${subjectType}:${subjectId}`;
+    return this.assignments.get(key) || null;
+  }
+  async saveExperimentAssignment(experimentId, subjectType, subjectId, variant) {
+    const key = `${experimentId}:${subjectType}:${subjectId}`;
+    this.assignments.set(key, variant);
+  }
+  clear() {
+    this.flags.clear();
+    this.rules.clear();
+    this.experiments.clear();
+    this.assignments.clear();
+  }
+}
+export {
+  hashToBucket,
+  getSubjectId,
+  evaluateRuleCondition,
+  InMemoryFlagRepository,
+  FlagEvaluator
+};