📆 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!