@yoltra/devtools-protocol

Ver la referencia de la API →

Tipos de protocolo compartidos, definiciones de mensajes y utilidades para el conjunto de Yoltra DevTools.

@yoltra/devtools-protocol es el paquete de vocabulario fundamental para todo el ecosistema DevTools. Define el formato de comunicación, los tipos de mensajes, la negociación de capacidades y las utilidades de JSON Patch de las que dependen todos los demás paquetes DevTools.

#Instalación

npm install @yoltra/devtools-protocol

#Qué Incluye

#Versión del Protocolo

Una cadena semver utilizada durante la negociación del handshake. El hub rechaza conexiones con una versión mayor incompatible.

import { PROTOCOL_VERSION } from "@yoltra/devtools-protocol";

console.log(PROTOCOL_VERSION); // "0.1.0"

#Roles

Un enum que identifica a los tres participantes del protocolo DevTools:

import { DevtoolsRole } from "@yoltra/devtools-protocol";

DevtoolsRole.STORE; // Una instancia de store de Yoltra
DevtoolsRole.EXTENSION; // Una UI de DevTools (panel del navegador, CLI, VSCode)
DevtoolsRole.HUB; // El broker central de mensajes

#Tipos de Mensajes

Todos los mensajes están discriminados por un campo type para permitir un enrutamiento seguro por tipo:

#Capacidades

Los stores, extensiones y el hub anuncian sus capacidades durante el handshake:

import type { StoreCapabilities, ExtensionCapabilities } from "@yoltra/devtools-protocol";

const storeCaps: StoreCapabilities = {
  replay: true,
  stateSnapshot: true,
  emit: false,
};

#Utilidades JSON Patch

Convierte la salida de detección de cambios de Yoltra en operaciones JSON Patch RFC 6902:

import { computePatches, getAtPath } from "@yoltra/devtools-protocol";

const prev = { counter: { value: 1 } };
const next = { counter: { value: 2 } };

const patches = computePatches(prev, next, ["counter.value"]);
// [{ op: "replace", path: "/counter/value", value: 2 }]

getAtPath(next, "counter.value"); // 2

#Manejo de Mensajes con Seguridad de Tipos

import type { DevtoolsMessage } from "@yoltra/devtools-protocol";

function handle(msg: DevtoolsMessage) {
  switch (msg.type) {
    case "STORE_EVENT":
      console.log("Patches:", msg.patches);
      break;
    case "STATE_SNAPSHOT":
      console.log("State:", msg.state, "v" + msg.version);
      break;
    case "STORE_CONNECTED":
      console.log("Store conectado:", msg.store.name);
      break;
    // TypeScript exige manejo exhaustivo
  }
}

#Cómo Funciona la Conexión del Store

El agente de store se conecta mediante ReconnectingWsClient, que se encarga del handshake, del búfer de envío y del ciclo de reconexión. El agente solo inyecta el socket como un DevtoolsSocketFactory, así que este paquete no importa ningún transporte. Nada sale antes de un HANDSHAKE_RESPONSE exitoso: hasta entonces las tramas esperan en un búfer FIFO acotado, y un desbordamiento descarta la trama más antigua y lo reporta mediante onBackpressure. El lado del panel (HubProvider en @yoltra/devtools-ui) tiene su propio código de conexión y no usa este cliente.

#Flujo de Handshake

Cliente (Store/Extensión)              Hub
  │                                     │
  ├─ HANDSHAKE_REQUEST ───────────────► │
  │  { role, protocolVersion, ... }     │
  │                                     │
  │ ◄─────────────── HANDSHAKE_RESPONSE │
  │  { success, negotiatedVersion }     │
  │                                     │
  │  (si es store) Hub transmite        │
  │  STORE_CONNECTED a extensiones      │
  │                                     │
  │  (si es extensión) Hub envía        │
  │  STORE_REGISTRY + eventos bufferizados |

El mismo intercambio con cada resultado que produce el hub. Un cliente se registra solo cuando el token, la versión mayor y el id de su rol son válidos; cualquier fallo termina con el código de cierre 1008, igual que un cliente que no envía HANDSHAKE_REQUEST en 5 segundos.

#Documentación Técnica

TypeDoc documentación generada automáticamente (en Inglés).

#Referencia de API

#Constantes

#Funciones

#Tipos

#Paquetes Relacionados

• @yoltra/devtools-server: Hub WebSocket que enruta mensajes del protocolo
• @yoltra/devtools-browser-agent: Wrapper de store para navegador
• @yoltra/devtools-ui: Hooks de React para consumir mensajes del protocolo

#Licencia

MIT: Libre de usar en proyectos comerciales y de código abierto.