@infitx/match 1.3.2 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.4.0](https://github.com/infitx-org/release-cd/compare/match-v1.3.2...match-v1.4.0) (2026-02-10)
+
+
+### Features
+
+* add $ref support for dynamic fact references in match rules ([#135](https://github.com/infitx-org/release-cd/issues/135)) ([032b207](https://github.com/infitx-org/release-cd/commit/032b20734cbe559b25126c25e5d7130e1a3cf7b3))
+
 ## [1.3.2](https://github.com/infitx-org/release-cd/compare/match-v1.3.1...match-v1.3.2) (2026-02-09)
 
 

package/README.md

@@ -22,6 +22,74 @@ match({ a: 1 }, { a: 2 }); // false
 match({ a: 1, b: 2 }, { a: 1 }); // true
 ```
 
+## Referencing Fact Values with `$ref`
+
+The `$ref` feature allows rules to reference values from other parts of the fact using JSON Pointer syntax. This is useful for dynamic comparisons where the expected value comes from the fact itself.
+
+```javascript
+// Reference another property in the fact
+match(
+  { expectedStatus: 'active', order: { status: 'active' } },
+  { order: { status: { $ref: '#/expectedStatus' } } }
+); // true - order.status matches expectedStatus
+
+// Use $ref in min/max range conditions
+match(
+  { offer: { dateCreated: '2024-01-01' }, order: { dateCreated: '2024-02-01' } },
+  { order: { dateCreated: { min: { $ref: '#/offer/dateCreated' } } } }
+); // true - order date is after offer date
+
+// Multiple $ref in same rule
+match(
+  { source: 'Alice', destination: 'Bob', transfer: { from: 'Alice', to: 'Bob' } },
+  { transfer: { from: { $ref: '#/source' }, to: { $ref: '#/destination' } } }
+); // true - transfer from/to matches source/destination
+
+// $ref with nested paths
+match(
+  { config: { pricing: { minPrice: 100 } }, order: { price: 150 } },
+  { order: { price: { min: { $ref: '#/config/pricing/minPrice' } } } }
+); // true - order price is above configured minimum
+
+// Missing properties resolve to undefined
+match(
+  { order: { dateCreated: '2024-02-01' } },
+  { order: { dateCreated: { min: { $ref: '#/offer/dateCreated' } } } }
+); // true - missing reference is treated as no constraint
+
+// $ref with type coercion
+match(
+  { targetAmount: '500', order: { amount: 500 } },
+  { order: { amount: { $ref: '#/targetAmount' } } }
+); // true - string '500' is coerced to number 500
+
+// $ref with arrays (any-of semantics apply)
+match(
+  { allowedTag: 'vip', order: { tags: ['vip', 'premium'] } },
+  { order: { tags: { $ref: '#/allowedTag' } } }
+); // true - at least one tag matches the reference
+```
+
+### JSON Pointer Syntax
+
+The `$ref` value uses JSON Pointer syntax (RFC 6901):
+- Always starts with `#/` to indicate the root of the fact object
+- Properties are separated by `/` 
+- Examples:
+  - `#/offer/dateCreated` → `fact.offer.dateCreated`
+  - `#/config/pricing/minPrice` → `fact.config.pricing.minPrice`
+  - `#/expectedStatus` → `fact.expectedStatus`
+
+### When to Use `$ref`
+
+Use `$ref` when you need to:
+- Compare related values within the same fact
+- Implement dynamic constraints based on other properties
+- Reference configuration values from the fact
+- Create rules that adapt to the data being matched
+
+```
+
 ## Matching Against Nested Structures
 
 The match function recursively compares nested objects:

package/index.js

@@ -1,6 +1,18 @@
 const isMatchWith = require('lodash/isMatchWith');
 const isPlainObject = require('lodash/isPlainObject');
 
+// Resolve JSON Pointer path from fact (e.g., "#/offer/dateCreated")
+function resolveRef(refPath, factValue) {
+    if (typeof refPath !== 'string' || !refPath.startsWith('#/')) return undefined;
+    const path = refPath.slice(2).split('/');
+    let value = factValue;
+    for (const key of path) {
+        if (value == null) return undefined;
+        value = value[key];
+    }
+    return value;
+}
+
 // Round a date to the start of a time unit
 function roundToUnit(date, unit) {
     const d = new Date(date);
@@ -72,7 +84,6 @@ function parseTimeInterval(str, referenceTime) {
     };
 
     const offset = multiplier * value * unitMultipliers[unit];
-    console.log({ referenceTime, offset });
     const resultTime = new Date(referenceTime + offset);
 
     // Apply rounding if specified
@@ -83,15 +94,20 @@ function parseTimeInterval(str, referenceTime) {
     return resultTime;
 }
 
-const match = (referenceTime) => (value, condition) => {
+const match = (referenceTime, rootFact) => (value, condition) => {
+    // Resolve $ref if condition is a reference object
+    if (isPlainObject(condition) && '$ref' in condition && Object.keys(condition).length === 1) {
+        condition = resolveRef(condition.$ref, rootFact);
+    }
+
     if (value == null && condition == null) {
         return true
     } else if (value === condition) {
         return true;
     } else if (Array.isArray(condition) || Array.isArray(value)) {
         return Array.isArray(value)
-            ? value.some(v => module.exports(v, condition, referenceTime))
-            : condition.some(v => module.exports(value, v, referenceTime));
+            ? value.some(v => module.exports(v, condition, referenceTime, rootFact))
+            : condition.some(v => module.exports(value, v, referenceTime, rootFact));
     } else if (value == null || condition == null) {
         return false;
     } else if (condition instanceof RegExp) {
@@ -113,7 +129,15 @@ const match = (referenceTime) => (value, condition) => {
             return condition(value);
         case 'object': {
             let { min, max, not } = condition;
-            if (not != null) return !module.exports(value, not, referenceTime);
+            if (not != null) return !module.exports(value, not, referenceTime, rootFact);
+
+            // Resolve $ref in min and max
+            if (isPlainObject(min) && min.$ref) {
+                min = resolveRef(min.$ref, rootFact);
+            }
+            if (isPlainObject(max) && max.$ref) {
+                max = resolveRef(max.$ref, rootFact);
+            }
 
             // Parse Grafana-style time intervals for min and max
             if (typeof min === 'string') {
@@ -125,7 +149,6 @@ const match = (referenceTime) => (value, condition) => {
                 if (parsed) max = parsed;
             }
 
-            console.log({ min, max, value });
             if (value instanceof Date) {
                 value = value.getTime();
                 if (!Number.isFinite(value)) return false;
@@ -144,24 +167,29 @@ const match = (referenceTime) => (value, condition) => {
             if (max != null && (value > max || value === Infinity || max === -Infinity))
                 return false;
             if (min != null || max != null) return true;
-            if (typeof value === 'object' && value && condition) return module.exports(value, condition, referenceTime);
+            // If condition only contains min/max/not (which have been handled above),
+            // and all resolved to undefined/null, return true (no constraints to enforce)
+            const conditionKeys = Object.keys(condition);
+            if (conditionKeys.every(k => ['min', 'max', 'not'].includes(k))) return true;
+            if (typeof value === 'object' && value && condition) return module.exports(value, condition, referenceTime, rootFact);
         }
     }
 }
 
-module.exports = function (factValue, ruleValue, referenceTime = Date.now()) {
+module.exports = function (factValue, ruleValue, referenceTime = Date.now(), rootFact = undefined) {
+    if (rootFact === undefined) rootFact = factValue;  // Store the root fact for $ref resolution only on first call
     if (factValue === ruleValue) return true;
-    if (ruleValue && typeof ruleValue === 'object' && 'not' in ruleValue && Object.keys(ruleValue).length === 1) return !module.exports(factValue, ruleValue.not, referenceTime);
+    if (ruleValue && typeof ruleValue === 'object' && 'not' in ruleValue && Object.keys(ruleValue).length === 1) return !module.exports(factValue, ruleValue.not, referenceTime, rootFact);
     if (
         Array.isArray(factValue) ||
         Array.isArray(ruleValue) ||
         !isPlainObject(factValue) ||
         !isPlainObject(ruleValue)
     )
-        return match(referenceTime)(factValue, ruleValue);
+        return match(referenceTime, rootFact)(factValue, ruleValue);
     if (factValue && ruleValue && typeof factValue === 'object' && typeof ruleValue === 'object') {
         const nullFilter = Object.entries(ruleValue).filter(([, value]) => value == null || Array.isArray(value));
         if (nullFilter.length > 0) factValue = { ...Object.fromEntries(nullFilter), ...factValue };
     };
-    return isMatchWith(factValue, ruleValue, match(referenceTime));
+    return isMatchWith(factValue, ruleValue, match(referenceTime, rootFact));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@infitx/match",
-    "version": "1.3.2",
+    "version": "1.4.0",
     "description": "Object pattern matching utility",
     "main": "index.js",
     "scripts": {