Add toDateFromExactTime function

Author: fabon-f

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - `fromJulianDate`, `fromModifiedJulianDate`, `modifiedJulianDate` functions
+- `toDateFromExactTime` function
 
 ### Changed
 

src/datetime/index.ts

@@ -38,4 +38,5 @@ export { startOfMonth } from "./startOfMonth.js";
 export { startOfSecond } from "./startOfSecond.js";
 export { startOfYear } from "./startOfYear.js";
 export { toDateFromClockTime } from "./toDateFromClockTime.js";
+export { toDateFromExactTime } from "./toDateFromExactTime.js";
 export { toTemporalFromClockTime } from "./toTemporalFromClockTime.js";

src/datetime/toDateFromExactTime.test.ts

@@ -0,0 +1,34 @@
+import { UTCDate } from "@date-fns/utc";
+import { Temporal } from "@js-temporal/polyfill";
+import { expect, test } from "vitest";
+
+import { toDateFromExactTime } from "./toDateFromExactTime.js";
+
+test("Instant", () => {
+	expect(
+		toDateFromExactTime(Temporal.Instant.from("2024-01-01T01:23:45.678Z")),
+	).toEqual(new Date("2024-01-01T01:23:45.678Z"));
+});
+
+test("units smaller than millisecond", () => {
+	expect(
+		toDateFromExactTime(Temporal.Instant.from("2024-01-01T00:00:00.0009Z")),
+	).toEqual(new Date("2024-01-01T00:00:00Z"));
+});
+
+test("ZonedDateTime", () => {
+	expect(
+		toDateFromExactTime(
+			Temporal.ZonedDateTime.from("2024-01-01T00:00:00+09:00[Asia/Tokyo]"),
+		),
+	).toEqual(new Date("2023-12-31T15:00:00Z"));
+});
+
+test("DateConstructor option", () => {
+	const result = toDateFromExactTime(
+		Temporal.ZonedDateTime.from("2024-01-01T00:00:00+09:00[Asia/Tokyo]"),
+		UTCDate,
+	);
+	expect(result).toEqual(new UTCDate("2023-12-31T15:00:00Z"));
+	expect(result).toBeInstanceOf(UTCDate);
+});

src/datetime/toDateFromExactTime.ts

@@ -0,0 +1,16 @@
+import type { GenericDateConstructor, Temporal } from "../types.js";
+
+/**
+ * Returns `Date` which represents exact time of the given temporal object.
+ *
+ * @param dateTime Temporal object which includes exact time info
+ * @param DateConstructor `Date` or extended class for return type, default is `Date`
+ * @returns `Date` (or its subclass) object which represents the exact time of the given Temporal object
+ */
+export function toDateFromExactTime<DateType extends Date = Date>(
+	dateTime: Temporal.ZonedDateTime | Temporal.Instant,
+	DateConstructor?: GenericDateConstructor<DateType>,
+): DateType {
+	const DateConstructorFunction = DateConstructor ?? Date;
+	return new DateConstructorFunction(dateTime.epochMilliseconds) as DateType;
+}