@kenji71089/evaluation 0.0.1 → 0.0.8

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## [0.0.7] (2026-01-20)
+
+### Fix
+
+- fix(evaluation): align equals/in semver fallback behavior with comparison operators [#2355](https://github.com/bucketeer-io/bucketeer/pull/2355)
+
+## [0.0.6] (2025-11-19)
+
+### Features
+
+- add yaml flag type support [#2217](https://github.com/bucketeer-io/bucketeer/pull/2217)
+
+## [0.0.5] (2025-09-26)
+
+### Fix
+
+- fix: resolve missing dependencies in incremental feature flag evaluation [#2315](https://github.com/bucketeer-io/bucketeer/pull/2135)
+
+## [0.0.4] (2025-09-01)
+
+### Feat
+
+- feat: support not equal operator for evaluation [#2095](https://github.com/bucketeer-io/bucketeer/pull/2095)
+
+## [0.0.3] (2025-03-07)
+
+### Fix
+
+- fix(evaluation/typescript): missing proto import when build release lib [#1567]([https://github.com/bucketeer-io/bucketeer/pull/1567)
+
+## [0.0.2] (2025-03-04)
+
+### Miscellaneous
+
+- chore(evaluation/typescript): export function getFeatureIDsDependsOn [#1553](https://github.com/bucketeer-io/bucketeer/pull/1553)
+
+- chore: improve bucket hash algorithm using murmurHash3 instead of md5 [#1523](https://github.com/bucketeer-io/bucketeer/pull/1523)
+
+## [0.0.1] (2025-01-22)
+
+### Features
+
+- initial release [#1258](https://github.com/bucketeer-io/bucketeer/pull/1258)

package/README.md

@@ -1,9 +1,39 @@
 # Evaluation module for Node.JS
 
-## Setup
-```export NPM_TOKEN="YOUR_NPM_TOKEN"```
-```make init```
-```make copy_proto_generated_code```
+## Development
 
-## Unit tests
-```make test```
+### Setup
+
+```sh
+export NPM_TOKEN="YOUR_NPM_TOKEN"
+make init
+make gen_proto
+```
+
+### Build
+
+```sh
+make build
+```
+
+### Unit tests
+
+```sh
+make test
+```
+
+### Lint
+
+```sh
+make lint
+```
+
+## Release to NPM
+
+```sh
+export NPM_TOKEN="YOUR_NPM_TOKEN"
+make init
+make gen_proto
+make build
+make publish
+```

package/lib/bucketeer.d.ts

@@ -0,0 +1,6 @@
+declare class Bucketeer {
+    bucket(input: string): number;
+    private murmur128;
+    private toFloat64;
+}
+export { Bucketeer };

package/lib/bucketeer.js

@@ -0,0 +1,65 @@
+"use strict";
+
+function _typeof(o) { "@babel/helpers - typeof"; return _typeof = "function" == typeof Symbol && "symbol" == typeof Symbol.iterator ? function (o) { return typeof o; } : function (o) { return o && "function" == typeof Symbol && o.constructor === Symbol && o !== Symbol.prototype ? "symbol" : typeof o; }, _typeof(o); }
+function _classCallCheck(a, n) { if (!(a instanceof n)) throw new TypeError("Cannot call a class as a function"); }
+function _defineProperties(e, r) { for (var t = 0; t < r.length; t++) { var o = r[t]; o.enumerable = o.enumerable || !1, o.configurable = !0, "value" in o && (o.writable = !0), Object.defineProperty(e, _toPropertyKey(o.key), o); } }
+function _createClass(e, r, t) { return r && _defineProperties(e.prototype, r), t && _defineProperties(e, t), Object.defineProperty(e, "prototype", { writable: !1 }), e; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == _typeof(i) ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != _typeof(t) || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != _typeof(i)) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+var __importDefault = void 0 && (void 0).__importDefault || function (mod) {
+  return mod && mod.__esModule ? mod : {
+    "default": mod
+  };
+};
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.Bucketeer = void 0;
+var murmurhash3js_1 = __importDefault(require("murmurhash3js"));
+var Bucketeer = /*#__PURE__*/function () {
+  function Bucketeer() {
+    _classCallCheck(this, Bucketeer);
+  }
+  return _createClass(Bucketeer, [{
+    key: "bucket",
+    value:
+    // Calculate the input hash of the target property and map it to a float64 between [0,1]
+    function bucket(input) {
+      var _this$murmur = this.murmur128(input),
+        high = _this$murmur.high,
+        low = _this$murmur.low;
+      return this.toFloat64(high, low);
+    }
+    // Computes MurmurHash3 (128-bit) hash and returns the high and low parts.
+    // The high and low parts of the hash are returned in big-endian format,
+    // which is crucial for consistency with the Go implementation that also uses big-endian.
+  }, {
+    key: "murmur128",
+    value: function murmur128(input) {
+      var hash = murmurhash3js_1["default"].x64.hash128(input);
+      // Convert the hash from hexadecimal to BigInt.
+      // The first 16 characters represent the high part (most significant bits),
+      // and the last 16 characters represent the low part (least significant bits).
+      var high = BigInt('0x' + hash.slice(0, 16)); // High part
+      var low = BigInt('0x' + hash.slice(16, 32)); // Low part
+      return {
+        high: high,
+        low: low
+      };
+    }
+    // Convert a 128-bit hash (two uint64 values) to a float64 in the range [0,1].
+    // Because we bucket millions of users, we use the full 128-bit hash to avoid collisions.
+  }, {
+    key: "toFloat64",
+    value: function toFloat64(high, low) {
+      // Combine the high and low parts into a single floating-point number.
+      // This maintains the full 128-bit range, ensuring a normalized value between [0,1].
+      var full = Number(high) * Math.pow(2, 64) + Number(low);
+      // Calculate the maximum value for a 128-bit number.
+      var maxValue = Math.pow(2, 128) - 1;
+      // Normalize the combined value to the range [0,1].
+      return full / maxValue;
+    }
+  }]);
+}();
+exports.Bucketeer = Bucketeer;

package/lib/bucketeer.mjs

@@ -0,0 +1,38 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Bucketeer = void 0;
+const murmurhash3js_1 = __importDefault(require("murmurhash3js"));
+class Bucketeer {
+    // Calculate the input hash of the target property and map it to a float64 between [0,1]
+    bucket(input) {
+        const { high, low } = this.murmur128(input);
+        return this.toFloat64(high, low);
+    }
+    // Computes MurmurHash3 (128-bit) hash and returns the high and low parts.
+    // The high and low parts of the hash are returned in big-endian format,
+    // which is crucial for consistency with the Go implementation that also uses big-endian.
+    murmur128(input) {
+        const hash = murmurhash3js_1.default.x64.hash128(input);
+        // Convert the hash from hexadecimal to BigInt.
+        // The first 16 characters represent the high part (most significant bits),
+        // and the last 16 characters represent the low part (least significant bits).
+        const high = BigInt('0x' + hash.slice(0, 16)); // High part
+        const low = BigInt('0x' + hash.slice(16, 32)); // Low part
+        return { high, low };
+    }
+    // Convert a 128-bit hash (two uint64 values) to a float64 in the range [0,1].
+    // Because we bucket millions of users, we use the full 128-bit hash to avoid collisions.
+    toFloat64(high, low) {
+        // Combine the high and low parts into a single floating-point number.
+        // This maintains the full 128-bit range, ensuring a normalized value between [0,1].
+        const full = Number(high) * Math.pow(2, 64) + Number(low);
+        // Calculate the maximum value for a 128-bit number.
+        const maxValue = Math.pow(2, 128) - 1;
+        // Normalize the combined value to the range [0,1].
+        return full / maxValue;
+    }
+}
+exports.Bucketeer = Bucketeer;

package/lib/clauseEvaluator.js

@@ -31,13 +31,23 @@ var __setModuleDefault = void 0 && (void 0).__setModuleDefault || (Object.create
 } : function (o, v) {
   o["default"] = v;
 });
-var __importStar = void 0 && (void 0).__importStar || function (mod) {
-  if (mod && mod.__esModule) return mod;
-  var result = {};
-  if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-  __setModuleDefault(result, mod);
-  return result;
-};
+var __importStar = void 0 && (void 0).__importStar || function () {
+  var _ownKeys = function ownKeys(o) {
+    _ownKeys = Object.getOwnPropertyNames || function (o) {
+      var ar = [];
+      for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+      return ar;
+    };
+    return _ownKeys(o);
+  };
+  return function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k = _ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+    __setModuleDefault(result, mod);
+    return result;
+  };
+}();
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
@@ -86,6 +96,8 @@ var ClauseEvaluator = /*#__PURE__*/function () {
             return this.dependencyEvaluator.evaluate(clause.getAttribute(), clause.getValuesList(), flagVariations);
           case clause_pb_1.Clause.Operator.PARTIALLY_MATCH:
             return this.partiallyMatches(targetValue, clause.getValuesList());
+          case clause_pb_1.Clause.Operator.NOT_EQUALS:
+            return !this.equals(targetValue, clause.getValuesList());
           default:
             return false;
         }
@@ -97,6 +109,21 @@ var ClauseEvaluator = /*#__PURE__*/function () {
   }, {
     key: "equals",
     value: function equals(targetValue, values) {
+      // First try semver comparison (with v-prefix normalization via semver.valid)
+      var semverTarget = semver.valid(targetValue);
+      if (semverTarget) {
+        var semverValues = values.map(function (v) {
+          return semver.valid(v);
+        }).filter(function (v) {
+          return v !== null;
+        });
+        // Target parsed as semver; if no values parsed or none matched, return false
+        // (consistent with greaterOrEqual, greater, less, lessOrEqual behavior)
+        return semverValues.some(function (value) {
+          return semver.eq(semverTarget, value);
+        });
+      }
+      // Fall back to exact string comparison only when target fails to parse as semver
       return values.includes(targetValue);
     }
   }, {
@@ -109,6 +136,21 @@ var ClauseEvaluator = /*#__PURE__*/function () {
   }, {
     key: "in",
     value: function _in(targetValue, values) {
+      // First try semver comparison (with v-prefix normalization via semver.valid)
+      var semverTarget = semver.valid(targetValue);
+      if (semverTarget) {
+        var semverValues = values.map(function (v) {
+          return semver.valid(v);
+        }).filter(function (v) {
+          return v !== null;
+        });
+        // Target parsed as semver; if no values parsed or none matched, return false
+        // (consistent with greaterOrEqual, greater, less, lessOrEqual behavior)
+        return semverValues.some(function (value) {
+          return semver.eq(semverTarget, value);
+        });
+      }
+      // Fall back to exact string comparison only when target fails to parse as semver
       return values.includes(targetValue);
     }
   }, {

package/lib/clauseEvaluator.mjs

@@ -15,13 +15,23 @@ var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (
 }) : function(o, v) {
     o["default"] = v;
 });
-var __importStar = (this && this.__importStar) || function (mod) {
-    if (mod && mod.__esModule) return mod;
-    var result = {};
-    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
-    __setModuleDefault(result, mod);
-    return result;
-};
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ClauseEvaluator = void 0;
 const clause_pb_1 = require("./proto/feature/clause_pb");
@@ -65,6 +75,8 @@ class ClauseEvaluator {
                     return this.dependencyEvaluator.evaluate(clause.getAttribute(), clause.getValuesList(), flagVariations);
                 case clause_pb_1.Clause.Operator.PARTIALLY_MATCH:
                     return this.partiallyMatches(targetValue, clause.getValuesList());
+                case clause_pb_1.Clause.Operator.NOT_EQUALS:
+                    return !this.equals(targetValue, clause.getValuesList());
                 default:
                     return false;
             }
@@ -75,12 +87,34 @@ class ClauseEvaluator {
         }
     }
     equals(targetValue, values) {
+        // First try semver comparison (with v-prefix normalization via semver.valid)
+        const semverTarget = semver.valid(targetValue);
+        if (semverTarget) {
+            const semverValues = values
+                .map((v) => semver.valid(v))
+                .filter((v) => v !== null);
+            // Target parsed as semver; if no values parsed or none matched, return false
+            // (consistent with greaterOrEqual, greater, less, lessOrEqual behavior)
+            return semverValues.some((value) => semver.eq(semverTarget, value));
+        }
+        // Fall back to exact string comparison only when target fails to parse as semver
         return values.includes(targetValue);
     }
     partiallyMatches(targetValue, values) {
         return values.some((value) => targetValue.includes(value));
     }
     in(targetValue, values) {
+        // First try semver comparison (with v-prefix normalization via semver.valid)
+        const semverTarget = semver.valid(targetValue);
+        if (semverTarget) {
+            const semverValues = values
+                .map((v) => semver.valid(v))
+                .filter((v) => v !== null);
+            // Target parsed as semver; if no values parsed or none matched, return false
+            // (consistent with greaterOrEqual, greater, less, lessOrEqual behavior)
+            return semverValues.some((value) => semver.eq(semverTarget, value));
+        }
+        // Fall back to exact string comparison only when target fails to parse as semver
         return values.includes(targetValue);
     }
     startsWith(targetValue, values) {

package/lib/evaluation.d.ts

@@ -8,6 +8,7 @@ export declare function EvaluationID(featureID: string, featureVersion: number,
 declare class Evaluator {
     private ruleEvaluator;
     private strategyEvaluator;
+    private variationCache;
     constructor();
     evaluateFeatures(features: Feature[], user: User, mapSegmentUsers: Map<string, SegmentUser[]>, targetTag: string): Promise<UserEvaluations>;
     getPrerequisiteDownwards(targetFeatures: Feature[], allFeatures: Feature[]): Feature[];
@@ -21,5 +22,13 @@ declare class Evaluator {
     }): [Reason, Variation];
     getEvalFeatures(targetFeatures: Feature[], allFeatures: Feature[]): Feature[];
     private findVariation;
+    /**
+     * Converts YAML to JSON if needed, with in-memory caching.
+     * This ensures client SDKs can retrieve variation values using the object variation interface.
+     * Only performs conversion when the variation type is YAML.
+     * Cache key uses feature.updatedAt + variation.id to ensure cache invalidation when variations are updated.
+     */
+    private convertVariationValue;
 }
-export { Evaluator };
+declare function getFeatureIDsDependsOn(feature: Feature): Array<string>;
+export { Evaluator, getFeatureIDsDependsOn };