0
# Date Range Creation
1

2
Create date ranges from various input formats including dates, moments, arrays, and ISO 8601 interval strings with full timezone support.
3

4
## Capabilities
5

6
### moment.range() Static Method
7

8
Creates a DateRange from various input formats.
9

10
```javascript { .api }
11
/**
12
 * Create a date range from start and end dates/moments
13
 * @param start - Start date or moment
14
 * @param end - End date or moment
15
 * @returns DateRange instance
16
 */
17
function moment.range(start: Date | Moment, end: Date | Moment): DateRange;
18

19
/**
20
 * Create a date range from an array of two dates/moments
21
 * @param range - Array containing start and end dates/moments
22
 * @returns DateRange instance
23
 */
24
function moment.range(range: [Date | Moment, Date | Moment]): DateRange;
25

26
/**
27
 * Create a date range from an ISO 8601 interval string
28
 * @param isoString - ISO 8601 interval string (e.g., "2024-01-01/2024-01-31")
29
 * @returns DateRange instance
30
 */
31
function moment.range(isoString: string): DateRange;
32

33
/**
34
 * Create a range for a specific time unit relative to current moment
35
 * @param interval - Time unit (year, month, week, day, hour, minute, second)
36
 * @returns DateRange spanning the entire interval
37
 */
38
function moment.range(interval: string): DateRange;
39
```
40

41
**Usage Examples:**
42

43
```javascript
44
import Moment from 'moment';
45
import { extendMoment } from 'moment-range';
46

47
const moment = extendMoment(Moment);
48

49
// From dates
50
const range1 = moment.range(new Date('2024-01-01'), new Date('2024-01-31'));
51

52
// From moments
53
const start = moment('2024-01-01');
54
const end = moment('2024-01-31');
55
const range2 = moment.range(start, end);
56

57
// From array
58
const range3 = moment.range([start, end]);
59

60
// From ISO string
61
const range4 = moment.range('2024-01-01/2024-01-31');
62

63
// For current year
64
const thisYear = moment().range('year');
65
```
66

67
### moment.rangeFromInterval()
68

69
Creates a range from a base date by adding a specified interval.
70

71
```javascript { .api }
72
/**
73
 * Create a date range between a date and a specified interval from that date
74
 * @param interval - The type of interval (year, month, day, etc.)
75
 * @param count - The number of intervals (positive or negative, default: 1)
76
 * @param date - The base date (default: current moment)
77
 * @returns DateRange spanning from date to date + (count * interval)
78
 */
79
function moment.rangeFromInterval(
80
  interval: string, 
81
  count?: number, 
82
  date?: Date | Moment
83
): DateRange;
84
```
85

86
**Usage Examples:**
87

88
```javascript
89
// Next 7 days from now
90
const nextWeek = moment.rangeFromInterval('day', 7);
91

92
// Previous 3 months from specific date
93
const pastQuarter = moment.rangeFromInterval('month', -3, moment('2024-06-01'));
94

95
// Next hour from now
96
const nextHour = moment.rangeFromInterval('hour', 1);
97
```
98

99
### moment.rangeFromISOString()
100

101
Creates a range from an ISO 8601 interval string with timezone preservation.
102

103
```javascript { .api }
104
/**
105
 * Create a date range from ISO 8601 interval string preserving timezones
106
 * Uses moment.parseZone to maintain timezone information on both endpoints
107
 * @param isoTimeInterval - ISO 8601 interval string with timezone info
108
 * @returns DateRange with timezone-aware start and end moments
109
 */
110
function moment.rangeFromISOString(isoTimeInterval: string): DateRange;
111
```
112

113
**Usage Examples:**
114

115
```javascript
116
// With timezone information preserved
117
const tzRange = moment.rangeFromISOString('2024-01-01T00:00:00-05:00/2024-01-31T23:59:59-05:00');
118

119
// Works with different timezone formats
120
const utcRange = moment.rangeFromISOString('2024-01-01T00:00:00Z/2024-01-31T23:59:59Z');
121
```
122

123
### DateRange Constructor
124

125
Direct constructor for creating DateRange instances.
126

127
```javascript { .api }
128
/**
129
 * DateRange constructor with flexible input handling
130
 * @param start - Start date/moment, array of dates, ISO string, or undefined for infinite start
131
 * @param end - End date/moment, or undefined for infinite end (optional if start is array or ISO string)
132
 */
133
class DateRange {
134
  constructor(start: Date | Moment, end: Date | Moment);
135
  constructor(range: [Date | Moment, Date | Moment]);
136
  constructor(isoString: string);
137
  constructor(); // Creates infinite range (start: -∞, end: +∞)
138
  constructor(start: Date | Moment | null, end: Date | Moment | null); // Null creates open-ended ranges
139
}
140
```
141

142
**Usage Examples:**
143

144
```javascript
145
import { DateRange } from 'moment-range';
146

147
// Direct construction
148
const range1 = new DateRange(moment('2024-01-01'), moment('2024-01-31'));
149

150
// From array
151
const range2 = new DateRange([new Date('2024-01-01'), new Date('2024-01-31')]);
152

153
// From ISO string
154
const range3 = new DateRange('2024-01-01/2024-01-31');
155

156
// Infinite range (open-ended)
157
const infiniteRange = new DateRange();
158

159
// Open-ended ranges with null boundaries
160
const fromStart = new DateRange(null, moment('2024-01-31')); // Everything before date
161
const toEnd = new DateRange(moment('2024-01-01'), null);     // Everything after date
162
```
163

164
### Open-ended Ranges
165

166
Create ranges with infinite start or end points for unbounded queries.
167

168
```javascript { .api }
169
// Range with no start (everything before end date)
170
const beforeDate = moment.range(null, '2024-01-31');
171

172
// Range with no end (everything after start date)  
173
const afterDate = moment.range('2024-01-01', null);
174
```
175

176
**Usage Examples:**
177

178
```javascript
179
// Everything before 2024
180
const beforeYear = moment.range(null, '2024-01-01');
181

182
// Everything after today
183
const afterToday = moment.range(moment(), null);
184

185
// Check if date is in unbounded range
186
const testDate = moment('2023-06-15');
187
console.log(testDate.within(beforeYear)); // true
188
```
189

190
## Types
191

192
```javascript { .api }
193
interface DateRange {
194
  start: Moment; // Start moment of range (may be -Infinity for open start)
195
  end: Moment;   // End moment of range (may be +Infinity for open end)
196
}
197

198
// Valid interval strings for range creation
199
type IntervalUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
200
```