Home / packages / core-debug / README

@larcjs/core-debug

![Version](https://www.npmjs.com/package/@larcjs/core-debug) ![License](LICENSE) ![Bundle Size](#)
Debug and tracing tools - Advanced debugging capabilities for PAN messages

Add comprehensive debugging and message tracing to LARC Core or Core Lite. Essential for development and troubleshooting complex message flows.

Installation

# Requires @larcjs/core or @larcjs/core-lite
npm install @larcjs/core-debug

Quick Start

<pan-bus debug="true" enable-tracing="true"></pan-bus>

<script type="module">
import '@larcjs/core-debug';

// Access debug manager
const debug = window.pan.debug;

// Enable tracing
debug.enableTracing();

// View message history
console.log(debug.getMessageHistory());

// Export state snapshot
const snapshot = debug.captureSnapshot();
console.log(JSON.stringify(snapshot, null, 2));
</script>

Features

  • 🔍 Message Tracing - Track all messages with full metadata
  • 📊 Performance Metrics - Handler duration, message sizes
  • 📸 State Snapshots - Export/import complete bus state
  • 🎯 Filtering - Filter messages by topic patterns
  • ⏱️ Timeline - View message history with timestamps
  • 📦 Export/Import - Save and restore state for debugging

API Reference

debug.enableTracing()

Start tracking all messages.

window.pan.debug.enableTracing();

debug.disableTracing()

Stop tracking messages.

window.pan.debug.disableTracing();

debug.getMessageHistory(filter?)

Get tracked messages, optionally filtered.

// All messages
const all = debug.getMessageHistory();

// Filtered by topic pattern
const filtered = debug.getMessageHistory('user.*');

debug.captureSnapshot()

Capture current bus state.

const snapshot = debug.captureSnapshot();
// Returns: { timestamp, messages, retained, subscriptions, stats }

debug.clear()

Clear message history.

debug.clear();

Usage with

The debug manager powers the component:

<pan-inspector></pan-inspector>

Features:

  • Real-time message monitoring
  • State tree visualization
  • Performance metrics dashboard
  • Export/import state snapshots

Development Workflow

1. Enable Debug Mode

<pan-bus debug="true" enable-tracing="true"></pan-bus>

2. Monitor Messages

// Watch console for debug logs
// [PAN Bus] Published { topic: 'user.login', delivered: 3, routes: 1 }

3. Inspect State

// View current retained state
const state = debug.captureSnapshot();
console.table(state.retained);

4. Export for Bug Reports

// Export state snapshot for sharing
const snapshot = debug.captureSnapshot();
navigator.clipboard.writeText(JSON.stringify(snapshot, null, 2));

Performance Impact

  • Overhead: ~5% when tracing enabled
  • Memory: Stores last 1000 messages (configurable)
  • Production: Automatically stripped in minified builds

Bundle Size

  • Minified: 3.0KB
  • Gzipped: ~1KB

Related Packages

License

MIT © Chris Robison