Timeslip Debugger (Console Recorder)

✨ A powerful tool that records all console logs, variable snapshots, and API results, then lets developers replay them later as if debugging in real-time.

Why it's cool

• 🐛 Debug production issues without replicating environment
• 📹 Playback logs step-by-step with timing preservation
• 🔍 Inspect variable states at any point in time
• 🌐 Track API requests/responses with full details
• ⏱️ Timeslip debugging - replay at different speeds

Installation

npm install timeslip-debugger

Quick Start

Basic Usage

import { quickStart } from 'timeslip-debugger';

// Start recording automatically
const debug = quickStart();

// Your application code
console.log('Hello, world!');
console.error('Something went wrong');

// Capture variable snapshots
let user = { name: 'John', age: 30 };
debug.snapshot('user', user);

// Stop recording and save
debug.stop();
debug.save('my-recording.json');

Advanced Usage

import { createRecorder, createPlayback } from 'timeslip-debugger';

// Create recorder
const recorder = createRecorder();

// Start recording
recorder.start();

// Your application runs here
console.log('App started');
fetch('/api/users').then(r => r.json()).then(console.log);

// Capture snapshots
const state = { count: 42, items: ['a', 'b', 'c'] };
recorder.snapshot('appState', state, 'main');

// Stop recording
recorder.stop();

// Export recording
const recording = recorder.export();
console.log(recording);

// Or save to file
recorder.save('production-bug.json');

Playback

import { createPlayback } from 'timeslip-debugger';
import fs from 'fs';

// Load a recording
const recordingData = fs.readFileSync('production-bug.json', 'utf-8');
const session = JSON.parse(recordingData);

// Create playback instance
const playback = createPlayback(session);

// Play back at 2x speed
playback.play({
  speed: 2,
  onEntry: (entry) => {
    console.log('Playing entry:', entry.type);
  },
  onComplete: () => {
    console.log('Playback complete!');
  },
});

// Or play with filters
playback.play({
  filter: (entry) => entry.type === 'console' || entry.type === 'error',
  speed: 1.5,
});

// Control playback
playback.pause();
playback.play({ speed: 1 });
playback.stop();
playback.seek(5000); // Seek to 5 seconds in

API Reference

TimeTravelRecorder

Methods

• start() - Start recording console logs, API calls, and variable snapshots
• stop() - Stop recording
• snapshot(name: string, value: any, scope?: string) - Capture a variable snapshot
• getSession() - Get the current recording session
• export() - Export recording as JSON string
• save(filename?: string) - Save recording to file (browser: download, Node.js: write to disk)
• load(json: string) - Load a recording from JSON string
• clear() - Clear current recording

TimeTravelPlayback

Methods

• play(options?: PlaybackOptions) - Play back the recording
• pause() - Pause playback
• stop() - Stop playback and reset
• seek(timestamp: number) - Seek to a specific timestamp
• getStatus() - Get current playback status

PlaybackOptions

interface PlaybackOptions {
  speed?: number;              // Playback speed (1 = real-time, 2 = 2x, 0.5 = half)
  onEntry?: (entry) => void;   // Callback for each entry
  onComplete?: () => void;      // Callback when playback completes
  filter?: (entry) => boolean;  // Filter entries to play
}

Examples

Recording API Calls

import { createRecorder } from 'timeslip-debugger';

const recorder = createRecorder();
recorder.start();

// All fetch and XHR calls are automatically recorded
fetch('/api/users')
  .then(res => res.json())
  .then(data => {
    console.log('Users:', data);
    recorder.snapshot('users', data);
  });

recorder.stop();
recorder.save('api-calls.json');

Debugging Production Issues

// In production code (with error handling)
import { createRecorder } from 'timeslip-debugger';

const recorder = createRecorder();

// Only start recording on errors
window.addEventListener('error', () => {
  recorder.start();
});

// After issue occurs, user can download recording
function downloadDebugInfo() {
  recorder.stop();
  recorder.save('error-debug.json');
}

Replaying in Development

// In development environment
import { createPlayback } from 'timeslip-debugger';

// Load production recording
const session = require('./error-debug.json');
const playback = createPlayback(session);

// Play back step by step
playback.play({
  speed: 1,
  onEntry: (entry) => {
    if (entry.type === 'error') {
      console.log('Error found:', entry.data);
    }
  },
});

Variable State Tracking

import { createRecorder } from 'timeslip-debugger';

const recorder = createRecorder();
recorder.start();

let count = 0;
function increment() {
  count++;
  recorder.snapshot('count', count, 'increment');
}

increment(); // count = 1
increment(); // count = 2
increment(); // count = 3

recorder.stop();
recorder.save('state-tracking.json');

Features

✅ Console Log Recording

• Captures all console methods: log, warn, error, info, debug
• Preserves stack traces for errors
• Maintains original console output

✅ Variable Snapshots

• Deep clone variables at any point
• Handle circular references safely
• Support for complex objects, arrays, Maps, Sets

✅ API Request/Response Tracking

• Intercepts fetch API calls
• Intercepts XMLHttpRequest calls
• Records headers, body, status, duration
• Tracks request/response pairs

✅ Playback System

• Time-accurate replay
• Adjustable playback speed
• Filtering capabilities
• Step-by-step execution

Browser Support

Works in all modern browsers that support:

• ES2020 features
• Fetch API (or XMLHttpRequest fallback)
• Console API

Node.js Support

Works in Node.js 14+ with:

• Fetch API (Node 18+) or polyfill
• File system access for saving recordings

License

MIT

Contributing

Contributions welcome! Please feel free to submit a Pull Request.