Přeskočit na obsah
Ověřeno

@xuda/core

Reaktivní engine bez závislostí, na kterém běží platforma, kompilátor i ukázkové aplikace.

@xuda/core je reaktivní engine Xudy (signály, plánovač, rozdíl seznamů s klíči, reaktivní renderer, router) jako balíček ESM bez závislostí. Při importu nic nečte ani nezapisuje do globálních proměnných: žádné func, žádné SESSION_OBJ, žádné window, žádný document.

Jediný veřejný balíček v této části dokumentace

package.json balíčku @xuda/core nese "private": false. Je to jediný ze tří balíčků popsaných v této sekci (vedle @xuda/compiler a @xuda/vite-plugin-xu, oba private: true), který je určen k tomu, aby na něm šlo záviset mimo tento repozitář.

Také to není jiný engine než ten, který platforma už dodává: vlastní skript build:globals balíčku (esbuild src/globals.js --bundle ... --outfile ../../runtime/js/xuda_core.globals.js) je způsob, jak se sestavuje runtime/js/xuda_core.globals.js, balíček reaktivního rendereru, který platforma sama dodává.

Reaktivní povrch

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

Pod tím vším je jeden graf závislostí, jeden strom vlastníků, jeden buffer dávek a jeden plánovač: ref přečtený uvnitř effect() se sleduje a efekt znovu spouští, stejně jako signál přečtený uvnitř watch(). computed zde přijímá getter nebo dvojici { get, set } pro zapisovatelný computed.

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

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

effectScope() odpovídá na otázku „kdo to uvolní“: pojmenovaný vlastník, kterého můžete předávat, vnořovat a zastavit jediným voláním, místo ručního skládání hromady uvolňovačů.

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

Komponenta vytvořená přes createApp() už jeden takový obor vlastní: její <script> běží uvnitř vlastního odděleného oboru komponenty, takže efekt napsaný tam se při odpojení komponenty uvolní automaticky.

Nízkoúrovňový primitiv

signal(initial) (.get(), .set(), .peek(), .notify(), .subscribe()) a signalComputed jsou vlastní buňky enginu pod ref a computed. Jsou exportovány a plně podporovány, ne odstraněny, protože na nich stojí renderer a starší most, a protože signal.notify(), opětovné spuštění odběratelů bez změny hodnoty, nemá v ref obdobu. Kód aplikace by měl místo nich sahat po ref a computed; tyto dva názvy jsou zdokumentovány jako vrstva pod nimi, za běhu nejsou označeny jako zastaralé (varování na signal() by se spustilo na každý řádkový obor a každý parametr panelu, tisíckrát na obrazovku, pro kód, který na dané vrstvě dělá přesně to správné).

Vstupní bod aplikace

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

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

App je zkompilovaný modul .xu, vytvořený @xuda/compiler nebo krokem sestavení vite-plugin-xu. createApp postaví sedm vstřikovaných závislostí, které renderer potřebuje, nad tabulkou thunků, kterou vrací setup() modulu, vytvoří renderer a připojí strom komponent. Není to druhý renderer: zkompilovaná cesta a interpretovaná cesta platformy sdílejí render.js.

examples/hello je konkrétní, otestovaná verze tohoto: createApp(App).mount('#app') nad zkompilovaným App.xu s čítačem, podmínkou a seznamem s klíči.

Renderer s vstřikovanými závislostmi

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

create_renderer(deps) je nezávislý na DOM. Vše prostředí přichází přes jediný objekt deps a nejmenší poctivý hostitel potřebuje přesně sedm věcí: document (createElement / createTextNode / createComment), evaluate (sledovaný, synchronní vyhodnocovač výrazů), cast_bool (pravdivost pro xu-render / xu-if), resolve_rows (sledovaný překladač polí řádků pro xu-for), row_key (stabilní identita řádku), write_field (zápisy xu-bind) a dispatch_event (obslužné rutiny xu-on:*). packages/core/demo staví přesně toto nad obyčejným objektem reactive({...}), bez SESSION_OBJ, bez vrstvy zdroje dat a bez starého mostu kdekoli pod tím.

Dvě tiché pasti smlouvy DOM, pokud píšete vlastní adaptér

Uzel deps.document bez nodeType se čte jako objekt jQuery, a ne jako skutečný uzel DOM, což může zanořit každý řádek do předchozího bez vyhozené chyby. Uzel bez remove() promění zahozený řádek v tiše odmítnutý promise: seznam se přestane aktualizovat a nic se nezaloguje. create_adapter v ukázce hlídá obojí vyhozením chyby při vytváření uzlu; předáním { guard: false } hlídání vypnete, až pochopíte, proč existuje.

Diagnostika a whenElement

onDiagnostic, getDiagnostics, diagnosticCount a resetDiagnostics mění tiché vzdání se enginu v jediný pozorovatelný kanál místo roztroušených volání console.error, takže se na ně adaptér hostitele nebo test může přihlásit kódem. whenElement spustí callback, jakmile uzel existuje: zeptá se jednou, pak se znovu ptá ve fázi potvrzení plánovače (přesně když se DOM usadí, před vykreslením) a čekání, které je po dvaceti usazených vykresleních stále nesplněné, se ohlásí jménem, místo aby se tiše vzdalo.

Router

createRouter, createWebHistory, createWebHashHistory, createMemoryHistory, useRouter a useRoute se dodávají ze stejného balíčku. Aktuální trasa je vlastní reactive z @xuda/core a historii dodává platforma, takže jeho použití nepřidává žádnou vlastní závislost.

Exporty balíčku

Deklarovaným minimem enginu je Node 18 nebo novější.