@xpulse/debug – Component Concept

1
@xpulse/debug
2
  ├── CLI Layer          ← debug:* commands for the terminal
3
  ├── Template Layer     ← {% debug(variable) %} directly in templates
4
  ├── Collector Layer    ← DataCollector base class + discovery
5
  ├── Toolbar            ← slim browser bar with badges + link to profiler
6
  └── Web Profiler       ← separate interface with panels, sub-panels, areas

1
1. node_modules/@xpulse/debug/src/datacollectors/*.js   ← @xpulse/debug built-ins
2
2. node_modules/@xpulse/*/src/datacollectors/*.js       ← other @xpulse packages
3
3. src/datacollectors/*.js                              ← the app itself

1
:root {
2
  --bg:       #0d0d0d;
3
  --surface:  #141414;
4
  --border:   #222;
5
  --muted:    #444;
6
  --text:     #c8c8c8;
7
  --text-dim: #555;
8
  --accent:   #8703b0;
9
  --accent2:  #7eb8a4;
10
  --danger:   #c0606a;
11
  --mono:     'JetBrains Mono', ui-monospace, 'Cascadia Code', 'Fira Code', Consolas, monospace;
12
  --serif:    'Fraunces', Georgia, ui-serif, serif;
13
}

1
@xpulse/debug
2
  ├── @xpulse/event      ← collectors listen via this.on()
3
  ├── @xpulse/config     ← check debug.enabled
4
  ├── @xpulse/router     ← register profiler routes
5
  ├── @xpulse/template   ← panel rendering + register {% debug() %}
6
  └── @xpulse/cli        ← debug:* commands via autodiscovery

1
// xpulse.json
2
{
3
  "debug": {
4
    "enabled": true,
5
    "toolbar": true,
6
    "web-profiler": {
7
      "enabled": true,
8
      "excluded-routes": ["/_debug/*"]
9
    }
10
  }
11
}

1
# .env.development
2
DEBUG=true

1
npx xpulse debug:events:list      # all registered events with listener count
2
npx xpulse debug:config:show      # loaded configuration (xpulse.json + .env)
3
npx xpulse debug:routes:list      # registered routes with name + method
4
npx xpulse debug:packages:list    # installed @xpulse/* packages with versions

1
{% debug(variable) %}
2
{% debug(config) %}
3
{% debug(_route) %}

1
// package.json of an @xpulse/* package with a collector
2
"optionalDependencies": {
3
  "@xpulse/debug": "^1.0.0"
4
}

1
"exports": {
2
  ".":          "./src/index.js",
3
  "./collector": "./src/collector.js"
4
}

1
import { DataCollector } from '@xpulse/debug/collector';

1
import { DataCollector } from '../collector.js';

1
// ✗ Wrong – breaks with concurrent requests
2
export default class MyCollector extends DataCollector {
3
    _data = null;  // ← overwritten by the next request
4
 
5
    async collect() {
6
        this.on('my:event', (payload) => { this._data = payload; });
7
        this.on('http:response', () => { this.addArea({ value: this._data }); });
8
    }
9
}
10
 
11
// ✓ Correct – each request has its own state
12
export default class MyCollector extends DataCollector {
13
    _data = new Map(); // traceId → data
14
 
15
    async collect() {
16
        this.on('my:event', (payload, traceId) => {
17
            this._data.set(traceId, payload);
18
        });
19
        this.on('http:response', (payload, traceId) => {
20
            this.addArea({ value: this._data.get(traceId) });
21
            this._data.delete(traceId);
22
        });
23
    }
24
}

1
// src/datacollectors/HttpCollector.js
2
import { DataCollector } from '@xpulse/debug/collector';
3
 
4
export default class HttpCollector extends DataCollector {
5
    _reqs = new Map(); // traceId → { req, startedAt }
6
 
7
    configure() {
8
        this
9
            .setName('http')
10
            .setIcon('🌐')
11
            .setPackage('@xpulse/http');
12
    }
13
 
14
    async collect() {
15
        this.on('http:request', (payload, traceId) => {
16
            this._reqs.set(traceId, { req: payload, startedAt: Date.now() });
17
        });
18
 
19
        this.on('http:response', (payload, traceId) => {
20
            const { status, duration } = payload;
21
            const entry = this._reqs.get(traceId);
22
            this._reqs.delete(traceId);
23
 
24
            this.setBadge(`${status} · ${duration}ms`);
25
 
26
            this.addArea({
27
                title: 'Request',
28
                type:  'kv',
29
                value: {
30
                    Method:   entry?.req?.method ?? '-',
31
                    Path:     entry?.req?.path   ?? '-',
32
                    Status:   status,
33
                    Duration: `${duration}ms`,
34
                },
35
            });
36
 
37
            this.addSpan({
38
                kind:     'http',
39
                label:    'http',
40
                start:    entry?.startedAt ?? (Date.now() - duration),
41
                duration: duration ?? 0,
42
            });
43
        });
44
    }
45
}

1
this.addSubPanel({
2
    title: payload.view,
3
    areas: [
4
        { title: 'Info',          type: 'kv',   value: { View: payload.view, Duration: `${payload.duration}ms` } },
5
        { title: 'Template Data', type: 'kv',   value: payload.data },
6
        { title: 'Extends Chain', type: 'list', value: payload.chain.map(c => c.view ?? c) },
7
    ],
8
});

1
{
2
  "panel-name": "http",
3
  "icon":       "🌐",
4
  "package":    "@xpulse/http",
5
  "badge":      "200 · 12ms",
6
  "areas": [
7
    {
8
      "title": "Request",
9
      "type":  "kv",
10
      "value": { "Method": "GET", "Path": "/info", "Status": 200, "Duration": "12ms" }
11
    }
12
  ],
13
  "sub-panels": []
14
}

1
const origEmit = event.emit;
2
event.emit = (name, data) => {
3
    if (!SKIP.has(name)) {
4
        const traceId = this._ctx.extractTraceId?.(data) ?? this._ctx.getCurrentTraceId?.();
5
        if (traceId) this._ctx.addEvent?.(traceId, { name, ts: Date.now(), data });
6
    }
7
    return origEmit.call(event, name, data);
8
};

1
var/cache/debug/
2
  _{traceId}/
3
    trace.json              ← base: method, path, status, duration, spans[], events[]
4
    packages/
5
      debug.json            ← DebugCollector
6
      http.json             ← HttpCollector
7
      router.json           ← RouterCollector
8
      controller.json       ← ControllerCollector
9
      template.json         ← TemplateCollector
10
      events.json           ← EventsCollector
11
      logger.json           ← LoggerCollector
12
      config.json           ← ConfigCollector
13
      env.json              ← EnvCollector
14
      my-cache.json         ← app-own collector

1
// src/datacollectors/MyCacheCollector.js
2
import { DataCollector } from '@xpulse/debug/collector';
3
 
4
export default class MyCacheCollector extends DataCollector {
5
    _hits = new Map(); // traceId → string[]
6
 
7
    configure() {
8
        this
9
            .setName('my-cache')
10
            .setIcon('💾')
11
            .setPackage('my-app');
12
    }
13
 
14
    async collect() {
15
        this.on('cache:hit', (payload, traceId) => {
16
            if (!this._hits.has(traceId)) this._hits.set(traceId, []);
17
            this._hits.get(traceId).push(payload.key);
18
        });
19
 
20
        this.on('http:response', (payload, traceId) => {
21
            const keys = this._hits.get(traceId) ?? [];
22
            this._hits.delete(traceId);
23
            this.setBadge(`${keys.length} hits`);
24
            this.addArea({ title: 'Cache Hits', type: 'list', value: keys });
25
        });
26
    }
27
}

1
┌──────────────────────────────────────────────────────────────────────────┐
2
│ my-app  ·  GET /info  ·  200  ·  12ms  │  ⚡ 18  │  📋 3  │  Profiler → │
3
└──────────────────────────────────────────────────────────────────────────┘

1
Click "Profiler →" in the toolbar
2
    ↓
3
/_debug/web-profiler/{traceId}/summary/

1
┌──────────────────────────────────────────────────────────────────────────┐
2
│  xPulse Profiler v1.0.0                        trace abc123              │
3
├─────────────────────┬────────────────────────────────────────────────────┤
4
│                     │                                                    │
5
│  @xpulse/debug      │  Panel content                                     │
6
│    Summary          │  ──────────────────────────────────────────────    │
7
│    Waterfall        │  Areas with structured data                        │
8
│  @xpulse/http       │                                                    │
9
│    Http         ←   │  ┌─────────────────────────────────────────────┐  │
10
│  @xpulse/router     │  │ Request                                 [kv] │  │
11
│    Router           │  │  Method   GET                                │  │
12
│  @xpulse/controller │  │  Path     /info                              │  │
13
│    Controller       │  │  Status   200                                │  │
14
│  @xpulse/template   │  │  Duration 12ms                               │  │
15
│    Template         │  └─────────────────────────────────────────────┘  │
16
│    › index          │                                                    │
17
│    › base           │                                                    │
18
│  @xpulse/event      │                                                    │
19
│    Events           │                                                    │
20
│  @xpulse/logger     │                                                    │
21
│    Logger           │                                                    │
22
│  @xpulse/config     │                                                    │
23
│    Config           │                                                    │
24
│  my-app             │                                                    │
25
│    My Cache         │                                                    │
26
└─────────────────────┴────────────────────────────────────────────────────┘

1
GET /_debug/web-profiler/{traceId}/{panelId}/
2
    ↓
3
Profiler reads var/cache/debug/_{traceId}/packages/*.json
4
    ↓
5
Builds sidebar dynamically from panel-name + package + sub-panels
6
    ↓
7
Renders the active panel via @xpulse/template
8
    ↓
9
Areas are rendered inline via renderArea() in profiler.js

1
[2026-03-24T09:12:34.123Z] (info ) [http]        GET /info 200 12ms
2
[2026-03-24T09:12:34.119Z] (debug) [controller]  InfoController@index aufgerufen
3
[2026-03-24T09:12:34.115Z] (debug) [template]    render info/index 4ms

1
@xpulse/debug/src/templates/web-profiler/
2
  dashboard.tpl.html              ← main layout: topbar + sidebar + content
3
  toolbar.tpl.html                ← toolbar HTML (injected into app)
4
  panels/
5
    summary.tpl.html              ← trace info + app name/ENV
6
    waterfall.tpl.html            ← time axis + span bars
7
    panel.tpl.html                ← generic panel: outputs areasHtml

1
@xpulse/debug/
2
  src/
3
    collector.js                  ← DataCollector base class (exported via ./collector)
4
    index.js                      ← init(), bootstrapDebug(), event.emit hook for logging
5
    profiler.js                   ← collector discovery, toolbar inject, routes, cache
6
    commands/
7
      ConfigShowCommand.js
8
      EventsListCommand.js
9
      PackagesListCommand.js
10
      RoutesListCommand.js
11
    datacollectors/
12
      DebugCollector.js           ← profiler metadata (version, collectors, config)
13
    template-methods/
14
      debug.js                    ← {% debug() %} registration + type rendering
15
    templates/
16
      web-profiler/
17
        dashboard.tpl.html
18
        toolbar.tpl.html
19
        panels/
20
          summary.tpl.html
21
          waterfall.tpl.html
22
          panel.tpl.html
23
  receipt/
24
    up.js
25
    down.js
26
  test/
27
  package.json
28
  xpulse.json

1
@xpulse/http/src/datacollectors/HttpCollector.js
2
@xpulse/router/src/datacollectors/RouterCollector.js
3
@xpulse/controller/src/datacollectors/ControllerCollector.js
4
@xpulse/template/src/datacollectors/TemplateCollector.js
5
@xpulse/event/src/datacollectors/EventsCollector.js
6
@xpulse/logger/src/datacollectors/LoggerCollector.js
7
@xpulse/config/src/datacollectors/ConfigCollector.js
8
@xpulse/dotenv/src/datacollectors/EnvCollector.js