Add startOfWeek and endOfWeek function

Author: fabon-f

src/datetime/endOfWeek.test.ts

@@ -0,0 +1,69 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { expect, test } from "vitest";
+
+import { endOfWeek } from "./endOfWeek.js";
+
+test("PlainDateTime", () => {
+	expect(
+		endOfWeek(Temporal.PlainDateTime.from("2024-01-01T12:34:56.789123456"), {
+			firstDayOfWeek: 1,
+		}),
+	).toEqual(Temporal.PlainDateTime.from("2024-01-07T23:59:59.999999999"));
+	expect(
+		endOfWeek(Temporal.PlainDateTime.from("2024-01-01T12:34:56.789123456"), {
+			firstDayOfWeek: 2,
+		}),
+	).toEqual(Temporal.PlainDateTime.from("2024-01-01T23:59:59.999999999"));
+	expect(
+		endOfWeek(Temporal.PlainDateTime.from("2024-01-02T12:34:56.789123456"), {
+			firstDayOfWeek: 2,
+		}),
+	).toEqual(Temporal.PlainDateTime.from("2024-01-08T23:59:59.999999999"));
+	expect(
+		endOfWeek(Temporal.PlainDateTime.from("2024-01-01T12:34:56.789123456"), {
+			firstDayOfWeek: 7,
+		}),
+	).toEqual(Temporal.PlainDateTime.from("2024-01-06T23:59:59.999999999"));
+	expect(
+		endOfWeek(Temporal.PlainDateTime.from("2024-01-07T12:34:56.789123456"), {
+			firstDayOfWeek: 7,
+		}),
+	).toEqual(Temporal.PlainDateTime.from("2024-01-13T23:59:59.999999999"));
+});
+
+test("PlainDate", () => {
+	expect(
+		endOfWeek(Temporal.PlainDate.from("2024-01-01"), {
+			firstDayOfWeek: 1,
+		}),
+	).toEqual(Temporal.PlainDate.from("2024-01-07"));
+	expect(
+		endOfWeek(Temporal.PlainDate.from("2024-01-01"), {
+			firstDayOfWeek: 2,
+		}),
+	).toEqual(Temporal.PlainDate.from("2024-01-01"));
+	expect(
+		endOfWeek(Temporal.PlainDate.from("2024-01-02"), {
+			firstDayOfWeek: 2,
+		}),
+	).toEqual(Temporal.PlainDate.from("2024-01-08"));
+	expect(
+		endOfWeek(Temporal.PlainDate.from("2024-01-01"), {
+			firstDayOfWeek: 7,
+		}),
+	).toEqual(Temporal.PlainDate.from("2024-01-06"));
+	expect(
+		endOfWeek(Temporal.PlainDate.from("2024-01-07"), {
+			firstDayOfWeek: 7,
+		}),
+	).toEqual(Temporal.PlainDate.from("2024-01-13"));
+});
+
+test("invalid day of week", () => {
+	expect(() => {
+		endOfWeek(Temporal.PlainDate.from("2024-01-01"), { firstDayOfWeek: 8 });
+	}).toThrowError();
+	expect(() => {
+		endOfWeek(Temporal.PlainDate.from("2024-01-01"), { firstDayOfWeek: -1 });
+	}).toThrowError();
+});

src/datetime/endOfWeek.ts

@@ -0,0 +1,49 @@
+import { isPlainDate } from "../type-utils.js";
+import type { Temporal } from "../types.js";
+
+export interface EndOfWeekOptions {
+	/**
+	 * First day of the week.
+	 * For example, in ISO calendar Monday is `1`, Sunday is `7`.
+	 */
+	firstDayOfWeek: number;
+}
+
+/**
+ * Returns the end of a week for the given datetime.
+ * 'end of a week' is ambiguous and locale-dependent,
+ * so `firstDayOfWeek` option is required.
+ * This function supports a calendar with a fixed `daysInWeek`,
+ * even if the week contains more or less than 7 days.
+ * But it doesn't support a calendar which lacks a fixed number of days.
+ *
+ * @param dt datetime object which includes date info
+ * @returns Temporal object which represents the end of a week
+ */
+export function endOfWeek<
+	DateTime extends Temporal.PlainDate | Temporal.PlainDateTime,
+>(dt: DateTime, options: EndOfWeekOptions): DateTime {
+	const firstDayOfWeek = options.firstDayOfWeek;
+	if (
+		!Number.isInteger(firstDayOfWeek) ||
+		firstDayOfWeek < 1 ||
+		firstDayOfWeek > dt.daysInWeek
+	) {
+		throw new Error(`${firstDayOfWeek} isn't a valid day of week`);
+	}
+	const endOfWeek = dt.add({
+		days: (firstDayOfWeek + dt.daysInWeek - dt.dayOfWeek - 1) % dt.daysInWeek,
+	});
+
+	if (isPlainDate(dt)) {
+		return endOfWeek as DateTime;
+	}
+	return endOfWeek.with({
+		hour: 23,
+		minute: 59,
+		second: 59,
+		millisecond: 999,
+		microsecond: 999,
+		nanosecond: 999,
+	}) as DateTime;
+}

src/datetime/index.ts

@@ -14,6 +14,7 @@ export { endOfHour } from "./endOfHour.js";
 export { endOfMinute } from "./endOfMinute.js";
 export { endOfMonth } from "./endOfMonth.js";
 export { endOfSecond } from "./endOfSecond.js";
+export { endOfWeek, type EndOfWeekOptions } from "./endOfWeek.js";
 export { endOfYear } from "./endOfYear.js";
 export { epochSeconds } from "./epochSeconds.js";
 export { formatRfc7231 } from "./formatRfc7231.js";
@@ -36,6 +37,7 @@ export { startOfHour } from "./startOfHour.js";
 export { startOfMinute } from "./startOfMinute.js";
 export { startOfMonth } from "./startOfMonth.js";
 export { startOfSecond } from "./startOfSecond.js";
+export { startOfWeek, type StartOfWeekOptions } from "./startOfWeek.js";
 export { startOfYear } from "./startOfYear.js";
 export { toDateFromClockTime } from "./toDateFromClockTime.js";
 export { toDateFromExactTime } from "./toDateFromExactTime.js";

src/datetime/startOfWeek.test.ts

@@ -0,0 +1,45 @@
+import { Temporal } from "@js-temporal/polyfill";
+import { expect, test } from "vitest";
+
+import { startOfWeek } from "./startOfWeek.js";
+
+test("PlainDateTime", () => {
+	expect(
+		startOfWeek(Temporal.PlainDateTime.from("2024-01-01T12:34:56.789123456"), {
+			firstDayOfWeek: 1,
+		}),
+	).toEqual(Temporal.PlainDateTime.from("2024-01-01T00:00:00"));
+	expect(
+		startOfWeek(Temporal.PlainDateTime.from("2024-01-01T12:34:56.789123456"), {
+			firstDayOfWeek: 7,
+		}),
+	).toEqual(Temporal.PlainDateTime.from("2023-12-31T00:00:00"));
+	expect(
+		startOfWeek(Temporal.PlainDateTime.from("2024-01-07T12:34:56.789123456"), {
+			firstDayOfWeek: 1,
+		}),
+	).toEqual(Temporal.PlainDateTime.from("2024-01-01T00:00:00"));
+});
+
+test("PlainDate", () => {
+	expect(
+		startOfWeek(Temporal.PlainDate.from("2024-01-01"), { firstDayOfWeek: 1 }),
+	).toEqual(Temporal.PlainDate.from("2024-01-01"));
+	expect(
+		startOfWeek(Temporal.PlainDate.from("2024-01-01"), { firstDayOfWeek: 7 }),
+	).toEqual(Temporal.PlainDate.from("2023-12-31"));
+	expect(
+		startOfWeek(Temporal.PlainDate.from("2024-01-07"), {
+			firstDayOfWeek: 1,
+		}),
+	).toEqual(Temporal.PlainDate.from("2024-01-01"));
+});
+
+test("invalid day of week", () => {
+	expect(() => {
+		startOfWeek(Temporal.PlainDate.from("2024-01-01"), { firstDayOfWeek: 8 });
+	}).toThrowError();
+	expect(() => {
+		startOfWeek(Temporal.PlainDate.from("2024-01-01"), { firstDayOfWeek: -1 });
+	}).toThrowError();
+});

src/datetime/startOfWeek.ts

@@ -0,0 +1,49 @@
+import { isPlainDate } from "../type-utils.js";
+import type { Temporal } from "../types.js";
+
+export interface StartOfWeekOptions {
+	/**
+	 * First day of the week.
+	 * For example, in ISO calendar Monday is `1`, Sunday is `7`.
+	 */
+	firstDayOfWeek: number;
+}
+
+/**
+ * Returns the start of a week for the given datetime.
+ * 'start of a week' is ambiguous and locale-dependent,
+ * so `firstDayOfWeek` option is required.
+ * This function supports a calendar with a fixed `daysInWeek`,
+ * even if the week contains more or less than 7 days.
+ * But it doesn't support a calendar which lacks a fixed number of days.
+ *
+ * @param dt datetime object which includes date info
+ * @returns Temporal object which represents the start of a week
+ */
+export function startOfWeek<
+	DateTime extends Temporal.PlainDate | Temporal.PlainDateTime,
+>(dt: DateTime, options: StartOfWeekOptions): DateTime {
+	const firstDayOfWeek = options.firstDayOfWeek;
+	if (
+		!Number.isInteger(firstDayOfWeek) ||
+		firstDayOfWeek < 1 ||
+		firstDayOfWeek > dt.daysInWeek
+	) {
+		throw new Error(`${firstDayOfWeek} isn't a valid day of week`);
+	}
+	const startOfWeek = dt.subtract({
+		days: (dt.dayOfWeek - firstDayOfWeek + dt.daysInWeek) % dt.daysInWeek,
+	});
+
+	if (isPlainDate(dt)) {
+		return startOfWeek as DateTime;
+	}
+	return startOfWeek.with({
+		hour: 0,
+		minute: 0,
+		second: 0,
+		millisecond: 0,
+		microsecond: 0,
+		nanosecond: 0,
+	}) as DateTime;
+}