@infitx/match 0.0.1 → 1.4.0

package/CHANGELOG.md

@@ -0,0 +1,59 @@
+# 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)
+
+
+### Bug Fixes
+
+* update package versions and permissions in workflows ([c582d9f](https://github.com/infitx-org/release-cd/commit/c582d9faff24e6a0549e529608f0ef6a8b362bcf))
+
+## [1.3.1](https://github.com/infitx-org/release-cd/compare/match-v1.3.0...match-v1.3.1) (2026-02-09)
+
+
+### Bug Fixes
+
+* deploy ([9aa2bd6](https://github.com/infitx-org/release-cd/commit/9aa2bd69093d4374f86dd8554a527b627032c326))
+
+## [1.3.0](https://github.com/infitx-org/release-cd/compare/match-v1.2.1...match-v1.3.0) (2026-02-09)
+
+
+### Features
+
+* add .npmignore files and ci-publish script for decision and match libraries ([c518708](https://github.com/infitx-org/release-cd/commit/c5187080c63a215a670fcbe37a11989d6ec4c37f))
+
+## [1.2.1](https://github.com/infitx-org/release-cd/compare/match-v1.2.0...match-v1.2.1) (2026-02-04)
+
+
+### Bug Fixes
+
+* enhance match function to support reference time and update test cases ([deb24d0](https://github.com/infitx-org/release-cd/commit/deb24d078f82fdc358b43bf2aa174d537b169c1d))
+
+## [1.2.0](https://github.com/infitx-org/release-cd/compare/match-v1.1.1...match-v1.2.0) (2026-01-15)
+
+
+### Features
+
+* add negation support with 'not' property in match function ([31fddc6](https://github.com/infitx-org/release-cd/commit/31fddc6ae4e7661bf71e37e40490e6baf0ce38aa))
+* add support for Grafana-style time intervals in match function ([ef622bb](https://github.com/infitx-org/release-cd/commit/ef622bba120978b3cf5950a08d34dd5e47dbbea5))
+
+## [1.1.1](https://github.com/infitx-org/release-cd/compare/match-v1.1.0...match-v1.1.1) (2025-12-26)
+
+
+### Bug Fixes
+
+* improve match function for nullish values ([2c5a5c0](https://github.com/infitx-org/release-cd/commit/2c5a5c05ef34ddb013a610ba4357f34185e60eed))
+
+## [1.1.0](https://github.com/infitx-org/release-cd/compare/match-v1.0.0...match-v1.1.0) (2025-12-23)
+
+
+### Features
+
+* add build script to package.json for decision and match libraries ([f4da999](https://github.com/infitx-org/release-cd/commit/f4da9993feec346cc94f573fa103dffa8c4a9eed))
+* match and decision libraries ([db62341](https://github.com/infitx-org/release-cd/commit/db623419a179b3e0ec0cbda05b2f135e01375552))

package/README.md

@@ -0,0 +1,833 @@
+# Match Function
+
+A flexible matching utility that compares values with advanced semantic rules,
+supporting nested structures, arrays, type coercion, and various matching strategies.
+
+## Installation
+
+```javascript
+const match = require('./match');
+```
+
+## Basic Usage
+
+```javascript
+const match = require('./match');
+
+// Exact match
+match({ a: 1 }, { a: 1 }); // true
+match({ a: 1 }, { a: 2 }); // false
+
+// Partial object match
+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:
+
+```javascript
+// Nested object matching
+match(
+  { user: { name: 'Alice', age: 30 } },
+  { user: { name: 'Alice' } }
+); // true - partial match on nested object
+
+match(
+  { user: { name: 'Alice', age: 30 } },
+  { user: { name: 'Bob' } }
+); // false - name doesn't match
+
+// Deep nesting
+match(
+  { a: { b: { c: { d: 'value' } } } },
+  { a: { b: { c: { d: 'value' } } } }
+); // true
+
+match(
+  { a: { b: { c: { d: 'value', e: 'extra' } } } },
+  { a: { b: { c: { d: 'value' } } } }
+); // true - extra properties are ignored
+```
+
+## Array Matching (Any-Of Semantics)
+
+Arrays implement "any of" semantics - at least one element must match. The
+behavior varies depending on whether arrays appear in the value, the condition,
+or both.
+
+### Array in Condition (Rule)
+
+When the condition is an array, the value must match **at least one** element
+in the array:
+
+```javascript
+// Scalar value against array condition
+match('hello', ['hello', 'world']); // true - matches first element
+match('world', ['hello', 'world']); // true - matches second element
+match('goodbye', ['hello', 'world']); // false - matches none
+
+// With numbers
+match(5, [1, 5, 10]); // true
+match(7, [1, 5, 10]); // false
+
+// With booleans
+match(true, [true, false]); // true
+match(false, [true]); // false
+
+// In nested structures - scalar value against array condition
+match(
+  { status: 'active' },
+  { status: ['active', 'pending', 'processing'] }
+); // true - status matches one of the allowed values
+
+match(
+  { status: 'inactive' },
+  { status: ['active', 'pending'] }
+); // false - status doesn't match any allowed value
+```
+
+### Array in Value
+
+When the value is an array, **at least one element** must match the condition:
+
+```javascript
+// Array value against scalar condition
+match(['apple', 'banana'], 'apple'); // true - first element matches
+match(['apple', 'banana'], 'banana'); // true - second element matches
+match(['apple', 'banana'], 'orange'); // false - no element matches
+
+// With numbers
+match([1, 2, 3], 2); // true
+match([1, 2, 3], 5); // false
+
+// In nested structures - array value against scalar condition
+match(
+  { tags: ['javascript', 'node', 'async'] },
+  { tags: 'javascript' }
+); // true - at least one tag matches
+
+match(
+  { tags: ['python', 'django'] },
+  { tags: 'javascript' }
+); // false - no tag matches
+
+// Array value against function condition
+match(
+  { scores: [85, 90, 78] },
+  { scores: (score) => score >= 80 }
+); // true - at least one score is >= 80
+
+match(
+  { scores: [65, 70, 75] },
+  { scores: (score) => score >= 80 }
+); // false - no score is >= 80
+```
+
+### Array in Both Value and Condition
+
+When both are arrays, a match occurs if **any value element matches any
+condition element**:
+
+```javascript
+// Both arrays - cartesian "any of any" matching
+match(['red', 'blue'], ['blue', 'green']); // true - 'blue' appears in both
+match(['red', 'yellow'], ['blue', 'green']); // false - no common elements
+
+match([1, 2, 3], [3, 4, 5]); // true - '3' is in both
+match([1, 2], [3, 4]); // false - no overlap
+
+// In nested structures
+match(
+  { tags: ['javascript', 'node'] },
+  { tags: ['node', 'async', 'backend'] }
+); // true - 'node' is in both arrays
+
+match(
+  { tags: ['python', 'django'] },
+  { tags: ['javascript', 'react'] }
+); // false - no common tags
+
+// Complex: array value against array of conditions (including objects)
+match(
+  { priority: [1, 2, 3] },
+  { priority: [{ min: 2, max: 5 }, 10] }
+); // true - elements 2 and 3 match the range { min: 2, max: 5 }
+
+match(
+  { priority: [1] },
+  { priority: [{ min: 2, max: 5 }, 10] }
+); // false - 1 doesn't match range or 10
+```
+
+### Array Value Against Object Condition
+
+When an array value is matched against an object condition (like a range or
+complex object), each element is tested against the condition:
+
+```javascript
+// Array value against range condition
+match(
+  [1, 5, 10],
+  { min: 3, max: 7 }
+); // true - element '5' falls within the range
+
+match(
+  [1, 2],
+  { min: 3, max: 7 }
+); // false - no element falls within the range
+
+// In nested structures
+match(
+  { scores: [45, 67, 89, 92] },
+  { scores: { min: 80 } }
+); // true - elements 89 and 92 are >= 80
+
+match(
+  { scores: [45, 67, 75] },
+  { scores: { min: 80 } }
+); // false - no score is >= 80
+
+// Array value against regex condition
+match(
+  { emails: ['admin@test.com', 'invalid', 'user@test.com'] },
+  { emails: /@test\.com$/ }
+); // true - at least one email matches the pattern
+
+match(
+  { emails: ['invalid1', 'invalid2'] },
+  { emails: /@test\.com$/ }
+); // false - no email matches
+```
+
+### Combining Arrays with Null
+
+Arrays can include `null` to make conditions optional:
+
+```javascript
+// Array with null - matches if property is missing OR matches other values
+match(
+  { status: 'active' },
+  { status: [null, 'active'] }
+); // true - matches 'active'
+
+match(
+  { name: 'Alice' },
+  { status: [null, 'active'] }
+); // true - 'status' is missing, matches null
+
+match(
+  { status: false },
+  { status: [null, 'active'] }
+); // false - false is neither null nor 'active'
+
+match(
+  { status: undefined },
+  { status: [null, 'active'] }
+); // true - undefined treated as null
+
+// Nested with arrays and null
+match(
+  { user: { role: 'admin' } },
+  { user: { role: [null, 'admin', 'moderator'] } }
+); // true - role matches 'admin'
+
+match(
+  { user: { name: 'Alice' } },
+  { user: { role: [null, 'admin'], name: 'Alice' } }
+); // true - role is missing (matches null), name matches
+```
+
+### Array Behavior Summary
+
+| Value Type | Condition Type             | Behavior                                      |
+| ---------- | -------------------------- | --------------------------------------------- |
+| Scalar     | Array                      | Value must match at least one array element   |
+| Array      | Scalar                     | At least one value must match the scalar      |
+| Array      | Array                      | At least one value must match one condition   |
+| Array      | Object (range/complex)     | At least one value must match the condition   |
+| Array      | Function                   | At least one value must satisfy the function  |
+
+## Matching Against Non-Existing Properties
+
+The match function has special handling for `null` values to match against
+non-existing properties:
+
+```javascript
+// null matches undefined/missing properties
+match({ b: 0 }, { a: null }); // true - 'a' is missing
+
+match({ a: null }, { a: null }); // true - both null
+
+match({ a: undefined }, { a: null }); // true - undefined treated as null
+
+match({ a: false }, { a: null }); // false - false is not null
+
+match({ a: 0 }, { a: null }); // false - 0 is not null
+
+match({ a: '' }, { a: null }); // false - empty string is not null
+
+// Nested non-existing properties
+match(
+  { a: {} },
+  { a: { b: null } }
+); // true - 'b' doesn't exist in nested object
+
+match(
+  { a: { b: false } },
+  { a: { b: null } }
+); // false - 'b' exists and is false
+
+// Array with null for optional properties
+match(
+  { status: 'active' },
+  { status: [null, 'active'] }
+); // true - matches 'active'
+
+match(
+  { name: 'Alice' },
+  { status: [null, 'active'] }
+); // true - 'status' is missing, matches null
+
+match(
+  { status: false },
+  { status: [null, 'active'] }
+); // false - false doesn't match null or 'active'
+```
+
+## Type Coercion
+
+The function coerces values to match the type of the rule:
+
+```javascript
+// Boolean coercion
+match('hello', true); // true - truthy string
+match('', false); // true - falsy empty string
+match(0, false); // true - falsy zero
+match(1, true); // true - truthy number
+
+// String coercion
+match(123, '123'); // true
+match(true, 'true'); // true
+
+// Number coercion
+match('42', 42); // true
+match('3.14', 3.14); // true
+```
+
+## Range Matching
+
+Use `min` and `max` for numeric and date range matching:
+
+```javascript
+// Numeric ranges
+match(5, { min: 1, max: 10 }); // true
+match(15, { min: 1, max: 10 }); // false
+match(1, { min: 1 }); // true - only minimum
+match(10, { max: 10 }); // true - only maximum
+
+// Date ranges
+const now = new Date('2025-06-15');
+const start = new Date('2025-01-01');
+const end = new Date('2025-12-31');
+
+match(now, { min: start, max: end }); // true
+match(new Date('2026-01-01'), { min: start, max: end }); // false
+
+// Nested range matching
+match(
+  { user: { age: 25 } },
+  { user: { age: { min: 18, max: 65 } } }
+); // true
+```
+
+### Grafana-Style Time Intervals
+
+The `min` and `max` properties support Grafana-style relative time intervals
+for convenient time-based matching:
+
+```javascript
+// Current time
+match(new Date(), { min: 'now-1h', max: 'now' });
+// true - current time is within the last hour
+
+// Future time check
+match(new Date(), { max: 'now+1d' });
+// true - current time is before tomorrow
+
+// Past time check
+match(new Date(), { min: 'now-1w' });
+// true - current time is within the last week
+
+// Time range
+match(
+  new Date(),
+  { min: 'now-1d', max: 'now+1d' }
+); // true - current time is within ±1 day
+
+// In nested structures
+match(
+  { event: { timestamp: new Date() } },
+  { event: { timestamp: { min: 'now-5m' } } }
+); // true - event occurred within the last 5 minutes
+
+match(
+  { event: { timestamp: new Date(Date.now() - 10 * 60 * 1000) } },
+  { event: { timestamp: { min: 'now-5m' } } }
+); // false - event occurred more than 5 minutes ago
+```
+
+#### Supported Time Units
+
+| Unit | Description    | Example     |
+| ---- | -------------- | ----------- |
+| `ms` | Milliseconds   | `now-500ms` |
+| `s`  | Seconds        | `now-30s`   |
+| `m`  | Minutes        | `now-5m`    |
+| `h`  | Hours          | `now-2h`    |
+| `d`  | Days           | `now-7d`    |
+| `w`  | Weeks          | `now-2w`    |
+| `M`  | Months (30d)   | `now-3M`    |
+| `y`  | Years (365d)   | `now-1y`    |
+
+#### Rounding Units
+
+When using the `/` operator, you can round to these time units:
+
+| Unit | Rounds To            | Example                          |
+| ---- | -------------------- | -------------------------------- |
+| `s`  | Start of second      | `now/s` = current second at .000 |
+| `m`  | Start of minute      | `now/m` = current minute at :00  |
+| `h`  | Start of hour        | `now/h` = current hour at :00:00 |
+| `d`  | Start of day         | `now/d` = today at 00:00:00      |
+| `w`  | Start of week        | `now/w` = Monday at 00:00:00     |
+| `M`  | Start of month       | `now/M` = 1st of month 00:00:00  |
+| `y`  | Start of year        | `now/y` = Jan 1st at 00:00:00    |
+
+**Note**: Week rounding always rounds to Monday as the first day of the week.
+
+#### Time Interval Format
+
+- **`now`**: Current time
+- **`now-<amount><unit>`**: Time in the past (e.g., `now-5m` = 5 minutes ago)
+- **`now+<amount><unit>`**: Time in the future (e.g., `now+1h` = 1 hour from now)
+- **`now/<unit>`**: Current time rounded to start of unit (e.g., `now/d` = start of today)
+- **`now[+-]<amount><unit>/<roundUnit>`**: Time with offset, rounded (e.g., `now-5d/d` = 5 days ago at midnight)
+
+#### Time Rounding
+
+The `/` operator rounds timestamps to the start of the specified time unit, following Grafana's approach:
+
+```javascript
+// Round to start of current day (midnight)
+match(new Date('2025-06-15T14:30:00'), { min: 'now/d', max: 'now' });
+// Compares against start of current day
+
+// Round to start of current hour
+match(new Date(), { min: 'now/h' });
+// Matches times from the start of the current hour
+
+// Combine offset and rounding
+// Example: 5 days ago, rounded to midnight of that day
+match(new Date(), { min: 'now-5d/d' });
+
+// Week rounding (rounds to Monday)
+match(new Date(), { min: 'now/w' });
+// Matches times from the start of the current week
+
+// Month rounding
+match(new Date(), { min: 'now-1M/M' });
+// Matches times from the start of last month
+
+// Rounding units: s (second), m (minute), h (hour), d (day),
+// w (week), M (month), y (year)
+```
+
+```javascript
+// Examples with different units
+match(new Date(), { min: 'now-500ms' }); // Last 500 milliseconds
+match(new Date(), { min: 'now-30s' }); // Last 30 seconds
+match(new Date(), { min: 'now-5m' }); // Last 5 minutes
+match(new Date(), { min: 'now-2h' }); // Last 2 hours
+match(new Date(), { min: 'now-7d' }); // Last 7 days
+match(new Date(), { min: 'now-2w' }); // Last 2 weeks
+match(new Date(), { min: 'now-3M' }); // Last 3 months (approx)
+match(new Date(), { min: 'now-1y' }); // Last year (approx)
+
+// Future times
+match(new Date(), { max: 'now+1h' }); // Within next hour
+match(new Date(), { max: 'now+7d' }); // Within next 7 days
+
+// Examples with rounding
+match(new Date(), { min: 'now/d' }); // Since midnight today
+match(new Date(), { min: 'now-7d/d', max: 'now/d' }); // Last 7 full days
+match(new Date(), { min: 'now/M' }); // Since start of current month
+match(new Date(), { min: 'now-1y/y', max: 'now/y' }); // Last full year
+
+// Practical examples
+// Check if log entry is recent (last 15 minutes)
+match(
+  { log: { timestamp: new Date() } },
+  { log: { timestamp: { min: 'now-15m' } } }
+); // true
+
+// Check if event occurred today (since midnight)
+match(
+  { event: { timestamp: new Date() } },
+  { event: { timestamp: { min: 'now/d' } } }
+); // true if event is from today
+
+// Check if data is from the current month
+match(
+  { report: { date: new Date() } },
+  { report: { date: { min: 'now/M', max: 'now' } } }
+); // true if report is from current month
+
+// Check if scheduled event is upcoming (next 24 hours)
+match(
+  { event: { scheduledAt: new Date(Date.now() + 12 * 60 * 60 * 1000) } },
+  { event: { scheduledAt: { min: 'now', max: 'now+1d' } } }
+); // true
+
+// Check if user session is still valid (created within last 30 minutes)
+match(
+  { session: { createdAt: new Date(Date.now() - 10 * 60 * 1000) } },
+  { session: { createdAt: { min: 'now-30m' } } }
+); // true
+
+// Daily reports: match events from start of day until now
+match(
+  { log: { timestamp: new Date() } },
+  { log: { timestamp: { min: 'now/d', max: 'now' } } }
+); // Matches anything that happened today
+
+// Weekly reports: last 7 complete days
+match(
+  { metric: { recorded: new Date() } },
+  { metric: { recorded: { min: 'now-7d/d', max: 'now/d' } } }
+); // Matches data from last 7 full days (midnight to midnight)
+
+// Business hours check: events during current hour
+match(
+  { transaction: { timestamp: new Date() } },
+  { transaction: { timestamp: { min: 'now/h', max: 'now' } } }
+); // Matches transactions from start of current hour
+```
+
+## Function Predicates
+
+Use functions for custom matching logic:
+
+```javascript
+// Function as rule
+match(10, (value) => value > 5); // true
+match(3, (value) => value > 5); // false
+
+// Complex predicate
+match(
+  'hello@example.com',
+  (value) => /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(value)
+); // true - valid email
+
+// Function in nested structure
+match(
+  { user: { age: 25 } },
+  { user: { age: (age) => age >= 18 } }
+); // true
+```
+
+## Negation with `not`
+
+Use the `not` property in an object condition to negate any match:
+
+```javascript
+// Basic negation
+match(3, { not: 5 }); // true - 3 is not 5
+match(5, { not: 5 }); // false - 5 is 5
+
+// Negate string match
+match('goodbye', { not: 'hello' }); // true
+match('hello', { not: 'hello' }); // false
+
+// Negate boolean
+match(false, { not: true }); // true
+match(true, { not: true }); // false
+match(0, { not: true }); // true - 0 is falsy, not true
+match(1, { not: true }); // false - 1 coerces to true
+
+// Negate null
+match(0, { not: null }); // true - 0 is not null
+match(null, { not: null }); // false
+match(undefined, { not: null }); // false - undefined treated as null
+
+// In nested structures
+match(
+  { status: 'inactive' },
+  { status: { not: 'active' } }
+); // true
+
+match(
+  { status: 'active' },
+  { status: { not: 'active' } }
+); // false
+```
+
+### Negating Complex Conditions
+
+The `not` property works with all match types including arrays, ranges,
+functions, and regex:
+
+```javascript
+// Negate regex
+match('goodbye', { not: /hello/ }); // true
+match('hello world', { not: /hello/ }); // false
+
+match(
+  { email: 'user@domain.org' },
+  { email: { not: /@example\.com$/ } }
+); // true - doesn't end with @example.com
+
+// Negate array (none of)
+match(5, { not: [1, 2, 3] }); // true - 5 is not in the list
+match(2, { not: [1, 2, 3] }); // false - 2 is in the list
+
+match(
+  { role: 'guest' },
+  { role: { not: ['admin', 'moderator'] } }
+); // true - guest is neither admin nor moderator
+
+match(
+  { role: 'admin' },
+  { role: { not: ['admin', 'moderator'] } }
+); // false - admin is in the list
+
+// Negate range
+match(3, { not: { min: 5, max: 10 } }); // true - 3 is outside the range
+match(7, { not: { min: 5, max: 10 } }); // false - 7 is in the range
+match(15, { not: { min: 5, max: 10 } }); // true - 15 is outside the range
+
+match(
+  { age: 15 },
+  { age: { not: { min: 18, max: 65 } } }
+); // true - age is below minimum
+
+match(
+  { age: 25 },
+  { age: { not: { min: 18, max: 65 } } }
+); // false - age is in range
+
+// Negate function predicate
+match(3, { not: (v) => v > 5 }); // true - 3 is not > 5
+match(10, { not: (v) => v > 5 }); // false - 10 is > 5
+
+match(
+  { price: 25 },
+  { price: { not: (p) => p >= 100 } }
+); // true - price is not >= 100
+
+// Negate object match
+match(
+  { user: { role: 'guest' } },
+  { user: { not: { role: 'admin' } } }
+); // true - role is not admin
+
+match(
+  { user: { role: 'admin' } },
+  { user: { not: { role: 'admin' } } }
+); // false - role is admin
+
+// Complex negation in nested structures
+match(
+  {
+    user: {
+      email: 'user@custom.com',
+      role: 'user'
+    }
+  },
+  {
+    user: {
+      email: { not: /@example\.com$/ },
+      role: { not: ['admin', 'moderator'] }
+    }
+  }
+); // true - email doesn't end with @example.com and role is not admin/moderator
+```
+
+### Combining `not` with Other Conditions
+
+You can combine `not` with other conditions in complex matching scenarios:
+
+```javascript
+// Exclude certain values while checking other properties
+match(
+  { status: 'pending', priority: 2 },
+  {
+    status: { not: ['cancelled', 'completed'] },
+    priority: { min: 1, max: 3 }
+  }
+); // true - status is not cancelled/completed and priority is in range
+
+// Array values with negation
+match(
+  { tags: ['javascript', 'backend'] },
+  { tags: { not: 'frontend' } }
+); // true - none of the tags are 'frontend'
+
+match(
+  { tags: ['javascript', 'frontend'] },
+  { tags: { not: 'frontend' } }
+); // false - 'frontend' is in the tags
+```
+
+## Regular Expression Matching
+
+```javascript
+// Regex patterns
+match('hello world', /hello/); // true
+match('goodbye world', /hello/); // false
+
+// Case-insensitive matching
+match('Hello World', /hello/i); // true
+
+// Nested regex
+match(
+  { email: 'user@example.com' },
+  { email: /^[^\s@]+@[^\s@]+\.[^\s@]+$/ }
+); // true
+```
+
+## Complex Examples
+
+Combining multiple matching strategies:
+
+```javascript
+// Complex nested structure with arrays and nulls
+match(
+  {
+    user: {
+      name: 'Alice',
+      email: 'alice@example.com',
+      roles: ['admin', 'user']
+    },
+    status: 'active'
+  },
+  {
+    user: {
+      email: /@example\.com$/,
+      roles: 'admin'
+    },
+    status: ['active', 'pending'],
+    lastLogin: null // optional field
+  }
+); // true
+
+// Multiple conditions
+match(
+  { price: 50, category: 'electronics', inStock: true },
+  {
+    price: { min: 0, max: 100 },
+    category: ['electronics', 'computers'],
+    inStock: true,
+    discount: null // discount is optional
+  }
+); // true
+```
+
+## API
+
+### `match(factValue, ruleValue)`
+
+Compares a fact value against a rule value with flexible matching semantics.
+
+**Parameters:**
+
+- `factValue` (any): The actual value to test
+- `ruleValue` (any): The pattern/rule to match against
+
+**Returns:**
+
+- `boolean`: `true` if the fact matches the rule, `false` otherwise
+
+**Matching Rules:**
+
+- **Exact equality**: Returns `true` if values are strictly equal
+- **Null handling**: `null` in rule matches `null` or `undefined` in fact
+- **Arrays**: "Any of" semantics - at least one element must match
+- **Objects**: Recursively matches properties (partial matching allowed)
+- **Type coercion**: Values are coerced to match rule type
+- **Ranges**: Objects with `min`/`max` properties enable range matching
+- **Negation**: Objects with `not` property negate any match condition
+- **Functions**: Rule functions are called with fact value as predicate
+- **RegExp**: Tests string values against regex patterns
+
+## License
+
+See the main project license.

package/index.js

@@ -0,0 +1,195 @@
+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);
+
+    switch (unit) {
+        case 's': // Round to start of second
+            d.setMilliseconds(0);
+            break;
+        case 'm': // Round to start of minute
+            d.setSeconds(0, 0);
+            break;
+        case 'h': // Round to start of hour
+            d.setMinutes(0, 0, 0);
+            break;
+        case 'd': // Round to start of day
+            d.setHours(0, 0, 0, 0);
+            break;
+        case 'w': // Round to start of week (Monday)
+            d.setHours(0, 0, 0, 0);
+            const day = d.getDay();
+            const diff = day === 0 ? 6 : day - 1; // Monday is 1, Sunday is 0
+            d.setDate(d.getDate() - diff);
+            break;
+        case 'M': // Round to start of month
+            d.setDate(1);
+            d.setHours(0, 0, 0, 0);
+            break;
+        case 'y': // Round to start of year
+            d.setMonth(0, 1);
+            d.setHours(0, 0, 0, 0);
+            break;
+    }
+
+    return d;
+}
+
+// Parse Grafana-style time intervals (now, now-5m, now+1h, now/d, now-5d/d, etc.)
+function parseTimeInterval(str, referenceTime) {
+    if (typeof str !== 'string') return null;
+
+    // Handle "now" without modifiers
+    if (str === 'now') return new Date(referenceTime);
+
+    // Handle "now/unit" (rounding without offset)
+    const roundOnlyMatch = /^now\/([smhdwMy])$/.exec(str);
+    if (roundOnlyMatch) {
+        const [, unit] = roundOnlyMatch;
+        return roundToUnit(new Date(referenceTime), unit);
+    }
+
+    // Handle "now[+-]amount(unit)" or "now[+-]amount(unit)/roundUnit"
+    const match = /^now([+-])(\d+)(ms|s|m|h|d|w|M|y)(?:\/([smhdwMy]))?$/.exec(str);
+    if (!match) return null;
+
+    const [, sign, amount, unit, roundUnit] = match;
+    const value = parseInt(amount, 10);
+    const multiplier = sign === '+' ? 1 : -1;
+
+    // Convert to milliseconds
+    const unitMultipliers = {
+        ms: 1,
+        s: 1000,
+        m: 60 * 1000,
+        h: 60 * 60 * 1000,
+        d: 24 * 60 * 60 * 1000,
+        w: 7 * 24 * 60 * 60 * 1000,
+        M: 30 * 24 * 60 * 60 * 1000, // Approximate month
+        y: 365 * 24 * 60 * 60 * 1000  // Approximate year
+    };
+
+    const offset = multiplier * value * unitMultipliers[unit];
+    const resultTime = new Date(referenceTime + offset);
+
+    // Apply rounding if specified
+    if (roundUnit) {
+        return roundToUnit(resultTime, roundUnit);
+    }
+
+    return resultTime;
+}
+
+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, rootFact))
+            : condition.some(v => module.exports(value, v, referenceTime, rootFact));
+    } else if (value == null || condition == null) {
+        return false;
+    } else if (condition instanceof RegExp) {
+        if (typeof value === 'string') return condition.test(value);
+    } else if (condition instanceof Date) {
+        value = value instanceof Date ? value.getTime() : new Date(value).getTime();
+        condition = condition.getTime();
+        if (!Number.isFinite(value) || !Number.isFinite(condition)) return false;
+        return value === condition;
+    } else if (Number.isNaN(value) || Number.isNaN(condition)) return false;
+    switch (typeof condition) {
+        case 'boolean':
+            return Boolean(value) === condition;
+        case 'string':
+            return String(value) === condition;
+        case 'number':
+            return Number(value) === condition;
+        case 'function':
+            return condition(value);
+        case 'object': {
+            let { min, max, not } = condition;
+            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') {
+                const parsed = parseTimeInterval(min, referenceTime);
+                if (parsed) min = parsed;
+            }
+            if (typeof max === 'string') {
+                const parsed = parseTimeInterval(max, referenceTime);
+                if (parsed) max = parsed;
+            }
+
+            if (value instanceof Date) {
+                value = value.getTime();
+                if (!Number.isFinite(value)) return false;
+                if (min != null) min = new Date(min).getTime();
+                if (max != null) max = new Date(max).getTime();
+            } else if (min instanceof Date || max instanceof Date) {
+                value = new Date(value).getTime();
+                if (!Number.isFinite(value)) return false;
+            }
+            if (min instanceof Date) min = min.getTime();
+            if (max instanceof Date) max = max.getTime();
+            if (Number.isNaN(min)) return false;
+            if (Number.isNaN(max)) return false;
+            if (min != null && (value < min || value === -Infinity || min === Infinity))
+                return false;
+            if (max != null && (value > max || value === Infinity || max === -Infinity))
+                return false;
+            if (min != null || max != null) return true;
+            // 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(), 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, rootFact);
+    if (
+        Array.isArray(factValue) ||
+        Array.isArray(ruleValue) ||
+        !isPlainObject(factValue) ||
+        !isPlainObject(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, rootFact));
+};

package/package.json

@@ -1,12 +1,25 @@
 {
     "name": "@infitx/match",
-    "version": "0.0.1",
-    "description": "",
-    "license": "ISC",
-    "author": "",
-    "type": "commonjs",
+    "version": "1.4.0",
+    "description": "Object pattern matching utility",
     "main": "index.js",
     "scripts": {
-        "test": "echo \"Error: no test specified\" && exit 1"
-    }
-}
+        "build": "true",
+        "ci-unit": "JEST_JUNIT_OUTPUT_DIR=coverage jest --ci --reporters=default --reporters=jest-junit --outputFile=./coverage/junit.xml",
+        "ci-publish": "npm publish --access public --provenance",
+        "watch": "jest --watchAll"
+    },
+    "dependencies": {
+        "lodash": "^4.17.21"
+    },
+    "devDependencies": {
+        "yaml": "^2.8.2",
+        "jest": "^30.2.0",
+        "jest-junit": "^16.0.0"
+    },
+    "repository": {
+        "url": "git+https://github.com/infitx-org/release-cd.git"
+    },
+    "author": "Kalin Krustev",
+    "license": "Apache-2.0"
+}