Week

`week`

Returns the ISO week number (1-53) for the given timestamp and timezone.

reference/week/week.ts

import { week } from "datezone";

const timestamp = Date.UTC(2024, 6, 10, 12, 0, 0); // 2024-07-10T12:00:00.000Z
const weekNumber = week(timestamp, "America/New_York");
console.log(weekNumber); // 28

`weekBase`

Calculates the ISO week number (1-53) from a plain calendar date (year, month, day).

reference/week/weekBase.ts

import { weekBase } from "datezone";

const weekNumber = weekBase(2024, 7, 10);
console.log(weekNumber); // 28

`getISOWeekYear`

Returns the ISO week-numbering year for the supplied timestamp.

reference/week/getISOWeekYear.ts

import { getISOWeekYear } from "datezone";

const timestamp = 1720612800000; // 2024-07-10T12:00:00.000Z
const isoWeekYear = getISOWeekYear(timestamp, "America/New_York");
console.log(isoWeekYear); // 2024

`getISOWeekYearBase`

Calculates the ISO week-numbering year from a plain calendar date.

reference/week/getISOWeekYearBase.ts

import { getISOWeekYearBase } from "datezone";

const isoWeekYear = getISOWeekYearBase(2024, 7, 10);

console.log(isoWeekYear); // 2024

`startOfWeek`

Returns the timestamp for the start of the week (00:00:00.000) respecting the weekStartsOn option.

reference/week/startOfWeek.ts

import { startOfWeek, toISOString, WeekStartsOn } from "datezone";

const timestamp = Date.UTC(2024, 6, 10, 12, 0, 0); // 2024-07-10T12:00:00.000Z
const start = startOfWeek(timestamp, "America/New_York", WeekStartsOn.MONDAY);
console.log(start, toISOString(start, "UTC")); // 1720411200000 (2024-07-08T04:00:00.000Z)

`startOfWeekBase`

Returns the timestamp for the end of the week (23:59:59.999) respecting weekStartsOn.

reference/week/startOfWeekBase.ts

import { startOfWeekBase, toISOString, WeekStartsOn } from "datezone";

const start = startOfWeekBase(
	2024,
	7,
	10,
	WeekStartsOn.MONDAY,
	"America/New_York",
);
console.log(start, toISOString(start, "UTC")); // 1720411200000 (2024-07-08T04:00:00.000Z)

`endOfWeek`

Returns the Monday-based start of ISO week for the given timestamp.

reference/week/endOfWeek.ts

import { endOfWeek, toISOString, WeekStartsOn } from "datezone";

const timestamp = 1720612800000; // 2024-07-10T12:00:00.000Z
const end = endOfWeek(timestamp, "America/New_York", WeekStartsOn.MONDAY);
console.log(end, toISOString(end, "UTC")); // 1721015999999 (2024-07-15T03:59:59.999Z)

`endOfWeekBase`

Returns the Sunday-based end of ISO week for the given timestamp.

reference/week/endOfWeekBase.ts

import { endOfWeekBase, toISOString, WeekStartsOn } from "datezone";

const end = endOfWeekBase(2024, 7, 10, WeekStartsOn.MONDAY, "America/New_York");
console.log(end, toISOString(end, "UTC")); // 1721015999999 (2024-07-15T03:59:59.999Z)

`addWeeks`

Adds a specified number of weeks to a timestamp, correctly handling timezone differences.

reference/week/addWeeks.ts

import { addWeeks, toISOString } from "datezone";

const timestamp = 1720612800000; // 2024-07-10T12:00:00.000Z

// Add 2 weeks
const twoWeeksLater = addWeeks(timestamp, 2, "America/New_York");
console.log(twoWeeksLater, toISOString(twoWeeksLater, "UTC")); // 1721793600000 2024-07-24T04:00:00.000Z

`addWeeksBase`

Returns the timestamp for the given date plus the given number of weeks.

reference/week/addWeeksBase.ts

import { addWeeksBase, toISOString } from "datezone";

const twoWeeksLater = addWeeksBase(2024, 7, 10, 2, "America/New_York");
console.log(twoWeeksLater, toISOString(twoWeeksLater, "UTC")); // 1721793600000 (2024-07-24T04:00:00.000Z)

`subWeeks`

Subtracts a specified number of weeks from a timestamp.

reference/week/subWeeks.ts

import { subWeeks, toISOString } from "datezone";

const timestamp = Date.UTC(2024, 6, 10, 12, 0, 0); // 2024-07-10T12:00:00.000Z
const twoWeeksAgo = subWeeks(timestamp, 2, "America/New_York");
console.log(twoWeeksAgo, toISOString(twoWeeksAgo, "UTC")); // 1719374400000 2024-06-26T04:00:00.000Z

`startOfISOWeek`

Returns the Monday-based start of ISO week for the given timestamp.

reference/week/startOfISOWeek.ts

import { startOfISOWeek, toISOString } from "datezone";

const timestamp = 1720612800000; // 2024-07-10T12:00:00.000Z
const start = startOfISOWeek(timestamp, "America/New_York");
console.log(start, toISOString(start, "UTC")); // 1720411200000 (2024-07-08T04:00:00.000Z)

`endOfISOWeek`

Returns the Sunday-based end of ISO week for the given timestamp.

reference/week/endOfISOWeek.ts

import { endOfISOWeek, toISOString } from "datezone";

const timestamp = 1720612800000; // 2024-07-10T12:00:00.000Z
const end = endOfISOWeek(timestamp, "America/New_York");
console.log(end, toISOString(end, "UTC")); // 1721015999999 (2024-07-15T03:59:59.999Z)

`weeksInMonth`

Calculates how many ISO weeks are contained in the month of the provided timestamp.

reference/week/weeksInMonth.ts

import { WeekStartsOn, weeksInMonth } from "datezone";

const timestamp = 1720612800000; // 2024-07-10T12:00:00.000Z
const weeks = weeksInMonth(timestamp, "America/New_York", WeekStartsOn.MONDAY);
console.log(weeks); // 5

`weeksInMonthBase`

Returns the number of weeks in the given month.

reference/week/weeksInMonthBase.ts

import { WeekStartsOn, weeksInMonthBase } from "datezone";

const weeks = weeksInMonthBase(
	2024,
	7,
	WeekStartsOn.MONDAY,
	"America/New_York",
);
console.log(weeks); // 5

WeekStartsOn

Enum or constant indicating which day of the week is considered the start (e.g., Sunday or Monday).

reference/week/WeekStartsOn.ts

// Example usage of the 'WeekStartsOn' export from datezone
import { WeekStartsOn } from "datezone";

console.log("Week starts on:", WeekStartsOn.MONDAY);