Time Sculptor

Time Sculptor is a lightweight JavaScript utility library that simplifies handling and converting UTC and local date-times. This package provides essential functions to work with dates and times, including conversions between 12-hour and 24-hour formats, offset adjustments, and retrieval of friendly date information. Ideal for projects that need reliable, timezone-aware date operations without the need for heavy dependencies.

Features

12-Hour Format Conversion: Convert 24-hour time to a 12-hour format with AM/PM notation. Time Offset Conversion: Adjust time with specific hour offsets. Local Date-Time Conversion: Easily convert UTC dates and times to local date-times using offsets. Timestamp Generation: Create UTC timestamps based on specific date and time inputs. UTC Conversion: Convert dates to UTC format and retrieve timezone offsets. Date Difference Calculation: Calculate the difference in days between two dates. Friendly Date Information: Get month names and day names for given dates.

Installation

Install Time Sculptor with npm:

npm install time-sculptor
Usage
Import the functions from the package:

const {
  convertTo12HourFormat,
  convertTimeWithOffset,
  userLocalDateTime,
  timeStamp,
   differenceInDays,
  getMonthName,
  getDayOfWeek,
} = require("time-sculptor");

convertTo12HourFormat(time);
// Converts a 24-hour time string (e.g., "14:30") to a 12-hour format with AM/PM.

const formattedTime = convertTo12HourFormat("14:30"); // "2:30 PM"
convertTimeWithOffset(time, offsetHours);
// Adjusts a given time string by an hour offset and returns it in UTC format.

const adjustedTime = convertTimeWithOffset("14:30", 6); // Adjusted time with a 6-hour offset
userLocalDateTime(givenDate, time, offset);
// Generates a local date-time with a specified UTC offset.

const localDateTime = userLocalDateTime("2024-11-07T14:00:00.000Z", "12:00", 6);
timeStamp(givenDate, time);
// Creates a UTC timestamp for a specified date and time.

differenceInDays(date1, date2);
// Calculates the number of days between two dates.

const daysBetween = differenceInDays("2024-11-01", "2024-11-07"); // 6
getMonthName(date);
// Returns the month name for a given date.

const month = getMonthName("2024-11-07"); // "November"
getDayOfWeek(date)
Returns the day of the week for a given date.

const day = getDayOfWeek("2024-11-07"); // "Thursday"

License
MIT License.

Contributing
Contributions are welcome! Feel free to submit a pull request or open an issue.