Запропонувати правку

Покращити цю статтю

Допрацюйте відповідь до «Що таке Temporal API?». Ваші зміни проходять модерацію перед публікацією.

Потрібне підтвердження

Контент

Що ви змінюєте

Заголовок (UA)

Коротка відповідь (UA)

Показується над повною відповіддю для швидкого нагадування.

Відповідь (UA)

**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` | доступ до поточного часу |

Markdown · перетягуйте зображення · ⌘B / ⌘I шорткати735 слів

Для рев’юера

Примітка для модератора (необов’язково)

Бачить лише модератор. Прискорює рев’ю.