@xuda/core
Reaktywny silnik bez zależności, na którym montują się platforma, kompilator i aplikacje demo.
@xuda/core to reaktywny silnik Xuda (sygnały, planista, różnicowanie list z kluczami, reaktywny
renderer, router) jako pakiet ESM bez zależności. Przy imporcie nie czyta ani nie zapisuje żadnych
globali: żadnego func, SESSION_OBJ, window ani document.
package.json pakietu @xuda/core ma "private": false. To jedyny pakiet spośród trzech
omawianych w tej sekcji (obok @xuda/compiler i @xuda/vite-plugin-xu, oba private: true),
zbudowany tak, by można było od niego zależeć poza tym repozytorium.
To także nie jest inny silnik niż ten, który platforma już dostarcza: własny skrypt build:globals
pakietu (esbuild src/globals.js --bundle ... --outfile ../../runtime/js/xuda_core.globals.js) buduje runtime/js/xuda_core.globals.js, czyli pakiet
reaktywnego renderera dostarczany przez samą platformę.
Powierzchnia reaktywna
Pod spodem jest jeden graf zależności, jedno drzewo właścicieli, jeden bufor wsadowy i jeden
planista: odczyt ref wewnątrz effect() śledzi go i uruchamia ponownie, tak samo jak odczyt
sygnału wewnątrz watch(). computed przyjmuje tu getter albo parę { get, set } dla zapisywalnego
computed.
effectScope() odpowiada na pytanie „kto to zwalnia”: nazwany właściciel, którego możesz przekazywać,
zagnieżdżać i zatrzymywać jednym wywołaniem, zamiast ręcznie budować worek zwalniaczy.
Komponent tworzony przez createApp() już ma taki zakres: jego <script> działa wewnątrz własnego,
odłączonego zakresu komponentu, więc efekt napisany tam jest zwalniany automatycznie, gdy komponent
jest odmontowywany.
Prymityw niskiego poziomu
signal(initial) (.get(), .set(), .peek(), .notify(), .subscribe()) i signalComputed to
własne komórki silnika pod ref i computed. Są eksportowane i w pełni wspierane, nie usunięte,
ponieważ renderer i most do starszego kodu są na nich zbudowane, a także dlatego, że signal.notify(),
czyli ponowne uruchomienie subskrybentów bez zmiany wartości, nie ma odpowiednika w ref. Kod
aplikacji powinien sięgać po ref i computed; te dwie nazwy są udokumentowane jako warstwa niżej,
a nie oznaczone jako przestarzałe w czasie działania (ostrzeżenie przy signal() odpalałoby się dla
każdego zakresu wiersza i każdego parametru panelu, tysiące razy na ekran, dla kodu, który na tej
warstwie robi dokładnie to, co trzeba).
Punkt wejścia aplikacji
App to skompilowany moduł .xu, wytworzony przez @xuda/compiler lub
krok budowania vite-plugin-xu. createApp buduje siedem wstrzykiwanych zależności, których potrzebuje
renderer, na tabeli thunków zwracanej przez setup() modułu, tworzy renderer i montuje drzewo
komponentów. To nie jest drugi renderer: ścieżka skompilowana i interpretowana ścieżka platformy
współdzielą render.js.
examples/hello to konkretna, przetestowana wersja tego: createApp(App).mount('#app') na
skompilowanym App.xu z licznikiem, warunkiem i listą z kluczami.
Renderer ze wstrzykiwanymi zależnościami
create_renderer(deps) jest niezależny od DOM. Wszystko środowiskowe przychodzi przez jeden obiekt
deps, a najmniejszy uczciwy host potrzebuje dokładnie siedmiu: document (createElement /
createTextNode / createComment), evaluate (śledzony, synchroniczny ewaluator wyrażeń), cast_bool
(prawdziwość dla xu-render / xu-if), resolve_rows (śledzony resolver tablicy wierszy dla
xu-for), row_key (stabilna tożsamość wiersza), write_field (zapisy xu-bind) i
dispatch_event (obsługa xu-on:*). packages/core/demo buduje dokładnie to na zwykłym obiekcie
reactive({...}), bez SESSION_OBJ, warstwy źródła danych ani mostu do starszego kodu pod spodem.
Węzeł deps.document bez nodeType jest czytany jako obiekt jQuery, a nie prawdziwy węzeł DOM, co
może zagnieździć każdy wiersz wewnątrz poprzedniego bez żadnego zgłoszonego błędu. Węzeł bez
remove() zamienia usunięty wiersz w po cichu odrzuconą obietnicę: lista przestaje się aktualizować i
nic nie jest logowane. create_adapter w demo zabezpiecza oba przypadki, rzucając błąd przy tworzeniu
węzła; przekaż { guard: false }, aby z tego zrezygnować, gdy zrozumiesz, po co jest to
zabezpieczenie.
Diagnostyka i whenElement
onDiagnostic, getDiagnostics, diagnosticCount i resetDiagnostics zamieniają ciche poddawanie
się silnika w jeden obserwowalny kanał, zamiast rozproszonych wywołań console.error, żeby adapter
hosta lub test mógł subskrybować je przez kod. whenElement uruchamia callback, gdy węzeł już
istnieje: pyta raz, potem pyta ponownie w fazie zatwierdzenia planisty (dokładnie wtedy, gdy DOM się
ustabilizuje, przed malowaniem), a oczekiwanie wciąż niespełnione po dwudziestu ustabilizowanych
renderach zgłasza się po nazwie zamiast po cichu się poddać.
Router
createRouter, createWebHistory, createWebHashHistory, createMemoryHistory, useRouter i
useRoute są dostarczane z tego samego pakietu. Bieżąca trasa to własny reactive z @xuda/core, a
historia pochodzi z platformy, więc korzystanie z niego nie dodaje własnej zależności.
Eksporty pakietu
Deklarowane minimum silnika to Node 18 lub nowszy.