Naar de inhoud springen
Geverifieerd

@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.

Het enige openbare pakket in dit deel van de docs

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

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

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.

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

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

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.

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

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

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

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

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

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

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.

Twee stille DOM-contractvallen als je zelf een adapter schrijft

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.