0
# Moment Extensions
1

2
Utility methods and instance methods added to Moment.js for range-aware operations and integration.
3

4
## Capabilities
5

6
### extendMoment Function
7

8
Main function that extends a Moment.js instance with range functionality.
9

10
```javascript { .api }
11
/**
12
 * Extend a Moment.js instance with range functionality
13
 * @param moment - Moment.js constructor to extend
14
 * @returns Extended moment with range methods and DateRange constructor
15
 */
16
function extendMoment(moment: typeof moment): MomentRange;
17

18
interface MomentRange extends typeof moment {
19
  // All original moment functionality plus:
20
  range: typeof moment.range;
21
  rangeFromInterval: typeof moment.rangeFromInterval;
22
  rangeFromISOString: typeof moment.rangeFromISOString;
23
  isRange: typeof moment.isRange;
24
}
25
```
26

27
**Usage Examples:**
28

29
```javascript
30
import Moment from 'moment';
31
import { extendMoment } from 'moment-range';
32

33
// Extend moment with range functionality
34
const moment = extendMoment(Moment);
35

36
// Now moment has range methods
37
const range = moment.range('2024-01-01', '2024-01-31');
38
console.log(moment.isRange(range)); // true
39

40
// CommonJS usage
41
const Moment = require('moment');
42
const MomentRange = require('moment-range');
43
const moment = MomentRange.extendMoment(Moment);
44
```
45

46
### Static Range Creation Methods
47

48
Methods added to the moment static object for creating ranges.
49

50
```javascript { .api }
51
/**
52
 * Create a DateRange from various inputs
53
 * Added to moment static object by extendMoment
54
 */
55
moment.range(start: Date | Moment, end: Date | Moment): DateRange;
56
moment.range(range: [Date | Moment, Date | Moment]): DateRange;
57
moment.range(isoString: string): DateRange;
58
moment.range(interval: string): DateRange; // For current moment
59

60
/**
61
 * Create range from interval calculation
62
 */
63
moment.rangeFromInterval(interval: string, count?: number, date?: Moment): DateRange;
64

65
/**
66
 * Create range from ISO string with timezone preservation
67
 */
68
moment.rangeFromISOString(isoTimeInterval: string): DateRange;
69

70
/**
71
 * DEPRECATED: Alias for rangeFromISOString
72
 */
73
moment.parseZoneRange(isoTimeInterval: string): DateRange;
74
```
75

76
**Usage Examples:**
77

78
```javascript
79
const moment = extendMoment(Moment);
80

81
// All range creation methods now available on moment
82
const range1 = moment.range('2024-01-01', '2024-01-31');
83
const range2 = moment.rangeFromInterval('day', 7);
84
const range3 = moment.rangeFromISOString('2024-01-01T00:00:00Z/2024-01-31T23:59:59Z');
85

86
// Create range for current year
87
const thisYear = moment().range('year');
88
```
89

90
### Instance Range Method
91

92
Method added to moment instances for creating ranges.
93

94
```javascript { .api }
95
/**
96
 * Create a DateRange from this moment instance
97
 * Added to moment prototype by extendMoment
98
 * @param start - Optional start date (uses this moment if not provided)
99
 * @param end - Optional end date
100
 * @returns DateRange instance
101
 */
102
moment.fn.range(start?: Date | Moment, end?: Date | Moment): DateRange;
103

104
// Overloaded for interval usage
105
moment.fn.range(interval: string): DateRange;
106
```
107

108
**Usage Examples:**
109

110
```javascript
111
const moment = extendMoment(Moment);
112

113
// Create range from current moment
114
const now = moment();
115
const rangeFromNow = now.range(null, moment().add(1, 'week'));
116

117
// Create range for current day
118
const today = moment().range('day');
119

120
// Create range using current moment as start
121
const nextMonth = moment().range(moment(), moment().add(1, 'month'));
122
```
123

124
### isRange Static Method
125

126
Utility method to test if an object is a DateRange instance.
127

128
```javascript { .api }
129
/**
130
 * Check if an object is a DateRange instance
131
 * Added to moment static object by extendMoment
132
 * @param range - Object to test
133
 * @returns true if object is a DateRange
134
 */
135
moment.isRange(range: any): boolean;
136
```
137

138
**Usage Examples:**
139

140
```javascript
141
const moment = extendMoment(Moment);
142

143
const range = moment.range('2024-01-01', '2024-01-31');
144
const notRange = moment();
145
const fakeRange = { start: moment(), end: moment() };
146

147
console.log(moment.isRange(range));     // true
148
console.log(moment.isRange(notRange));  // false
149
console.log(moment.isRange(fakeRange)); // false
150
console.log(moment.isRange(null));      // false
151
console.log(moment.isRange(undefined)); // false
152
```
153

154
### within Instance Method
155

156
Method added to moment instances to test if they fall within a range.
157

158
```javascript { .api }
159
/**
160
 * Check if this moment is within the given DateRange
161
 * Added to moment prototype by extendMoment
162
 * @param range - DateRange to test against
163
 * @returns true if this moment is contained in the range
164
 */
165
moment.fn.within(range: DateRange): boolean;
166
```
167

168
**Usage Examples:**
169

170
```javascript
171
const moment = extendMoment(Moment);
172

173
const range = moment.range('2024-01-01', '2024-01-31');
174

175
// Test various moments
176
const jan15 = moment('2024-01-15');
177
const feb15 = moment('2024-02-15');
178
const jan01 = moment('2024-01-01'); // boundary
179
const jan31 = moment('2024-01-31'); // boundary
180

181
console.log(jan15.within(range)); // true
182
console.log(feb15.within(range)); // false
183
console.log(jan01.within(range)); // true (boundaries included)
184
console.log(jan31.within(range)); // true (boundaries included)
185

186
// Works with open-ended ranges
187
const openRange = moment.range(null, '2024-01-31');
188
const earlyDate = moment('2020-01-01');
189
console.log(earlyDate.within(openRange)); // true
190
```
191

192
### Constructor Reference
193

194
Access to DateRange constructor through moment.
195

196
```javascript { .api }
197
/**
198
 * Reference to DateRange constructor
199
 * Added to moment.range by extendMoment
200
 */
201
moment.range.constructor: typeof DateRange;
202
```
203

204
**Usage Examples:**
205

206
```javascript
207
const moment = extendMoment(Moment);
208

209
// Access DateRange constructor
210
const DateRangeClass = moment.range.constructor;
211
const range = new DateRangeClass('2024-01-01', '2024-01-31');
212

213
// Useful for type checking
214
console.log(range instanceof DateRangeClass); // true
215
console.log(range instanceof moment.range.constructor); // true
216
```
217

218
### Integration Patterns
219

220
Common patterns for integrating moment-range with existing codebases.
221

222
**Usage Examples:**
223

224
```javascript
225
// Plugin pattern - extend existing moment instance
226
import moment from 'moment'; // Your existing moment
227
import { extendMoment } from 'moment-range';
228

229
// Extend without replacing
230
const momentRange = extendMoment(moment);
231

232
// Factory pattern - create extended instance on demand
233
function createMomentWithRanges() {
234
  return extendMoment(require('moment'));
235
}
236

237
// Namespace pattern - keep ranges separate
238
import Moment from 'moment';
239
import { extendMoment, DateRange } from 'moment-range';
240

241
const moment = extendMoment(Moment);
242

243
export { moment, DateRange };
244

245
// Conditional extension - only extend if needed
246
let extendedMoment = null;
247
function getMomentWithRanges() {
248
  if (!extendedMoment) {
249
    extendedMoment = extendMoment(require('moment'));
250
  }
251
  return extendedMoment;
252
}
253
```
254

255
### Browser Integration
256

257
Browser-specific integration patterns.
258

259
**Usage Examples:**
260

261
```html
262
<!-- Load dependencies -->
263
<script src="moment.js"></script>
264
<script src="moment-range.js"></script>
265

266
<script>
267
  // Browser global usage
268
  const momentRange = window['moment-range'];
269
  momentRange.extendMoment(moment);
270
  
271
  // Now moment has range functionality
272
  const range = moment.range('2024-01-01', '2024-01-31');
273
  console.log(moment.isRange(range)); // true
274
</script>
275
```
276

277
```javascript
278
// AMD/RequireJS usage
279
define(['moment', 'moment-range'], function(moment, momentRange) {
280
  const extendedMoment = momentRange.extendMoment(moment);
281
  return extendedMoment;
282
});
283

284
// UMD detection
285
if (typeof module !== 'undefined' && module.exports) {
286
  // Node.js
287
  module.exports = extendMoment(require('moment'));
288
} else if (typeof define === 'function' && define.amd) {
289
  // AMD
290
  define(['moment'], function(moment) {
291
    return extendMoment(moment);
292
  });
293
} else {
294
  // Browser globals
295
  window.moment = extendMoment(window.moment);
296
}
297
```
298

299
## Types
300

301
```javascript { .api }
302
// Extended moment interface
303
interface MomentRange extends typeof moment {
304
  range: {
305
    (start: Date | Moment, end: Date | Moment): DateRange;
306
    (range: [Date | Moment, Date | Moment]): DateRange;
307
    (isoString: string): DateRange;
308
    (interval: string): DateRange;
309
    constructor: typeof DateRange;
310
  };
311
  rangeFromInterval(interval: string, count?: number, date?: Moment): DateRange;
312
  rangeFromISOString(isoTimeInterval: string): DateRange;
313
  parseZoneRange(isoTimeInterval: string): DateRange; // DEPRECATED
314
  isRange(range: any): boolean;
315
}
316

317
// Extended moment instance interface
318
declare module 'moment' {
319
  interface Moment {
320
    within(range: DateRange): boolean;
321
    range(start?: Date | Moment, end?: Date | Moment): DateRange;
322
    range(interval: string): DateRange;
323
  }
324
}
325
```