@robertocemeri/date-utils

A lightweight JavaScript library for easy date and time operations with timezone support.

Installation

npm install @robertocemeri/date-utils
## Usage

### Basic Usage

```javascript
import { currentDate, currentYear, currentTime, currentDateTime } from '@robertocemeri/date-utils';

// Get current date
console.log(currentDate()); // "2024-01-15"
console.log(currentDate('DD/MM/YYYY')); // "15/01/2024"

// Get current year
console.log(currentYear()); // 2024

// Get current time
console.log(currentTime()); // "14:30:25"
console.log(currentTime('HH:mm')); // "14:30"

// Get current date and time
console.log(currentDateTime()); // "2024-01-15 14:30:25"
console.log(currentDateTime('DD/MM/YYYY HH:mm')); // "15/01/2024 14:30"

Advanced Usage with Timezone

import { createDateUtils } from '@robertocemeri/date-utils';

// Create instance with timezone
const dateUtils = createDateUtils('America/New_York');

console.log(dateUtils.currentDate()); // "2024-01-15"
console.log(dateUtils.currentTime()); // "09:30:25" (EST)
console.log(dateUtils.currentDateTime()); // "2024-01-15 09:30:25"

// Change timezone
dateUtils.setTimezone('UTC');
console.log(dateUtils.currentDateTime()); // "2024-01-15 14:30:25"

// Date manipulation
console.log(dateUtils.addDays(5).currentDate()); // Date 5 days from now
console.log(dateUtils.subtractDays(2).currentDate()); // Date 2 days ago

Class-based Usage

import { DateUtils } from '@robertocemeri/date-utils';

const utils = new DateUtils('Asia/Tokyo');
console.log(utils.currentYear()); // 2024
console.log(utils.currentDate('YYYY/MM/DD')); // "2024/01/16"
console.log(utils.currentTime()); // "23:30:25" (JST)

// Get available timezones
const timezones = DateUtils.getAvailableTimezones();
console.log('Available timezones:', timezones.slice(0, 5));

API Reference

Convenience Functions

• currentDate(format = 'YYYY-MM-DD') - Get current date
• currentYear() - Get current year
• currentTime(format = 'HH:mm:ss') - Get current time
• currentDateTime(format = 'YYYY-MM-DD HH:mm:ss') - Get current date and time
• timestamp() - Get current timestamp

DateUtils Class

• constructor(timezone = 'local')
• setTimezone(timezone) - Set timezone
• currentDate(format) - Get current date
• currentYear() - Get current year
• currentTime(format) - Get current time
• currentDateTime(format) - Get current date and time
• timestamp() - Get timestamp
• addDays(days) - Add days to current date
• subtractDays(days) - Subtract days from current date
• static getAvailableTimezones() - Get array of all available IANA timezones

Format Options

Date Formats

• YYYY - Four-digit year (e.g., 2024)
• YY - Two-digit year (e.g., 24)
• MM - Two-digit month (01-12)
• M - Month without leading zero (1-12)
• DD - Two-digit day (01-31)
• D - Day without leading zero (1-31)

Time Formats

• HH - Two-digit hour in 24-hour format (00-23)
• H - Hour without leading zero (0-23)
• mm - Two-digit minutes (00-59)
• m - Minutes without leading zero (0-59)
• ss - Two-digit seconds (00-59)
• s - Seconds without leading zero (0-59)
• SSS - Three-digit milliseconds (000-999)

Timezone Support

The library supports all IANA timezone names. Common examples:

• 'local' - System local time (default)
• 'utc' - UTC/GMT time
• 'America/New_York' - Eastern Time
• 'America/Los_Angeles' - Pacific Time
• 'Europe/London' - GMT/British Summer Time
• 'Europe/Paris' - Central European Time
• 'Asia/Tokyo' - Japan Standard Time
• 'Asia/Kolkata' - India Standard Time

Get all available timezones:

import { DateUtils } from '@robertocemeri/date-utils';
console.log(DateUtils.getAvailableTimezones());

Examples

Different Date Formats

import { currentDate } from '@robertocemeri/date-utils';

console.log(currentDate('YYYY-MM-DD'));        // "2024-01-15"
console.log(currentDate('DD/MM/YYYY'));        // "15/01/2024"
console.log(currentDate('MM/DD/YY'));          // "01/15/24"
console.log(currentDate('D/M/YYYY'));          // "15/1/2024"
console.log(currentDate('YYYY年MM月DD日'));    // "2024年01月15日"

Different Time Formats

import { currentTime } from '@robertocemeri/date-utils';

console.log(currentTime('HH:mm:ss'));          // "14:30:25"
console.log(currentTime('HH:mm'));             // "14:30"
console.log(currentTime('H:m'));               // "14:30"
console.log(currentTime('HH:mm:ss.SSS'));      // "14:30:25.123"

Working with Different Timezones

import { createDateUtils } from '@robertocemeri/date-utils';

// Compare different timezones
const ny = createDateUtils('America/New_York');
const london = createDateUtils('Europe/London');
const tokyo = createDateUtils('Asia/Tokyo');

console.log('New York:', ny.currentDateTime());
console.log('London:', london.currentDateTime());
console.log('Tokyo:', tokyo.currentDateTime());

Date Manipulation

import { createDateUtils } from '@robertocemeri/date-utils';

const utils = createDateUtils();

console.log('Today:', utils.currentDate());
console.log('Tomorrow:', utils.addDays(1).currentDate());
console.log('Last week:', utils.subtractDays(7).currentDate());
console.log('In 3 days:', utils.addDays(3).currentDate('DD/MM/YYYY'));

Error Handling

The library gracefully handles invalid timezones by falling back to local time:

import { createDateUtils } from '@robertocemeri/date-utils';

const utils = createDateUtils('Invalid/Timezone');
// Will console.warn: "Invalid timezone: Invalid/Timezone. Using local time."
// And continue with local timezone

Browser Support

This library works in all modern browsers that support:

• ES6 modules
• Intl.DateTimeFormat
• String.padStart()

For older browsers, consider using a polyfill for Intl.DateTimeFormat.

Node.js Support

Requires Node.js version 12.0.0 or higher.

License

MIT

Author

Roberto Cemeri [email protected]

Repository

https://github.com/robertocemeri/date-utils