0
# Range Querying
1

2
Query relationships between ranges and dates including containment, overlap, adjacency, and intersection operations.
3

4
## Capabilities
5

6
### Contains
7

8
Test if a range contains a date, moment, or another range.
9

10
```javascript { .api }
11
/**
12
 * Check if this range contains a date, moment, or another range
13
 * @param other - Date, moment, or range to test
14
 * @param options - Options for boundary inclusion/exclusion
15
 * @returns true if other is contained within this range
16
 */
17
contains(other: Date | Moment | DateRange, options?: ContainsOptions): boolean;
18

19
interface ContainsOptions {
20
  excludeStart?: boolean; // Exclude start boundary from containment check
21
  excludeEnd?: boolean;   // Exclude end boundary from containment check
22
  exclusive?: boolean;    // DEPRECATED: Use excludeStart and excludeEnd
23
}
24
```
25

26
**Usage Examples:**
27

28
```javascript
29
const range = moment.range('2024-01-01', '2024-01-31');
30

31
// Test date containment
32
const testDate = moment('2024-01-15');
33
console.log(range.contains(testDate)); // true
34

35
// Test boundary dates
36
const startDate = moment('2024-01-01');
37
console.log(range.contains(startDate)); // true
38
console.log(range.contains(startDate, { excludeStart: true })); // false
39

40
// Test range containment
41
const subRange = moment.range('2024-01-10', '2024-01-20');
42
console.log(range.contains(subRange)); // true
43

44
// Test with boundary exclusion
45
const boundaryRange = moment.range('2024-01-01', '2024-01-15');
46
console.log(range.contains(boundaryRange, { excludeStart: true })); // false
47
```
48

49
### Overlaps
50

51
Test if two ranges overlap or are adjacent.
52

53
```javascript { .api }
54
/**
55
 * Check if this range overlaps with another range
56
 * @param other - Range to test for overlap
57
 * @param options - Options for adjacency consideration
58
 * @returns true if ranges overlap or are adjacent (when specified)
59
 */
60
overlaps(other: DateRange, options?: OverlapOptions): boolean;
61

62
interface OverlapOptions {
63
  adjacent?: boolean; // Consider adjacent ranges as overlapping
64
}
65
```
66

67
**Usage Examples:**
68

69
```javascript
70
const range1 = moment.range('2024-01-01', '2024-01-15');
71
const range2 = moment.range('2024-01-10', '2024-01-25');
72

73
// Test overlap
74
console.log(range1.overlaps(range2)); // true
75

76
// Test non-overlapping
77
const range3 = moment.range('2024-01-20', '2024-01-31');
78
console.log(range1.overlaps(range3)); // false
79

80
// Test adjacent ranges
81
const range4 = moment.range('2024-01-16', '2024-01-31');
82
console.log(range1.overlaps(range4)); // false
83
console.log(range1.overlaps(range4, { adjacent: true })); // true
84
```
85

86
### Adjacent
87

88
Test if two ranges are adjacent (touching but not overlapping).
89

90
```javascript { .api }
91
/**
92
 * Check if this range is adjacent to another range
93
 * Adjacent means ranges touch at exactly one point but don't overlap
94
 * @param other - Range to test for adjacency
95
 * @returns true if ranges are adjacent
96
 */
97
adjacent(other: DateRange): boolean;
98
```
99

100
**Usage Examples:**
101

102
```javascript
103
const range1 = moment.range('2024-01-01', '2024-01-15');
104
const range2 = moment.range('2024-01-16', '2024-01-31');
105

106
console.log(range1.adjacent(range2)); // true
107

108
const range3 = moment.range('2024-01-14', '2024-01-20');
109
console.log(range1.adjacent(range3)); // false (overlapping)
110

111
const range4 = moment.range('2024-01-20', '2024-01-31');
112
console.log(range1.adjacent(range4)); // false (gap between ranges)
113
```
114

115
### Intersect
116

117
Get the intersection of two ranges.
118

119
```javascript { .api }
120
/**
121
 * Get the intersection of this range with another range
122
 * @param other - Range to intersect with
123
 * @returns DateRange representing intersection, or null if no intersection
124
 */
125
intersect(other: DateRange): DateRange | null;
126
```
127

128
**Usage Examples:**
129

130
```javascript
131
const range1 = moment.range('2024-01-01', '2024-01-15');
132
const range2 = moment.range('2024-01-10', '2024-01-25');
133

134
// Get intersection
135
const intersection = range1.intersect(range2);
136
console.log(intersection.toString()); // "2024-01-10T00:00:00Z/2024-01-15T23:59:59Z"
137

138
// No intersection case
139
const range3 = moment.range('2024-01-20', '2024-01-31');
140
const noIntersection = range1.intersect(range3);
141
console.log(noIntersection); // null
142

143
// Zero-length range intersection
144
const point1 = moment.range('2024-01-10', '2024-01-10');
145
const point2 = moment.range('2024-01-10', '2024-01-10');
146
console.log(point1.intersect(point2)); // null (zero-length intersections return null)
147
```
148

149
### Equality
150

151
Test if two ranges are exactly equal.
152

153
```javascript { .api }
154
/**
155
 * Check if this range is exactly equal to another range
156
 * @param other - Range to compare with
157
 * @returns true if start and end moments are identical
158
 */
159
isEqual(other: DateRange): boolean;
160

161
/**
162
 * Alias for isEqual
163
 * @param other - Range to compare with  
164
 * @returns true if ranges are equal
165
 */
166
isSame(other: DateRange): boolean;
167
```
168

169
**Usage Examples:**
170

171
```javascript
172
const range1 = moment.range('2024-01-01', '2024-01-31');
173
const range2 = moment.range('2024-01-01', '2024-01-31');
174
const range3 = moment.range('2024-01-01', '2024-01-30');
175

176
console.log(range1.isEqual(range2)); // true
177
console.log(range1.isSame(range2));  // true (alias)
178
console.log(range1.isEqual(range3)); // false
179
```
180

181
### Within (Moment Extension)
182

183
Test if a moment is within a range (added to Moment instances).
184

185
```javascript { .api }
186
/**
187
 * Check if this moment is within the given range
188
 * @param range - DateRange to test against
189
 * @returns true if this moment is contained in the range
190
 */
191
moment.fn.within(range: DateRange): boolean;
192
```
193

194
**Usage Examples:**
195

196
```javascript
197
const range = moment.range('2024-01-01', '2024-01-31');
198
const testMoment = moment('2024-01-15');
199

200
console.log(testMoment.within(range)); // true
201

202
const outsideMoment = moment('2024-02-15');
203
console.log(outsideMoment.within(range)); // false
204
```
205

206
### isRange (Static Utility)
207

208
Test if an object is a DateRange instance.
209

210
```javascript { .api }
211
/**
212
 * Check if an object is a DateRange instance
213
 * @param range - Object to test
214
 * @returns true if object is a DateRange
215
 */
216
function moment.isRange(range: any): boolean;
217
```
218

219
**Usage Examples:**
220

221
```javascript
222
const range = moment.range('2024-01-01', '2024-01-31');
223
const notRange = { start: moment(), end: moment() };
224

225
console.log(moment.isRange(range)); // true
226
console.log(moment.isRange(notRange)); // false
227
console.log(moment.isRange(null)); // false
228
```
229

230
## Types
231

232
```javascript { .api }
233
interface ContainsOptions {
234
  excludeStart?: boolean;
235
  excludeEnd?: boolean;
236
  exclusive?: boolean; // DEPRECATED in favor of excludeStart/excludeEnd
237
}
238

239
interface OverlapOptions {
240
  adjacent?: boolean;
241
}
242
```