Dates-by-month NPM

Dates by Month

dates-by-month returns a nested array of date objects, sorted by month.

Setup

Install the package:

npm install dates-by-month

Usage

dates-by-month accepts 4 optional arguments:

startDate (default is new Date())
- dates-by-month will return a nested array, where each child array is every date within a particular month - partial months are not returned.
- The startDate argument must be a date object.
- It can be any date within the month that you want to be the base for the return.
  - For example, whether this argument is new Date('2024-05-01') or new Date('2024-05-31') won't affect the return as both of these dates are within the same month. new Date('2024-06-01') will give a different return as it's in a different month.
numberOfPastMonths (default is 0)
- This must be a whole number of 0 or above - decimals are not accepted.
- Strings that can be evaulated as postive integers are accepted (for example '3').
- This value defines the number of months before the startDate month that will be returned.
  - For example, if startDate is new Date('2024-05-03') and numberOfPastMonths is 3 then the return will include the dates for February '24, March '24, April '24 and May '24.
numberOfFutureMonths (default is 0)
- Accepts the same values as numberOfPastMonths.
- numberOfFutureMonths defines the number of months after the startDate month that will be returned.
  - For example, if startDate is new Date('2024-05-03'), numberOfPastMonths is 0 and numberOfFutureMonths is 3 then the return will include the dates for May '24, June '24, July '24 and August '24.
utc (default is true)
- Will be evaluated as truthy or falsey.
- When truthy it will return the dates in UTC.
- When falsey it will return dates in the user's local timezone.

Examples

import datesByMonth from 'dates-by-month';

// Assuming today's date is 3rd May 2024
console.log(datesByMonth());
/*
[
  [
    2024-05-01T00:00:00.000Z,
    2024-05-02T00:00:00.000Z,
    2024-05-03T00:00:00.000Z,
    2024-05-04T00:00:00.000Z,
    2024-05-05T00:00:00.000Z,
    2024-05-06T00:00:00.000Z,
    2024-05-07T00:00:00.000Z,
    2024-05-08T00:00:00.000Z,
    2024-05-09T00:00:00.000Z,
    2024-05-10T00:00:00.000Z,
    2024-05-11T00:00:00.000Z,
    2024-05-12T00:00:00.000Z,
    2024-05-13T00:00:00.000Z,
    2024-05-14T00:00:00.000Z,
    2024-05-15T00:00:00.000Z,
    2024-05-16T00:00:00.000Z,
    2024-05-17T00:00:00.000Z,
    2024-05-18T00:00:00.000Z,
    2024-05-19T00:00:00.000Z,
    2024-05-20T00:00:00.000Z,
    2024-05-21T00:00:00.000Z,
    2024-05-22T00:00:00.000Z,
    2024-05-23T00:00:00.000Z,
    2024-05-24T00:00:00.000Z,
    2024-05-25T00:00:00.000Z,
    2024-05-26T00:00:00.000Z,
    2024-05-27T00:00:00.000Z,
    2024-05-28T00:00:00.000Z,
    2024-05-29T00:00:00.000Z,
    2024-05-30T00:00:00.000Z,
    2024-05-31T00:00:00.000Z
  ]
]
*/

console.log(datesByMonth(new Date('2020-03-31')));
/*
[
  [
    2020-03-01T00:00:00.000Z,
    2020-03-02T00:00:00.000Z,
    2020-03-03T00:00:00.000Z,
    2020-03-04T00:00:00.000Z,
    2020-03-05T00:00:00.000Z,
    2020-03-06T00:00:00.000Z,
    2020-03-07T00:00:00.000Z,
    2020-03-08T00:00:00.000Z,
    2020-03-09T00:00:00.000Z,
    2020-03-10T00:00:00.000Z,
    2020-03-11T00:00:00.000Z,
    2020-03-12T00:00:00.000Z,
    2020-03-13T00:00:00.000Z,
    2020-03-14T00:00:00.000Z,
    2020-03-15T00:00:00.000Z,
    2020-03-16T00:00:00.000Z,
    2020-03-17T00:00:00.000Z,
    2020-03-18T00:00:00.000Z,
    2020-03-19T00:00:00.000Z,
    2020-03-20T00:00:00.000Z,
    2020-03-21T00:00:00.000Z,
    2020-03-22T00:00:00.000Z,
    2020-03-23T00:00:00.000Z,
    2020-03-24T00:00:00.000Z,
    2020-03-25T00:00:00.000Z,
    2020-03-26T00:00:00.000Z,
    2020-03-27T00:00:00.000Z,
    2020-03-28T00:00:00.000Z,
    2020-03-29T00:00:00.000Z,
    2020-03-30T00:00:00.000Z,
    2020-03-31T00:00:00.000Z
  ]
]
*/

console.log(datesByMonth(new Date('2024-05-03'), 2));
/*
[
  [
    2024-03-01T00:00:00.000Z,
    2024-03-02T00:00:00.000Z,
    2024-03-03T00:00:00.000Z,
    2024-03-04T00:00:00.000Z,
    2024-03-05T00:00:00.000Z,
    2024-03-06T00:00:00.000Z,
    2024-03-07T00:00:00.000Z,
    2024-03-08T00:00:00.000Z,
    2024-03-09T00:00:00.000Z,
    2024-03-10T00:00:00.000Z,
    2024-03-11T00:00:00.000Z,
    2024-03-12T00:00:00.000Z,
    2024-03-13T00:00:00.000Z,
    2024-03-14T00:00:00.000Z,
    2024-03-15T00:00:00.000Z,
    2024-03-16T00:00:00.000Z,
    2024-03-17T00:00:00.000Z,
    2024-03-18T00:00:00.000Z,
    2024-03-19T00:00:00.000Z,
    2024-03-20T00:00:00.000Z,
    2024-03-21T00:00:00.000Z,
    2024-03-22T00:00:00.000Z,
    2024-03-23T00:00:00.000Z,
    2024-03-24T00:00:00.000Z,
    2024-03-25T00:00:00.000Z,
    2024-03-26T00:00:00.000Z,
    2024-03-27T00:00:00.000Z,
    2024-03-28T00:00:00.000Z,
    2024-03-29T00:00:00.000Z,
    2024-03-30T00:00:00.000Z,
    2024-03-31T00:00:00.000Z
  ],
  [
    2024-04-01T00:00:00.000Z,
    2024-04-02T00:00:00.000Z,
    2024-04-03T00:00:00.000Z,
    2024-04-04T00:00:00.000Z,
    2024-04-05T00:00:00.000Z,
    2024-04-06T00:00:00.000Z,
    2024-04-07T00:00:00.000Z,
    2024-04-08T00:00:00.000Z,
    2024-04-09T00:00:00.000Z,
    2024-04-10T00:00:00.000Z,
    2024-04-11T00:00:00.000Z,
    2024-04-12T00:00:00.000Z,
    2024-04-13T00:00:00.000Z,
    2024-04-14T00:00:00.000Z,
    2024-04-15T00:00:00.000Z,
    2024-04-16T00:00:00.000Z,
    2024-04-17T00:00:00.000Z,
    2024-04-18T00:00:00.000Z,
    2024-04-19T00:00:00.000Z,
    2024-04-20T00:00:00.000Z,
    2024-04-21T00:00:00.000Z,
    2024-04-22T00:00:00.000Z,
    2024-04-23T00:00:00.000Z,
    2024-04-24T00:00:00.000Z,
    2024-04-25T00:00:00.000Z,
    2024-04-26T00:00:00.000Z,
    2024-04-27T00:00:00.000Z,
    2024-04-28T00:00:00.000Z,
    2024-04-29T00:00:00.000Z,
    2024-04-30T00:00:00.000Z
  ],
  [
    2024-05-01T00:00:00.000Z,
    2024-05-02T00:00:00.000Z,
    2024-05-03T00:00:00.000Z,
    2024-05-04T00:00:00.000Z,
    2024-05-05T00:00:00.000Z,
    2024-05-06T00:00:00.000Z,
    2024-05-07T00:00:00.000Z,
    2024-05-08T00:00:00.000Z,
    2024-05-09T00:00:00.000Z,
    2024-05-10T00:00:00.000Z,
    2024-05-11T00:00:00.000Z,
    2024-05-12T00:00:00.000Z,
    2024-05-13T00:00:00.000Z,
    2024-05-14T00:00:00.000Z,
    2024-05-15T00:00:00.000Z,
    2024-05-16T00:00:00.000Z,
    2024-05-17T00:00:00.000Z,
    2024-05-18T00:00:00.000Z,
    2024-05-19T00:00:00.000Z,
    2024-05-20T00:00:00.000Z,
    2024-05-21T00:00:00.000Z,
    2024-05-22T00:00:00.000Z,
    2024-05-23T00:00:00.000Z,
    2024-05-24T00:00:00.000Z,
    2024-05-25T00:00:00.000Z,
    2024-05-26T00:00:00.000Z,
    2024-05-27T00:00:00.000Z,
    2024-05-28T00:00:00.000Z,
    2024-05-29T00:00:00.000Z,
    2024-05-30T00:00:00.000Z,
    2024-05-31T00:00:00.000Z
  ]
]
*/

console.log(datesByMonth(new Date('2024-05-03'), 2, 3));
/*
[
  [
    2024-03-01T00:00:00.000Z,
    2024-03-02T00:00:00.000Z,
    2024-03-03T00:00:00.000Z,
    2024-03-04T00:00:00.000Z,
    2024-03-05T00:00:00.000Z,
    2024-03-06T00:00:00.000Z,
    2024-03-07T00:00:00.000Z,
    2024-03-08T00:00:00.000Z,
    2024-03-09T00:00:00.000Z,
    2024-03-10T00:00:00.000Z,
    2024-03-11T00:00:00.000Z,
    2024-03-12T00:00:00.000Z,
    2024-03-13T00:00:00.000Z,
    2024-03-14T00:00:00.000Z,
    2024-03-15T00:00:00.000Z,
    2024-03-16T00:00:00.000Z,
    2024-03-17T00:00:00.000Z,
    2024-03-18T00:00:00.000Z,
    2024-03-19T00:00:00.000Z,
    2024-03-20T00:00:00.000Z,
    2024-03-21T00:00:00.000Z,
    2024-03-22T00:00:00.000Z,
    2024-03-23T00:00:00.000Z,
    2024-03-24T00:00:00.000Z,
    2024-03-25T00:00:00.000Z,
    2024-03-26T00:00:00.000Z,
    2024-03-27T00:00:00.000Z,
    2024-03-28T00:00:00.000Z,
    2024-03-29T00:00:00.000Z,
    2024-03-30T00:00:00.000Z,
    2024-03-31T00:00:00.000Z
  ],
  [
    2024-04-01T00:00:00.000Z,
    2024-04-02T00:00:00.000Z,
    2024-04-03T00:00:00.000Z,
    2024-04-04T00:00:00.000Z,
    2024-04-05T00:00:00.000Z,
    2024-04-06T00:00:00.000Z,
    2024-04-07T00:00:00.000Z,
    2024-04-08T00:00:00.000Z,
    2024-04-09T00:00:00.000Z,
    2024-04-10T00:00:00.000Z,
    2024-04-11T00:00:00.000Z,
    2024-04-12T00:00:00.000Z,
    2024-04-13T00:00:00.000Z,
    2024-04-14T00:00:00.000Z,
    2024-04-15T00:00:00.000Z,
    2024-04-16T00:00:00.000Z,
    2024-04-17T00:00:00.000Z,
    2024-04-18T00:00:00.000Z,
    2024-04-19T00:00:00.000Z,
    2024-04-20T00:00:00.000Z,
    2024-04-21T00:00:00.000Z,
    2024-04-22T00:00:00.000Z,
    2024-04-23T00:00:00.000Z,
    2024-04-24T00:00:00.000Z,
    2024-04-25T00:00:00.000Z,
    2024-04-26T00:00:00.000Z,
    2024-04-27T00:00:00.000Z,
    2024-04-28T00:00:00.000Z,
    2024-04-29T00:00:00.000Z,
    2024-04-30T00:00:00.000Z
  ],
  [
    2024-05-01T00:00:00.000Z,
    2024-05-02T00:00:00.000Z,
    2024-05-03T00:00:00.000Z,
    2024-05-04T00:00:00.000Z,
    2024-05-05T00:00:00.000Z,
    2024-05-06T00:00:00.000Z,
    2024-05-07T00:00:00.000Z,
    2024-05-08T00:00:00.000Z,
    2024-05-09T00:00:00.000Z,
    2024-05-10T00:00:00.000Z,
    2024-05-11T00:00:00.000Z,
    2024-05-12T00:00:00.000Z,
    2024-05-13T00:00:00.000Z,
    2024-05-14T00:00:00.000Z,
    2024-05-15T00:00:00.000Z,
    2024-05-16T00:00:00.000Z,
    2024-05-17T00:00:00.000Z,
    2024-05-18T00:00:00.000Z,
    2024-05-19T00:00:00.000Z,
    2024-05-20T00:00:00.000Z,
    2024-05-21T00:00:00.000Z,
    2024-05-22T00:00:00.000Z,
    2024-05-23T00:00:00.000Z,
    2024-05-24T00:00:00.000Z,
    2024-05-25T00:00:00.000Z,
    2024-05-26T00:00:00.000Z,
    2024-05-27T00:00:00.000Z,
    2024-05-28T00:00:00.000Z,
    2024-05-29T00:00:00.000Z,
    2024-05-30T00:00:00.000Z,
    2024-05-31T00:00:00.000Z
  ],
  [
    2024-06-01T00:00:00.000Z,
    2024-06-02T00:00:00.000Z,
    2024-06-03T00:00:00.000Z,
    2024-06-04T00:00:00.000Z,
    2024-06-05T00:00:00.000Z,
    2024-06-06T00:00:00.000Z,
    2024-06-07T00:00:00.000Z,
    2024-06-08T00:00:00.000Z,
    2024-06-09T00:00:00.000Z,
    2024-06-10T00:00:00.000Z,
    2024-06-11T00:00:00.000Z,
    2024-06-12T00:00:00.000Z,
    2024-06-13T00:00:00.000Z,
    2024-06-14T00:00:00.000Z,
    2024-06-15T00:00:00.000Z,
    2024-06-16T00:00:00.000Z,
    2024-06-17T00:00:00.000Z,
    2024-06-18T00:00:00.000Z,
    2024-06-19T00:00:00.000Z,
    2024-06-20T00:00:00.000Z,
    2024-06-21T00:00:00.000Z,
    2024-06-22T00:00:00.000Z,
    2024-06-23T00:00:00.000Z,
    2024-06-24T00:00:00.000Z,
    2024-06-25T00:00:00.000Z,
    2024-06-26T00:00:00.000Z,
    2024-06-27T00:00:00.000Z,
    2024-06-28T00:00:00.000Z,
    2024-06-29T00:00:00.000Z,
    2024-06-30T00:00:00.000Z
  ],
  [
    2024-07-01T00:00:00.000Z,
    2024-07-02T00:00:00.000Z,
    2024-07-03T00:00:00.000Z,
    2024-07-04T00:00:00.000Z,
    2024-07-05T00:00:00.000Z,
    2024-07-06T00:00:00.000Z,
    2024-07-07T00:00:00.000Z,
    2024-07-08T00:00:00.000Z,
    2024-07-09T00:00:00.000Z,
    2024-07-10T00:00:00.000Z,
    2024-07-11T00:00:00.000Z,
    2024-07-12T00:00:00.000Z,
    2024-07-13T00:00:00.000Z,
    2024-07-14T00:00:00.000Z,
    2024-07-15T00:00:00.000Z,
    2024-07-16T00:00:00.000Z,
    2024-07-17T00:00:00.000Z,
    2024-07-18T00:00:00.000Z,
    2024-07-19T00:00:00.000Z,
    2024-07-20T00:00:00.000Z,
    2024-07-21T00:00:00.000Z,
    2024-07-22T00:00:00.000Z,
    2024-07-23T00:00:00.000Z,
    2024-07-24T00:00:00.000Z,
    2024-07-25T00:00:00.000Z,
    2024-07-26T00:00:00.000Z,
    2024-07-27T00:00:00.000Z,
    2024-07-28T00:00:00.000Z,
    2024-07-29T00:00:00.000Z,
    2024-07-30T00:00:00.000Z,
    2024-07-31T00:00:00.000Z
  ],
  [
    2024-08-01T00:00:00.000Z,
    2024-08-02T00:00:00.000Z,
    2024-08-03T00:00:00.000Z,
    2024-08-04T00:00:00.000Z,
    2024-08-05T00:00:00.000Z,
    2024-08-06T00:00:00.000Z,
    2024-08-07T00:00:00.000Z,
    2024-08-08T00:00:00.000Z,
    2024-08-09T00:00:00.000Z,
    2024-08-10T00:00:00.000Z,
    2024-08-11T00:00:00.000Z,
    2024-08-12T00:00:00.000Z,
    2024-08-13T00:00:00.000Z,
    2024-08-14T00:00:00.000Z,
    2024-08-15T00:00:00.000Z,
    2024-08-16T00:00:00.000Z,
    2024-08-17T00:00:00.000Z,
    2024-08-18T00:00:00.000Z,
    2024-08-19T00:00:00.000Z,
    2024-08-20T00:00:00.000Z,
    2024-08-21T00:00:00.000Z,
    2024-08-22T00:00:00.000Z,
    2024-08-23T00:00:00.000Z,
    2024-08-24T00:00:00.000Z,
    2024-08-25T00:00:00.000Z,
    2024-08-26T00:00:00.000Z,
    2024-08-27T00:00:00.000Z,
    2024-08-28T00:00:00.000Z,
    2024-08-29T00:00:00.000Z,
    2024-08-30T00:00:00.000Z,
    2024-08-31T00:00:00.000Z
  ]
]
*/

console.log(datesByMonth(new Date('2024-05-03'), 0, 0, true));
/*
[
  [
    2024-05-01T00:00:00.000Z,
    2024-05-02T00:00:00.000Z,
    2024-05-03T00:00:00.000Z,
    2024-05-04T00:00:00.000Z,
    2024-05-05T00:00:00.000Z,
    2024-05-06T00:00:00.000Z,
    2024-05-07T00:00:00.000Z,
    2024-05-08T00:00:00.000Z,
    2024-05-09T00:00:00.000Z,
    2024-05-10T00:00:00.000Z,
    2024-05-11T00:00:00.000Z,
    2024-05-12T00:00:00.000Z,
    2024-05-13T00:00:00.000Z,
    2024-05-14T00:00:00.000Z,
    2024-05-15T00:00:00.000Z,
    2024-05-16T00:00:00.000Z,
    2024-05-17T00:00:00.000Z,
    2024-05-18T00:00:00.000Z,
    2024-05-19T00:00:00.000Z,
    2024-05-20T00:00:00.000Z,
    2024-05-21T00:00:00.000Z,
    2024-05-22T00:00:00.000Z,
    2024-05-23T00:00:00.000Z,
    2024-05-24T00:00:00.000Z,
    2024-05-25T00:00:00.000Z,
    2024-05-26T00:00:00.000Z,
    2024-05-27T00:00:00.000Z,
    2024-05-28T00:00:00.000Z,
    2024-05-29T00:00:00.000Z,
    2024-05-30T00:00:00.000Z,
    2024-05-31T00:00:00.000Z
  ]
]
*/

// Assuming that the user is on Taipei Standard Time (UTC + 8)
console.log(datesByMonth(new Date('2024-05-03'), 0, 0, false));
/*
[
  [
    2024-04-30T16:00:00.000Z,
    2024-05-01T16:00:00.000Z,
    2024-05-02T16:00:00.000Z,
    2024-05-03T16:00:00.000Z,
    2024-05-04T16:00:00.000Z,
    2024-05-05T16:00:00.000Z,
    2024-05-06T16:00:00.000Z,
    2024-05-07T16:00:00.000Z,
    2024-05-08T16:00:00.000Z,
    2024-05-09T16:00:00.000Z,
    2024-05-10T16:00:00.000Z,
    2024-05-11T16:00:00.000Z,
    2024-05-12T16:00:00.000Z,
    2024-05-13T16:00:00.000Z,
    2024-05-14T16:00:00.000Z,
    2024-05-15T16:00:00.000Z,
    2024-05-16T16:00:00.000Z,
    2024-05-17T16:00:00.000Z,
    2024-05-18T16:00:00.000Z,
    2024-05-19T16:00:00.000Z,
    2024-05-20T16:00:00.000Z,
    2024-05-21T16:00:00.000Z,
    2024-05-22T16:00:00.000Z,
    2024-05-23T16:00:00.000Z,
    2024-05-24T16:00:00.000Z,
    2024-05-25T16:00:00.000Z,
    2024-05-26T16:00:00.000Z,
    2024-05-27T16:00:00.000Z,
    2024-05-28T16:00:00.000Z,
    2024-05-29T16:00:00.000Z,
    2024-05-30T16:00:00.000Z
  ]
]
*/

// Assuming that the user is on Colombia Standard Time (UTC - 5)
console.log(datesByMonth(new Date('2024-05-03'), 0, 0, false));
/*
[
  [
    2024-05-01T05:00:00.000Z,
    2024-05-02T05:00:00.000Z,
    2024-05-03T05:00:00.000Z,
    2024-05-04T05:00:00.000Z,
    2024-05-05T05:00:00.000Z,
    2024-05-06T05:00:00.000Z,
    2024-05-07T05:00:00.000Z,
    2024-05-08T05:00:00.000Z,
    2024-05-09T05:00:00.000Z,
    2024-05-10T05:00:00.000Z,
    2024-05-11T05:00:00.000Z,
    2024-05-12T05:00:00.000Z,
    2024-05-13T05:00:00.000Z,
    2024-05-14T05:00:00.000Z,
    2024-05-15T05:00:00.000Z,
    2024-05-16T05:00:00.000Z,
    2024-05-17T05:00:00.000Z,
    2024-05-18T05:00:00.000Z,
    2024-05-19T05:00:00.000Z,
    2024-05-20T05:00:00.000Z,
    2024-05-21T05:00:00.000Z,
    2024-05-22T05:00:00.000Z,
    2024-05-23T05:00:00.000Z,
    2024-05-24T05:00:00.000Z,
    2024-05-25T05:00:00.000Z,
    2024-05-26T05:00:00.000Z,
    2024-05-27T05:00:00.000Z,
    2024-05-28T05:00:00.000Z,
    2024-05-29T05:00:00.000Z,
    2024-05-30T05:00:00.000Z,
    2024-05-31T05:00:00.000Z
  ]
]
*/

console.log(datesByMonth('2024-05-03', 2, 3));
// Error: The first argument must be a date object (for example, new Date('2024-01-01'))

console.log(datesByMonth(new Date('2024-05-03'), 2.1, 3));
// Error: The second argument must be a whole number equal to or greater than zero (for example 3)

console.log(datesByMonth(new Date('2024-05-03'), 2, -3));
// Error: The third argument must be a whole number equal to or greater than zero (for example 3)

dates-by-month month-dates array-of-month-dates array-of-months calendar-dates

1 year ago

1 year ago

1 year ago

1 year ago