@megaorm/zone/README.md

This package is designed to convert UTC datetimes to a specific timezone and helps format and display them as you like.

# MegaORM Zone

This package is designed to convert UTC datetimes to a specific timezone and helps format and display them as you like. It also provides methods to extract date and time components and calculate time differences.

## Table of Contents

1. [Installation](#installation)
2. [Zone Class](#zone-class)
3. [Zone Methods](#zone-methods)
4. [Key Points to Remember](#key-points-to-remember)

## Installation

To install this package, run:

```bash
npm install @megaorm/zone
```

## Zone Class

The `Zone` class converts UTC datetimes to a specific timezone. It also provides methods to format and access date and time components in that timezone.

```js
// Import Zone
const { Zone } = require('@megaorm/zone');

// Create an instance
const zone = new Zone('2024-12-15 10:00:00', 'America/New_York');

// Converted datetime string in 'America/New_York' timezone
console.log(zone.datetime);

// The year in the specified timezone.
console.log(zone.year);

// The month (1-12) in the specified timezone.
console.log(zone.month);

// The day of the month (1-31) in the specified timezone.
console.log(zone.day);

// The hour (0-23) in the specified timezone.
console.log(zone.hour);

// The minute (0-59) in the specified timezone.
console.log(zone.minute);

// The second (0-59) in the specified timezone.
console.log(zone.second);
```

> The first argument must be a UTC datetime string in `YYYY-MM-DD hh:mm:ss` format. The second argument is the timezone identifier (e.g., `America/New_York`, `Europe/London`).

## Zone Methods

**`format(formatter)`**: Formats the datetime using a custom formatter function.

```js
// Custom formatter example
const formatted = zone.format((year, month, day, hour, minute, second) => {
  return `${month}-${day}-${year} ${hour}:${minute}:${second}`;
});
console.log(formatted); // Custom formatted datetime
```

> This method will return the default datetime string if the formatter is invalid.

**`toDateString()`**: Returns the date portion of the datetime in `YYYY-MM-DD` format.

```js
console.log(zone.toDateString()); // "2024-12-15"
```

**`toTimestring()`**: Returns the time portion of the datetime in `hh:mm:ss` format.

```js
console.log(zone.toTimestring()); // "10:00:00"
```

**`ampm()`**: Converts the time portion of the datetime to 12-hour AM/PM format.

```js
console.log(zone.ampm()); // "10:00 AM"
```

**`diff()`**: Calculates the time difference between the current time and the given datetime. It returns a human-readable description of the time difference, such as `5 minutes ago` or `2 days ago`.

```js
console.log(zone.diff()); // "Just now"
```

## **Key Points to Remember**

- **Constructor**: Converts a UTC datetime to the specified timezone.
- **format**: Formats the datetime using a custom formatter.
- **toDateString**: Returns the date in `YYYY-MM-DD` format.
- **toTimestring**: Returns the time in `hh:mm:ss` format.
- **ampm**: Returns the time in 12-hour AM/PM format.
- **diff**: Returns the time difference between the current time and the given datetime.
- **Use** `@megaorm/utc` to generate UTC datetimes, and use `@megaorm/zone` to convert them to any timezone of your choice. Both packages work together to handle timezone conversions seamlessly.