DateNTime - Simple JS Date Object Formatter

#javascript

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 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 and include it in your HTML if you prefer this approach.

Example usage:

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:

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 😊