Sari la conținut
Verificat

@xuda/core

Motorul reactiv fără dependențe pe care se montează platforma, compilatorul și aplicațiile demo.

@xuda/core este motorul reactiv Xuda (semnale, scheduler, diff de liste cu chei, renderer reactiv, router) ca pachet ESM fără dependențe. Nu citește și nu scrie variabile globale la import: nici func, nici SESSION_OBJ, nici window, nici document.

Singurul pachet public din această parte a documentației

package.json al lui @xuda/core poartă "private": false. Este singurul pachet dintre cele trei tratate în această secțiune (alături de @xuda/compiler și @xuda/vite-plugin-xu, ambele private: true) făcut ca să fie folosit ca dependență în afara acestui repository.

Nu este nici un motor separat de cel pe care îl livrează deja platforma: scriptul propriu al pachetului, build:globals (esbuild src/globals.js --bundle ... --outfile ../../runtime/js/xuda_core.globals.js), este cel care construiește runtime/js/xuda_core.globals.js, bundle-ul de renderer reactiv livrat chiar de platformă.

Suprafața reactivă

js
import { ref, reactive, computed, effect, watch, effectScope } from '@xuda/core';

Dedesubtul tuturor există un singur graf de dependențe, un singur arbore de proprietari, un singur buffer de batch și un singur scheduler: un ref citit într-un effect() este urmărit și îl rulează din nou, la fel ca un semnal citit într-un watch(). computed primește aici un getter sau o pereche { get, set } pentru un computed scriptibil.

js
const state = reactive({ count: 0 });
state.count++;             // no .get(), no .set()

const n = ref(0);
n.value++;

effectScope() răspunde la întrebarea „cine eliberează asta": un proprietar cu nume pe care îl poți transmite, îmbrica și opri printr-un singur apel, în loc să asamblezi manual o grămadă de funcții de eliberare.

js
const scope = effectScope();
scope.run(() => {
  effect(() => { /* ... */ });
  watch(source, callback);
  onScopeDispose(() => io.disconnect());
});
scope.stop();

O componentă instanțiată prin createApp() deține deja unul: <script> ei rulează în scope-ul propriu, detașat, al componentei, deci un efect scris acolo este eliberat automat când componenta se demontează.

Primitiva de nivel jos

signal(initial) (.get(), .set(), .peek(), .notify(), .subscribe()) și signalComputed sunt celulele proprii ale motorului, aflate sub ref și computed. Sunt exportate și pe deplin susținute, nu eliminate, pentru că renderer-ul și puntea legacy sunt construite pe ele și pentru că signal.notify(), care rulează din nou abonații fără o schimbare de valoare, nu are echivalent în ref. Codul de aplicație ar trebui să folosească ref și computed; aceste două nume sunt documentate ca stratul de dedesubt, nu ca depreciate la runtime (un avertisment pe signal() s-ar declanșa la fiecare scope de rând și la fiecare parametru de panou, de mii de ori pe ecran, pentru cod care face exact ce trebuie la acel nivel).

Punctul de intrare al aplicației

js
import { createApp } from '@xuda/core';
import App from './App.xu';

createApp(App).mount('#app');

App este un modul .xu compilat, produs de @xuda/compiler sau de pasul de build vite-plugin-xu. createApp construiește cele șapte dependențe injectate de care are nevoie renderer-ul, peste tabelul de thunk-uri returnat de setup() al modulului, creează renderer-ul și montează arborele de componente. Nu este un al doilea renderer: calea compilată și calea interpretată a platformei folosesc același render.js.

examples/hello este versiunea concretă, testată, a acestui lucru: createApp(App).mount('#app') peste un App.xu compilat, cu un contor, o condiție și o listă cu chei.

Renderer-ul, cu dependențe injectate

js
import { create_renderer } from '@xuda/core';
import { reactive } from '@xuda/core/reactivity';

create_renderer(deps) este agnostic față de DOM. Tot ce ține de mediu sosește printr-un singur obiect deps, iar cel mai mic host onest are nevoie de exact șapte: document (createElement / createTextNode / createComment), evaluate (un evaluator de expresii sincron, urmărit), cast_bool (valoarea de adevăr pentru xu-render / xu-if), resolve_rows (un rezolvator urmărit de array-uri de rânduri pentru xu-for), row_key (identitatea stabilă a rândului), write_field (scrierile xu-bind) și dispatch_event (handler-ele xu-on:*). packages/core/demo construiește exact asta peste un simplu obiect reactive({...}), fără SESSION_OBJ, fără strat de surse de date și fără punte legacy dedesubt.

Două capcane tăcute ale contractului DOM, dacă îți scrii propriul adaptor

Un nod deps.document fără nodeType este citit ca obiect jQuery, nu ca nod DOM real, ceea ce poate îmbrica fiecare rând în cel dinainte, fără nicio eroare aruncată. Un nod fără remove() transformă un rând eliminat într-un promise respins în tăcere: lista nu se mai actualizează și nu se loghează nimic. create_adapter din demo apără împotriva ambelor aruncând o eroare la crearea nodului; transmite { guard: false } ca să renunți la protecție după ce înțelegi de ce există.

Diagnostice și whenElement

onDiagnostic, getDiagnostics, diagnosticCount și resetDiagnostics transformă renunțările tăcute ale motorului într-un singur canal observabil, în loc de apeluri console.error risipite, astfel încât un adaptor de host sau un test să se poată abona la ele din cod. whenElement rulează un callback când există un nod: întreabă o dată, apoi întreabă din nou la faza de commit a scheduler-ului (exact când DOM-ul se stabilizează, înainte de paint), iar o așteptare nesatisfăcută după douăzeci de randări stabilizate se raportează singură pe nume, în loc să renunțe în tăcere.

Router-ul

createRouter, createWebHistory, createWebHashHistory, createMemoryHistory, useRouter și useRoute vin din același pachet. Ruta curentă este propriul reactive al lui @xuda/core, iar istoricul vine de la platformă, deci folosirea lui nu adaugă nicio dependență proprie.

Exporturile pachetului

Node 18 sau mai nou este pragul minim declarat al motorului.