⏰ precise-time-ntp

The ultimate time synchronization library for Node.js applications

🚀 Sync with atomic clocks • Smooth correction • Server validation

---

🎯 What makes precise-time-ntp special?

✅ Atomic Precision - Sync with global NTP servers
✅ Smart System Drift Correction - Automatically compensates for clock drift over time
✅ Network Latency Compensation - Accounts for network delays in time calculations
✅ Server Coherence Validation - Validates consistency across multiple NTP servers
✅ Smooth Time Correction - Prevents jarring time jumps in applications
✅ Universal Compatibility - Works in Node.js backend + HTML frontend
✅ Zero Configuration - Works out of the box with intelligent defaults
✅ Production Hardened - Automatic failover, error handling, reconnection logic
✅ Blazing Fast - Under 50KB, optimized for performance

---

⚡ Quick Start

npm install precise-time-ntp

const timeSync = require('precise-time-ntp');

// Sync with atomic time (automatically handles system drift)
await timeSync.sync();

// Get precise time - accurate to the millisecond
console.log('Precise time:', timeSync.now());
console.log('System is off by:', timeSync.offset(), 'ms');

// Keep your app synchronized automatically
timeSync.startAutoSync(300000); // Re-sync every 5 minutes

🎉 That's it! Your app now uses atomic time with automatic drift correction.

---

Advanced Features

Server Validation

Automatically test multiple NTP servers for better reliability:

// Enable server validation (detects unreliable/inaccurate servers)
await timeSync.sync({ coherenceValidation: true });

Smooth Time Correction

Prevent jarring time jumps in your applications:

// Gradually adjust time instead of instant jumps (prevents breaking timers)
timeSync.setSmoothCorrection(true, {
    maxCorrectionJump: 1000,     // Max 1s instant jump (larger = gradual)
    correctionRate: 0.1,         // 10% gradual correction per sync cycle
    maxOffsetThreshold: 5000     // Force instant correction if >5s off (emergency)
});

await timeSync.sync({ coherenceValidation: true });
timeSync.startAutoSync(300000);

---

📖 Usage Examples

1. Basic Time Sync

const timeSync = require('precise-time-ntp');

// Sync with default NTP servers: pool.ntp.org, time.nist.gov, time.cloudflare.com
await timeSync.sync();

// Get precise time
console.log('Precise time:', timeSync.now());
console.log('ISO timestamp:', timeSync.timestamp());
console.log('System offset:', timeSync.offset(), 'ms');

2. Sync Configuration

const timeSync = require('precise-time-ntp');

// Custom configuration with server validation
await timeSync.sync({
    servers: ['time.cloudflare.com', 'time.google.com'],  // Custom NTP servers
    timeout: 5000,                                        // 5s timeout per server
    retries: 3,                                           // Retry 3 times if failed
    coherenceValidation: true  // Tests multiple servers for consistency (detects bad servers)
});

console.log('Synced with validated servers!');

3. Auto-Sync & Production Setup

const timeSync = require('precise-time-ntp');

// Basic auto-sync setup
await timeSync.sync({ 
    coherenceValidation: true  // Validate server consistency (recommended)
});
timeSync.startAutoSync(300000); // Re-sync every 5 minutes

// Production setup with smooth correction
timeSync.setSmoothCorrection(true, {
    maxCorrectionJump: 500,      // Max 0.5s instant jump (prevents app disruption)
    correctionRate: 0.1,         // 10% gradual correction per sync
    maxOffsetThreshold: 3000     // Force instant correction if >3s off
});

await timeSync.sync({ coherenceValidation: true });
timeSync.startAutoSync(300000);

console.log('Production time sync active!');
// Your computer's clock drifts ~1-2 seconds per day without auto-sync

4. Smooth Time Correction (Avoid Time Jumps)

const timeSync = require('precise-time-ntp');

// Configure smooth correction to prevent breaking running timers/intervals
timeSync.setSmoothCorrection(true, {
    maxCorrectionJump: 1000,     // Max 1s instant jump (larger jumps are gradual)
    correctionRate: 0.1,         // 10% gradual correction per sync cycle
    maxOffsetThreshold: 5000     // Force instant correction if >5s off (emergency)
});

await timeSync.sync({ 
    coherenceValidation: true    // Validate server consistency for accuracy
});
timeSync.startAutoSync(300000);

// Monitor when correction completes
timeSync.on('correctionComplete', (data) => {
    console.log(`🎯 Correction completed: ${data.finalOffset}ms`);
    if (data.converged) console.log('Perfect precision achieved');
});

5. Live HTML Clock

// Node.js server
const timeSync = require('precise-time-ntp');

await timeSync.sync({ 
    coherenceValidation: true    // Ensure accurate time for public display
});
timeSync.startWebSocketServer(8080);  // Broadcast time to web clients
timeSync.startAutoSync(300000);       // Keep time accurate automatically

<!-- HTML file -->
<h1 id="clock">Loading...</h1>
<script>
const ws = new WebSocket('ws://localhost:8080');
ws.onmessage = (e) => {
    const data = JSON.parse(e.data);
    document.getElementById('clock').textContent = 
        new Date(data.data.timestamp).toLocaleTimeString();
};
setInterval(() => ws.send('{"type":"getTime"}'), 1000);
</script>

6. Events & Error Handling

const timeSync = require('precise-time-ntp');

await timeSync.sync({ 
    coherenceValidation: true    // Enable server validation events
});

// Basic sync events
timeSync.on('sync', (data) => {
    console.log(`✅ Synced with ${data.server} (offset: ${data.offset}ms)`);
});

timeSync.on('error', (error) => {
    console.log(`❌ Sync failed: ${error.message}`);
});

---

📊 API Reference

Method	Purpose	Example
sync()	Sync with NTP servers	await timeSync.sync()
now()	Get precise timestamp (ms)	timeSync.now()
timestamp()	Get ISO string	timeSync.timestamp()
offset()	Get system drift (ms)	timeSync.offset()
stats()	Get detailed sync info	timeSync.stats()
startAutoSync(ms)	Auto-sync every X ms	timeSync.startAutoSync(300000)
stopAutoSync()	Stop auto-sync	timeSync.stopAutoSync()
setSmoothCorrection()	Configure gradual time correction	timeSync.setSmoothCorrection(true, options)
startWebSocketServer(port)	Enable HTML integration	timeSync.startWebSocketServer(8080)

---

🔍 System Monitoring & Diagnostics

For advanced monitoring and diagnostics in production environments:

Get Detailed Stats

Monitor synchronization status and performance:

const timeSync = require('precise-time-ntp');

await timeSync.sync();

// Get detailed synchronization information
const stats = timeSync.stats();
console.log(stats);

/* Output:
{
  synchronized: true,              // Sync status
  lastSync: 2025-07-06T19:18:27.130Z,  // Last sync time
  offset: -10,                     // Real system offset (ms)
  correctedOffset: -10,            // Currently applied offset (ms)
  targetOffset: -10,               // Target for smooth correction (ms)
  correctionInProgress: false,     // Whether correction is active
  uptime: 5432,                    // Time since sync (ms)
  config: {                        // Current configuration
    smoothCorrection: true,
    maxCorrectionJump: 1000,
    correctionRate: 0.1,
    maxOffsetThreshold: 5000
  }
}
*/

// Access specific values
console.log('System offset:', stats.offset, 'ms');
console.log('Is synchronized:', stats.synchronized);
console.log('Smooth correction active:', stats.correctionInProgress);

Server Monitoring

Monitor server coherence and detect inconsistencies:

// Monitor for server issues
timeSync.on('coherenceWarning', (data) => {
    console.log(`⚠️ Server variance detected: ${data.variance}ms`);
    console.log('Servers tested:', data.servers);
});

System Health Monitoring

Monitor system clock drift and correction progress:

// Monitor system clock drift
timeSync.on('driftWarning', (data) => {
    const hours = (data.elapsed / 3600000).toFixed(1);
    console.log(`⏰ System running ${hours}h without sync`);
});

// Monitor smooth correction completion
timeSync.on('correctionComplete', (data) => {
    console.log(`🎯 Correction completed: ${data.finalOffset}ms`);
    if (data.converged) console.log('Perfect convergence achieved');
});

---

📄 Complete Documentation

For detailed guides, advanced configuration, and troubleshooting:

👉 View Full Documentation

• Quick Start Guide - Get started in 5 minutes
• Complete API Reference - All methods and options
• WebSocket Integration - Real-time HTML clocks

📁 Examples:

• examples/basic.js - Simple time sync with stats
• examples/auto-sync.js - Automatic periodic synchronization
• examples/monitoring.js - Detailed synchronization diagnostics
• Smooth Correction Guide - Avoid time jumps
• FAQ & Troubleshooting - Common questions

Test It Now

npm run basic        # Simple sync test
npm run auto-sync    # Auto-sync test  
npm run websocket    # WebSocket + HTML demo

📄 License

MIT License - use anywhere, commercially or personally.

---

⏰ precise-time-ntp - Because timing matters

📖 Documentation • 🐛 Report Bug • 💡 Request Feature