Age Calculator

A simple and accurate age calculation utility for JavaScript/TypeScript that calculates the precise age between two dates, accounting for leap years and varying month lengths.

Features

• 🎯 Accurate calculations - Handles leap years and varying month lengths
• 📅 Flexible date handling - Works with any date range
• 🔢 Detailed breakdown - Returns years, months, weeks, and days
• 📦 TypeScript support - Full type definitions included
• 🪶 Lightweight - No dependencies
• ✅ Well tested - Comprehensive test suite

Installation

npm install age-calculator-utils

Usage

Basic Usage

import { calculateAge } from 'age-calculator-utils';

const age = calculateAge('2020-01-15', '2024-03-20');
console.log(age);
// Output: { years: 4, months: 2, weeks: 0, days: 5 }

JavaScript (CommonJS)

const { calculateAge } = require('age-calculator-utils');

const age = calculateAge('2020-01-15', '2024-03-20');
console.log(age);
// Output: { years: 4, months: 2, weeks: 0, days: 5 }

Real-world Examples

import { calculateAge } from 'age-calculator-utils';

// Calculate someone's age
const birthDate = '1990-05-15';
const today = new Date().toISOString().split('T')[0]; // Get today's date in YYYY-MM-DD format
const age = calculateAge(birthDate, today);
console.log(`Age: ${age.years} years, ${age.months} months, ${age.weeks} weeks, ${age.days} days`);

// Calculate project duration
const projectStart = '2023-01-01';
const projectEnd = '2023-12-31';
const duration = calculateAge(projectStart, projectEnd);
console.log(`Project duration: ${duration.years} years, ${duration.months} months`);

// Handle leap years correctly
const leapYearStart = '2024-02-29';
const leapYearEnd = '2025-02-28';
const leapAge = calculateAge(leapYearStart, leapYearEnd);
console.log(leapAge); // { years: 0, months: 11, weeks: 4, days: 2 }

API Reference

calculateAge(startDate, endDate)

Calculates the age between two dates.

Parameters:

• startDate (string): Start date in YYYY-MM-DD format
• endDate (string): End date in YYYY-MM-DD format

Returns:

• AgeResult: Object containing the calculated age

interface AgeResult {
  years: number;   // Full years
  months: number;  // Additional months (0-11)
  weeks: number;   // Additional weeks (0-4)
  days: number;    // Additional days (0-6)
}

getDaysInMonth(year, month)

Returns the number of days in a specific month, accounting for leap years.

Parameters:

• year (number): The year
• month (number): The month (1-12)

Returns:

• number: Number of days in the month

getDaysInMonth(2024, 2); // 29 (leap year)
getDaysInMonth(2023, 2); // 28 (non-leap year)
getDaysInMonth(2024, 4); // 30

isLeapYear(year)

Checks if a year is a leap year.

Parameters:

• year (number): The year to check

Returns:

• boolean: True if leap year, false otherwise

isLeapYear(2024); // true
isLeapYear(2023); // false
isLeapYear(2000); // true
isLeapYear(1900); // false

Edge Cases Handled

This library correctly handles various edge cases:

• Leap years: February 29th is properly handled
• Month boundaries: Crossing month boundaries with different day counts
• Year boundaries: December to January transitions
• Short months: February, April, June, September, November
• Same dates: Returns zero for all fields when dates are identical

Examples

// Leap year handling
calculateAge('2024-02-29', '2025-02-28');
// { years: 0, months: 11, weeks: 4, days: 2 }

// Month boundary
calculateAge('2024-01-31', '2024-02-29');
// { years: 0, months: 0, weeks: 4, days: 1 }

// Year boundary
calculateAge('2023-12-15', '2024-01-20');
// { years: 0, months: 1, weeks: 0, days: 5 }

// Same date
calculateAge('2024-01-01', '2024-01-01');
// { years: 0, months: 0, weeks: 0, days: 0 }

TypeScript Support

This package is written in TypeScript and includes full type definitions. All functions and interfaces are properly typed:

import { calculateAge, getDaysInMonth, isLeapYear, AgeResult } from 'age-calculator-utils';

const age: AgeResult = calculateAge('2020-01-01', '2024-01-01');
const days: number = getDaysInMonth(2024, 2);
const isLeap: boolean = isLeapYear(2024);

Testing

The library includes comprehensive tests covering:

• Basic age calculations
• Leap year scenarios
• Month boundary cases
• Year boundary cases
• Edge cases and real-world examples

Run tests:

npm test

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

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

Author

Stanislau Stankevich

• GitHub: @nkvch
• Package: @nkvch/age-calculator