This capability provides advanced calendar operations for working with date ranges, week arrays, month arrays, and calendar views. These methods are particularly useful for building calendar components, date pickers, and scheduling interfaces.
getWeekArray(date: Moment): Moment[][]Generates a 2D array representing a calendar month view with weeks as rows and days as columns. Each week contains 7 days, with leading/trailing days from adjacent months to fill complete weeks.
Parameters:
date - Any date within the month to generate the calendar forReturns: 2D array where each sub-array represents a week (usually 4-6 weeks total)
Usage:
const october2023 = utils.parseISO("2023-10-15T12:00:00.000Z");
const weekArray = utils.getWeekArray(october2023);
// Result structure (example):
// [
// [Sep24, Sep25, Sep26, Sep27, Sep28, Sep29, Sep30], // Week 1 (partial)
// [Oct01, Oct02, Oct03, Oct04, Oct05, Oct06, Oct07], // Week 2
// [Oct08, Oct09, Oct10, Oct11, Oct12, Oct13, Oct14], // Week 3
// [Oct15, Oct16, Oct17, Oct18, Oct19, Oct20, Oct21], // Week 4
// [Oct22, Oct23, Oct24, Oct25, Oct26, Oct27, Oct28], // Week 5
// [Oct29, Oct30, Oct31, Nov01, Nov02, Nov03, Nov04] // Week 6 (partial)
// ]
// Practical usage for calendar component
weekArray.forEach((week, weekIndex) => {
week.forEach((day, dayIndex) => {
const isCurrentMonth = utils.isSameMonth(day, october2023);
const isToday = utils.isSameDay(day, utils.date());
console.log(`Week ${weekIndex}, Day ${dayIndex}: ${utils.format(day, "shortDate")}
(Current month: ${isCurrentMonth}, Today: ${isToday})`);
});
});getMonthArray(date: Moment): Moment[]Generates an array of 12 Moment objects representing all months in the year of the given date. Each month is set to the first day of that month.
Parameters:
date - Any date within the year to generate months forReturns: Array of 12 Moment objects (January through December)
Usage:
const someDate2023 = utils.parseISO("2023-06-15T12:00:00.000Z");
const monthArray = utils.getMonthArray(someDate2023);
// Result: [
// 2023-01-01T00:00:00.000Z, // January
// 2023-02-01T00:00:00.000Z, // February
// 2023-03-01T00:00:00.000Z, // March
// // ... through ...
// 2023-12-01T00:00:00.000Z // December
// ]
// Practical usage for month picker
monthArray.forEach((month, index) => {
const monthName = utils.format(month, "month");
const isCurrentMonth = utils.isSameMonth(month, utils.date());
console.log(`${index}: ${monthName} (Current: ${isCurrentMonth})`);
});getYearRange(start: Moment, end: Moment): Moment[]Generates an array of Moment objects representing years between start and end dates (inclusive). Each year is set to January 1st of that year.
Parameters:
start - Starting date (year will be extracted)end - Ending date (year will be extracted)Returns: Array of Moment objects for each year in the range
Usage:
const start2020 = utils.parseISO("2020-05-15T12:00:00.000Z");
const end2025 = utils.parseISO("2025-08-20T12:00:00.000Z");
const yearRange = utils.getYearRange(start2020, end2025);
// Result: [
// 2020-01-01T00:00:00.000Z,
// 2021-01-01T00:00:00.000Z,
// 2022-01-01T00:00:00.000Z,
// 2023-01-01T00:00:00.000Z,
// 2024-01-01T00:00:00.000Z,
// 2025-01-01T00:00:00.000Z
// ]
// Practical usage for year picker
yearRange.forEach(year => {
const yearNumber = utils.getYear(year);
const isCurrentYear = utils.isSameYear(year, utils.date());
console.log(`${yearNumber} (Current: ${isCurrentYear})`);
});
// Single year (start === end)
const single = utils.getYearRange(start2020, start2020); // [2020-01-01T00:00:00.000Z]getWeekdays(): string[]Returns an array of localized weekday names starting from the locale-specific first day of the week.
Returns: Array of 7 weekday names in locale language
Usage:
// English locale
const enUtils = new MomentUtils({ locale: "en" });
const enWeekdays = enUtils.getWeekdays();
// ["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]
// French locale
const frUtils = new MomentUtils({ locale: "fr" });
const frWeekdays = frUtils.getWeekdays();
// ["lundi", "mardi", "mercredi", "jeudi", "vendredi", "samedi", "dimanche"]
// German locale
const deUtils = new MomentUtils({ locale: "de" });
const deWeekdays = deUtils.getWeekdays();
// ["Montag", "Dienstag", "Mittwoch", "Donnerstag", "Freitag", "Samstag", "Sonntag"]
// Practical usage for calendar headers
const weekdays = utils.getWeekdays();
weekdays.forEach((day, index) => {
console.log(`Column ${index}: ${day}`);
});mergeDateAndTime(date: Moment, time: Moment): MomentCombines the date portion from the first parameter with the time portion from the second parameter. Note: This method modifies the original date object in place rather than creating a new instance.
Parameters:
date - Source for date components (year, month, day)time - Source for time components (hour, minute, second, millisecond)Returns: New Moment object with combined date and time
Usage:
const targetDate = utils.parseISO("2023-10-30T09:15:30.123Z"); // Date we want
const timeToApply = utils.parseISO("2023-01-01T14:45:20.500Z"); // Time we want
const combined = utils.mergeDateAndTime(targetDate, timeToApply);
// Result: 2023-10-30T14:45:20.500Z (Oct 30 date with 14:45:20.500 time)
// Practical usage scenarios:
// 1. Date picker + time picker combination
const selectedDate = utils.parseISO("2023-12-25T00:00:00.000Z"); // User selected date
const selectedTime = utils.parseISO("2023-01-01T18:30:00.000Z"); // User selected time
const appointment = utils.mergeDateAndTime(selectedDate, selectedTime);
// Result: 2023-12-25T18:30:00.000Z
// 2. Apply business hours to a selected date
const today = utils.date();
const businessHourStart = utils.parseISO("2023-01-01T09:00:00.000Z"); // 9 AM
const workDayStart = utils.mergeDateAndTime(today, businessHourStart);
// 3. Preserve time while changing date
const originalDateTime = utils.parseISO("2023-10-15T16:45:30.000Z");
const newDate = utils.parseISO("2023-11-20T00:00:00.000Z");
const preservedTime = utils.mergeDateAndTime(newDate, originalDateTime);
// Result: 2023-11-20T16:45:30.000Z (Nov 20 with original time)Here are practical examples of using these methods together to build calendar functionality:
function buildMonthlyCalendar(displayMonth: Moment) {
const weekArray = utils.getWeekArray(displayMonth);
const weekdays = utils.getWeekdays();
const today = utils.date();
return {
weekdays,
weeks: weekArray.map(week =>
week.map(day => ({
date: day,
isCurrentMonth: utils.isSameMonth(day, displayMonth),
isToday: utils.isSameDay(day, today),
isWeekend: [0, 6].includes(day.day()), // Sunday or Saturday
formattedDate: utils.format(day, "dayOfMonth")
}))
)
};
}
const october2023 = utils.parseISO("2023-10-15T12:00:00.000Z");
const calendar = buildMonthlyCalendar(october2023);function buildYearView(displayYear: Moment) {
const monthArray = utils.getMonthArray(displayYear);
const today = utils.date();
return monthArray.map(month => ({
month,
monthName: utils.format(month, "month"),
isCurrentMonth: utils.isSameMonth(month, today),
daysInMonth: utils.getDaysInMonth(month),
firstDayOfWeek: utils.startOfWeek(utils.startOfMonth(month)).day()
}));
}
const year2023 = utils.parseISO("2023-06-15T12:00:00.000Z");
const yearView = buildYearView(year2023);function buildDateRangePicker(minDate: Moment, maxDate: Moment) {
const yearRange = utils.getYearRange(minDate, maxDate);
const currentYear = utils.getYear(utils.date());
return {
availableYears: yearRange.map(year => ({
year: utils.getYear(year),
label: utils.format(year, "year"),
isCurrent: utils.getYear(year) === currentYear
})),
minDate,
maxDate,
isDateInRange: (date: Moment) => utils.isWithinRange(date, [minDate, maxDate])
};
}
const min = utils.parseISO("2020-01-01T00:00:00.000Z");
const max = utils.parseISO("2025-12-31T23:59:59.999Z");
const rangePicker = buildDateRangePicker(min, max);