Работа с датами и временем в JavaScript: от А до Я для Node.js

Введение: Почему работа с датами в JavaScript — вызов для разработчика

Работа с датами и временем — одна из самых частых и одновременно коварных задач в веб-разработке. Кажется, что может быть проще, чем получить текущую дату или посчитать разницу между двумя событиями? Однако на практике разработчики на JavaScript (Node.js) сталкиваются с множеством подводных камней: часовые пояса, формат ISO, неочевидное поведение метода getMonth() и устаревшие библиотеки. В этой статье мы разберем работу с датами от базовых принципов до продвинутых техник, используя только стандартный объект Date и современную библиотеку date-fns.

1. Основы объекта Date в Node.js

Встроенный объект Date — это фундамент для работы со временем. Он хранит количество миллисекунд, прошедших с 1 января 1970 года (эпоха Unix). Рассмотрим основные операции.

Создание и получение текущего времени

Самый простой способ создать объект даты — вызвать new Date() без аргументов. Это вернет текущую дату и время на сервере.

// Текущая дата и время (в часовом поясе сервера)
const now = new Date();
console.log(now); // Пример: 2024-05-20T14:30:00.000Z

// Создание из строки ISO
const specificDate = new Date('2024-12-25T10:00:00');
console.log(specificDate); // 2024-12-25T10:00:00.000Z

// Создание из компонентов (год, месяц, день, часы, минуты, секунды)
const birthday = new Date(1990, 5, 15); // Внимание: месяц 5 = Июнь!
console.log(birthday); // 1990-06-15T00:00:00.000Z

Важное замечание: Месяцы в JavaScript нумеруются с 0 (Январь — 0, Декабрь — 11). Это частая причина багов.

Методы для получения компонентов даты

Для извлечения отдельных частей даты используются геттеры. Помните, что они возвращают значения в локальном часовом поясе сервера.

const date = new Date('2024-03-15T12:30:45');

console.log(date.getFullYear());   // 2024
console.log(date.getMonth());      // 2 (Март, так как отсчет с 0)
console.log(date.getDate());       // 15
console.log(date.getDay());        // 5 (Пятница, 0 - Воскресенье)
console.log(date.getHours());      // 12
console.log(date.getMinutes());    // 30
console.log(date.getSeconds());    // 45

Для работы в UTC (всемирное координированное время) используйте методы с префиксом getUTC..., например getUTCHours().

2. Форматирование и вывод дат

В Node.js нет встроенного удобного форматирования дат в произвольный строковый формат (например, "15 марта 2024"). Для этого есть два пути: ручная сборка строки или использование библиотек.

Ручное форматирование (без сторонних библиотек)

Если вам нужно вывести дату в простом формате, можно написать небольшую функцию.

function formatDate(date) {
  const day = String(date.getDate()).padStart(2, '0');
  const month = String(date.getMonth() + 1).padStart(2, '0');
  const year = date.getFullYear();
  return `${day}.${month}.${year}`;
}

const today = new Date();
console.log(formatDate(today)); // Пример: "20.05.2024"

Современное решение: библиотека date-fns

Библиотека date-fns — это современная, модульная и легковесная альтернатива устаревшему moment.js. Она идеально подходит для Node.js.

// Установка: npm install date-fns

const { format, addDays, differenceInDays } = require('date-fns');
const { ru } = require('date-fns/locale'); // Локализация

const date = new Date();

// Форматирование с локализацией
console.log(format(date, 'dd MMMM yyyy', { locale: ru }));
// Пример: "20 мая 2024"

// Добавление дней
const nextWeek = addDays(date, 7);
console.log(format(nextWeek, 'yyyy-MM-dd')); // "2024-05-27"

// Разница в днях
const start = new Date(2024, 0, 1);
const end = new Date(2024, 11, 31);
console.log(differenceInDays(end, start)); // 365

Преимущества date-fns: импорт только нужных функций (экономия памяти), иммутабельность (не меняет исходный объект), поддержка таймзон.

3. Парсинг дат из строк и работа с часовыми поясами

Часто даты приходят от пользователя или из API в виде строк. Парсинг — критически важный этап, где легко ошибиться.

Парсинг строк с помощью Date и date-fns

Встроенный парсер new Date(string) нестабилен и зависит от браузера/среды. В Node.js для надежности лучше использовать date-fns/parse.

const { parse } = require('date-fns');

// Строка от пользователя: "15.03.2024 14:30"
const userInput = '15.03.2024 14:30';
const parsedDate = parse(userInput, 'dd.MM.yyyy HH:mm', new Date());

console.log(parsedDate); // 2024-03-15T11:30:00.000Z (если сервер в UTC+3)

Второй аргумент — маска формата. Это гарантирует, что дата будет распарсена правильно, независимо от региональных настроек.

Работа с часовыми поясами (Timezone)

Одна из самых сложных тем. Объект Date всегда хранит время в UTC, а геттеры конвертируют его в локальный пояс сервера. Для работы с произвольными таймзонами (например, "America/New_York") в Node.js используйте date-fns-tz.

// Установка: npm install date-fns-tz

const { format, utcToZonedTime, zonedTimeToUtc } = require('date-fns-tz');

// Конвертируем локальное время сервера в время Нью-Йорка
const date = new Date();
const timeZone = 'America/New_York';
const zonedDate = utcToZonedTime(date, timeZone);

console.log(format(zonedDate,