🕒 useCountdown

A lightweight React hook to run a live countdown between two DateX instances.

Built with TypeScript and designed to integrate seamlessly into React apps using bdd-date-ext.

📦 Installation

npm install use-countdown-hook

This package depends on bdd-date-ext, which will be installed automatically.

🔧 Usage

import { useCountdown } from 'use-countdown-hook';
import { DateX } from 'bdd-date-ext';

const CountdownComponent = () => {
  const countdownEnd = new DateX().shift(5, "minute"); // 5 minutes from NOW
  
  const values = useCountdown({
    end: countdownEnd,
    onEnd: () => console.log("Time's up!"),
    timedActions: [
      {
        timestamp: countdownEnd.shift(-1, "minute"),
        action: () => console.log("Only 1 minute left!"),
      },
    ],
  });

  return (
    <div>
      <p>{values.days}d {values.hours}h {values.minutes}m {values.seconds}s</p>
    </div>
  );
};

🧠 Hook Signature

useCountdown(args: {
  start?: DateX; // default = new DateX()
  end: DateX;
  onStart?: (start: DateX) => void;
  onEnd?: (end: DateX) => void;
  timedActions?: { timestamp: DateX, action: (timestamp: DateX) => void }[];
}): {
  days: number;
  hours: number;
  minutes: number;
  seconds: number;
  milliseconds: number;
}

✅ Features

• ⏱ Starts automatically from start (or now)
• 📌 onStart and onEnd lifecycle callbacks
• 🔔 Supports timed actions (e.g., alert 1 min before end)
• 🧪 Fully typed (TypeScript ready)
• 💡 Based on bdd-date-ext for improved date manipulation

📄 License

MIT