Temporal API в ES2026: современный подход к работе со временем

[kirilljsx]

Забудьте о том, что вы знали о работе с датами в JavaScript. После девяти лет разработки Temporal API наконец-то достиг Stage 4 и стал частью ECMAScript 2026. Это не просто обновление — это полная переделка того, как мы работаем с датами, временем и временными зонами. Если вы писали хотя бы один парсер или интеграцию с разными часовыми поясами, вы уже знаете, сколько боли несет с собой старый Date object.

В этой статье разберёмся, почему Temporal — это эволюция, а не революция, как его использовать в реальных проектах и почему TypeScript разработчики должны обновить свои знания прямо сейчас.

Почему старый Date так плох

Действительно, Date существует с начала JavaScript, но его конструкция отражает время, когда веб был намного проще. Неизменяемость отсутствует — все методы изменяют объект на месте, что приводит к неожиданным побочным эффектам. Вы вызываете setMonth(), и затем другая часть кода работает с уже изменённым объектом, а вы об этом не знаете.

Ещё хуже то, что Date неявно работает с локальной временной зоной пользователя, и это легко пропустить. Результат: баги, которые проявляются только у части пользователей в определённых часовых поясах. К тому же, старый API попросту неудобен — нужно писать кучу вспомогательных функций для простых операций вроде добавления дней или форматирования даты.

Теперь о конкретных проблемах:

• Мутирующие методы — каждый setter изменяет исходный объект, что нарушает принципы функционального программирования
• Неявная работа с часовыми поясами — Date всегда использует локальную зону, что скрыто от разработчика
• Нет встроенной поддержки только дат или только времени — приходится создавать обходные пути
• Невозможно работать с календарями, отличными от григорианского — для не-западных приложений это серьёзное ограничение
• Запутанный и неэргономичный API — методы названы странно, поведение не всегда интуитивно

Temporal API: четыре кита современной работы со временем

Temporal переделал всё с нуля, взяв самое лучшее из других языков (как Python и C#) и адаптировав для JavaScript. Это не просто улучшение — это новая парадигма. Основной посыл: явность, неизменяемость и удобство.

Вместо одного Date object, Temporal даёт вам набор специализированных классов. Каждый из них отвечает за одну задачу, и вместе они покрывают абсолютно все сценарии работы со временем. Это похоже на то, как в TypeScript вы вместо any используете правильные типы — код становится чище и безопаснее.

Основные типы данных, которыми вы будете оперировать:

• Temporal.Instant — конкретный момент времени (UTC, неизменяемо)
• Temporal.PlainDate — дата без времени (например, день рождения)
• Temporal.PlainTime — время без даты (например, время встречи)
• Temporal.PlainDateTime — дата и время, но без привязки к часовому поясу
• Temporal.ZonedDateTime — полная информация: дата, время и часовой пояс
• Temporal.Now — пространство имён для получения текущего времени

Каждый класс имеет методы для манипуляции данными: add(), subtract(), round(), equals(), compare(). Все они возвращают новые объекты, оставляя исходные без изменений.

Практические примеры: от парсинга до автоматизации

Давайте посмотрим, как реальный код выглядит с Temporal. Вы разработчик, пилите интеграцию с несколькими часовыми поясами — вот именно здесь Temporal светит во всей красе.

Получение текущей даты и времени — просто и понятно:

const today = Temporal.Now.plainDateISO();
console.log(today.toString()); // 2026-03-25

const now = Temporal.Now.instant();
console.log(now.epochMilliseconds); // миллисекунды с эпохи

Работа с конкретной датой и добавление дней:

const date = Temporal.PlainDate.from({ year: 2026, month: 3, day: 11 });
const nextWeek = date.add({ days: 7 });
console.log(nextWeek.toString()); // 2026-03-18

Оригинальная date остаётся без изменений. Это неизменяемость в действии — как в TypeScript с readonly параметрами, но встроенная в язык.

Конвертация между часовыми поясами — вот где видна вся мощь:

const instant = Temporal.Instant.from('2026-03-21T10:00:00Z');
const johannesburgTime = instant.toZonedDateTimeISO('Africa/Johannesburg');
console.log(johannesburgTime.toString()); // 2026-03-21T12:00:00+02:00[Africa/Johannesburg]

Вы получили абсолютный момент времени (UTC), а потом показали его в конкретной зоне. Никакой магии, никакой неявной конвертации.

Работа с cookie-ми и временем жизни:

const expires = Temporal.Now.instant().add({ hours: 24 }).epochMilliseconds;
await cookieStore.set({
  name: 'session',
  value: 'token123',
  expires: expires
});

Вместо старого способа писать Date.now() + 24 * 60 * 60 * 1000, вы пишете четко: добавь 24 часа. Намного выразительнее.

Парсинг и сравнение дат:

const deadline = Temporal.PlainDate.from('2026-06-30');
const today = Temporal.Now.plainDateISO();

if (today.equals(deadline)) {
  console.log('Сегодня дедлайн!');
} else if (Temporal.PlainDate.compare(today, deadline) < 0) {
  console.log('Ещё есть время');
}

Методы compare() работают со всеми типами Temporal и возвращают -1, 0 или 1, как в других языках.

TypeScript интеграция: типизация по полной программе

Теперь самое интересное для тех, кто пишет на TypeScript. Temporal органично встраивается в систему типов и делает ваш код ещё безопаснее. В TypeScript 6.0 Beta уже есть встроенная поддержка Temporal типов.

Вместо того чтобы передавать Date | number | string (что вообще ужас), вы можете быть конкретны:

function scheduleTask(date: Temporal.PlainDate, time: Temporal.PlainTime): void {
  const dateTime = date.toPlainDateTime(time);
  // теперь мы знаем точно, что у нас есть
}

function sendNotificationAt(instant: Temporal.Instant): Promise<void> {
  // функция работает с абсолютным временем в UTC
  // никаких сюрпризов с часовыми поясами
}

Типы становятся документацией вашего кода. Глядя на сигнатуру функции, сразу понимаешь, какую именно информацию нужно передать. Это особенно полезно, когда работаете в команде или через несколько месяцев возвращаетесь к своему старому коду.

Ещё один плюс — валидация на уровне системы типов:

const date: Temporal.PlainDate = Temporal.PlainDate.from('2026-03-25'); // OK
const invalid: Temporal.PlainDate = '2026-03-25'; // ERROR: Type 'string' is not assignable to type 'Temporal.PlainDate'

Compiler не пустит вас дальше, если вы попробуете смешать типы. Это предотвращает целый класс багов на стадии разработки.

Автоматизация и масштабирование: где Temporal экономит время

Если вы автоматизируете бизнес-процессы или пилите парсеры, Temporal становится вашим лучшим другом. Повторяющиеся задачи, связанные со временем, упрощаются в разы.

Рассмотрите сценарий: нужно скачать отчёты за каждый день месяца, но только в рабочие дни и только с 9 до 17 часов (время сервера в UTC). Старый способ — кошмар из условий и проверок. С Temporal это логично:

function* generateWorkingHours(startDate: Temporal.PlainDate, endDate: Temporal.PlainDate) {
  let current = startDate;
  
  while (Temporal.PlainDate.compare(current, endDate) <= 0) {
    // Пропускаем выходные (суббота и воскресенье)
    if (current.dayOfWeek < 6) {
      for (let hour = 9; hour < 17; hour++) {
        const time = Temporal.PlainTime.from({ hour });
        yield current.toPlainDateTime(time).toZonedDateTime('UTC');
      }
    }
    current = current.add({ days: 1 });
  }
}

Код читается как описание логики, а не как боевик по исправлению багов с датами.

Ещё несколько практических применений:

• Расчёт сроков по рабочим дням — добавь N рабочих дней к дате с учётом выходных и праздников
• Обработка логов по временным диапазонам — парсинг timestamp-ов из разных источников и группировка
• Планирование крон-задач — расчёт следующего времени запуска с учётом переходов на летнее/зимнее время
• Сравнение версий с датами — версионирование по датам без борьбы с временными зонами
• Отчёты и статистика — агрегация данных по дням, неделям, месяцам с чистым API

Особенно полезна работа с повторяющимися событиями (recurrence rules):

const startDate = Temporal.PlainDate.from('2026-04-01');
const dates: Temporal.PlainDate[] = [];

// Каждый понедельник в апреле
let current = startDate;
while (current.month === 4) {
  if (current.dayOfWeek === 1) {
    dates.push(current);
  }
  current = current.add({ days: 1 });
}

Когда масштабируете, скорость разработки и количество багов напрямую зависят от удобства API. Temporal в этом плане — как обновление с Python 2 на Python 3: вроде мелочь, а на деле экономит часы работы.

Поддержка браузеров и инструментов: можно ли использовать уже сейчас

Темпоральный вопрос — когда его использовать. Хорошая новость: уже сейчас. Stage 4 в TC39 означает, что это финальная версия, и браузеры уже добавляют поддержку.

Текущее состояние поддержки на момент написания:

Браузер/Окружение	Версия	Статус
Firefox	139+ (май 2025)	Полная поддержка
Chrome	144+ (январь 2026)	Полная поддержка
Edge	144+ (январь 2026)	Полная поддержка
Node.js	26 (планируется)	Будет в стабильной версии
TypeScript	6.0 Beta (февраль 2026)	Встроенные типы
Safari	Technology Preview	Частичная поддержка

Для проектов на Node.js вы можете использовать Temporal прямо сейчас, если работаете на свежих версиях. Для браузерных приложений ситуация лучше — большинство современных браузеров уже поддерживают.

Если вам нужна поддержка старых браузеров, существуют полифиллы. Временная API достаточно сложная, и полифилл может быть значительным по размеру, но это лучше, чем остаться с проблемами старого Date.

Миграция со старого кода:

// Было
const now = new Date();
const nextWeek = new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000);

// Стало
const now = Temporal.Now.instant();
const nextWeek = now.add({ days: 7 });

Вы не обязаны переписывать весь legacy код сразу. Начните с новых функций и постепенно переходите на Temporal в остальном коде.

На что обратить внимание: подводные камни

Temporal мощный, но есть несколько деталей, которые стоит помнить. Наносекундная точность — это здорово для некоторых применений, но может быть избыточно в других. Не все базы данных поддерживают наносекунды, поэтому при сохранении в БД придётся конвертировать.

Ещё один момент — RFC 9557 формат. Temporal использует расширенный ISO 8601 формат с поддержкой часовых поясов и календарей. Это мощно, но при обмене данными с системами, не знающими об этом формате, нужна конвертация.

Кроме того, сравнение дат работает правильно только для одного типа. Нельзя напрямую сравнивать PlainDate с ZonedDateTime — нужно сначала привести их к одному типу.

И наконец, помните про диапазон дат. Temporal поддерживает диапазон ±108 дней от Unix эпохи (приблизительно с -271821 по +275760), что на практике означает, что можно работать с датами в прошлом и далёком будущем, но не раньше чем на миллионы лет назад.

Что дальше: окончание эпохи старого Date

Temporal API в ES2026 — это поворотный момент. Эти девять лет разработки окупились тем, что JavaScript наконец получил инструмент, достойный 2026-го года. Если вы разработчик на TypeScript, пишете парсеры, обрабатываете временные ряды или просто устали от багов с датами — пора переходить.

Обновитесь на свежие версии браузеров и Node.js, начните писать новый код с Temporal и постепенно мигрируйте старый. Это будет того стоить. Потратите день-два на изучение API, сэкономите недели на отладке будущих багов.