Gå til indhold
Bekræftet

@xuda/core

Den afhængighedsfri reaktive motor, som platformen, kompileren og demo-apps alle monteres på.

@xuda/core er Xudas reaktive motor (signaler, scheduler, nøglebaseret listediff, reaktiv renderer, router) som en afhængighedsfri ESM-pakke. Den læser og skriver ingen globaler ved import: ingen func, ingen SESSION_OBJ, intet window, intet document.

Den ene offentlige pakke i denne del af dokumentationen

@xuda/cores package.json har "private": false. Den er den eneste af de tre pakker, der dækkes i dette afsnit (sammen med @xuda/compiler og @xuda/vite-plugin-xu, begge private: true), der er bygget til at blive brugt som afhængighed uden for dette repositorium.

Den er heller ikke en anden motor end den, platformen allerede leverer: pakkens eget build:globals-script (esbuild src/globals.js --bundle ... --outfile ../../runtime/js/xuda_core.globals.js) er den måde, runtime/js/xuda_core.globals.js, platformens egen leverede bundle med den reaktive renderer, bliver bygget på.

Den reaktive flade

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

Der er én afhængighedsgraf, ét ejertræ, én batch-buffer og én scheduler under det hele: en ref, der læses inde i en effect(), spores og kører den igen, ligesom et signal, der læses i en watch(). computed accepterer her en getter eller et { get, set }-par til en skrivbar computed.

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

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

effectScope() svarer på "hvem rydder op efter dette": en navngiven ejer, du kan give videre, indlejre og stoppe med ét kald, i stedet for at hjemmesnedkerere en pose med oprydningsfunktioner.

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

En komponent, der oprettes gennem createApp(), ejer allerede en af disse: dens <script> køres inde i komponentens egen afkoblede scope, så en effekt, der skrives der, ryddes automatisk op, når komponenten afmonteres.

Den lavniveau-primitive

signal(initial) (.get(), .set(), .peek(), .notify(), .subscribe()) og signalComputed er motorens egne celler under ref og computed. De er eksporteret og fuldt understøttet, ikke fjernet, fordi renderen og den ældre bro er bygget på dem, og fordi signal.notify(), som kører abonnenter igen uden værdiændring, ikke har nogen ref-ækvivalent. Programkode bør i stedet bruge ref og computed. Disse to navne er dokumenteret som laget under og er ikke forældede i runtime (en advarsel på signal() ville udløses pr. rækkescope og pr. panelparameter, tusindvis af gange pr. skærm, for kode, der gør lige det rigtige på det lag).

App-indgangspunktet

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

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

App er et kompileret .xu-modul, produceret af @xuda/compiler eller build-trinnet i vite-plugin-xu. createApp bygger de syv injicerede afhængigheder, renderen har brug for, over den thunk-tabel, som modulets setup() returnerer, opretter renderen og monterer komponenttræet. Det er ikke en anden renderer: den kompilerede vej og den fortolkede platformsvej deler render.js.

examples/hello er den konkrete, testede udgave af dette: createApp(App).mount('#app') over en kompileret App.xu med en tæller, en betingelse og en liste med nøgler.

Renderen, med afhængighedsinjektion

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

create_renderer(deps) er DOM-agnostisk. Alt miljøafhængigt kommer ind gennem ét deps-objekt, og den mindste ærlige vært har brug for præcis syv af dem: document (createElement / createTextNode / createComment), evaluate (en sporet, synkron udtryksevaluator), cast_bool (sandhedsværdi til xu-render / xu-if), resolve_rows (en sporet række-array-resolver til xu-for), row_key (stabil rækkeidentitet), write_field (xu-bind-skrivninger) og dispatch_event (xu-on:*- handlere). packages/core/demo bygger præcis dette over et almindeligt reactive({...})-objekt, uden SESSION_OBJ, uden datakildelag og uden nogen ældre bro nedenunder.

To stille DOM-kontraktfælder, hvis du skriver din egen adapter

En deps.document-node uden nodeType læses som et jQuery-objekt i stedet for en rigtig DOM-node, hvilket kan indlejre hver række inde i den forrige uden nogen kastet fejl. En node uden remove() gør en fjernet række til et stille afvist promise: listen holder op med at opdatere, og intet logges. create_adapter i demoen beskytter mod begge ved at kaste en fejl, når noden oprettes. Send { guard: false } for at fravælge det, når du forstår, hvorfor beskyttelsen findes.

Diagnostik og whenElement

onDiagnostic, getDiagnostics, diagnosticCount og resetDiagnostics gør motorens stille opgivelser til én observerbar kanal i stedet for spredte console.error-kald, så en værtsadapter eller en test kan abonnere på dem i kode. whenElement kører en callback, når en node findes: den spørger én gang og spørger så igen i schedulerens commit-fase (præcis når DOM'en falder til ro, før der males), og en ventetid, der stadig ikke er opfyldt efter tyve afsluttede renderinger, melder sig ved navn i stedet for at give op i stilhed.

Routeren

createRouter, createWebHistory, createWebHashHistory, createMemoryHistory, useRouter og useRoute leveres fra samme pakke. Den nuværende rute er @xuda/cores eget reactive, og historikken kommer fra platformen, så brugen tilføjer ingen afhængighed af sig selv.

Pakkeeksporter

Node 18 eller nyere er den erklærede motorgrænse.