@infitx/match 0.0.1 → 1.3.2

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+## [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,765 @@
+# 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
+```
+
+## 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,167 @@
+const isMatchWith = require('lodash/isMatchWith');
+const isPlainObject = require('lodash/isPlainObject');
+
+// 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];
+    console.log({ referenceTime, offset });
+    const resultTime = new Date(referenceTime + offset);
+
+    // Apply rounding if specified
+    if (roundUnit) {
+        return roundToUnit(resultTime, roundUnit);
+    }
+
+    return resultTime;
+}
+
+const match = (referenceTime) => (value, condition) => {
+    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));
+    } 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);
+
+            // 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;
+            }
+
+            console.log({ min, max, value });
+            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 (typeof value === 'object' && value && condition) return module.exports(value, condition, referenceTime);
+        }
+    }
+}
+
+module.exports = function (factValue, ruleValue, referenceTime = Date.now()) {
+    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 (
+        Array.isArray(factValue) ||
+        Array.isArray(ruleValue) ||
+        !isPlainObject(factValue) ||
+        !isPlainObject(ruleValue)
+    )
+        return match(referenceTime)(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));
+};

package/package.json

@@ -1,12 +1,25 @@
 {
     "name": "@infitx/match",
-    "version": "0.0.1",
-    "description": "",
-    "license": "ISC",
-    "author": "",
-    "type": "commonjs",
+    "version": "1.3.2",
+    "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"
+}