Saltar para o conteúdo
Verificado

@xuda/core

O motor reativo sem dependências sobre o qual a plataforma, o compilador e as aplicações de demonstração se montam.

O @xuda/core é o motor reativo do Xuda (signals, agendador, comparação de listas com chaves, renderizador reativo, router) como um pacote ESM sem dependências. Não lê nem escreve globais ao ser importado: nenhum func, nenhum SESSION_OBJ, nenhum window, nenhum document.

O único pacote público nesta parte da documentação

O package.json do @xuda/core tem "private": false. É o único pacote entre os três abordados nesta secção (juntamente com @xuda/compiler e @xuda/vite-plugin-xu, ambos private: true) feito para ser usado como dependência fora deste repositório.

Também não é um motor separado do que a plataforma já disponibiliza: o próprio script build:globals do pacote (esbuild src/globals.js --bundle ... --outfile ../../runtime/js/xuda_core.globals.js) é a forma como o runtime/js/xuda_core.globals.js, o bundle do renderizador reativo da própria plataforma, é construído.

A superfície reativa

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

Há um só grafo de dependências, uma só árvore de proprietários, um só buffer de lotes e um só agendador por baixo de tudo: um ref lido dentro de um effect() é acompanhado e volta a executá-lo, tal como um signal lido dentro de um watch(). O computed aqui aceita um getter, ou um par { get, set } para um computed gravável.

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

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

O effectScope() responde a "quem descarta isto": um proprietário com nome que pode passar de mão em mão, aninhar e parar numa só chamada, em vez de montar à mão um saco de descartadores.

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

Um componente instanciado através de createApp() já possui um destes: o seu <script> executa-se dentro do âmbito separado do próprio componente, por isso um efeito escrito aí é descartado automaticamente quando o componente é desmontado.

A primitiva de baixo nível

signal(initial) (.get(), .set(), .peek(), .notify(), .subscribe()) e signalComputed são as células do próprio motor por baixo de ref e computed. Estão exportadas e totalmente suportadas, não foram removidas, porque o renderizador e a ponte legada assentam nelas, e porque o signal.notify(), que volta a executar os subscritores sem mudança de valor, não tem equivalente em ref. O código da aplicação deve recorrer a ref e computed em vez disso; estes dois nomes estão documentados como a camada de baixo, não como obsoletos em runtime (um aviso em signal() seria disparado por cada âmbito de linha e por cada parâmetro de painel, milhares de vezes por ecrã, para código que está a fazer exatamente o certo nessa camada).

O ponto de entrada da aplicação

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

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

App é um módulo .xu compilado, produzido pelo @xuda/compiler ou pelo passo de compilação do vite-plugin-xu. O createApp constrói as sete dependências injetadas de que o renderizador precisa sobre a tabela de thunks que o setup() do módulo devolve, cria o renderizador e monta a árvore de componentes. Não é um segundo renderizador: o caminho compilado e o caminho interpretado da plataforma partilham o render.js.

O examples/hello é a versão concreta e testada disto: createApp(App).mount('#app') sobre um App.xu compilado com um contador, uma condicional e uma lista com chaves.

O renderizador, com injeção de dependências

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

O create_renderer(deps) é agnóstico quanto ao DOM. Tudo o que é ambiental chega através de um só objeto deps, e o anfitrião honesto mais pequeno precisa exatamente de sete: document (createElement / createTextNode / createComment), evaluate (um avaliador de expressões síncrono e acompanhado), cast_bool (veracidade para xu-render / xu-if), resolve_rows (um resolvedor acompanhado de arrays de linhas para xu-for), row_key (identidade estável da linha), write_field (escritas de xu-bind) e dispatch_event (tratadores de xu-on:*). O packages/core/demo constrói exatamente isto sobre um objeto reactive({...}) simples, sem SESSION_OBJ, sem camada de datasource e sem ponte legada por baixo.

Duas armadilhas silenciosas do contrato do DOM, se escrever o seu próprio adaptador

Um nó de deps.document sem nodeType é lido como um objeto jQuery em vez de um verdadeiro nó do DOM, o que pode aninhar cada linha dentro da anterior sem lançar erro. Um nó sem remove() transforma uma linha descartada numa promessa rejeitada em silêncio: a lista deixa de atualizar e nada é registado. O create_adapter na demonstração protege ambos lançando um erro ao criar o nó; passe { guard: false } para desativar a proteção depois de perceber porque existe.

Diagnósticos e whenElement

onDiagnostic, getDiagnostics, diagnosticCount e resetDiagnostics transformam as desistências silenciosas do motor num só canal observável, em vez de chamadas console.error dispersas, para que um adaptador de anfitrião ou um teste se possa subscrever a elas por código. O whenElement executa uma callback quando um nó existe: pergunta uma vez, depois volta a perguntar na fase de commit do agendador (exatamente quando o DOM assenta, antes da pintura), e uma espera ainda por satisfazer depois de vinte renderizações assentadas reporta-se pelo nome em vez de desistir em silêncio.

O router

createRouter, createWebHistory, createWebHashHistory, createMemoryHistory, useRouter e useRoute vêm no mesmo pacote. A rota atual é o próprio reactive do @xuda/core, e o histórico vem da plataforma, por isso usá-lo não acrescenta nenhuma dependência própria.

Exportações do pacote

O Node 18 ou posterior é o mínimo de motor declarado.