REFERÊNCIA DE APIS19 MIN DE LEITURA · MARKDOWN ↗

Referência de carregamento, cache e diagnóstico

Carregamento dinâmico, prioridades, substituições, cache, estilos e observação do runtime.

Escolher o nível de carregamento

Use wu.mount para o ciclo de vida completo. wu.prefetch antecipa recursos de aplicações registradas e wu.use carrega componentes publicados por exportações. WuLoader é um carregador independente: não substitui o catálogo, o sandbox nem as concessões do core.

As substituições e as ferramentas de inspeção pertencem ao host. Uma métrica mede um trecho observado; não garante que o navegador terminou de desenhar. Consulte carregamento de aplicações e diagnóstico para o fluxo completo.

wu.use

Carrega uma exportação de componente declarada por outra aplicação.

wu.use("app.component"): Promise<unknown>

Parâmetros: Nome exato app.component; o manifesto do provedor deve declarar wu.exports.
Retorno: default export quando existe, ou namespace do módulo.
Erros: App/export ausentes, traversal, URL inválida ou import malsucedido causam rejeição.
Permissões: Host; um componente carregado executa código no realm do consumidor.
Limpeza: A instância do renderizador que usa o componente administra sua limpeza.

const ProductCard = await wu.use('catalog.ProductCard');

Método presente no runtime, mas ausente da declaração WuCore. Não converte componentes entre frameworks.

Referência: src/core/wu-core.js.

wu.prefetchAll

Solicita o pré-carregamento de todas as aplicações registradas.

wu.prefetchAll(options?): Promise<void> | (() => void)

Parâmetros: Mesmas opções de disparador de prefetch.
Retorno: Promise imediata ou limpeza dos disparadores adiados.
Erros: O pré-carregamento é uma solicitação ao navegador; não confirma que um renderizador possa montar.
Permissões: API do host; não é exposta pela fachada com escopo.
Limpeza: Mantenha a limpeza se escolher um disparador adiado.

await wu.prefetchAll({ on: 'immediate' });

Referência: src/core/wu-prefetch.js.

new WuLoader

Cria um loader de código e componentes com cache e deduplicação de operações em andamento.

new WuLoader({ maxCacheSize?, cacheTTL? }?): WuLoader

Parâmetros: maxCacheSize limita o número de entradas (50 por padrão); cacheTTL expressa milissegundos (1800000 por padrão).
Retorno: Instância com loadApp, loadComponent, preload, isAvailable e clearCache.
Erros: A construção não registra apps nem executa o ciclo de vida.
Permissões: API do host; não é exposta pela fachada com escopo.
Limpeza: loader.clearCache() libera suas entradas em cache.

import { WuLoader } from 'wu-framework';
const loader = new WuLoader({ maxCacheSize: 20, cacheTTL: 60000 });

Referência: src/core/wu-loader.js.

WuLoader.loadApp

Baixa o texto de código de uma entrada para o pipeline de carregamento.

loader.loadApp(appUrl, manifest?): Promise<string>

Parâmetros: URL base e manifesto com entry opcional.
Retorno: String com código; não executa mount nem registra a app.
Erros: Fetch malsucedido, resposta inválida ou falha na resolução de entry causam rejeição.
Permissões: Host; sujeito ao acesso de rede do ambiente.
Limpeza: clearCache(base) descarta futuras leituras em cache.

const code = await loader.loadApp('/apps/catalog', { entry: 'entry.js' });

Referência: src/core/wu-loader.js.

WuLoader.loadComponent

Importa um componente restrito à base de uma app.

loader.loadComponent(appUrl, componentPath): Promise<unknown>

Parâmetros: Base e caminho relativo do componente; não aceita URLs absolutas nem traversal.
Retorno: default export ou namespace importado.
Erros: Caminho fora da base ou import malsucedido causa rejeição.
Permissões: O módulo executa código no mesmo contexto; não é RPC com escopo.
Limpeza: O import nativo mantém seu cache de módulos.

const card = await loader.loadComponent('/apps/catalog', 'components/card.js');

Referência: src/core/wu-loader.js.

WuLoader.preload

Antecipa o download de código para uma lista de aplicações.

loader.preload(appConfigs: WuAppConfig[]): Promise<void>

Parâmetros: Array de configurações com name e url.
Retorno: Promise de conclusão do percurso de pré-carregamento.
Erros: O pré-carregamento captura falhas por app; inspecione a disponibilidade antes da montagem.
Permissões: API do host; não é exposta pela fachada com escopo.
Limpeza: Não monta renderizadores; clearCache libera o texto em cache.

await loader.preload([{ name: 'catalog', url: '/apps/catalog' }]);

Referência: src/core/wu-loader.js.

WuLoader.isAvailable

Consulta se uma URL responde corretamente a HEAD.

loader.isAvailable(url): Promise<boolean>

Parâmetros: URL a verificar.
Retorno: Booleano; erros de rede são convertidos em false.
Erros: Um servidor que rejeita HEAD pode retornar false mesmo que GET funcione.
Permissões: Acesso de rede do host.
Limpeza: Não cria inscrições nem processos persistentes.

const available = await loader.isAvailable('/apps/catalog/entry.js');

Referência: src/core/wu-loader.js.

WuLoader.clearCache

Descarta o texto e os registros em cache do loader.

loader.clearCache(pattern?): void

Parâmetros: Padrão opcional; sem padrão, esvazia o cache do loader.
Retorno: void.
Erros: Não invalida o cache ESM do navegador.
Permissões: API do host; não é exposta pela fachada com escopo.
Limpeza: Não cria inscrições nem processos persistentes.

loader.clearCache('catalog');

Referência: src/core/wu-loader.js.

WuLoader.getStats

Consulta o cache e os imports em andamento do loader.

loader.getStats(): object

Parâmetros: Sem argumentos.
Retorno: Objeto de métricas.
Erros: Não representa o estado de montagem das apps.
Permissões: API do host; não é exposta pela fachada com escopo.
Limpeza: Não cria inscrições nem processos persistentes.

console.log(loader.getStats());

Referência: src/core/wu-loader.js.

wu.override

Configura uma substituição de URL para desenvolvimento.

wu.override(name, url, options?): void

Parâmetros: name e URL autorizada; options.maxAge/path configuram a persistência da substituição.
Retorno: void
Erros: O sistema valida domínios e configuração; a substituição não remonta automaticamente.
Permissões: API do host; não é exposta pela fachada com escopo.
Limpeza: Remova as substituições de desenvolvimento antes de compartilhar uma sessão.

wu.override('catalog', 'http://localhost:4101');

Referência: src/core/wu-overrides.js.

wu.removeOverride

Remove uma substituição de URL.

wu.removeOverride(name): void

Parâmetros: Nome exato da app.
Retorno: void
Erros: O sistema valida domínios e configuração; a substituição não remonta automaticamente.
Permissões: API do host; não é exposta pela fachada com escopo.
Limpeza: Remova as substituições de desenvolvimento antes de compartilhar uma sessão.

wu.removeOverride('catalog');

Referência: src/core/wu-overrides.js.

wu.getOverrides

Consulta as substituições de URL ativas.

wu.getOverrides(): Record<string,string>

Parâmetros: Sem argumentos.
Retorno: Record<string,string>
Erros: O sistema valida domínios e configuração; a substituição não remonta automaticamente.
Permissões: API do host; não é exposta pela fachada com escopo.
Limpeza: Remova as substituições de desenvolvimento antes de compartilhar uma sessão.

console.log(wu.getOverrides());

Referência: src/core/wu-overrides.js.

wu.clearOverrides

Remove todas as substituições ativas.

wu.clearOverrides(): void

Parâmetros: Sem argumentos.
Retorno: void
Erros: O sistema valida domínios e configuração; a substituição não remonta automaticamente.
Permissões: API do host; não é exposta pela fachada com escopo.
Limpeza: Remova as substituições de desenvolvimento antes de compartilhar uma sessão.

wu.clearOverrides();

Referência: src/core/wu-overrides.js.

normalizeStyleMode

Normaliza os aliases de configuração de estilos.

normalizeStyleMode(mode): string | undefined

Parâmetros: String de modo ou undefined.
Retorno: none→isolated; own-only→fully-isolated; outros valores passam sem validação.
Erros: Não valida por si só se o modo é aceito pelo manifesto.
Permissões: Função pura; não concede permissões.
Limpeza: Não cria inscrições nem processos persistentes.

import { normalizeStyleMode } from 'wu-framework';
console.log(normalizeStyleMode('own-only'));

Referência: src/core/wu-sandbox.js.

resolveDomOwnership

Resolve a propriedade explícita e os aliases nativeShadow/framework.

resolveDomOwnership(options?): "wu" | "app" | "light"

Parâmetros: domOwnership tem precedência; depois nativeShadow; Lit seleciona app por padrão.
Retorno: Propriedade efetiva.
Erros: Não cria Shadow DOM nem valida se um renderizador implementa seu limite.
Permissões: Função de configuração; não é controle de segurança.
Limpeza: Não cria inscrições nem processos persistentes.

import { resolveDomOwnership } from 'wu-framework';
console.log(resolveDomOwnership({ framework: 'lit' }));

Referência: src/core/wu-sandbox.js.

wu.tagStyleAsApp

Atribui uma folha style/link a uma aplicação para a ponte CSS.

wu.tagStyleAsApp(element, appName): void

Parâmetros: Elemento style/link e nome da app.
Retorno: void.
Erros: A atribuição não substitui styleMode do manifesto.
Permissões: API do host; não é exposta pela fachada com escopo.
Limpeza: Remova a folha quando seu proprietário terminar.

const style = document.createElement('style');
style.textContent = ':host { color: var(--accent); }';
wu.tagStyleAsApp(style, 'catalog');
document.head.append(style);

Referência: src/core/wu-core.js.

new WuCache

Cria um cache LRU com TTL e armazenamento opcional.

new WuCache(options?): WuCache

Parâmetros: maxSize em MB; maxItems; TTL em ms; persistent e storage memory/localStorage/sessionStorage.
Retorno: Instância de cache.
Erros: Uma entrada grande demais ou um limite de operações pode impedir o armazenamento.
Permissões: Host; não use armazenamento persistente como autorização.
Limpeza: cache.clear() libera as entradas e seu namespace persistente.

import { WuCache } from 'wu-framework';
const cache = new WuCache({ maxSize: 2, maxItems: 20, defaultTTL: 60000, storage: 'memory' });

Referência: src/core/wu-cache.js.

WuCache.get

Lê uma entrada não expirada e atualiza sua ordem LRU.

cache.get(key): unknown | null

Parâmetros: Chave da entrada.
Retorno: Valor salvo ou null por ausência, expiração ou limite de requisições.
Erros: null não distingue ausência, expiração e cooldown; consulte as métricas.
Permissões: Acesso ao cache proprietário; não aplica concessões de store.
Limpeza: Não cria inscrições nem processos persistentes.

const result = cache.get('catalog-result');

A leitura em memória retorna a referência salva; não é um snapshot separado como WuStore.

Referência: src/core/wu-cache.js.

WuCache.set

Salva um valor e aplica limites de espaço e expiração.

cache.set(key, value, ttl?): boolean

Parâmetros: Chave, valor e TTL em ms; ttl=0 usa defaultTTL pela seleção com ||.
Retorno: true se for armazenado; false por tamanho, erro ou limite de requisições.
Erros: Captura falhas e retorna false; a cota de storage pode limitar a persistência.
Permissões: Host; valide quais dados você salva de forma persistente.
Limpeza: delete(key) remove uma entrada; clear() remove todas.

const cached = cache.set('catalog-result', { count: 12 }, 30000);

Referência: src/core/wu-cache.js.

WuCache.delete

Remove uma entrada da memória e do armazenamento de apoio configurado.

cache.delete(key): void

Parâmetros: Chave exata.
Retorno: void
Erros: A persistência depende da disponibilidade e da cota do storage.
Permissões: Autoridade do proprietário do cache.
Limpeza: Não cria inscrições nem processos persistentes.

cache.delete('catalog-result');

Referência: src/core/wu-cache.js.

WuCache.clear

Esvazia o cache desta instância e seu armazenamento configurado.

cache.clear(): void

Parâmetros: Sem argumentos.
Retorno: void
Erros: A persistência depende da disponibilidade e da cota do storage.
Permissões: Autoridade do proprietário do cache.
Limpeza: Não cria inscrições nem processos persistentes.

cache.clear();

Referência: src/core/wu-cache.js.

WuCache.getStats

Consulta acertos, ausências, expulsões, tamanhos e limitação de requisições.

cache.getStats(): object

Parâmetros: Sem argumentos.
Retorno: object
Erros: A persistência depende da disponibilidade e da cota do storage.
Permissões: Autoridade do proprietário do cache.
Limpeza: Não cria inscrições nem processos persistentes.

console.log(cache.getStats());

Referência: src/core/wu-cache.js.

WuCache.getRateLimitStatus

Consulta se as operações estão em cooldown e sua cota.

cache.getRateLimitStatus(): object

Parâmetros: Sem argumentos.
Retorno: object
Erros: A persistência depende da disponibilidade e da cota do storage.
Permissões: Autoridade do proprietário do cache.
Limpeza: Não cria inscrições nem processos persistentes.

console.log(cache.getRateLimitStatus());

Referência: src/core/wu-cache.js.

wu.getStats

Resume o estado e as métricas dos subsistemas do core.

wu.getStats(): object

Parâmetros: Sem argumentos.
Retorno: Objeto de diagnóstico.
Erros: Não substitui um teste de montagem nem uma verificação HTTP.
Permissões: API do host; não é exposta pela fachada com escopo.
Limpeza: Não cria inscrições nem processos persistentes.

console.log(wu.getStats());

Referência: src/core/wu-core.js.

wu.getManifestDiagnostics

Lê erros de dependências declarativas entre apps.

wu.getManifestDiagnostics(): WuManifestImportDiagnostic[]

Parâmetros: Sem argumentos; depende da verificação prévia de imports.
Retorno: Lista de diagnósticos por consumidor/import/provedor.
Erros: Não verifica automaticamente todos os imports transitivos de um bundle.
Permissões: API do host; não é exposta pela fachada com escopo.
Limpeza: Não cria inscrições nem processos persistentes.

console.table(wu.getManifestDiagnostics());

Referência: src/core/wu-core.js.

wu.showInspector

Abre o inspetor visual carregado sob demanda.

wu.showInspector(): Promise<{ close(): void } | null>

Parâmetros: Sem argumentos.
Retorno: Handle close ou null quando não abre.
Erros: O carregamento do chunk ou o ambiente DOM podem impedir a abertura.
Permissões: API do host; não é exposta pela fachada com escopo.
Limpeza: close() ou wu.hideInspector() remove a sobreposição.

const inspector = await wu.showInspector();
// Al cerrar tu herramienta:
inspector?.close();

Referência: src/core/wu-core.js.

wu.hideInspector

Fecha a sobreposição de inspeção, se existir.

wu.hideInspector(): Promise<void>

Parâmetros: Sem argumentos.
Retorno: Promise de fechamento.
Erros: Não remove apps nem dados do store.
Permissões: API do host; não é exposta pela fachada com escopo.
Limpeza: Remove a interface de diagnóstico.

await wu.hideInspector();

Referência: src/core/wu-core.js.

wu.performance.startMeasure

Marca o início de uma duração associada à app ou global.

wu.performance.startMeasure(name, appName?): void

Parâmetros: Nome da medição; appName global por padrão.
Retorno: void.
Erros: Uma configuração disabled omite o registro.
Permissões: API do host; não é exposta pela fachada com escopo.
Limpeza: Termine com endMeasure usando o mesmo par nome/app.

wu.performance.startMeasure('load-catalog', 'catalog');