0
# Watch Utilities
1

2
Enhanced watching capabilities beyond Vue's built-in watchers, including debounced, throttled, pausable, and conditional watchers.
3

4
## Capabilities
5

6
### whenever
7

8
Shorthand for watching a value to be truthy.
9

10
```typescript { .api }
11
/**
12
 * Watch for truthy values
13
 * @param source - Watch source
14
 * @param cb - Callback when source becomes truthy
15
 * @param options - Watch options
16
 * @returns Stop handle
17
 */
18
function whenever<T>(
19
  source: WatchSource<T | false | null | undefined>, 
20
  cb: WatchCallback<T>, 
21
  options?: WatchOptions
22
): WatchStopHandle;
23
```
24

25
**Usage Example:**
26

27
```typescript
28
import { whenever, ref } from "@vueuse/shared";
29

30
const name = ref('');
31

32
// Only triggers when name has a truthy value
33
whenever(name, (value) => {
34
  console.log('Name is set:', value);
35
});
36

37
name.value = 'John'; // Triggers callback
38
name.value = '';     // Does not trigger
39
name.value = 'Jane'; // Triggers callback
40
```
41

42
### watchDebounced
43

44
Debounced version of watch.
45

46
```typescript { .api }
47
/**
48
 * Debounced watch
49
 * @param source - Watch source
50
 * @param cb - Watch callback
51
 * @param options - Watch and debounce options
52
 * @returns Stop handle
53
 */
54
function watchDebounced<T>(
55
  source: WatchSource<T>, 
56
  cb: WatchCallback<T>, 
57
  options?: WatchDebouncedOptions
58
): WatchStopHandle;
59

60
interface WatchDebouncedOptions extends WatchOptions {
61
  debounce?: number;
62
  maxWait?: number;
63
}
64
```
65

66
**Usage Example:**
67

68
```typescript
69
import { watchDebounced, ref } from "@vueuse/shared";
70

71
const searchQuery = ref('');
72

73
// Debounce search API calls
74
watchDebounced(
75
  searchQuery,
76
  async (query) => {
77
    if (query) {
78
      const results = await searchAPI(query);
79
      console.log('Search results:', results);
80
    }
81
  },
82
  { debounce: 500, maxWait: 1000 }
83
);
84
```
85

86
### watchThrottled
87

88
Throttled version of watch.
89

90
```typescript { .api }
91
/**
92
 * Throttled watch
93
 * @param source - Watch source
94
 * @param cb - Watch callback  
95
 * @param options - Watch and throttle options
96
 * @returns Stop handle
97
 */
98
function watchThrottled<T>(
99
  source: WatchSource<T>, 
100
  cb: WatchCallback<T>, 
101
  options?: WatchThrottledOptions
102
): WatchStopHandle;
103

104
interface WatchThrottledOptions extends WatchOptions {
105
  throttle?: number;
106
  leading?: boolean;
107
  trailing?: boolean;
108
}
109
```
110

111
### watchPausable
112

113
Watch that can be paused and resumed.
114

115
```typescript { .api }
116
/**
117
 * Pausable watch
118
 * @param source - Watch source
119
 * @param cb - Watch callback
120
 * @param options - Watch options
121
 * @returns Pausable watch controls
122
 */
123
function watchPausable<T>(
124
  source: WatchSource<T>, 
125
  cb: WatchCallback<T>, 
126
  options?: WatchPausableOptions
127
): WatchPausableReturn;
128

129
interface WatchPausableOptions extends WatchOptions {
130
  eventFilter?: EventFilter;
131
}
132

133
interface WatchPausableReturn extends Pausable {
134
  stop: WatchStopHandle;
135
}
136
```
137

138
**Usage Example:**
139

140
```typescript
141
import { watchPausable, ref } from "@vueuse/shared";
142

143
const counter = ref(0);
144

145
const { pause, resume, isActive, stop } = watchPausable(
146
  counter,
147
  (count) => console.log('Counter:', count)
148
);
149

150
counter.value++; // Logs: "Counter: 1"
151

152
pause();
153
counter.value++; // No log (paused)
154

155
resume(); 
156
counter.value++; // Logs: "Counter: 3"
157

158
stop(); // Stop watching completely
159
```
160

161
### watchIgnorable
162

163
Watch that can ignore specific updates.
164

165
```typescript { .api }
166
/**
167
 * Watch that can ignore updates
168
 * @param source - Watch source
169
 * @param cb - Watch callback
170
 * @param options - Watch options
171
 * @returns Ignorable watch controls
172
 */
173
function watchIgnorable<T>(
174
  source: WatchSource<T>, 
175
  cb: WatchCallback<T>, 
176
  options?: WatchIgnorableOptions
177
): WatchIgnorableReturn;
178

179
interface WatchIgnorableOptions extends WatchOptions {
180
  eventFilter?: EventFilter;
181
}
182

183
interface WatchIgnorableReturn {
184
  ignoreUpdates: (updater: () => void) => void;
185
  ignorePrevAsyncUpdates: () => void;
186
  stop: WatchStopHandle;
187
}
188
```
189

190
**Usage Example:**
191

192
```typescript
193
import { watchIgnorable, ref } from "@vueuse/shared";
194

195
const counter = ref(0);
196

197
const { ignoreUpdates, stop } = watchIgnorable(
198
  counter,
199
  (count) => console.log('Counter:', count)
200
);
201

202
counter.value++; // Logs: "Counter: 1"
203

204
// Ignore this update
205
ignoreUpdates(() => {
206
  counter.value++; // No log
207
});
208

209
counter.value++; // Logs: "Counter: 3"
210
```
211

212
### watchTriggerable
213

214
Watch that can be manually triggered.
215

216
```typescript { .api }
217
/**
218
 * Watch that can be manually triggered
219
 * @param source - Watch source
220
 * @param cb - Watch callback
221
 * @param options - Watch options
222
 * @returns Triggerable watch controls
223
 */
224
function watchTriggerable<T>(
225
  source: WatchSource<T>, 
226
  cb: WatchCallback<T>, 
227
  options?: WatchTriggerableOptions
228
): WatchTriggerableReturn;
229

230
interface WatchTriggerableOptions extends WatchOptions {
231
  // Standard watch options
232
}
233

234
interface WatchTriggerableReturn {
235
  trigger: () => void;
236
  stop: WatchStopHandle;
237
}
238
```
239

240
### watchAtMost
241

242
Watch that only triggers for the first few changes.
243

244
```typescript { .api }
245
/**
246
 * Watch only the first few changes
247
 * @param source - Watch source
248
 * @param cb - Watch callback
249
 * @param options - Watch options with count limit
250
 * @returns Stop handle
251
 */
252
function watchAtMost<T>(
253
  source: WatchSource<T>, 
254
  cb: WatchCallback<T>, 
255
  options: WatchAtMostOptions
256
): WatchStopHandle;
257

258
interface WatchAtMostOptions extends WatchOptions {
259
  count: number;
260
}
261
```
262

263
**Usage Example:**
264

265
```typescript
266
import { watchAtMost, ref } from "@vueuse/shared";
267

268
const counter = ref(0);
269

270
// Only watch first 3 changes
271
watchAtMost(
272
  counter,
273
  (count) => console.log('Counter:', count),
274
  { count: 3 }
275
);
276

277
counter.value++; // Logs: "Counter: 1"
278
counter.value++; // Logs: "Counter: 2" 
279
counter.value++; // Logs: "Counter: 3"
280
counter.value++; // No log (exceeded count)
281
```
282

283
### watchOnce
284

285
Watch that stops after the first trigger.
286

287
```typescript { .api }
288
/**
289
 * Watch that stops after first trigger
290
 * @param source - Watch source
291
 * @param cb - Watch callback
292
 * @param options - Watch options
293
 * @returns Stop handle
294
 */
295
function watchOnce<T>(
296
  source: WatchSource<T>, 
297
  cb: WatchCallback<T>, 
298
  options?: WatchOptions
299
): WatchStopHandle;
300
```
301

302
### watchWithFilter
303

304
Watch with custom filter logic.
305

306
```typescript { .api }
307
/**
308
 * Watch with custom filter
309
 * @param source - Watch source
310
 * @param cb - Watch callback
311
 * @param options - Watch options with filter
312
 * @returns Stop handle
313
 */
314
function watchWithFilter<T>(
315
  source: WatchSource<T>, 
316
  cb: WatchCallback<T>, 
317
  options: WatchWithFilterOptions<T>
318
): WatchStopHandle;
319

320
interface WatchWithFilterOptions<T> extends WatchOptions {
321
  eventFilter: (invoke: Fn, options: FunctionArgs) => void;
322
}
323
```
324

325
### watchArray
326

327
Watch for deep changes on an array.
328

329
```typescript { .api }
330
/**
331
 * Watch for deep changes on an array
332
 * @param source - Array to watch
333
 * @param cb - Array change callback
334
 * @param options - Watch options
335
 * @returns Stop handle
336
 */
337
function watchArray<T>(
338
  source: WatchSource<T[]> | T[], 
339
  cb: WatchArrayCallback<T>, 
340
  options?: WatchOptions
341
): WatchStopHandle;
342

343
type WatchArrayCallback<T> = (
344
  newValue: T[],
345
  oldValue: T[],
346
  added: T[],
347
  removed: T[],
348
  onCleanup: (cleanupFn: () => void) => void
349
) => void;
350
```
351

352
**Usage Example:**
353

354
```typescript
355
import { watchArray, ref } from "@vueuse/shared";
356

357
const list = ref([1, 2, 3]);
358

359
watchArray(list, (newList, oldList, added, removed) => {
360
  console.log('New:', newList);
361
  console.log('Added:', added);
362
  console.log('Removed:', removed);
363
});
364

365
list.value.push(4); // Logs added: [4]
366
list.value.splice(0, 1); // Logs removed: [1]
367
```
368

369
### Convenience Watchers
370

371
Several watch utilities provide common configurations:
372

373
```typescript { .api }
374
/**
375
 * Watch with deep: true
376
 */
377
function watchDeep<T>(
378
  source: WatchSource<T>, 
379
  cb: WatchCallback<T>, 
380
  options?: WatchOptions
381
): WatchStopHandle;
382

383
/**
384
 * Watch with immediate: true
385
 */
386
function watchImmediate<T>(
387
  source: WatchSource<T>, 
388
  cb: WatchCallback<T>, 
389
  options?: WatchOptions
390
): WatchStopHandle;
391
```