Make == / != valueOf-aware so DateTime values just work

Equal/notEqual in the core compare two non-null objects by their
`valueOf()` result whenever both operands return a primitive distinct
from themselves. This mirrors what `<` / `>` / `<=` / `>=` already
did via JavaScript's `ToPrimitive` algorithm, and lets values like
Luxon `DateTime` and JS `Date` compare by instant without the core
ever knowing about either type.

Twelve-line change to packages/expreszo/src/operators/binary/comparison.ts:

* `equal(a, b)` short-circuits on `a === b`, then for two non-null
  object operands calls `a.valueOf()` and `b.valueOf()`. If neither
  result is the object itself (i.e. both have a meaningful primitive
  form), it returns `av === bv`. Otherwise falls through to false,
  preserving today's reference-equality semantics for plain objects
  and arrays.
* `notEqual(a, b)` is now `!equal(a, b)`.

What this changes:
* Two `Date` instances at the same millisecond are now `==`.
* Two Luxon `DateTime` values at the same instant are now `==` (when
  the @pro-fa/expreszo-datetime plugin is registered, since that's
  the source of the values).
* Boxed primitives (new Number(5), new String('x')) compare by their
  primitive form too.

What this does NOT change:
* Plain objects ({a:1} == {a:1}) still false — they have no
  overridden valueOf, so the new branch falls through.
* Arrays ([1,2] == [1,2]) still false, same reason.
* Primitives keep their existing semantics.
* null/undefined handling unchanged.
* Object compared to a primitive is still false — no implicit
  cross-type coercion.

No plugin changes required. Users register `dateTimePlugin` exactly
as before; all six comparison operators (`<`, `>`, `<=`, `>=`, `==`,
`!=`) work on DateTimes (and JS Dates) automatically.

Tests:
* 9 new tests in packages/expreszo/test/operators/operators-comparison.ts
  covering Date↔Date, custom-valueOf objects, Date↔custom-valueOf
  cross-type, plain objects (still false), arrays (still false),
  NaN-valued Dates (still not equal), object vs primitive,
  null handling.
* 4 new tests in packages/expreszo-datetime/test/plugin.test.ts
  covering the actual Luxon DateTime path end-to-end and DateTime↔Date
  cross-type equality.

Versions:
* @pro-fa/expreszo: 0.6.0 -> 0.6.1
* @pro-fa/expreszo-datetime: 0.2.0 -> 0.2.1, peer-dep range bumped
  to ^0.6.1 to require the new equality behaviour.

Docs:
* BREAKING_CHANGES.md gains a 0.6.1 section explaining the change,
  what's affected, and what isn't.
* CHANGELOG.md (datetime) gains a 0.2.1 entry pointing at the core
  change as the source.
* docs/datetime.md "Comparison" section now leads with the operator
  examples and demotes the named functions to the millisecond-truncated
  / range / sortable cases.
* docs/datetime-integration.md gains an "Operators on DateTime values"
  section explaining the valueOf duck-typing and noting that
  arithmetic operators (+, -) are intentionally not covered.

Verified: yarn workspaces run lint/type-check/test all green
(2200 core + 25 datetime + 12 mcp = 2237 tests). mkdocs build
--strict clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: Sander Toonen

docs/datetime-integration.md

@@ -54,6 +54,22 @@ Functions that **produce** a date return a Luxon `DateTime` so chains stay effic
 
 The full normaliser lives at [`packages/expreszo-datetime/src/normalize.ts`](https://github.com/Pro-Fa/expreszo-typescript/blob/main/packages/expreszo-datetime/src/normalize.ts) and is exported as `toDateTime` / `toDateTimeOrUndefined` for callers who want to do their own conversions outside an expression.
 
+## Operators on DateTime values
+
+As of `@pro-fa/expreszo` 0.6.1, the core comparison operators are `valueOf`-aware: any two non-null objects whose `.valueOf()` returns a primitive distinct from themselves compare by that primitive. So with `dateTimePlugin` registered (or just a JS `Date` in your `variables` map):
+
+```
+parseISO('2026-01-01') == parseISO('2026-01-01')   // true
+parseISO('2026-01-01') <  parseISO('2026-02-01')   // true
+parseISO('2026-01-01') >= parseISO('2026-01-01')   // true
+```
+
+No operator overrides, no separate plugin — the relational operators (`<`, `>`, `<=`, `>=`) always worked because JS's `ToPrimitive` already calls `valueOf`; `==` and `!=` now follow suit.
+
+Plain objects and arrays still use reference equality, so the change is targeted at value-bearing objects (`Date`, Luxon `DateTime`, boxed primitives) only.
+
+Arithmetic operators (`+`, `-`) are intentionally **not** DateTime-aware — `addDuration`, `subtractDuration`, and `diff` are explicit about units and avoid the "what does `date + 7` mean" footgun.
+
 ## Wiring the plugin into the language service
 
 `createLanguageService` accepts the same plugins via a `plugins` option, so completions, hover, and diagnostics see the datetime functions too:

packages/expreszo-datetime/CHANGELOG.md

@@ -4,6 +4,14 @@ All notable changes to `@pro-fa/expreszo-datetime` are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.2.1
+
+### Improved
+
+`==` and `!=` now compare two `DateTime` values by instant. This isn't a change in this package — it's a side-effect of `@pro-fa/expreszo` 0.6.1 making the core operators `valueOf`-aware. With `dateTimePlugin` registered, **all six comparison operators** (`<`, `>`, `<=`, `>=`, `==`, `!=`) work as expected on DateTimes (and on JS `Date` values from your variables map). No additional wiring needed.
+
+The peer-dependency range now requires `@pro-fa/expreszo` ≥ 0.6.1.
+
 ## 0.2.0
 
 ### Added

packages/expreszo-datetime/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pro-fa/expreszo-datetime",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Optional Luxon-backed date/time functions for the @pro-fa/expreszo expression evaluator.",
   "license": "MIT",
   "type": "module",
@@ -40,7 +40,7 @@
     "plugin"
   ],
   "peerDependencies": {
-    "@pro-fa/expreszo": "^0.6.0"
+    "@pro-fa/expreszo": "^0.6.1"
   },
   "dependencies": {
     "luxon": "^3.5.0"

packages/expreszo-datetime/test/plugin.test.ts

@@ -132,6 +132,35 @@ describe('inspection', () => {
   });
 });
 
+// Core's `equal`/`notEqual` are valueOf-aware as of @pro-fa/expreszo 0.6.1,
+// so two Luxon DateTime instances at the same instant compare equal via the
+// existing `==` and `!=` operators. The plugin doesn't need to override
+// anything — it just needs to be the source of the DateTime values.
+describe('== and != on DateTime values via core operators', () => {
+  it('two DateTimes at the same instant are ==', () => {
+    expect(parser().evaluate("parseISO('2026-01-01') == parseISO('2026-01-01')")).toBe(true);
+    expect(parser().evaluate("parseISO('2026-01-01') != parseISO('2026-01-01')")).toBe(false);
+  });
+
+  it('two DateTimes at different instants are !=', () => {
+    expect(parser().evaluate("parseISO('2026-01-01') == parseISO('2026-01-02')")).toBe(false);
+    expect(parser().evaluate("parseISO('2026-01-01') != parseISO('2026-01-02')")).toBe(true);
+  });
+
+  it('a Luxon DateTime equals an equivalent JS Date', () => {
+    const ms = Date.UTC(2026, 0, 1);
+    const jsDate = new Date(ms);
+    expect(parser().evaluate("parseISO('2026-01-01T00:00:00Z') == d", { d: jsDate as unknown as never })).toBe(true);
+  });
+
+  it('relational operators continue to work as before', () => {
+    expect(parser().evaluate("parseISO('2026-01-01') <  parseISO('2026-02-01')")).toBe(true);
+    expect(parser().evaluate("parseISO('2026-02-01') >  parseISO('2026-01-01')")).toBe(true);
+    expect(parser().evaluate("parseISO('2026-01-01') <= parseISO('2026-01-01')")).toBe(true);
+    expect(parser().evaluate("parseISO('2026-01-01') >= parseISO('2026-01-01')")).toBe(true);
+  });
+});
+
 describe('end-to-end pipeline', () => {
   it('chains construction, arithmetic, and formatting', () => {
     expect(

packages/expreszo/BREAKING_CHANGES.md

@@ -2,6 +2,26 @@
 
 This document lists breaking changes in the library to help users migrate between versions.
 
+## 0.6.1 — `==` / `!=` are now valueOf-aware
+
+`equal` and `notEqual` (the `==` and `!=` operators) now compare two non-null objects by their `valueOf()` result whenever both operands return a primitive distinct from themselves. This mirrors what `<` / `>` / `<=` / `>=` already did via JavaScript's `ToPrimitive` algorithm, and lets values like Luxon `DateTime` and JS `Date` compare by instant without the core knowing about either type.
+
+**What changed:**
+
+- Two `Date` instances at the same millisecond are now `==`. They were `!=` before (reference equality on objects).
+- Two Luxon `DateTime` values at the same instant are now `==` (when the `@pro-fa/expreszo-datetime` plugin is registered).
+- Boxed primitives — `new Number(5)`, `new String('x')` — also start comparing by their primitive form.
+
+**What did not change:**
+
+- Plain objects (`{a:1} == {a:1}`) still return `false` — they have no overridden `valueOf()`, so the new branch falls through to reference equality.
+- Arrays (`[1,2] == [1,2]`) still return `false`, same reason.
+- All primitive comparisons (`3 == 3`, `'a' == 'a'`) keep their existing semantics.
+- `null` continues to equal only `null`; `undefined` continues to equal only `undefined`.
+- Object compared to a primitive is still `false` — no implicit cross-type coercion.
+
+This is technically a behaviour change for code that was relying on `Date == Date` returning `false`. Audit any expression that explicitly compared two date-like objects expecting reference inequality.
+
 ## 0.6.0 — companion packages and `parser.use(plugin)`
 
 ### `./mcp-server` subpath export removed

packages/expreszo/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pro-fa/expreszo",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Mathematical expression evaluator",
   "keywords": [
     "expression",

packages/expreszo/src/operators/binary/comparison.ts

@@ -4,11 +4,27 @@
  */
 
 export function equal(a: any, b: any): boolean {
-  return a === b;
+  if (a === b) return true;
+  // Two non-null objects with a meaningful `valueOf()` (i.e. one that
+  // returns something *other than* the object itself) are compared by
+  // their primitive form. This mirrors what the relational operators
+  // (`<`, `>`, `<=`, `>=`) already do via JS's `ToPrimitive`, and lets
+  // values like Luxon `DateTime` and JS `Date` compare by instant
+  // without the core ever knowing about either type.
+  // Plain objects and arrays return themselves from `valueOf()`, so
+  // they still fall through to reference-equality semantics.
+  if (a !== null && b !== null && typeof a === 'object' && typeof b === 'object') {
+    const av = a.valueOf();
+    const bv = b.valueOf();
+    if (av !== a && bv !== b) {
+      return av === bv;
+    }
+  }
+  return false;
 }
 
 export function notEqual(a: any, b: any): boolean {
-  return a !== b;
+  return !equal(a, b);
 }
 
 export function greaterThan(a: any, b: any): boolean | undefined {

packages/expreszo/test/operators/operators-comparison.ts

@@ -138,4 +138,73 @@ describe('Comparison Operators TypeScript Test', () => {
       expect(parser.evaluate('3 <= 3')).toBe(true);
     });
   });
+
+  // Equality is valueOf-aware: any two non-null objects whose `.valueOf()`
+  // returns a primitive distinct from themselves compare by that primitive.
+  // This makes `==` and `!=` line up with how `<`/`>`/`<=`/`>=` already
+  // behave (via ToPrimitive), and lets values like JS `Date` and Luxon
+  // `DateTime` work without core knowing about either type.
+  describe('== / != on objects with a meaningful valueOf', () => {
+    const ms = Date.UTC(2026, 0, 1);
+
+    it('two JS Date instances at the same instant are ==', () => {
+      const d1 = new Date(ms);
+      const d2 = new Date(ms);
+      expect(parser.evaluate('a == b', { a: d1 as never, b: d2 as never })).toBe(true);
+      expect(parser.evaluate('a != b', { a: d1 as never, b: d2 as never })).toBe(false);
+    });
+
+    it('two JS Date instances at different instants are !=', () => {
+      const d1 = new Date(ms);
+      const d2 = new Date(ms + 1);
+      expect(parser.evaluate('a == b', { a: d1 as never, b: d2 as never })).toBe(false);
+      expect(parser.evaluate('a != b', { a: d1 as never, b: d2 as never })).toBe(true);
+    });
+
+    it('two custom objects with the same numeric valueOf are ==', () => {
+      const a = { valueOf: () => 42 };
+      const b = { valueOf: () => 42 };
+      expect(parser.evaluate('a == b', { a: a as never, b: b as never })).toBe(true);
+    });
+
+    it('a JS Date and a custom valueOf object compare by their primitive', () => {
+      const a = new Date(ms);
+      const b = { valueOf: () => ms };
+      expect(parser.evaluate('a == b', { a: a as never, b: b as never })).toBe(true);
+    });
+
+    it('plain objects without an overridden valueOf still use reference equality', () => {
+      const a = { x: 1 };
+      const b = { x: 1 };
+      expect(parser.evaluate('a == b', { a: a as never, b: b as never })).toBe(false);
+      expect(parser.evaluate('a != b', { a: a as never, b: b as never })).toBe(true);
+      // Same reference is still ==
+      expect(parser.evaluate('a == a', { a: a as never })).toBe(true);
+    });
+
+    it('arrays still use reference equality', () => {
+      const a = [1, 2, 3];
+      const b = [1, 2, 3];
+      expect(parser.evaluate('a == b', { a: a as never, b: b as never })).toBe(false);
+    });
+
+    it('two invalid Dates (NaN-valued) are not ==', () => {
+      const a = new Date(NaN);
+      const b = new Date(NaN);
+      expect(parser.evaluate('a == b', { a: a as never, b: b as never })).toBe(false);
+      expect(parser.evaluate('a != b', { a: a as never, b: b as never })).toBe(true);
+    });
+
+    it('object compared to a primitive is not ==', () => {
+      const a = new Date(ms);
+      expect(parser.evaluate('a == ms', { a: a as never, ms })).toBe(false);
+      expect(parser.evaluate('a != ms', { a: a as never, ms })).toBe(true);
+    });
+
+    it('null still equals only null', () => {
+      const a = new Date(ms);
+      expect(parser.evaluate('a == n', { a: a as never, n: null })).toBe(false);
+      expect(parser.evaluate('n == n', { n: null })).toBe(true);
+    });
+  });
 });