Make startOfWeek locale-aware by default

src/startOfWeek/index.ts

@@ -1,50 +1,59 @@
 import { toDate } from "../toDate/index.js";
-import type { LocalizedOptions, WeekOptions } from "../types.js";
+import type { LocalizedOptions, WeekOptions, Locale } from "../types.js";
 import { getDefaultOptions } from "../_lib/defaultOptions/index.js";
+import { enUS } from "../locale/index.js";
 
 /**
  * The {@link startOfWeek} function options.
  */
 export interface StartOfWeekOptions
   extends LocalizedOptions<"options">,
-    WeekOptions {}
+  WeekOptions { }
 
 /**
  * @name startOfWeek
  * @category Week Helpers
  * @summary Return the start of a week for the given date.
  *
- * @description
- * Return the start of a week for the given date.
- * The result will be in the local timezone.
+  * @description
+ * Return the start of a week for the given date, considering the locale information 
+ * provided in the options or default settings. The result will be in the local timezone.
  *
  * @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 original date
  * @param options - An object with options
+ *  * @property {Locale} [locale] - The locale object used to determine the week start day. 
+ * If not provided, the default locale or `enUS` is used.
+ * 
  *
  * @returns The start of a week
  *
- * @example
- * // The start of a week for 2 September 2014 11:55:00:
- * const result = startOfWeek(new Date(2014, 8, 2, 11, 55, 0))
- * //=> Sun Aug 31 2014 00:00:00
- *
- * @example
- * // If the week starts on Monday, the start of the week for 2 September 2014 11:55:00:
- * const result = startOfWeek(new Date(2014, 8, 2, 11, 55, 0), { weekStartsOn: 1 })
- * //=> Mon Sep 01 2014 00:00:00
- */
+ * @example
+ * // The start of the week for September 2nd, 2014, considering US English locale (Sunday start):
+ * const result = startOfWeek(new Date(2014, 8, 2))
+ * //=> Sun Aug 31 2014 00:00:00
+ *
+ * @example
+ * // The start of the week for September 2nd, 2014, considering Arabic (Egypt) locale (Saturday start):
+ * const result = startOfWeek(new Date(2014, 8, 2), { locale: arDZ })
+ * //=> Sat Aug 30 2014 00:00:00
+ */
 export function startOfWeek<DateType extends Date>(
   date: DateType | number | string,
   options?: StartOfWeekOptions,
 ): DateType {
   const defaultOptions = getDefaultOptions();
+  const locale: Locale = options?.locale as Locale || defaultOptions.locale as Locale || enUS
+
+
+  const localeWeekStartsOn = locale.options?.weekStartsOn;
+
+
   const weekStartsOn =
     options?.weekStartsOn ??
-    options?.locale?.options?.weekStartsOn ??
+    localeWeekStartsOn ??
     defaultOptions.weekStartsOn ??
-    defaultOptions.locale?.options?.weekStartsOn ??
     0;
 
   const _date = toDate(date);

src/startOfWeek/test.ts

@@ -1,5 +1,7 @@
 import { describe, expect, it } from "vitest";
 import { startOfWeek } from "./index.js";
+import { enUS, fr } from "../locale/index.js";
+
 
 describe("startOfWeek", () => {
   it("returns the date with the time set to 00:00:00 and the date set to the first day of a week", () => {
@@ -84,3 +86,13 @@ describe("startOfWeek", () => {
     expect(result instanceof Date && isNaN(result.getTime())).toBe(true);
   });
 });
+
+
+it("allows to specify which day is the first day of the week in different locales", () => {
+  const date = new Date(2014, 8 /* Sep */, 2, 11, 55, 0);
+  const result_enUS = startOfWeek(date, { locale: enUS }); // Using en-US locale
+  expect(result_enUS).toEqual(new Date(2014, 7 /* Aug */, 31));
+
+  const result_fr = startOfWeek(date, { locale: fr }); // Using fr locale
+  expect(result_fr).toEqual(new Date(2014, 8 /* Sep */, 1));
+});