datemapper/Readme.md

A lightweight date utility for format conversion, validation, and date manipulation.

# 📆 DateMapper

[![NPM Version](https://img.shields.io/npm/v/datemapper)](https://www.npmjs.com/package/datemapper)
[![Downloads](https://img.shields.io/npm/dt/datemapper)](https://www.npmjs.com/package/datemapper)
[![License](https://img.shields.io/npm/l/datemapper)](LICENSE)

**DateMapper** is a lightweight and efficient **date utility library** for handling **date formatting, conversion, validation, and manipulation** in **Node.js and browser environments**. 🚀

## 📌 Features
✅ Convert **Unix-style** date formats (`%Y-%m-%d`) ↔ **Moment.js** format (`YYYY-MM-DD`)
✅ **Validate** and **normalize** date ranges with **timezone support**
✅ **Increment and decrement** dates by day, month, hour, year, or week
✅ Generate **date ranges** between two dates
✅ Supports **custom date formats**

---

## 📦 Installation

### **Using npm**
```sh
npm install datemapper
```

### **Using yarn**
```sh
yarn add datemapper
```

---

## 🚀 Usage

### **1️⃣ Convert Date Formats**
Convert between **Unix-style (`%Y-%m-%d`)** and **Moment.js (`YYYY-MM-DD`)** formats.
```ts
import { convertDateFormat } from "datemapper";

console.log(convertDateFormat("%Y-%m-%d %H:%M:%S", true));
// Output: "YYYY-MM-DD HH:mm:ss"

console.log(convertDateFormat("YYYY-MM-DD HH:mm:ss", false));
// Output: "%Y-%m-%d %H:%M:%S"
```

---

### **2️⃣ Validate & Normalize Date Ranges**
Ensures **valid date format**, applies **timezone adjustments**, and **sets defaults**.
```ts
import { validateDate } from "datemapper";

const validRange = validateDate({ from: "2024-02-01", to: "2024-02-10" }, "America/New_York");
console.log(validRange);
// Output: { from: 2024-02-01T05:00:00.000Z, to: 2024-02-10T04:59:59.999Z }
```

🔴 **Handles invalid input**
```ts
try {
  validateDate({ from: "invalid-date", to: "2024-02-10" });
} catch (error) {
  console.error(error.message);
  // Output: Invalid starting date format. Expected format: YYYY-MM-DD.
}
```

---

### **3️⃣ Increment Date by Specific Units**
Add **days, months, hours, years, or weeks** to a given date.
```ts
import { incrementDate } from "datemapper";

const newDate = incrementDate(new Date("2025-02-24"), "day", "UTC");
console.log(newDate);
// Output: 2025-02-25T00:00:00Z
```

---

### **4️⃣ Decrement Date by Specific Units**
Subtract **days, months, hours, years, or weeks** from a given date.
```ts
import { decrementDate } from "datemapper";

const previousDate = decrementDate(new Date("2025-02-24"), "month", "UTC");
console.log(previousDate);
// Output: 2025-01-01T00:00:00Z
```

---

### **5️⃣ Generate Dates Between Two Ranges**
Generate an array of dates between **start and end dates** with a chosen **increment type**.
```ts
import { datesBetween } from "datemapper";

const dateList = datesBetween("2024-01-01", "2024-01-10", "day");
console.log(dateList);
/*
Output:
[
  "2024-01-01",
  "2024-01-02",
  "2024-01-03",
  "2024-01-04",
  "2024-01-05",
  "2024-01-06",
  "2024-01-07",
  "2024-01-08",
  "2024-01-09",
  "2024-01-10"
]
*/
```

---

## 🛠 API Reference

### **convertDateFormat(format: string, toNewFormat?: boolean): string**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `format` | `string` | - | The date format string to be converted. |
| `toNewFormat` | `boolean` | `true` | `true` (convert from Unix-style to Moment.js), `false` (reverse conversion). |

---

### **validateDate(range: { from?: string; to?: string }, timezone?: string, format?: string): { from: Date, to: Date }**
| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `from` | `string` | - | The start date (optional). |
| `to` | `string` | - | The end date (optional). |
| `timezone` | `string` | `"UTC"` | The timezone to apply. |
| `format` | `string` | `"YYYY-MM-DD"` | Expected date format. |

---

### **incrementDate(date: Date, incrementType: "day" | "month" | "hour" | "year" | "week", timezone: string): Date**
| Parameter | Type | Description |
|-----------|------|-------------|
| `date` | `Date` | The starting date to be incremented. |
| `incrementType` | `"day" \| "month" \| "hour" \| "year" \| "week"` | Type of increment to apply. |
| `timezone` | `string` | The timezone to use. |

---

### **decrementDate(date: Date, decrementType: "day" | "month" | "hour" | "year" | "week", timezone: string): Date**
| Parameter | Type | Description |
|-----------|------|-------------|
| `date` | `Date` | The starting date to be decremented. |
| `decrementType` | `"day" \| "month" \| "hour" \| "year" \| "week"` | Type of decrement to apply. |
| `timezone` | `string` | The timezone to use. |

---

## 📜 License
This project is licensed under the **MIT License**.

---

## 🛠 Contributing
Have an idea? Want to improve this package?
Feel free to **fork the repository**, submit issues, or contribute with **pull requests**! 🚀

---

### **📣 Support**
If you find this package helpful, give it a ⭐ on GitHub!