npm package: @meovang/datetime-utils
Description: DateTime utility functions for JavaScript
Author: vinhtran79@gmail.com
Latest version: 1.0.4

# @meovang/datetime-utils

A lightweight JavaScript utility library for working with dates and times. Features UTC to GMT+7 conversion and comprehensive date formatting similar to dayjs. Pure ES6 modules.

## Installation

```bash
npm install @meovang/datetime-utils
```

## Usage

```javascript
import { utcToGMT7DateTime, formatDateTime } from '@meovang/datetime-utils';

// Convert UTC date to GMT+7 timezone
const utcDate = new Date('2025-10-28T08:30:00.000Z'); // UTC time
const gmt7Date = utcToGMT7DateTime(utcDate);
console.log(gmt7Date); // 2025-10-28T15:30:00.000Z (7 hours added)

// Format date with various patterns
const now = new Date();
console.log(formatDateTime(now, 'YYYY-MM-DD')); // 2025-10-28
console.log(formatDateTime(now, 'DD/MM/YYYY HH:mm:ss')); // 28/10/2025 15:30:45
console.log(formatDateTime(now, 'MMMM D, YYYY')); // October 28, 2025
```

## API Reference

### `utcToGMT7DateTime(date)`

Converts UTC date to GMT+7 timezone by adding 7 hours.

- **Parameters:**
  - `date` (Date | string | number): The date to convert. Accepts Date object, date string, or timestamp
- **Returns:** Date object converted to GMT+7 timezone, or original input if invalid
- **Example:**
  ```javascript
  const utcDate = new Date('2025-10-28T08:30:00.000Z');
  const gmt7Date = utcToGMT7DateTime(utcDate);
  console.log(gmt7Date); // 2025-10-28T15:30:00.000Z
  
  // Also works with strings and timestamps
  const fromString = utcToGMT7DateTime('2025-10-28T08:30:00.000Z');
  const fromTimestamp = utcToGMT7DateTime(1729853400000);
  ```

### `formatDateTime(date, format)`

Format a date according to the provided format string using tokens similar to dayjs.

- **Parameters:**
  - `date` (Date | string | number): The date to format. Accepts Date object, date string, or timestamp
  - `format` (string): Format pattern using tokens
- **Returns:** Formatted date string, or original format string if date is invalid

#### Format Tokens

| Token | Description | Example |
|-------|-------------|---------|
| `YYYY` | Full year | 2025 |
| `YY` | Short year | 25 |
| `MMMM` | Full month name | January |
| `MMM` | Short month name | Jan |
| `MM` | Month with zero padding | 01 |
| `M` | Month without padding | 1 |
| `DD` | Day with zero padding | 01 |
| `D` | Day without padding | 1 |
| `dddd` | Full day name | Sunday |
| `ddd` | Short day name | Sun |
| `dd` | Minimal day name | Su |
| `d` | Day of week (0-6) | 0 |
| `HH` | Hours 24-hour with padding | 00-23 |
| `H` | Hours 24-hour without padding | 0-23 |
| `hh` | Hours 12-hour with padding | 01-12 |
| `h` | Hours 12-hour without padding | 1-12 |
| `mm` | Minutes with padding | 00-59 |
| `m` | Minutes without padding | 0-59 |
| `ss` | Seconds with padding | 00-59 |
| `s` | Seconds without padding | 0-59 |
| `SSS` | Milliseconds (3 digits) | 000-999 |
| `SS` | Milliseconds (2 digits) | 00-99 |
| `S` | Milliseconds (1 digit) | 0-9 |
| `A` | AM/PM uppercase | AM/PM |
| `a` | am/pm lowercase | am/pm |
| `X` | Unix timestamp (seconds) | 1729853400 |
| `x` | Unix timestamp (milliseconds) | 1729853400000 |

## Examples

```javascript
import { utcToGMT7DateTime, formatDateTime } from '@meovang/datetime-utils';

// UTC to GMT+7 conversion examples
const utcNow = new Date();
const gmt7Now = utcToGMT7DateTime(utcNow);
console.log('UTC:', utcNow.toISOString());
console.log('GMT+7:', gmt7Now.toISOString());

// Date formatting examples
const date = new Date('2025-10-28T15:30:45.123Z');

// Basic formats
console.log(formatDateTime(date, 'YYYY-MM-DD')); // 2025-10-28
console.log(formatDateTime(date, 'DD/MM/YYYY')); // 28/10/2025
console.log(formatDateTime(date, 'MM-DD-YY')); // 10-28-25

// Time formats
console.log(formatDateTime(date, 'HH:mm:ss')); // 15:30:45
console.log(formatDateTime(date, 'h:mm A')); // 3:30 PM
console.log(formatDateTime(date, 'HH:mm:ss.SSS')); // 15:30:45.123

// Full datetime formats
console.log(formatDateTime(date, 'YYYY-MM-DD HH:mm:ss')); // 2025-10-28 15:30:45
console.log(formatDateTime(date, 'MMMM D, YYYY h:mm A')); // October 28, 2025 3:30 PM
console.log(formatDateTime(date, 'dddd, MMMM D, YYYY')); // Monday, October 28, 2025

// Custom formats
console.log(formatDateTime(date, 'ddd MMM D')); // Mon Oct 28
console.log(formatDateTime(date, 'YYYY年MM月DD日')); // 2025年10月28日

// Works with different input types
console.log(formatDateTime('2025-10-28', 'YYYY-MM-DD')); // 2025-10-28
console.log(formatDateTime(1729853445123, 'YYYY-MM-DD HH:mm:ss')); // 2025-10-28 15:30:45
```

## License

MIT

## Author

Meovang

## Repository

This package is part of the @meovang monorepo.