threshold-history 📈🚨💡

Threshold-aware value tracking with smart alerts & time-in-range stats

🚀 Why Use This?

Track values over time, get alerted when thresholds are crossed, and calculate how often values stay in desired ranges. Like a Fitbit for your IoT devices! 🔋📡

📦 Installation

# Using Bun (recommended)
bun add threshold-history

# Using npm
npm install threshold-history

💻 Quick Start

// REMOVED external import: import { ValueTracker } from 'threshold-history';

// Monitor room temperature between 18°C-25°C
const tracker = new ValueTracker({
  thresholds: [
    { value: 18, direction: 'above', label: 'too-cold' },
    { value: 25, direction: 'below', label: 'too-hot' }
  ],
  bufferSize: 1000
});

// Add temperature readings
tracker.addValue(22, Date.now() - 3600_000); // 1 hour ago
tracker.addValue(17.5); // Now - crosses lower threshold!

// Get critical events
console.log(tracker.getCrossings());
// Returns: [{ timestamp: 1717045200000, threshold: 'too-cold', direction: 'below' }]

// Calculate time-in-range
console.log(tracker.getStats().inRangePercentage);
// Returns: 97.2 (percent of time in acceptable range)

📖 Core API

ValueTracker(config)

• config.thresholds: Array of ThresholdConfig

  type ThresholdConfig = {
    value: number;
    direction: 'above' | 'below';
    label: string;
  };

• config.bufferSize: Max stored entries (default: 1000)

Key Methods

• .addValue(value: number, timestamp = Date.now())
  Record new measurement
• .getCrossings(): ThresholdCrossing[]
  Returns threshold crossings with timestamps
• .getStats(): TrackingStats
  Returns time-in-range %, total duration, and value statistics

🧪 Real-World Example

// Monitor server CPU temperature
const serverMonitor = new ValueTracker({
  thresholds: [
    { value: 70, direction: 'above', label: 'overheat-warning' },
    { value: 90, direction: 'above', label: 'critical-shutdown' }
  ]
});

// Simulate temperature spikes
serverMonitor.addValue(65);
serverMonitor.addValue(72); // Triggers warning
serverMonitor.addValue(85);
serverMonitor.addValue(91); // Critical shutdown!

console.log(serverMonitor.getStats());
// {
//   inRangePercentage: 66.6,
//   totalDuration: 3600000,
//   valueStats: { min: 65, max: 91, avg: 78.25 }
// }

🤝 Contributing

Found a bug? Got a cool idea?

1. Fork it 🍴
2. Code it 💻
3. PR it 🚀
   We <3 quality contributions!

📄 License

MIT © AdametherzLab
Made with ❤️ and enough caffeine to power a small city