Vai al contenuto
Verificata

@xuda/core

Il motore reattivo senza dipendenze su cui si montano la piattaforma, il compilatore e le app demo.

@xuda/core è il motore reattivo di Xuda (signal, scheduler, diff di liste con chiavi, renderer reattivo, router) come pacchetto ESM senza dipendenze. Non legge né scrive alcuna variabile globale all'importazione: niente func, niente SESSION_OBJ, niente window, niente document.

L'unico pacchetto pubblico in questa parte della documentazione

Il package.json di @xuda/core riporta "private": false. È l'unico dei tre pacchetti trattati in questa sezione (insieme a @xuda/compiler e @xuda/vite-plugin-xu, entrambi private: true) pensato per essere usato come dipendenza fuori da questo repository.

Inoltre non è un motore separato da quello che la piattaforma distribuisce già: lo script build:globals del pacchetto (esbuild src/globals.js --bundle ... --outfile ../../runtime/js/xuda_core.globals.js) è il modo in cui viene costruito runtime/js/xuda_core.globals.js, il bundle del renderer reattivo distribuito dalla piattaforma stessa.

La superficie reattiva

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

Sotto a tutto c'è un solo grafo di dipendenze, un solo albero dei proprietari, un solo buffer di batch e un solo scheduler: un ref letto dentro un effect() viene tracciato e lo riesegue, come un signal letto dentro un watch(). Qui computed accetta un getter, oppure una coppia { get, set } per un computed scrivibile.

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

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

effectScope() risponde alla domanda "chi smaltisce questo": un proprietario con nome che puoi passare, annidare e fermare con una sola chiamata, invece di costruirti a mano un sacchetto di funzioni di smaltimento.

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

Un componente istanziato tramite createApp() ne possiede già uno: il suo <script> viene eseguito dentro lo scope separato del componente stesso, quindi un effect scritto lì viene smaltito automaticamente quando il componente viene smontato.

La primitiva di basso livello

signal(initial) (.get(), .set(), .peek(), .notify(), .subscribe()) e signalComputed sono le celle del motore stesso sotto ref e computed. Sono esportate e pienamente supportate, non rimosse, perché il renderer e il bridge legacy sono costruiti su di esse, e perché signal.notify(), che riesegue gli iscritti senza una variazione di valore, non ha un equivalente in ref. Il codice applicativo dovrebbe usare invece ref e computed; questi due nomi sono documentati come il livello sottostante, non deprecati a runtime (un avviso su signal() scatterebbe per ogni scope di riga e per ogni parametro di pannello, migliaia di volte per schermata, per codice che a quel livello fa esattamente la cosa giusta).

Il punto di ingresso dell'app

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

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

App è un modulo .xu compilato, prodotto da @xuda/compiler o dal passaggio di build vite-plugin-xu. createApp costruisce le sette dipendenze iniettate di cui il renderer ha bisogno sulla tabella di thunk restituita dal setup() del modulo, crea il renderer e monta l'albero dei componenti. Non è un secondo renderer: il percorso compilato e il percorso interpretato della piattaforma condividono render.js.

examples/hello è la versione concreta e testata di questo: createApp(App).mount('#app') su un App.xu compilato con un contatore, una condizione e un elenco con chiavi.

Il renderer, con dipendenze iniettate

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

create_renderer(deps) è indipendente dal DOM. Tutto ciò che è ambientale arriva tramite un solo oggetto deps, e l'host onesto più piccolo ne richiede esattamente sette: document (createElement / createTextNode / createComment), evaluate (un valutatore di espressioni sincrono e tracciato), cast_bool (la veridicità per xu-render / xu-if), resolve_rows (un risolutore tracciato di array di righe per xu-for), row_key (identità stabile della riga), write_field (scritture di xu-bind) e dispatch_event (gestori xu-on:*). packages/core/demo costruisce esattamente questo su un semplice oggetto reactive({...}), senza SESSION_OBJ, senza livello datasource e senza bridge legacy in nessun punto sottostante.

Due trappole silenziose del contratto DOM, se scrivi un tuo adapter

Un nodo deps.document senza nodeType viene letto come un oggetto jQuery invece che come un vero nodo DOM, e questo può annidare ogni riga dentro la precedente senza alcun errore lanciato. Un nodo senza remove() trasforma una riga eliminata in una promise rifiutata in silenzio: l'elenco smette di aggiornarsi e non viene registrato nulla. create_adapter nella demo protegge da entrambi lanciando un errore al momento della creazione del nodo; passa { guard: false } per rinunciarvi una volta capito perché la protezione esiste.

Diagnostica e whenElement

onDiagnostic, getDiagnostics, diagnosticCount e resetDiagnostics trasformano le rinunce silenziose del motore in un unico canale osservabile, invece di chiamate console.error sparse, così un adapter host o un test può iscriversi a esse da codice. whenElement esegue una callback quando un nodo esiste: lo chiede una volta, poi lo richiede nella fase di commit dello scheduler (esattamente quando il DOM si assesta, prima del paint), e un'attesa ancora insoddisfatta dopo venti rendering assestati si segnala per nome invece di rinunciare in silenzio.

Il router

createRouter, createWebHistory, createWebHashHistory, createMemoryHistory, useRouter e useRoute sono distribuiti dallo stesso pacchetto. La route corrente è il reactive di @xuda/core stesso, e la cronologia arriva dalla piattaforma, quindi usarlo non aggiunge alcuna dipendenza propria.

Export del pacchetto

Node 18 o successivo è la versione minima dichiarata.