Jak to będziemy robić?

Zajmiemy się wszystkimi wspomnianymi problemami po kolei, próbując ich rozwiązania zamknąć w spójne, sensowne API. Będziemy korzystać z już istniejących rozwiązań, żeby podpatrzeć, jak można pewne rzeczy zrobić. Będziemy też całość pisać w TypeScripcie, dzięki czemu za darmo dostaniemy ładne typy. Oficjalna strona TypeScriptu udostępnia miejsce do testowania kodu online.

Obecnie kod TS można także uruchomić bezpośrednio w Node.js:

$ node --experimental-strip-types ./nasz-plik.ts

Node.js obsługuje TS-a od wersji 22.6.0.

Poprawiamy asynchroniczność

Pierwszym problemem było przestarzałe podejście do asynchroniczności, objawiające się używaniem callbacków. Dlatego nasze API powinno używać obietnic, które obecnie są zalecanym sposobem obsługi asynchroniczności.

Przepisywanie APi callbackowego na obietnicowe najlepiej podpatrzyć w Node.js, które miało kiedyś ten problem:

import { readFile as readFileCallback } from 'node:fs';
import { readFile as readFilePromise } from 'node:fs/promises';

readFileCallback( '/jakis-plik', 'utf-8', ( err, data ) => {
	console.log( data );
} );

const data = await readFilePromise( '/jakis-plik', 'utf-8' );

W przypadku callbackowego API z parametrów wyleciał callback (zatem readFilePromise() przyjmuje tylko 2 parametry, podczas gdy readFileCallback() – 3). Wynik działania funkcji za to jest zwracany z tej funkcji, nie zaś – przekazywany do callbacku. I to w sumie tyle, ile będzie nam potrzebne. Warto jednak wspomnieć, że zmienia się także sposób obsługi błędów:

readFileCallback( '/plik-do-ktorego-nie-mamy-uprawnien', 'utf-8', ( err, data ) => { // 1
	console.error( err );
} );

try { // 2
	const data = await readFilePromise( '/plik-do-ktorego-nie-mamy-uprawnien', 'utf-8' );
} catch ( err ) {
	console.error( err );
}

W przypadku, gdy wystąpi błąd w wersji callbackowej, zostanie on przekazany jako pierwszy parametr do callbacku (1). W przypadku wersji z obietnicą, błąd spowoduje odrzucenie obietnicy. Można go obsłużyć, dodając blok try/catch (2).

Niemniej przy czasomierzach nie będziemy dodawać obsługi błędów. To API bowiem nie rzuca żadnymi błędami.

Mając to wszystko na uwadze, stwórzmy obietnicowe setTimeout():

async function setTimeout( delay: number ): Promise<void> { // 1
	return new Promise( ( resolve ) => { // 2
		globalThis.setTimeout( resolve, delay ); // 3
	} );
}

Tworzymy asynchroniczną funkcję setTimeout() (1), która przyjmuje jako parametr delay. Ten parametr jest typu number, bo przekazywać będziemy liczbę milisekund. Dodatkowo oznaczamy funkcję jako zwracającą pustą obietnicę (Promise<void>). W środku tworzymy nową obietnicę (2), w której wywołujemy globalThis.setTimeout() (3), a następnie zwracamy tę obietnicę. Do wywołania globalThis.setTimeout() przekazujemy resolve() obietnicy jako callback oraz delay jako liczbę milisekund do odczekania.

Kod ten wygląda bardzo podobnie do funkcji wait() z poprzedniego artykułu. Niemniej, z uwagi na to, że używamy nazwy setTimeout(), tym samym przesłaniamy natywną funkcję setTimeout(). Ta jednak wciąż istnieje jako globalThis.setTimeout() – a więc funkcja globalna o takiej nazwie. Zmienna globalThis wskazuje na globalne this (w uproszczeniu można przyjąć, że globalny obiekt) i jest dostępna nie tylko w przeglądarce, ale także w innych środowiskach uruchomieniowych JS-a (takich jak Node.js).

Tym sposobem mamy rozwiązaną połowę problemu asynchroniczności. Ale pozostaje jeszcze setInterval(), które służy do wykonywania jakiejś czynności co określony czas. Nie jesteśmy w stanie zatem zwrócić pojedynczej obietnicy. Na szczęście ktoś już ten problem rozwiązał! W Node.js istnieje oparte na obietnicach API czasomierzy, w tym – takie dla setInterval(). API to zwraca nie obietnicę, a asynchroniczny iterator:

import { setInterval } from 'node:timers/promises'; // 1

for await ( const _ of setInterval( 1000 ) ) { // 2
	console.log( 'tick' ); // 3
}

Importujemy obietnicową wersję setInterval() z modułu node:timers/promises (1). Następnie wywołujemy setInterval() wewnątrz pętli for await...of (2). Co sekundę pętla ta spowoduje wyświetlenie słowa 'tick' (3).

Spróbujmy zatem odtworzyć to API:

async function* setInterval( tick: number ): AsyncIterableIterator<void> { // 1
	while ( true ) { // 2
		yield setTimeout( tick ); // 3
	}
}

async function setTimeout( delay: number ): Promise<void> {
	[…]
}

Najprostszym sposobem na stworzenie asynchronicznego iteratora jest wykorzystanie asynchronicznego generatora (1). Wewnątrz niego tworzymy nieskończoną pętlę (2), natomiast w niej – yieldujemy wywołanie stworzonego przez nas wcześniejsetTimeout() (3). Tym sposobem za każdym razem zwracamy obietnicę, którą zewnętrzny kod może wykorzystać w pętli for await...for.

Dość ironicznie wewnątrz naszego setInterval() nie da się wykorzystać tego oryginalnego. Wynika to stąd, że dla każdego “tyknięcia” musimy zwrócić osobną wartość (nową obietnicę). W przypadku natywnego setInterval() byłoby to niemożliwe. W przeciwieństwie do setTimeout(), przekazanie resolve() nie zadziałałoby poprawnie (nie da się spełnić dwa razy tej samej obietnicy). Dlatego najłatwiejszym sposobem jest użycie obietnicowej wersji setTimeout(). Dzięki temu za każdym razem zwrócimy nową obietnicę, która zostanie rozwiązana po określonym czasie. Taka “podmiana” pojedynczego odliczania z interwałem jest możliwa, ponieważ z zewnątrz następujące po sobie wywołania setTimeout() tak naprawdę nie różnią się zachowaniem od interwału.

Dodanie wsparcia dla AbortControllera

Przejście na obietnicowe API sprawia, że drugi problem, brak wsparcia dla AbortControllera, jest jeszcze bardziej palący. Z racji tego, że obietnica jest tworzona wewnątrz setTimeout(), nie ma za bardzo możliwości jej odrzucenia z zewnątrz. Tutaj bardzo pomogłaby możliwość przekazania sygnału, który mógłby przerywać odliczanie lub interwał. Dorzućmy zatem jego obsługę do naszego API. Zacznijmy od setTimeout():

interface SetTimeoutOptions { // 2
	signal?: AbortSignal; // 3
}

async function setTimeout(
	delay: number,
	{ signal }: SetTimeoutOptions = {} // 1
): Promise<void> {
	return new Promise( ( resolve, reject ) => {
		const timeoutId = globalThis.setTimeout( resolve, delay ); // 3

		if ( signal !== undefined ) { // 4
			signal.addEventListener( 'abort', ( evt ) => { // 5
				clearTimeout( timeoutId ); // 6
				reject( evt ); // 7
			} );
		}
	} );
}

W funkcji setTimeout() pojawił się drugi, opcjonalny parametr (1). Korzystam tutaj ze wzorca obiektu opcji, żeby przekazać do funkcji obiekt z opcjonalną konfiguracją. Kształt opcji jest opisywany przez interfejs SetTimeoutOptions (2). Jak na razie zezwalamy tylko na jedną opcję – signal (3), która będzie naszym AbortSignalem. Z kolei w samym setTimeout() zapisujemy id zwracane przez natywne setTimeout() do zmiennej timeoutId (3). Następnie, jeśli sygnał został przekazany (4), dodajemy obsługę jego zdarzenia abort (5). Gdy to zdarzenie nastąpi, chcemy anulować odliczanie przy pomocy clearTimeout() (6) oraz odrzucić obietnicę (7). Jako powód odrzucenia zwracamy zdarzenie abort.

Sprawdźmy, czy faktycznie da się w taki sposób zatrzymać odliczanie. Stwórzmy sobie kilka odliczeń korzystających z tego samego sygnału, a następnie wyślijmy do niego informację o anulowaniu asynchronicznej operacji przy pomocy AbortController#abort():

const abortController = new AbortController(); // 1
const { signal } = abortController; // 2
const timeouts = [ // 3
	setTimeout( 1000, { signal } ),
	setTimeout( 2000, { signal } ),
	setTimeout( 3000, { signal } )
];

abortController.abort(); // 4

const results = await Promise.allSettled( timeouts ); // 5

results.forEach( ( result ) => {
	console.log( result ); // 6
} );

Na początku tworzymy AbortController (1) i wyciągamy z niego sygnał (2). Następnie tworzymy tablicę z setTimeout()ami (3). Każdemu odliczaniu przekazujemy ten sam sygnał. Następnie wywołujemy abortController.abort() (4), żeby przerwać odliczanie. Dalej czekamy na zakończenie wszystkich obietnic przy pomocy Promise.allSettled() (5). Użycie tej funkcji pozwoli nam na zaczekanie zarówno na odrzucone obietnice, jak i na te poprawnie spełnione (w przeciwieństwie do Promise.all(), które obsłuży tylko spełnione obietnice). Status wszystkich obietnic zapisujemy do zmiennej results. Następnie wyświetlamy status każdej obietnicy (6).

Po uruchomieniu powyższego kodu powinniśmy zobaczyć, że dla każdej obietnicy został zwrócony obiekt podobny do poniższego:

{
	status: 'rejected', // 1
	reason: { // 2
		type: 'abort',
		defaultPrevented: false,
		cancelable: false,
		timeStamp: 89.556842
	}
}

Obietnice zostały odrzucone (1), a jako powód odrzucenia podane jest zdarzenie abort (2).

Niemniej natywne API korzystające z AbortSignala zachowują się nieco inaczej. Przyjrzyjmy się, jak to robi setTimeout z Node’owego modułu node:timers/promises:

import { setTimeout } from 'node:timers/promises'; // 1

const abortController = new AbortController(); // 2
const { signal } = abortController; // 3
const res = setTimeout( 100, 'result', { signal } ); // 4

abortController.abort(); // 5

await res; // 6

Na początku importujemy setTimeout() (1). Następnie tworzymy AbortControllera (2), wyciągamy z niego sygnał (3) i przekazujemy go do wywołania setTimeout() (4). Potem wywołujemy abortController.abort() (5) i czekamy na odrzucenie odliczania (6). Jeśli uruchomimy ten kod i spojrzymy do konsoli, zobaczymy mniej więcej taki błąd:

node:timers/promises:48
    reject(new AbortError(undefined, { cause: signal?.reason }));
           ^

AbortError: The operation was aborted
    at Timeout.cancelListenerHandler (node:timers/promises:48:12)
    at [nodejs.internal.kHybridDispatch] (node:internal/event_target:816:20)
    at AbortSignal.dispatchEvent (node:internal/event_target:751:26)
    at runAbort (node:internal/abort_controller:410:10)
    at abortSignal (node:internal/abort_controller:396:3)
    at AbortController.abort (node:internal/abort_controller:428:5)
    at file://[ciach]/test.ts:11:17
    ... 2 lines matching cause stack trace ...
    at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:116:5) {
  code: 'ABORT_ERR',
  [cause]: DOMException [AbortError]: This operation was aborted
      at new DOMException (node:internal/per_context/domexception:53:5)
      at AbortController.abort (node:internal/abort_controller:427:18)
      at file://[ciach]/test.ts:11:17
      at ModuleJob.run (node:internal/modules/esm/module_job:268:25)
      at async onImport.tracePromise.__proto__ (node:internal/modules/esm/loader:543:26)
      at async asyncRunEntryPointWithESMLoader (node:internal/modules/run_main:116:5)
}

Node.js rzucił w tym wypadku AbortError, który jako swoją przyczynę (Error#cause) wskazał na przyczynę przerwania przekazaną do sygnału (AbortSignal#reason). Spróbujmy zatem nieco poprawić zachowanie naszego setTimeout():

async function setTimeout( delay: number, { signal }: SetTimeoutOptions = {} ): Promise<void> {
	return new Promise( ( resolve, reject ) => {
		const timeoutId = globalThis.setTimeout( resolve, delay );

		if ( signal !== undefined ) {
			signal.addEventListener( 'abort', () => {
				clearTimeout( timeoutId );
				reject( signal.reason ); // 1
			} );
		}
	} );
}

Tak naprawdę nie potrzebujemy dodatkowego owijania we własny AbortError, możemy skorzystać bezpośrednio z AbortSignal#reason. Co też robimy (1). I to w sumie jedyna zmiana. Jeśli teraz odpalimy nasz kod, zauważymy, że powód odrzucenia obietnicy się zmienił – teraz jest to błąd typu DOMException z komunikatem signal is aborted without reason (testowane w Chrome).

Jest jeszcze jedna sytuacja, którą powinniśmy wziąć pod uwagę: co jeśli do setTimeout() zostanie przekazany już “wykorzystany” sygnał? Może to nastąpić, gdy AbortController#abort() zostało wywołane przed wywołaniem setTimeout(). Obsługa zdarzenia abort tego nie wykryje, bo ono jest w stanie wykryć jedynie przerwanie tu i teraz (tak samo jak np. zdarzenie click nie zareaguje na kliknięcie sprzed 10 minut). Na szczęście istnieje własność AbortSignal#aborted, która informuje o stanie sygnału:

async function setTimeout( delay: number, { signal }: SetTimeoutOptions = {} ): Promise<void> {
	return new Promise( ( resolve, reject ) => {
		if ( signal?.aborted ) { // 1
			reject( signal.reason ); // 2

			return; // 3
		}

		[…]
	} );
}

Na samym początku naszej obietnicy dodajemy sprawdzenie, czy własność signal.aborted jest prawdą (1). Stosuję tutaj operator opcjonalnego łańcuchowania (ang. optional chaining operator) dla zwięzłości zapisu. Jeśli ta własność jest prawdą, odrzucam obietnicę (2) i przerywam dalsze działanie funkcji przez return (3).

Teraz możemy przetestować działanie nowej wersji setTimeout():

const abortController = new AbortController();
const { signal } = abortController;

abortController.abort();
setTimeout( 1000, { signal } );

Na początku tworzymy AbortController (1), wyciągamy z niego sygnał (2), a następnie wywołujemy abortController.abort() (3) i dopiero potem wywołujemy setTimeout() i przekazujemy do niego sygnał (4). Po uruchomieniu tego kodu powinniśmy zobaczyć w konsoli znany już nam błąd DOMException.

Skoro obsługę AbortControllera w setTimeout() mamy już za sobą, pora zająć się setInterval():

async function* setInterval(
	tick: number,
	options: SetTimeoutOptions = {} // 1
): AsyncIterableIterator<void> {
	while ( true ) {
		yield setTimeout( tick, options ); // 2
	}
}

Zmiana na dobrą sprawę jest jedna. Pojawił się nowy parametr, przyjmujący ten sam obiekt opcji co w przypadku setTimeout() (1). Ten parametr przekazujemy dalej do setTimeout() (2)… i to w sumie tyle. Całą obsługą AbortControllera zajmuje się setTimeout().

Przetestujmy naszą nową wersję setInterval():

const abortController = new AbortController(); // 1
const { signal } = abortController; // 2

try { // 4
	for await ( const _ of setInterval( 1000, { signal } ) ) { // 3
		console.log( 'tick' ); // 5
		abortController.abort(); // 6
	}
} catch ( e ) {
	console.log( e.message );
}

Standardowo już tworzymy AbortControllera (1) i wyciągamy z niego sygnał (2). Następnie tworzymy pętlę for await...of z setInterval()a, do którego przekazaliśmy sygnał (3). Całą pętlę dodatkowo otaczamy blokiem try/catch (4), żeby wyłapać odrzucenie obietnicy. W samej pętli najpierw wyświetlamy 'tick' (5), a następnie wywołujemy abortController.abort() (6). Zgodnie z tą logiką powinniśmy zobaczyć w konsoli tylko jeden napis 'tick', a potem – błąd DOMException. I, jeśli wywołamy powyższy kod, to dokładnie tak się stanie!

Co z clearTimeout()/clearInterval()?

Obecnie cała nasza obsługa błędów jest oparta o AbortController. Niemniej natywne API posiada dwie funkcje służące do anulowania odliczania i interwałów. Zastanówmy się, czy da się je jakoś zaadaptować na potrzeby nowego API.

Zacznijmy od clearTimeout(). Funkcja ta pozwala anulować odliczanie przy pomocy unikatowego identyfikatora, który jednoznacznie identyfikuje odliczanie. W naszym przypadku również można taki identyfikator znaleźć – może być nim obietnica zwrócona przez setTimeout(). W przypadku clearInterval() można próbować identyfikować przy pomocy asynchronicznego generatora i na tej podstawie anulować poszczególne odliczania. Niemniej uważam, ze jest to niepotrzebne kombinowanie – AbortController dostarcza wygodniejszy i potężniejszy mechanizm anulowania poszczególnych odliczań i interwałów. Dlatego też pozwolę sobie pominąć obydwie te funkcje.

Lepszy format czasu

Trzecim wymienionym przeze mnie problemem był nieprzyjazny format czasu. Czasomierze akceptują bowiem wyłącznie liczbę milisekund, a ja chciałbym podawać czas w bardziej przystępnym, tekstowym formacie:

99h55m33s124ms

Format ten jest luźną adaptacją formatu czasu trwania ze specyfikacji HTML.

Równocześnie jestem w stanie wyobrazić sobie, że część osób będzie go uważać za mniej czytelny od podawania liczby milisekund, więc starszy sposób również powinien być wspierany. Zmieńmy zatem odpowiednio pierwszy parametr naszych czasomierzy:

type Hours = `${ number }h`; // 6
type Minutes = `${ number }m`; // 7
type Seconds = `${ number }s`; // 8
type MiliSeconds = `${ number }ms`; // 9
type Delay = // 3
| number // 4
| Exclude< // 6
	`${ Hours | ''}${ Minutes | '' }${ Seconds | '' }${ MiliSeconds | ''}`, // 5
	''
>;

async function setTimeout(
	delay: Delay, // 1
	{ signal }: SetTimeoutOptions = {}
): Promise<void> {
	[…]
}

async function* setInterval(
	tick: Delay, // 2
	options: SetTimeoutOptions = {}
): AsyncIterableIterator<void> {
	[…]
}

Zarówno w setTimeout() (1), jak i setInterval() (2), typ pierwszego parametru zmienił się z number na Delay (3). Ten typ może przyjąć dwie postaci – albo liczby (4), albo mocno skomplikowanego ciągu znaków (5), który dodatkowo owinięty jest w Exclude<> (6). Zatrzymajmy się na moment przy tym typie.

W TypeScripcie istnieje coś takiego jak typy szablonowe literałów (ang. template literal types). W dużym skrócie są niejako odpowiednikiem szablonowych ciągów znaków z JS-a. Różnica polega na tym, że gdy w JS-ie możemy w takie ciągi wsadzać zmienne, tak w TS-ie – inne typy. Dlatego też do naszego typu wsadziliśmy typy oznaczające godziny (6), minuty (7), sekundy (8) i milisekundy (9). Jak widać, to też są template literal types, ale prostsze:

type Hours = `${ number }h`;

W tym przypadku typ Hours oznacza ciąg, w którym znajduje się dowolna liczba, po której następuje literka h. Typy dla poszczególnych jednostek czasu wyglądają podobnie, różnią się tylko, cóż, jednostką. Natomiast typ Delay łączy je wszystkie w jeden ciąg – ale każdy człon jest opcjonalny. W końcu nie wszyscy potrzebują czasomierza ustawionego w godzinach. Opcjonalność członów została uzyskana przy pomocy unii typów:

type Delay = `${ Hours | '' }`;

Każdy człon może zostać zastąpiony przez pusty ciąg znaków. Niemniej to powoduje pewien problem: skoro wszystkie człony są opcjonalne, to ostatecznie typ Delay dopuszcza także pusty ciąg znaków (''). I tutaj przydaje się typ Exclude<>, dzięki któremu odfiltrowujemy z naszego Delay pusty ciąg znaków. Ostatecznie więc otrzymujemy listę wszystkich możliwych kombinacji jednostek czasu.

Innymi słowy, typ Delay można zapisać też jako:

type Delay =
| number
| `${number}h`
| `${number}m`
| `${number}s`
| `${number}ms`
| `${number}s${number}ms`
| `${number}m${number}ms`
| `${number}m${number}s`
| `${number}m${number}s${number}ms`
| `${number}h${number}ms`
| `${number}h${number}s`
| `${number}h${number}s${number}ms`
| `${number}h${number}m`
| `${number}h${number}m${number}ms`
| `${number}h${number}m${number}s`
| `${number}h${number}m${number}s${number}ms`

Taką też listę powinniśmy zobaczyć po najechaniu na typ w edytorze kodu/IDE. I choć można by ten typ zapisać tak w kodzie, wydaje mi się, że sposób z Exclude<> + osobnymi typami dla poszczególnych jednostek czasu jest mimo wszystko czytelniejszy. Acz zdecydowanie bardziej sprytny i wymagający nieco przetrawienia.

Skoro mamy już typ parametru, teraz pora go obsłużyć. Z racji tego, że wewnątrz setInterval() jedynie go przekazujemy do wnętrza setTimeout(), zajmijmy się od razu tą drugą funkcją:

async function setTimeout(
	delay: Delay,
	{ signal }: SetTimeoutOptions = {}
): Promise<void> {
	return new Promise( ( resolve, reject ) => {
		[…]

		const delayInMs = convertDelayToMs( delay ); // 1
		const timeoutId = globalThis.setTimeout( resolve, delayInMs ); // 2

		[…]
	} );
}

Pojawiła się nowa zmienna, delayInMs, która przechowuje wynik wywołania funkcji convertDelayToMs() (1). Tę zmienną przekazujemy jako czas do natywnego setTimeout() (2).

Natomiast sama funkcja convertDelayToMs() wygląda następująco:

interface DelayGroups { // 13
	hours?: Hours;
	minutes?: Minutes;
	seconds?: Seconds;
	miliseconds?: MiliSeconds;
}

function convertDelayToMs( delay: Delay ): number { // 1
	if ( typeof delay === 'number' ) { // 2
		return delay; // 3
	}

	const delayRegex = /^(?<hours>\d+h)?(?<minutes>\d+m(?!s))?(?<seconds>\d+s)?(?<miliseconds>\d+ms)?$/; // 5
	const matched = delay.match( delayRegex ); // 4
	const { hours, minutes, seconds, miliseconds } = matched.groups as DelayGroups; // 6
	let totalDelay = 0; // 7

	if ( hours !== undefined ) { // 8
		totalDelay += removeUnit( hours ) * 3600000; // 9
	}

	if ( minutes !== undefined ) {
		totalDelay += removeUnit( minutes ) * 60000;
	}

	if ( seconds !== undefined ) {
		totalDelay += removeUnit( seconds ) * 1000;
	}

	if ( miliseconds !== undefined ) {
		totalDelay += removeUnit( miliseconds );
	}

	return totalDelay; // 12
}

function removeUnit( delay: Hours | Minutes | Seconds | MiliSeconds ): number { // 10
	return Number( delay.replaceAll( /[a-z]/g, '' ) ); // 11
}

Funkcja convertDelayToMs() przyjmuje jako jedyny parametr wartość delay i zwraca liczbę (1). Na samym początku sprawdzamy, czy przekazane delay jest liczbą (2) – jeśli tak, to po prostu tę wartość zwracamy (3). W innym przypadku parsujemy argument delay (4) przy pomocy wyrażenia regularnego (5). Wyciągamy z rezultatu parsowania nazwane grupy (6). Następnie tworzymy zmienną totalDelay (7), która będzie zawierać wynik sumowania czasu. Następnie przechodzimy przez każdą wykrytą jednostkę czasu – sprawdzamy, czy została ustawiona (8), a następnie przeliczamy ją na milisekundy i dodajemy do totalDelay (9). Przy przeliczaniu musimy usunąć samą jednostkę. Do tego służy funkcja removeUnit() (10), która przyjmuje jednostkę czasu i zwraca samą jej wartość. W tym celu usuwa wszelką nieliczbową treść z przekazanej wartości, a rezultat rzutuje na liczbę (11). Gdy skończymy już dodawać poszczególne jednostki czasu do siebie, zwracamy totalDelay (12).

Wróćmy na chwilę do wyrażenia regularnego. Po pierwsze, warto zwrócić uwagę, że nazwane grupy (6) rzutowane są na typ DelayGroups (13). Domyślnie TypeScript nie typuje własności groups w wyniku parsowania ciągu wyrażeniem regularnym, dlatego trzeba to zrobić własnoręcznie. W samym wyrażeniu regularnym z kolei każda jednostka czasu jest oznaczona jako opcjonalna:

/(?<hours>\d+h)?/

Taki zapis z ? za nawiasem oznacza “dana grupa może wystąpić raz lub nie wystąpić wcale”.

Dodatkowo grupa dla minut stosuje tzw. negatywne rozglądnięcie się do przodu (ang. negative lookahead assertion), żeby przez przypadek nie złapać też milisekund:

/(?<minutes>\d+m(?!s))?/

Taki zapis oznacza “znajdź liczbę, po której następuje litera m, po której nie następuje litera s”.

Dodatkowe poprawki

Nasze API wygląda dobrze. Niemniej myślę, że można dodać jeszcze jedno usprawnienie. Obecnie zarówno setTimeout(), jak i setInterval() nie zwracają żadnej wartości w obietnicach. Zamiast tego mogą zwracać aktualny znacznik czasu (podobnie jak to robi np. requestAnimationFrame()):

async function setTimeout(
	delay: Delay,
	{ signal }: SetTimeoutOptions = {}
): Promise<number> { // 1
	return new Promise( ( resolve, reject ) => {
		[…]

		const timeoutId = globalThis.setTimeout( () => { // 3
			resolve( Date.now() ); // 4
		}, delayInMs );

		[…]
	} );
}

async function* setInterval(
	tick: Delay,
	options: SetTimeoutOptions = {}
): AsyncIterableIterator<number> { // 2
	[…]
}

Zmienił się typ zwracanych wartości funkcji – setTimeout() zwraca teraz Promise<number> (1), a setInterval() – AsyncIterableIterator<number> (2). W setTimeout() zaszła jeszcze jedna zmiana – resolve() nie jest już przekazywany bezpośrednio jako callback. Został owinięty w funkcję strzałkową (3), a do samego resolve() przekazywana jest wartość Date.now() (4).

Kolejnym usprawnieniem, jakie wprowadziłbym, jest… zmiana nazw w naszym API. Istniejące w przeglądarkach czasomierze są na tyle znane, że “podszywanie się” pod nie niekoniecznie jest dobrym pomysłem. Zwłaszcza, że nasze API działa całkowicie inaczej. Nie dość, że zmieniło się zachowanie funkcji setTimeout() i setInterval(), to dodatkowo clearTimeout() i clearInterval() nie działają w ogóle. Dlatego, żeby nie wprowadzać niepotrzebnego chaosu, nasze setTimeout() będzie nazywać się wait(), a setInterval() – tick().

Całość kodu

Ostatecznie nasz kod powinien wyglądać mniej więcej tak:

type Hours = `${ number }h`;
type Minutes = `${ number }m`;
type Seconds = `${ number }s`;
type MiliSeconds = `${ number }ms`;
type Delay =
| number
| Exclude<
	`${ Hours | ''}${ Minutes | '' }${ Seconds | '' }${ MiliSeconds | ''}`,
	''
>;

interface SetTimeoutOptions {
	signal?: AbortSignal;
}

async function wait(
	delay: Delay,
	{ signal }: SetTimeoutOptions = {}
): Promise<number> {
	return new Promise( ( resolve, reject ) => {
		if ( signal?.aborted ) {
			reject( signal.reason );

			return;
		}

		const delayInMs = convertDelayToMs( delay );
		const timeoutId = globalThis.setTimeout( () => {
			resolve( Date.now() );
		}, delayInMs );

		if ( signal !== undefined ) {
			signal.addEventListener( 'abort', () => {
				clearTimeout( timeoutId );
				reject( signal.reason );
			} );
		}
	} );
}

async function* tick(
	tick: Delay,
	options: SetTimeoutOptions = {}
): AsyncIterableIterator<number> {
	while ( true ) {
		yield wait( tick, options );
	}
}

interface DelayGroups {
	hours?: Hours;
	minutes?: Minutes;
	seconds?: Seconds;
	miliseconds?: MiliSeconds;
}

function convertDelayToMs( delay: Delay ): number {
	if ( typeof delay === 'number' ) {
		return delay;
	}

	const delayRegex = /^(?<hours>\d+h)?(?<minutes>\d+m(?!s))?(?<seconds>\d+s)?(?<miliseconds>\d+ms)?$/;
	const matched = delay.match( delayRegex );
	const { hours, minutes, seconds, miliseconds } = matched.groups as DelayGroups;
	let totalDelay = 0;

	if ( hours !== undefined ) {
		totalDelay += removeUnit( hours ) * 3600000;
	}

	if ( minutes !== undefined ) {
		totalDelay += removeUnit( minutes ) * 60000;
	}

	if ( seconds !== undefined ) {
		totalDelay += removeUnit( seconds ) * 1000;
	}

	if ( miliseconds !== undefined ) {
		totalDelay += removeUnit( miliseconds );
	}

	return totalDelay;
}

function removeUnit( delay: Hours | Minutes | Seconds | MiliSeconds ): number {
	return Number( delay.replaceAll( /[a-z]/g, '' ) );
}

Co dalej?

Udało nam się zaprojektować nowe API dla czasomierzy. W następnym odcinku spróbujemy z tego skleić profesjonalny pakiet npm!

Czym są czasomierze?

Czasomierze (liczniki czasu, timery) to przeglądarkowe API, które służy do odliczania czasu. Jest dokładnie opisane w specyfikacji HTML i składa się z czterech globalnych funkcji:

• setTimeout() – służącej do jednorazowego odliczenia czasu i wykonania po tym czasie jakiejś czynności,
• setInterval() – służącej do wykonywania jakiejś czynności co określony czas,
• clearTimeout() – służącej do anulowania odliczania czasu rozpoczętego przy pomocy setTimeout(),
• clearInterval() – służącej do anulowania odliczania czasu rozpoczętego przy pomocy setInterval().

Przy ustawianiu czasomierza należy podać czynność, którą chcemy wykonać, oraz czas, po jakim ma zostać wykonana (w przypadku setTimeout()), lub odstęp między poszczególnymi wykonaniami czynności (w przypadku setInterval()):

setTimeout( () => {
	console.log( 'timeout' ); // 2
}, 5000 ); // 1

setInterval( () => {
	console.log( 'tik' ); // 4
}, 1000 ); // 3

W przypadku setTimeout() chcemy, żeby po 5 sekundach (1) wyświetlił się w konsoli napis 'timeout' (2). W przypadku setInterval() z kolei chcemy, żeby co sekundę (3) wyświetlał się w konsoli napis 'tik' (4). Warto przy tym zwrócić uwagę na dwie rzeczy. Pierwsza z nich to fakt, że czas należy podać w milisekundach. Druga to fakt, że nie ma gwarancji, że czasomierz dokładnie odmierzy podany czas. Przeglądarka zagwarantuje jedynie, że odmierzy co najmniej tyle, ile jej kazano – a więc co najmniej 5 sekund w przypadku setTimeout() oraz co najmniej sekundę w przypadku setInterval(). Zależy to od wielu czynników, m.in. od tego, czy przeglądarka ma akurat “wolne”, czy procesor nie jest zajęty przez coś innego, czy okno przeglądarki jest sfocusowane, itd.

Zarówno setTimeout(), jak i setInterval() zwracają id, które może być następnie użyte w clearTimeout() i clearInterval():

const timeoutId = setTimeout( timeoutHandler, 5000 );
const intervalId = setInterval( intervalHandler, 1000 );

clearTimeout( timeoutId );
clearInterval( intervalId );

Żeby nie było za prosto, clearTimeout() zadziała też dla czasomierza stworzonego przez setInterval(), a clearInterval() – dla czasomierza stworzonego przez setTimeout(). Wynika to z tego, że standard przewiduje wspólną kolejkę dla obydwu typów czasomierzy.

Choć czasomierze są API przeglądarkowym, są na tyle użyteczne, że pojawiły się także w pozostałych środowiskach uruchomieniowych JS-a: Node, Bunie i Deno. Niemniej implementacje czasomierzy między przeglądarkami a resztą środowisk mogą się nieco różnić. Dlatego w tym artykule skupiam się głównie na przeglądarkach.

Istniejące problemy

Tak po prawdzie czasomierze nie zmieniły się od czasu swojego powstania. A to oznacza, że ominął je szereg rewolucji i ewolucji, jakie zaszły w JS-owym ekosystemie przez ostatnie, cóż, dekady. Osobiście widzę trzy główne problemy:

• przestarzałe podejście do asynchroniczności,
• brak współpracy z AbortControllerem,
• nieprzyjazny format czasu.

Przyjrzyjmy się pokrótce każdemu z tych problemów.

Przestarzałe podejście do asynchroniczności

ES2015 przyniosło prawdziwą rewolucję związana ze zmianą podejścia do asynchroniczności w JS-ie. Polegała ona na odejściu od funkcji zwrotnych (callbacks) na rzecz obietnic (Promise). Zmianę tą bardzo ładnie widać na przykładzie API w Node, np. do odczytywania zawartości pliku. Starsza, callbackowa wersja (fs.readFile()) doczekała się obietnicowego odpowiednika (fsPromises.readFile()):

import { readFile as readFileCallback } from 'node:fs'; // 1
import { readFile as readFilePromise } from 'node:fs/promises'; // 2

readFileCallback( '/jakis-plik', 'utf-8', ( err, data ) => { // 3
	console.log( data ); // 4
} );

const data = await readFilePromise( '/jakis-plik', 'utf-8' ); // 5

Starą wersję APi importujemy jako readFileCallback() (1), natomiast nową – readFilePromise() (2). Stara wersja przyjmuje trzy parametry (3): ścieżkę do pliku, opcje (w tym przypadku podajemy samo kodowanie pliku) oraz callback. W callbacku wyświetlamy odczytaną zawartość pliku (4). W przypadku obietnicowego API całość sprowadzona jest do jednej linijki (5). Sama funkcja przyjmuje też tylko dwa parametry – wszak callback nie jest potrzebny. Dzięki zastosowaniu tutaj top-level await przypisujemy zawartość pliku do zmiennej data – dokładnie tak, jakbyśmy zrobili to w przypadku synchronicznego kodu.

Podobny proces zaszedł w przypadku sporej liczby technologii przeglądarkowych, np. oparty na obietnicach fetch() w wielu wypadkach wyparł stare, oparte na zdarzeniach API XMLHttpRequest. Obietnice, zwłaszcza w połączeniu z top-level await, pozwalają na pisanie kodu asynchronicznego w bardzo podobny sposób, jak kodu synchronicznego. Nie mamy już więcej do czynienia z tzw. piekłem callbacków, kod jest płaski.

Niemniej w przypadku czasomierzy jedyną dostępną opcją są właśnie callbacki, przez co jesteśmy zmuszani do zagnieżdżania kodu. Co więcej, w przypadku nowoczesnego asynchronicznego kodu, opartego na Promise, mieszanie go z callbackami jest najzwyczajniej w świecie niewygodne:

await someAsyncAction(); // 1

setTimeout( async () => { // 3
	await someOtherAsyncAction();
	await yetAnotherAsyncAction();
}, 1000 ); // 2

Na początku wywołujemy jakąś asynchroniczną akcję (1). Kolejne dwie muszą być wywołane po jednej sekundzie odstępu (2). To sprawia, że muszą zostać przeniesione do wewnątrz wywołania setTimeout() (3). W momencie, gdy później pojawić musiałby się kolejny czasomierz, całość zrobiłaby się jeszcze bardziej zagnieżdżona.

Najczęściej taka sytuacja kończy się napisaniem jakiejś pomocniczej funkcji, która otaczałaby callbackowy kod w obietnicę:

await someAsyncAction(); // 1
await wait( 1000 ); // 2
await someOtherAsyncAction(); // 3
await yetAnotherAsyncAction();

async function wait( time ) { // 4
	return new Promise( ( resolve ) => { // 5
		setTimeout( resolve, time ); // 6
	} );
}

Nasz kod wywołuje najpierw pierwszą asynchroniczną akcję (1), następnie naszą pomocniczą funkcję wait() (2), a następnie – resztę asynchronicznego kodu (3). Z kolei pomocnicza funkcja przyjmuje jako argument czas, który ma odliczyć (4), a następnie zwraca obietnicę (5). Wewnątrz obietnicy wywołujemy setTimeout() (6). Jako callback przekazujemy funkcję resolve() obietnicy oraz czas przekazany do samego wait(). Dzięki temu czasomierz rozwiąże obietnicę, gdy odliczanie czasu się zakończy.

Brak współpracy z AbortControllerem

Jak już kiedyś pisałem, AbortController pozwala na eleganckie przerywanie operacji asynchronicznych “z zewnątrz”. Chyba sztandarowym przykładem jest przerywanie pobierania pliku po przekroczeniu określonego czasu oczekiwania:

( async () => { // 1
	const abortController = new AbortController(); // 3
	const { signal } = abortController; // 4

	setTimeout( () => { // 5
		abortController.abort( 'timeout' ); // 7
	}, 2000 ); // 6

	try { // 2
		const response = await fetch( 'https://slowfil.es/file?type=png&delay=10000', { // 8
			signal // 9
		} );

		console.log( response ); // 10
	} catch ( err ) {
		console.error( err ); // 11
	}
} )();

Całość otoczona jest w samowywołującą się funkcję asynchroniczną (1) – wszystko z powodu bloku try/catch (2). Wewnątrz funkcji tworzymy AbortController (3) oraz wyciągamy z niego sygnał (4). Następnie tworzymy czasomierz (5) i ustawiamy go na 2 sekundy (6). Jako callback wywołujemy metodę abort() naszego AbortControllera (7). Jako powód przerwania operacji podajemy 'timeout'. Następnie, w bloku try (2), tworzymy żądanie do pliku .png (8). Korzystam tutaj z usługi Slowfil.es, która pozwala symulować powolną odpowiedź serwera poprzez ustawienie czasu odpowiedzi. W naszym wypadku obrazek zostanie zwrócony dopiero po 10 sekundach – a więc dawno po odliczeniu czasu przez czasomierz. Do fetch()a przekazujemy także sygnał jako opcję signal (9). W przypadku, gdy żądanie się powiedzie, wyświetlamy odpowiedź z serwera (10). W innym wypadku – wyświetlamy błąd (11).

Blok try/catch wymusił otoczenie całego kodu w asynchroniczną funkcję, ponieważ top-level await – jak sama nazwa wskazuje – działa tylko na najwyższym poziomie modułu. Jakiekolwiek zagłębienie jest już poniżej tego poziomu.

Jeśli uruchomimy powyższy kod, zauważymy, że po około dwóch sekundach w konsoli pojawi się błąd 'timeout', a żądanie zostanie przerwane i odpowiedź z serwera nigdy nie trafi do konsoli.

Innym ciekawym przykładem zastosowania AbortControllera jest anulowanie wielu operacji asynchronicznych naraz. Zmodyfikujmy nieco nasz przykład:

( async () => {
	const abortController = new AbortController();
	const { signal } = abortController;

	setTimeout( () => {
		abortController.abort( 'timeout' );
	}, 2000 );

	try {
		const promise1 = fetch( 'https://slowfil.es/file?type=png&delay=10000', { // 1
			signal // 4
		} );
		const promise2 = fetch( 'https://slowfil.es/file?type=png&delay=20000', { // 2
			signal // 5
		} );
		const promise3 = fetch( 'https://slowfil.es/file?type=png&delay=30000', { // 3
			signal // 6
		} );

		await Promise.all( [ // 7
			promise1,
			promise2,
			promise3
		] );

        console.log( 'Done' ); // 8
	} catch ( err ) {
		console.error( err );
	}
} )();

Większość kodu pozostała bez zmian. Zamiast jednak jednego żądania, mamy w tym wypadku trzy (1, 2, 3). Są one tworzone na początku przez przypisanie obietnic zwróconych przez fetch() do zmiennych. Do każdego wywołania fetch() przekazujemy ten sam sygnał (4, 5, 6). Następnie czekamy na wykonanie się wszystkich żądań przy pomocy Promise.all() (7). gdy wszystkie żądania się zakończą, w konsoli wyświetlamy napis 'Done' (8). Tak się jednak nie stanie, bo wszystkie żądania zostaną przerwane przez czasomierz.

Jeśli spojrzymy teraz do zakładki Network w narzędziach developerskich przeglądarki, zauważymy, że, faktycznie, żadne z trzech żądań nie zostało dokończone:

Wyobraźmy sobie jednak inną sytuację: mamy kilka czasomierzy na stronie i w momencie, gdy w jednym z nich dochodzi do błędu, reszta również powinna być anulowana. Brak obsługi AbortControllera wymusza tak naprawdę trzymanie id wszystkich czasomierzy i anulowanie ich pojedynczo:

const timeouts = [
	setTimeout( () => { // 2
		stopTimeouts(); // 5
	}, 1000 ),

	setTimeout( () => { // 3
		console.log( '#2' );
	}, 2000 ),

	setTimeout( () => { // 4
		console.log( '#3' );
	}, 3000 )
];

function stopTimeouts() {
	console.log( 'stop' );

	timeouts.forEach( ( timeout ) => { // 6
		clearTimeout( timeout ); // 7
	} );
}

Tworzymy tablicę timeouts (1), w której umieszczamy trzy wywołania setTimeout() (2, 3, 4). Dzięki temu tworzymy tablicę zawierającą id wszystkich czasomierzy. W pierwszym z nich symulujemy błąd, wywołując funkcję stopTimeouts() (5). Funkcja ta iteruje po tablicy timeouts (6) i dla każdego czasomierza wywołuje funkcję clearTimeout() (7).

I choć to rozwiązanie działa, jest zdecydowanie mniej eleganckie od obsługi przerywania asynchronicznych aplikacji przy pomocy AbortControllera. Co więcej, robi się zdecydowanie bardziej kłopotliwe w momencie, gdy przerwanie ma nastąpić gdzieś z zewnątrz – z poziomu kodu, który niekoniecznie wie (czy wręcz: powinien wiedzieć), że gdzieś są wykorzystywane czasomierze. W idealnym świecie taki zewnętrzny kod mógłby przesłać sygnał do środka funkcji z asynchroniczną operacją i, w razie potrzeby, użyć go do wymuszenia przerwania tej operacji. W przypadku czasomierzy nie da się tego zrobić bez napisania własnoręcznie tłumaczenia sygnału na odpowiednie wywołania clearTimeout().

Nieprzyjazny format czasu

To zarzut zdecydowanie mniejszego kalibru niż dwa poprzednie. Otóż, niekoniecznie lubię się z milisekundami. A dokładniej: z przeliczaniem wszystkiego na milisekundy. W przypadku sekund jeszcze jest łatwo, ale jeśli potrzeba czegoś w minutach, to już się robi kłopotliwie. Dlatego fajnie byłoby móc przekazywać do czasomierzy czas w jakimś innym formacie, np. tekstowym:

setTimeout( () => {}, '1m23s' );

Prawda, że ładniej?

Co dalej?

Skoro znamy już problemy i bolączki natywnych czasomierzy w przeglądarkach, czas pomyśleć, w jaki sposób można by je rozwiązać. Ale to już temat na kolejny wpis!