@robertocemeri/date-utils/README.md

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

# @robertocemeri/date-utils

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

## Installation

```bash
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

```javascript
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

```javascript
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:

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

### Examples

Different Date Formats

```javascript
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

```javascript
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

```javascript
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

```javascript
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:

```javascript
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 <robertocemeri29@gmail.com>

## Repository

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