feat: Add native Date object support to fast-json-patch

This commit adds proper handling for JavaScript Date objects in JSON Patch operations.

## Changes

### 1. Enhanced `_deepClone` function (src/helpers.ts)
- Added special handling for Date objects to preserve them as Date instances
- Changed from JSON.stringify/parse approach to recursive cloning
- Date objects are now cloned using `new Date(obj.getTime())` to maintain type and value
- Arrays and objects are recursively cloned to handle nested Date objects

### 2. Enhanced `_generate` function (src/duplex.ts)
- Added Date-specific comparison logic
- Date objects are now compared by value (using `getTime()`) instead of by reference
- When two Date objects have different timestamps, a replace patch is generated
- Preserves Date objects in the generated patches (not converted to ISO strings)

### 3. Added comprehensive test suite (test/spec/dateSpec.mjs)
- Tests for cloning Date objects
- Tests for comparing objects with Date properties
- Tests for nested Date objects in arrays and objects
- Real-world scenario test simulating calendar event workflows

## Benefits

- **Type Preservation**: Date objects remain as Date instances throughout patch operations
- **Correct Comparisons**: Dates are compared by value, not reference
- **Backward Compatible**: All existing tests pass (215 specs, 0 failures)
- **Real-world Use Case**: Solves issues when working with API responses containing dates

## Use Case

This fix addresses the common scenario where workflow contexts contain Date objects
(e.g., calendar events, timestamps, scheduled tasks) and need to generate accurate
diffs without converting dates to strings.

Example:
```javascript
const oldContext = { events: [] };
const newContext = {
  events: [{
    startTime: new Date('2025-11-15T10:00:00Z'),
    endTime: new Date('2025-11-15T11:00:00Z')
  }]
};

const patches = compare(oldContext, newContext);
// Patches now contain actual Date objects, not ISO strings
```

## Testing

All tests pass:
- New Date-specific tests: 11 specs, 0 failures
- Existing core tests: 215 specs, 0 failures

Co-authored-by: Claude <noreply@anthropic.com>

Author: nyamathshaik

commonjs/duplex.js

@@ -132,7 +132,19 @@ function _generate(mirror, obj, patches, path, invertible) {
         if (helpers_js_1.hasOwnProperty(obj, key) && !(obj[key] === undefined && oldVal !== undefined && Array.isArray(obj) === false)) {
             var newVal = obj[key];
             if (typeof oldVal == "object" && oldVal != null && typeof newVal == "object" && newVal != null && Array.isArray(oldVal) === Array.isArray(newVal)) {
-                _generate(oldVal, newVal, patches, path + "/" + helpers_js_1.escapePathComponent(key), invertible);
+                // Special handling for Date objects: compare by value, not reference
+                if (oldVal instanceof Date && newVal instanceof Date) {
+                    if (oldVal.getTime() !== newVal.getTime()) {
+                        changed = true;
+                        if (invertible) {
+                            patches.push({ op: "test", path: path + "/" + helpers_js_1.escapePathComponent(key), value: helpers_js_1._deepClone(oldVal) });
+                        }
+                        patches.push({ op: "replace", path: path + "/" + helpers_js_1.escapePathComponent(key), value: helpers_js_1._deepClone(newVal) });
+                    }
+                }
+                else {
+                    _generate(oldVal, newVal, patches, path + "/" + helpers_js_1.escapePathComponent(key), invertible);
+                }
             }
             else {
                 if (oldVal !== newVal) {

commonjs/helpers.js

@@ -52,7 +52,25 @@ exports._objectKeys = _objectKeys;
 function _deepClone(obj) {
     switch (typeof obj) {
         case "object":
-            return JSON.parse(JSON.stringify(obj)); //Faster than ES5 clone - http://jsperf.com/deep-cloning-of-objects/5
+            if (obj === null) {
+                return null;
+            }
+            // Handle Date objects specially to preserve them as Date instances
+            if (obj instanceof Date) {
+                return new Date(obj.getTime());
+            }
+            // Handle Arrays
+            if (Array.isArray(obj)) {
+                return obj.map(function (item) { return _deepClone(item); });
+            }
+            // Handle plain objects - recursively clone each property
+            var cloned = {};
+            for (var key in obj) {
+                if (hasOwnProperty(obj, key)) {
+                    cloned[key] = _deepClone(obj[key]);
+                }
+            }
+            return cloned;
         case "undefined":
             return null; //this is how JSON.stringify behaves for array items
         default:

module/duplex.mjs

@@ -128,7 +128,19 @@ function _generate(mirror, obj, patches, path, invertible) {
         if (hasOwnProperty(obj, key) && !(obj[key] === undefined && oldVal !== undefined && Array.isArray(obj) === false)) {
             var newVal = obj[key];
             if (typeof oldVal == "object" && oldVal != null && typeof newVal == "object" && newVal != null && Array.isArray(oldVal) === Array.isArray(newVal)) {
-                _generate(oldVal, newVal, patches, path + "/" + escapePathComponent(key), invertible);
+                // Special handling for Date objects: compare by value, not reference
+                if (oldVal instanceof Date && newVal instanceof Date) {
+                    if (oldVal.getTime() !== newVal.getTime()) {
+                        changed = true;
+                        if (invertible) {
+                            patches.push({ op: "test", path: path + "/" + escapePathComponent(key), value: _deepClone(oldVal) });
+                        }
+                        patches.push({ op: "replace", path: path + "/" + escapePathComponent(key), value: _deepClone(newVal) });
+                    }
+                }
+                else {
+                    _generate(oldVal, newVal, patches, path + "/" + escapePathComponent(key), invertible);
+                }
             }
             else {
                 if (oldVal !== newVal) {

module/helpers.mjs

@@ -49,7 +49,25 @@ export function _objectKeys(obj) {
 export function _deepClone(obj) {
     switch (typeof obj) {
         case "object":
-            return JSON.parse(JSON.stringify(obj)); //Faster than ES5 clone - http://jsperf.com/deep-cloning-of-objects/5
+            if (obj === null) {
+                return null;
+            }
+            // Handle Date objects specially to preserve them as Date instances
+            if (obj instanceof Date) {
+                return new Date(obj.getTime());
+            }
+            // Handle Arrays
+            if (Array.isArray(obj)) {
+                return obj.map(function (item) { return _deepClone(item); });
+            }
+            // Handle plain objects - recursively clone each property
+            var cloned = {};
+            for (var key in obj) {
+                if (hasOwnProperty(obj, key)) {
+                    cloned[key] = _deepClone(obj[key]);
+                }
+            }
+            return cloned;
         case "undefined":
             return null; //this is how JSON.stringify behaves for array items
         default: