⏱️ server-time-timer-yolabs

Enterprise-grade server-synchronized countdown timer Provides consistent countdowns across all devices, immune to client clock drift or manipulation.

🚀 Why Use server-time-timer-yolabs?

In real-world applications such as lotteries, online exams, flash sales, games, or Telegram Mini Apps:

• ❌ Client clocks can be wrong
• ❌ Users can manipulate device time
• ❌ Different platforms may display inconsistent countdowns

✅ server-time-timer-yolabs ensures all timers rely on the server clock, keeping countdowns synchronized everywhere.

✨ Key Features

• 🔒 Server time is the single source of truth
• 🌍 Same countdown on all devices and platforms
• 🧠 Automatic clock drift correction
• ⚡ Lightweight & framework-agnostic
• 🧩 Compatible with Next.js, NestJS, React, Vanilla JS, Telegram Mini Apps
• 🏢 Enterprise-ready architecture for robust applications

📦 Installation

npm install server-time-timer-yolabs

or

yarn add server-time-timer-yolabs

🧠 How It Works

1. Server sends current time (serverNow) and endTime.
2. Client calculates offset from server time.
3. Countdown runs locally using the offset.
4. Optional periodic re-sync keeps everything accurate.

➡️ Result: perfectly synchronized timers across all devices.

🔧 Basic Usage (JavaScript / TypeScript)

import { createServerTimer } from 'server-time-timer-yolabs';

const timer = createServerTimer({
  endTime: '2025-01-01T12:10:00Z'
});

timer.onTick(time => {
  console.log(`${time.minutes}m ${time.seconds}s`);
});

timer.start();

🕒 Returned Time Object

{
  totalMs: number,
  days: number,
  hours: number,
  minutes: number,
  seconds: number
}

Pick only the fields you need for your UI.

⚛️ React / Next.js Example

'use client';

import { useEffect, useState } from 'react';
import { createServerTimer } from 'server-time-timer-yolabs';

export default function Countdown({ endTime }: { endTime: string }) {
  const [time, setTime] = useState<any>(null);

  useEffect(() => {
    const timer = createServerTimer({ endTime });
    timer.onTick(setTime);
    timer.start();
    return () => timer.stop();
  }, [endTime]);

  if (!time) return null;

  return (
    <div>
      ⏳ {time.minutes}:{String(time.seconds).padStart(2, '0')}
    </div>
  );
}

🔁 Re-Sync with Server (Recommended)

setInterval(async () => {
  const res = await fetch('/api/server-time');
  const data = await res.json();
  timer.sync(data.now);
}, 30000); // every 30 seconds

• ✅ Prevents drift
• ✅ Enterprise best practice

⏰ Detect When Time Ends

timer.onTick(time => {
  if (time.totalMs <= 0) {
    console.log('Time is up!');
  }
});

🤖 Telegram Mini App / Framework-Agnostic Example

import { createServerTimer } from 'server-time-timer-yolabs';

const timer = createServerTimer({ endTime: gameEndTime });

timer.onTick(time => {
  document.getElementById('timer')!.innerText =
    `${time.minutes}:${time.seconds}`;
});

timer.start();

• ✔ Same countdown on all phones
• ✔ Safe against user manipulation

❌ Common Mistakes to Avoid

• Using Date.now() directly for countdowns
• Trusting client device time for business-critical logic
• Running important logic only in the UI
• Using setTimeout for rules that must be precise

✅ Best Practices

• Always use UTC time
• Keep business logic on the server
• Use the timer only for display purposes
• Re-sync for long-running sessions

🏢 Use Cases

• 🎟️ Lottery & raffle systems
• 🛒 Flash sales & limited offers
• 📝 Online exams & timed tests
• 🎮 Games & live events
• 📱 Telegram Mini Apps
• 🌐 Multi-platform enterprise systems

📜 License

YonasLabs ©