Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/Teamweek/instadate
A minimal high performance date library for Node.js and Browser
https://github.com/Teamweek/instadate
Last synced: about 1 month ago
JSON representation
A minimal high performance date library for Node.js and Browser
- Host: GitHub
- URL: https://github.com/Teamweek/instadate
- Owner: Teamweek
- License: mit
- Created: 2016-01-18T09:54:26.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2019-05-10T08:11:03.000Z (over 5 years ago)
- Last Synced: 2024-10-30T11:09:09.004Z (about 1 month ago)
- Language: JavaScript
- Homepage:
- Size: 38.1 KB
- Stars: 797
- Watchers: 23
- Forks: 30
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# Instadate [](https://travis-ci.org/Teamweek/instadate)
A minimal high performance date library for Node.js and Browser. Use it to compare and manipulate dates.
## Installation
```
npm install instadate
```
## Usage
### ES6
```javascript
import instadate from "instadate";
const date1 = new Date();
const date2 = instadate.addDays(date1, 1);
instadate.differenceInDates(date1, date2); // => 1
```
### ES5
```javascript
var instadate = require("instadate");
var date1 = new Date();
var date2 = instadate.addDays(date1, 1);
instadate.differenceInDates(date1, date2); // => 1
```
## Motivation behind Instadate
Current popular date libraries put a lot of effort into doing a lot causing them to lose a lot of performance because of heavy abstractions. Instadate on the other hand only has a handful of features that are all geared towards performance. Instadate is more of a wrapper around the native JavaScript Date than a full on date library.
Use Instadate when you need to run thousands of date manipulations or comparisons per second. Instadate is managed and used by [Teamweek](https://teamweek.com/) team calendar.
**Instadate..**
- is **fast** (10 - 1000 times faster than moment)
- is **small** (just look at the source)
- is **immutable** (Instadate will always return new date objects and never modify the given ones)
## API Reference
**`utc(date)`**
Returns the UTC time in milliseconds.
**`noon(date)`**
Returns a copy of the date with hours set to 12 and minutes, seconds and milliseconds set to 0.
**`differenceInDays(from, to)`**
Returns the difference in days (24 hour periods) between two dates. Returned result can be negative.
**`differenceInHours(from, to)`**
Returns the difference in hours (60 minute periods) between two dates. Returned result can be negative.
**`differenceInMinutes(from, to)`**
Returns the difference in minutes (60 second periods) between two dates. Returned result can be negative.
**`differenceInSeconds(from, to)`**
Returns the difference in seconds (1000 millisecond periods) between two dates. Returned result can be negative.
**`differenceInWeekendDays(from, to)`**
Returns the difference in days (24 hour periods) between two dates. Excludes work days. Returned result can be negative.
**`differenceInWorkDays(from, to)`**
Returns the difference in days (24 hour periods) between two dates. Excludes weekend days. Returned result can be negative.
**`differenceInDates(from, to)`**
Similar to `differenceInDays` however counts all dates that fit into the period, not 24 hour periods.
**`addYears(date, years)`**
Returns a cloned date with years added to it, use negative input for subtraction.
**`addMonths(date, months)`**
Returns a cloned date with months added to it, use negative input for subtraction.
**`addDays(date, days)`**
Returns a cloned date with days added to it, use negative input for subtraction.
**`addHours(date, hours)`**
Returns a cloned date with hours added to it, use negative input for subtraction.
**`addMinutes(date, minutes)`**
Returns a cloned date with minutes added to it, use negative input for subtraction.
**`addSeconds(date, seconds)`**
Returns a cloned date with seconds added to it, use negative input for subtraction.
**`addMilliseconds(date, milliseconds)`**
Returns a cloned date with milliseconds added to it, use negative input for subtraction.
**`isSameYear(date1, date2)`**
Returns if the years are equal
**`isSameMonth(date1, date2)`**
Returns if the years and months are equal
**`isSameDay(date1, date2)`**
Returns if the years, months and dates are equal
**`equal(date1, date2)`**
Returns if the dates are equal to millisecond precision
**`min(date1, date2)`**
Returns the earliest date
**`max(date1, date2)`**
Returns the latest date
**`dates(start, end)`**
Returns all dates within start and end period. Uses `differenceInDates` internally.
**`dateString(date)`**
Returns the date part of a Date as a string. Example: `Mon Jan 25 2016`.
**`isoDateString(date)`**
Returns the date part of an iso Date as a string. Example: `2016-01-25`.
**`parseISOString(isoString)`**
Parses an ISO string to a date. If used in a browser environment also resets the timezone offset using `resetTimezoneOffset`.
```js
const date = instadate.parseISOString("2017-04-24");
// Sun Apr 24 2017 00:00:00 GMT-0700 (PDT)
```
**`resetTimezoneOffset(date)`**
Resets the timezone offset caused by browsers when parsing a date.
```js
let date = new Date("2017-04-24");
// Sun Apr 23 2017 17:00:00 GMT-0700 (PDT)
// Note how the parsed date is 23, not 24
// This is caused by browsers and does not happen in node
date = instadate.resetTimezoneOffset(date);
// Sun Apr 24 2017 00:00:00 GMT-0700 (PDT)
```
**`firstDateInMonth(date)`**
Returns the first date of the month.
**`lastDateInMonth(date)`**
Returns the last date of the month.
**`isWeekendDay(day)`**
Checks if the given day (0-6) is a weekend day.
**`isWorkDay(day)`**
Checks if the given day (0-6) is a work day.
**`isWeekendDate(date)`**
Checks if the given date is a weekend day.
**`isWorkDate(date)`**
Checks if the given date is a work day.
**`setWeekendDays(daysArray)`**
Sets the given days (array containing integers from 0 to 6) as weekend days. Any day not in the array will be set as a work day. After the weekend days are set all Instadate functions will use the new work and weekend days.
**`daysInPeriod(firstDay, length, daysArray)`**
Counts the days defined in daysArray within the given period.
- firstDay - day to start counting from (0-6)
- length - the total of days to count (can be negative)
- daysArray - array of days to count (if you want to count Mondays and Tuesdays use [1, 2])
**`weekendDaysInPeriod(firstDay, length)`**
Counts weekend days within period.
**`workDaysInPeriod(firstDay, length)`**
Counts work days within period.
**`isAfter(date1, date2)`**
Checks if date1 is after date2.
**`isYearAfter(date1, date2)`**
Checks if date1 year is after date2 year.
**`isMonthAfter(date1, date2)`**
Checks if date1 month is after date2 month.
**`isDayAfter(date1, date2)`**
Checks if date1 date is after date2 date.
**`isBefore(date1, date2)`**
Checks if date1 is before date2.
**`isYearBefore(date1, date2)`**
Checks if date1 year is before date2 year.
**`isMonthBefore(date1, date2)`**
Checks if date1 month is before date2 month.
**`isDayBefore(date1, date2)`**
Checks if date1 date is before date2 date.
**`isYearBetween(date1, date2, date3)`**
Checks if date1 year is between date2 and date3 years.
**`isMonthBetween(date1, date2, date3)`**
Checks if date1 month is between date2 and date3 months.
**`isDayBetween(date1, date2, date3)`**
Checks if date1 is between date2 and date3.
**`isoWeekDay(day)`**
Converts day (0-6) to iso day (1-7).
**`daysInMonth(month, year)`**
Returns how many days are in a month.
```js
let date = new Date();
instadate.daysInMonth(date.getMonth(), date.getFullYear()); //28, 29, 30 or 31
```
## Testing
```
npm test
```
## License
MIT
## Changelog
- 0.6.0 - Added `daysInMonth` function.
- 0.5.0 - Changed `isoDateString` to work correctly with UTC+13, UTC+14 & UTC-12. Removed `dateString` function.
- 0.4.0 - Added `parseISOString` and `resetTimezoneOffset` functions
- 0.3.2 - Performance optimisations. Subtract dates instead of comparing them.
- 0.3.1 - Modified `addDays`, `addHours`, `addMinutes`, `addSeconds` and `addMilliseconds` functions to work with dayling saving changes.