@toba/time

@toba/time is a minimalist JavaScript library for modern browsers with a largely Moment.js-compatible API. If you use Moment.js, you already know how to use @toba/time.

dateTime()
   .startOf('month')
   .add(1, 'day')
   .set('year', 2018)
   .format('YYYY-MM-DD HH:mm:ss');

• 🕒 Familiar Moment.js API & patterns
• 💪 Immutable
• 🔥 Chainable
• 📦 2kb mini library
• 👫 All browsers support

Installation

You have multiple ways of getting Day.js:

• Via NPM:

npm install dayjs --save

var dayjs = require('dayjs');
dateTime().format();

• Via CDN:

<!-- Latest compiled and minified JavaScript -->
<script src="https://unpkg.com/dayjs"></script>
<script>
  dateTime().format();
</script>

• Via download and self-hosting:

Just download the latest version of Day.js at https://unpkg.com/dayjs

Getting Started

Instead of modifying the native Date.prototype, Day.js creates a wrapper for the Date object, called DateTime object. DateTime object is immutable, that is to say, all API operation will return a new DateTime object.

API

API will always return a new DateTime object if not specified.

• Parse
  • Now
  • String
  • Unix Timestamp (milliseconds)
  • Date
  • Clone
  • Validation
• Get + Set
  • Year
  • Month
  • Date of Month
  • Hour
  • Minute
  • Second
  • Millisecond
  • Set
• Manipulate
  • Add
  • Subtract
  • Start of Time
  • End of Time
• Display
  • Format
  • Difference
  • Unix Timestamp (milliseconds)
  • Unix Timestamp (seconds)
  • Days in Month
  • As Javascript Date
  • As Array
  • As JSON
  • As ISO 8601 String
  • As Object
  • As String
• Query
  • Is Before
  • Is Same
  • Is After
  • Is Leap Year

Parse

Simply call dateTime() with one of the supported input types.

Now

To get the current date and time, just call dateTime() with no parameters.

dateTime();

String

Creating from a string matches ISO 8601 format.

dateTime(String);
dateTime('1995-12-25');

Unix Timestamp (milliseconds)

Passing an integer value representing the number of milliseconds since the Unix Epoch (Jan 1 1970 12AM UTC).

dateTime(Number);
dateTime(1318781876406);

Date

Passing a pre-existing native Javascript Date object.

dateTime(Date);
dateTime(new Date(2018, 8, 18));

Clone

All DateTime are immutable. If you want a copy of the object, just call .clone(). Calling dateTime() on a DateTime object will also clone it.

dateTime(Dayjs);
dateTime().clone();

Validation

• returns a Boolean

Check whether the DateTime object considers the date invalid.

dateTime().isValid();

Get + Set

Get and set date.

Year

• returns a Number

Get year.

dateTime().year;

Month

• returns a Number

Get month.

dateTime().month;

Date of Month

• returns a Number

Get day of the month.

dateTime().date;

Hour

• returns a Number

Get hour.

dateTime().hour;

Minute

• returns a Number

Get minute.

dateTime().minute;

Second

• returns a Number

Get second.

dateTime().second;

Millisecond

• returns a Number

Get millisecond.

dateTime().millisecond;

Set

Date setter. Units are case insensitive

dateTime().set((unit: String), (value: Int));
dateTime().set('month', 3); // April
dateTime().set('second', 30);

Manipulate

Once you have a DateTime object, you may want to manipulate it in some way like this:

dateTime()
   .startOf('month')
   .add(1, 'day')
   .subtract(1, 'year');

Add

Returns a new DateTime object by adding time.

dateTime().add((value: Number), (unit: String));
dateTime().add(7, 'day');

Subtract

Returns a new DateTime object by subtracting time. exactly the same as dateTime#add.

dateTime().subtract((value: Number), (unit: String));
dateTime().subtract(7, 'year');

Start of Time

Returns a new DateTime object by by setting it to the start of a unit of time.

dateTime().startOf((unit: String));
dateTime().startOf('year');

End of Time

Returns a new DateTime object by by setting it to the end of a unit of time.

dateTime().endOf((unit: String));
dateTime().endOf('month');

Display

Once parsing and manipulation are done, you need some way to display the DateTime object.

Format

• returns a String

Takes a string of tokens and replaces them with their corresponding date values.

dateTime().format(String);
dateTime().format(); // "2014-09-08T08:02:17-05:00" (ISO 8601, no fractional seconds)
dateTime().format('[YYYY] MM-DDTHH:mm:ssZ'); // "[2014] 09-08T08:02:17-05:00"

List of all available formats:

Difference

• returns a Number

Get the difference of two DateTime object in milliseconds or other unit.

dateTime().diff(Dayjs, unit);
dateTime().diff(dateTime(), 'years'); // 0

Unix Timestamp (milliseconds)

• returns a Number

Outputs the number of milliseconds since the Unix Epoch

dateTime().valueOf();

Unix Timestamp (seconds)

• returns a Number

Outputs a Unix timestamp (the number of seconds since the Unix Epoch).

dateTime().unix();

Days in Month

• returns a Number

Get the number of days in the current month.

dateTime().daysInMonth();

As JavaScript Date

• returns a JavaScript Date object

Get copy of the native Date object from DateTime object.

dateTime().toDate();

As Array

• returns a Array

Returns an array that mirrors the parameters from new Date().

dateTime().toArray(); //[2018, 8, 18, 00, 00, 00, 000];

As JSON

• returns a JSON String

Serializing an DateTime to JSON, will return an ISO8601 string.

dateTime().toJSON(); //"2018-08-08T00:00:00.000Z"

As ISO 8601 String

• returns a String

Formats a string to the ISO8601 standard.

dateTime().toISOString();

As Object

• returns a Object

Returns an object with year, month ... millisecond.

dateTime().toObject(); // { years:2018, months:8, date:18, hours:0, minutes:0, seconds:0, milliseconds:0}

As String

• returns a String

dateTime().toString();

Query

Is Before

• returns a Boolean

Check if a DateTime object is before another DateTime object.

dateTime().isBefore(DateTime);
dateTime().isBefore(dateTime()); // false

Is Same

• returns a Boolean

Check if a DateTime object is same as another DateTime object.

dateTime().isSame(DateTime);
dateTime().isSame(dateTime()); // true

Is After

• returns a Boolean

Check if a DateTime object is after another DateTime object.

dateTime().isAfter(DateTime);
dateTime().isAfter(dateTime()); // false

Is Leap Year

• returns a Boolean

Check if a year is a leap year.

dateTime().isLeapYear();
dateTime('2000-01-01').isLeapYear(); // true

License

MIT