easy-date-range

easy-date-range is a simple, easy to use library for creating date ranges which can be used as a foundation for building all sorts of calendars, schedulers, date lists and more.

Features

Single reference date

easy-date-range simplifies the creation of date ranges by using methods that only need one reference date. The range you get is determined by the method you choose, and the reference date that belongs to it.

Descriptive API

Here is a brief summary of core functionalities: the range generators:

getDays creates a range of custom number of days.
getMonthExact creates a month range, from the first to the last day of the month.
getMonthExtended creates a month range extended to include the full weeks.
getWeek creates a week range.
getNext and getPrevious enable easy shifting of any range passed into them.

Easy to customize

All range generators use the current day as a reference date unless specified otherwise. It can be easily customized by passing an options object where you can also set other settings such as offsets, day that starts the week or days count and more.

Type-Safe

easy-date-range is written entirely in TypeScript for type safety and other benefits such as autocomplete features in your code editor. Works with no issues in plain JavaScript environment, too.

Date and time made easy with Luxon

easy-date-range uses Luxon as a peer dependency for date handling. Luxon is a powerful and modern library for working with dates and times in JavaScript. It offers a consistent and fluent API, as well as support for various formats and locales.

easy-date-range supports both Luxon and native JavaScript dates as inputs and outputs.

More features to come

At the moment, easy-date-range provides basic functionality for creating date ranges that cover full days. In the future, I plan to add more functions for creating ranges that span other intervals such as minutes, hours or months and years.

Installation

To install easy-date-range, run:

npm install easy-date-range luxon

Usage

Basic usage

import { DateRange } from 'easy-date-range';

// create a range of current week starting on Monday
const currentWeek = new DateRange().getWeek();

// create a range of a week with specifying reference date
const week = new DateRange().getWeek({ refDate: new Date('2023-01-01') });

Then to access dates array use:

// 'toDateTimes' method for an array of Luxon DateTimes
currentWeek.toDateTimes().forEach((date) => console.log(date.toString()));

// 'toDates' method for an array of JS Dates
currentWeek.toDates().forEach((date) => console.log(date.toString()));

// you can also use a getter property 'dateTimes' for Luxon DateTimes
currentWeek.dateTimes.forEach((dateTime) => console.log(dateTime.toString()));

Customize the range

You can customize the range with an options object passed to a range generator.

Common options available for all methods:

refDate for setting the reference date,
startOffset for setting the offset at the start of the range,
endOffset for setting the offset at the end of the range,

Specific options depending on the method and type of range it generates:

refWeekday for setting the weekday to start the range from. Available with getWeek and getMonthExtended methods
daysCount for setting the number of days with getDays method

Note: The offset is applied after the range is created; or in other words, it comes after all other options. Think of it as a way to add or subtract days from your range as a final touch.

Here is a brief example showing how you can customize the range.

// set a month range of January 2023 extended to full weeks with customized refWeekday and offsets
const monthExtended = new DateRange().getMonthExtended({
  refDate: new Date('2023-01-01'),
  refWeekday: WEEKDAY.Sunday,
  startOffset: 2,
  endOffset: -2,
});

The range from the above example will include dates that span across all the days of January 2023 extended to start from Friday, Dec 30, 2022 and end on Thursday, Feb 2, 2023.

The first two days in the range come from the startOffset setting, which added two extra days. At the end of the range, two days were removed because of the negative endOffset setting.

Without the offsets, the first day of the range would be Jan 1, 2023 (Sunday - as specified with refWeekday) and the last day would be Feb 4, 2023 (Saturday).

API

DateRange class

DateRange is the core component of easy-date-range. It provides various methods and properties for generating and handling date ranges.

To use the class, an instance must be created and initialized with one of the range generator methods.

Properties

Property	Type	Default value	Description
daysCount	number	0	The days count value for the range generated by getDays.
dateTimes	Array<DateTime>	not applicable	The array of luxon DateTimes for current generated range.
endOffset	number	0	The end offset value for current generated range.
rangeType	RANGE_TYPE	not applicable	The type of current generated range.
refDate	DateTime	current day	The reference date for current generated range.
refWeekday	WEEKDAY	1	The reference weekday value for current generated range.
startOffset	number	0	The start offset value for current generated range.
isNext	boolean	false	A boolean that indicates whether DateRange is created with a `getNext` method.
isPrevious	boolean	false	A boolean that indicates whether DateRange is created with a `getPrevious` method.

Note: All the properties are defined once the date range is initialized, regardless of whether they are relevant for the current range or not.

Methods

Range generators

Method	Description
getDays	Creates a range of custom number of days.
getMonthExact	Creates a single month range, from the first to the last day of the month.
getMonthExtended	Creates a single month range extended to include the full weeks.
getWeek	Creates a single week range.
getNext	Creates the next range based on given one.
getPrevious	Creates the previous range based on given one.

Utilities

Method	Description
isValidOffset	Checks if a given value is a valid offset.
isValidRefDate	Checks if a given value is a valid reference date.
isValidRefWeekday	Checks if a given value is a valid weekday

Date array getters

Method	Description
toDates	Returns an array of dates generated for the instance as JS Date objects.
toDateTimes	Returns an array of dates generated for the instance as Luxon DateTime objects.

getDays

Creates a range of custom number of days.

The reference date is a starting point of the range.

The reference date is set to the current day if not specified otherwise.

The length of the range can be specified with the daysCount property in the options object. If not specified, the range will be created with a single date.

Each date is set to the start of the day (midnight).

Signature

public getDays(options?: OptionsDays): DateRange

Parameters

Parameter	Type	Description
options	OptionsDays	An object to configure the range.

Options properties

Property	Type	Description
refDate	DateTime \| Date	The reference date to calculate the range.
daysCount	number	The number of days to include in the range.
startOffset	number	The number of days to add or remove from the beginning of the range.
endOffset	number	The number of days to add or remove from the end of the range.

Returns:

DateRange

Examples

// Get a current date
const range1 = new DateRange().getDays();

// Get a range of 10 days starting on 2023-01-10
const range2 = new DateRange().getDays({
  daysCount: 10,
  refDate: new Date('2023-01-10'),
});
// Generated dates:
// Jan 10, 2023 at 12:00:00 AM
// Jan 11, 2023 at 12:00:00 AM
// Jan 12, 2023 at 12:00:00 AM
// Jan 13, 2023 at 12:00:00 AM
// Jan 14, 2023 at 12:00:00 AM
// Jan 15, 2023 at 12:00:00 AM
// Jan 16, 2023 at 12:00:00 AM
// Jan 17, 2023 at 12:00:00 AM
// Jan 18, 2023 at 12:00:00 AM
// Jan 19, 2023 at 12:00:00 AM

getMonthExact

Creates a single month range, from the first to the last day of the month.

The reference date is set to the current day if not specified otherwise.

Each date is set to the start of the day (midnight).

Signature

public getMonthExact(options?: OptionsMonthExact): DateRange

Parameters

Parameter	Type	Description
options	OptionsMonthExact	An object to configure the range.

Options properties

Property	Type	Description
refDate	DateTime \| Date	The reference date to calculate the range.
startOffset	number	The number of days to add or remove from the beginning of the range.
endOffset	number	The number of days to add or remove from the end of the range.

Returns:

DateRange

Examples

// Get current month
const currentMonthExact = new DateRange().getMonthExact();

// Get month with specified refDate
const monthExact = new DateRange().getMonthExact({
  refDate: new Date('2023-01-10'),
});
// Generated dates:
// Sun, January 1, 2023 at 12:00:00 AM -> The first date of the range
// Mon, January 2, 2023 at 12:00:00 AM
// Tue, January 3, 2023 at 12:00:00 AM
// ...
// Tue, January 31, 2023 at 12:00:00 AM -> The last date of the range

// Get month with specified refDate and offsets
const month3 = new DateRange().getMonthExact({
  refDate: new Date('2023-01-10'),
  startOffset: 2,
  endOffset: 2,
});
// Fri, December 30, 2022 at 12:00:00 AM  -> The range starts 2 days before default first day
// Sat, December 31, 2022 at 12:00:00 AM
// Sun, January 1, 2023 at 12:00:00 AM
// ...
// Tue, January 31, 2023 at 12:00:00 AM
// Wed, February 1, 2023 at 12:00:00 AM
// Thu, February 2, 2023 at 12:00:00 AM -> The range ends 2 days after default last day

getMonthExtended

Creates a single month range extended to include the full weeks.

By default, the method starts the range on Monday before or on the first day of the month and ends it on Sunday after or on the last day of the month.

The end of the week will also be shifted accordingly if the start of the week is changed to a different day than Monday.

The reference date is set to the current day if not specified otherwise.

Each date is set to the start of the day (midnight).

Signature

public getMonthExtended(options?: OptionsMonthExtended): DateRange

Parameters

Parameter	Type	Description
options	OptionsMonthExtended	An object to configure the range.

Options properties

Property	Type	Description
refDate	DateTime \| Date	The reference date to calculate the range.
refWeekday	WEEKDAY	The reference weekday to start the range from.
startOffset	number	The number of days to add or remove from the beginning of the range.
endOffset	number	The number of days to add or remove from the end of the range.

Returns:

DateRange

Examples

// Get current month extended to full weeks
const currentMonthExtended = new DateRange().getMonthExtended();

// Get month extended to full weeks based on a refDate and starting on Wednesday
const monthExtended = new DateRange().getMonthExtended({
  refDate: new Date('2023-01-10'),
  refWeekday: WEEKDAY.Wednesday,
});

// Generated dates:
// Wed, December 28, 2022 at 12:00:00 AM -> The first date of the range
// Thu, December 29, 2022 at 12:00:00 AM
// Fri, December 30, 2022 at 12:00:00 AM
// ...
// Tue, January 31, 2023 at 12:00:00 AM -> The last date of the range

getWeek

Creates a single week range.

By default, the method starts the range on Monday before or on the reference date and ends it on Sunday after or on the reference date.

If the start of the week is changed from Monday to a different day, the end of the week will also be shifted accordingly.

The reference date is set to the current day if not specified otherwise.

Each date is set to the start of the day (midnight).

Signature

public getWeek(options?: OptionsWeek): DateRange

Parameters

Parameter	Type	Description
options	OptionsWeek	An object to configure the range.

Options properties

Property	Type	Description
refDate	DateTime \| Date	The reference date to calculate the range.
refWeekday	WEEKDAY	The reference weekday to start the range from.
startOffset	number	The number of days to add or remove from the beginning of the range.
endOffset	number	The number of days to add or remove from the end of the range.

Returns:

DateRange

Examples

// get current week starting on Monday
const currentWeek = new DateRange().getWeek();

// get week based on a refDate and starting on Sunday
const week2 = new DateRange().getWeek({
  refDate: new Date('2023-01-10'),
  refWeekday: WEEKDAY.Sunday,
});
// Generated dates:👇
// Sun, January 8, 2023 at 12:00:00 AM
// Mon, January 9, 2023 at 12:00:00 AM
// Tue, January 10, 2023 at 12:00:00 AM
// Wed, January 11, 2023 at 12:00:00 AM
// Thu, January 12, 2023 at 12:00:00 AM
// Fri, January 13, 2023 at 12:00:00 AM
// Sat, January 14, 2023 at 12:00:00 AM

getNext

Generates the next range based on given one.

The method takes the refDate and rangeType from the DateRange argument and assigns a new refDate which can produce a new range that is one interval after the current one.

The method shifts the refDate to the next one as follows:

for a range generated with getDays, the refDate is incremented by the daysCount property.
for a range generated with getWeek, the refDate is incremented by 7 days.
for a range generated with getMonthExact and getMonthExtended, the refDate is set to the first day of the next month.

The options used to adjust the given range are copied and applied to the new range.

In all cases, the refDate is set to the start of the day (midnight).

To check whether the range is generated with a getNext method, access the isNext property on its instance.

Signature

public getNext(dateRange: DateRange): DateRange

Parameters

Parameter	Type	Description
dateRange	DateRange	A DateRange object with initialized range.

Returns:

DateRange

getPrevious

Generates the previous range based on given one.

The method takes the refDate and rangeType from the DateRange argument and assigns a new refDate which can produce a new range that is one interval after the current one.

The method shifts the refDate to the previous one as follows:

for a range generated with getDays, the refDate is decremented by the daysCount property.
for a range generated with getWeek, the refDate is decremented by 7 days.
for a range generated with getMonthExact and getMonthExtended, the refDate is set to the first day of the previous month.

The options used to adjust the given range are copied and applied to the new range.

In all cases, the refDate is set to the start of the day (midnight).

To check whether the range is generated with a getPrevious method, access the isPrevious property on its instance.

Signature

public getPrevious(dateRange: DateRange): DateRange

Parameters

Parameter	Type	Description
dateRange	DateRange	A DateRange object with initialized range.

Returns:

DateRange

isValidOffset

Checks if a given value is a valid offset.

Signature

public isValidOffset(offset: unknown): boolean

Parameters

Parameter	Type	Description
offset	unknown	The value to check.

Returns:

boolean - True if the value is an integer, false otherwise.

isValidRefDate

Checks if a given value is a valid reference date.

Signature

public isValidRefDate(refDate: unknown): boolean

Parameters

Parameter	Type	Description
refDate	unknown	The value to check.

Returns:

boolean - True if the value is a valid reference date, false otherwise.

isValidRefWeekday

Checks if a given value is a valid weekday (integer from 1 to 7).

Signature

public isValidRefWeekday(weekday: unknown): boolean

Parameters

Parameter	Type	Description
weekday	unknown	The value to check.

Returns:

boolean - True if the value is a valid weekday, false otherwise.

toDates

Returns an array of dates generated for the instance as JS Date objects.

Signature

public toDates(): Date[]

Parameters

The methods doesn't accept parameters.

Returns:

Date[] - An array of JavaScript Dates.

toDateTimes

Returns an array of dates generated for the instance as Luxon DateTime objects.

Signature

public toDateTimes(): DateTime[]

Parameters

The methods doesn't accept parameters.

Returns:

DateTime[] - An array of Luxon DateTimes.

Interfaces

RangeOptionsMonthExact interface

/**
 * Options for the DateRange `getMonthExact()` method.
 */
export type RangeOptionsMonthExact = Omit<RangeOptions, 'refWeekday'>;

RangeOptionsDays interface

/**
 * Options for the DateRange `getDays()` method.
 */
export type RangeOptionsDays = Omit<RangeOptions, 'refWeekday'> & {
  daysCount?: number;
};

DaysCount interface

interface DaysCount {
  /**
   * The number of days to be included in the range generated with `getDays` method.
   */
  daysCount?: number;
}

Offset interface

export interface Offset {
  /**
   * The number of days to add or remove from the beginning of the range.
   *
   * @remarks
   * If the specified offset is positive, dates are added. If negative, dates are removed.
   *
   * @defaultValue `0`
   *
   * @example
   * ```
   * // set the reference date
   * const refDate = new Date("2020-01-17");
   *
   * // with no offset 👈
   * const month1 = new DateRange().getMonthExact({ refDate });
   * // first date in range
   * month1.dateTimes[0]; // Jan 1, 2020
   * // last date in range
   * month1.dateTimes[month1.dateTimes.length - 1]; // Jan 31, 2020
   *
   * // with positive startOffset 👈
   * const month2 = new DateRange().getMonthExact({ refDate, startOffset: 5 });
   * // first date in range
   * month2.dateTimes[0]; // Dec 27, 2020
   * // last date in range (no changes)
   * month2.dateTimes[month2.dateTimes.length - 1]; // Jan 31, 2020
   *
   * // with negative startOffset 👈
   * const month3 = new DateRange().getMonthExact({ refDate, startOffset: -5 });
   * // first date in range
   * month3.dateTimes[0]; // Jan 6, 2020
   * // last date in range (no changes)
   * month3.dateTimes[month3.dateTimes.length - 1]; // Jan 31, 2020
   * ```
   */
  startOffset?: number;

  /**
   * The number of days to add or remove from the end of the range.
   *
   * @remarks
   * If the specified offset is positive, dates are added. If negative, dates are removed.
   *
   * @defaultValue `0`
   *
   * @example
   * ```
   * // set the reference date
   * const refDate = new Date("2020-01-17");
   *
   * // with no offset 👈
   * const month1 = new DateRange().getMonthExact({ refDate });
   * // first date in range
   * month1.dateTimes[0]; // Jan 1, 2020
   * // last date in range
   * month1.dateTimes[month1.dateTimes.length - 1]; // Jan 31, 2020
   *
   * // with positive endOffset 👈
   * const month2 = new DateRange().getMonthExact({ refDate, endOffset: 5 });
   * // first date in range (no changes)
   * month2.dateTimes[0]; // Jan 1, 2020
   * // last date in range
   * month2.dateTimes[month2.dateTimes.length - 1]; // Feb 5, 2020
   *
   * // with negative endOffset 👈
   * const month3 = new DateRange().getMonthExact({ refDate, endOffset: -5 });
   * // first date in range (no changes)
   * month3.dateTimes[0]; // Jan 1, 2020
   * // last date in range
   * month3.dateTimes[month3.dateTimes.length - 1]; // Jan 26, 2020
   * ```
   */
  endOffset?: number;
}

RefDate interface

interface RefDate {
  /**
   * The reference date to calculate the range.
   *
   * @remarks
   * Must be a Date object or luxon DateTime object.
   * Defaults to current time.
   *
   * @example
   * ```
   * // with DateTime
   * new DateRange().getWeek({ refDate: DateTime.fromISO('2023-05-15') });
   *
   * // with Date
   * new DateRange().getWeek({ refDate: new Date("2023-05-15") });
   * ```
   */
  refDate?: DateTime | Date;
}

RefWeekday interface

interface RefWeekday {
  /**
   * The reference weekday to start the range from.
   *
   * @remarks
   * Must be an integer from 1 (Monday) to 7 (Sunday).
   * Defaults to Monday.
   *
   *@example
   * ```
   * // with WEEKDAY enum. The range will start from Sunday
   * new DateRange().getWeek({refWeekday: WEEKDAY.Sunday });
   * // the equivalent with a number
   * new DateRange().getWeek({ refWeekday: 7 });
   * ```
   */
  refWeekday?: WEEKDAY;
}

OptionsDays interface

interface OptionsDays extends RefDate, DaysCount, Offset {}

OptionsWeek interface

interface OptionsWeek extends RefDate, RefWeekday, Offset {}

OptionsMonthExact interface

interface OptionsMonthExact extends RefDate, Offset {}

OptionsMonthExtended interface

interface OptionsMonthExtended extends RefDate, RefWeekday, Offset {}

Enums

RANGE_TYPE enum

/**
 * An enum that represents the type of date range that is generated and stored by DateRange instance.
 *
 * It corresponds to the range generator method used to create the range:
 * - `WEEK` for `getWeek`
 * - `MONTH-EXACT` for `getMonthExact`
 * - `MONTH-EXTENDED` for `getMonthExtended`
 * - `DAYS` for `getDays`
 */
export enum RANGE_TYPE {
  Week = 'WEEK',
  MonthExact = 'MONTH-EXACT',
  MonthExtended = 'MONTH-EXTENDED',
  Days = 'DAYS',
}

WEEKDAY enum

/**
 * An enum that represents the weekdays as numbers from 1 to 7.
 */
export enum WEEKDAY {
  Monday = 1,
  Tuesday = 2,
  Wednesday = 3,
  Thursday = 4,
  Friday = 5,
  Saturday = 6,
  Sunday = 7,
}

License

easy-date-range is licensed under the MIT license.

Name		Name	Last commit message	Last commit date
Latest commit History 141 Commits
.github/workflows		.github/workflows
.husky		.husky
src		src
tests		tests
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
commitlint.config.cjs		commitlint.config.cjs
package-lock.json		package-lock.json
package.json		package.json
readme.md		readme.md
release.config.cjs		release.config.cjs
rome.json		rome.json
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

License

jschepke/easy-date-range

Folders and files

Latest commit

History

Repository files navigation

easy-date-range

Features

Single reference date

Descriptive API

Easy to customize

Type-Safe

Date and time made easy with Luxon

More features to come

Installation

Usage

Basic usage

Customize the range

API

DateRange class

Properties

Methods

Range generators

Utilities

Date array getters

getDays

Signature

Parameters

Returns:

Examples

getMonthExact

Signature

Parameters

Returns:

Examples

getMonthExtended

Signature

Parameters

Returns:

Examples

getWeek

Signature

Parameters

Returns:

Examples

getNext

Signature

Parameters

Returns:

getPrevious

Signature

Parameters

Returns:

isValidOffset

Signature

Parameters

Returns:

isValidRefDate

Signature

Parameters

Returns:

isValidRefWeekday

Signature

Parameters

Returns:

toDates

Signature

Parameters

Returns:

toDateTimes

Signature

Parameters

Returns:

Interfaces

RangeOptionsMonthExact interface

RangeOptionsDays interface

DaysCount interface

Offset interface

RefDate interface

RefWeekday interface

Packages