@mode-7/raceway

Official Node.js/TypeScript SDK for Raceway - Race condition detection and distributed tracing for Node.js applications.

📚 Full Documentation

Features

• Three instrumentation approaches: Proxy-based auto-tracking, Babel plugin, or manual tracking
• Automatic lock tracking helpers: withLock() for easy lock instrumentation
• Automatic context propagation using AsyncLocalStorage
• Distributed tracing across service boundaries (W3C Trace Context)
• Race condition detection and concurrency bug analysis
• Express/Connect middleware support

Installation

npm install @mode-7/raceway

Quick Start

import express from 'express';
import { Raceway } from '@mode-7/raceway';

const raceway = new Raceway({
  serverUrl: 'http://localhost:8080',
  serviceName: 'my-service'
});

const app = express();
app.use(express.json());
app.use(raceway.middleware());

// Auto-track state changes with Proxies
const accounts = raceway.track({
  alice: { balance: 1000 },
  bob: { balance: 500 }
}, 'accounts');

app.post('/transfer', async (req, res) => {
  const { from, to, amount } = req.body;

  // Automatically tracked!
  const balance = accounts[from].balance;
  if (balance < amount) {
    return res.status(400).json({ error: 'Insufficient funds' });
  }

  accounts[from].balance -= amount;
  accounts[to].balance += amount;

  res.json({ success: true });
});

app.listen(3000);

Distributed Tracing

Propagate traces across service boundaries:

import axios from 'axios';

app.post('/checkout', async (req, res) => {
  const { orderId } = req.body;

  // Get propagation headers
  const headers = raceway.propagationHeaders();

  // Call downstream services
  await axios.post('http://inventory-service/reserve',
    { orderId },
    { headers }
  );

  res.json({ success: true });
});

Which Approach Should I Use?

• Have shared mutable objects? → Use raceway.track() for auto-tracking
• Need to track local variables? → Use Babel plugin for zero-code instrumentation
• Want precise control? → Use manual tracking API
• Need lock tracking? → Use withLock() helpers

Documentation

• 📚 Full SDK Documentation - Complete API reference, examples, and best practices
• 🚀 Getting Started Guide - Step-by-step setup
• 🔍 Race Detection Guide - Understanding race conditions
• 🌐 Distributed Tracing - Cross-service tracing
• 🔐 Security Guide - Best practices

Examples

See examples/typescript-banking for a complete Express.js application with Raceway integration.

License

MIT

Links

• GitHub Repository
• Documentation
• Issue Tracker