Date Range Plugin
Date Range Plugin — Chronos Plugin Documentation.
About Date Range Plugin
Date range plugin is a plugin that adds date range related functionalities to Chronos.
Import & Usage
Import
To use the Date Range Plugin, import it first:
import { Chronos, chronos } from "chronos-date";
import { dateRangePlugin } from 'chronos-date/plugins/dateRangePlugin';Register
Now you can use the plugin's methods:
// Register the plugin globally
Chronos.use(dateRangePlugin);
// or
chronos.use(dateRangePlugin);
// or
Chronos.register(dateRangePlugin);
// or
chronos.register(dateRangePlugin);Usage
Example usage of the dateRangePlugin:
const c = new Chronos();
const datesInRange = c.getDatesInRange({
from: '2025-01-01',
to: '2025-01-31',
skipDays: ['Saturday', 'Sunday'] // or [6, 0]
});
console.log(datesInRange);Example Usage
playground.ts
Overview
The dateRangePlugin adds comprehensive date range functionalities to Chronos, enabling:
- Generating an array of ISO date strings within a specified date range
- Generating an array of
Chronosinstances ifformatis set to'chronos'
Methods Added by the Plugin
Note
All these methods are provided by dateRangePlugin. You must register it using Chronos.use(dateRangePlugin) before calling them. Once registered, all Chronos instances will have access to these methods.
| Method | Description | Returns |
|---|---|---|
getDatesInRange | Generate an array of ISO date strings or Chronos instances in the range. | (string | Chronos)[] |
API Reference
getDatesInRange()
Generate an array of ISO date strings within a specified date range.
Signatures
getDatesInRange<F extends ISODateFormat | 'chronos' = 'local'>(options?: RangeWithDates<F>): DateRangeResult<F>Overview
Generates dates between two points in time with:
- Fixed date ranges (
from/to) or relative ranges (span/unit) - Weekday filtering (
skipDays/onlyDays) - Format control (
local/utc/chronos) - Date boundary rounding
Parameters
options (Optional)
Configuration object accepting either fixed or relative range parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
from | ChronosInput | Current date | Start date (inclusive) |
to | ChronosInput | 4 weeks from from | End date (inclusive) |
span | number | 4 | Number of time units |
unit | 'year'|'month'|'week'|'day' | 'week' | Unit of time for relative ranges |
format | 'local'|'utc'|'chronos' | 'local' | Output format for ISO strings or Chronos instances |
skipDays | WeekDay[] | Enumerate<7>[] | [] | Weekdays to exclude (e.g. ['Sunday', 'Saturday'] or [0, 6]) |
onlyDays | WeekDay[] | Enumerate<7>[] | [] | Include these (e.g. ['Monday'] or [1], overrides skipDays) |
roundDate | boolean | false | Round dates to start of day |
interface RangeWithDates {
/** Start date of the range (inclusive). Defaults to the current `Chronos` instance if not provided. */
from?: ChronosInput;
/** End date of the range (inclusive). Defaults to **4 weeks from the current `Chronos` instance** if not provided. */
to?: ChronosInput;
/** Output format. Default: 'local' */
format?: 'local' | 'utc' | 'chronos';
/**
* An array of weekdays to exclude from the date range.
* - Accepts either weekday names (e.g., `'Saturday'`, `'Sunday'`) or numeric indices (0 for Sunday to 6 for Saturday).
* - Ignored if `onlyDays` is provided.
*/
skipDays?: Array<WeekDay> | Array<Enumerate<7>>;
/**
* An array of weekdays to explicitly include in the date range.
* - Accepts either weekday names (e.g., `'Monday'`, `'Wednesday'`) or numeric indices (0 for Sunday to 6 for Saturday).
* - When provided, this overrides `skipDays` and includes only the specified days.
*/
onlyDays?: Array<WeekDay> | Array<Enumerate<7>>;
/** Round dates to start of day. Default: false */
roundDate?: boolean;
}Return Value
DateRangeResult<F> - Array of ISO date strings or Chronos instances based on the format option.
Tips
- When
formatischronos, the method returns an array ofChronosinstances. - Thus you can call any method of
Chronoson each element of the returned array. - Note: Each
Chronosinstance will be in the same time zone as the original instance.
Behavior
- Fixed ranges: Includes all dates between
fromandto(inclusive) - Relative ranges: Generates dates forward from current date
onlyDaystakes precedence overskipDayswhen both are provided- Defaults to
4-week rangewhen no options provided
Note
- When using
Chronosinstances forfromand/orto, ensure both are created in the same time zone to avoid mismatched boundaries. - Mixing zones may shift the interpreted start or end by several hours, which can cause the range to include or exclude incorrect weekdays.
Examples
import { dateRangePlugin } from 'chronos-date/plugins/dateRangePlugin';
Chronos.use(dateRangePlugin);
// Get all dates in January 2025
new Chronos().getDatesInRange({
from: '2025-01-01',
to: '2025-01-31',
skipDays: ['Saturday', 'Sunday'] // or [6, 0]
});
// Include only Fridays in a full month range
const now = new Chronos();
now.getDatesInRange({
from: now.startOf('month'),
to: now.endOf('month'),
onlyDays: ['Friday'],
roundDate: true
});
// Include only Mondays and Wednesdays in the range
new Chronos().getDatesInRange({
from: '2025-07-01',
to: '2025-07-15',
onlyDays: ['Monday', 'Wednesday']
});Notes
Important
- Weekday names must exactly match:
'Monday','Tuesday', etc. (case-sensitive) - When using
onlyDays, all other days are excluded regardless ofskipDays
Similar Static Method
Last updated: Sat, Jun 27, 2026 03:21:48PM (UTC)