0
# Time-based Operations
1

2
Operators for time-based operations including delay, throttle, debounce, and interval scheduling.
3

4
## Capabilities
5

6
### Delay
7

8
Delays the emission of elements by a specified duration.
9

10
```javascript { .api }
11
/**
12
 * Delays the emission of elements by the specified duration
13
 * @param {number} dueTime - Delay duration in milliseconds
14
 * @param {Scheduler} [scheduler] - Scheduler to use for the delay
15
 * @returns {Observable} Observable sequence with delayed emissions
16
 */
17
observable.delay = function(dueTime, scheduler);
18
```
19

20
**Usage Example:**
21

22
```javascript
23
var source = Rx.Observable.range(1, 3);
24
var delayed = source.delay(1000);
25
// Emits 1, 2, 3 after 1 second delay
26
```
27

28
### Debounce
29

30
Emits an element only after a specified duration has passed without another emission.
31

32
```javascript { .api }
33
/**
34
 * Emits an element only after a specified duration of silence
35
 * @param {number} dueTime - Debounce duration in milliseconds
36
 * @param {Scheduler} [scheduler] - Scheduler to use for timing
37
 * @returns {Observable} Observable sequence with debounced emissions
38
 */
39
observable.debounce = function(dueTime, scheduler);
40
```
41

42
**Usage Example:**
43

44
```javascript
45
var source = Rx.Observable.fromEvent(textInput, 'keyup');
46
var debounced = source.debounce(300);
47
// Only emits after 300ms of no typing
48
```
49

50
### Throttle
51

52
Emits the first element, then ignores subsequent elements for a specified duration.
53

54
```javascript { .api }
55
/**
56
 * Emits first element then ignores subsequent elements for specified duration
57
 * @param {number} windowDuration - Throttle window duration in milliseconds
58
 * @param {Scheduler} [scheduler] - Scheduler to use for timing
59
 * @returns {Observable} Observable sequence with throttled emissions
60
 */
61
observable.throttle = function(windowDuration, scheduler);
62
```
63

64
### Sample
65

66
Samples the observable at specified intervals.
67

68
```javascript { .api }
69
/**
70
 * Samples the observable sequence at specified intervals
71
 * @param {number|Observable} intervalOrSampler - Interval in milliseconds or sampling observable
72
 * @param {Scheduler} [scheduler] - Scheduler to use for timing
73
 * @returns {Observable} Observable sequence with sampled values
74
 */
75
observable.sample = function(intervalOrSampler, scheduler);
76
```
77

78
**Usage Example:**
79

80
```javascript
81
var source = Rx.Observable.interval(100);
82
var sampled = source.sample(500);
83
// Samples every 500ms, getting latest value from 100ms interval
84
```
85

86
### Timeout
87

88
Applies a timeout to the observable sequence.
89

90
```javascript { .api }
91
/**
92
 * Applies a timeout to the observable sequence
93
 * @param {number} dueTime - Timeout duration in milliseconds
94
 * @param {Observable} [other] - Observable to switch to on timeout
95
 * @param {Scheduler} [scheduler] - Scheduler to use for timing
96
 * @returns {Observable} Observable sequence with timeout applied
97
 */
98
observable.timeout = function(dueTime, other, scheduler);
99
```
100

101
**Usage Example:**
102

103
```javascript
104
var source = Rx.Observable.timer(2000);
105
var timeoutSource = source.timeout(1000, Rx.Observable.return('Timeout!'));
106
// Emits 'Timeout!' if source doesn't emit within 1 second
107
```
108

109
### Time Interval
110

111
Attaches time interval information to each element.
112

113
```javascript { .api }
114
/**
115
 * Records the time interval between consecutive emissions
116
 * @param {Scheduler} [scheduler] - Scheduler to use for timing
117
 * @returns {Observable} Observable sequence with time interval information
118
 */
119
observable.timeInterval = function(scheduler);
120
```
121

122
**Usage Example:**
123

124
```javascript
125
var source = Rx.Observable.interval(1000);
126
var withInterval = source.timeInterval();
127
// Emits objects like: {value: 0, interval: 1000}
128
```
129

130
### Timestamp
131

132
Attaches timestamp information to each element.
133

134
```javascript { .api }
135
/**
136
 * Records the timestamp of each emission
137
 * @param {Scheduler} [scheduler] - Scheduler to use for timing
138
 * @returns {Observable} Observable sequence with timestamp information
139
 */
140
observable.timestamp = function(scheduler);
141
```
142

143
**Usage Example:**
144

145
```javascript
146
var source = Rx.Observable.range(1, 3);
147
var withTimestamp = source.timestamp();
148
// Emits objects like: {value: 1, timestamp: 1234567890}
149
```
150

151
### Interval (Static)
152

153
Creates an observable that emits sequential numbers at specified intervals.
154

155
```javascript { .api }
156
/**
157
 * Creates an observable that emits sequential numbers at specified intervals
158
 * @param {number} period - Interval period in milliseconds
159
 * @param {Scheduler} [scheduler] - Scheduler to use for timing
160
 * @returns {Observable} Observable sequence of sequential numbers
161
 */
162
Rx.Observable.interval = function(period, scheduler);
163
```
164

165
**Usage Example:**
166

167
```javascript
168
var source = Rx.Observable.interval(1000);
169
// Emits: 0, 1, 2, 3, ... every 1000ms
170
```
171

172
### Timer (Static)
173

174
Creates an observable that emits after a delay and then optionally at intervals.
175

176
```javascript { .api }
177
/**
178
 * Creates an observable that emits after a delay, optionally repeating
179
 * @param {number} dueTime - Initial delay in milliseconds
180
 * @param {number} [period] - Period for subsequent emissions in milliseconds
181
 * @param {Scheduler} [scheduler] - Scheduler to use for timing
182
 * @returns {Observable} Observable sequence with timer emissions
183
 */
184
Rx.Observable.timer = function(dueTime, period, scheduler);
185
```
186

187
**Usage Example:**
188

189
```javascript
190
var source = Rx.Observable.timer(2000, 1000);
191
// Waits 2s, then emits: 0, 1, 2, 3, ... every 1000ms
192
```
193

194
### Window With Time
195

196
Creates windows based on time intervals.
197

198
```javascript { .api }
199
/**
200
 * Projects elements into zero or more windows based on timing information
201
 * @param {number} timeSpan - Maximum time length of a window
202
 * @param {number} [timeShift] - Interval between creation of consecutive windows
203
 * @param {Scheduler} [scheduler] - Scheduler to use for timing
204
 * @returns {Observable} Observable sequence of observable windows
205
 */
206
observable.windowWithTime = function(timeSpan, timeShift, scheduler);
207
observable.windowTime = function(timeSpan, timeShift, scheduler); // Alias
208
```
209

210
### Buffer With Time
211

212
Buffers elements based on time intervals.
213

214
```javascript { .api }
215
/**
216
 * Buffers elements into arrays based on timing information
217
 * @param {number} timeSpan - Maximum time length of a buffer
218
 * @param {number} [timeShift] - Interval between creation of consecutive buffers
219
 * @param {Scheduler} [scheduler] - Scheduler to use for timing
220
 * @returns {Observable} Observable sequence of arrays
221
 */
222
observable.bufferWithTime = function(timeSpan, timeShift, scheduler);
223
observable.bufferTime = function(timeSpan, timeShift, scheduler); // Alias
224
```
225

226
**Usage Example:**
227

228
```javascript
229
var source = Rx.Observable.interval(100);
230
var buffered = source.bufferWithTime(500);
231
// Emits arrays of values collected every 500ms
232
```
233

234
### Delay Subscription
235

236
Delays the subscription to the source observable.
237

238
```javascript { .api }
239
/**
240
 * Delays the subscription to the source observable by specified duration
241
 * @param {number} dueTime - Delay duration in milliseconds
242
 * @param {Scheduler} [scheduler] - Scheduler to use for the delay
243
 * @returns {Observable} Observable sequence with delayed subscription
244
 */
245
observable.delaySubscription = function(dueTime, scheduler);
246
```
247

248
### Take/Skip With Time
249

250
Time-based versions of take and skip operations.
251

252
```javascript { .api }
253
/**
254
 * Takes elements for the specified duration
255
 * @param {number} duration - Duration in milliseconds to take elements
256
 * @param {Scheduler} [scheduler] - Scheduler to use for timing
257
 * @returns {Observable} Observable sequence taking elements for specified duration
258
 */
259
observable.takeWithTime = function(duration, scheduler);
260

261
/**
262
 * Skips elements for the specified duration
263
 * @param {number} duration - Duration in milliseconds to skip elements
264
 * @param {Scheduler} [scheduler] - Scheduler to use for timing
265
 * @returns {Observable} Observable sequence skipping elements for specified duration
266
 */
267
observable.skipWithTime = function(duration, scheduler);
268

269
/**
270
 * Takes the last elements that occurred within the specified duration
271
 * @param {number} duration - Duration in milliseconds
272
 * @param {Scheduler} [scheduler] - Scheduler to use for timing
273
 * @returns {Observable} Observable sequence of last elements within duration
274
 */
275
observable.takeLastWithTime = function(duration, scheduler);
276
```