real_ist_time

Get accurate Indian Standard Time (IST) from multiple reliable sources with automatic fallback and smart caching. Perfect for applications that need precise time independent of device clock settings.

✨ Why Use This Package?

• 🎯 Always Get IST Time - All sources return DateTime objects with IST values (UTC+5:30)
• 🔄 8 Reliable Sources - 5 NTP servers + 3 HTTP APIs with automatic fallback
• ⚡ Smart Caching - Reduces network requests while maintaining accuracy
• 🚀 Zero Configuration - Works out of the box with sensible defaults
• ⚙️ Highly Configurable - Customize timeouts, sources, and behavior
• 💪 Production Ready - Comprehensive error handling and testing

📦 Installation

Add to your pubspec.yaml:

dependencies:
  real_ist_time: ^1.0.0

Then run:

flutter pub get

🚀 Quick Start

Get IST Time

import 'package:real_ist_time/real_ist_time.dart';

// Get current IST time
DateTime istTime = await RealIstTime.getIstTime();
print('Current IST: $istTime');

// Get formatted time (24-hour)
String time = await RealIstTime.getFormattedIstTime();
print('Time: $time'); // "19:15:30"

// Get formatted time (12-hour)
String time12h = await RealIstTime.getFormattedIstTime12Hour();
print('Time: $time12h'); // "07:15:30 PM"

// Get full date and time
String fullDateTime = await RealIstTime.getFullDateTime();
print(fullDateTime); // "30 Nov 2025, 07:15:30 PM IST"

Get Time with Source Information

TimeSourceResult result = await RealIstTime.getIstTimeWithSource();
print('Time: ${result.dateTime}');
print('Source: ${result.source}'); // e.g., "Google NTP"
print('Latency: ${result.latency.inMilliseconds}ms');
print('From Cache: ${result.fromCache}');

🎯 Use Cases

Perfect for applications that need reliable IST time:

• Attendance Systems - Prevent time manipulation
• Exam Applications - Ensure accurate timing
• Booking Systems - Synchronize across devices
• Financial Apps - Accurate transaction timestamps
• Gaming - Fair gameplay timing
• Event Scheduling - Precise event timing

🔧 Advanced Usage

Custom Configuration

RealIstTime.configure(IstTimeConfig(
  useNtp: true,              // Enable NTP servers
  useHttp: true,             // Enable HTTP APIs
  useCache: true,            // Enable caching
  cacheDurationSeconds: 60,  // Cache for 60 seconds
  ntpTimeoutSeconds: 5,      // NTP timeout
  httpTimeoutSeconds: 10,    // HTTP timeout
  ntpServers: [              // Custom NTP servers
    'time.google.com',
    'time.cloudflare.com',
  ],
  httpApis: [                // Custom HTTP APIs
    'timeapi.io',
    'worldtimeapi.org',
  ],
));

Synchronous Cache Access

// Get cached time immediately (no network request)
DateTime? cachedTime = RealIstTime.getIstTimeSync();
if (cachedTime != null) {
  print('Cached IST: $cachedTime');
} else {
  // No cache, fetch from network
  DateTime freshTime = await RealIstTime.getIstTime();
}

Cache Management

// Get cache statistics
Map<String, dynamic> stats = RealIstTime.getCacheStatus();
print('Has cache: ${stats['hasCache']}');
print('Is valid: ${stats['isValid']}');
print('Age: ${stats['ageSeconds']} seconds');

// Clear cache to force fresh fetch
RealIstTime.clearCache();

Test All Sources

// Test all available sources (useful for debugging)
List<TimeSourceResult> results = await RealIstTime.testAllSources();
for (var result in results) {
  print('${result.source}: ${result.dateTime} (${result.latency.inMilliseconds}ms)');
}

🌐 How It Works

The package tries to get IST time from multiple sources in this order:

1. Cache (if enabled and valid) - Instant response
2. NTP Servers (if enabled):
   • Google NTP (time.google.com)
   • Cloudflare NTP (time.cloudflare.com)
   • NTP Pool (pool.ntp.org)
   • Windows NTP (time.windows.com)
   • NIST NTP (time.nist.gov)
3. HTTP APIs (if enabled):
   • timeapi.io
   • worldtimeapi.org
   • worldclockapi.com

If one source fails, it automatically tries the next one. All sources return DateTime objects with IST values (not UTC with offset).

⚙️ Configuration Options

Option	Type	Default	Description
useNtp	bool	true	Enable NTP servers
useHttp	bool	true	Enable HTTP APIs
useCache	bool	true	Enable caching
cacheDurationSeconds	int	30	Cache validity duration
ntpTimeoutSeconds	int	5	NTP request timeout
httpTimeoutSeconds	int	10	HTTP request timeout
maxRetries	int	1	Retry attempts per source
ntpServers	List<String>	5 servers	Custom NTP servers
httpApis	List<String>	3 APIs	Custom HTTP APIs

❓ Troubleshooting

All sources failing?

try {
  DateTime time = await RealIstTime.getIstTime();
} on AllTimeSourcesFailedException catch (e) {
  print('All sources failed:');
  for (var error in e.errors) {
    print('${error.source}: ${error.message}');
  }
}

Network connectivity issues?

• Increase timeout values in configuration
• Check internet connectivity
• Verify firewall settings (NTP uses UDP port 123)

Need faster responses?

• Enable caching (enabled by default)
• Increase cache duration
• Use getIstTimeSync() for instant cached results

📱 Example App

Check out the example folder for a complete Flutter app demonstrating:

• Real-time IST clock display
• Source indicator
• Cache status
• Configuration options
• Testing all sources

Run the example:

cd example
flutter run

🤝 Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• NTP servers: Google, Cloudflare, NTP Pool, Microsoft, NIST
• Time APIs: timeapi.io, worldtimeapi.org, worldclockapi.com
• ntp package for NTP implementation

📞 Support

• 🐛 Report bugs
• 💡 Request features
• ⭐ Star on GitHub

---

Made with ❤️ for developers who need accurate IST time