@rolloutctrl/evaluator 0.0.1

package/dist/index.d.mts

@@ -0,0 +1,75 @@
+type Operator = 'EQUALS' | 'IN' | 'INCLUDES' | 'GT' | 'LT' | 'GTE' | 'LTE' | 'CONTAINS' | 'STARTS_WITH' | 'ENDS_WITH';
+type MatchType = 'ALL' | 'ANY';
+type ActionEffect = 'ALLOW' | 'DENY';
+interface Rule {
+    field: string;
+    operator: Operator;
+    not: boolean;
+    value: unknown;
+}
+interface SegmentRule extends Rule {
+    priority: number;
+}
+interface Segment {
+    id: string;
+    key: string;
+    rules: SegmentRule[];
+}
+interface Strategy {
+    id: string;
+    enabled: boolean;
+    priority: number;
+    matchType: MatchType;
+    rolloutPercentage: number | null;
+    rolloutStickinessField: string | null;
+    startsAt: Date | null;
+    endsAt: Date | null;
+    segment: Segment | null;
+    rules: Rule[];
+}
+interface FeatureFlagEnvironment {
+    enabled: boolean;
+    strategies: Strategy[];
+}
+interface ActionStrategy {
+    id: string;
+    enabled: boolean;
+    priority: number;
+    effect: ActionEffect;
+    matchType: MatchType;
+    segment: Segment | null;
+    rules: Rule[];
+}
+interface Action {
+    id: string;
+    key: string;
+    enabled: boolean;
+    defaultEffect: ActionEffect;
+    strategies: ActionStrategy[];
+}
+type EvaluationContext = Record<string, unknown>;
+interface FeatureFlagResult {
+    enabled: boolean;
+    strategyId: string | null;
+}
+interface ActionResult {
+    effect: ActionEffect;
+    strategyId: string | null;
+}
+
+declare function evaluateOperator(operator: Operator, not: boolean, field: string, ruleValue: unknown, context: Record<string, unknown>): boolean;
+
+declare function evaluateRule(rule: Rule, context: EvaluationContext): boolean;
+declare function evaluateRules(rules: Rule[], matchType: MatchType, context: EvaluationContext): boolean;
+
+declare function evaluateSegment(segment: Segment, context: EvaluationContext): boolean;
+
+declare function evaluateRollout(strategyId: string, percentage: number, stickinessField: string | null, context: EvaluationContext): boolean;
+
+declare function evaluateStrategy(strategy: Strategy, context: EvaluationContext): boolean;
+declare function evaluateActionStrategy(strategy: ActionStrategy, context: EvaluationContext): ActionEffect | null;
+
+declare function evaluateFeatureFlag(flagEnv: FeatureFlagEnvironment, context: EvaluationContext): FeatureFlagResult;
+declare function evaluateAction(action: Action, context: EvaluationContext): ActionResult;
+
+export { type Action, type ActionEffect, type ActionResult, type ActionStrategy, type EvaluationContext, type FeatureFlagEnvironment, type FeatureFlagResult, type MatchType, type Operator, type Rule, type Segment, type SegmentRule, type Strategy, evaluateAction, evaluateActionStrategy, evaluateFeatureFlag, evaluateOperator, evaluateRollout, evaluateRule, evaluateRules, evaluateSegment, evaluateStrategy };

package/dist/index.d.ts

@@ -0,0 +1,75 @@
+type Operator = 'EQUALS' | 'IN' | 'INCLUDES' | 'GT' | 'LT' | 'GTE' | 'LTE' | 'CONTAINS' | 'STARTS_WITH' | 'ENDS_WITH';
+type MatchType = 'ALL' | 'ANY';
+type ActionEffect = 'ALLOW' | 'DENY';
+interface Rule {
+    field: string;
+    operator: Operator;
+    not: boolean;
+    value: unknown;
+}
+interface SegmentRule extends Rule {
+    priority: number;
+}
+interface Segment {
+    id: string;
+    key: string;
+    rules: SegmentRule[];
+}
+interface Strategy {
+    id: string;
+    enabled: boolean;
+    priority: number;
+    matchType: MatchType;
+    rolloutPercentage: number | null;
+    rolloutStickinessField: string | null;
+    startsAt: Date | null;
+    endsAt: Date | null;
+    segment: Segment | null;
+    rules: Rule[];
+}
+interface FeatureFlagEnvironment {
+    enabled: boolean;
+    strategies: Strategy[];
+}
+interface ActionStrategy {
+    id: string;
+    enabled: boolean;
+    priority: number;
+    effect: ActionEffect;
+    matchType: MatchType;
+    segment: Segment | null;
+    rules: Rule[];
+}
+interface Action {
+    id: string;
+    key: string;
+    enabled: boolean;
+    defaultEffect: ActionEffect;
+    strategies: ActionStrategy[];
+}
+type EvaluationContext = Record<string, unknown>;
+interface FeatureFlagResult {
+    enabled: boolean;
+    strategyId: string | null;
+}
+interface ActionResult {
+    effect: ActionEffect;
+    strategyId: string | null;
+}
+
+declare function evaluateOperator(operator: Operator, not: boolean, field: string, ruleValue: unknown, context: Record<string, unknown>): boolean;
+
+declare function evaluateRule(rule: Rule, context: EvaluationContext): boolean;
+declare function evaluateRules(rules: Rule[], matchType: MatchType, context: EvaluationContext): boolean;
+
+declare function evaluateSegment(segment: Segment, context: EvaluationContext): boolean;
+
+declare function evaluateRollout(strategyId: string, percentage: number, stickinessField: string | null, context: EvaluationContext): boolean;
+
+declare function evaluateStrategy(strategy: Strategy, context: EvaluationContext): boolean;
+declare function evaluateActionStrategy(strategy: ActionStrategy, context: EvaluationContext): ActionEffect | null;
+
+declare function evaluateFeatureFlag(flagEnv: FeatureFlagEnvironment, context: EvaluationContext): FeatureFlagResult;
+declare function evaluateAction(action: Action, context: EvaluationContext): ActionResult;
+
+export { type Action, type ActionEffect, type ActionResult, type ActionStrategy, type EvaluationContext, type FeatureFlagEnvironment, type FeatureFlagResult, type MatchType, type Operator, type Rule, type Segment, type SegmentRule, type Strategy, evaluateAction, evaluateActionStrategy, evaluateFeatureFlag, evaluateOperator, evaluateRollout, evaluateRule, evaluateRules, evaluateSegment, evaluateStrategy };

package/dist/index.js

@@ -0,0 +1,209 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  evaluateAction: () => evaluateAction,
+  evaluateActionStrategy: () => evaluateActionStrategy,
+  evaluateFeatureFlag: () => evaluateFeatureFlag,
+  evaluateOperator: () => evaluateOperator,
+  evaluateRollout: () => evaluateRollout,
+  evaluateRule: () => evaluateRule,
+  evaluateRules: () => evaluateRules,
+  evaluateSegment: () => evaluateSegment,
+  evaluateStrategy: () => evaluateStrategy
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/operators.ts
+function getFieldValue(context, field) {
+  const parts = field.split(".");
+  let current = context;
+  for (const part of parts) {
+    if (current === null || current === void 0 || typeof current !== "object") {
+      return void 0;
+    }
+    current = current[part];
+  }
+  return current;
+}
+function toNumber(value) {
+  const n = Number(value);
+  return isNaN(n) ? null : n;
+}
+function applyOperator(operator, contextValue, ruleValue) {
+  switch (operator) {
+    case "EQUALS":
+      return String(contextValue) === String(ruleValue);
+    case "IN": {
+      const list = Array.isArray(ruleValue) ? ruleValue : [ruleValue];
+      return list.map(String).includes(String(contextValue));
+    }
+    case "INCLUDES": {
+      if (!Array.isArray(contextValue)) return false;
+      return contextValue.map(String).includes(String(ruleValue));
+    }
+    case "GT": {
+      const a = toNumber(contextValue);
+      const b = toNumber(ruleValue);
+      return a !== null && b !== null && a > b;
+    }
+    case "LT": {
+      const a = toNumber(contextValue);
+      const b = toNumber(ruleValue);
+      return a !== null && b !== null && a < b;
+    }
+    case "GTE": {
+      const a = toNumber(contextValue);
+      const b = toNumber(ruleValue);
+      return a !== null && b !== null && a >= b;
+    }
+    case "LTE": {
+      const a = toNumber(contextValue);
+      const b = toNumber(ruleValue);
+      return a !== null && b !== null && a <= b;
+    }
+    case "CONTAINS":
+      return typeof contextValue === "string" && contextValue.includes(String(ruleValue));
+    case "STARTS_WITH":
+      return typeof contextValue === "string" && contextValue.startsWith(String(ruleValue));
+    case "ENDS_WITH":
+      return typeof contextValue === "string" && contextValue.endsWith(String(ruleValue));
+    default:
+      return false;
+  }
+}
+function evaluateOperator(operator, not, field, ruleValue, context) {
+  const contextValue = getFieldValue(context, field);
+  const result = applyOperator(operator, contextValue, ruleValue);
+  return not ? !result : result;
+}
+
+// src/rule.ts
+function evaluateRule(rule, context) {
+  return evaluateOperator(rule.operator, rule.not, rule.field, rule.value, context);
+}
+function evaluateRules(rules, matchType, context) {
+  if (rules.length === 0) return true;
+  if (matchType === "ALL") {
+    return rules.every((rule) => evaluateRule(rule, context));
+  }
+  return rules.some((rule) => evaluateRule(rule, context));
+}
+
+// src/segment.ts
+function evaluateSegment(segment, context) {
+  if (segment.rules.length === 0) return true;
+  const sorted = [...segment.rules].sort((a, b) => b.priority - a.priority);
+  return sorted.every((rule) => evaluateRule(rule, context));
+}
+
+// src/rollout.ts
+function hashString(input) {
+  let hash = 5381;
+  for (let i = 0; i < input.length; i++) {
+    hash = (hash << 5) + hash ^ input.charCodeAt(i);
+    hash = hash >>> 0;
+  }
+  return hash;
+}
+function evaluateRollout(strategyId, percentage, stickinessField, context) {
+  if (percentage <= 0) return false;
+  if (percentage >= 100) return true;
+  const stickyValue = stickinessField !== null ? String(context[stickinessField] ?? "") : "";
+  const seed = `${strategyId}:${stickyValue}`;
+  const hash = hashString(seed);
+  const bucket = hash % 100;
+  return bucket < percentage;
+}
+
+// src/strategy.ts
+function isWithinTimeWindow(startsAt, endsAt) {
+  const now = /* @__PURE__ */ new Date();
+  if (startsAt !== null && now < startsAt) return false;
+  if (endsAt !== null && now > endsAt) return false;
+  return true;
+}
+function evaluateStrategy(strategy, context) {
+  if (!strategy.enabled) return false;
+  if (!isWithinTimeWindow(strategy.startsAt, strategy.endsAt)) return false;
+  if (strategy.segment !== null) {
+    if (!evaluateSegment(strategy.segment, context)) return false;
+  } else if (strategy.rules.length > 0) {
+    if (!evaluateRules(strategy.rules, strategy.matchType, context)) return false;
+  }
+  if (strategy.rolloutPercentage !== null) {
+    return evaluateRollout(
+      strategy.id,
+      strategy.rolloutPercentage,
+      strategy.rolloutStickinessField,
+      context
+    );
+  }
+  return true;
+}
+function evaluateActionStrategy(strategy, context) {
+  if (!strategy.enabled) return null;
+  if (strategy.segment !== null) {
+    if (!evaluateSegment(strategy.segment, context)) return null;
+  } else if (strategy.rules.length > 0) {
+    if (!evaluateRules(strategy.rules, strategy.matchType, context)) return null;
+  }
+  return strategy.effect;
+}
+
+// src/evaluate.ts
+function evaluateFeatureFlag(flagEnv, context) {
+  if (!flagEnv.enabled) {
+    return { enabled: false, strategyId: null };
+  }
+  const sorted = [...flagEnv.strategies].sort((a, b) => b.priority - a.priority);
+  for (const strategy of sorted) {
+    if (evaluateStrategy(strategy, context)) {
+      return { enabled: true, strategyId: strategy.id };
+    }
+  }
+  return { enabled: false, strategyId: null };
+}
+function evaluateAction(action, context) {
+  if (!action.enabled) {
+    return { effect: action.defaultEffect, strategyId: null };
+  }
+  const sorted = [...action.strategies].sort((a, b) => b.priority - a.priority);
+  for (const strategy of sorted) {
+    const effect = evaluateActionStrategy(strategy, context);
+    if (effect !== null) {
+      return { effect, strategyId: strategy.id };
+    }
+  }
+  return { effect: action.defaultEffect, strategyId: null };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  evaluateAction,
+  evaluateActionStrategy,
+  evaluateFeatureFlag,
+  evaluateOperator,
+  evaluateRollout,
+  evaluateRule,
+  evaluateRules,
+  evaluateSegment,
+  evaluateStrategy
+});

package/dist/index.mjs

@@ -0,0 +1,174 @@
+// src/operators.ts
+function getFieldValue(context, field) {
+  const parts = field.split(".");
+  let current = context;
+  for (const part of parts) {
+    if (current === null || current === void 0 || typeof current !== "object") {
+      return void 0;
+    }
+    current = current[part];
+  }
+  return current;
+}
+function toNumber(value) {
+  const n = Number(value);
+  return isNaN(n) ? null : n;
+}
+function applyOperator(operator, contextValue, ruleValue) {
+  switch (operator) {
+    case "EQUALS":
+      return String(contextValue) === String(ruleValue);
+    case "IN": {
+      const list = Array.isArray(ruleValue) ? ruleValue : [ruleValue];
+      return list.map(String).includes(String(contextValue));
+    }
+    case "INCLUDES": {
+      if (!Array.isArray(contextValue)) return false;
+      return contextValue.map(String).includes(String(ruleValue));
+    }
+    case "GT": {
+      const a = toNumber(contextValue);
+      const b = toNumber(ruleValue);
+      return a !== null && b !== null && a > b;
+    }
+    case "LT": {
+      const a = toNumber(contextValue);
+      const b = toNumber(ruleValue);
+      return a !== null && b !== null && a < b;
+    }
+    case "GTE": {
+      const a = toNumber(contextValue);
+      const b = toNumber(ruleValue);
+      return a !== null && b !== null && a >= b;
+    }
+    case "LTE": {
+      const a = toNumber(contextValue);
+      const b = toNumber(ruleValue);
+      return a !== null && b !== null && a <= b;
+    }
+    case "CONTAINS":
+      return typeof contextValue === "string" && contextValue.includes(String(ruleValue));
+    case "STARTS_WITH":
+      return typeof contextValue === "string" && contextValue.startsWith(String(ruleValue));
+    case "ENDS_WITH":
+      return typeof contextValue === "string" && contextValue.endsWith(String(ruleValue));
+    default:
+      return false;
+  }
+}
+function evaluateOperator(operator, not, field, ruleValue, context) {
+  const contextValue = getFieldValue(context, field);
+  const result = applyOperator(operator, contextValue, ruleValue);
+  return not ? !result : result;
+}
+
+// src/rule.ts
+function evaluateRule(rule, context) {
+  return evaluateOperator(rule.operator, rule.not, rule.field, rule.value, context);
+}
+function evaluateRules(rules, matchType, context) {
+  if (rules.length === 0) return true;
+  if (matchType === "ALL") {
+    return rules.every((rule) => evaluateRule(rule, context));
+  }
+  return rules.some((rule) => evaluateRule(rule, context));
+}
+
+// src/segment.ts
+function evaluateSegment(segment, context) {
+  if (segment.rules.length === 0) return true;
+  const sorted = [...segment.rules].sort((a, b) => b.priority - a.priority);
+  return sorted.every((rule) => evaluateRule(rule, context));
+}
+
+// src/rollout.ts
+function hashString(input) {
+  let hash = 5381;
+  for (let i = 0; i < input.length; i++) {
+    hash = (hash << 5) + hash ^ input.charCodeAt(i);
+    hash = hash >>> 0;
+  }
+  return hash;
+}
+function evaluateRollout(strategyId, percentage, stickinessField, context) {
+  if (percentage <= 0) return false;
+  if (percentage >= 100) return true;
+  const stickyValue = stickinessField !== null ? String(context[stickinessField] ?? "") : "";
+  const seed = `${strategyId}:${stickyValue}`;
+  const hash = hashString(seed);
+  const bucket = hash % 100;
+  return bucket < percentage;
+}
+
+// src/strategy.ts
+function isWithinTimeWindow(startsAt, endsAt) {
+  const now = /* @__PURE__ */ new Date();
+  if (startsAt !== null && now < startsAt) return false;
+  if (endsAt !== null && now > endsAt) return false;
+  return true;
+}
+function evaluateStrategy(strategy, context) {
+  if (!strategy.enabled) return false;
+  if (!isWithinTimeWindow(strategy.startsAt, strategy.endsAt)) return false;
+  if (strategy.segment !== null) {
+    if (!evaluateSegment(strategy.segment, context)) return false;
+  } else if (strategy.rules.length > 0) {
+    if (!evaluateRules(strategy.rules, strategy.matchType, context)) return false;
+  }
+  if (strategy.rolloutPercentage !== null) {
+    return evaluateRollout(
+      strategy.id,
+      strategy.rolloutPercentage,
+      strategy.rolloutStickinessField,
+      context
+    );
+  }
+  return true;
+}
+function evaluateActionStrategy(strategy, context) {
+  if (!strategy.enabled) return null;
+  if (strategy.segment !== null) {
+    if (!evaluateSegment(strategy.segment, context)) return null;
+  } else if (strategy.rules.length > 0) {
+    if (!evaluateRules(strategy.rules, strategy.matchType, context)) return null;
+  }
+  return strategy.effect;
+}
+
+// src/evaluate.ts
+function evaluateFeatureFlag(flagEnv, context) {
+  if (!flagEnv.enabled) {
+    return { enabled: false, strategyId: null };
+  }
+  const sorted = [...flagEnv.strategies].sort((a, b) => b.priority - a.priority);
+  for (const strategy of sorted) {
+    if (evaluateStrategy(strategy, context)) {
+      return { enabled: true, strategyId: strategy.id };
+    }
+  }
+  return { enabled: false, strategyId: null };
+}
+function evaluateAction(action, context) {
+  if (!action.enabled) {
+    return { effect: action.defaultEffect, strategyId: null };
+  }
+  const sorted = [...action.strategies].sort((a, b) => b.priority - a.priority);
+  for (const strategy of sorted) {
+    const effect = evaluateActionStrategy(strategy, context);
+    if (effect !== null) {
+      return { effect, strategyId: strategy.id };
+    }
+  }
+  return { effect: action.defaultEffect, strategyId: null };
+}
+export {
+  evaluateAction,
+  evaluateActionStrategy,
+  evaluateFeatureFlag,
+  evaluateOperator,
+  evaluateRollout,
+  evaluateRule,
+  evaluateRules,
+  evaluateSegment,
+  evaluateStrategy
+};

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@rolloutctrl/evaluator",
+  "version": "0.0.1",
+  "description": "RolloutCtrl feature flag & action evaluator",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "lint": "tsc --noEmit",
+    "test": "jest",
+    "test:watch": "jest --watch"
+  },
+  "devDependencies": {
+    "@jest/types": "^30.4.1",
+    "@types/jest": "^29.5.0",
+    "jest": "^29.7.0",
+    "jest-util": "^30.4.1",
+    "ts-jest": "^29.1.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}