Temporal API - koniec koszmaru pracy z datami 🤩

Temporal API to nowe API JavaScriptu do pracy z datami, godzinami i strefami czasowymi. Nie jest kolejną biblioteką, którą trzeba doinstalować do projektu, tylko kierunkiem, w którym sam JavaScript ma w końcu uporządkować temat dat. Cel jest prosty: mniej zgadywania, mniej dziwnych przesunięć czasu i mniej sytuacji, w których data, godzina, strefa czasowa i konkretny moment w czasie są wrzucone do jednego worka.

W czerwcu 2026 Temporal jest już na Stage 4 w TC39, czyli od strony standardu jest praktycznie gotowy. Zaczyna też pojawiać się w przeglądarkach i Node.js. To nadal nie znaczy, że można wrzucić go do każdej aplikacji bez sprawdzenia. MDN oznacza Temporal jako funkcję o ograniczonej dostępności, a największym znakiem zapytania pozostają Safari i iOS.

Dlaczego to potrzebne?

Stary Date w JS to relikt, z którym da się żyć, ale trudno go lubić. Jeden obiekt próbuje opisać za dużo rzeczy naraz: konkretny moment w czasie, lokalną datę, godzinę i wynik przeliczeń zależnych od ustawień systemu użytkownika. Do tego dochodzą klasyczne pułapki: miesiące liczone od zera, automatyczne "naprawianie" niepoprawnych dat, odczytywanie dat zapisanych jako tekst oraz metody, które potrafią po cichu zmienić istniejącą datę.

Największy problem pojawia się wtedy, gdy aplikacja musi obsłużyć realne scenariusze: rezerwacje, deadline'y, spotkania w różnych krajach, cykliczne wydarzenia, zmianę czasu z letniego na zimowy albo dane zapisywane po stronie serwera w UTC i wyświetlane lokalnie użytkownikowi. W takich miejscach Date bardzo łatwo pozwala napisać kod, który wygląda poprawnie, ale przesuwa godzinę o jedną strefę albo jeden dzień.

Co konkretnie daje Temporal?

Temporal robi jedną bardzo ważną rzecz: rozdziela pojęcia, które Date mieszał w jednym obiekcie. Temporal.Instant opisuje konkretny punkt w czasie. Temporal.PlainDate to sama data, bez godziny i strefy. Temporal.PlainTime to sama godzina. Temporal.ZonedDateTime łączy datę, godzinę i konkretną strefę czasową, np. Europe/Warsaw. Do tego dochodzi Temporal.Duration, czyli prosty sposób opisania różnicy typu "dodaj 2 godziny i 30 minut".

W praktyce oznacza to mniej ukrytych przeliczeń i więcej decyzji zapisanych w kodzie wprost. Temporal nie zmienia też raz utworzonych wartości. Metody takie jak add() i subtract() zwracają nowe daty, zamiast po cichu modyfikować istniejącą.

Przykłady praktyczne

Tworzenie daty ze strefą czasową

Przykład: Spotkanie w Warszawie o 14:30, 11 sierpnia 2026 roku:

const date = new Date('2026-08-11T14:30:00+02:00');
console.log(date.toString()); // -> Wynik zostanie pokazany w lokalnej strefie użytkownika.

const meeting = Temporal.ZonedDateTime.from({
    year: 2026,
    month: 8,
    day: 11,
    hour: 14,
    minute: 30,
    timeZone: 'Europe/Warsaw',
});

console.log(meeting.toString()); // -> 2026-08-11T14:30:00+02:00[Europe/Warsaw]

Dodawanie czasu bez mutowania

const later = meeting.add({ hours: 2, minutes: 30 });

console.log(meeting.toString()); // -> 2026-08-11T14:30:00+02:00[Europe/Warsaw]
console.log(later.toString()); // -> 2026-08-11T17:00:00+02:00[Europe/Warsaw]

Konwersja i formatowanie

const instant = Temporal.Instant.from('2026-08-11T12:30:00Z');
const warsawTime = instant.toZonedDateTimeISO('Europe/Warsaw');

console.log(warsawTime.toLocaleString('pl-PL', {
    dateStyle: 'medium',
    timeStyle: 'short',
    timeZoneName: 'short',
}));

Wsparcie przeglądarek i jak zacząć

Najprościej testować Temporal tam, gdzie jest już wbudowany. W czerwcu 2026 można sprawdzać go m.in. w Firefoxie 139+, Chrome/Edge 144+ oraz w Node.js 26+. Aktualną listę obsługiwanych przeglądarek warto sprawdzać w Can I Use, bo wsparcie, niestety, nadal nie jest równomierne.

Do szybkiego sprawdzenia wystarczy prosty test w kodzie:

console.log(typeof globalThis.Temporal !== 'undefined'); // -> true albo false, zależnie od tego, gdzie uruchamiasz kod

Jeżeli chcesz poeksperymentować w projekcie już teraz, możesz użyć polyfilla, np. @js-temporal/polyfill. To dodatkowa paczka, która pozwala korzystać z Temporal zanim dana przeglądarka obsłuży go sama. Warto jednak pamiętać, że TC39 wprost odradza używanie starego, testowego polyfilla z repozytorium proposal-temporal w prawdziwych projektach.

Kiedy można bezpiecznie używać go w produkcji?

Bez polyfilla - dopiero wtedy, gdy przeglądarki i wersje, z których korzystają Twoi użytkownicy, mają już dostęp do Temporal. W aplikacji webowej oznacza to głównie sprawdzenie Safari, iOS, starszych wersji Google Chrome, a także osadzane w apkach mobilnych WebView oraz starsze przeglądarki narzucane przez firmy ich pracownikom. Na backendzie trzeba po prostu upewnić się, na jakiej wersji Node.js działa projekt i czy jest to już spokojny wybór na produkcję. Node.js 26 w czerwcu 2026 jest jeszcze wydaniem Current, a nie LTS.

Z polyfillem można zacząć wcześniej, ale nadal warto potraktować go jak coś, co bierzesz na siebie w produkcji. Trzeba sprawdzić, ile kodu dokładamy do aplikacji, czy wszystko działa w przeglądarkach używanych przez użytkowników, jak zachowuje się zmiana czasu letniego i zimowego oraz gdzie nowy kod spotyka się ze starym kodem opartym na Date.

Najbezpieczniejszy sposób używania Temporal w praktyce jest dość prosty: konkretne momenty w czasie trzymaj jako UTC albo Instant, zwykłe daty kalendarzowe jako PlainDate, a wydarzenia związane z konkretnym miejscem jako ZonedDateTime. Przeliczanie do widoku użytkownika rób dopiero tam, gdzie pokazujesz dane na ekranie.

Podsumowanie

Temporal API nie sprawia, że daty nagle stają się proste. Sprawia za to, że problemy są nazwane wprost: inny typ dla daty, inny dla godziny, inny dla punktu w czasie i inny dla daty ze strefą czasową. To duża zmiana względem leciwego Date, który przez lata zmuszał frontendowców do zgadywania, dokładania bibliotek i pisania bardzo ostrożnego kodu.

Na dziś Temporal warto znać, testować i brać pod uwagę przy nowych projektach. Nie trzeba od razu przepisywać całej aplikacji. Warto jednak wiedzieć, że JavaScript w końcu dostaje sensowniejszy sposób pracy z datami - i że przed użyciem na produkcji trzeba sprawdzić wsparcie albo świadomie dodać polyfill.