epochtoolkit

epochToolkit is a comprehensive toolkit for managing dates, times, and epoch conversions in JavaScript. It provides a suite of utilities to convert between date strings and epoch times, format dates and times, validate date strings, and check for leap years. With this toolkit, you can simplify date and time management in your JavaScript projects.

Table of Contents

• Installation
• Quick Start
• Features
• Methods Overview
• Usage

Installation

This is a Node.js module available through the npm registry.

Before installing, download and install Node.js. Node.js 0.10 or higher is required.

If this is a brand new project, make sure to create a package.json first with the npm init command.

Installation is done using the npm install command:

To install saltyhash, use npm:

$ npm install epochtoolkit

Quick Start

const epochToolkit = require('epochtoolkit');

// Convert a date string to epoch time
const epoch = epochToolkit.dateStringToEpochObject('2024-11-01T12:44:33');
console.log("Epoch from Date String:", epoch);

// Check if 2024 is a leap year
console.log("Is 2024 a Leap Year:", epochToolkit.isLeapYear(2024));

Features

• Date Conversion: Convert dates to and from epoch formats (milliseconds and seconds) and ISO date formats.
• Date Formatting: Display dates in a readable format (YYYY-MM-DD and HH:MM:SS).
• Validation: Check for valid timestamps and ISO date strings.
• Leap Year Check: Determine if a specified year is a leap year.
• Modular & User-Friendly: Easy to use, plug-and-play design, adaptable to any project.

Methods Overview

The Epoch Toolkit provides various functions to manipulate and convert dates and timestamps in JavaScript. Below is a comprehensive overview of its methods, including descriptions and practical examples.

| Method | Description | Example | |--------------------------------------------|----------------------------------------------------------------------------------------------|----------------------------------------------------------| | dateStringToEpochObject(dateString) | Converts a date string in ISO 8601 format to an epoch object containing milliseconds and seconds. | epochObject = epochToolkit.dateStringToEpochObject('2024-11-01T12:44:33'); Output: { milliseconds: 1730445273000, seconds: 1730445273 } | | millisecondsToDate(milliseconds) | Converts a timestamp in milliseconds to a formatted date string. | formattedDateFromMilliseconds = epochToolkit.millisecondsToDate(1730445273627); Output: "11/1/2024, 12:44:33 PM" | | secondsToDate(seconds) | Converts a timestamp in seconds to a formatted date string. | formattedDateFromSeconds = epochToolkit.secondsToDate(1730445273); Output: "11/1/2024, 12:44:33 PM" | | isoToMilliseconds(isoDateString) | Converts an ISO date string to a timestamp in milliseconds. | millisecondsFromISO = epochToolkit.isoToMilliseconds('2024-11-01T12:44:33Z'); Output: 1730445273000 | | formatDate(date) | Formats a given date object into a string representation of the date. | formattedDate = epochToolkit.formatDate(new Date()); Output: "2024-11-01" | | formatTime(date) | Formats a given date object into a string representation of the time. | formattedTime = epochToolkit.formatTime(new Date()); Output: "12:44:33" | | isValidTimestamp(timestamp) | Validates whether the given timestamp is a valid epoch timestamp. | isValidTimestamp = epochToolkit.isValidTimestamp(1730445273000); Output: true | | isValidISODateString(isoDateString) | Checks if the provided string is a valid ISO date string. | isValidISODate = epochToolkit.isValidISODateString('2024-11-01T12:44:33Z'); Output: true | | isLeapYear(year) | Determines whether the specified year is a leap year. | isLeap = epochToolkit.isLeapYear(2024); Output: true isLeap1900 = epochToolkit.isLeapYear(1900); Output: false isLeap2000 = epochToolkit.isLeapYear(2000); Output: true |

Usage

To use the Epoch Toolkit, ensure you have it installed in your project. You can require it in your JavaScript files and utilize the above methods for various date and time manipulations.

Conversion Functions

1. dateStringToEpochObject(dateString)

Converts a date string (e.g., YYYY-MM-DDTHH:mm:ss) into an object containing both the epoch time in milliseconds and in seconds. This is useful for converting human-readable date formats into epoch time, which is commonly used in databases and system logs.

const epochObject = epochToolkit.dateStringToEpochObject('2024-11-01T12:44:33');
console.log("Epoch Object from Date String:", epochObject); 
// Output: { milliseconds: 1730445273000, seconds: 1730445273 }

2. millisecondsToDate(milliseconds)

Converts an epoch time in milliseconds to a formatted date string. Use this when you need to display epoch time as a readable date.

const formattedDateFromMilliseconds = epochToolkit.millisecondsToDate(1730445273627);
console.log("Formatted Date from Milliseconds:", formattedDateFromMilliseconds); 
// Output: "11/1/2024, 12:44:33 PM"

3. secondsToDate(seconds)

Converts epoch time in seconds to a formatted date string. This is helpful when dealing with epoch time in seconds instead of milliseconds.

const formattedDateFromSeconds = epochToolkit.secondsToDate(1730445273);
console.log("Formatted Date from Seconds:", formattedDateFromSeconds); 
// Output: "11/1/2024, 12:44:33 PM"

4. isoToMilliseconds(isoString)

Converts an ISO date string (e.g., 2024-11-01T12:44:33Z) to epoch time in milliseconds. This is useful when working with ISO date formats and needing to convert them to epoch time.

const millisecondsFromISO = epochToolkit.isoToMilliseconds('2024-11-01T12:44:33Z');
console.log("Milliseconds from ISO Date String:", millisecondsFromISO); 
// Output: 1730445273000

Formatting Functions

1. formatDate(date)

Formats a Date object as a YYYY-MM-DD string. Use this to display dates in a standard format.

const formattedDate = epochToolkit.formatDate(new Date());
console.log("Formatted Date:", formattedDate); 
// Output: e.g., "2024-11-01"

2. formatTime(date)

Formats a Date object as a HH:MM:SS string. Useful when you need to display the time portion of a date.

const formattedTime = epochToolkit.formatTime(new Date());
console.log("Formatted Time:", formattedTime); 
// Output: e.g., "12:44:33"

Validation Functions

1. isValidTimestamp(timestamp)

Checks if a given number represents a valid epoch timestamp. Useful to verify that a value is a valid timestamp before further processing.

const isValidTimestamp = epochToolkit.isValidTimestamp(1730445273000);
console.log("Is Valid Timestamp:", isValidTimestamp); 
// Output: true

2. isValidISODateString(isoString)

Verifies if a string follows a valid ISO date format. Helpful for validating input from users or external sources.

const isValidISODate = epochToolkit.isValidISODateString('2024-11-01T12:44:33Z');
console.log("Is Valid ISO Date String:", isValidISODate); 
// Output: true

Leap Year Check

isLeapYear(year) Determines if a specified year is a leap year. This is useful for applications with calendar functionality.

console.log("Is 2024 a Leap Year:", epochToolkit.isLeapYear(2024)); 
// Output: true

console.log("Is 1900 a Leap Year:", epochToolkit.isLeapYear(1900)); 
// Output: false

console.log("Is 2000 a Leap Year:", epochToolkit.isLeapYear(2000)); 
// Output: true

Error Handliing

To help manage errors, epochToolkit includes built-in validation functions:

• Invalid ISO Date Strings: The isValidISODateString function will return false for any improperly formatted strings, ensuring that only valid ISO date formats are processed.

• Invalid Timestamps: The isValidTimestamp function checks that the numbers provided as timestamps are valid, returning false for any invalid inputs.

const validDate = epochToolkit.isValidISODateString('invalid-date');
console.log(validDate); 
// Output: false

Contributing

If you're interested in improving or adding features to epochToolkit, we are always happy to welcome contributions!

Contact

For questions, suggestions, or support, please reach out to [Your Contact Email] or open an issue on GitHub.