@yoltra/devtools-browser-agent 0.5.0 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.es.md +163 -0
- package/README.md +1 -1
- package/package.json +13 -12
package/README.es.md
ADDED
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
|
|
2
|
+
|
|
3
|
+
# @yoltra/devtools-browser-agent
|
|
4
|
+
|
|
5
|
+
> 👉 🇲🇽 Versión en Español | [ 🇺🇸 English Version](./README.md)
|
|
6
|
+
|
|
7
|
+
**Agente de DevTools para el navegador — conecta un store de Yoltra al hub de DevTools desde el
|
|
8
|
+
navegador.**
|
|
9
|
+
|
|
10
|
+
`@yoltra/devtools-browser-agent` instrumenta un store de Yoltra de forma transparente, así que
|
|
11
|
+
cada evento, cambio de estado y métrica se reenvía al hub de DevTools en tiempo real. Usa la API
|
|
12
|
+
nativa `WebSocket` del navegador (sin dependencia de `ws`), con reconexión automática y búfer de
|
|
13
|
+
mensajes.
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## Instalación
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
npm install @yoltra/devtools-browser-agent
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
**Dependencia peer:** `@yoltra/core`
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Inicio rápido
|
|
28
|
+
|
|
29
|
+
```typescript
|
|
30
|
+
import { createStore } from "@yoltra/core";
|
|
31
|
+
import { withDevtools } from "@yoltra/devtools-browser-agent";
|
|
32
|
+
|
|
33
|
+
const store = createStore({
|
|
34
|
+
name: "TodoApp",
|
|
35
|
+
reducer: {
|
|
36
|
+
todos: {
|
|
37
|
+
state: { items: [] },
|
|
38
|
+
when: { channel: "todos" },
|
|
39
|
+
reducer: (state, event) => {
|
|
40
|
+
if (event.type === "add") return { items: [...state.items, event.payload] };
|
|
41
|
+
return state;
|
|
42
|
+
},
|
|
43
|
+
},
|
|
44
|
+
},
|
|
45
|
+
});
|
|
46
|
+
|
|
47
|
+
// Instrumenta el store — se conecta al hub en ws://localhost:9800
|
|
48
|
+
withDevtools(store, { port: 9800 });
|
|
49
|
+
|
|
50
|
+
// Usa el store con normalidad — los eventos se reenvían automáticamente
|
|
51
|
+
await store.emit("todos", "add", { title: "Comprar leche" });
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
---
|
|
55
|
+
|
|
56
|
+
## Cómo funciona
|
|
57
|
+
|
|
58
|
+
1. **Registra un efecto `when: { any: true }`** en el store para interceptar cada evento
|
|
59
|
+
2. **Calcula diferencias en JSON Patch** entre el estado anterior y el siguiente
|
|
60
|
+
3. **Envía mensajes `STORE_EVENT`** con los parches al hub
|
|
61
|
+
4. **Almacena mensajes en un búfer** (hasta 100) mientras está desconectado, y los vacía al
|
|
62
|
+
reconectar
|
|
63
|
+
5. **Atiende los comandos entrantes** de las extensiones:
|
|
64
|
+
- `REQUEST_STATE` → instantánea completa del estado
|
|
65
|
+
- `REQUEST_METRICS` → contadores de rendimiento
|
|
66
|
+
- `REQUEST_SUBSCRIPTIONS` → inventario de reducers y efectos
|
|
67
|
+
- `TIME_TRAVEL` → restaura el store a un estado anterior
|
|
68
|
+
- `EVENT_REPLAY` → reproduce eventos pasando solo por los reducers
|
|
69
|
+
- `EMIT_TO_STORE` → inyecta un evento sintético
|
|
70
|
+
|
|
71
|
+
El envoltorio es **transparente**: devuelve la misma instancia del store.
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Configuración
|
|
76
|
+
|
|
77
|
+
```typescript
|
|
78
|
+
interface DevtoolsWrapperConfig {
|
|
79
|
+
/** Puerto del servidor hub. Requerido. */
|
|
80
|
+
port: number;
|
|
81
|
+
/** Host del servidor hub. @default "localhost" */
|
|
82
|
+
host?: string;
|
|
83
|
+
/** ID persistente del store (sobrevive a las reconexiones). @default crypto.randomUUID() */
|
|
84
|
+
storeId?: string;
|
|
85
|
+
/** Habilita el viaje en el tiempo y la reproducción de eventos. @default false */
|
|
86
|
+
allowReplay?: boolean;
|
|
87
|
+
/** Permite que las extensiones emitan eventos a este store. @default false */
|
|
88
|
+
allowEmit?: boolean;
|
|
89
|
+
/** Reconexión automática al desconectarse. @default true */
|
|
90
|
+
autoReconnect?: boolean;
|
|
91
|
+
/** Máximo de intentos de reconexión. @default Infinity */
|
|
92
|
+
maxReconnectAttempts?: number;
|
|
93
|
+
/** Retardo base para el backoff exponencial (ms). @default 1000 */
|
|
94
|
+
baseDelay?: number;
|
|
95
|
+
/** Tope máximo de retardo para el backoff (ms). @default 30000 */
|
|
96
|
+
maxDelay?: number;
|
|
97
|
+
}
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### Configuración completa
|
|
101
|
+
|
|
102
|
+
```typescript
|
|
103
|
+
withDevtools(store, {
|
|
104
|
+
port: 9800,
|
|
105
|
+
storeId: "my-app-store",
|
|
106
|
+
allowReplay: true,
|
|
107
|
+
allowEmit: true,
|
|
108
|
+
autoReconnect: true,
|
|
109
|
+
maxReconnectAttempts: 20,
|
|
110
|
+
baseDelay: 1000,
|
|
111
|
+
maxDelay: 15000,
|
|
112
|
+
});
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
---
|
|
116
|
+
|
|
117
|
+
## Reconexión
|
|
118
|
+
|
|
119
|
+
El agente usa backoff exponencial con jitter para reconectarse:
|
|
120
|
+
|
|
121
|
+
- Empieza en `baseDelay` (1 s por defecto)
|
|
122
|
+
- Se duplica en cada intento, con tope en `maxDelay` (30 s por defecto)
|
|
123
|
+
- Añade un 10 % de jitter para evitar la estampida de reconexiones
|
|
124
|
+
- Los mensajes se guardan en un búfer durante las desconexiones y se vacían al reconectar
|
|
125
|
+
|
|
126
|
+
---
|
|
127
|
+
|
|
128
|
+
## Referencia de la API
|
|
129
|
+
|
|
130
|
+
| Export | Descripción |
|
|
131
|
+
| ----------------------------- | ---------------------------------------------- |
|
|
132
|
+
| `withDevtools(store, config)` | Instrumenta un store y lo conecta al hub |
|
|
133
|
+
| `DevtoolsWrapperConfig` | Tipo de configuración |
|
|
134
|
+
|
|
135
|
+
---
|
|
136
|
+
|
|
137
|
+
## Comparación con `@yoltra/devtools-node-agent`
|
|
138
|
+
|
|
139
|
+
| Característica | `devtools-browser-agent` | `devtools-node-agent` |
|
|
140
|
+
| ------------------ | ------------------------ | ------------------------- |
|
|
141
|
+
| Entorno | Navegador | Node.js |
|
|
142
|
+
| WebSocket | API nativa `WebSocket` | Paquete `ws` |
|
|
143
|
+
| Impacto en bundle | Cero dependencias | Añade `ws` |
|
|
144
|
+
| Caso de uso | SPAs, apps de navegador | Servidores, CLIs, SSR |
|
|
145
|
+
|
|
146
|
+
Ambos agentes ofrecen la misma instrumentación y el mismo cumplimiento del protocolo.
|
|
147
|
+
|
|
148
|
+
---
|
|
149
|
+
|
|
150
|
+
## Paquetes relacionados
|
|
151
|
+
|
|
152
|
+
- **[@yoltra/devtools-protocol](../devtools-protocol/README.md)** — Formato de cable y tipos de
|
|
153
|
+
mensaje
|
|
154
|
+
- **[@yoltra/devtools-server](../devtools-server/README.md)** — El hub al que se conecta este
|
|
155
|
+
agente
|
|
156
|
+
- **[@yoltra/devtools-ext](../devtools-ext/README.md)** — Extensión de navegador que muestra la UI
|
|
157
|
+
- **[@yoltra/core](../../packages/core/README.md)** — El store que se instrumenta
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## Licencia
|
|
162
|
+
|
|
163
|
+
**MIT** — De uso libre en proyectos comerciales y de código abierto.
|
package/README.md
CHANGED
package/package.json
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@yoltra/devtools-browser-agent",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.7.0",
|
|
4
4
|
"description": "Browser store agent for Yoltra DevTools — instruments stores and reports to the hub via native WebSocket",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": {
|
|
7
7
|
"name": "Manu Ramirez <@pixerael>",
|
|
8
|
-
"email": "
|
|
8
|
+
"email": "opensource@yoltra.dev"
|
|
9
9
|
},
|
|
10
10
|
"maintainers": [],
|
|
11
11
|
"homepage": "https://yoltra.dev",
|
|
@@ -38,25 +38,26 @@
|
|
|
38
38
|
],
|
|
39
39
|
"sideEffects": false,
|
|
40
40
|
"peerDependencies": {
|
|
41
|
-
"@yoltra/core": "^0.
|
|
41
|
+
"@yoltra/core": "^0.7.0"
|
|
42
42
|
},
|
|
43
43
|
"dependencies": {
|
|
44
|
-
"@yoltra/devtools-protocol": "0.
|
|
44
|
+
"@yoltra/devtools-protocol": "0.7.0"
|
|
45
45
|
},
|
|
46
46
|
"devDependencies": {
|
|
47
|
+
"@vitest/coverage-v8": "3.2.7",
|
|
47
48
|
"typedoc": "^0.28.13",
|
|
48
|
-
"typedoc-plugin-markdown": "4.9.0",
|
|
49
49
|
"typedoc-plugin-localization": "3.0.6",
|
|
50
|
+
"typedoc-plugin-markdown": "4.9.0",
|
|
50
51
|
"typescript": "5.9.3",
|
|
51
|
-
"vite": "^7.
|
|
52
|
-
"vite-plugin-dts": "^4.5.4",
|
|
52
|
+
"vite": "^7.3.6",
|
|
53
53
|
"vite-plugin-banner": "0.8.1",
|
|
54
|
-
"
|
|
55
|
-
"
|
|
56
|
-
"@yoltra/devtools-ui": "0.
|
|
54
|
+
"vite-plugin-dts": "^4.5.4",
|
|
55
|
+
"vitest": "3.2.7",
|
|
56
|
+
"@yoltra/devtools-ui": "0.7.0",
|
|
57
|
+
"@yoltra/core": "0.7.0"
|
|
57
58
|
},
|
|
58
59
|
"engines": {
|
|
59
|
-
"node": ">=18
|
|
60
|
+
"node": ">=18"
|
|
60
61
|
},
|
|
61
62
|
"publishConfig": {
|
|
62
63
|
"access": "public"
|
|
@@ -74,7 +75,7 @@
|
|
|
74
75
|
"scripts": {
|
|
75
76
|
"build": "vite build && node ../../tools/repo-tools/bin/dts-extensions.mjs dist/types",
|
|
76
77
|
"lint": "node ../../tools/repo-tools/bin/repo-eslint.cjs --report-unused-disable-directives --max-warnings 0",
|
|
77
|
-
"test": "vitest --watch=false",
|
|
78
|
+
"test": "vitest --coverage --watch=false",
|
|
78
79
|
"typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.vitest.json --noEmit",
|
|
79
80
|
"docs": "rushx docs:js && rushx docs:md && rushx docs:stamp",
|
|
80
81
|
"docs:stamp": "node ../../tools/repo-tools/bin/docs-stamp.mjs docs",
|