datetimez

a small size date (and time) formatter library based on native javascript Date.

Installing

Using npm:

$ npm install datetimez

Using bower:

$ bower install datetimez

Using yarn:

$ yarn add datetimez

Using DateTimez

There is some ways to use date time:

Import default as a function

// CommonJS
const date = require('datetimez').default;

// ES6
import date from 'datetimez';

// Create date with current date as a value
const current = date();
current.year // current year

// Create date using numbers as parameters
const foo = date(2021, 5);
foo.year    // 2021
foo.month   // 5 default 0
foo.date    // 1 default 1
foo.hour    // 0 default 0
foo.minute    // 0 default 0
foo.second    // 0 default 0
foo.millisecond   // 0 default 0

// Create date using string as parameter
const bar = date('2021-11-01T03:24:00');
bar.year	// 2021
bar.month	// 11
bar.date	// 1
bar.hour	// 3
bar.minute	// 24

Import DateTimez

// CommonJS
const { DateTimez } = require('datetimez');

// ES6
import { DateTimez } from 'datetimez';

// Create date with current date as a value
const current = new DateTimez();
current.year // current year

// Create date using numbers as parameters
const foo = new DateTimez(2021, 5);
foo.year    // 2021
foo.month   // 5 default 0
foo.date    // 1 default 1
foo.hour    // 0 default 0
foo.minute    // 0 default 0
foo.second    // 0 default 0
foo.millisecond	  // 0 default 0

// Create date using string as parameter
const bar = new DateTimez('2021-11-01T03:24:00');
bar.year	// 2021
bar.month	// 11
bar.date	// 1
bar.hour	// 3
bar.minute	// 24

Since DateTimez is based on native Javascript Date, everything that work on Date is work on DateTimez too.

Attributes

const foo = date(2021, 2, 5, 12, 30, 10);

let's say there is a variable named foo like code above. So, below attributes will be available on foo.
Please note, attributes mark as readonly means it can't be modify directly. There are methods for modify each of them.

locale < String >

foo.locale // 'en' default en

year < Number > #readonly

foo.year // 2021

month < Number > #readonly

foo.month // 2

monthString < String > #readonly

foo.monthString // March

date < Number > #readonly

foo.date // 5

dayString < String > #readonly

foo.dayString // Friday

hour < Number > #readonly

foo.hour // 12

minute < Number > #readonly

foo.minute // 30

second < Number > #readonly

foo.second // 10

millisecond < Number > #readonly

foo.millisecond // 0

unix < Number > #readonly

foo.unix // 1614922210

lastDateOfMonth < Number > #readonly

foo.lastDateOfMonth // 31

Modify

Note: Every DateTimez instances are mutable. Calling any of the modify methods will modify instance's value.

setLocale(id: String): DateTimez

set locale value using id of a string with a BCP 47 language tag, or an array of such strings. For more info about locale read this.

addDate(n: Number): DateTimez

const date = require('datetimez');

date(2021, 1, 5).addDate(5).date // 10

// in case result of calculation is bigger than last date of current month, it will increase month
const foo = date(2021, 0, 31);
foo.addDate(5).date // 5
foo.month // 1

// just like case above, addDate will increase year if result of calculation is bigger than Dec 31st
const bar = date(2021, 11, 31);
bar.addDate(5).date // 5
bar.month // 0
bar.year // 2022

addMonth(n: Number): DateTimez

date(2021, 1, 5).addMonth(5).month // 6

// if result of calculation is bigger than 11, it will increase year
const foo = date(2021, 5, 10);
foo.addMonth(8).month // 1
foo.year // 2022

// if date is last date of previous month and not available after calculation. Date will be decreased to nearest available date.
const bar = date(2021, 0, 31);
bar.addMonth(1).month // 1
bar.date // 28

addYear(n: Number): DateTimez

date(2021, 1, 5).addYear(5).year // 2026

// if date is last date of previous year and not available after calculation. Date will be decreased to nearest available date.
const foo = date(2020, 1, 29);
foo.addYear(1).year // 2021
foo.date // 28

substractDate(n: Number): DateTimez

date(2021, 1, 20).subtractDate(5).date // 15

// in case result of calculation is less than 1, it will decrease month
const foo = date(2021, 1, 2);
foo.subtractDate(5).date // 28
foo.month // 0

// just like case above, subtractDate will modify year if result of calculation is less than Jan 31st
const bar = date(2021, 0, 2);
bar.subtractDate(5).date // 28
bar.month // 0
bar.year // 2020

subtractMonth(n: Number): DateTimez

date(2021, 7, 5).subtractMonth(5).month // 2

// if result of calculation is less than 0, it will decrease year
const foo = date(2021, 0, 10);
foo.subtractMonth(1).month // 11
foo.year // 2020

// if date on previous month not available after calculation. Date will be decreased to nearest available date.
const bar = date(2021, 2, 31);
bar.subtractMonth(1).month // 1
bar.date // 28

subtractYear(n: Number): DateTimez

date(2020, 1, 29).subtractYear(1).year // 2019

// if date on previous year not available after calculation. Date will be decreased to nearest available date.
const foo = date(2019, 1, 29);
foo.subtractYear(1).year // 2019
foo.date // 28

Validate

isBefore (d: Date): DateTimez

const year2019 = date(2019, 5, 20);
const year2021 = date(2021, 5, 20);

year2019.isBefore(year2021) // true
year2021.isBefore(year2019) // false
year2021.isBefore(year2021) // false

isAfter (d: Date): DateTimez

const year2019 = date(2019, 5, 20);
const year2021 = date(2021, 5, 20);

year2019.isAfter(year2021) // false
year2021.isAfter(year2019) // true
year2021.isAfter(year2021) // false

isEqual (d: Date): DateTimez

const foo = date(2021, 5, 20);
const bar = date(2021, 5, 20);
const fooBar = date(2021, 5, 20, 17);

foo.isEqual(bar) // true
bar.isEqual(fooBar) // false

isBetween (d1: Date, d2: Date): DateTimez

Check whether a DateTimez is between 2 other Dates or not. Return true if equal to first parameter or second parameter.

Units of measurements: Year, Month, Date, Hour, Minute, Second

const foo = date(2019, 5, 20);
const bar = new DateTimez(2019, 5, 27);
const fooBar = new Date(2019, 5, 30);

bar.isBetween(foo, fooBar) // true
foo.isBetween(bar, fooBar) // false

Format

format(format: String, locale?: String)

Takes a string of tokens and replaces them with their corresponding values. You can freely decide the separators.
Example:

const foo = date('December 11, 2021 03:24:00');

foo.format('ddd, MM-DD-YYYY') // Sat, 12-12-2021
foo.format('dddd, MM/DD/YYYY') // Saturday, 12/12/2021
foo.format('dddd DD MMMM YYYY hh:mm:ss', 'id') // Sabtu 12 Desember 2021 03:24:00

available tokens

Token	Value	Examples
ss	2-digit second	00, 01, ..., 59
mm	2-digit minute	00, 01, ..., 59
hh	2-digit hour	00, 01, ..., 23
ddd	Short Day	Sun, Mon, Tue, ...
dddd	Full Day	Sunday, Monday, ...
DD	2-digit date	01, 02, 03, 04, ...
MM	2-digit Month	01, 02, 03, ..., 12
MMM	Short Month	Jan, Feb, ..., Dec
MMMM	Full Month	January, ..., December
YY	2-digit Year	19, 20, 21, 22, ...
YYYY	4-digit Year	2019, 2020, 2021, ...

Playground

You can use Gitpod as an online IDE(which is free for Open Source) for running the examples online.

In Gitpod terminal:

cd datetimez
npm i
npm start

License

MIT