npm package: @nesn/commons-date-utils
Description: Time Converter is a TypeScript module designed to facilitate the conversion of timestamps between Unix format and JavaScript Date objects. The module provides utility functions for seamlessly converting Unix timestamps to Date objects, Date objects to Uni
Author: Lance Sims
Latest version: 1.0.4

# Time Converter

Time Converter is a TypeScript module designed to facilitate the conversion of timestamps between Unix format and JavaScript Date objects. The module provides utility functions for seamlessly converting Unix timestamps to Date objects, Date objects to Unix timestamps, and parsing date strings into Date objects.

## Functions

### `convertUnixTimestampToDate`

```typescript
/**
 * Converts a Unix timestamp to a JavaScript Date object.
 * @param timestamp The Unix timestamp (in seconds or milliseconds).
 * @returns A JavaScript Date object.
 */
export const convertUnixTimestampToDate = (timestamp: number): Date => {
    // Implementation ensures correct conversion from either seconds or milliseconds...
};
```

This function takes a Unix timestamp, whether in seconds or milliseconds, and returns the corresponding JavaScript Date object.

### `convertDateToUnixTimestamp`

```typescript
/**
 * Converts a JavaScript Date object to a Unix timestamp.
 * @param date The JavaScript Date object to convert.
 * @param inMilliseconds A boolean flag, defaulted to false, indicating whether the result should be in milliseconds.
 * @returns Unix timestamp in either seconds or milliseconds format.
 */
export const convertDateToUnixTimestamp = (date: Date, inMilliseconds: boolean = false): number => {
    // Implementation ensures conversion to either seconds or milliseconds...
};
```

This function takes a JavaScript Date object and converts it to a Unix timestamp. The `inMilliseconds` parameter allows you to specify whether the result should be in seconds or milliseconds.

### `convertStringToDate`

```typescript
/**
 * Attempts to convert a date string to a JavaScript Date object.
 * @param dateString The input string representing a date.
 * @returns A JavaScript Date object.
 * @throws Error if the input string is not a valid date.
 */
export const convertStringToDate = (dateString: string): Date => {
    // Implementation ensures parsing of the input string and throws an error for invalid dates...
};
```

This function attempts to convert a string representing a date to a JavaScript Date object. It throws an error if the input string is not a valid date.

## Usage

To use the Time Converter module in your TypeScript project, you can import the functions directly or include the module.

```typescript
import { convertUnixTimestampToDate, convertDateToUnixTimestamp, convertStringToDate } from 'path/to/time-converter';

const timestamp = 1637614823000;
const dateFromTimestamp = convertUnixTimestampToDate(timestamp);

const currentDate = new Date();
const timestampFromCurrentDate = convertDateToUnixTimestamp(currentDate);

const dateString = '2023-01-01T12:30:00.000Z';
const dateFromString = convertStringToDate(dateString);
```

Replace `'path/to/time-converter'` with the actual path to the `time-converter.ts` file in your project.

## Installation

To include the Time Converter module in your TypeScript project, you can install it via npm:

```bash
npm install --save path/to/time-converter
```

## License

This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.