0
# Range Iteration
1

2
Iterate over ranges using various time intervals with customizable options for step size and boundary inclusion using ES6 iterator protocol.
3

4
## Capabilities
5

6
### By Interval (Forward)
7

8
Iterate forward through the range by a specified time interval.
9

10
```javascript { .api }
11
/**
12
 * Create forward iterator over range by time interval
13
 * @param interval - Time unit to iterate by
14
 * @param options - Iteration options
15
 * @returns Iterable that yields Moment objects
16
 */
17
by(interval: IntervalUnit, options?: IterationOptions): Iterable<Moment>;
18

19
interface IterationOptions {
20
  excludeEnd?: boolean; // Exclude the end boundary from iteration
21
  step?: number;        // Step size (default: 1)
22
  exclusive?: boolean;  // DEPRECATED: Use excludeEnd instead
23
}
24

25
type IntervalUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
26
```
27

28
**Usage Examples:**
29

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

33
// Basic iteration by day
34
for (const day of range.by('day')) {
35
  console.log(day.format('YYYY-MM-DD'));
36
}
37
// Output: 2024-01-01, 2024-01-02, 2024-01-03, 2024-01-04, 2024-01-05
38

39
// Exclude end boundary
40
for (const day of range.by('day', { excludeEnd: true })) {
41
  console.log(day.format('YYYY-MM-DD'));
42
}
43
// Output: 2024-01-01, 2024-01-02, 2024-01-03, 2024-01-04
44

45
// Step by 2 days
46
for (const day of range.by('day', { step: 2 })) {
47
  console.log(day.format('YYYY-MM-DD'));
48
}
49
// Output: 2024-01-01, 2024-01-03, 2024-01-05
50

51
// Convert to array
52
const days = Array.from(range.by('day'));
53
console.log(days.length); // 5
54

55
// Iterate by hours
56
const hourRange = moment.range('2024-01-01T00:00:00', '2024-01-01T06:00:00');
57
for (const hour of hourRange.by('hour')) {
58
  console.log(hour.format('HH:mm'));
59
}
60
// Output: 00:00, 01:00, 02:00, 03:00, 04:00, 05:00, 06:00
61
```
62

63
### By Range (Forward)
64

65
Iterate forward through the range using another range as the step interval.
66

67
```javascript { .api }
68
/**
69
 * Create forward iterator over range using another range as step interval  
70
 * @param interval - DateRange defining the step size
71
 * @param options - Iteration options
72
 * @returns Iterable that yields Moment objects
73
 */
74
byRange(interval: DateRange, options?: IterationOptions): Iterable<Moment>;
75
```
76

77
**Usage Examples:**
78

79
```javascript
80
const range = moment.range('2024-01-01', '2024-01-31');
81

82
// Step by week intervals
83
const weekInterval = moment.range('2024-01-01', '2024-01-07'); // 7-day range
84
for (const start of range.byRange(weekInterval)) {
85
  console.log(start.format('YYYY-MM-DD'));
86
}
87
// Output: 2024-01-01, 2024-01-08, 2024-01-15, 2024-01-22, 2024-01-29
88

89
// Step by 3-day intervals
90
const threeDayInterval = moment.range('2024-01-01', '2024-01-03');
91
for (const start of range.byRange(threeDayInterval, { step: 2 })) {
92
  console.log(start.format('YYYY-MM-DD'));
93
}
94
// Output: Every 6 days (3-day interval * step 2)
95

96
// Custom business day range
97
const businessWeek = moment.range('2024-01-01', '2024-01-05'); // Mon-Fri
98
for (const weekStart of range.byRange(businessWeek)) {
99
  console.log(`Week starting: ${weekStart.format('YYYY-MM-DD')}`);
100
}
101
```
102

103
### Reverse By Interval
104

105
Iterate backward through the range by a specified time interval.
106

107
```javascript { .api }
108
/**
109
 * Create reverse iterator over range by time interval
110
 * @param interval - Time unit to iterate by
111
 * @param options - Reverse iteration options
112
 * @returns Iterable that yields Moment objects in reverse order
113
 */
114
reverseBy(interval: IntervalUnit, options?: ReverseIterationOptions): Iterable<Moment>;
115

116
interface ReverseIterationOptions {
117
  excludeStart?: boolean; // Exclude the start boundary from iteration
118
  step?: number;          // Step size (default: 1)
119
  exclusive?: boolean;    // DEPRECATED: Use excludeStart instead
120
}
121
```
122

123
**Usage Examples:**
124

125
```javascript
126
const range = moment.range('2024-01-01', '2024-01-05');
127

128
// Basic reverse iteration by day
129
for (const day of range.reverseBy('day')) {
130
  console.log(day.format('YYYY-MM-DD'));
131
}
132
// Output: 2024-01-05, 2024-01-04, 2024-01-03, 2024-01-02, 2024-01-01
133

134
// Exclude start boundary
135
for (const day of range.reverseBy('day', { excludeStart: true })) {
136
  console.log(day.format('YYYY-MM-DD'));
137
}
138
// Output: 2024-01-05, 2024-01-04, 2024-01-03, 2024-01-02
139

140
// Step by 2 days backwards
141
for (const day of range.reverseBy('day', { step: 2 })) {
142
  console.log(day.format('YYYY-MM-DD'));
143
}
144
// Output: 2024-01-05, 2024-01-03, 2024-01-01
145

146
// Reverse iterate by hours
147
const hourRange = moment.range('2024-01-01T00:00:00', '2024-01-01T06:00:00');
148
for (const hour of hourRange.reverseBy('hour')) {
149
  console.log(hour.format('HH:mm'));
150
}
151
// Output: 06:00, 05:00, 04:00, 03:00, 02:00, 01:00, 00:00
152
```
153

154
### Reverse By Range
155

156
Iterate backward through the range using another range as the step interval.
157

158
```javascript { .api }
159
/**
160
 * Create reverse iterator over range using another range as step interval
161
 * @param interval - DateRange defining the step size
162
 * @param options - Reverse iteration options  
163
 * @returns Iterable that yields Moment objects in reverse order
164
 */
165
reverseByRange(interval: DateRange, options?: ReverseIterationOptions): Iterable<Moment>;
166
```
167

168
**Usage Examples:**
169

170
```javascript
171
const range = moment.range('2024-01-01', '2024-01-31');
172

173
// Reverse step by week intervals
174
const weekInterval = moment.range('2024-01-01', '2024-01-07');
175
for (const start of range.reverseByRange(weekInterval)) {
176
  console.log(start.format('YYYY-MM-DD'));
177
}
178
// Output: 2024-01-31, 2024-01-24, 2024-01-17, 2024-01-10, 2024-01-03
179

180
// Combine with array methods
181
const monthStarts = Array.from(range.reverseByRange(weekInterval))
182
  .map(moment => moment.format('YYYY-MM-DD'))
183
  .slice(0, 3); // Take first 3
184
console.log(monthStarts); // Last 3 week starts in reverse order
185
```
186

187
### Iteration Helpers
188

189
Utility methods for working with iterators.
190

191
**Usage Examples:**
192

193
```javascript
194
const range = moment.range('2024-01-01', '2024-01-10');
195

196
// Convert iterator to array
197
const allDays = Array.from(range.by('day'));
198
console.log(allDays.length); // 10
199

200
// Use with array methods
201
const weekends = Array.from(range.by('day'))
202
  .filter(day => day.day() === 0 || day.day() === 6) // Sunday or Saturday
203
  .map(day => day.format('YYYY-MM-DD'));
204

205
// Count iterations without storing
206
let count = 0;
207
for (const day of range.by('day')) {
208
  count++;
209
}
210
console.log(`Range spans ${count} days`);
211

212
// Find specific dates
213
const businessDays = Array.from(range.by('day'))
214
  .filter(day => day.day() >= 1 && day.day() <= 5); // Monday-Friday
215

216
// Break early from iteration
217
for (const day of range.by('day')) {
218
  console.log(day.format('YYYY-MM-DD'));
219
  if (day.format('DD') === '05') break; // Stop at 5th day
220
}
221
```
222

223
### Edge Cases and Performance
224

225
Handle special cases and optimize performance.
226

227
**Usage Examples:**
228

229
```javascript
230
// Infinite ranges
231
const infiniteRange = moment.range(null, null);
232
// Iteration will throw or return empty iterator - check implementation
233

234
// Zero-length ranges
235
const zeroRange = moment.range('2024-01-01', '2024-01-01');
236
const zeroIterations = Array.from(zeroRange.by('day'));
237
console.log(zeroIterations.length); // 1 (includes the single day)
238

239
// Large step sizes
240
const yearRange = moment.range('2020-01-01', '2030-01-01');
241
for (const year of yearRange.by('year', { step: 2 })) {
242
  console.log(year.format('YYYY')); // Every 2 years
243
}
244

245
// Very small intervals
246
const minuteRange = moment.range('2024-01-01T00:00:00', '2024-01-01T01:00:00');
247
const minutes = Array.from(minuteRange.by('minute'));
248
console.log(minutes.length); // 61 minutes (includes both boundaries)
249
```
250

251
## Types
252

253
```javascript { .api }
254
interface IterationOptions {
255
  excludeEnd?: boolean;
256
  step?: number;
257
  exclusive?: boolean; // DEPRECATED
258
}
259

260
interface ReverseIterationOptions {
261
  excludeStart?: boolean;
262
  step?: number;
263
  exclusive?: boolean; // DEPRECATED
264
}
265

266
type IntervalUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';
267

268
// Iterator interface (ES6 Standard)
269
interface Iterator<T> {
270
  next(): IteratorResult<T>;
271
}
272

273
interface IteratorResult<T> {
274
  done: boolean;
275
  value: T;
276
}
277

278
interface Iterable<T> {
279
  [Symbol.iterator](): Iterator<T>;
280
}
281
```