Początkowe rozczarowanie

Jak przystało na porządnego użytkownika dowolnego frameworka, ochoczo kliknąłem przycisk Get started. Jednak w miarę czytania mój entuzjazm powoli opadał. Pierwszym problemem był wykorzystany technologiczny stos. Cosmic UI opierało się na Ark UI, Reakcie i Tailwindzie, z dodatkiem Zaga do bardziej złożonych komponentów. Zatem na technologiach, których raczej nie użyłbym do małego, pobocznego projektu. Jednak o wiele większym problemem był fakt, że… Cosmic UI nie było pakietem npm.

Żeby zainstalować dowolny komponent, należy skopiować jego kod z dokumentacji i wkleić do swojego projektu. Niemniej komponenty zależą od siebie nawzajem i żeby mieć ładne przyciski, muszę tak naprawdę najpierw zainstalować komponent ramki. A żeby zainstalować komponent ramki, muszę dokładnie przeczytać jego dokumentację, bo przy okazji wymaga on instalacji paczki do renderowania SVG. W tym momencie zapaliła mi się czerwona lampka, ale postanowiłem ją zignorować. W końcu to naprawdę są ładne komponenty, nie może być aż tak źle, prawda?

Odwrócona inżynieria wsteczna

Skoro nie mogłem użyć Cosmic UI w jego oryginalnej postaci, stwierdziłem, że zrobię to dobrze po swojemu. Co w tym miejscu oznacza, że zaglądnę w bebechy biblioteki i znajdę, w jaki sposób generowane są te fancy komponenty. W tym celu posłużyłem się niezwykle zaawansowanym narzędziem, służącym do inżynierii wstecznej aplikacji webowych – inspektorem elementów w Chrome. Dzięki niemu odkryłem, że sztuczka, wbrew pozorom, jest dość prosta. Za wygląd komponentów odpowiadają grafiki SVG, na które następnie naniesione zostały pozostałe elementy interfejsu. W uproszczeniu kod każdego komponentu wygląda mniej więcej tak:

<div class="component">
	<svg class="component__background">[…]</svg>
    <div class="component__content">[…]</div>
</div>

Element .component zawiera w sobie dwa elementy: grafikę SVG oraz kontener z treścią komponentu. Cały komponent jest pozycjonowany relatywnie, natomiast sama grafika – absolutnie. Dzięki temu może być użyta jako tło dla komponentu. Tę technikę (przy użyciu diva zamiast SVG) zobaczyć można na poniższym przykładzie:

Skoro więc sztuczka jest tak prosta, wystarczy wyciągnąć SVG z kodu i pora na CS-a… znaczy na poboczny projekt. Tylko pojawił się pewien problem: w repozytorium Cosmic UI nie było żadnego pliku SVG. To była druga czerwona lampka, którą zignorowałem. Zacząłem więc szperać w kodzie. Zauważyłem, że wszystkie komponenty używają komponentu Frame. On sam z kolei opisany był jako służący do wyświetlania niestandardowych ramek SVG dla pozostałych komponentów. Spojrzałem na przykład użycia:

<Frame
  className="drop-shadow-2xl drop-shadow-primary/50"
  paths={JSON.parse(
    '[{"show":true,"style":{"strokeWidth":"1","stroke":"var(--color-frame-1-stroke)","fill":"var(--color-frame-1-fill)"},"path":[["M","37","12"],["L","0% + 59","12"],["L","0% + 85","0% + 33"],["L","79","0% + 12"],["L","50% - 3","12"],["L","50% + 16","30"],["L","100% - 35","30"],["L","100% - 16","47"],["L","100% - 16","100% - 47.05882352941177%"],["L","100% - 8","100% - 44.85294117647059%"],["L","100% - 9","100% - 16.666666666666668%"],["L","100% - 17","100% - 14.705882352941176%"],["L","100% - 17","100% - 30"],["L","100% - 34","100% - 12"],["L","50% + 13","100% - 12"],["L","50% + 15","100% - 26"],["L","50% - 11","100% - 12"],["L","37","100% - 12"],["L","19","100% - 30"],["L","19","0% + 50.490196078431374%"],["L","10","0% + 48.529411764705884%"],["L","10","0% + 20.098039215686274%"],["L","0% + 19.000000000000004","0% + 18.38235294117647%"],["L","19","29"],["L","37","12"]]},{"show":true,"style":{"strokeWidth":"1","stroke":"var(--color-frame-2-stroke)","fill":"var(--color-frame-2-fill)"},"path":[["M","50% + 10","15"],["L","50% + 19","15"],["L","50% + 24","0% + 20"],["L","50% + 16","0% + 20"],["L","50% + 10","15"]]},{"show":true,"style":{"strokeWidth":"1","stroke":"var(--color-frame-3-stroke)","fill":"var(--color-frame-3-fill)"},"path":[["M","50% + 25","15"],["L","50% + 34","15"],["L","50% + 40","0% + 21"],["L","50% + 31","0% + 21"],["L","50% + 25","15"]]},{"show":true,"style":{"strokeWidth":"1","stroke":"var(--color-frame-4-stroke)","fill":"var(--color-frame-4-fill)"},"path":[["M","50% + 40","15"],["L","50% + 52","15"],["L","50% + 61","0% + 23"],["L","50% + 49","0% + 23"],["L","50% + 40","15"]]},{"show":true,"style":{"strokeWidth":"1","stroke":"var(--color-frame-5-stroke)","fill":"var(--color-frame-5-fill)"},"path":[["M","36","3"],["L","0% + 58","0"],["L","0% + 84","0% + 40"],["L","81","0% + 0"],["L","50% - 1","4"],["L","50% + 5","6"],["L","50% + 54","7"],["L","50% + 74","23"],["L","100% - 32","21"],["L","100% - 8","42"],["L","100% - 9","100% - 52.450980392156865%"],["L","100% + 0","100% - 50.245098039215684%"],["L","100% + 0","100% - 15.196078431372548%"],["L","100% - 7","100% - 13.480392156862745%"],["L","100% - 7","100% - 27"],["L","100% - 29","100% - 3"],["L","50% + 14","100% + 0"],["L","50% + 21","100% - 31"],["L","50% - 13","100% + 0"],["L","37","100% - 4"],["L","11","100% - 28"],["L","10","0% + 55.3921568627451%"],["L","0","0% + 52.94117647058823%"],["L","1","0% + 18.627450980392158%"],["L","11","0% + 16.666666666666668%"],["L","11","25"],["L","36","3"]]}]'
  )}
/>

I wówczas zrozumiałem, czemu w całym repozytorium nie było plików SVG. Te były bowiem dynamiczne renderowane dla każdego komponentu osobno przy pomocy wspomnianego już wcześniej renderera SVG, pakietu npm @left4code/svg-renderer. Każdy komponent dostawał tablicę ścieżek SVG, które następnie były mielone do faktycznych SVG. Co więcej, sposób działania biblioteki oznaczał, że każdy komponent, który trafiał ostatecznie do przeglądarki, miał swoją kopię takiego SVG. Zatem jeśli na stronie było 50 przycisków, oznaczało to, że każdy z tych przycisków ma swoje SVG. Wisienką na torcie jest fakt, że taka tablica ścieżek jest ciągiem tekstowym, wsadzonym do JSON.parse(), co – bez żadnego wyraźnego powodu – sprawia, że całość jest całkowicie niesformatowana w edytorze kodu.

To była trzecia czerwona lampka i fakt, że ją zignorowałem, skłania mnie do refleksji, czy aby nie jestem masochistą. Postanowiłem bowiem wyciągnąć te ścieżki z kodu i stworzyć z nich pliki SVG samodzielnie.

Ramki zagłady

W celu ekstrakcji ramek postanowiłem napisać skrypt… w Pythonie. Bo jak się już bawić, to na całego!

Sprytny plan

Plan był dość prosty:

1. Ściągnąć repozytorium Cosmic UI.
2. Przy pomocy skryptu wyszukać wszystkie pliki komponentów.
3. Znaleźć w nich ścieżki.
4. Zmielić ścieżki do elementów path.
5. Wygenerować sprite’a SVG i zapisać go do pliku.

Stwierdziłem, że repozytorium ściągnę ręcznie, zatem skrypt musiał poprawnie wykonać kroki 2-5. Nie zostało nic innego, jak go napisać.

Wyszukiwanie plików komponentów

Krótki rzut oka na repozytorium Cosmic UI powiedział mi, że pliki z poszczególnymi komponentami są ulokowane w katalogu src/components/ui. Wystarczyło zatem, żeby skrypt do niego wszedł i pobrał listę wszystkich plików .tsx. Ale żeby było ładniej, zadecydowałem przy tym, że ścieżka do katalogu ze ściągniętym repozytorium będzie przekazywana jako argument do pythonowego skryptu.

W Pythonie istnieje klasa ArgumentParser w module argparse. Pozwala ona tworzyć proste aplikacje CLI, które przyjmują argumenty. Wykorzystajmy ją do obsługi przekazywania ścieżki:

from argparse import ArgumentParser # 1

def parse_arguments(): # 2
	arg_parser = ArgumentParser( # 3
		prog = 'Extract SVGs', # 4
		description = 'Extract SVGs from Cosmic UI', # 5
	)
	arg_parser.add_argument( 'dir' ) # 6
	args = arg_parser.parse_args() # 7

	return args # 8

def main(): # 9
	args = parse_arguments() # 10

main() # 11

Na początku importujemy klasę z odpowiedniego modułu (1). Następnie tworzymy funkcję parse_arguments() (2). W niej tworzymy nową instancję ArgumentParsera (3). Jako argumenty przekazujemy do konstruktora nazwę naszego “programu” (4) oraz jego krótki opis (5). Następnie dodajemy nowy argument, dir (6). Na samym końcu parsujemy przekazane przez terminal parametry do zmiennej args (7) i je zwracamy (8). Żeby było ładniej, stworzymy przy okazji funkcję main() (9), która będzie opakowaniem na całą logikę aplikacji. Na razie zawiera jedynie parsowanie argumentów (10). Na samym końcu wywołujemy main() (11).

Jeśli zapiszemy teraz nasz skrypt i wywołamy go w terminalu z flagą --help, zauważymy, że wyświetla się nazwa oraz opis przekazane do konstruktora ArgumentParser wraz z krótką instrukcją obsługi:

$ python ./extract-svgs.py --help

usage: Extract SVGs [-h] dir

Extract SVGs from Cosmic UI

positional arguments:
  dir

options:
  -h, --help  show this help message and exit

Ok, skoro wiemy już, jak przekazać ścieżkę do katalogu z Cosmic UI, pora wyciągnąć przy jej pomocy ścieżki do plików. W tym celu stworzymy funkcję get_component_paths(), która jako argument przyjmuje ścieżkę do katalogu z Cosmic UI:

from os.path import abspath, join as join_path, isfile # 1

[…]

def get_component_paths( dir_path: str ) -> list[str]: # 2
	cosmic_ui_path = abspath( dir_path ) # 3
	component_dir_path = abspath( join_path( cosmic_ui_path, 'src/components/ui' ) ) # 4
	component_paths = list( # 5
		filter( # 6
			lambda path: isfile( path ), # 7
			map( # 8
				lambda path: abspath( join_path( components_dir_path, path ) ), # 10
				listdir( component_dir_path ) # 9
			)
		)

	)

	component_paths.append( abspath( join_path( cosmic_ui_path, 'src/pages/home.tsx' ) ) ) # 11

	return component_paths # 12

def main():
	args = parse_arguments()
	component_paths = get_component_paths( args.dir ) # 13

[…]

Na początek importujemy potrzebne funkcje z modułu os.path (1). Następnie definiujemy funkcję get_component_paths() (2), która przyjmuje ścieżkę do katalogu Cosmic UI i zwraca listę ścieżek do plików z komponentami. Przy pomocy funkcji abspath() konwertujemy ścieżkę do Cosmic UI na ścieżkę absolutną (3). To zabezpieczenie na wypadek, gdyby ktoś wywołał skrypt ze ścieżką względną (python extract-svgs.py ./cosmic-ui). Następnie dołączamy do tej ścieżki ścieżkę do katalogu src/components/ui i konwertujemy całość na ścieżkę absolutną (4). Żeby wyciągnąć listę samych komponentów, tworzymy nową listę component_paths (5), która jest wynikiem przefiltrowania (6) funkcją isfile() (7) wszystkich absolutnych ścieżek do komponentów. Ścieżki te uzyskamy poprzez zmapowanie (8) wyniku funkcji listdir() na katalogu komponentów – a więc listy wszystkich elementów wewnątrz tego katalogu – (9) na listę ścieżek absolutnych, uzyskanych poprzez dołączenie ścieżki do elementu do ścieżki katalogu komponentów i wrzucenie tego do abspath() (10). W obydwu przypadkach korzystamy z lambdy – odpowiednika funkcji strzałkowych w JS-ie. W składni JS-owej wyglądałoby to następująco:

const componentPaths = listDir( componentDirPath )
	.map( element => absPath( joinPath( componentDirPath, element ) ) )
	.filter( element => isFile( element ) )

Osobiście uważam, że zdecydowanie czytelniej niż w Pythonie.

Do tak stworzonej listy dorzucamy jeszcze plik src/pages/home.tsx (11). Robimy to, ponieważ strona główna Cosmic UI ma kilka ciekawych kształtów ramek, które nie są użyte w żadnym komponencie. Następnie zwracamy tak stworzoną listę ścieżek (12) i dorzucamy wywołanie funkcji get_component_paths() do funkcji main() (13).

Znajdowanie ścieżek

Pora na trudniejszą część zadania: znalezienie ścieżek SVG w plikach komponentów. Moją pierwszą myślą było zaprzęgnięcie do tego jakiegoś parsera TS-a z prawdziwego zdarzenia. Ale szybko odrzuciłem ten pomysł. Każde wystąpienie ścieżki SVG trzymało się bowiem takiego samego schematu:

<Frame
	paths={JSON.parse(
		'tutaj ścieżki'
	)}
/>

A to oznaczało, że można tutaj zastosować wyrażenia regularne! Ułóżmy zatem odpowiednie wyrażenie regularne:

paths={JSON.parse\(\s*'(?P<path>[^']+)'

Rozbijmy je na części:

1. paths={JSON.parse\( szuka dokładnie takiego fragmentu w kodzie; \ (znak ucieczki) przed ( ma związek z tym, że w wyrażeniach regularnych () służą do oznaczania grup;
2. \s* jest “na wszelki wypadek” i oznacza “w tym miejscu może wystąpić dowolna liczba białych znaków lub nie być żadnego”;
3. '(?P<path>[^']+)' tworzy grupę o nazwie path, w której znajduje się co najmniej jeden znak inny niż '; grupa ta jest otoczona '.

To wyrażenie powinno wyszukać wszystkie ścieżki SVG w kodzie komponentów. Dodajmy je zatem do kodu:

[…]
from re import finditer # 1

SVG_REGEX = 'paths={JSON.parse\\(\\s*\'(?P<path>[^\']+)\'' # 2

[…]

def parse_component( component_path: str ) -> list[str]: # 7
	symbols: list[str] = [] # 8

	component_content = open( component_path, mode='r' ).read() # 9
	svg_paths = finditer( SVG_REGEX, component_content ) # 10

	for path in svg_paths: # 11
		symbols.append( path.group( 'path' ) ) # 12

	return symbols # 13

def parse_components( component_paths: list[str] ) -> list[str]: # 3
	symbols: list[str] = [] # 4

	for component_path in component_paths: # 5
		symbols = symbols + parse_component( component_path ) # 6

	return symbols; # 7

def main():
	args = parse_arguments()
	component_paths = get_component_paths( args.dir )
	symbols = parse_components( component_paths ) # 14

	print( symbols )

main()

Na sam początek importujemy funkcję finditer() z modułu re (1), która pozwala na wyszukanie wszystkich dopasowań do wyrażenia regularnego w jakimś ciągu tekstowym. Następnie tworzymy zmienną SVG_REGEX (2), w której umieszczamy nasze wyrażenie regularne. Z racji tego, że jest ono umieszczone w kodzie jako zwykły ciąg tekstowy, znaki ucieczki są podwójne (zatem \\s zamiast \s itd.) – inaczej traktowane byłyby jako znaki ucieczki w ciągu tekstowym. Następnie tworzymy funkcję parse_components() (3), która przyjmuje listę ścieżek do plików komponentów i zwraca listę wyciągniętych z nich i sparsowanych ścieżek. Sparsowane ścieżki trzymamy w liście symbols (4). Docelowo ma trzymać elementy symbol , stąd nazwa. Następnie dla każdego pliku komponentu (5) wywołujemy funkcję parse_component() (6). Z uwagi na to, że parse_component() może zwrócić listę ścieżek (bo w pliku może być więcej niż jedna ścieżka), stosujemy tutaj łączenie list (nowa_lista = lista1 + lista2 – tu z kolei Python jest zdecydowanie elegantszy niż JS!). Na końcu zwracamy listę symboli.

Funkcja parse_component() (7) tworzy swoją własną listę symbols (8), a następnie otwiera plik komponentu i czyta jego treść (9), by potem wyszukać w niej ścieżek przy pomocy wyrażenia regularnego SVG_REGEX (10). Z każdej znalezionej ścieżki (11) wyciąga jedynie wartość grupy path i wrzuca ją do tablicy symbols (12), którą następnie zwraca (13). Na sam koniec dorzucamy wywołanie parse_components() do funkcji main() (14) i dorzucamy print() (15), żeby zobaczyć, czy coś się nie skrzaczyło. Naszym oczom powinna się ukazać… ściana liter i cyfr. Co na tym etapie oznacza tyle, że nasz skrypt faktycznie coś z komponentów wyciąga. Teraz pora to sparsować do sensownej postaci!

Mielenie ścieżek

Przyjrzyjmy się, co tak naprawdę siedzi w każdym komponencie Frame. Jego magiczna własność paths zawiera JSON-a mniej więcej o takim kształcie:

{
	"show": true,
	"style": {
		"style": "css"
    },
	"path": [
		[ "M", "17", "0" ]
	]
}

Nie odkryłem, co robi show, ale style i path były proste do odgadnięcia. Własność style zawiera po prostu style CSS dla danej ścieżki, natomiast path – tzw. komendy ścieżki. Krótka analiza artykułu na MDN zasugerowała mi, że powyższy kod JSON jest odpowiednikiem mniej więcej takiego SVG:

<svg xmlns="http://www.w3.org/2000/svg">
	<path d="M 17,0" style="style: css;" />
</svg>

Skoro tak, to sparsowanie tego do używalnej formy nie powinno stanowić większego problemu! Przystąpmy zatem do pracy. Na początek stwórzmy funkcję create_symbol():

[…]
import json # 1
[…]
SYMBOL_WIDTH = 100 # 14
SYMBOL_HEIGHT = 100 # 15

current_symbol = 1; # 11

[…]

def create_symbol( svg_string: str ) -> str: # 2
	global current_symbol
	paths: list[str] = [] # 3
	path_data = json.loads( svg_string ) # 4

	for path in path_data: # 5
		path_coords = create_path_commands( path[ 'path' ] ) # 6
		path_style = create_path_style( path[ 'style' ] ) # 7
		paths.append( f'<path d="{path_coords}" style="{path_style}"/>' ) # 8

	symbol = f'<symbol id="cosmic-{current_symbol}" viewBox="0 0 {SYMBOL_WIDTH} {SYMBOL_HEIGHT}">{''.join( paths )}</symbol>' # 9

	current_symbol += 1 # 13

	return symbol # 10

[…]

Na początek importujemy moduł json (1), odpowiedzialny za pracę z JSON-em. Następnie definiujemy funkcję create_symbol() (2), która będzie generować elementy symbol z poprawnymi ścieżkami. Wewnątrz niej tworzymy zmienną paths (3), która będzie przechowywać stworzone elementy path. Następnie do zmiennej path_data parsujemy przy pomocy funkcji json.loads() wyciągnięte przez nas ścieżki z komponentów (4). Dla każdej wyciągniętej ścieżki (5) tworzymy komendy ścieżki przy pomocy funkcji create_path_commands() (6) oraz style przy pomocy funkcji create_path_style() (7), a następnie na tej podstawie generujemy element path (przy pomocy f-stringu) i wsadzamy go do listy paths (8). Na samym końcu tworzymy z tego element symbol (9) i go zwracamy (10). System sprite’ów wymaga, żeby każdy symbol miał swoje id, więc tworzymy go według wzoru cosmic-<kolejna liczba>. Licznik trzymany w globalnej zmiennej current_symbol (11). Wewnątrz funkcji create_symbol() zaznaczamy jej użycie słówkiem kluczowym global (12), następnie wykorzystujemy przy tworzeniu elementu symbol (9), a potem – zwiększamy o 1 jej wartość (13). Dodatkowo każdy symbol ma określony viewbox przy pomocy zmiennych SYMBOL_WIDTH (14) i SYMBOL_HEIGHT (15) – w naszym przypadku obydwie te zmienne mają wartość 100.

Funkcję create_symbol() wsadzamy teraz do parse_component() (1):

def parse_component( component_path: str ) -> list[str]:
	symbols: list[str] = []

	component_content = open( component_path, mode='r' ).read()
	svg_paths = finditer( SVG_REGEX, component_content )

	for path in svg_paths:
		symbols.append( create_symbol( path.group( 'path' ) ) ) # 1

	return symbols

Przyjrzyjmy się jeszcze funkcjom generującym style i komendy ścieżki. Na początek create_path_style():

def create_path_style( style ) -> str:
	style_string_parts: list[str] = [] # 1

	for property, value in style.items(): # 2
		style_string_parts.append( f'{property}: {value}' ) # 3

	return ';'.join( style_string_parts ) # 4

Tworzymy listę style_string_parts, następnie dla każdej pary klucz → wartość ze słownika style (2) tworzymy nową regułę CSS (3). Na samym końcu łączymy wszystkie reguły CSS w jeden ciąg tekstowy, odgradzając poszczególne z nich średnikami (4).

Natomiast funkcja create_path_commands() prezentuje się następująco:

def create_path_commands( path ) -> str:
	commands: list[str] = [] # 1

	for command_data in path: # 2
		command_name = command_data.pop( 0 ) # 3
		x = command_data.pop( 0 ) # 4
		y = command_data.pop( 0 ) # 5

		commands.append( f'{command_name} {x},{y}' ) # 6

	return ' '.join( commands ) # 7

Tworzymy listę commands (1). Następnie z każdej komendy zapisanej w JSON-ie (2) wyciągamy jej nazwę, czyli pierwszy element listy (3), współrzędną na osi X, zatem drugi element listy (4), oraz współrzędną na osi Y, czyli trzeci element listy (5). Formatujemy to jako poprawną komendę ścieżki i wrzucamy do listy commands (6). Na końcu robimy z komend jeden ciąg tekstowy i go zwracamy (7).

Jeśli teraz uruchomimy nasz skrypt, dostaniemy gotowe do użycia elementy symbol! Dla testów możemy skopiować dowolny, opatulić go w svg i spróbować użyć:

<svg><!-- tutaj dowolny symbol --></svg>

<svg>
	<use href="#symbol-1" />
</svg>

Gdy otworzymy taki plik HTML, to okaże się, że… nie działa. A po otwarciu konsoli w Chrome wita nas piękny komunikat błędu:

Error: <path> attribute d: Expected number, "M 14,6 L 50% - 7,6 L 50% - …".

Spojrzałem zatem dokładniej w kod Cosmic UI. I wówczas odkryłem, że w JSON-ie nie do końca są ścieżki. Były tam też… działania matematyczne, takie jak 100% - 40. Pogrzebałem trochę głębiej i odkryłem, że faktyczne wartości dla ścieżek są obliczane na bieżąco, na podstawie wielkości poszczególnych komponentów. To był ten moment, w którym chciałem porzucić cały projekt, ale zainwestowałem już za dużo czasu. Nie zostało mi nic innego, jak dodać obliczenia do mojego skryptu.

Na szczęście nie okazało się to jakoś przesadnie trudne. Na sam początek trzeba zmienić funkcję create_path_commands():

def create_path_commands( path ) -> str:
	commands: list[str] = []

	for command_data in path:
		command_name = command_data.pop( 0 )
		x = calculate_coord( command_data.pop( 0 ), 'x' ) # 1
		y = calculate_coord( command_data.pop( 0 ), 'y' ) # 2

		commands.append( f'{command_name} {x},{y}' )

	return ' '.join( commands )

Teraz zmienne x i y tworzymy przez wywołanie funkcji calculate_coord(), do której przekazujemy odpowiednią wartość z listy command_data oraz oś, do której koordynat należy (1, 2).

Sama funkcja calculate_coord() przedstawia się następująco:

from re import finditer, search # 2

[…]

CALC_REGEX = '^(?P<left>\\d+(?:\\.\\d+)?%?)\\s*(?P<operator>[\\-+*/])\\s*(?P<right>\\d+(?:\\.\\d+)?%?)$' # 4

[…]

def calculate_coord( coord: str, axis: str ) -> str:
	if coord.find( '%' ) == -1: # 1
		return coord

	calculation = search( CALC_REGEX, coord ) # 3

	if calculation == None: # 5
		return coord; # 6

	left = get_coord_value( calculation.group( 'left' ), axis ) # 7
	operator = calculation.group( 'operator' ) # 8
	right = get_coord_value( calculation.group( 'right' ), axis ) # 9

	match operator: # 10
		case '-':
			return f'{int( left - right )}' # 11
		case '+':
			return f'{int( left + right )}' # 12
		case '*':
			return f'{int( left * right )}' # 13
		case '/':
			return f'{int( left / right )}' # 14

Na sam początek sprawdzamy, czy koordynat zawiera znak % (1). Jeśli nie, zwracamy przekazany koordynat bez zmian (Cosmic UI zawsze stosuje procenty w obliczeniach, stąd ten warunek). Następnie przy pomocy funkcji search() z modułu re (2) wyszukujemy dopasowanie (3) do wyrażenia regularnego CALC_REGEX (4) wewnątrz przekazanego koordynatu. Jeśli go nie znajdujemy (5), zwracamy koordynat bez zmian (6). W innym wypadku wyciągamy z dopasowania lewą stronę działania (7), operator (8) oraz prawą stronę działania (9). Następnie sprawdzamy, jaki mamy operator (10) i w zależności od tego, wykonujemy odpowiednie działanie – odejmowanie (11), dodawanie (12), mnożenie (13) lub dzielenie (14).

Przyjrzyjmy się jeszcze wyrażeniu regularnemu:

^(?P<left>\d+(?:\.\d+)?%?)\s*(?P<operator>[\-+*/])\s*(?P<right>\d+(?:\.\d+)?%?)$

1. ^ oznacza, że dopasowanie musi się zaczynać od początku ciągu;
2. (?P<left>\d+(?:\.\d+)?%?) to grupa oznaczająca lewą stronę działania:
   1. ?P<left> nadaje nazwę left grupie,
   2. \d+ oznacza “co najmniej jedną cyfrę”,
   3. (?:\.\d+)? oznacza “w tym miejscu może wystąpić kropka, po której następuje co najmniej jedna cyfra” (czyli liczby po przecinku),
   4. %? oznacza “w tym miejscu może wystąpić znak procenta”;
3. \s*(?P<operator>[\-+*/])\s* to operator (znak -, +, * lub /), który może być otoczony z obydwu stron białymi znakami;
4. (?P<right>\d+(?:\.\d+)?%?) to grupa oznaczająca prawą stronę działania; jest identyczna, jak dla lewej strony;
5. $ oznacza, że dopasowanie musi się kończyć na końcu ciągu; w połączeniu z ^ sprawia, że cały ciąg musi być dopasowany.

Natomiast funkcja get_coord_value() odpowiednio konwertuje każdą stronę działania:

def get_coord_value( raw_value: str, axis: str ) -> float:
	if raw_value.find( '%' ) == -1: # 1
		return float( raw_value ) # 2

	raw_number = float( raw_value.replace( '%', '' ) ) # 3

	return float( ( raw_number / 100 ) * ( SYMBOL_WIDTH if axis == 'x' else SYMBOL_HEIGHT ) ) # 4

Jeśli przekazany ciąg nie zawiera znaku % (1), wówczas konwertujemy go na liczbę zmiennoprzecinkową i zwracamy (2). W innym wypadku usuwamy z liczby znak procenta i konwertujemy ją na liczbę zmiennoprzecinkową (3). Następnie konwertujemy procenty na odpowiednią wartość (4):

1. dzielimy raw_number przez 100,
2. mnożymy to przez szerokość symbolu, jeśli to koordynat dla osi X, lub przez wysokość symbolu, jeśli to koordynat dla osi Y.

Tak przekonwertowaną wartość zwracamy.

Jeśli teraz przetestujemy nasz skrypt, to otrzymamy działające symbole 🎉! Tylko że nie do końca…

Po raz kolejny zagłębiłem się w kod Cosmic UI, szukając przyczyny takiego zachowania. Intuicja podpowiadała, że coś jest nie tak z obliczeniami – ale empiryczne sprawdzenie ich dla kilku losowych komponentów pokazywało, że wszystko jest liczone poprawnie. W końcu zauważyłem pewną rzecz w komponencie dialog. A dokładniej dwie ścieżki obok siebie w JSON-ie:

[
	["L", "100% - 7", "100% - 33.33333333333332%"],
	["L", "100% - 7", "100% - 40"]
]

Wówczas doszło do mnie, na czym polega problem. Mój skrypt jak najbardziej liczył poprawnie! Problem polegał na tym, że ustawiłem wysokość i szerokość symboli na 100. Przy tych wartościach pierwsza ścieżka na osi Y miała koordynat ok. 66.7, natomiast druga – 60. Niemniej żaden komponent Cosmic UI nigdy nie miał takich małych rozmiarów! Jeśli przyjmiemy, że najmniejszy rozmiar to 150×150 (a w rzeczywistości praktycznie zawsze był większy), to wówczas drugi z tych koordynatów będzie zawsze większy. Zmieniłem zatem wielkość symbolu na 640×480 i… zaczęło działać.

Zapisanie SVG

Została zatem ostatnia część do zrobienia: zapisanie tego w postaci sprite’a SVG.

def create_svg( symbols: list[str] ) -> str: # 1
	return f'<svg xmlns="http://www.w3.org/2000/svg">{''.join( symbols )}</svg>' # 3

def save_svg( svg_content: str ) -> None: # 2
	svg_path = abspath( './cosmic.svg' ) # 5

	with open( svg_path, 'w', encoding = 'utf-8' ) as file: # 4
		file.write( svg_content ) # 6

def main():
	args = parse_arguments()
	component_paths = get_component_paths( args.dir )
	symbols = parse_components( component_paths )
	svg_content = create_svg( symbols ) # 7
	save_svg( svg_content ) # 8

Tworzymy dwie nowe funkcje – create_svg() (1), która przyjmuje listę wygenerowanych symboli i zwraca SVG jako ciąg tekstowy, oraz save_svg() (2), która przyjmuje ten ciąg i zapisuje go do pliku. Funkcja create_svg() łączy wszystkie symbole w jeden ciąg tekstowy, a następnie wkłada go do środka znacznika svg i zwraca tak stworzony ciąg (3). Z kolei funkcja save_svg() otwiera plik SVG (4) pod ścieżką ./cosmic.svg (5) i zapisuje do niego ciąg tekstowy z kodem SVG (6). Na sam koniec dorzucamy obydwie funkcje do funkcji main() (7, 8).

Tym sposobem udało nam się wyciągnąć wszystkie kształty z Cosmic UI i wygenerować sprite’a SVG. Możemy być z siebie dumni! Całość skryptu (z lekkimi zmianami względem tego postu) jest na Giście.

Smutny koniec

Gdy już się udało to wszystko zrobić, doszło do mnie, że to bez sensu… Bo z uwagi na to, jak są generowane te ramki (jako jeden duży kształt w SVG), nie są one responsywne. A to wyklucza je z większości zastosowań, jakie mógłbym dla nich mieć.

Zrobienie tak stylizowanego interfejsu w sposób w pełni responsywny jest trudne. Nie wiem, jakbym podszedł do takiego problemu. To, co mi chodzi po głowie, to podzielenie tych ramek na części, np.:

1. część dla lewego górnego rogu,
2. część dla prawego górnego rogu,
3. część dla lewego dolnego rogu,
4. część dla prawego dolnego rogu
5. powtarzalne obramowanie dla góry,
6. powtarzalne obramowanie dla dołu,
7. powtarzalne obramowanie dla lewej strony,
8. powtarzalne obramowanie dla prawej strony,
9. powtarzalny wzór tła dla środka kontenera z treścią.

Dzięki powtarzalnym obramowaniom i tłu możliwe byłoby rozciąganie faktycznej treści teoretycznie w nieskończoność – zarówno w poziomie, jak i pionie. Jedynie same rogi pozostawały zawsze takie same.

Ale Cosmic UI, niestety, nie oferuje takiego rozwiązania. No cóż, na osłodę łez zostaje przynajmniej font Orbitron, który w Cosmic UI dopełniał całości iluzji, a którego użycie raczej będzie mnie kosztowało zdecydowanie mniej pracy.

import { styleText } from 'node:util';

console.log( util.styleText( 'underline', util.styleText( 'italic', 'Podkreślony, pochylony tekst' ) ) ),

Hmm, powiedziałem łatwo i przyjemnie… A mówiąc to, mam na myśli tak naprawdę to, w jaki sposób zachowuje się Chalk:

import chalk from 'chalk';

console.log( chalk.underline.italic( 'Podkreślony, pochylony tekst' ) );

Zdecydowanie czytelniej i jakoś tak milej. No więc postanowiłem spróbować dorobić taki interfejs do natywnego wsparcia kolorków.

Kreda

Owocem mojego eksperymentu jest pakiet kreda. Używa on pod spodem moich ulubionych proxy. Czemu zdecydowałem się na ich użycie? Przyjrzyjmy się łańcuszkowi stworzonemu przez Chalk. Widzimy, że mamy tam własność underline oraz metodę italic(). Jak na razie wygląda to jak typowe zastosowanie techniki chainingu (łańcuchowania). Coś typu:

class Chalk { // 1
	underline = this; // 2

	italic() { // 3
		return this; // 4
	}
}

const chalk = new Chalk(); // 5

chalk.underline.italic( 'Jakiś tekst' ); // 6

Mamy sobie klasę Chalk (1), która ma własność underline (2) oraz metodę italic() (3). Metoda ta zwraca this (4), podobnie jak własność. Dzięki temu w momencie, gdy stworzymy sobie instancję tej klasy (5), możemy tworzyć łańcuszek (6).

Tylko że pojawia się drobny problem:

// To też działa:
chalk.italic.underline( 'Jakiś tekst' );

Innymi słowy: w Chalku każda własność może być równocześnie metodą, jeśli zajdzie taka potrzeba. I na odwrót: każda metoda to też własność. Stąd moim pierwszym skojarzeniem były proxy – one wszak pozwalają na dziwną magię w obiektach.

I faktycznie, udało mi się stworzyć prosty mechanizm, który tak się zachowuje!

const kreda = createProxy( [] ); // 2

function createProxy( modifiers ) { // 1
	return new Proxy( () => {}, { // 3
		get( target, property ) { // 4
			return createProxy( [ ...modifiers, property ] ); // 6
		},
		apply( target, thisArg, args ) { // 5
			return style( modifiers, ...args ); // 7
		}
	} );
}

Stworzyłem funkcję createProxy() (1), która jako argument przyjmuje tablicę modyfikatorów (stylów tekstu). Na samym początku jest ona pusta (2). Funkcja createProxy() zwraca Proxy (3), które ma dwie pułapki – get() (4) do obsługi własności i apply() (5) do obsługi wywołania funkcji. Warto zwrócić uwagę na to, ze proxy jest tworzone na pustej funkcji strzałkowej. Inaczej pułapka apply() nie zadziała (dostaniemy błąd, że próbujemy wywołać coś, co nie jest funkcją)

W chwili, gdy następuje odwołanie do dowolnej własności proxy, pułapka get() zwraca nowe proxy (6). Jako argument przekazuje tablicę zawierającą wszystkie obecne modyfikatory + nazwę żądanej własności (np. underline). Z kolei, gdy ktoś chce wywołać własność, odpalana jest funkcja style() (7), która jako 1. argument dostaje tablicę wszystkich modyfikatorów, a jako kolejne – poszczególne argumenty przekazane do wywołania funkcji. Przykładowo:

kreda.underline.italic( 'Test' );
// oznacza
style( [ 'underline', 'italic' ], 'Test' );

Sama zaś funkcja style() po prostu wywołuje natywną funkcję Node’a od kolorowania tekstu. Tym sposobem udało się stworzyć chalkowy łańcuszek! Jak takie coś działa, z dodatkową walidacją i kilkoma innymi ficzerami, można zobaczyć w kodzie kredy.

A jak to robi Chalk?

Magicznie ✨.

Niemniej z tego, co zrozumiałem, Chalk za każdym razem zwraca funkcję, której prototyp jest modyfikowany “na żywca” tak, aby zawierał poszczególne własności. Mniej więcej coś takiego:

const chainPrototype = Object.defineProperties( () => {}, { // 1
	property1: {
		get() { // 2
			return createChain(); // 3
		}
	},
	property2: {
		get() {
			return createChain();
		}
	}
} );

function createChain() {
	const chain = ( text ) => { // 4
		console.log( text ); // 5
	};

	Object.setPrototypeOf( chain, chainPrototype ); // 6

	return chain; // 7
}

const chain = createChain(); // 8

chain.property1.property2( 'Powinienem się wyświetlić w konsoli' ); // 9

Na początku tworzony jest prototyp dla łańcucha (1). Odbywa się to przy pomocy Object.defineProperties(). Jest ono wykorzystywane z powodu możliwości definiowania w wygodny sposób getterów. Każda własność ma getter (2), który wywołuje funkcję createChain() (3). Funkcja ta tworzy funkcję, która ostatecznie ma zostać wywołana (4). W naszym wypadku wyświetla ona jedynie przekazany tekst w konsoli (5). Następnie do prototypu tej funkcji doczepiany jest nasz prototyp łańcucha (6). Tak zmodyfikowana funkcja jest następnie zwracana (7). Łańcuchowanie zaczyna się od przypisana wyniku createChain() do zmiennej (8). Dzięki temu można dowolnie łączyć ze sobą własności i każdą z nich wywoływać jak funkcję (9).

Czemu Chalk robi to w ten sposób? Jednym z powodów jest zapewne kompatybilność takiego rozwiązania, które powinno działać od Node 0.12.0 (czyli od zawsze). Drugi powód, który przychodzi mi na myśl, to wydajność – nie zdziwiłoby mnie, gdyby rozwiązanie oparte o Proxy było wolniejsze (aczkolwiek nie robiłem benchmarków). Niemniej osobiście wydaje mi się, że chalkowe rozwiązanie ma zdecydowanie wyższy wskaźnik WTF/minuta, niźli rozwiązanie kredowe.

Wielki powrót Node’a

Stylowanie tekstu w terminalu zostało przeportowane do Node’a 20.12.0 praktycznie bez zmian. Ale weszło też do nowego Node’a 22. I tam już poprawiono ergonomię! Teraz można przekazać tablicę formatów zamiast pojedynczego formatu:

import { styleText } from 'node:util';

console.log( util.styleText( [ 'underline', 'italic' ], 'Podkreślony, pochylony tekst' ) ),

Zdecydowanie przyjemniej, ale IMO wciąż łańcuszek jest nieco czytelniejszy. Nie jest to jednak aż tak duża różnica, żeby kruszyć o to kopie. Co oznacza, że kreda raczej nie doczeka się jakichś wielkich aktualizacji, ale mimo wszystko była ciekawym eksperymentem.

Zmiana krajobrazu

Nieco ponad rok temu stworzyłem Bramkarza, po czym szybko odesłałem go na urlop. Od tamtego czasu trochę się pozmieniało w krajobrazie narzędzi do “pilnowania” kodu odpalanego w Node.js. Hagana, czyli pierwowzór Bramkarza, w sumie umarła mniej więcej w tym samym czasie i nie dostała żadnej aktualizacji od lipca tamtego roku. Natomiast pojawiło się nowe narzędzie tego typu, @sandworm/guard… mające jedno pobranie tygodniowo i zaktualizowane 9 miesięcy temu. Innymi słowy: również podzieliło los Bramkarza. Więc pod względem userlandowych rozwiązań za dużo się nie wydarzyło.

Wydarzyło się za to po stronie samego Node’a. Pojawił się bowiem eksperymentalny system uprawnień. Dzięki niemu można m.in. blokować operacje na plikach. Gdy uruchomi się Node’a z flagą --experimental-permission, domyślnie wszystkie operacje na plikach będą blokowane:

node --experimental-permission
Welcome to Node.js v20.5.0.
Type ".help" for more information.
>
Access to FileSystemWrite is restricted.
[…]
> const { readFile } = require( 'node:fs/promises' )
undefined
> await readFile( './test' )
Uncaught Error: Access to this API has been restricted
    at open (node:internal/fs/promises:595:19)
    at readFile (node:internal/fs/promises:1042:20)
    at REPL2:1:39 {
  code: 'ERR_ACCESS_DENIED',
  permission: 'FileSystemRead',
  resource: '/Users/comandeer/test'
}

Można też m.in. ograniczać URL-e, do których mają mieć dostęp poszczególne moduły. Tym samym Bramkarz jest jeszcze mniej potrzebny.

Bindingi

Niemniej przez ten rok udało mi się też rozwiązać inną zagadkę związaną z Bramkarzem. Ubolewałem mocno nad tym, że poprawne zabezpieczenie zarówno modułów CJS, jak i modułów ESM, wymaga tak naprawdę stworzenia dwóch różnych implementacji wbudowanego modułu fs. Dodatkowo wersja dla ESM była mocno upierdliwa. Okazuje się jednak, że byłem w błędzie!

W jednym ze swoich projektów używam paczki mock-fs do testów. Jej zadaniem jest stworzenie fałszywego systemu plików w pamięci, dzięki czemu ma się pełną kontrolę nad tym, jakie pliki są dostępne dla aplikacji. Myślałem, że paczka ta robi to, co ja w Bramkarzu: żmudnie nadpisuje wszystkie metody modułu fs. Spodziewałem się więc, że nie zadziała, gdy przepiszę mój kod na ESM. Ale przepisałem, a testy dalej działały… Zafrapowało mnie to i odkryłem wówczas pewien fragment w dokumentacji:

Instead of overriding all methods of the built-in fs module, the library now overrides process.binding('fs').

[Zamiast nadpisywać wszystkie metody z wbudowanego modułu fs, ta biblioteka nadpisuje teraz process.binding( 'fs' ).]

Prawdę mówiąc, nie słyszałem wcześniej o tajemniczym process.binding(), a oficjalna dokumentacja milczy na ten temat. Na całe szczęście istnieje internet i szybkie googlowanie dało mi odpowiedź. Ta niepozorna funkcja stanowi łącznik między JS-owymi częściami Node’a, a tymi napisanymi w innych językach (głównie C++). W rzeczywistości bowiem wbudowany moduł fs to JS-owa nakładka na bibliotekę do operacji na plikach napisaną w C++. I w jakiś sposób ta nakładka musi się z tym kodem w innym języku porozumiewać. Tym jest właśnie process.binding() – zwraca funkcje pozwalające na wywołanie kodu C++! I z jakiegoś powodu jest ona dostępna z poziomu użytkownika Node’a. nie jedynie z wewnątrz samego Node’a.

Co więcej, zwracany binding można do woli nadpisywać, a zmiany są widoczne dla całego procesu, omijając przy tym problem oddzielnych wersji dla ESM i CJS. Tym samym nadpisać dowolną operację na plikach można także w następujący sposób:

import { mkdir } from 'node:fs/promises'; // 4
import { binding } from 'node:process'; // 1

const fsBinding = binding( 'fs' ); // 2

fsBinding.mkdir = console.error; // 3

await mkdir( './whatever' ); // 5

Importuję funkcję binding() z wbudowanego modułu node:process, reprezentującego aktualny proces (1). Następnie zapisuję sobie do zmiennej bindingi dla modułu fs (2). Potem nadpisuję metodę mkdir() z bindingów na wywołanie console.error() (3). W ramach testów importuję funkcję mkdir() z wbudowanego modułu fs (4), po czym wywołuję ją z argumentem ./whatever (5). Warto przy tym zauważyć, że nadpisanie bindingu dla mkdir następuje po zaimportowaniu mkdir() z modułu fs.

Domyślnie funkcja mkdir tworzy nowy katalog. Jednak odpalenie powyższego kodu sprawi, że zamiast stworzyć nowy katalog, funkcja mkdir() po prostu wyświetli w konsoli argumenty przekazane jej bindingowi:

./whatever 511 false Symbol(fs_use_promises_symbol)

Co prawda rezultat, który otrzymujemy, nie do końca pokrywa się z tym, jakie parametry przyjmuje funkcja mkdir(), ale da się dość łatwo zgadnąć, który argument za co odpowiada:

• ./whatever to przekazana przez nas ścieżka do nowego katalogu,
• 511 to chmod nowego katalogu,
• false to informacja, czy katalogi mają być tworzone rekursywnie (jeślibyśmy przekazali ścieżkę typu ./whatever/innyever),
• Symbol(fs_use_promises_symbol) to oznaczenie, że wywołano obiecankową wersję funkcji mkdir().

W ten sposób udało nam się nadpisać funkcję mkdir() w trakcie działania programu. Gdybym wiedział o tym cudeńku wcześniej, to na pewno bym użył tego w trakcie pisania Bramkarza.

A tak… no cóż, kolejna cegiełka do mojej kolekcji ciekawej, acz średnio przydatnej wiedzy o JS-ie.

Zatem zrobiłem tylko jedną logiczną rzecz… Co? Nie, oczywiście, że nie chodzi mi o przygotowanie PR-a do dprinta. Zacząłem rzeźbić własny formater!

Problem

Ale w zasadzie jaki problem chciałem rozwiązać formaterem? No w sumie to żaden… Po prostu zauważyłem, że zdecydowana większość rzeczy, na które zwraca mi uwagę ESLint, to właśnie formatowanie. Czyli akurat ta część pisania kodu, którą można najłatwiej zautomatyzować. Więc zacząłem się zastanawiać, czy nie byłoby wydajniej, gdybym nie musiał w ogóle martwić się podkreślaniem brakujących spacji wewnątrz tablic czy innymi przecinkami w nieodpowiednich miejscach. Zwłaszcza, że nieużywanie lintera do formatera powoli staje się dobrą praktyką.

No i formater pozwoliłby mi także na formatowanie bardziej złożonych przypadków, które przy pomocy ESLinta trudno obsłużyć. W końcu linter niekoniecznie musi nawet wiedzieć o tym, jak sformatowany jest kod – dla niego najważniejsza jest semantyka kodu. To formater jest choćby od tego, by wiedzieć, ile jest znaków w danej linijce i jak przełamać ciąg znaków, jeśli ktoś się uprze, że linia nie może mieć więcej niż 100 znaków.

Pierwszym krokiem do formaterowej rewolucji było wydzielenie reguł formatujących do osobnej konfiguracji ESLinta. Dzięki temu będę w stanie je szybciej wyłączyć, gdy już podłączę formater. Drugim krokiem było przeglądnięcie istniejących opcji. A tych, wbrew pozorem, nie jest dużo. Jest oczywiście Prettier – król formaterów – ale sam nazywa siebie mocno opinionated (upartym), co jest eufemizmem na “powodzenia z konfigurowaniem”. Dlatego też odpadł w przedbiegach. Następny w kolejce był dprint. Trzeba przyznać – ma imponującą liczbę opcji konfiguracyjnych. Ale mimo to nie udało mi się znaleźć niektórych opcji pozwalających na np. wstawianie spacji wewnątrz definicji pętli. A że całość jest napisana w Ruście, w którym nie czuję się jakoś szczególnie mocny, to na ten moment dopisanie do dprinta potrzebnych mi ficzerów odłożyłem na półkę. Spojrzałem nawet na Rome, niemniej pod względem konfiguracji było równie nieciekawie, co w przypadku Prettiera.

No więc została tylko jedna opcja: napisać to samemu!

Koncept

W gruncie rzeczy formater nie różni się zbytnio od pozostałych zabaw z JS-em, jakie ostatnio uskuteczniałem. Jego fundamentem jest – a jakże – AST. Z tym, że dotąd interesowały mnie głównie transformacje samego drzewka, całkowicie nie zważałem na to, co ostatecznie się z tym drzewkiem dzieje. A zatem: nie interesowało mnie, jak będzie wyglądał wyprodukowany kod JS. W tym przypadku jest jednak odwrotnie: to właśnie ten generowany kod mnie najbardziej interesuje.

Na dobrą sprawę formater można nazwać generatorem kodu, który tym się różni od tradycyjnego generatora (takiego jak @babel/generator), że dba o to, aby zwracany kod był czytelny dla człowieka. Zasada działania generatora jest w miarę prosta:

• weź drzewko AST,
• dla każdego węzła zwróć jego tekstową reprezentację,
• posklejaj wszystkie te ciągi w jeden i go zwróć.

Wyzwania

Brzmi dość prosto, ale okazuje się, że niekoniecznie takie jest.

Liczba węzłów

Pierwszym problemem, na jaki można się natknąć, jest przekształcanie węzłów do ich reprezentacji tekstowej. Weźmy prosty, przykładowy kod:

console.log( 'test' );

Jeśli spojrzymy na wygenerowane drzewko, zauważymy, że wcale nie jest takie proste. Całość opakowana jest w węzeł File, który reprezentuje plik JS. W tym pliku znajduje się z kolei Program – a więc całość kodu JS. Wewnątrz programu mamy ExpressionStatement (czyli instrukcję, która jest także wyrażeniem; to nasz console.log() wraz ze średnikiem na końcu), a dalej samo wyrażenie. Ale żeby nie było za łatwo, to wyrażenia mają swoje typy! W tym przypadku – CallExpression, czyli wywołanie funkcji. Ale samo wywołanie funkcji składa się z kolejnych dwóch węzłów – argumentu będącego StringLiteralem (ciągiem znaków) oraz nazwy wywoływanej funkcji. Ta nazwa z kolei to MemberExpression, czyli odwołanie do własności obiektu (bo tak naprawdę wywołujemy metodę log() obiektu console), a ten składa się z dwóch Identifierów – nazwy obiektu oraz nazwy samej własności.

W postaci uproszczonego drzewka wyglądałoby to mniej więcej tak:

File
| - Program
|   | - ExpressionStatement
|   |   | - CallExpression
|   |   |   | - StringLiteral
|   |   |   | - MemberExpression
|   |   |   |   | - Identifier
|   |   |   |   | - Identifier

W sumie: 7 rodzajów węzłów. A wywołaliśmy tylko console.log()a! Jasne, część z tego drzewka to niepotrzebne nam “śmieci” (jak File czy Program), ale reszty nie da się tak prosto pozbyć. Co oznacza, że nawet dla prostych programów trzeba dodać obsługę sporej liczby węzłów. Części z nich nie da się pominąć, ale niektóre rzeczy można próbować upraszczać (jak np. literały czy typowe przypisy z TS-a). Niemniej: na start widać, że to nie będzie przyjemna praca, tylko żmudne rzeźbienie w oceanie pojedynczych węzłów.

Wcięcia

Kolejnym, dość nieoczywistym problemem, są wcięcia. Prosty przykład:

function test() {
    return true;
}

Formater musi wiedzieć, że wewnątrz funkcji na początku nowej linii musi być wcięcie. I w takim prostym przypadku da się to zrobić “na chama”, wstawiając odpowiednie wcięcie na sztywno. Ale w bardziej skomplikowanych przypadkach już niekoniecznie to zadziała:

function test() {
    if ( true ) {
        return false;
    }
}

W każdym przypadku, gdy będzie więcej niż jeden poziom zagłębienia, formater musi wiedzieć, ile wcięć powinien wstawić. Zatem musi w jakiś sposób śledzić to, jak wygląda generowany kod.

Długość linii

Wreszcie – długość linii. Załóżmy, że chcemy, aby linie nie przekraczały 120 znaków. Tylko w jaki sposób formater miałby to wykryć? Zwłaszcza, że ta długość linii może zacząć przekraczać 120 znaków dopiero po sformatowaniu. Kolejny problem pojawia się przy pytaniu, co z tym zrobić. Formater musiałby wiedzieć, jak np. łamać ciągi znaków albo zapisywać całe funkcje w taki sposób, żeby np. rozdzielać parametry na linie:

function test(
	a,
    b,
    c
) {
    return true;
}

Ze wszystkich problemów ten wydaje się najbardziej złożony.

Implementacja

Zacząłem rzeźbić pomału własny formater. Z racji tego, że uwielbiam ironię, nie jest w żaden sposób konfigurowalny. Co ma w sumie sens, zważając na to, że nigdy go nie ukończę tylko ja go będę używał. Na ten moment rozwój idzie dość niemrawo. Okazało się bowiem, że stworzenie podstawowej architektury i rozwiązanie większości problemów zajmują bardzo mało czasu w porównaniu do… tworzenia obsługi poszczególnych typów węzłów. A to jest po prostu żmudna robota, która skutecznie mnie zniechęca do dłuższego grzebania przy tym.

Ale do rzeczy!

Formatery

Trzon rozwiązania stanowią tzw. formatery (“Słyszałem, że lubisz formatować swój kod, więc umieściłem formatery wewnątrz formatera, żebyś mógł formatować kod w trakcie jego formatowania!”) – czyli funkcje zajmujące się mieleniem poszczególnych węzłów do ich tekstowej reprezentacji. Każdy formater ma identyczną strukturę. Weźmy dla przykładu ten dla BooleanLiterala (czyli wartości boolean):

import { isBooleanLiteral } from '@babel/types'; // 3
import { FormatterContext } from '../context.js';

export default function BooleanLiteral( context: FormatterContext ): string { // 1
	const { node } = context;

	if ( !isBooleanLiteral( node ) ) { // 2
		throw new Error( 'Incorrect node type' ); // 4
	}

	return String( node.value ); // 5
}

Formater przyjmuje jako argument kontekst (o nim za chwilę) i zwraca ciąg znaków (1). Na samym początku następuje sprawdzenie, czy na pewno mamy do czynienia z booleanem (2) przy pomocy funkcji udostępnianej przez samego Babela (3). Jeśli nie, rzucamy błąd (4). Taka sytuacja nigdy nie powinna się zdarzyć, a samo sprawdzenie jest w sumie kompromisem, na jaki poszedłem z TS-em, żeby niepotrzebnie nie komplikować typów w innych miejscach. Dlatego praktycznie zawsze zwracana jest tekstowa reprezentacja węzła (5). W przypadku booleana całość to po prostu skonwertowanie wartości węzła do stringu. W innych przypadkach konwersja może być zdecydowanie bardziej skomplikowana.

Konteksty

I właśnie w tych innych przypadkach przydają się konteksty. To prosta struktura, która przechowuje aktualnie formatowany węzeł wraz z aktualnym stanem całego formatowania. Do tego dochodzą proste metody do wywołania formatowania na potomnym węźle (np. na argumencie, gdy jesteśmy wewnątrz deklaracji funkcji) czy do pobrania poprzedniego/następnego węzła w drzewie. Z kolei w stanie, na ten moment, znajdują się tylko dwie rzeczy: kod źródłowy JS-a oraz aktualny poziom zagnieżdżenia. Dzięki temu drugiemu udało się rozwiązać problem z wcięciami. Teraz zwiększenie poziomu wcięcia rozwiązuję, wywołując metodę context#formatDescendant() z odpowiednim argumentem:

context.formatDescendant( node, {
	increaseIndent: true
} );

Opcja ta jest wykorzystywana np. do automatycznego wcinania kodu wewnątrz bloków.

Z kolei trzymanie kodu źródłowego w stanie pozwoliło na rozwiązanie dość nieoczekiwanego problemu. Nie tak dawno temu opisywałem makra. Korzystały one z nowej składni tzw. atrybutów importów. Problem w tym, że wcześniej nazywało się to asercjami importów i używało innego słowa kluczowego:

// Nowa składnia
import test from './test.js' with { type: 'whatever' };

// Stara składnia
import test from './test.js' assert { type: 'whatever' };

Obecnie obydwie te wersje są wspierane przez silniki JS (zwłaszcza V8, którego używa m.in. Node.js), ale Babel reprezentuje je w ten sam sposób. Innymi słowy: z poziomu drzewka AST nie da się dowiedzieć, które słowo kluczowe zostało użyte. Na szczęście Babel przy parsowaniu pliku dołącza do każdego węzła informacje o tym, gdzie się znajduje jego kod źródłowy w tymże pliku. Dlatego też napisałem prostą funkcję do wyciągania kodu danego węzła. Następnie przy pomocy wyrażenia regularnego przeszukuję ten kod i ustalam, jakie słowo kluczowe zostało użyte. Brutalne, ale działa.

Z kolei funkcje pobierające poprzedni i następny węzeł pozwoliły mi na rozwiązanie innego problemu: ustalenia, gdzie wstawić puste linie w kodzie. Na ten moment jest to wykorzystywane w formaterze ifów do generowania pustej linii przed nimi. Ale zapewne użyję tego w wielu innych miejscach, bo dość chętnie stosuję puste linie.

Tło fabularne

Ale czemu w zasadzie konteksty powstały? Zapewne osoby trochę siedzące w JS-owym AST zauważą, że ich API jest dość podobne do ścieżek z Babela. Niemniej ścieżki zawierają sporo informacji, które nie są dla mnie interesujące, a równocześnie – nie zawierają informacji, które są dla mnie istotne (np. poziom zagłębienia). Co więcej, oficjalne API Babela “odwiedza” węzły w kolejności ich występowania w kodzie, a bardzo szybko przekonałem się, że o wiele wygodniejsze byłoby dla mnie robienie tego rekurencyjnie (zatem nie “w bok”, a w głąb). Wróćmy do naszego console.log()a. Przy wykorzystaniu oficjalnej paczki @babel/traverse, Babel będzie odwiedzał węzły w następującej kolejności:

enter Program
enter ExpressionStatement
enter CallExpression
enter MemberExpression
enter Identifier
exit Identifier
enter Identifier
exit Identifier
exit MemberExpression
enter StringLiteral
exit StringLiteral
exit CallExpression
exit ExpressionStatement
exit Program

Babel pozwala na określenie, czy chcemy obsłużyć węzeł przy wchodzeniu do niego (enter), czy przy wychodzeniu (exit). W przypadku console.log();a wejście oznacza dotarcie do console, a wyjście – dotarcie do średnika na końcu. Niemniej to oznacza, że generowanie np. ExpressionStatement musiałoby być podzielone na dwie części. Na wejściu, na dobrą sprawę, nie mielibyśmy pojęcia, jak wygląda instrukcja, moglibyśmy jedynie zaznaczyć w jakimś wewnętrznym stanie, że w takowej jesteśmy. Następnie każdy węzeł byłby uważany za część naszej instrukcji. I dopiero, gdy napotkalibyśmy wyjście z instrukcji, moglibyśmy ją w całości zwrócić. To może dość utrudniać poprawną obsługę wcięć i białych znaków, nie wspominając już o problemie z długością linii.

Taka metoda dodatkowo średnio pozwala na pominięcie węzłów, które z różnych powodów nas nie interesują. Dlatego doszedłem do wniosku, że o wiele lepiej byłoby móc przechodzić drzewo rekurencyjnie (w głąb). Stąd stworzyłem konteksty, które zastępują Babelowe ścieżki i pozwalają na ręczne ustalenie, czy chcemy wchodzić w głąb jakiegoś węzła. Każdy formater dostaje swój własny kontekst, zawierający węzeł do sformatowania wraz z aktualnym stanem formatowania i informacjami o najbliższym otoczeniu węzła. Kontekst pozwala także na wywołanie formatowania potomnego węzła – albo i nie, dzięki czemu nie trzeba obsługiwać wszystkich dziwnych przypadków lub obsłużyć je w rodzicu.

Nierozwiązany problem długości linii

Główny nierozwiązany problem, jaki pozostał, to problem zbyt długich linii. Zastanawiałem się, czy uda mi się znaleźć jakieś sensowne rozwiązanie dla niego, ale na tę chwilę nic mi nie przychodzi do głowy. Jedyne na co wpadłem, to sformatowanie danego węzła, po czym sprawdzenie, czy wynikowy ciąg ma więcej niż 120 znaków. W takim przypadku byłby uruchamiany “tryb wielolinowy”, który formatowałby dany węzeł tak, by ten mieścił się w określonej liczbie znaków. Jeśli nie wymyślę nic sensowniejszego, to prawdopodobnie ostatecznie spróbuję z tym sposobem.

Dalsze plany

Dalszych planów za bardzo nie ma. Prace uznam za zakończone, gdy uda mi się przepuścić przez formater kod mojego bundlera i dostać na wyjściu dokładnie taki sam kod, jaki był na wejściu. Ale do tego jeszcze długa droga, bo na ten moment formater obsługuje kilkanaście typów węzłów z jakichś kilkuset potrzebnych. Więc jest spora szansa, że zarzucę całość, zanim na dobre ją ukończę…

…albo dprint doda brakujące opcje konfiguracyjne. Jedno z tych dwóch.

Makra – co to?

Założenie makr jest dość proste: przy wykorzystaniu tzw. atrybutów importów poinformujmy kompilator, że dana importowana funkcja jest makrem. Następnie kompilator znajdzie wszystkie wywołania tej funkcji i zamieni je na wynik jej wywołania.

Wyobraźmy sobie, że mamy moduł eksportujący funkcję losującą liczbę, random.js:

function random() {
	return Math.random();
}

export { random };

Następnie w innym miejscu naszej aplikacji chcemy jej użyć jako makra:

import { random } from './random.js' with { type: 'macro' };

console.log( random() );

W imporcie pojawiła się dodatkowa część ze słówkiem kluczowym with – to właśnie atrybut importu. W tym przypadku nazywa się type i ma wartość macro, ponieważ chcemy poinformować kompilator, że ma do czynienia z makrem. W podobny sposób można poinformować, że wczytujemy np. JSON zamiast JS-a:

import pkg from './package.json' with { type: 'json' };

Warto przy tym zauważyć, że na ten moment zdecydowanie częściej można spotkać starszą wersję składni atrybutów (z czasów, gdy jeszcze były asercjami):

import pkg from './package.json' assert { type: 'json' };

Obydwie robią to samo, ale ta druga ma obecnie lepsze wsparcie zarówno w środowiskach uruchomieniowych JS-a, jak i we wszelkiego rodzaju narzędziach. To się jednak będzie powoli zmieniać, zatem pozwolę sobie używać w tym artykule nowszej składni.

Funkcje zaimportowane z atrybutem { type: 'macro' } zostaną usunięte z ostatecznego kodu i zastąpione wynikiem ich wywołania:

console.log( 0.7507075485199182 );

W bunie dzieje się to podczas wywołania komendy build:

bun build ./app.ts

W Node.js nie ma jednak wbudowanego żadnego buildera czy choćby kompilatora TS-a, ale za to istnieje bogaty ekosystem bundlerów. Jednym z nich jest Rollup.js. I właśnie do niego postanowiłem dodać eksperymentalną obsługę makr.

Zarys rozwiązania

Rollup.js jest narzędziem, które bardzo łatwo rozwijać dzięki jego dość rozbudowanemu API pluginów. W taki też sposób można do niego dodać obsługę makr. Tak naprawdę plugin będzie składał się z dwóch części:

1. wykrycia, że dany moduł to moduł zawierający makra, dzięki czemu będzie można go usunąć z ostatecznego bundle’a,
2. podmiany wywołań konkretnych makr na ich wyniki.

Obydwie części wykonamy przy pomocy tzw. hooków (haków), które pozwalają się wpinać w poszczególne etapy bundle’owania, takie jak parsowanie opcji przekazanych do rollupa czy wczytywanie poszczególnych modułów. Do różnych operacji na kodzie wykorzystamy AST.

Bierzmy się zatem do pracy!

Wykrywanie modułu z makrami

W przypadku Rollupa nie da się tak po prawdzie całkowicie usunąć jakiegoś modułu z bundle’a. Jedyne, co można zrobić, to poinformować bundler, że dany moduł jest external (zewnętrzny). To sprawi, że Rollup pozostawi import tego modułu w spokoju. Jest to zdecydowanie krok w dobrą stronę, bo o wiele prościej będzie usunąć taki import, niż próbować usunąć cały zbundle’owany kod modułu.

Wykrywanie modułu z makrami jest stosunkowo proste. Rollup udostępnia hook resolveId(), który pozwala m.in. właśnie na oznaczenie modułu jako zewnętrzny.

Ale zanim przejdziemy do mięska, trzeba stworzyć szkielet naszego pluginu:

function plugin() { // 1
	return { // 2
		name: 'macros' // 3
	};
}

export default plugin;

Typowy plugin do Rollupa jest funkcją (1), która zwraca obiekt (2). Musi on mieć własność name (3) zawierającą nazwę pluginu. Pozostałymi własnościami są poszczególne hooki.

Dodajmy zatem nasz hook resolveId():

function plugin() {
	return {
		name: 'macros',

		resolveId( importee, importer, { assertions } ) { // 1
			if ( assertions && assertions.type === 'macro' ) { // 2
				return { // 3
					id: importee, // 4
					external: true // 5
				};
			}

			return null; // 6
		}
	};
}

export default plugin;

Hook resolveId() przyjmuje kilka parametrów (1):

1. importee – nazwa wczytywanego modułu,
2. importer – ścieżka wczytującego modułu,
3. options – obiekt z dodatkowymi informacjami o wczytywanym module, w tym atrybuty (nazywane tutaj asercjami – assertions).

Nas interesują w zasadzie tylko dwie rzeczy – nazwa wczytywanego modułu oraz atrybuty. Jeśli istnieje atrybut type i ma on wartość macro (2), zwracamy obiekt (3), który wskazuje, że ten konkretny moduł importee (4) powinien być traktowany jako zewnętrzny (5) i jego kod nie powinien zostać dorzucony do bundle’a. Z kolei jeśli nie ma atrybutu type albo ma on inną wartość, wówczas zwracamy null (6), co dla Rollupa oznacza, że dla tego modułu powinien odpalić hooki resolveId() z kolejnych pluginów albo użyć domyślnego, jeśli żadnego innego pluginu nie ma.

Taki hook resolveId() wystarczy, żeby import modułu z makrem został nienaruszony, dzięki czemu można go będzie łatwo usunąć.

Usuwanie importów modułów z makrami

Modyfikacje kodu wczytywanych modułów przeprowadza się w hooku transform(). Daje on dostęp do kodu modułu i oczekuje, że po wszystkich zmianach zwrócony zostanie nowy kod. Rollup pozwala także zwrócić mapę dla kodu po zmianach, co może być przydatne, jeśli zaszły większe zmiany. W przypadku tego eksperymentu pozwoliłem sobie pominąć mapy, bo niepotrzebnie komplikowałyby całość.

Dodajmy zatem hook transform() do naszego pluginu:

function plugin() {
	return {
		name: 'macros',

		// […]

		transform( code ) { // 1

		}
	};
}

export default plugin;

Na ten moment potrzebny będzie nam tylko pierwszy argument, czyli kod modułu w formie stringa (1).

Skoro mamy stringa z kodem, to w teorii można by wykorzystać wyrażenia regularne, żeby znaleźć interesujący nas fragment i go podmienić (jest nawet biblioteka od tego – swoją drogą, bardzo dobra!). Niemniej takie wyrażenie regularne musiałoby być mocno skomplikowane (bo samych sposobów wstawienia spacji między poszczególnymi elementami importu jest co najmniej kilka…), przez co całość byłaby podatna na błędy. Na szczęście istnieje inny, bardziej elegancki sposób: sparsowanie kodu do postaci AST.

Tutaj z pomocą przychodzi nam Rollup, który wewnątrz hooka transform() udostępnia metodę this.parse(). Wykorzystuje ona parser Acorn (używany wewnętrznie przez Rollupa), aby sparsować kod do drzewka AST. Niemniej samo drzewko nie da nam zbyt dużo, bo brakuje nam jeszcze sposobu, aby poruszać się po nim. Tego Rollup już nie oferuje, ale na szczęście istnieją odpowiednie narzędzia do tego. Na potrzeby tego eksperymentu użyjemy pakietu estree-walker:

import { walk } from 'estree-walker'; // 3

function plugin() {
	return {
		// […]

		transform( code ) {
			const ast = this.parse( code ); // 1

			walk( ast, { // 2
				enter( node ) {
					if ( node.type === 'ImportDeclaration' && isMacroImport( node ) ) { // 4
						this.remove(); // 5
					}
				}
			} );
		}
	};
}

Zamieniamy kod na AST przy pomocy wspomnianego już this.parse() (1). Następnie przechodzimy przez to drzewko przy pomocy funkcji walk (2), którą zaimportowaliśmy z pakietu estree-walker (3). Szukamy importów do makr (4). Jeśli takowy znajdziemy, usuwamy go (5). Szukanie składa się z dwóch zasadniczych części: sprawdzenia, czy typ węzła to ImportDeclaration, oraz wywołania funkcji isMacroImport().

Logika tej funkcji jest bardzo podobna do tej, którą zastosowaliśmy w hooku resolveId():

function isMacroImport( node ) {
	if ( !node.assertions ) { // 1
		return false;
	}

	const [ assertion ] = node.assertions; // 2

	return assertion.key.name === 'type' && assertion.value.value === 'macro'; // 3
}

Sprawdzamy, czy import ma atrybuty (1) – czyli własność node.assertions (uwielbiam chaos w nazewnictwie!). Jeśli tak, pobieramy pierwszy z nich (2) i sprawdzamy, czy ma odpowiednią nazwę i wartość (3).

Zapisywanie informacji o makrach

Niemniej jeśli ot tak usuniemy wszystkie importy makr, pozbawimy się informacji o tym, które wywołania funkcji powinniśmy następnie podmienić. Wypada zatem zapisać sobie gdzieś informacje z importów. W tym celu stwórzmy mapę makr:

import { resolve as resolvePath, dirname } from 'node:path'; // 9
// […]

function plugin() {
	return {
		// […]

		transform( code, path ) { // 3
			const ast = this.parse( code );
			const macros = new Map(); // 1

			walk( ast, {
				enter( node ) {
					if ( node.type === 'ImportDeclaration' && isMacroImport( node ) ) {
						extractMacros( macros, node, path );
						this.remove();
					}
				}
			} );
		}
	};
}

function extractMacros( macros, node, modulePath ) { // 2
	const moduleDirPath = dirname( modulePath ); // 7
	const macroPath = resolvePath( moduleDirPath, node.source.value ); // 8

	node.specifiers.forEach( ( specifier ) => { // 4
		const originalName = specifier.type === 'ImportDefaultSpecifier' ?
			'default' :
			specifier.imported.name; // 5
		macros.set( specifier.local.name, { // 6
			name: originalName,
			path: macroPath
		} );
	} );
}

Makra będziemy zapisywali do zmiennej macros (1), w której znajduje się pusta mapa. Logika do zapisu znajduje się w funkcji extractMacros() (2). Przekazujemy do niej mapę, węzeł oraz ścieżkę do aktualnie transformowanego modułu. Ścieżkę tę dostajemy jako drugi argument hooku transform() (3). Funkcja extractMacros() dla każdego specyfikatora importu (4) ustala jego oryginalną nazwę (5), a następnie zapisuje tę informację wraz ze ścieżką do importowanego modułu pod lokalną nazwą makra (6). Ścieżkę uzyskujemy poprzez pobranie katalogu obecnie transformowanego modułu (7) a następnie rozwiązując ścieżkę do importowanego modułu (wyciągniętą z własności node.source.value) względem niego (8) przy pomocy odpowiednich funkcji z modułu node:path (9).

Brzmi to skomplikowanie, więc rozbijmy to na części. Zacznijmy od specyfikatorów (specifiers). W składni importu to określenie na to, co importujemy, np:

import { test } from './test.js';

Specyfikatorem w tym kodzie jest test. W tym konkretnym przypadku lokalna nazwa (czyli ta używana w module importującym), jak i ta oryginalna (czyli ta użyta do eksportu w module importowanym), są takie same. Ale nazwy te mogą się też różnić, gdy pojawią się aliasy:

import { test as t } from './test.js';

W tym wypadku lokalna nazwa to t, a oryginalna – test. Z racji tego, że nazwy te mogą się różnić między sobą, musimy zapisać je obie.

Warto też zwrócić uwagę na szczególny przypadek specyfikatora – specyfikator domyślnego importu:

import Whatever from './whatever.js';

W takim wypadku węzeł nie zawiera oryginalnej nazwy, a jedynie lokalną. Nasz kod ma specjalny warunek na tę okazję:

const originalName = specifier.type === 'ImportDefaultSpecifier' ? // 1
	'default' : // 2
	specifier.imported.name; // 3

Jeśli typ specyfikatora to ImportDefaultSpecifier (1) – czyli domyślny import – wówczas użyj default (2) jako oryginalnej nazwy. W przeciwnym razie weź nazwę z własności imported specyfikatora (3).

Ta sztuczka pozwoli nam później, przy samym wywoływaniu makra, nieco uprościć kod. Domyślne importy bowiem to w rzeczywistości skrócona wersja takiego zapisu:

import { default as Whatever } from './whatever.js';

Inny słowy: domyślne importy można traktować jak aliasy do importu nazwanego eksportu default.

Z kolei w przypadku ścieżki potrzebujemy absolutnej (czemu, to okaże się później) – a więc rozpoczynającej się od /. Niemniej nasz węzeł importu zawiera ją najprawdopodobniej w formie ścieżki relatywnej – zaczynającej się od ./. Takie ścieżki zawsze podawane są względem katalogu modułu importującego. Zatem przy pomocy funkcji dirname() wyciągamy absolutną ścieżkę do katalogu ze ścieżki do modułu, a następnie rozwiązujemy ścieżkę do modułu z makrami przy pomocy funkcji resolvePath(). Dzięki temu uzyskujemy absolutną ścieżkę do importowanego modułu.

Tak zebrane informacje wrzucamy do modułu z makrami i jesteśmy gotowi, by odpalić jakieś makro!

Wyszukiwanie makr w kodzie

Zanim jednak je odpalimy, musimy je znaleźć. Na szczęście istnieje odpowiedni typ węzła, którego możemy po prostu poszukać w drzewku AST – CallExpression. Te węzły to nic innego jak wywołania funkcji.

Dodajmy zatem kolejny if do naszego walka(), tym razem dla wywołań funkcji:

function plugin() {
	return {
		// […]

		transform( code, path ) {
			const ast = this.parse( code );
			const macros = new Map();

			walk( ast, {
				enter( node ) {
					// […]
					if ( node.type === 'CallExpression' ) { // 1
						const name = node.callee.name; // 2

						if ( !macros.has( name ) ) { // 3
							return;
						}

						const macro = macros.get( name ); // 4
					}
				}
			} );
		}
	};
}

Po upewnieniu się, że mamy do czynienia z wywołaniem funkcji (1), pobieramy jej nazwę (2). Sprawdzamy, czy taka nazwa występuje w naszej mapie z makrami (3). Jeśli tak, wyciągamy informacje o makrze do zmiennej macro (4).

Odpalanie makr

Skoro już znaleźliśmy makro, pora je odpalić:

function plugin() {
	return {
		// […]

		transform( code, path ) {
			// […]

			asyncWalk( ast, { // 3
				async enter( node ) { // 2
					// […]
					if ( node.type === 'CallExpression' ) {
						const name = node.callee.name;

						if ( !macros.has( name ) ) {
							return;
						}

						const macro = macros.get( name );
						const macroResult = await executeMacro( macro ); // 1
					}
				}
			} );
		}
	};
}

Cała logika odpalania makra została zamknięta w asynchronicznej funkcji executeMacro() (1), do której przekazujemy obiekt makra, a która zwraca Promise z wynikiem wywołania makra. Warto przy tym zwrócić uwagę, że to wymusza zrobienie całej metody enter() asynchroniczną (2). Równocześnie wymusza też wymianę walk() na asyncWalk() (3) – bo to pierwsze jest wyłącznie synchroniczne.

Natomiast funkcja executeMacro() prezentuje się następująco:

import { writeFile } from 'node:fs/promises';
import { pathToFileURL } from 'node:url';
import { Worker } from 'node:worker_threads';
import { temporaryFile } from 'tempy';

async function executeMacro( { name, path } ) {
	const alias = name === 'default' ? 'tempName' : name;
	const pathURL = pathToFileURL( path );
	const code = `import { parentPort } from 'node:worker_threads';
	import { ${ name } as ${ alias } } from '${ pathURL }';

	const result = await ${ alias }();

	parentPort.postMessage( result );`;

	const workerFilePath = temporaryFile( {
		extension: 'mjs'
	} );

	await writeFile( workerFilePath, code, 'utf-8' );

	return new Promise( ( resolve, reject ) => {
		const worker = new Worker( workerFilePath );

		worker.on( 'message', resolve );
		worker.on( 'error', reject );
		worker.on( 'exit', ( exitCode ) => {
			if ( exitCode !== 0 ) {
				reject( exitCode );
			}
		} );
	} );
}

Wykorzystuje ona workery, aby odpalić kod makra “z dala” od reszty kodu i następnie jedynie przekazać jego wynik.

Trochę się tutaj dzieje, więc rozbijmy sobie tę funkcję na dwie części. Pierwsza część odpowiedzialna jest za wygenerowanie kodu workera:

const alias = name === 'default' ? 'tempName' : name; // 1
const pathURL = pathToFileURL( path ); // 2
const code = `import { parentPort } from 'node:worker_threads';
import { ${ name } as ${ alias } } from '${ pathURL }';

const result = await ${ alias }();

parentPort.postMessage( result );`; // 3

const workerFilePath = temporaryFile( { // 4
	extension: 'mjs' // 5
} );

await writeFile( workerFilePath, code, 'utf-8' ); // 6

Na początku ustalamy lokalną nazwę importu – alias (1). Jeśli mamy do czynienia z domyślnym importem (czyli default), naszym aliasem będzie tempName. Wynika to z tego, że default jest zarezerwowanym słowem w JS-ie i nie może ot tak wystąpić jako nazwa funkcji. Dlatego też musimy wybrać jakąś inną nazwę. Nie chciało mi się myśleć, więc jest tempName. Z kolei jeśli nazwa importu jest inna, używamy jej bezpośrednio. Następnie zamieniamy absolutną ścieżkę modułu na URL (2) przy pomocy funkcji pathToFileURL() z modułu node:url. Moduły w Node.js wymagają, by były wczytywane po URL-u. A to oznacza, że ścieżki na Windowsie (nawet zapisane z / zamiast \) będą sprawiać problemy – a to z powodu tego, że litera dysku (np. c:) zostanie potraktowana jako schemat. Dlatego bezpieczniej jest przekształcić absolutną ścieżkę na URL ze schematem file:. Mając przygotowany alias i URL modułu generujemy kod workera (3). Następnie tworzymy tymczasowy plik (4) z rozszerzeniem .mjs (5) – tutaj przy pomocy funkcji temporaryFile() z pakietu tempy. Do tego pliku zapisujemy wygenerowany kod (6).

Wykorzystanie tymczasowego pliku tłumaczy, czemu potrzebowaliśmy absolutnej ścieżki do modułu z makrami. Taki tymczasowy plik jest tworzony w systemowym katalogu przeznaczonym do -przechowywania plików tymczasowych. Z tego też powodu relatywna ścieżka wskazywałaby na nieistniejący plik. Ścieżka absolutna zapewnia z kolei poprawne wczytanie modułu.

Prawdę mówiąc, miałem nadzieję, że uda się całość zrobić bez użycia tymczasowego pliku, zwłaszcza, że konstruktor workera pozwala podać kod:

new Worker( 'console.log( "Hello, world!" );', {
	eval: true
} );

Problem polega na tym, że tak wykonany kod odpala się jako moduł CJS – a więc nie działają w nim importy.

W teorii można też przekazać do konstruktora Data URL z kodem JS, ale ta opcja też nie chciała działać. Node.js upierał się, że URL jest niepoprawny, podczas gdy przeglądarka nie miała problemu z jego odpaleniem. Ostatecznie zatem musiałem użyć tymczasowego pliku. Na wszelki wypadek dałem mu rozszerzenie .mjs, żeby wymusić na Node.js traktowanie go jako modułu ES.

Przyjrzyjmy się jeszcze przez chwilę samemu kodowi workera:

import { parentPort } from 'node:worker_threads'; // 4
import { name as alias } from 'file:///path/to/module-with-macros.mjs'; // 1

const result = await alias(); // 2

parentPort.postMessage( result ); // 3

Jest bardzo prosty, bo jego jedynym zadaniem jest zaimportowanie makra (1), wywołanie go – na wszelki wypadek z awaitem (2), a następnie przesłanie do bundlera wyniku tego wywołania (3). W tym celu posługuje się obiektem parentPort zaimportowanym z modułu node:worker_threads (4). Ten schemat jest bardzo podobny do tego, jak działa komunikacja między głównym wątkiem a workerem w przeglądarce.

Z kolei druga część funkcji executeMacro() wygląda następująco:

return new Promise( ( resolve, reject ) => { // 1
	const worker = new Worker( workerFilePath ); // 2

	worker.on( 'message', resolve ); // 3
	worker.on( 'error', reject ); // 4
	worker.on( 'exit', ( exitCode ) => {
		if ( exitCode !== 0 ) {
			reject( exitCode ); // 5
		}
	} );
} );

Zwraca ona Promise (1), dzięki czemu można poczekać na wykonanie executeMacro() przy pomocy zwykłego await. Wewnątrz tego Promise’a tworzymy workera na podstawie naszego tymczasowego pliku (2). Jeśli prześle on jakąś wiadomość, rozwiązujemy obietnicę z nią jako wynikiem (3). W przypadku błędu (4) lub przedwczesnego zakończenia workera (5) odrzucamy obietnicę.

Podmiana makra na wynik

Skoro już wywołaliśmy makro i dostaliśmy jego wynik, pora zamieścić go w kodzie zamiast samego wywołania. Tutaj jednak pojawia się problem: z workera otrzymujemy JS-ową wartość – czy to typu prostego, czy też obiekt lub tablicę. A my potrzebujemy węzła, który można wsadzić do drzewka AST. Tu z pomocą przychodzi nam nasz stary znajomy – this.parse():

function plugin() {
	return {
		// […]

		transform( code, path ) {
			// […]

			asyncWalk( ast, {
				async enter( node ) {
					const parse = this.parse; // 2

					// […]

					if ( node.type === 'CallExpression' ) {
						// […]
						const macroResult = await executeMacro( macro );
						const macroResultAST = parse( `( ${ JSON.stringify( macroResult ) } )` ); // 1
						const expression = getValueNode( macroResultAST ); // 3

						this.replace( expression ); // 4
					}
				}
			} );
		}
	};
}

Wywołujemy parse() na wyniku zwróconym przez makro (1). Z racji tego, że parser przyjmuje wyłącznie stringi, najpierw musimy przepuścić ten wynik przez JSON.stringify(). Dodatkowo otaczamy całość nawiasami. Jest to konieczne, ponieważ w JS-ie istnieje pewna dwuznaczność – { a: 1 } może oznaczać zarówno obiekt z własnością a, jak i tzw. instrukcję z etykietą zamkniętą w bloku. W przypadku tej niejasności parser wybiera instrukcję z etykietą w bloku… Otoczenie całości nawiasami usuwa tę dwuznaczność, ponieważ instrukcje nie mogą znajdować się wewnątrz nawiasów, a więc musi to być tzw. wyrażenie obiektowe (czyli inaczej – po prostu obiekt). Warto tutaj też zauważyć, że zapisaliśmy sobie this.parse() do zmiennej parse() (2) – a to dlatego, że wewnątrz enter() mamy inny kontekst this (węzeł AST). Samo sparsowanie wyniku do AST to jednak nie wszystko. Parser zwraca bowiem cały program, a takowym nie możemy zastąpić wywołania funkcji. Musimy wyłuskać z programu sam wynik – i tym zajmuje się funkcja getValueNode() (3). Gdy już wyłuskamy odpowiedni węzeł, zastępujemy nim ten obecny (4).

Funkcja getValueNode() wygląda następująco:

function getValueNode( node ) { // 1
	const allowedNodeTypes = [ // 2
		'Literal', // 3
		'ObjectExpression', // 4
		'ArrayExpression' // 5
	];
	let valueNode; // 6

	walk( node, { // 7
		enter( node ) {
			if ( !allowedNodeTypes.includes( node.type ) ) { // 8
				return; // 9
			}

			valueNode = node; // 10
			this.skip(); // 11
		}
	} );

	return valueNode; // 12
}

Przekazujemy do niej nasz wynik w formie AST (1). Następnie definiujemy sobie, jakich węzłów szukamy (2) – w naszym przypadku będą to literały (3), obiekty (4) oraz tablice (5). Dla parsera literałem są praktycznie wszystkie wartości prymitywne (oprócz symboli; niemniej tych i tak nie da się przesłać z workera, więc who cares). Następnie tworzymy sobie zmienną valueNode (6) i przechodzimy przez nasze drzewko przy pomocy znanej już nam funkcji walk() (7). Jeśli węzeł nie jest jednym z dozwolonych typów (8), nic nie robimy (9). W innym wypadku przypisujemy go do zmiennej valueNode (10) oraz wywołujemy this.skip() (11), informując walkera, że nie chcemy wchodzić głębiej w drzewko. Na samym końcu zwracamy znaleziony węzeł (12).

Obsługa argumentów

Niemniej niektóre makra mają parametry. I wypadałoby takie też obsługiwać. Na szczęście dodanie podstawowego wsparcia dla przekazywania argumentów do makr jest stosunkowo proste. I można to zrobić np. tak:

function plugin() {
	return {
		// […]

		transform( code, path ) {
			// […]

			asyncWalk( ast, {
				async enter( node ) {
					// […]

					if ( node.type === 'CallExpression' ) {
						// […]
						const allowedArgNodeTypes = [ // 1
							'Literal',
							'ObjectExpression',
							'ArrayExpression'
						];
						const args = node.arguments; // 2
						const isSupported = args.every( ( { type } ) => { // 3
							return allowedArgNodeTypes.includes( type ); // 4
						} );

						if ( !isSupported ) { // 5
							throw new Error( 'Only macros with arguments of primitive types, object and arrays are supported currently.' ); // 6
						}

						const macroResult = await executeMacro( macro, args ); // 7
						// […]
					}
				}
			} );
		}
	};
}

Tworzymy sobie tablicę typów argumentów, które obecnie obsługujemy (1) – to dokładnie te same typy, które obsługujemy przy wyniku. Następnie do zmiennej args pobieramy sobie argumenty przekazane do makra z własności node.arguments (2). Przy pomocy args.every() (3) sprawdzamy, czy wszystkie argumenty są przez nas obsługiwane (4). Jeśli nie (5), rzucamy błąd (6). W innym przypadku wywołujemy makro, przekazując argumenty jako drugi argument (7).

W executeMacro() pojawił się z kolei kod odpowiedzialny za formatowanie argumentów:

import { generate } from 'escodegen'; // 3

async function executeMacro( { name, path }, args ) {
	// […]
	const formattedArgs = args.map( ( node ) => { // 1
		return generate( node ); // 2
	} ).join( ', ' ); // 4
	const code = `import { parentPort } from 'node:worker_threads';
	import { ${ name } as ${ alias } } from '${ pathURL }';

	const result = await ${ alias }( ${ formattedArgs } ); // 5

	parentPort.postMessage( result );`;

	// […]
}

Dla każdego argumentu w formie AST (1) generujemy odpowiadający mu kod przy pomocy funkcji generate() (2) z pakietu escodegen (3). Następnie łączymy wszystkie argumenty przy pomocy przecinka (4) – żeby uzyskać poprawny fragment kodu z argumentami. Mając takowy, podstawiamy go do wywołania makra w kodzie workera (5).

Pakiet escodegen to taka odwrotność parsera – zwraca kod z podanego drzewka AST. Wykorzystaliśmy go tutaj, ponieważ do workera potrzebujemy kodu JS, nie – AST.

Zwrócenie zmodyfikowanego kodu

Skoro już wywołaliśmy makro i podstawiliśmy za nie jego wynik, została ostatnia rzecz: zwrócenie zmodyfikowanego kodu z hooka transform():

function plugin() {
	return {
		// […]

		transform( code, path ) {
			// […]

			return {
				code: generate( ast ) // 1
			};
		}
	};
}

Raz jeszcze wykorzystujemy tutaj funkcję generate() (1) z pakietu escodegen, żeby wygenerować kod ze zmodyfikowanego przez nas drzewka AST.

I tym sposobem zaimplementowaliśmy makra w Rollupie!

Wnioski

To był zadziwiająco przyjemny i stosunkowo mało złożony projekt. A efekt końcowy jest zdecydowanie jednym z lepszych, jakie udało mi się osiągnąć w przypadku moich eksperymentów. Jasne, jest tu sporo niedoskonałości, które można doszlifować, np.

• Co jeśli makro zostało przykryte przez jakąś zmienną w zasięgu? Wówczas nie powinniśmy podmieniać takiego wywołania. Tutaj na pomoc może przyjść funkcja attachScopes() z pakietu @rollup/pluginutils, która pozwala sprawdzić, czy dana nazwa zmiennej jest z zasięgu globalnego czy lokalnego. A że importy muszą być globalne, to pozwoli to wykryć potencjalne kolizje.
• Wypadałoby też obsługiwać inne rodzaje argumentów, np. zmienne. Oczywiście nie wszystkie się da, ale jeśli zmienna zawiera choćby liczbę, to powinno to być możliwe. Problemem jest trzymanie informacji o tym, gdzie jest która zmienna, żeby móc szybko odczytać jej wartość.
• Fajnie byłoby wspierać bardziej “egzotyczne” wyniki, jak np. bufory czy obiekty odpowiedzi generowane przez fetch(). Ale to już wymaga niestandardowej serializacji.

Obecne rozwiązanie, po lekkim refactorze, można znaleźć na GitHubie. Być może komuś się do czegoś przyda. Ja, w każdym razie, miałem przyjemność w trakcie tworzenia tego kodu. A to chyba najważniejsze.

Teoria

W teorii pliki .d.ts wyglądają bardzo podobnie do zwykłych modułów ES. Definicje typów są podzielone na pliki, które odzwierciedlają podział plików źródłowych aplikacji. Dla przykładu, jeśli mamy takie pliki z kodem:

src/
|- index.ts
|- tools.ts
|- SomeClass.ts

to TS wygeneruje nam takie pliki z definicjami typów:

types/
|- index.d.ts
|- tools.d.ts
|- SomeClass.d.ts

Jeśli przyjrzymy się losowemu plikowi .d.ts (ten jest akurat dla lodashowej funkcji assignWith()), zauważymy znajomą składnię importów i eksportów. Więc z perspektywy bundlera zmienia się na dobrą sprawę głównie rozszerzenie pliku i pojawia się nieco inna składnia (TS zamiast czystego JS-a). Niemniej zdecydowana większość logiki bundlera powinna być możliwa do ponownego użycia bez żadnych zmian.

Przykład

Stwórzmy sobie więc przykład, który będziemy chcieli bundle’ować. Składać się on będzie z trzech plików:

• index.d.ts,
• Fixture.d.ts,
• Test.d.ts.

Główny plik, index.d.ts, będzie eksportował wszystkie pozostałe typy:

import { Test } from   './Test'; // 1

export { Test }; // 2
export { Fixture } from   './Fixture'; // 3

Żeby było ciekawie, zastosowałem tutaj dwie metody eksportu – import (1) a następnie eksport (2) oraz eksport połączony z importem (3).

Plik Fixture.d.ts zawiera interfejs Fixture:

interface Fixture { // 1
	name: string;
	path: string;
}

export { Fixture }; // 2

Najpierw definiuje on interfejs (1) a następnie go eksportuje (2).

Z kolei plik Test.d.ts eksportuje interfejs Test:

import { Fixture } from './Fixture'; // 2

export interface Test { // 3
	readonly name: string;
	createFixture( name: string ): Fixture; // 1
}

Wykorzystuje on interfejs Fixture (1), który importuje z pliku Fixture.d.ts (2). Natomiast eksport jest tutaj bezpośrednio połączony z deklaracją interfejsu (3).

Spróbujmy zatem zbundle’ować te trzy pliki razem!

Obsługa składni TypeScriptu

Babel jest parserem JS-a, więc nie ma wbudowanej obsługi składni TS-a. Niemniej istnieje oficjalny plugin, który taką obsługę dodaje. Wystarczy go zainstalować:

npm i @babel/plugin-transform-typescript

a następnie dołączyć do naszego parsera w bundlerze:

function processModule( path, isMain = false ) {
    […]

	const ast = parse( code, {
		sourceType: 'module',
		plugins: [ // 1
			[
				'typescript', // 2
				{
					dts: true // 3
				}
			]
		]
	} );

    […]
}

Do parsera dodajemy opcję plugins (1), która pobiera tablicę pluginów wraz z opcjami dla nich. Dodajemy do niej plugin typescript (2) wraz z opcją dts ustawioną na true (3), która pozwala na parsowanie właśnie plików .d.ts.

Yay, nasz bundler JS-a właśnie stał się bundlerem plików .d.ts!

Ścieżki do plików bez rozszerzeń

I choć nasz bundler już w teorii powinien radzić sobie z plikami .d.ts, to TS ma kilka przypadłości składniowych, które uniemożliwiają mu sensowne działanie. Jedną z nich jest omijanie rozszerzeń plików w importach, np:

import { Fixture } from './Fixture';

Tak naprawdę import odbywa się z pliku Fixture.d.ts, nie zaś – Fixture. Musimy wziąć na to poprawkę i przygotować prostą funkcję, która będzie nam zamieniać ścieżki z importów na poprawne ścieżki do plików:

function createFilePath( importSpecifier ) {
	if ( !importSpecifier.endsWith( '.d.ts' ) ) { // 1
		return `${ importSpecifier }.d.ts`; // 2
	}

	return importSpecifier; // 3
}

Sprawdzamy, czy ścieżka kończy się rozszerzeniem .d.ts (1) i jeśli nie, to po prostu je dodajemy i zwracamy tak zmodyfikowaną ścieżką (2). W innym wypadku zwracamy oryginalną ścieżkę (3).

Teraz wypada dodać tę zmianę do kodu bundlera. Należy podmienić dwie linijki odpowiadające za wczytanie importowanego pliku na poniższy kod:

const importRelativePath = createFilePath( node.source.value );
const depPath = resolvePath( dir, importRelativePath );

modules.push( ...processModule( depPath ) );

A że tę logikę będziemy wykorzystywać też w innym miejscu (spoilers…), to wyciągnijmy sobie ją od razu do osobnej funkcji, processImport():

function processImport( node, dir, modules ) {
	const importRelativePath = createFilePath( node.source.value );
	const depPath = resolvePath( dir, importRelativePath );

	modules.push( ...processModule( depPath ) );
}

Przekazywane parametry to:

• node – czyli węzeł AST z importem,
• dir – katalog pliku importującego (wzięty z funkcji processModule()),
• modules – tablica modułów (wzięta z funkcji processModule()).

Lepsza obsługa eksportów

Pliki z definicjami typów raczej eksportują typy, więc byłoby miło, gdyby nasz bundler nie wycinał eksportów – ale tylko w głównym pliku (czyli tym, od którego zaczynamy bundle’owanie), bo inaczej dostaniemy niepoprawny składniowo plik, np:

export interface Test {
	[…]
}

export { Test };

Potrzebujemy więc sposobu, aby rozpoznawać, czy aktualnie obsługiwany plik jest tym głównym, czy nie. W tym celu wystarczy dodać parametr isMain do processModule():

function processModule( path, isMain = false ) {
	[…]
}

W chwili, gdy będziemy zaczynać całe bundle’owanie, ustawimy go na true, a we wszystkich innych przypadkach – na false (lub całkowicie pominiemy i pozwolimy przyjąć mu domyślną wartość, czyli właśnie false).

Jednak proste wycinanie wszystkich eksportów z importowanych plików nie zadziała, ponieważ wytnie też konstrukcje typu export interface Test {}, w których deklaracja jest bezpośrednio w eksporcie. Z tego też powodu trzeba zastąpić usuwanie eksportu funkcją handleExport():

function handleExport( path, { isMain, dir, modules } ) {
	const node = path.node;

	if ( node.source ) {
		processImport( node, dir, modules );
	}

	if ( isMain && node.source ) {
		path.replaceWith( exportNamedDeclaration( node.declaration, node.specifiers ) );

		return;
	}

	if ( isMain ) {
		return;
	}

	if ( node.declaration ) {
		path.replaceWith( node.declaration );

		return;
	}

	path.remove();
}

Trochę się tu dzieje, więc przyjrzyjmy się po kolei poszczególnym fragmentom. Na sam początek jest obsługa sytuacji, w których eksport jest połączony z importem (export { Something } from './file'):

const node = path.node; // 1

if ( node.source ) { // 2
	processImport( node, dir, modules ); // 3
}

Na początku pobieramy sobie węzeł eksportu do zmiennej (1), następnie sprawdzamy, czy ma ustawioną własność source (2). To właśnie ona wskazuje na plik, z którego eksportujemy. Jeśli tak, odpalamy na tym eksporcie opisaną już wcześniej funkcję processImport() (3). Wszystkie potrzebne parametry dostajemy z zewnątrz, z funkcji processModule().

Następny fragment dodaje dodatkową logikę dla takich eksportów w głównym pliku. Jest to spowodowane tym, że musimy w nich zamienić eksport z zewnętrznego pliku na eksport lokalnego typu:

export { Fixture } from './Fixture';
// trzeba zmienić na:
export { Fixture };

W tym celu używamy path.replaceWith():

if ( isMain && node.source ) {
	path.replaceWith( exportNamedDeclaration( node.declaration, node.specifiers ) ); // 1

	return; // 2
}

Funkcja exportNamedDeclaration() (1) pochodzi z pakietu @babel/types i służy do tworzenia nowych deklaracji nazwanych eksportów. Przekazujemy do niej dane ze starego eksportu, dzięki czemu powstaje taki sam eksport, ale już bez informacji o zewnętrznym pliku. Z kolei return (2) pozwala zakończyć obsługę tego eksportu w tym miejscu, co pozwala zmniejszyć liczbę zagłębień i else-ów w reszcie funkcji handleExport().

To jest też cała logika dla głównego pliku, więc jeśli w nim jesteśmy, teraz jest pora, by wyjść:

if ( isMain ) {
	return;
}

Następny fragment dotyczy obsługi eksportów połączonych z deklaracją (export interface Test {}) w importowanych plikach (w głównym takich eksportów nie ruszamy, bo i nie ma po co – główny plik powinien bez przeszkód eksportować):

if ( node.declaration ) { // 1
	path.replaceWith( node.declaration ); // 2

	return; // 3
}

Żeby wykryć taki eksport, sprawdzamy, czy zawiera deklarację (1). Jeśli tak, podmieniamy eksport na tę deklarację (2) i wychodzimy z funkcji handleExport() (3).

I w końcu, gdy mamy do czynienia z jakimkolwiek innym rodzajem eksportu, najzwyczajniej w świecie go usuwamy:

path.remove();

To pozwoli pozbyć się z importowanych plików konstrukcji typu export { Fixture }.

I to tyle, stworzyliśmy prymitywny bundler typów!

Możliwe ścieżki rozwoju

Podobnie do “normalnego” bundlera, który był dość prymitywny, tak i bundler typów jest mocno prymitywny i radzi sobie tylko z najprostszymi konstrukcjami. Istnieje zatem szereg możliwych usprawnień, np:

• obsługa aliasów w eksportach – często eksporty zawierają aliasy typu export { default as someName } from './File'; i obecnie bundler całkowicie sobie nie radzi z takimi aliasami (zostawia je bez zmian),
• obsługa składni export = SomeThing; – obecnie ta składnia działa częściowo; po prostu nie jest traktowana jako eksport, więc jest zostawiana bez zmian, co powinno działać w głównym pliku, ale już nie w importowanych,
• dodanie tree shakingu – wiedząc, jakich typów potrzebujemy, możemy importować tylko te potrzebne z poszczególnych plików .d.ts,
• dodanie zabezpieczenia przed konfliktami w importach – niektóre importowane typy mogą mieć takie same nazwy (np. Node z modułu obsługującego HTML i Node z modułu obsługującego SVG), więc warto byłoby się przed tym zabezpieczyć, choćby generując unikatowe nazwy dla wszystkich niepublicznych typów.

To oczywiście nie wszystkie możliwości, jedynie kilka luźnych propozycji. W żadnym razie bundler, jaki stworzyłem, nie jest produkcyjny i przy każdym bardziej zaawansowanym pliku .d.ts wyglebi się na pierwszej nierówności. Do poważnych zastosowań wypadałoby wybrać coś bardziej sprawdzonego, np. rollup-plugin-dts.

Bundler jest dostępny na GitHubie.

Dziurawe zabezpieczenie

Bramkarz był w założeniu narzędziem pokroju Hagany, ale dla projektów, które wykorzystywały natywne moduły ES zamiast, tradycyjnego dla Node.js, systemu modułów CJS. To wymuszało wykorzystanie eksperymentalnego API loaderów. I chociaż całość była dość toporna z powodu ograniczeń składni ESM (m.in. brak dynamicznych eksportów), to działało to nadspodziewanie dobrze.
Tylko że był jeden mały problem: tego typu zabezpieczenie można było banalnie prosto obejść. Wystarczyło stworzyć plik JS z rozszerzeniem .cjs. Dla Node’a oznacza to, że w tym pliku znajduje się kod w składni CJS. Czyli taki, który jest wczytywany przy pomocy require(), nie zaś – import. A więc taki, który omija całe zabezpieczenie dodane przez Bramkarza przy pomocy loadera ESM…

Próba ratowania sytuacji

Na szczęście Node.js posiada flagę --require, która pozwala wczytać na start moduł podany jako wartość tej flagi. W teorii zatem wystarczyłoby przygotować moduł CJS nadpisujący operacje na plikach i dorzucić flagę --require do naszego skryptu odpalającego Bramkarza.

Tylko tutaj pojawia się pierwszy z problemów: Bramkarz korzysta z tzw. top-level await do wczytania konfiguracji. W ESM jest to możliwe, ponieważ moduły są wczytywane asynchronicznie – Node.js spokojnie zaczeka przy wczytywaniu, aż dany moduł się wykona. W CJS jest inaczej – require() jest synchroniczne. To znaczy, że nasz moduł nadpisujący zostanie tak naprawdę wczytany przed tym, jak zdąży cokolwiek nadpisać. Innymi słowy: ktoś może skorzystać z operacji na plikach, zanim te zostaną podmienione na zabezpieczone wersje. Problem można zobaczyć choćby na prostym przykładzie na CodeSandboxie. Odpalenie tej aplikacji da nam taki output:

index.js loaded
async initialized

Główna aplikacja odpala się przed wykonaniem się kodu wewnątrz wczytywanego modułu. W ESM przed taką sytuacją chroni właśnie top-level await.

Niemniej i na to istnieją haki – niekoniecznie działające stuprocentowo dobrze, ale działające.

Istnieje w Node.js moduł node:module, który zawiera całą logikę obsługi modułów CJS. Wśród niej jest (nieudokumentowana) metoda Module._load, służąca właśnie do wczytywania modułów. Nadpisanie jej w teorii pozwala dodać wsparcie dla asynchronicznego require(). A przynajmniej takiego, które poczeka na wczytanie się konfiguracji Bramkarza:

const Module = require( 'node:module' ); // 1
const originalLoad = Module._load; // 2
const somePromise = new Promise( ( resolve ) => { // 3
    setTimeout( () => {
        resolve();
    }, 1000 ); // 4
} );

Module._load = function ( ...args ) { // 5
    somePromise.then( () => { // 6
        return originalLoad( ...args ); // 7
    } );
};

Na sam początek wczytujemy moduł node:module (1). Następnie zapisujemy sobie oryginalną wersję metody Module#_load() do zmiennej (2). Potem tworzymy obietnicę somePromise (3), która będzie emulować wczytywanie się konfiguracji. Jedyne, co robi, to odczekanie sekundy (4). Na samym końcu nadpisujemy Module#_load() (5). Nowa wersja czeka, aż obietnica somePromise zostanie rozwiązana, co można zrobić przy pomocy #then() (6). Po rozwiązaniu obietnicy odpalamy oryginalną metodę Module#load() (7). Taki “loader” można dodać do naszej aplikacji właśnie przy pomocy flagi --require.

Ten przykład również można zobaczyć na CodeSandboxie.

Tylko że tutaj trafiłem na kolejny problem: mój projekt ma zależności. Większość z nich stworzył Sindre Sorhus, który porzucił wsparcie dla CJS jakiś czas temu. I jak moduły CJS da się wczytać wewnątrz ESM, tak w drugą stronę już nie bardzo. Owszem, są na to odpowiednie haki, np. używanie dynamicznych importów, ale to rodzi kolejne problemy (np. konieczność zmiany konfiguracji Rollupa). I to był ten moment, gdy stwierdziłem, że odpuszczam. Zbyt dużo problemów jak na projekt, który jest zwykłym eksperymentem.

I to by było na tyle

Szkoda mi tego projektu, bo bardzo podobała mi się idea zrobienia narzędzia, które pozwalałoby na wprowadzenie do Node’a czegoś na wzór systemu uprawnień. Niemniej trudności, które napotkałem, skutecznie mnie zniechęciły. A już nawet wygenerowałem ładne logo dla projektu przy użyciu Dall·e 2:

No cóż, może Bramkarz doczeka się lepszych czasów, np. Node.js kiedyś porzuci wsparcie dla CJS. Na razie jednak Bramkarz zostaje wysłany na urlop.

Proxy, czyli stary znajomy

Myślałem, że w środku znajdę coś naprawdę ciekawego… i trochę się zawiodłem. Zobaczyłem bowiem rzecz, którą bawię się od dłuższego czasu i którą już nieraz opisywałem tutaj na blogu. Jedyna różnica polega na tym, że Hagana wykorzystuje ją w innych celach.

A o jakiej rzeczy tak w zasadzie mówię? O proxy, przy pomocy którego nie tak dawno odtwarzałem wycinek Immera. Okazuje się, że ten mechanizm można także wykorzystać, żeby lepiej zabezpieczyć swoją aplikację w Node.js. Trzonem w Haganie są bowiem tzw. overrides – funkcje nadpisujące natywne mechanizmy Node’a. Nadpisaniu ulegają m.in. funkcje odpowiedzialne za odczyt i zapis do plików. Każda taka funkcja jest opakowywana w proxy, które przy pomocy pułapki apply wykonuje dodatkową walidację przed faktyczną operacją na plikach. Dzięki temu możliwe jest zabronienie operacji na plikach, które znajdują się poza katalogiem projektu (czyli nici z podkradania /etc/passwd…).

Funkcje odpowiadające za nadpisanie poszczególnych mechanizmów (obsługi plików, wątków roboczych itd.) są odpalane w chwili importu Hagany do naszej aplikacji. I to w sumie tyle – nie ma tutaj nic przesadnie skomplikowanego, a działa to całkiem dobrze.

ESM, czyli zaczynają się problemy

Niemniej pierwsze, co rzuciło mi się w oczy, to fakt, że Hagana była raczej tworzona z myślą o modułach CJS (czyli tych starych, z require()). Intuicja podpowiadała mi, że sposób nadpisywania poszczególnych funkcji nie będzie działał (lub będzie działał częściowo) w przypadku nowych modułów (czyli tych z import).

Najłatwiej wyjaśnić to na prostym przykładzie. Wyobraźmy sobie, że mamy plik fs.mjs, który imituje natywny moduł fs z Node.js. Dla uproszczenia będzie on zawierał tylko jedną funkcję, readFile(). W przypadku natywnego modułu fs funkcja taka dostępna byłaby na co najmniej dwa sposoby:

1. jako własność domyślnego eksportu:

   import fs from 'node:fs';
   
   fs.readFile( 'jakaś/ścieżka', callback );
   

2. jako osobny import:

   import { readFile } from 'node:fs';
   
   readFile( 'jakaś/ścieżka', callback );
   

Stwórzmy zatem moduł, który by działał w taki sposób:

function readFile() {} // 1

const fs = { // 2
	readFile // 3
};

export default fs; // 4
export { readFile }; // 5

Na początku tworzymy funkcję readFile() (1). Następnie tworzymy obiekt fs (2), w którym tworzymy własność readFile zawierającą naszą funkcję (3). Ten obiekt będzie naszym domyślnym eksportem (4). Oprócz tego eksportujemy osobno samą funkcję readFile() (5).

Stwórzmy jeszcze moduł, który będzie próbował nadpisać naszą funkcję readFile():

import fs, { readFile } from './fs.mjs'; // 1

console.log( fs.readFile === readFile ); // true – 2

fs.readFile = () => {}; // 3

console.log( fs.readFile === readFile ); // false – 4

readFile = () => {}; // error – 5

Na samym początku importujemy zarówno domyślny eksport, jak i bezpośrednio funkcję readFile() (1). Sprawdzamy sobie, czy fs#readFile() to ta sama funkcja co readFile() (2). I faktycznie, jest to ta sama funkcja. Następnie nadpisujemy fs#readFile() nową funkcją (3) i ponawiamy sprawdzenie (4). Tym razem otrzymujemy już fałsz. Natomiast próba nadpisania bezpośrednio readFile() (5) kończy się błędem.

A to dlatego, że w uproszczeniu importy można traktować jako zmienne zadeklarowane przy pomocy const. Z tego też powodu można mutować zaimportowany obiekt fs, ale już nie można nadpisać importowanych wartości. Innymi słowy: w przypadku ESM użytkownik będzie zabezpieczony wyłącznie, gdy będzie używał fs#readFile(), ale gdy zaimportuje readFile() bezpośrednio, to ominie całe nasze zabezpieczenie. A to brzmi jak naprawdę poważny problem.

Czemu jednak działa to w CJS? Ponieważ tam eksportowany jest po prostu obiekt z poszczególnymi funkcjami. Nawet zrobienie

const { readFile } = require( 'node:fs' );

oznacza jedynie destrukturyzację tego obiektu. ESM są pod tym względem, niestety, bardziej kłopotliwe.

Bramkarz, czyli próba obejścia

Zacząłem się zastanawiać, czy jest jakiś sposób, aby być w stanie nadpisać obydwa sposoby importowania funkcji obsługujących pliki w przypadku, gdy aplikacja korzysta z natywnej obsługi ESM w Node.js. Jedyną rzeczą, jaka przychodziła mi do głowy, były niestandardowe loadery. Ich zamysł opisałem już kiedyś na blogu w artykule poświęconym wczytywaniu plików .html bezpośrednio w Node.js. Co prawda, od tamtego czasu dość znacząco zmieniła się składnia rozwiązania, ale podstawy teoretyczne pozostały te same: dzięki niestandardowym loaderom możemy podstawić dowolny kod w miejsce konkretnego modułu.

Taki niestandardowy loader zazwyczaj składa się z dwóch zasadniczych części – asynchronicznej funkcji resolve(), która przerabia nazwy modułów (takie jak node:fs czy @comandeer/rollup-lib-bundler) na URL-e, oraz asynchronicznej funkcji load(), która zajmuje się faktycznym wczytywaniem modułów. Całość jest stosunkowo prosta i w zupełności wystarczająca do wykonania tego, co chciałem.

Zamysł był prosty: funkcja resolve() będzie otrzymywać informacje o tym, kiedy program próbuje załadować moduł node:fs i na ich podstawie będzie decydować, czy należy wczytać nasz podmieniony moduł. Loader, oprócz samej nazwy/URL-a modułu, dostaje także dodatkowe informacje, w tym o rodzicu danego modułu – czyli o module, który wczytał aktualnie importowany moduł. Postanowiłem to wykorzystać. W chwili, gdy program chciał wczytać moduł node:fs, podmieniałem go na adres tego nadpisującego. Oczywiście wewnątrz tego nadpisującego modułu musiałem importować oryginalne node:fs. Dzięki informacji o rodzicu modułu mogłem ominąć problem wywołania nieskończonej pętli importów. Nie podmieniałem bowiem node:fs w momencie, gdy był importowany ze środka mojego nadpisującego modułu.

Podsumowując:

1. Funkcja resolve() sprawdza, czy program nie próbuje importować node:fs.
2. Jeśli tak, sprawdzany jest rodzic modułu i jeśli jest inny od mojego nadpisującego modułu (dla ułatwienia nazwijmy go bramkarz:fs), URL node:fs podmieniany jest na URL modułu bramkarz:fs.
3. Moduł bramkarz:fs jest wczytywany przez domyślny loader Node’a.
4. Moduł bramkarz:fs wczytuje oryginalny moduł node:fs.
5. Funkcja resolve() ignoruje ten import, bo widzi, że rodzicem jest bramkarz:fs.
6. Mooduł bramkarz:fs zwraca funkcje operujące na plikach, które są opakowane w proxy sprawdzające, czy podana ścieżka do pliku powinna być dostępna dla programu.

Brzmi to dość skomplikowanie i na pierwszy rzut oka jest nieco przekombinowane, ale na tę chwilę nie przychodzi mi do głowy żaden inny sposób, w jaki można by to rozwiązać.

A skoro już siadłem do zabawy nad tym, stwierdziłem, że może spróbuję napisać jakieś sensowne narzędzie. Tak narodził się Bramkarz. Co prawda jest na bardzo wczesnym etapie rozwoju, ale można już podpatrzeć w nim niestandardowy loader, o którym przed chwilą pisałem. Dodatkowo doszedłem do wniosku, że bardziej przyjazne użytkownikowi będzie stworzenie prostego programu konsolowego, który się będzie odpalać zamiast Node’a (czyli bramkarz . zamiast node .). On już zadba o to, by loader był dołączany do uruchamianego programu i wykonywał w tle swoją robotę, niemalże niezauważalnie dla użytkownika. Natomiast sama konfiguracja została wyrzucona do osobnego pliku, .bramkarzrc.json.

ESM, czyli moje problemy mają problemy

Chyba największym problemem (czy też – upierdliwością) jest mocno statyczna składnia ESM. W idealnym świecie nadpisanie modułu wyglądałoby tak:

import * as fs from 'node:fs'; // 1

const newFS = { ...fs }; // 2

newFS.readFile = newFS.default.readFile = createProxy(); // 3

export { ...newFS }; // 4

Na początku importuję sobie nasz moduł (1). Następnie tworzę jego kopię (2) i nadpisuję w niej interesujące mnie rzeczy (3). Następnie używam destrukturyzacji w eksporcie, żeby wyeksportować wszystko, co jest w newFS (4).

Innymi słowy zakładałbym, że destrukturyzacja w eksporcie robiłaby to samo co kod poniżej:

export { fs.default as default };
export { fs.readFile as readFile };
// itd.

W rzeczywistości ani pierwszy, ani drugi kod nie działa… Jestem więc skazany na rzeźbienie wszystkich eksportów ręcznie:

import * as fs from 'node:fs';

const newFS = { ...fs };

newFS.readFile = newFS.default.readFile = createProxy();

const { readFile } = newFS;

export default newFS.default;
export { readFile };

Tak na razie wygląda nadpisanie fs w Bramkarzu. Powyższy kod tworzy tak naprawdę moduł jedynie z metodą readFile() oraz domyślnym eksportem. Reszta pojedynczych eksportów jest stracona, dopóki nie będę miał czasu i chęci, by je na powrót dodać… A że eksporty mogą być tylko na najwyższym poziomie, bez żadnego zagnieżdżenia, to odpada nawet pętla for...of do przeiterowania po newFS i stworzenia poszczególnych eksportów. To naprawdę trzeba zrobić wszystko ręcznie.

Rozwój, czyli co dalej?

Nie wiem, czy będę próbował rozwijać Bramkarza i czy w ogóle wypuszczę jakąkolwiek wersję na npm-ie. Na ten moment mnie mocno zmęczył, głównie ze względu na to, jak mało przyjazne wydają się narzędzia do pracy z natywnymi ESM w Node w porównaniu do modułów CJS, które dzięki transpilatorom i tak mogą wyglądać jak ESM.

Z drugiej strony podejście Bramkarza wydaje się nieco bezpieczniejsze niż Hagany. Loader, który działa w tle, niezależnie od programu, który ma chronić, brzmi jak coś bardziej odpornego na próby przechytrzenia, niż nadpisywanie modułów dopiero w chwili importu zabezpieczającego modułu. Dodatkowo jest to bardziej przezroczyste dla użytkownika, który po prostu odpala program i ten jest chroniony z automatu.

Niemniej sam pomysł takiego zabezpieczenia mi się podoba. Zdecydowanie brakuje czegoś takiego wbudowanego w Node.js. Deno robi to zdecydowanie lepiej. Może kiedyś dochrapiemy się tego także w Node.js. Na ten jednak moment rozwiązania pokroju Hagany czy właśnie Bramkarza wydają się wartą rozważenia namiastką.

Dlaczego nie gotowe rozwiązania?

“Przecież pewnie jest pełno gotowych spinnerów w npm!” – zakrzyknie Co Bardziej Rozgarnięty Czytelnik. I muszę przyznać Ci, drogi Czytelniku, rację. Tak, jest ich pełno. Ale mój szybki research przekonał mnie, że większość ma mało przyjazne API, nie była aktualizowana od długiego czasu lub ogólnie wydaje się nie być rozwijana. Na szczęście istnieje Sindre Sorhus, który w JS napisał już wszystko, więc także i kręciołka. Tak trafiłem na pakiet ora, który ze wszystkich znalezionych przeze mnie spinnerów miał najprzyjaźniejsze API. Nie szukając zatem dłużej, zainstalowałem i… okazało się, że z bliżej niezidentyfikowanych powodów ora nie działała. Spinner często się duplikował, a dodatkowo nie był widoczny w terminalu nawet po wywołaniu metody do jego usuwania. Po 1.5 godziny debugowania doszedłem do wniosku, że to przecież tylko spinner i nie ma sensu marnować na to większej ilości czasu.

Sięgnąłem zatem po opcję atomową. Wychodząc z logicznego założenia, że spinner, który pokazuje się w npm przy instalacji zależności, musi działać (w końcu wyświetlany jest jakieś… kilkadziesiąt milionów razy miesięcznie), poszperałem i znalazłem pakiet gauge. I faktycznie, działa i już go wdrożyłem w swoich projektach potrzebujących kręciołka. Tylko że jest jeden problem. Tak, jak większość narzędzi wykorzystywanych w npm, tak i ten ma API równie przyjemne, co jedzenie kawałków szkła zalanych kwasem siarkowym na śniadanie. Prosty przykład: trzeba ręcznie wywoływać każdą klatkę animacji spinnera. W chwili, gdy wdrażałem spinner, był także problem związany z brakiem jednej z zależności w package.json, ale widzę, że został rozwiązany kilka dni temu.

Dlatego doszedłem do wniosku, że sprawdzę, czy nie da się napisać jakiegoś prymitywnego kręciołka samodzielnie, bez potrzeby uciekania się do gotowców. I okazuje się, że jak najbardziej się da i nie jest to specjalnie trudne!

Kontrola nad terminalem

Jednym z najpopularniejszych pakietów do pracy z terminalem jest chalk (stworzony przez Sindre’a Sorhusa – a jakże!). Pakiet ten pozwala na kolorowanie komunikatów wyświetlanych w terminalu. Dlaczego o nim wspominam? Bo wykorzystuje on specjalne sekwencje znaków, które terminal odczytuje jako polecenie przełączenia na odpowiedni kolor, np.

console.log( '\x1b[31mTest' );

Powyższy kod odpalony w Node.js wyświetli czerwony tekst “Test”. Odpowiedzialny za to jest kod \x1b[31m. Kodów jest o wiele, wiele więcej i oprócz kolorów pozwalają też na kontrolowanie m.in. pozycji kursora.

Jedynym problemem może być wsparcie dla tego typu sekwencji ucieczki (jak to się ładnie nazywa). Jeśli wsparcie na Linuksach czy macOS-ach jest pewne, tak problem może pojawić się na Windowsie. Z własnego doświadczenia mogę powiedzieć, że na Windowsie 10 powinno działać – zarówno w standardowym cmd, jak i w PowerShellu. Na starszych Windowsach prawdopodobnie będziemy musieli obejść się smakiem.

Ogólne założenia kręciołka

Zasada działania kręciołka jest dość prosta. Jak przyjrzymy się, jak zachowuje się terminal, to zauważymy, że wypluwa informacje linia po linii. Każdy console.log to kolejna linia. Z kolei kręciołek “siedzi” cały czas w tej samej linii i w dodatku jest animowany. Musimy zatem znaleźć sposób na to, aby zablokować przechodzenie do kolejnej linii…

Albo podejść do sprawy z innej strony. Zablokowanie przechodzenia do kolejnej linii jest tak naprawdę równoznaczne z wyczyszczeniem aktualnej linii i zapisaniem w niej nowej treści. Zatem przy każdej klatce animacji usuwamy aktualną linię w terminalu i wstawiamy w niej nową zawartość. Można to zrobić przy pomocy odpowiednich kodów. Najpierw należy przejść na początek aktualnej linii przy pomocy \r (czyli znaku powrotu karetki), a następnie użyć kodu \x1b[K, który powoduje usunięcie zawartości linii od pozycji kursora do samego jej końca. Po usunięciu zawartości linii można następnie wstawić kolejną klatkę animacji. Cały mechanizm przypomina nieco używanie requestAnimationFrame w przeglądarce. Tam też jesteśmy zmuszeni do kontrolowania każdej klatki osobno.

Pozostaje jeszcze jeden problem: console.log wymusza przejście do nowej linii na końcu każdego wyświetlonego komunikatu. A tego nie chcemy. Tu na szczęście przychodzi nam z pomocą fakt, że process.stdout (czyli tzw. standardowe wyjście, a więc w naszym wypadku terminal) jest strumieniem. Dzięki temu możemy całkowicie pominąć pośrednika w postaci console i wypisywać komunikaty bezpośrednio. Da nam to całkowitą kontrolę nad formatowaniem, w tym nad znakami nowej linii. A to dokładnie to, czego potrzebujemy, by upewnić się, że spinner będzie prawidłowo odświeżany.

Prototyp

Napiszmy więc szybki prototyp. Stwórzmy sobie plik spinner.js. Pierwsze, co będziemy chcieli zrobić, to stworzyć sobie tablicę klatek ze spinnerem. W naszym wypadku będą to kreski:

const spinner = [
	'/',
	'-',
	'\\',
	'|'
];

Następnie chcemy napisać prostą funkcję, która będzie pobierała poszczególne klatki spinnera. Nazwijmy ją prepareFrame:

const spinner = [
	…
];
let currentFrame = 0; // 1

function prepareFrame() {
	return spinner[ currentFrame++ % spinner.length ]; // 2
}

Tworzymy sobie licznik currentFrame (1), który będzie nam wskazywał, która klatka animacji powinna być aktualnie wyświetlana. Następnie w dość przerażająco wyglądającej linijce (2) pobieramy potrzebną nam ramkę. Rozbijmy tę linijkę na części.

currentFrame++ oznacza, że wartość currentFrame zostanie zwiększona o 1 po wykonaniu działania obecnego w tej linijce. To oznacza, że dla pierwszego wywołania prepareFrame możemy wyrażenie currentFrame++ zamienić na 0. Z kolei spinner.length możemy podmienić na 4 (bo tyle mamy kresek w tablicy spinner). Otrzymujemy zatem mniej groźnie wyglądające działanie 0 % 4 – czyli 0. Dla kolejnego wywołania będziemy mieli 1 % 4 – czyli 1 itd. Wykorzystanie operatora % pozwala nam na nieresetowanie licznika, gdy ten przekroczy długość tablicy, np. 8 % 4 da nam 0, 9 % 4 – 1 itd.

Liczbę uzyskaną z tego działania przekazujemy jako indeks do tablicy spinner i zwracamy element znajdujący się pod tym indeksem. W ten sposób wyciągamy odpowiednią kreskę z tablicy.

Jednak sama kreska musi być też narysowana i podmieniana przez nowe co określony czas. Napiszmy zatem funkcję drawFrame, która będzie to robić:

[…]
function drawFrame() {
	const nextFrame = prepareFrame(); // 2

	console.log( nextFrame );

	setTimeout( drawFrame, 60 ); // 1
}

drawFrame(); // 3

Jeśli teraz odpalimy nasz program, zauważymy, że w nieskończoność wyświetla kreski z tablicy po kolei (program można ubić naciskając Ctrl + C, również na macOS-ie). Osiągnęliśmy to dzięki zastosowaniu setTimeout (1), które wywołuje rysowanie kolejnej klatki animacji (czyli dokładnie jak przy requestAnimationFrame!). Wykorzystujemy tutaj także funkcję prepareFrame do pobierania kolejnych klatek (2). Na samym końcu wywołujemy funkcję drawFrame (3), by rozpocząć animację.

Oczywisty problem z aktualnym podejściem polega na tym, że wykorzystuje console.log, przez co uzyskujemy każdą klatkę w nowej linii. Zmieńmy zatem nieco kod funkcji drawFrame i zastosujmy strumień:

[…]

function drawFrame() {
	const nextFrame = prepareFrame();

	process.stdout.write( nextFrame, 'utf8', () => { // 1
		setTimeout( drawFrame, 60 ); // 2
	} );
}

[…]

Pojawiła się funkcja process.stdout.write (1). Służy ona do wysyłania danych do strumienia. Funkcja ta przyjmuje trzy argumenty: tekst (dane), który chcemy umieścić w strumieniu, kodowanie tego tekstu oraz callback, który zostanie wywołany po umieszczeniu danych w strumieniu. W naszym wypadku po prostu kolejkujemy rysowanie kolejnej klatki (2).

Jeśli odpalimy program teraz, zauważymy, że kolejne klatki co prawda wyświetlają się w tej samej linii, ale poprzednie nie są usuwane. A to dlatego, że nie usuwamy tego, co jest w tej linii. W tym celu najlepiej będzie zmienić funkcję prepareFrame, by dodawała do klatki także odpowiednie sekwencje ucieczki:

function prepareFrame() {
	const eraseLineCmd = '\r\x1b[K'; // 2
	const nextFrame = spinner[ currentFrame++ % spinner.length ]; // 3

	return eraseLineCmd + nextFrame; // 1
}

Teraz funkcja zwraca ramkę (1), która składa się z dwóch rzeczy: kodu, który przesuwa kursor na początek linii, a następnie usuwa jej zawartość (2), oraz samej ramki (3). Po odpaleniu naszego programu w takiej wersji, uzyskamy w końcu ładny kręciołek 🎉!

Cały kod wygląda tak:

const spinner = [
	'/',
	'-',
	'\\',
	'|'
];
let currentFrame = 0;

function prepareFrame() {
	const eraseLineCmd = '\r\x1b[K';
	const nextFrame = spinner[ currentFrame++ % spinner.length ];

	return eraseLineCmd + nextFrame;
}

function drawFrame() {
	const nextFrame = prepareFrame();

	process.stdout.write( nextFrame, 'utf8', () => {
		setTimeout( drawFrame, 60 );
	} );
}

drawFrame();

Co dalej?

Oczywiście taki kręciołek można rozwijać na wiele sposobów. Jednym z nich jest dodanie wsparcia dla etykiet tekstowych wyświetlanych obok animowanego kręciołka. Warto także dodać wykrywanie, czy aby na pewno terminal użytkownika wspiera takie rzeczy. No i w końcu warto to wszystko otoczyć w jakieś przyjemne API, by można było kontrolować, kiedy spinner ma się pokazywać i ukrywać. Jak to wygląda (czy też będzie wyglądać) u mnie, można zobaczyć na GitHubie.

PS jakby ktoś pytał, NIH to dla mnie taki komiks internetowy.

Zasada działania

Zacznijmy od szybkiego wyjaśnienia, czym jest code coverage (pokrycie kodu)? To wskażnik informujący nas o tym, ile kodu faktycznie zostało pokrytych testami automatycznymi. Jeśli jakiś kod (np. funkcja bakeCake) nie został wykonany w czasie testów, to znaczy, że jest tak naprawdę nieprzetestowany (trudno przetestować ciasto bez jego wcześniejszego upieczenia!). Stąd też code coverage pozwala wyłapać tego typu sytuacje i dopisać brakujące testy.

Ale jak to dokładnie działa? Bodaj najpopularniejszym narzędziem do code coverage w światku JS jest IstanbulJS i to właśnie jemu się przyjrzymy. Standardowo używa się go przy pomocy narzędzia CLI, nyc, które “dokłada się” do polecenia testującego, np. nyc mocha tests/*.js. W ten sposób dokładamy do naszych testów uruchamianych przy pomocy Mocha ładne zliczanie pokrycia kodu. Od kuchni jednak Istanbula podzielić można na 3 podstawowe części:

• instrumenter – przerabiającą kod źródłowy tak, by dało się wyliczyć pokrycie kodu;
• hook – podpinającą instrumenter do każdego wczytywanego w Node.js przez require modułu (analogicznie do tego, jak opisywałem to kiedyś na blogu);
• reporter – przerabiający wyniki uzyskane dzięki instrumenterowi na format zrozumiały dla maszyn i/lub ludzi.

Najciekawszy jest zdecydowanie instrumenter, bo to w nim odbywa się cała magia związana z wyliczaniem pokrycia kodu. Zainstalujmy go zatem i zobaczmy, co robi z kodem źródłowym:

npm install istanbul-lib-instrument

Teraz stwórzmy prosty skrypt, który będzie z niego korzystał:

const { createInstrumenter } = require( 'istanbul-lib-instrument' ); // 1

const instrumenter = createInstrumenter(); // 2
const instrumentedCode = instrumenter.instrumentSync( `const hello = () => { // 3
    console.log( 'Hello, world!' );
};

hello();`, 'virtual-file.js' ); // 4

console.log( instrumentedCode ); // 5

Na początku importujemy funkcję createInstrumenter (1) , która jest fabryką instrumenterów. Następnie tworzymy jeden z domyślnymi opcjami (2). Dzięki temu możemy wywołać jego metodę instrumentSync i przerobić podany kod JS (3). Warto przy tym zauważyć, że kod podajemy jako string. Wynika to z tego, że instrumenter jest w zdecydowanej większości przypadków wywoływany przy pomocy hooka, a hooki dostają kod wczytywanych modułów jako string. W naszym przypadku przykładowy kod do pokrycia to:

const hello = () => {
    console.log( 'Hello, world!' );
};

hello();

Drugi parametr (4) to nazwa pliku, z jakiego pochodzi kod i najczęściej zostaje pobrana przez hook. W naszym wypadku nazwa pliku jest nieistotna, więc można tu wpisać cokolwiek. Na samym końcu wyświetlamy otrzymany kod (5).

Odpalmy zatem nasz skrypt:

node nazwa-pliku-ze-skryptem

Powinniśmy uzyskać coś takiego:

function cov_2mvg7hpc0f(){var path="virtual-file.js";var hash="c0f42c29fc01993cc28c18384ed0d61fa827b717";var global=new Function("return this")();var gcv="__coverage__";var coverageData={path:"virtual-file.js",statementMap:{"0":{start:{line:1,column:14},end:{line:3,column:1}},"1":{start:{line:2,column:4},end:{line:2,column:35}},"2":{start:{line:5,column:0},end:{line:5,column:8}}},fnMap:{"0":{name:"(anonymous_0)",decl:{start:{line:1,column:14},end:{line:1,column:15}},loc:{start:{line:1,column:20},end:{line:3,column:1}},line:1}},branchMap:{},s:{"0":0,"1":0,"2":0},f:{"0":0},b:{},_coverageSchema:"1a1c01bbd47fc00a2c39e90264f33305004495a9",hash:"c0f42c29fc01993cc28c18384ed0d61fa827b717"};var coverage=global[gcv]||(global[gcv]={});if(!coverage[path]||coverage[path].hash!==hash){coverage[path]=coverageData;}var actualCoverage=coverage[path];{// @ts-ignore
cov_2mvg7hpc0f=function(){return actualCoverage;};}return actualCoverage;}cov_2mvg7hpc0f();cov_2mvg7hpc0f().s[0]++;const hello=()=>{cov_2mvg7hpc0f().f[0]++;cov_2mvg7hpc0f().s[1]++;console.log('Hello, world!');};cov_2mvg7hpc0f().s[2]++;hello();

Jak widać, kod został mocno przerobiony. Co się jednak tak właściwie dzieje? Otóż Istanbul dorzucił do każdego wyrażenia w naszym kodzie JS licznik, w postaci mapaPokrycia.s[ numerWyrażenia ]. Na początku mapaPokrycia zawiera listę wszystkich występujących w kodzie wyrażeń wraz z liczbą ich wywołań w trakcie testów (na start wynoszącą 0). Jeśli po zakończeniu testów przy danym wyrażeniu w mapie wciąż będzie widnieć 0, to znaczy, że nie zostało ono przetestowane.

Sprawdzanie natomiast, które wyrażenie zostało wykonane, odbywa się poprzez “doklejenie” do wyrażenia odpowiedniej inkrementacji licznika, np.:

mapaPokrycia.s[ 1 ]++;console.log('Hello, world!');

Tym sposobem, gdy test dojdzie do linijki z console.log, równocześnie zmieni się wartośc licznika dla tego console.log. Dostawienie inkrementacji bezpośrednio przed sprawdzanym wyrażeniem pozwala także na sprawdzanie wyrażeń wewnątrz if–ów i innych bloków (np. funkcji).

Osobne liczniki istnieją dla funkcji czy odgałęzień if–ów. I połączenie tych wszystkich liczników daje nam pełny obraz pokrycia kodu w danym pliku. Znając liczbę wszystkich wyrażeń w danym pliku i wiedząc, które z nich nie zostały wywołane ani razu, obliczenie procentowego pokrycia kodu testami jest już proste.

Warto tutaj także dodać, w jaki sposób Istanbul po zakończeniu testów jest w stanie zebrać dane ze wszystkich plików. Wszystkie mapy pokrycia przechowywane są bowiem w… zmiennej globalnej (w przypadku Node.js to zmienna doczepiona do global). To tak naprawdę jedyny sposób, żeby zebrać w jednym miejscu dane z wielu modułów, które w innym wypadku są od siebie całkowicie odizolowane. Zatem jeśli szukacie dobrego wykorzystania zmiennych globalnych, to właśnie ono – zbieranie informacji o code coverage.

Implementacja

Skoro wiemy już, jak działa narzędzie do code coverage, zabierzmy się do napisania własnego! Oczywiście będzie ono o wiele prostsze od Istanbula i będzie zliczać wyłącznie pokrycie funkcji.

Przygotowanie środowiska

Na sam początek trzeba sobie przygotować środowisko pracy. Stwórzmy zatem katalog coverage-sample i wygenerujmy plik package.json przy pomocy komendy:

npm init -y

Z racji tego, że nasze rozwiązanie będzie działać podobnie do pokazanego wcześniej nyc, musimy dodać jeszcze pole bin do wygenerowanego package.json:

"bin": "index.js"

Teraz pora na zainstalowanie zależności. Będą nam potrzebne trzy:

• @babel/core – zajmująca się dodawaniem liczników do kodu;
• pirates – zajmująca się dodawaniem dodawania przez Babela;
• @babel/types – zawierająca typy dla Babela, bo stwierdzili, że trzymanie ich osobno będzie wygodniejsze.

Wypada je zatem zainstalować:

npm install @babel/core pirates @babel/types

Główny plik

Mając już postawione środowisko, możemy przystąpić do pisania kodu. Zaczniemy od pliku index.js, który będzie równocześnie programem wykonywalnym (odpowiednikiem nyc):

#!/usr/bin/env node
// ↑1
const { resolve: resolvePath } = require( 'path' ); // 8
const addHook = require( './src/hook' ); // 2
const instrument = require( './src/instrumenter' ); // 3
const report = require( './src/reporter' ); // 4

global.__coverage__ = {}; // 5

addHook( instrument ); // 6

const entryPath = resolvePath( process.cwd(), process.argv[ 2 ] ); // 7

require( entryPath ); // 9

report( global.__coverage__ ); // 10

Na samym początku wstawiamy shebang (1), który informuje terminal, jaki program powinien być użyty do uruchomienia tego pliku (w tym wypadku Node.js). Następnie załączamy poszczególne elementy naszego narzędzia (do ich tworzenia przystąpimy za chwilę): hook (2), instrumenter (3) oraz reporter (4). Tworzymy też globalny obiekt, który będzie przechowywał informacje o pokryciu kodu (5). Cała magia ukryta jest za dodaniem hooka (6). Funkcja ta jako argument przyjmuje instrumenter – bo chcemy, żeby wszystkie załączane pliki były instrumentowane. Następnie ustalamy ścieżkę do modułu z testami (7) przy użyciu funkcji resolve z wbudowanego modułu path (8). Ścieżkę tworzymy łącząc ścieżkę do katalogu roboczego (a więc katalogu, z którego ktoś odpalił nasze narzędzie) oraz ścieżkę przekazaną do samego programu. Tablica process.argv zawiera wszystkie argumenty z linii poleceń:

coverage-sample /ścieżka

W tym wypadku /ścieżka jest 3 elementem tej tablicy (po ścieżce Node’a oraz nazwie samego programu) – stąd w kodzie wykorzystujemy process.argv[ 2 ].

Następnie po prostu wczytujemy moduł z testami (9), co powoduje wykonanie się zawartego w nim kodu, a przy okazji – liczników wstrzykniętych przez nasze narzędzie. Na samym końcu wyświetlamy wyniki zebrane w zmiennej globalnie w przyjaznej użytkownikowi formie (10).

Reporter

Przejdźmy zatem do pliku reportera – src/reporter.js – bo jest najmniej ciekawy i w sumie istnieje tylko po to, żeby całość spełniała normę estetyczną. Plik wygląda tak:

module.exports = ( coverageData ) => { // 1
	const { all, covered } = Object.entries( coverageData ).reduce( ( data, [ , { functions } ] ) => { // 2
		data.all += functions.length;
		data.covered += functions.reduce( ( covered, func ) => {
			return covered + func;
		}, 0 );

		return data;
	}, { all: 0, covered: 0 } );

	console.log( `All functions: ${ all }
Covered functions: ${ covered }
Coverage: ${ Math.round( covered / all * 100 ) }%` ); // 3
};

Cały plik składa się z eksportowanej funkcji (1), która jako argument przyjmuje zmienną globalną z danymi pokrycia. Wyciągamy z niej potrzebne nam dane przy pomocy Object.entries + [].reduce (2), formatujemy i wyświetlamy w konsoli (3). W sumie tyle – nic ciekawego się tutaj nie dzieje.

Hook

Przejdźmy zatem do hooka (w pliku src/hook.js), bo ten jest już zdecydowanie bardziej ciekawy:

const { addHook } = require( 'pirates' ); // 3

module.exports = ( instrument ) => { // 1
	addHook( ( code, path ) => { // 2
		if ( path.includes( '/tests/' ) ) { // 5
			return code; // 6
		}

		const instrumentedCode = instrument( code, path ); // 7

		return instrumentedCode; // 8
	}, { exts: [ '.js' ] } ); // 4
};

Cały plik to znowu eksportowana funkcja (1), która jako argument tym razem przyjmuje instrumenter. W jej środku wywołujemy funkcję addHook (2) z biblioteki pirates (3). Nasz hook będzie działał tylko na pliki z rozszerzeniem .js (4). Na samym początku odsiewamy wszystkie pliki testów (5). Dodanie liczników do plików testów nie ma sensu. Nie dość, że nie interesuje nas pokrycie kodu w testach a jedynie w samym kodzie aplikacji, to dodatkowo może to zaciemniać obraz. Stąd kod testów zostawiamy w spokoju i zwracamy go niezmieniony (6). Natomiast całą resztę kodu traktujemy naszym instrumenterem (7) i tak zmodyfikowany kod zwracamy (8). Dzięki temu każde wczytanie dowolnego modułu wczyta kod z dodanymi licznikami.

Instrumenter

W końcu przyszła pora na danie główne – instrumenter! Zacznijmy od stworzenia pliku src/instrumenter.js. Jego główną częścią będzie funkcja instrument, którą będziemy eksportować, a która przyjmuje dwa parametry – kod do przetworzenia i ścieżkę do pliku, z którego kod pochodzi:

function instrument( code, filePath) {}

module.exports = instrument;

Wewnątrz tej funkcji będziemy chcieli pobrać wszystkie deklaracje funkcji i wstawić do nich licznik. W przeciwieństwie do mojego wcześniejszego artykułu o AST, tym razem posłużymy się API wyższego poziomu, jakie jest udostępniane przez pakiet @babel/core – funkcją transformSync:

const { transformSync } = require( '@babel/core' ); // 1

function instrument( code, filePath ) {
	const instrumentedCode = transformSync( code, { // 2
		plugins: [ // 3
			function codeCoverage() { // 4
				return { // 5
					visitor: { // 6
						FunctionDeclaration( path ) { // 7
						}
					}
				};
			}
		]
	} );

	return instrumentedCode.code; // 8
}

Na samym początku importujemy tę funkcję (1). Następnie, wewnątrz instrument, wywołujemy ją, przekazując jej jako 1. parametr kod do przetworzenia (2). Drugi parametr to obiekt opcji. W naszym wypadku chcemy tam przekazać plugin, który będzie dodawał liczniki do kodu. W tym celu musimy dorzucić opcję plugins (3) i sam plugin w formie funkcji (4). Babel pozwala pluginom używać wzorcu Wizytatora. Innymi słowy: można stworzyć funkcję, która będzie “wizytować” każdy węzeł w AST. Co więcej, można wybrać typ węzłów dla naszego wizytatora, dzięki czemu odwiedzi tylko odpowiednie węzły. Żeby stworzyć wizytatora, nasz plugin musi zwróci obiekt (5) z własnością visitor (6). Natomiast sam wizytator musi mieć nazwę taką samą, jak typ węzła, który chcemy “wizytować” – w naszym wypadku FunctionDeclaration (7). Od tej chwili nasz wizytator będzie wywoływany za każdym razem, gdy Babel natrafi na deklarację funkcji. Na samym końcu zwracamy przetworzony kod (8).

Funkcja transformSync zawiera w sobie wszystko to, co wcześniej robiliśmy przy pomocy odpowiednich pakietów Babela, a więc: parsuje kod do AST, trawersuje go i modyfikuje, a na końcu na powrót generuje kod JS. To w połączeniu ze wzorcem Wizytatora tworzy przyjemny sposób na modyfikowanie AST.

Co jednak dokładnie będzie robił nasz wizytator? Wiemy, że ma dodawać liczniki do funkcji – tak, aby zliczać, czy są wywoływane. Najpewniej będzie to zrobić, dodając go jako pierwsze wyrażenie w ciele funkcji:

function deklaracjaFunkcji() {
    // Tutaj chcemy umieścić licznik.
    […]
}

Umieszczenie licznika w ciele funkcji gwarantuje nam, że zostanie uruchomiony jedynie wówczas, gdy sama funkcja zostanie wywołana. Natomiast umieszczenie go na samym początku ciała funkcji pozwala ominąć nam wszystkie klauzule strażnicze i inne potencjalne problemy, które mogłyby zaciemnić obraz. Co więcej, sam początek ciała nie nastręcza trudności związanych choćby z potrzebą wstawiania licznika przed return, jeśli chcielibyśmy go umieszczać na końcu ciała funkcji (bo znajdując się po return nigdy nie zostałby uruchomiony).

Zatem kod naszego wizytatora powinien wyglądać tak:

FunctionDeclaration( path ) {
    const counter = createCounter( filePath ); // 1

    path.get( 'body' ).unshiftContainer( 'body', counter ); // 2
}

Na samym początku tworzymy licznik (1), a następnie wstawiamy go na początek ciała funkcji (2).

Zanim przejdziemy do funkcji tworzącej licznik, wypada też zadbać o to, by nasz instrumenter zapisywał informacje o funkcjach i ich pokryciu dla każdego pliku, jaki przetwarza. W tym celu stwórzmy tablicę functions, która później będzie lądować w zmiennej globalnej:

function instrument( code, filePath ) {
	const functions = []; // 1

	const instrumentedCode = transformSync( code, {
		plugins: [
			function codeCoverage() {
				return {
					visitor: {
						FunctionDeclaration( path ) {
							const counter = createCounter( filePath, functions.length ); // 3

							path.get( 'body' ).unshiftContainer( 'body', counter );
							functions.push( 0 ); // 2
						}
					}
				};
			}
		]
	} );

	global.__coverage__[ filePath ] = { // 4
		functions
	};

	return instrumentedCode.code;
}

Na samym początku funkcji instrumentującej tworzymy pustą tablicę functions (1). Za każdym razem, gdy wizytator natrafia na kolejną funkcję, wrzucamy do tej tablicy liczbę wywołań dla kolejnej funkcji (2). Natomiast sama funkcja tworząca liczniki powinna też wiedzieć, dla której konkretnie funkcji go tworzy – a więc dostawać indeks tej funkcji w tablicy functions. W tym celu zastosowane zostało functions.length (3). Działa to, ponieważ długość tablicy jest zawsze o jeden większa niż numer ostatniego indeksu. A to oznacza, że nowo dodawana funkcja ma indeks równy długości tablicy. Na samym końcu dorzucamy tablicę functions do globalnej zmiennej __coverage__ pod kluczem stworzonym ze ścieżki do pliku modułu (4).

Przejdźmy zatem do funkcji tworzącej sam licznik:

const {
	expressionStatement,
	identifier,
	stringLiteral,
	numericLiteral,
	memberExpression,
	updateExpression } = require( '@babel/types' ); // 3

[…]

function createCounter( fileName, index ) {
	return expressionStatement(
		updateExpression( '++', // 1
			memberExpression(
				memberExpression(
					memberExpression(
						memberExpression(
							identifier( 'global' ),
							identifier( '__coverage__' ),
							false // 2
						),
						stringLiteral( fileName ),
						true
					),
					identifier( 'functions' ),
					false
				),
				numericLiteral( index ),
				true
			)
		)
	);
}

Wygląda ona przerażająco, ale głównie z powodu sporej liczby zagnieżdżeń.

Tak naprawdę jedyne, co ten kod robi, to tworzy inkrementację zmiennej globalnej w postaci global.__coverage__[ 'ścieżka/do/pliku' ].functions[ 0 ]++. Sama inkrementacja to updateExpression (1). Natomiast odwołania do poszczególnych własności to kolejne memberExpression. Warto zwrócić tutaj uwagę na trzeci parametr tej funkcji (2). Określa on, czy dana własność ma być zapisana z kropką, czy z nawiasem. Dla ścieżki do pliku oraz liczby przyjmuje on wartość true, wymuszając nawias. Gdybyśmy zastosowali w tych wypadkach false, prowadziłoby to do błędu składniowego (global.__coverage__.'ścieżka/do/pliku'.functions.0++), stąd Babel dla takiego przypadku rzuca błędem. Wszystkie funkcje generujące nowe węzły pochodzą z pakietu @babel/types (3).

Cały kod instrumentera wygląda następująco:

const {
	expressionStatement,
	identifier,
	stringLiteral,
	numericLiteral,
	memberExpression,
	updateExpression } = require( '@babel/types' );

const { transformSync } = require( '@babel/core' );

function instrument( code, filePath ) {
	const functions = [];

	const instrumentedCode = transformSync( code, {
		plugins: [
			function codeCoverage() {
				return {
					visitor: {
						FunctionDeclaration( path ) {
							const counter = createCounter( filePath, functions.length );

							path.get( 'body' ).unshiftContainer( 'body', counter );
							functions.push( 0 );
						}
					}
				};
			}
		]
	} );

	global.__coverage__[ filePath ] = {
		functions
	};

	return instrumentedCode.code;
}

function createCounter( fileName, index ) {
	return expressionStatement(
		updateExpression( '++',
			memberExpression(
				memberExpression(
					memberExpression(
						memberExpression(
							identifier( 'global' ),
							identifier( '__coverage__' ),
							false
						),
						stringLiteral( fileName ),
						true
					),
					identifier( 'functions' ),
					false
				),
				numericLiteral( index ),
				true
			)
		)
	);
}

module.exports = instrument;

Testowanie narzędzia

W celu przetestowania narzędzia najlepiej będzie stworzyć przykładowy projekt. Stwórzmy zatem wewnątrz katalogu coverage-sample dodatkowy katalog – sample-project – i otwórzmy go w terminalu, by wygenerować dla niego plik package.json:

npm init -y

Do tak wygenerowanego pliku musimy dodać dwie rzeczy: nasz pakiet coverage-sample w formie zależności oraz wykorzystujący nasz pakiet skrypt testujący. Cały plik package.json powinien po zmianach wyglądać mniej więcej tak:

{
  "name": "sample-project",
  "version": "1.0.0",
  "description": "",
  "main": "src/index.js",
  "directories": {
    "test": "tests"
  },
  "scripts": {
    "test": "coverage-sample ./tests/" // 4
  },
  "devDependencies": { // 1
    "coverage-sample": ".." // 2
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

Nasze narzędzie znalazło się w sekcji devDependencies (1). Zamiast wersji użyjemy .., żeby wskazać miejsce na dysku, w którym znajduje się nasz pakiet (2). W tym wypadku znajduje się on katalog wyżej. Natomiast w sekcji scripts (3) znalazł się skrypt test, który wykorzystuje nasz pakiet jako program wykonywalny (4). Jest to możliwe, ponieważ w coverage-sample dodaliśmy pole bin do package.json.

Teraz wystarczy “zainstalować” nasz pakiet:

npm install

Dzięki tej komendzie npm utworzy odpowiednie linki symboliczne do naszego coverage-sample i będzie można go bez przeszkód wykorzystywać w przykładowym projekcie.

Natomiast sam projekt składać się będzie z dwóch plików: src/index.js, zawierającego kod aplikacji, oraz tests/index.js, zawierającego testy.

Plik src/index.js prezentuje się następująco:

function main() {
	console.log( 'Hello, world!' );
}

function notMain() {
	console.log( 'Whatever' );
}

module.exports = {
	main,
	notMain
};

Z kolei plik tests/index.js wygląda tak:

const { main } = require( '../src' );

main();

Jak widać, “testy” wykonują tylko jedną funkcję – main. Ten brak pokrycia powinien zostać wykazany przez nasze narzędzie do code coverage. Sprawdźmy, czy faktycznie tak się stanie:

npm test

Jeśli wszystko poszło zgodnie z planem, w terminalu powinna się pokazać następująca informacja:

All functions: 2
Covered functions: 1
Coverage: 50%

I to by było na tyle! Mam nadzieję, że artykuł choć trochę przybliżył działanie narzędzi pokroju IstanbulJS. Oczywiście cały kod źródłowy dostępny jest na GitHubie. Miłej zabawy!

PS wygląda, że zapomniałem o ważnej rocznicy: 9 stycznia 2021 mój tutorial o semantycznym blogu w HTML obchodził swoje 10 urodziny! Nigdy nie sądziłem, że będzie żył tak długo, a już tym bardziej, że będę dbał o to, by był jak najbardziej aktualny.