@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

npm install @meovang/datetime-utils

Usage

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:

  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

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.