@mangcoding/day-calculator/README.md

Simple Project to calculate day

# @mangcoding/day-calculator

[![npm version](https://img.shields.io/npm/v/@mangcoding/day-calculator.svg)](https://www.npmjs.com/package/@mangcoding/day-calculator)
[![npm downloads](https://img.shields.io/npm/dm/@mangcoding/day-calculator.svg)](https://www.npmjs.com/package/@mangcoding/day-calculator)
[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)

A simple and powerful JavaScript library for calculating date differences in various units (years, months, days, hours, minutes, seconds), getting day names in different locales, and calculating future/past dates. Built with Moment.js for reliable date handling.

## 🚀 Installation

```bash
npm install @mangcoding/day-calculator
```

## ✨ Features

- 📅 **Date Difference Calculations** - Calculate differences in years, months, days, hours, minutes, and seconds
- 🌍 **Multi-language Support** - Get day names in different locales (English, Indonesian, Spanish, etc.)
- ⏰ **Future/Past Date Calculations** - Easily calculate future and past dates
- 🎯 **Age Calculation** - Get detailed age breakdown including years, months, and days
- 🔧 **Flexible Date Formats** - Support for various date input formats
- 📦 **Lightweight** - Built with Moment.js for reliable date handling

## 📖 Usage

```javascript
const dayCalculator = require('@mangcoding/day-calculator');

// Calculate comprehensive difference
const result = dayCalculator.difference('2023-01-01', '2024-12-31');
console.log(result);
// Output: { year: 1, month: 11, day: 364, hour: 8736, minute: 524160, second: 31449600 }

// Calculate specific differences
console.log(dayCalculator.differenceInYears('2023-01-01', '2024-12-31')); // 1
console.log(dayCalculator.differenceInMonths('2023-01-01', '2024-12-31')); // 23
console.log(dayCalculator.differenceInDays('2023-01-01', '2024-12-31')); // 729
console.log(dayCalculator.differenceInHours('2023-01-01', '2024-12-31')); // 17520
console.log(dayCalculator.differenceInMinutes('2023-01-01', '2024-12-31')); // 1051200
console.log(dayCalculator.differenceInSeconds('2023-01-01', '2024-12-31')); // 63072000

// Calculate age with detailed breakdown
const age = dayCalculator.yourAgeIncludingMonthsAndDays('1989-09-13', new Date());
console.log(age); // "34 years 3 months 15 days"

// Get day name in different locales
console.log(dayCalculator.daysName('1989-09-13', 'en')); // "Wednesday"
console.log(dayCalculator.daysName('1989-09-13', 'id')); // "Rabu"

// Calculate future and past dates
console.log(dayCalculator.futureDate(new Date(), 10)); // "2024-01-15" (10 days from now)
console.log(dayCalculator.pastDate(new Date(), 30)); // "2023-12-16" (30 days ago)
```

## 📚 API Reference

### `difference(startDate, endDate)`

Returns a comprehensive object containing the difference in all time units.

**Parameters:**
- `startDate` (string|Date): The start date
- `endDate` (string|Date): The end date

**Returns:** Object with properties: `year`, `month`, `day`, `hour`, `minute`, `second`

### `differenceInYears(startDate, endDate)`

Calculates the difference in years.

**Parameters:**
- `startDate` (string|Date): The start date
- `endDate` (string|Date): The end date

**Returns:** Number of years

### `differenceInMonths(startDate, endDate)`

Calculates the difference in months.

**Parameters:**
- `startDate` (string|Date): The start date
- `endDate` (string|Date): The end date

**Returns:** Number of months

### `differenceInDays(startDate, endDate)`

Calculates the difference in days.

**Parameters:**
- `startDate` (string|Date): The start date
- `endDate` (string|Date): The end date

**Returns:** Number of days

### `differenceInHours(startDate, endDate)`

Calculates the difference in hours.

**Parameters:**
- `startDate` (string|Date): The start date
- `endDate` (string|Date): The end date

**Returns:** Number of hours

### `differenceInMinutes(startDate, endDate)`

Calculates the difference in minutes.

**Parameters:**
- `startDate` (string|Date): The start date
- `endDate` (string|Date): The end date

**Returns:** Number of minutes

### `differenceInSeconds(startDate, endDate)`

Calculates the difference in seconds.

**Parameters:**
- `startDate` (string|Date): The start date
- `endDate` (string|Date): The end date

**Returns:** Number of seconds

### `yourAgeIncludingMonthsAndDays(startDate, endDate)`

Calculates age with detailed breakdown including years, months, and days.

**Parameters:**
- `startDate` (string|Date): The birth date
- `endDate` (string|Date): The current date

**Returns:** String in format "X years Y months Z days"

### `daysName(date, locale)`

Gets the day name of the week for a given date in the specified locale.

**Parameters:**
- `date` (string|Date): The date to get the day name for
- `locale` (string): The locale code (e.g., 'en', 'id', 'es'). Defaults to 'en'

**Returns:** String with the day name in the specified locale

### `futureDate(startDate, days, format)`

Calculates a future date by adding the specified number of days.

**Parameters:**
- `startDate` (string|Date): The starting date
- `days` (number): Number of days to add
- `format` (string): Date format. Defaults to 'YYYY-MM-DD'

**Returns:** String with the future date in the specified format

### `pastDate(startDate, days, format)`

Calculates a past date by subtracting the specified number of days.

**Parameters:**
- `startDate` (string|Date): The starting date
- `days` (number): Number of days to subtract
- `format` (string): Date format. Defaults to 'YYYY-MM-DD'

**Returns:** String with the past date in the specified format

## 🎯 Examples

### Basic Usage

```javascript
const dayCalculator = require('@mangcoding/day-calculator');

// Calculate time since a specific date
const startDate = '2020-01-01';
const endDate = new Date();

const timeDiff = dayCalculator.difference(startDate, endDate);
console.log(`Time passed: ${timeDiff.year} years, ${timeDiff.month} months, ${timeDiff.day} days`);
```

### Age Calculation

```javascript
const dayCalculator = require('@mangcoding/day-calculator');

// Calculate someone's age
const birthDate = '1990-05-15';
const currentDate = new Date();

const age = dayCalculator.yourAgeIncludingMonthsAndDays(birthDate, currentDate);
console.log(`Age: ${age}`);
```

### Project Duration

```javascript
const dayCalculator = require('@mangcoding/day-calculator');

// Calculate project duration
const projectStart = '2023-06-01';
const projectEnd = '2024-03-15';

const duration = dayCalculator.differenceInDays(projectStart, projectEnd);
console.log(`Project duration: ${duration} days`);
```

### Day Name and Locale Support

```javascript
const dayCalculator = require('@mangcoding/day-calculator');

// Get day names in different languages
const date = '2024-01-01';
console.log(dayCalculator.daysName(date, 'en')); // "Monday"
console.log(dayCalculator.daysName(date, 'id')); // "Senin"
console.log(dayCalculator.daysName(date, 'es')); // "lunes"
```

### Future and Past Date Calculations

```javascript
const dayCalculator = require('@mangcoding/day-calculator');

// Calculate future dates
const today = new Date();
const nextWeek = dayCalculator.futureDate(today, 7);
const nextMonth = dayCalculator.futureDate(today, 30);
console.log(`Next week: ${nextWeek}`);
console.log(`Next month: ${nextMonth}`);

// Calculate past dates
const lastWeek = dayCalculator.pastDate(today, 7);
const lastMonth = dayCalculator.pastDate(today, 30);
console.log(`Last week: ${lastWeek}`);
console.log(`Last month: ${lastMonth}`);

// Custom format
const customFuture = dayCalculator.futureDate(today, 10, 'DD/MM/YYYY');
console.log(`Custom format: ${customFuture}`);
```

## 🛠️ Development

### Running Tests

```bash
npm test
```

### Dependencies

- [Moment.js](https://momentjs.com/) - For reliable date manipulation

## 📄 License

ISC License - see [LICENSE](LICENSE) file for details.

## 🤝 Contributing

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

## 📞 Support

If you have any questions or issues, please:

1. Check the [Issues](https://github.com/mangcoding/day-calculator/issues) page
2. Create a new issue if your problem isn't already reported
3. Contact the maintainer

## 📋 Changelog

### Version 1.0.2
- ✨ Added `daysName()` function for getting day names in different locales
- ✨ Added `futureDate()` function for calculating future dates
- ✨ Added `pastDate()` function for calculating past dates
- 🔧 Enhanced main module exports to include new functions
- 📚 Updated documentation with new API reference and examples

### Version 1.0.0
- 🎉 Initial release
- 📅 Date difference calculations in multiple units
- 🎯 Age calculation with detailed breakdown
- 🌍 Multi-language day name support

## 🔗 Links

- [NPM Package](https://www.npmjs.com/package/@mangcoding/day-calculator)
- [GitHub Repository](https://github.com/mangcoding/day-calculator)
- [Report Bug](https://github.com/mangcoding/day-calculator/issues)

---

Made with ❤️ by [Nugraha](https://github.com/mangcoding)