TS Timer Countdown

A TypeScript-based countdown timer with event handling capabilities. This library provides a simple and efficient way to manage countdown timers in your TypeScript applications.

Features

• 🚀 Type-safe implementation with TypeScript
• 📡 Event-driven architecture
• 🔄 Multiple timer instances support
• 🧹 Memory management with proper cleanup
• ✅ 100% test coverage
• 🛡️ Comprehensive error handling
• 🔌 Automatic cleanup of event listeners
• 🏗️ Singleton pattern for timer management

Installation

npm install ts-timer-countdown

Usage

import { Timer, TimerEvent, Status } from 'ts-timer-countdown';

// Get a timer instance
const timer = Timer.getTimer('myTimer');

// Set up event listeners
const cleanup = timer.addEventListener(TimerEvent.onChangeTime, (status: Status) => {
  console.log('Time changed:', status.currentTime);
});

timer.addEventListener(TimerEvent.onFinishTime, (status: Status) => {
  console.log('Timer finished!');
});

// Set timer duration (in milliseconds)
timer.setStartTime(10000); // 10 seconds
timer.setFinishTime(0); // Stop at 0

// Start the timer
timer.start();

// Pause the timer
timer.pause();

// Stop the timer
timer.stop();

// Clean up event listener when no longer needed
cleanup();

API Documentation

Timer Class

A singleton class that manages multiple timer instances.

Static Methods

• getTimer(key: string): Countdown - Get a timer instance by key. Creates a new instance if one doesn't exist.
• getTimers(): Record<string, Countdown> - Get all timer instances.
• deleteTimer(key: string): void - Delete a timer instance and stop it.

Countdown Class

Properties

• startTime: 10000ms (10 seconds) - Default initial time
• delay: 1000ms (1 second) - Default update interval
• finishTime: 0ms - Default finish time
• isPaused: true - Initial pause state

Methods

• start(): void - Start the timer. Does nothing if timer is already running.
• stop(): void - Stop the timer and clear the interval.
• pause(): void - Pause the timer and trigger onPausedTime event.
• setStartTime(time: number): void - Set the initial time in milliseconds.
• setFinishTime(time: number): void - Set the finish time in milliseconds.
• addEventListener(eventName: TimerEvent, eventListener: EventListener): () => void - Add an event listener. Returns a cleanup function.
• removeEventListener(eventName: TimerEvent, eventListener: EventListener): void - Remove an event listener.

Events

The library provides three types of events:

• TimerEvent.onChangeTime - Fired every second when the time changes
• TimerEvent.onFinishTime - Fired when the timer reaches the finish time
• TimerEvent.onPausedTime - Fired when the timer is paused

Types

Status Interface

interface Status {
  isStarted: boolean;  // true if timer is running
  isPaused: boolean;   // true if timer is paused
  currentTime: string; // formatted as "MM:SS"
}

EventListener Type

type EventListener = (status: Status) => void;

TimerEvent Enum

enum TimerEvent {
  onChangeTime = 'onChangeTime',
  onFinishTime = 'onFinishTime',
  onPausedTime = 'onPausedTime'
}

Time Format

The timer displays time in "MM:SS" format:

• Minutes and seconds are separated by a colon
• Single-digit seconds are padded with a leading zero
• Example: "1:05" for 1 minute and 5 seconds

Development

Project Structure

src/
├── __tests__/     # Test files
├── types.ts       # TypeScript type definitions
├── index.ts       # Main entry point
├── Timer.ts       # Timer management class
└── Countdown.ts   # Countdown implementation

Running Tests

# Run tests once
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

Building

npm run build

Contributing

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

License

MIT © [Your Name]