/dayjs

⏰Fast 2KB immutable date library alternative to Moment.js with the same modern API

Primary LanguageJavaScriptMIT LicenseMIT

English | 简体中文

Day.js

Fast 2kB alternative to Moment.js with the same modern API


Gzip Size NPM Version Build Status Codecov License

Day.js 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 Day.js.

dayjs().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');
    dayjs().format();
  • Via CDN:
    <!-- Latest compiled and minified JavaScript -->
    <script src="https://unpkg.com/dayjs"></script>
    <script>
      dayjs().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 Dayjs object. Dayjs object is immutable, that is to say, all api operation will return a new Dayjs object.

API

Api will always return a new Dayjs object if not specified.


Parse

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

Now

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

dayjs();

String

Creating from a string matches ISO 8601 format.

dayjs(String);
dayjs("1995-12-25");

Unix Timestamp (milliseconds)

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

dayjs(Number);
dayjs(1318781876406);

Date

Passing a pre-existing native Javascript Date object.

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

Clone

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

dayjs(Dayjs);
dayjs().clone();

Validation

  • return Boolean

Check whether the Dayjs object considers the date invalid.

dayjs().isValid();

Get + Set

Get and set date.

Year

  • return Number

Get year.

dayjs().year();

Month

  • return Number

Get month.

dayjs().month();

Date of Month

  • return Number

Get day of the month.

dayjs().date();

Hour

  • return Number

Get hour.

dayjs().hour();

Minute

  • return Number

Get minute.

dayjs().minute();

Second

  • return Number

Get second.

dayjs().second();

Millisecond

  • return Number

Get millisecond.

dayjs().millisecond();

Set

Date setter. Units are case insensitive

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

Manipulate

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

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

Add

Return a new Dayjs object by adding time.

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

Subtract

Return a new Dayjs object by subtracting time. exactly the same as dayjs#add.

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

Start of Time

Return a new Dayjs object by by setting it to the start of a unit of time.

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

End of Time

Return a new Dayjs object by by setting it to the end of a unit of time.

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

Display

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

Format

  • return String

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

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

Difference

  • return Number

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

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

Unix Timestamp (milliseconds)

  • return Number

Outputs the number of milliseconds since the Unix Epoch

dayjs().valueOf();

Unix Timestamp (seconds)

  • return Number

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

dayjs().unix();

Days in Month

  • return Number

Get the number of days in the current month.

dayjs().daysInMonth();

As Javascript Date

  • return Javascript Date object

Get copy of the native Date object from Dayjs object.

dayjs().toDate();

As Array

  • return Array

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

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

As JSON

  • return JSON String

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

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

As ISO 8601 String

  • return String

Formats a string to the ISO8601 standard.

dayjs().toISOString();

As Object

  • return Object

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

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

As String

  • return String
dayjs().toString();

Query

Is Before

  • return Boolean

Check if a Dayjs object is before another Dayjs object.

dayjs().isBefore(Dayjs);
dayjs().isBefore(dayjs()); // false

Is Same

  • return Boolean

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

dayjs().isSame(Dayjs);
dayjs().isSame(dayjs()); // true

Is After

  • return Boolean

Check if a Dayjs object is after another Dayjs object.

dayjs().isAfter(Dayjs);
dayjs().isAfter(dayjs()); // false

Is Leap Year

  • return Boolean

Check if a year is a leap year.

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

License

MIT