Що таке Temporal API?

JavaScriptMiddle~2 хв читання

Temporal API - це нове вбудоване API для роботи з датами і часом у JavaScript (офіційно у стадії фінального стандарту ES2024). Його мета - замінити "зламаний" Date і дати точні, безпечні, зручні інструменти для всіх операцій із часом.

Чому взагалі з'явився Temporal

Date - одна з найстаріших і найпроблемніших частин JS (ще з 1995 року):

Проблема	Приклад
Неявні часові пояси	`new Date('2024-01-01')` -> результат залежить від твого регіону
Непередбачувані обчислення	`new Date(2024, 1, 30)` -> 1 березня
Мутуючі методи	`setMonth()`, `setHours()` змінюють вихідний об'єкт
Погана робота з UTC	Часто потрібно вручну конвертувати через `toISOString()`, `getUTC*()`
Немає нормального API для календарів, тривалостей і часових зон

Temporal вирішує всі ці проблеми, вводячи чітку модель часу і незмінні об'єкти.

Основна ідея Temporal API

Temporal дає нові класи, які працюють з різними аспектами часу:

Клас	Що представляє	Приклад
`Temporal.Instant`	Момент у часі (точка в UTC)	`"2025-10-16T21:00:00Z"`
`Temporal.PlainDate`	Дата без часу	`"2025-10-16"`
`Temporal.PlainTime`	Час без дати	`"21:00:00"`
`Temporal.PlainDateTime`	Дата і час без часового поясу	`"2025-10-16T21:00:00"`
`Temporal.ZonedDateTime`	Дата + час + часовий пояс	`"2025-10-16T21:00:00+02:00[Europe/Warsaw]"`
`Temporal.Duration`	Різниця між моментами (тривалість)	`"P3DT5H"` (3 дні 5 годин)
`Temporal.Now`	Утиліта для отримання поточного часу	-

Приклад: створення дати і часу

javascript

// Проста дата
const date = Temporal.PlainDate.from('2025-10-16');
console.log(date.year, date.month, date.day); // 2025 10 16

// Час
const time = Temporal.PlainTime.from('13:45:30');
console.log(time.hour); // 13

// Дата і час
const dt = Temporal.PlainDateTime.from('2025-10-16T13:45:30');
console.log(dt.toString()); // 2025-10-16T13:45:30

Приклад: робота з часовими поясами

javascript

const zdt = Temporal.ZonedDateTime.from({
  timeZone: 'Europe/Warsaw',
  year: 2025,
  month: 10,
  day: 16,
  hour: 21,
});

console.log(zdt.toString());
// 2025-10-16T21:00:00+02:00[Europe/Warsaw]

console.log(zdt.toInstant().toString());
// 2025-10-16T19:00:00Z (в UTC)

Temporal зберігає часовий пояс як частину даних ([Europe/Warsaw]), а не просто зміщення +02:00.

Приклад: обчислення з датами і часом

javascript

const today = Temporal.PlainDate.from('2025-10-16');
const tomorrow = today.add({ days: 1 });
const lastWeek = today.subtract({ weeks: 1 });

console.log(tomorrow.toString()); // 2025-10-17
console.log(lastWeek.toString()); // 2025-10-09

Усі об'єкти незмінні - операції повертають нові значення, не змінюючи вихідний об'єкт.

Приклад: обчислення тривалості (Duration)

javascript

const start = Temporal.PlainDateTime.from('2025-10-16T10:00');
const end = Temporal.PlainDateTime.from('2025-10-18T15:30');

const duration = end.since(start);
console.log(duration.toString()); // P2DT5H30M (2 дні 5 годин 30 хвилин)

Приклад: поточний час і час у зоні

javascript

const now = Temporal.Now.instant();
console.log(now.toString()); // Поточний UTC-час

const warsaw = Temporal.Now.zonedDateTimeISO('Europe/Warsaw');
console.log(warsaw.toString());
// Наприклад: 2025-10-16T23:50:00+02:00[Europe/Warsaw]

Приклад: відмінність від `Date`

javascript

// Date
new Date(2025, 1, 30) // 2025-03-02 (!) -> автоматичне "перенесення"

// Temporal
Temporal.PlainDate.from({ year: 2025, month: 1, day: 30 });
// RangeError: Invalid PlainDate

Temporal суворо перевіряє коректність дат - жодних "автоматичних виправлень".

Приклад: форматування і парсинг ISO

javascript

const zdt = Temporal.ZonedDateTime.from('2025-10-16T21:00+02:00[Europe/Warsaw]');
console.log(zdt.toString()); // 2025-10-16T21:00:00+02:00[Europe/Warsaw]

Підтримує повний ISO 8601 і роботу з часовими зонами через базу IANA (ту саму, що в Intl.DateTimeFormat).

Приклад: використання з `Intl`

Можна зручно форматувати дати і час для користувача:

javascript

const zdt = Temporal.ZonedDateTime.from('2025-10-16T21:00:00+02:00[Europe/Warsaw]');
const fmt = new Intl.DateTimeFormat('en-US', { dateStyle: 'full', timeStyle: 'long' });

console.log(fmt.format(zdt));
// Thursday, October 16, 2025 at 9:00:00 PM GMT+2

Приклад: безпечна робота з часовими поясами

javascript

const beforeDST = Temporal.ZonedDateTime.from('2025-03-30T01:30:00+01:00[Europe/Berlin]');
const afterDST = beforeDST.add({ hours: 1 });
console.log(afterDST.toString());
// 2025-03-30T03:30:00+02:00[Europe/Berlin]

Temporal розуміє переходи на літній/зимовий час і коректно зміщує години.

Переваги Temporal API

Перевага	Що дає
Незмінність	Безпечні операції без мутацій
Чітка модель	Розділення понять "дата", "час", "зона"
Точна робота з часовими поясами	Використовує базу IANA
Немає "магії" `Date`	Помилки замість неявних виправлень
Сумісний з `Intl`	Гарне форматування
Підтримка ISO і Duration	Проста робота з різницями та інтервалами

Де вже можна використовувати

Node.js 20+ - вбудовано нативно
Сучасні браузери (Chrome 115+, Firefox 122+, Edge 115+)
Старі середовища - через polyfill @js-temporal/polyfill

javascript

npm i @js-temporal/polyfill

javascript

import { Temporal } from '@js-temporal/polyfill';

Підсумок

Об'єкт	Опис
`Temporal.Instant`	абсолютна точка в часі (UTC)
`Temporal.PlainDate`, `PlainTime`, `PlainDateTime`	локальні значення без зони
`Temporal.ZonedDateTime`	дата + час + часовий пояс
`Temporal.Duration`	тривалість (різниця в часі)
`Temporal.Now`	доступ до поточного часу

Коротка відповідь

Для співбесіди

Premium

Коротка відповідь допоможе вам впевнено відповідати на цю тему під час співбесіди.