feature(date): Implement $dateDiff operator

src/operators/expression/date/dateDiff.ts

@@ -0,0 +1,54 @@
+// Date Expression Operators: https://docs.mongodb.com/manual/reference/operator/aggregation/#date-expression-operators
+
+import { computeValue, Options } from "../../../core";
+import { AnyVal, RawObject } from "../../../types";
+import { computeDate, Duration, DURATION_IN_MILLIS } from "./_internal";
+
+/**
+ * Returns the difference between two dates.
+ * @param obj
+ * @param expr
+ * @param options Options
+ */
+export function $dateDiff(
+  obj: RawObject,
+  expr: RawObject,
+  options?: Options
+): AnyVal {
+  const args = computeValue(obj, expr, null, options) as {
+    startDate: AnyVal;
+    endDate: AnyVal;
+    unit: Duration;
+    timezone?: string;
+    startOfWeek?: string;
+  };
+
+  const d1 = computeDate(obj, expr.startDate, options);
+  const d2 = computeDate(obj, expr.endDate, options);
+
+  let diff;
+  switch (args.unit) {
+    case "year":
+    case "quarter":
+    case "month":
+      diff = diffYQM(d1, d2, args.unit);
+      break;
+    default:
+      diff = (d2.getTime() - d1.getTime()) / DURATION_IN_MILLIS[args.unit];
+  }
+
+  return diff;
+}
+
+const unitMonths = {
+  year: 12,
+  quarter: 3,
+  month: 1,
+};
+
+function diffYQM(d1: Date, d2: Date, unit: string): number {
+  let months = (d2.getUTCFullYear() - d1.getUTCFullYear()) * 12;
+  months -= d1.getUTCMonth();
+  months += d2.getUTCMonth();
+  return Math.trunc(months / unitMonths[unit]);
+}

src/operators/expression/date/index.ts

@@ -1,4 +1,5 @@
 export * from "./dateAdd";
+export * from "./dateDiff";
 export * from "./dateFromParts";
 export * from "./dateFromString";
 export * from "./dateSubtract";

test/operators/expression/date.test.ts

@@ -2,12 +2,6 @@ import { aggregate } from "../../../src";
 import { AnyVal, RawArray, RawObject } from "../../../src/types";
 import * as support from "../../support";
 
-const apply3Units = {
-  startDate: "$$this",
-  amount: 3,
-  timezone: "+00",
-};
-
 const testDate = new Date("2021-01-28T13:05:00Z");
 // dates less 3 units
 const yearDate = new Date("2018-01-28T13:05:00Z");
@@ -20,6 +14,17 @@ const minuteDate = new Date("2021-01-28T13:02:00Z");
 const secondDate = new Date("2021-01-28T13:04:57Z");
 const millisecondDate = new Date("2021-01-28T13:04:59.997Z");
 
+const apply3Units = {
+  startDate: "$$this",
+  amount: 3,
+  timezone: "+00",
+};
+const dateDiff3Units = {
+  startDate: "$$this",
+  endDate: testDate,
+  timezone: "+00",
+};
+
 support.runTest("operators/expression/date", {
   $week: [
     [new Date("2016-01-01T00:00:00Z"), 0],
@@ -107,6 +112,17 @@ support.runTest("operators/expression/date", {
       { obj: testDate },
     ],
   ],
+  $dateDiff: [
+    [{ ...dateDiff3Units, unit: "year" }, 3, { obj: yearDate }],
+    [{ ...dateDiff3Units, unit: "quarter" }, 3, { obj: quarterDate }],
+    [{ ...dateDiff3Units, unit: "month" }, 3, { obj: monthDate }],
+    [{ ...dateDiff3Units, unit: "week" }, 3, { obj: weekDate }],
+    [{ ...dateDiff3Units, unit: "day" }, 3, { obj: dayDate }],
+    [{ ...dateDiff3Units, unit: "hour" }, 3, { obj: hourDate }],
+    [{ ...dateDiff3Units, unit: "minute" }, 3, { obj: minuteDate }],
+    [{ ...dateDiff3Units, unit: "second" }, 3, { obj: secondDate }],
+    [{ ...dateDiff3Units, unit: "millisecond" }, 3, { obj: millisecondDate }],
+  ],
   $dateFromString: [
     [
       { dateString: "2017-02-08T12:10:40.787" },