DateNTime - Simple JS Date Object Formatter
Tags: javascript
Published: 2020-10-04 13:06:59

Long time ago when I first started writing code, first language I learned was PHP and after moving to Node.js and JavaScript in general, I find working with JavaScript Date objects frustrating. Formatting with PHP `date()` was so easy, I decided to write something similar for JavaScript and I'm sharing it with you in my first ever post on dev.to 🥳

[DateNTime](https://github.com/n-ts/DateNTime) is tiny (657 bytes minified and gzipped), works in every JavaScript environment including (but not limited to) Node.js, Cloudflare Workers and every modern / legacy browsers (tested in IE9 and up).

You can install it using `npm install datentime` and `require('datentime')` it or just download `datentime.min.js` file from [GitHub](https://github.com/n-ts/DateNTime) and include it in your HTML if you prefer this approach.

Example usage:
```javascript
const DateNTime = require('datentime');

console.log(
  DateNTime('Current date and time: !MM/!DD/!YYYY - !HH:!mm !TD')
); // Current date and time: 04/10/2020 - 03:32 PM

console.log(
  DateNTime('!NW, !NM !DD, !YYYY', new Date('2017-04-25'))
); // Tuesday, April 25, 2017
```


DateNTime accepts following parameters:

| Parameter | Description |
|---|---|
| `_format(String)` | (Optional) String with formatting. Default: `!YYYY-!MM-!DD !hh:!mm:!ss.!SSS` |
| `_date(Date)` | (Optional) Date object. Default: Date object of current date `new Date()` |
| `_months(Array[12])` | (Optional) Array of alternative/localized month names. Default: `["January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"]` |
| `_wdays(Array[7])` | (Optional) Array of alternative/localized names for days of the week. Default: `["Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"]` |

All parameters are optional, you can just run `DateNTime()` without any parameters to return current date and time in default `!YYYY-!MM-!DD !hh:!mm:!ss.!SSS` format. Additionally, order of parameters isn't important and you can add parameters in any order you like (script will automatically detect parameters based on type and length).

If you want to localize months and week days for your local language, you can easily do it using following (French) example:

```javascript
const months_FR = [
  'janvier',
  'février',
  'mars',
  'avril',
  'mai',
  'juin',
  'juillet',
  'août',
  'septembre',
  'octobre',
  'novembre',
  'décembre',
];

const wdays_FR = [
  'Dimanche',
  'Lundi',
  'Mardi',
  'Mercredi',
  'Jeudi',
  'Vendredi',
  'Samedi',
];

console.log(
  DateNTime('!NW, !NM !DD, !YYYY', months_FR, wdays_FR)
); // Dimanche, octobre 04, 2020
```

Format character(s) always start with `!` symbol and full list of supported format character(s) is listed below:

| Characters | Description |
|---|---|
| `!UTM` | Get Unix Time in milliseconds |
| `!UTS` | Get Unix Time in seconds |
| `!YYYY` | Get full year |
| `!YY` | Get last 2 digits of year |
| `!MM` | Get month with leading zero 01-12 |
| `!M` | Get month 1-12 |
| `!NM` | Get name of the month January-December |
| `!DD` | Get date with leading zero 01-31 |
| `!D` | Get date 1-31 |
| `!W` | Get day of the week 0-6 (where 0 is Sunday and 6 is Saturday) |
| `!NW` | Get name of the day of the week Sunday-Saturday |
| `!HH` | Get hour (12-hour format) with leading zero 12-01-11 |
| `!H` | Get hour (12-hour format) 12-1-11 |
| `!hh` | Get hour with leading zero 00-23 |
| `!h` | Get hour 0-23 |
| `!mm` | Get minutes with leading zero 00-59 |
| `!m` | Get minutes 0-59 |
| `!ss` | Get seconds with leading zero 00-59 |
| `!s` | Get seconds 0-59 |
| `!SSS` | Get milliseconds with leading zeros 000-999 |
| `!S` | Get milliseconds 0-999 |
| `!TD` | Get time of the day for 12-hour format AM/PM |


Please let me know in the comments if you find it useful, if you end up using it in your project or even if something is not clear and need help :)

Disclaimer: Yes, I'm aware that `moment.js` exists and it's awesome, but it's also huge (~29 times larger than DateNTime) and not everyone needs all functionality of `moment.js` to justify its size 😊