@xuda/core
De afhankelijkheidsvrije reactieve engine waarop het platform, de compiler en de demo-apps allemaal mounten.
@xuda/core is de reactieve engine van Xuda (signals, scheduler, keyed list diff, reactieve
renderer, router) als een afhankelijkheidsvrij ESM-pakket. Het leest en schrijft bij import geen
globals: geen func, geen SESSION_OBJ, geen window, geen document.
De package.json van @xuda/core heeft "private": false. Het is het enige pakket van de drie
die in deze sectie worden behandeld (naast @xuda/compiler en @xuda/vite-plugin-xu, beide
private: true) dat is gebouwd om buiten deze repository als dependency te worden gebruikt.
Het is ook geen aparte engine naast die welke het platform al meelevert: het eigen
build:globals-script van het pakket (esbuild src/globals.js --bundle ... --outfile ../../runtime/js/xuda_core.globals.js) is hoe runtime/js/xuda_core.globals.js, de eigen
meegeleverde bundel met reactieve renderer van het platform, wordt gebouwd.
Het reactieve oppervlak
Eronder zit één afhankelijkheidsgraaf, één eigenaarsboom, één batchbuffer en één scheduler: een
ref die binnen een effect() wordt gelezen, wordt gevolgd en voert hem opnieuw uit, net als een
signal die in een watch() wordt gelezen. computed accepteert hier een getter, of een
{ get, set }-paar voor een schrijfbare computed.
effectScope() beantwoordt "wie ruimt dit op": een benoemde eigenaar die je kunt doorgeven,
nesten en in één aanroep kunt stoppen, in plaats van zelf een zak disposers bij te houden.
Een component die via createApp() wordt geïnstantieerd, heeft er al een: zijn <script> draait
binnen de eigen losgekoppelde scope van de component, dus een effect dat je daar schrijft, wordt
automatisch opgeruimd wanneer de component wordt ontmount.
De primitive op laag niveau
signal(initial) (.get(), .set(), .peek(), .notify(), .subscribe()) en
signalComputed zijn de eigen cellen van de engine onder ref en computed. Ze worden
geëxporteerd en volledig ondersteund, niet verwijderd, omdat de renderer en de legacy bridge erop
zijn gebouwd, en omdat signal.notify(), het opnieuw uitvoeren van subscribers zonder
waardewijziging, geen ref-equivalent heeft. Applicatiecode moet in plaats daarvan naar ref en
computed grijpen; deze twee namen zijn gedocumenteerd als de laag eronder, niet als verouderd in
de runtime (een waarschuwing op signal() zou per rijscope en per paneelparameter afgaan,
duizenden keren per scherm, voor code die op die laag precies het juiste doet).
Het app-toegangspunt
App is een gecompileerde .xu-module, gemaakt door @xuda/compiler of
de buildstap vite-plugin-xu. createApp bouwt de zeven geïnjecteerde deps die de renderer nodig
heeft over de thunk-tabel die de setup() van de module teruggeeft, maakt de renderer en mount de
componentboom. Het is geen tweede renderer: het gecompileerde pad en het geïnterpreteerde
platformpad delen render.js.
examples/hello is de concrete, geteste versie hiervan: createApp(App).mount('#app') over een
gecompileerde App.xu met een teller, een conditie en een lijst met sleutels.
De renderer, met dependency injection
create_renderer(deps) is DOM-agnostisch. Alles wat van de omgeving afhangt, komt binnen via één
deps-object, en de kleinste eerlijke host heeft er precies zeven nodig: document
(createElement / createTextNode / createComment), evaluate (een gevolgde, synchrone
expressie-evaluator), cast_bool (waarheidsgehalte voor xu-render / xu-if), resolve_rows
(een gevolgde rij-array-resolver voor xu-for), row_key (stabiele rij-identiteit), write_field
(schrijfacties van xu-bind) en dispatch_event (xu-on:*-handlers). packages/core/demo bouwt
precies dit over een gewoon reactive({...})-object, zonder SESSION_OBJ, zonder
datasource-laag en zonder legacy bridge eronder.
Een deps.document-node zonder nodeType wordt gelezen als een jQuery-object in plaats van een
echte DOM-node, wat elke rij in zijn voorganger kan nesten zonder dat er een fout wordt gegooid.
Een node zonder remove() maakt van een verwijderde rij een stilletjes afgewezen promise: de lijst
wordt niet meer bijgewerkt en er wordt niets gelogd. create_adapter in de demo bewaakt beide door
bij het aanmaken van de node een fout te gooien; geef { guard: false } mee om dat uit te zetten
zodra je begrijpt waarom de bewaking bestaat.
Diagnostiek en whenElement
onDiagnostic, getDiagnostics, diagnosticCount en resetDiagnostics maken van de stille
opgaves van de engine één waarneembaar kanaal, in plaats van verspreide console.error-aanroepen,
zodat een hostadapter of een test zich erop kan abonneren via code. whenElement voert een
callback uit zodra een node bestaat: hij vraagt het één keer, vraagt het daarna opnieuw in de
commitfase van de scheduler (precies wanneer de DOM tot rust komt, vóór het tekenen), en een wacht
die na twintig afgeronde renders nog niet is voldaan, meldt zichzelf bij naam in plaats van stilletjes
op te geven.
De router
createRouter, createWebHistory, createWebHashHistory, createMemoryHistory, useRouter en
useRoute komen uit hetzelfde pakket. De huidige route is de eigen reactive van @xuda/core, en
de history komt van het platform, dus het gebruik ervan voegt geen eigen dependency toe.
Pakketexports
Node 18 of nieuwer is de gedeclareerde ondergrens voor de engine.