Erm…

Dzięki temu, że mamy styczeń, mamy też mnóstwo czasu na… Że co? Że jest już sierpień?!

No więc tak, projekt czasomierzy zdecydowanie zaliczył poślizg – ale hej! To raptem tylko 7 miesięcy, nie ma powodów do paniki. Wróćmy może do kodu…!

Tworzymy repozytorium

Jeśli spojrzymy na stronę przykładowego pakietu npm, np. Reacta, zauważymy, że składa się ona z dwóch części: dokumentacji pakietu oraz dodatkowych informacji o nim (instrukcji instalacji, liczby pobrań, itd.). Większość pakietów wśród tych informacji zawiera także linka do repozytorium, w którym znaleźć można ich kod źródłowy – tak jest też w przypadku Reacta. Najczęściej takie repozytorium jest hostowane na GitHubie (GH). Na dzień dzisiejszy to największe miejsce, w którym rozwijane jest oprogramowanie open source. GitHub, jak sama nazwa wskazuje, został zbudowany wokół systemu kontroli wersji git.

Z racji tego, że większość pakietów npm zaczyna się od repozytorium na GH i jest to w sumie dość wygodny sposób rozwijania oprogramowania open source, to nasze czasomierze również tam wylądują. W tym celu należy stworzyć repozytorium. W trakcie tworzenia GitHub zapyta nas o parę rzeczy:

• Nazwa repozytorium – z racji tego, że projekt nazywa się czasomierze, tak też wypada nazwać nasze repozytorium. Aczkolwiek nazwa może być całkowicie dowolna.
• Opis – krótki opis zawartości repozytorium. Można go całkowicie pominąć.
• Widoczność repozytorium – publiczne repozytoria są widoczne dla wszystkich, podczas gdy prywatne tylko dla nas i osób, które zaprosimy. W przypadku czasomierzy nie ma to większego znaczenia. Ja zwykle wybieram publiczne repozytoria, bo nie widzę potrzeby chowania kodu open source.
• Szablon – pewien czas temu GitHub dodał szablony, czyli specjalny typ repozytoriów, które można wykorzystywać jako punkt startowy do własnych projektów. W przypadku czasomierzy szablon nie jest nam potrzebny.
• Plik README – GitHub może stworzyć ten plik za nas.
• Plik .gitignore – GitHub może stworzyć za nas również ten plik. Z listy wybrać można wykorzystywaną technologię, żeby był jak najlepiej dostosowany do projektu. W naszym przypadku “Node” może się dobrze sprawdzić.
• Plik LICENSE – kolejny plik, który GitHub może wygenerować dla nas. Ja zwykle używam licencji MIT.

Gdy już stworzymy repozytorium na GitHubie, wypada je sklonować lokalnie, by móc na nim pracować:

git clone git@github.com:Comandeer/czasomierze.git

Tworzymy szkielet

Gdy już mamy repozytorium postawione, trzeba w nim dodać pewne podstawowe pliki.

.gitignore

Zacznijmy od magicznego pliku .gitignore. Zawiera on listę plików i folderów, które git ma ignorować. Takie pliki nie znajdą się w repozytorium. Zwyczajowo omija się w ten sposób np. katalog node_modules, zawierający zależności, oraz katalog zawierający zbudowaną/skompilowaną wersję projektu. Stąd na potrzeby naszego projektu wypada dodać następujące wpisy do pliku:

dist/
node_modules/

package.json

Plik package.json to podstawowy plik w każdym pakiecie npm. Zawiera wszystkie najważniejsze informacje o nim, takie jak nazwa, lista zależności, skrypty itd. Nie musimy go jednak tworzyć ręcznie, możemy wykorzystać do tego komendę npm init:

npm init --y

Komenda pyta o różne rzeczy, takie jak nazwa pakietu. Możemy to pominąc, dodając flagę --y. Informuje ona npm, że akceptujemy wszystkie sugerowane wartości. Dzięki temu powinniśmy dostać mniej więcej taki plik package.json:

{
  "name": "czasomierze",
  "version": "1.0.0",
  "description": "A simpler and friendler timers.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/Comandeer/czasomierze.git"
  },
  "keywords": [],
  "author": "",
  "license": "ISC",
  "type": "commonjs",
  "bugs": {
    "url": "https://github.com/Comandeer/czasomierze/issues"
  },
  "homepage": "https://github.com/Comandeer/czasomierze#readme"
}

Wprowadzimy do niego jednak kilka modyfikacji. Po pierwsze, pole type zmienimy z commonjs na module, a pole main zastąpimy polem exports:

{
    "exports": {
        ".": {
            "types": "./dist/index.d.ts",
            "import": "./dist/index.js"
        }
    }
}

Dodamy też pole files:

{
    "files": [
    	"dist"
    ]
}

Dzięki niemu przy publikacji pakietu zostaną opublikowane tylko pliki z katalogu dist – a więc skompilowana wersja naszej biblioteki.

A jak już mowa o skompilowanej wersji biblioteki mowa, to warto od razu zainstalować transpiler TypeScripta:

npm i -D typescript

Ta komenda zainstaluje najnowszą wersję TS-a i doda ją do zależności developerskich projektu. Potrzebujemy jeszcze skryptu, dzięki któremu zbudujemy naszą bibliotekę:

{
	"scripts": {
		"build": "tsc"
    }
}

Dzięki temu będziemy mogli wywołać komendę npm run build, która stworzy z naszych plików TS pliki JS.

Warto także dodać autora (author), słowa kluczowe (keywords) czy opis (description). Osobiście zmieniam także wersję na niższą, jak 0.0.1 czy 0.1.0. Pierwszą wersję bezpieczniej opublikować z takim eksperymentalnym numerem, zamiast psuć sobie od razu poważną wersję 1.0.0, gdyby coś poszło nie tak.

Ostatecznie nasz plik package.json powinien wyglądać mniej więcej tak:

{
  "name": "czasomierze",
  "version": "0.0.1",
  "description": "A simpler and friendler timers.",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    }
  },
  "files": [
    "dist"
  ],
  "scripts": {
    "build": "tsc"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/Comandeer/czasomierze.git"
  },
  "keywords": [
    "timers"
  ],
  "author": "Comandeer",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/Comandeer/czasomierze/issues"
  },
  "homepage": "https://github.com/Comandeer/czasomierze#readme",
  "devDependencies": {
    "typescript": "7.0.2"
  }
}

package-lock.json

Po instalacji TypeScriptu powinien pojawić się plik package-lock.json. To plik zawierający dokładne informacje o zainstalowanych zależnościach i wersjach. Na ten moment nie musimy się nim martwić, wrócimy do niego w artykule o zależnościach.

tsconfig.json

Żeby móc transpilować naszą bibliotekę, przyda się także konfiguracja TypeScriptu, którą zapiszemy w pliku tsconfig.json:

{
	"include": [
		"src/**/*"
	],
	"compilerOptions": {
		"rootDir": "./src",
		"outDir": "dist/",

		"module": "nodenext",
		"moduleResolution": "nodenext",
		"resolveJsonModule": true,
		"target": "esnext",
		"declaration": true,
		"declarationMap": true,
		"sourceMap": true,
		"skipLibCheck": true,
		"verbatimModuleSyntax": true,
		"allowImportingTsExtensions": true,
		"rewriteRelativeImportExtensions": true,

		"strict": true,
		"strictNullChecks": true,
		"exactOptionalPropertyTypes": true,
		"noImplicitOverride": true,
		"noUncheckedIndexedAccess": true,
		"noFallthroughCasesInSwitch": true,
		"noImplicitReturns": true,
		"noPropertyAccessFromIndexSignature": true
	}
}

Nie będę wchodził w szczegóły – to zdecydowanie temat na osobny artykuł. Wypada jedynie wspomnieć, że pole include zawiera listę plików, które mają zostać stranspilowane, natomiast opcja compilerOptions.outDir – ścieżkę do katalogu, w którym mają być zapisane wygenerowane pliki JS.

src/index.ts

To plik zawierający kod naszych czasomierzy! To niemal ten sam kod, co w poprzednim artykule:

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;
}

export async function wait( // 1
	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 );
			} );
		}
	} );
}

export async function* tick( // 2
	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, '' ) );
}

Pojawiła się w nim tylko jedna, mała zmiana: funkcje wait() (1) i tick() (2) są eksportowane. Dzięki temu, gdy ktoś zainstaluje nasz pakiet, będzie mógł go użyć w swoim kodzie:

import { wait, tick } from 'czasomierze';

await wait( '5s' );

for await ( const _ of tick( 1000 ) ) {
    console.log( 'tick' )
}

Skoro już mamy plik z kodem, to możemy przy okazji przetestować, czy nasz kod poprawnie się transpiluje. W tym celu wystarczy wywołać polecenie:

npm run build

Jeśli wszystko pójdzie dobrze, powinien pojawić się katalog dist, a w nim plik index.js z kodem JS naszej biblioteki.

README.md

W tym pliku znajduje się opis projektu wraz z podstawową dokumentacją. To jego zawartość widać zarówno na npm-ie, jak i GitHubie. Dobrze więc, żeby był jak najbardziej czytelny i zawierał wszystkie potrzebne informacje. Osobiście stosuję taki szablon:

# <nazwa pakietu

<informacyjne tarcze>

<Opis projektu w jednym zdaniu>

## Installation

```bash
npm install <nazwa pakietu>
```

## Usage

<Przykład użycia, najlepiej z kodem>

<Dodatkowe sekcje z potrzebnymi informacjami>

## License

See [LICENSE](./LICENSE) file for details.

Dla czasomierzy plik README.md może wyglądać następująco:

# czasomierze

Simpler and friendler timers.

## Installation

```bash
npm install czasomierze
```

## Usage

```typescript
import { wait, tick } from 'czasomierze';

await wait( 5000 ); // Waits for 5 seconds
await wait( '10m' ) // waits 10 minutes

for await ( const _ of tick( '1s' ) ) {
	console.log( 'tick' ); // Logs in 1 second intervals
}
```

## License

See [LICENSE](./LICENSE) file for details.

{% note %}

Choć nie ma obowiązku tworzenia pliku README.md w języku angielskim, to jednak jest on de facto standardem w branży. Jeśli chcemy dodać także informacje w innym języku, można stworzyć dodatkowe pliki README-<kod języka>.md, np. README-pl.md dla języka polskiego.

{% endnote %}

LICENSE

Ten plik zawiera treść licencji, na której rozprowadzamy nasze oprogramowanie. Osobiście w większości przypadków wybieram licencję MIT. Z kolei npm proponuje domyślnie licencję ISC – która jest praktycznie tożsama z MIT. Strona Choose an open source license zawiera więcej licencji przeznaczonych dla projektów open source.

Licencje open source to oczywiście niejedyny możliwy wybór. Niektóre pakiety npm są na licencjach komercyjnych (wówczas najczęściej nie linkują też do repozytorium z kodem). Coraz popularniejsze robią się także licencje typu source-available, które np. mogą mieć dodatkowe ograniczenia dotyczące komercyjnego wykorzystania kodu.

CONTRIBUTING.md

Ten plik zawiera informacje dla osób, które chcą dołączyć do projektu. Powinien wskazywać, w jaki sposób zakładać nowe issues, jakie wymogi muszą spełniać PR-y, jaki styl kodu jest używany w projekcie, itd. Jeśli nasz projekt jest małym, prywatnym projektem, to raczej można się obejść bez tego pliku. Natomiast jeśli chcemy go rozwijać na większą skalę, to taki plik warto dodać prędzej niż później.

CHANGELOG.md

Jeśli ktoś chce się szybko zorientować, co zmieniło się w naszej bibliotece, najczęściej zagląda właśnie do pliku CHANGELOG.md. Ten plik w czytelny sposób powinien opisywać, jakie rzeczy zmieniły się w poszczególnych wersjach. Jest wiele przyjętych formatów tego pliku, ja osobiście stosuję Keep a Changelog:

# czasomierze Changelog

All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](http://keepachangelog.com/)
and this project adheres to [Semantic Versioning](http://semver.org/).

---

## 0.1.0
### Added
* First working version, yay!

.github

W tym katalogu znajdują się ustawienia społecznościowe GitHuba, pozwalające zmienić np. szablony dla nowych issues czy szablon dla nowych PR-ów. Można w nim także umieścić wspomniany już plik CONTRIBUTING.md.

.editorconfig

Ten plik zawiera ustawienia dla edytora kodu w formacie EditorConfig. Format ten jest rozpoznawany przez wiele różnych edytorów (niektóre wymagają rozszerzeń, jak np. VSC). Dzięki niemu można ustawić m.in. preferowany styl nowych linii czy szerokość i styl wcięć. Mój standardowy plik .editorconfig wygląda następująco:

root = true

# Unix-style newlines with a newline ending every file
[*]
end_of_line = lf
insert_final_newline = true
indent_style = tab
indent_size = 4

[*.yml]
indent_style = space
indent_size = 2

[package.json]
indent_style = space
indent_size = 2

.nvmrc

Jeśli mamy zainstalowaną tylko jedną wersję Node’a na komputerze, ten plik nie jest nam do niczego potrzebny. Niemniej, gdy pracuje się nad kilkoma projektami równocześnie, bardzo szybko się okazuje, że różne projekty potrzebują różnych wersji Node. I tutaj na pomoc przychodzą managery wersji Node’a. Osobiście stosuję nvm, stąd plik konfiguracyjny .nvmrc. W przypadku naszego projektu można skonfigurować nvm, żeby zawsze używał najnowszej dostępnej wersji Node’a:

node

.gitattributes

Plik .giattributes ustawia atrybuty dla wybranych plików. Na ten moment nie będziemy się wgłębiać, co to dokładnie oznacza – na to przyjdzie czas w osobnym artykule. Na potrzeby naszego projektu starczy nam taki plik .gitattributes:

* text=auto
*.js eol=lf
*.ts eol=lf

Podsumowanie

Nasz szkielet powinien wyglądać mniej więcej tak:

| - .github/
|   | - ISSUE_TEMPLATE.md
|   | - PULL_REQUEST_TEMPLATE.md
| - src/
|   | - index.ts
| - .editorconfig
| - .gitattributes
| - .gitignore
| - .nvmrc
| - CHANGELOG.md
| - CONTRIBUTING.md
| - LICENSE
| - package-lock.json
| - package.json
| - README.md
| - tsconfig.json

Możemy go teraz scomiitować i wypchnąć do repozytorium:

git add . && git commit -m "chore: Add skeleton" && git push origin main

I tym oto sposobem nasze repozytorium zawiera działający zalążek pakietu npm!

Co dalej?

Postawiliśmy repozytorium na GitHubie i ogarnęliśmy szkielet pakietu npm. Dalszą pracę rozbijemy na zdecydowanie mniejsze etapy (totalnie nie po to, żeby łatwiej mi się pisało posty…). W następnych odcinkach przyglądniemy się bliżej niektórym plikom w repozytorium, dodamy testy i lintery, a na końcu – opublikujemy paczkę w npmie!

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).

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!