jayc13 / dayjs

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

English | 简体中文

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

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
  • 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 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