📆 DateMapper

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

npm install datemapper

Using yarn

yarn add datemapper

---

🚀 Usage

1️⃣ Convert Date Formats

Convert between Unix-style (%Y-%m-%d) and Moment.js (YYYY-MM-DD) formats.

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.

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

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.

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.

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.

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!