0
# moment-range
1

2
moment-range is a JavaScript/TypeScript library that extends Moment.js with comprehensive date range functionality. It provides a powerful DateRange class and extends Moment.js with range-specific methods, enabling creation, manipulation, querying, and iteration of date ranges with full timezone support.
3

4
## Package Information
5

6
- **Package Name**: moment-range
7
- **Package Type**: npm
8
- **Language**: JavaScript/TypeScript
9
- **Installation**: `npm install moment-range`
10
- **Peer Dependencies**: `moment >= 2.0.0`
11

12
## Core Imports
13

14
```javascript
15
import Moment from 'moment';
16
import { extendMoment, DateRange } from 'moment-range';
17

18
const moment = extendMoment(Moment);
19
```
20

21
For CommonJS:
22

23
```javascript
24
const Moment = require('moment');
25
const MomentRange = require('moment-range');
26

27
const moment = MomentRange.extendMoment(Moment);
28
```
29

30
Browser usage:
31

32
```html
33
<script src="moment.js"></script>
34
<script src="moment-range.js"></script>
35
<script>
36
  window['moment-range'].extendMoment(moment);
37
</script>
38
```
39

40
## Basic Usage
41

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

46
const moment = extendMoment(Moment);
47

48
// Create a date range
49
const start = moment('2024-01-01');
50
const end = moment('2024-01-31');
51
const range = moment.range(start, end);
52

53
// Check if a date is within the range
54
const testDate = moment('2024-01-15');
55
console.log(testDate.within(range)); // true
56

57
// Iterate over range by day
58
for (const day of range.by('day')) {
59
  console.log(day.format('YYYY-MM-DD'));
60
}
61

62
// Check if ranges overlap
63
const otherRange = moment.range('2024-01-15', '2024-02-15');
64
console.log(range.overlaps(otherRange)); // true
65
```
66

67
## Architecture
68

69
moment-range is built around several key components:
70

71
- **DateRange Class**: Core class providing range operations, iteration, and manipulation methods
72
- **Moment Extensions**: Static methods added to moment for range creation and utility functions
73
- **Instance Extensions**: Methods added to moment instances for range-aware operations
74
- **Iterator Protocol**: ES6 Symbol.iterator support for efficient range iteration
75
- **Timezone Support**: Full timezone awareness through moment.parseZone integration
76

77
## Capabilities
78

79
### Date Range Creation
80

81
Create date ranges from various input formats including dates, moments, arrays, and ISO 8601 interval strings.
82

83
```javascript { .api }
84
// Static creation methods
85
function moment.range(start: Date | Moment, end: Date | Moment): DateRange;
86
function moment.range(range: [Date | Moment, Date | Moment]): DateRange;
87
function moment.range(isoString: string): DateRange;
88
function moment.rangeFromInterval(interval: string, count?: number, date?: Moment): DateRange;
89
function moment.rangeFromISOString(isoString: string): DateRange;
90

91
// Constructor
92
class DateRange {
93
  constructor(start: Date | Moment, end: Date | Moment);
94
  constructor(range: [Date | Moment, Date | Moment]);
95
  constructor(isoString: string);
96
}
97
```
98

99
[Range Creation](./range-creation.md)
100

101
### Range Querying
102

103
Query relationships between ranges and dates including containment, overlap, adjacency, and intersection operations.
104

105
```javascript { .api }
106
// Range relationship methods
107
adjacent(other: DateRange): boolean;
108
contains(other: Date | Moment | DateRange, options?: ContainsOptions): boolean;
109
overlaps(other: DateRange, options?: OverlapOptions): boolean;
110
intersect(other: DateRange): DateRange | null;
111
isEqual(other: DateRange): boolean;
112

113
interface ContainsOptions {
114
  excludeStart?: boolean;
115
  excludeEnd?: boolean;
116
}
117

118
interface OverlapOptions {
119
  adjacent?: boolean;
120
}
121
```
122

123
[Range Querying](./range-querying.md)
124

125
### Range Manipulation
126

127
Manipulate ranges through addition, subtraction, cloning, and boundary snapping operations.
128

129
```javascript { .api }
130
// Range manipulation methods
131
add(other: DateRange, options?: { adjacent?: boolean }): DateRange | null;
132
subtract(other: DateRange): DateRange[];
133
clone(): DateRange;
134
snapTo(interval: string): DateRange;
135
center(): Moment;
136
```
137

138
[Range Manipulation](./range-manipulation.md)
139

140
### Range Iteration
141

142
Iterate over ranges using various time intervals with customizable options for step size and boundary inclusion.
143

144
```javascript { .api }
145
// Forward iteration
146
by(interval: string, options?: IterationOptions): Iterable<Moment>;
147
byRange(interval: DateRange, options?: IterationOptions): Iterable<Moment>;
148

149
// Reverse iteration
150
reverseBy(interval: string, options?: ReverseIterationOptions): Iterable<Moment>;
151
reverseByRange(interval: DateRange, options?: ReverseIterationOptions): Iterable<Moment>;
152

153
interface IterationOptions {
154
  excludeEnd?: boolean;
155
  step?: number;
156
}
157

158
interface ReverseIterationOptions {
159
  excludeStart?: boolean;
160
  step?: number;
161
}
162
```
163

164
[Range Iteration](./range-iteration.md)
165

166
### Moment Extensions
167

168
Utility methods and instance methods added to Moment.js for range-aware operations.
169

170
```javascript { .api }
171
// Static utility methods
172
function moment.isRange(range: any): boolean;
173

174
// Instance methods
175
function moment.fn.within(range: DateRange): boolean;
176
function moment.fn.range(start?: Date | Moment, end?: Date | Moment): DateRange;
177
```
178

179
[Moment Extensions](./moment-extensions.md)
180

181
## Types
182

183
```javascript { .api }
184
class DateRange {
185
  start: Moment;
186
  end: Moment;
187
  
188
  // Core methods
189
  diff(unit?: string, precise?: boolean): number;
190
  duration(unit?: string, precise?: boolean): number;
191
  valueOf(): number;
192
  toString(): string;
193
  toDate(): [Date, Date];
194
}
195
```