Add constructNow

Added the `constructNow` function that creates the current date using the passed reference date's constructor.

package.json

@@ -248,6 +248,16 @@
         "default": "./constructFrom.mjs"
       }
     },
+    "./constructNow": {
+      "require": {
+        "types": "./constructNow.d.ts",
+        "default": "./constructNow.js"
+      },
+      "import": {
+        "types": "./constructNow.d.mts",
+        "default": "./constructNow.mjs"
+      }
+    },
     "./daysToWeeks": {
       "require": {
         "types": "./daysToWeeks.d.ts",

src/constructFrom/index.ts

@@ -10,6 +10,8 @@ import type { GenericDateConstructor } from "../types.js";
  * date and the given value. It helps to build generic functions that accept
  * date extensions.
  *
+ * It defaults to `Date` if the passed reference date is a number or a string.
+ *
  * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
  *
  * @param date - The reference date to take constructor from

src/constructNow/index.ts

@@ -0,0 +1,37 @@
+import { constructFrom } from "../index.js";
+
+/**
+ * @name constructNow
+ * @category Generic Helpers
+ * @summary Constructs a new current date using the passed value constructor.
+ * @pure false
+ *
+ * @description
+ * The function constructs a new current date using the constructor from
+ * the reference date. It helps to build generic functions that accept date
+ * extensions and use the current date.
+ *
+ * It defaults to `Date` if the passed reference date is a number or a string.
+ *
+ * @typeParam DateType - The `Date` type, the function operates on. Gets inferred from passed arguments. Allows to use extensions like [`UTCDate`](https://github.com/date-fns/utc).
+ *
+ * @param date - The reference date to take constructor from
+ *
+ * @returns Current date initialized using the given date constructor
+ *
+ * @example
+ * import { constructNow, isSameDay } from 'date-fns'
+ *
+ * function isToday<DateType extends Date>(
+ *   date: DateType | number | string,
+ * ): boolean {
+ *   // If we were to use `new Date()` directly, the function would  behave
+ *   // differently in different timezones and return false for the same date.
+ *   return isSameDay(date, constructNow(date));
+ * }
+ */
+export function constructNow<DateType extends Date>(
+  date: DateType | number | string,
+): DateType {
+  return constructFrom(date, Date.now());
+}

src/constructNow/test.ts

@@ -0,0 +1,38 @@
+import assert from "assert";
+import { describe, it } from "vitest";
+import { constructNow } from ".";
+
+describe("constructNow", () => {
+  it("creates a new Date instance using the constructor from the reference date", () => {
+    const result = constructNow(new Date("2023-10-25T12:00:00"));
+
+    assert.ok(result instanceof Date);
+    assert(+result - Date.now() < 10); // Give 10 ms of slack
+    assert.strictEqual(result.constructor, Date);
+  });
+
+  it("creates a new Date instance using a number as the reference date", () => {
+    const result = constructNow(1635158400000);
+
+    assert.ok(result instanceof Date);
+    assert(+result - Date.now() < 10); // Give 10 ms of slack
+    assert.strictEqual(result.constructor, Date);
+  });
+
+  it("creates a new Date instance using a string as the reference date", () => {
+    const result = constructNow("2023-10-25T12:00:00");
+
+    assert.ok(result instanceof Date);
+    assert(+result - Date.now() < 10); // Give 10 ms of slack
+    assert.strictEqual(result.constructor, Date);
+  });
+
+  it("creates a new custom Date instance using the constructor from the reference date", () => {
+    class CustomDate extends Date {}
+    const result = constructNow(new CustomDate("2023-10-26T12:00:00"));
+
+    assert.ok(result instanceof CustomDate);
+    assert(+result - Date.now() < 10); // Give 10 ms of slack
+    assert.strictEqual(result.constructor, CustomDate);
+  });
+});

src/index.ts

@@ -19,6 +19,7 @@ export * from "./closestTo/index.js";
 export * from "./compareAsc/index.js";
 export * from "./compareDesc/index.js";
 export * from "./constructFrom/index.js";
+export * from "./constructNow/index.js";
 export * from "./daysToWeeks/index.js";
 export * from "./differenceInBusinessDays/index.js";
 export * from "./differenceInCalendarDays/index.js";

typedoc.json

@@ -21,6 +21,7 @@
     "./src/compareAsc/index.ts",
     "./src/compareDesc/index.ts",
     "./src/constructFrom/index.ts",
+    "./src/constructNow/index.ts",
     "./src/daysToWeeks/index.ts",
     "./src/differenceInBusinessDays/index.ts",
     "./src/differenceInCalendarDays/index.ts",