0
# Shared Utilities
1

2
Essential reactive programming utilities and helpers that provide fundamental building blocks for Vue composition patterns. These utilities offer enhanced reactivity patterns, advanced computed properties, lifecycle helpers, and functional programming patterns.
3

4
## Capabilities
5

6
### Enhanced Reactivity
7

8
#### computedEager
9

10
Eager computed that triggers computation immediately without lazy evaluation.
11

12
```typescript { .api }
13
/**
14
 * Eager computed that computes immediately
15
 * @param fn - Computation function
16
 * @returns Computed ref that computes eagerly
17
 */
18
function computedEager<T>(fn: () => T): ComputedRef<T>;
19
```
20

21
#### computedWithControl
22

23
Computed with manual trigger control for complex dependency management.
24

25
```typescript { .api }
26
/**
27
 * Computed with manual control over when to trigger re-computation
28
 * @param source - Source function
29
 * @param fn - Computation function
30
 * @returns Controlled computed ref with trigger function
31
 */
32
function computedWithControl<T, S>(
33
  source: () => S,
34
  fn: (source: S, oldValue?: T) => T
35
): {
36
  0: ComputedRef<T>;
37
  1: () => void;
38
  trigger: () => void;
39
};
40
```
41

42
#### reactiveComputed
43

44
Make a computed reactive by accepting refs as arguments.
45

46
```typescript { .api }
47
/**
48
 * Computed that accepts reactive arguments
49
 * @param fn - Function that accepts reactive arguments
50
 * @returns Reactive computed function
51
 */
52
function reactiveComputed<T extends any[], R>(
53
  fn: (...args: T) => R
54
): (...args: ToRefs<T>) => ComputedRef<R>;
55
```
56

57
### Ref Utilities
58

59
#### refAutoReset
60

61
Ref that automatically resets to default value after specified time.
62

63
```typescript { .api }
64
/**
65
 * Ref that automatically resets after a timeout
66
 * @param defaultValue - Default value to reset to
67
 * @param afterMs - Milliseconds after which to reset
68
 * @returns Auto-resetting ref
69
 */
70
function refAutoReset<T>(
71
  defaultValue: T,
72
  afterMs?: MaybeRefOrGetter<number>
73
): Ref<T>;
74
```
75

76
#### refDebounced
77

78
Debounced ref that delays updates.
79

80
```typescript { .api }
81
/**
82
 * Debounced version of a ref
83
 * @param value - Source ref or value
84
 * @param ms - Debounce delay in milliseconds
85
 * @param options - Debounce options
86
 * @returns Debounced ref
87
 */
88
function refDebounced<T>(
89
  value: MaybeRefOrGetter<T>,
90
  ms?: MaybeRefOrGetter<number>,
91
  options?: DebounceFilterOptions
92
): Readonly<Ref<T>>;
93
```
94

95
#### refThrottled
96

97
Throttled ref that limits update frequency.
98

99
```typescript { .api }
100
/**
101
 * Throttled version of a ref
102
 * @param value - Source ref or value
103
 * @param delay - Throttle delay in milliseconds
104
 * @param trailing - Whether to invoke on trailing edge
105
 * @param leading - Whether to invoke on leading edge
106
 * @returns Throttled ref
107
 */
108
function refThrottled<T>(
109
  value: MaybeRefOrGetter<T>,
110
  delay?: number,
111
  trailing?: boolean,
112
  leading?: boolean
113
): Readonly<Ref<T>>;
114
```
115

116
#### refDefault
117

118
Ref with default value fallback for undefined/null values.
119

120
```typescript { .api }
121
/**
122
 * Ref with default value when null or undefined
123
 * @param source - Source ref
124
 * @param defaultValue - Default value to use
125
 * @returns Ref with default fallback
126
 */
127
function refDefault<T>(
128
  source: Ref<T | null | undefined>,
129
  defaultValue: T
130
): Ref<T>;
131
```
132

133
#### refWithControl
134

135
Ref with get/set control and trigger functions.
136

137
```typescript { .api }
138
/**
139
 * Ref with manual control over get/set operations
140
 * @param initial - Initial value
141
 * @param options - Control options
142
 * @returns Controlled ref with additional methods
143
 */
144
function refWithControl<T>(
145
  initial: T,
146
  options?: RefWithControlOptions<T>
147
): RefWithControlReturn<T>;
148

149
interface RefWithControlReturn<T> extends Ref<T> {
150
  get: (tracking?: boolean) => T;
151
  set: (value: T, triggering?: boolean) => void;
152
  untrackedGet: () => T;
153
  silentSet: (value: T) => void;
154
  peek: () => T;
155
  lay: (value: T) => void;
156
  trigger: () => void;
157
}
158
```
159

160
#### extendRef
161

162
Extend a ref with additional reactive properties.
163

164
```typescript { .api }
165
/**
166
 * Extend a ref with additional reactive properties
167
 * @param ref - Source ref
168
 * @param extend - Object with additional properties
169
 * @param options - Extension options
170
 * @returns Extended ref with additional properties
171
 */
172
function extendRef<R extends Ref<any>, Extend extends Record<string, any>>(
173
  ref: R,
174
  extend: Extend,
175
  options?: ExtendRefOptions
176
): ExtendRefReturn<R, Extend>;
177
```
178

179
### Advanced Watchers
180

181
#### watchDebounced
182

183
Debounced watcher that delays callback execution.
184

185
```typescript { .api }
186
/**
187
 * Debounced version of watch
188
 * @param source - Watch source
189
 * @param cb - Callback function
190
 * @param options - Watch and debounce options
191
 * @returns Stop function
192
 */
193
function watchDebounced<T>(
194
  source: WatchSource<T>,
195
  cb: WatchCallback<T>,
196
  options?: WatchDebouncedOptions
197
): WatchStopHandle;
198
```
199

200
#### watchThrottled
201

202
Throttled watcher that limits callback frequency.
203

204
```typescript { .api }
205
/**
206
 * Throttled version of watch
207
 * @param source - Watch source
208
 * @param cb - Callback function
209
 * @param options - Watch and throttle options
210
 * @returns Stop function
211
 */
212
function watchThrottled<T>(
213
  source: WatchSource<T>,
214
  cb: WatchCallback<T>,
215
  options?: WatchThrottledOptions
216
): WatchStopHandle;
217
```
218

219
#### watchPausable
220

221
Pausable watcher with pause/resume controls.
222

223
```typescript { .api }
224
/**
225
 * Pausable watcher with pause/resume controls
226
 * @param source - Watch source
227
 * @param cb - Callback function
228
 * @param options - Watch options
229
 * @returns Pausable watcher controls
230
 */
231
function watchPausable<T>(
232
  source: WatchSource<T>,
233
  cb: WatchCallback<T>,
234
  options?: WatchPausableOptions
235
): PausableWatchReturn<T>;
236

237
interface PausableWatchReturn<T> {
238
  stop: WatchStopHandle;
239
  pause: () => void;
240
  resume: () => void;
241
  isActive: Ref<boolean>;
242
}
243
```
244

245
#### watchIgnorable
246

247
Ignorable watcher that can skip callback execution.
248

249
```typescript { .api }
250
/**
251
 * Ignorable watcher that can skip notifications
252
 * @param source - Watch source
253
 * @param cb - Callback function
254
 * @param options - Watch options
255
 * @returns Ignorable watcher controls
256
 */
257
function watchIgnorable<T>(
258
  source: WatchSource<T>,
259
  cb: WatchCallback<T>,
260
  options?: WatchIgnorableOptions
261
): IgnorableWatchReturn;
262

263
interface IgnorableWatchReturn {
264
  stop: WatchStopHandle;
265
  ignoreUpdates: (updater: () => void) => void;
266
  ignorePrevAsyncUpdates: () => void;
267
}
268
```
269

270
#### watchTriggerable
271

272
Triggerable watcher with manual trigger capability.
273

274
```typescript { .api }
275
/**
276
 * Triggerable watcher with manual trigger
277
 * @param source - Watch source
278
 * @param cb - Callback function
279
 * @param options - Watch options
280
 * @returns Triggerable watcher controls
281
 */
282
function watchTriggerable<T>(
283
  source: WatchSource<T>,
284
  cb: WatchCallback<T>, 
285
  options?: WatchTriggerableOptions
286
): TriggerableWatchReturn;
287

288
interface TriggerableWatchReturn {
289
  stop: WatchStopHandle;
290
  trigger: () => void;
291
}
292
```
293

294
#### whenever
295

296
Shorthand for conditional watching when value is truthy.
297

298
```typescript { .api }
299
/**
300
 * Shorthand for watching when condition is truthy
301
 * @param source - Watch source
302
 * @param cb - Callback function
303
 * @param options - Watch options
304
 * @returns Stop function
305
 */
306
function whenever<T>(
307
  source: WatchSource<T | false | null | undefined>,
308
  cb: WatchCallback<T>,
309
  options?: WatchOptions
310
): WatchStopHandle;
311
```
312

313
#### until
314

315
Wait for condition to be truthy.
316

317
```typescript { .api }
318
/**
319
 * Wait for a condition to be truthy
320
 * @param r - Condition to wait for
321
 * @returns Promise that resolves when condition is truthy
322
 */
323
function until<T>(r: MaybeRefOrGetter<T>): UntilReturn<T>;
324

325
interface UntilReturn<T> {
326
  toMatch: (condition: (v: T) => boolean, options?: UntilToMatchOptions) => Promise<void>;
327
  changed: (options?: UntilOptions) => Promise<void>;
328
  changedTimes: (n?: number, options?: UntilOptions) => Promise<void>;
329
  toBe: <P>(value: MaybeRefOrGetter<P>, options?: UntilOptions) => Promise<void>;
330
  toBeTruthy: (options?: UntilOptions) => Promise<void>;
331
  toBeNull: (options?: UntilOptions) => Promise<void>;
332
  toBeUndefined: (options?: UntilOptions) => Promise<void>;
333
  not: UntilReturn<T>;
334
}
335
```
336

337
### Array Utilities
338

339
#### useArrayMap
340

341
Reactive array map function.
342

343
```typescript { .api }
344
/**
345
 * Reactive array map
346
 * @param list - Source array or ref
347
 * @param fn - Map function
348
 * @returns Reactive mapped array
349
 */
350
function useArrayMap<T, U>(
351
  list: MaybeRefOrGetter<T[]>,
352
  fn: (element: T, index: number) => U
353
): ComputedRef<U[]>;
354
```
355

356
#### useArrayFilter
357

358
Reactive array filter function.
359

360
```typescript { .api }
361
/**
362
 * Reactive array filter
363
 * @param list - Source array or ref
364
 * @param fn - Filter predicate function
365
 * @returns Reactive filtered array
366
 */
367
function useArrayFilter<T>(
368
  list: MaybeRefOrGetter<T[]>,
369
  fn: (element: T, index: number) => boolean
370
): ComputedRef<T[]>;
371
```
372

373
#### useArrayFind
374

375
Reactive array find function.
376

377
```typescript { .api }
378
/**
379
 * Reactive array find
380
 * @param list - Source array or ref
381
 * @param fn - Find predicate function
382
 * @returns Reactive found element
383
 */
384
function useArrayFind<T>(
385
  list: MaybeRefOrGetter<T[]>,
386
  fn: (element: T, index: number) => boolean
387
): ComputedRef<T | undefined>;
388
```
389

390
#### useArrayReduce
391

392
Reactive array reduce function.
393

394
```typescript { .api }
395
/**
396
 * Reactive array reduce
397
 * @param list - Source array or ref
398
 * @param reducer - Reducer function
399
 * @param initialValue - Initial accumulator value
400
 * @returns Reactive reduced value
401
 */
402
function useArrayReduce<T, U>(
403
  list: MaybeRefOrGetter<T[]>,
404
  reducer: (accumulator: U, currentValue: T, currentIndex: number) => U,
405
  initialValue: MaybeRefOrGetter<U>
406
): ComputedRef<U>;
407
```
408

409
#### useArraySome
410

411
Reactive array some function.
412

413
```typescript { .api }
414
/**
415
 * Reactive array some
416
 * @param list - Source array or ref
417
 * @param fn - Test predicate function
418
 * @returns Reactive boolean result
419
 */
420
function useArraySome<T>(
421
  list: MaybeRefOrGetter<T[]>,
422
  fn: (element: T, index: number) => boolean
423
): ComputedRef<boolean>;
424
```
425

426
#### useArrayEvery
427

428
Reactive array every function.
429

430
```typescript { .api }
431
/**
432
 * Reactive array every
433
 * @param list - Source array or ref
434
 * @param fn - Test predicate function
435
 * @returns Reactive boolean result
436
 */
437
function useArrayEvery<T>(
438
  list: MaybeRefOrGetter<T[]>,
439
  fn: (element: T, index: number) => boolean
440
): ComputedRef<boolean>;
441
```
442

443
### State Helpers
444

445
#### createGlobalState
446

447
Create globally shared reactive state.
448

449
```typescript { .api }
450
/**
451
 * Create global reactive state that persists across component instances
452
 * @param stateFactory - Function that creates the initial state
453
 * @returns Global state creator function
454
 */
455
function createGlobalState<T>(
456
  stateFactory: () => T
457
): () => T;
458
```
459

460
#### createSharedComposable
461

462
Create a shared composable that returns the same instance.
463

464
```typescript { .api }
465
/**
466
 * Make a composable function shared across multiple instances
467
 * @param composable - Composable function to share
468
 * @returns Shared version of the composable
469
 */
470
function createSharedComposable<Fn extends (...args: any[]) => any>(
471
  composable: Fn
472
): Fn;
473
```
474

475
#### useToggle
476

477
Toggle state management utility.
478

479
```typescript { .api }
480
/**
481
 * Boolean toggle utility with multiple states support
482
 * @param initialValue - Initial value or array of values
483
 * @returns Toggle state and functions
484
 */
485
function useToggle<T = boolean>(
486
  initialValue?: MaybeRef<T>
487
): UseToggleReturn<T>;
488

489
interface UseToggleReturn<T> {
490
  0: Ref<T>;
491
  1: (value?: T) => T;
492
  toggle: (value?: T) => T;
493
}
494
```
495

496
#### useCounter
497

498
Counter state management utility.
499

500
```typescript { .api }
501
/**
502
 * Counter with increment/decrement operations
503
 * @param initialValue - Initial counter value
504
 * @param options - Counter options
505
 * @returns Counter state and operations
506
 */
507
function useCounter(
508
  initialValue?: MaybeRef<number>,
509
  options?: UseCounterOptions
510
): UseCounterReturn;
511

512
interface UseCounterReturn {
513
  count: Ref<number>;
514
  inc: (delta?: number) => number;
515
  dec: (delta?: number) => number;
516
  get: () => number;
517
  set: (val: number) => number;
518
  reset: (val?: number) => number;
519
}
520
```
521

522
### Time & Intervals
523

524
#### useInterval
525

526
Reactive interval management.
527

528
```typescript { .api }
529
/**
530
 * Reactive interval
531
 * @param callback - Callback function to execute
532
 * @param interval - Interval delay in milliseconds
533
 * @param options - Interval options
534
 * @returns Interval controls
535
 */
536
function useInterval(
537
  callback: Fn,
538
  interval?: MaybeRef<number>,
539
  options?: UseIntervalOptions
540
): Pausable;
541
```
542

543
#### useTimeout
544

545
Reactive timeout management.
546

547
```typescript { .api }
548
/**
549
 * Reactive timeout
550
 * @param callback - Callback function to execute
551
 * @param interval - Timeout delay in milliseconds
552
 * @param options - Timeout options
553
 * @returns Timeout controls
554
 */
555
function useTimeout(
556
  callback: Fn,
557
  interval: MaybeRef<number>,
558
  options?: UseTimeoutOptions
559
): UseTimeoutReturn;
560
```
561

562
#### useDateFormat
563

564
Reactive date formatting utility.
565

566
```typescript { .api }
567
/**
568
 * Reactive date formatting
569
 * @param date - Date to format
570
 * @param format - Format string
571
 * @param options - Formatting options
572
 * @returns Reactive formatted date string
573
 */
574
function useDateFormat(
575
  date: MaybeRefOrGetter<Date | number | string>,
576
  format?: MaybeRefOrGetter<string>,
577
  options?: UseDateFormatOptions
578
): ComputedRef<string>;
579
```
580

581
### Utility Functions
582

583
#### reactify
584

585
Convert a function to accept reactive arguments.
586

587
```typescript { .api }
588
/**
589
 * Convert a function to accept refs as arguments
590
 * @param fn - Function to reactify
591
 * @returns Reactified function
592
 */
593
function reactify<T extends (...args: any[]) => any>(
594
  fn: T,
595
  options?: ReactifyOptions<T>
596
): ReactifyReturn<T>;
597
```
598

599
#### toReactive
600

601
Convert a ref to reactive object.
602

603
```typescript { .api }
604
/**
605
 * Convert refs to reactive object
606
 * @param objectRef - Ref containing an object
607
 * @returns Reactive version of the object
608
 */
609
function toReactive<T extends Record<string, any>>(
610
  objectRef: MaybeRef<T>
611
): ToReactive<T>;
612
```
613

614
#### makeDestructurable
615

616
Make an object both array-like and object-like for destructuring.
617

618
```typescript { .api }
619
/**
620
 * Make return values suitable for both array and object destructuring
621
 * @param obj - Object to make destructurable
622
 * @param arr - Array representation
623
 * @returns Destructurable object
624
 */
625
function makeDestructurable<T extends Record<string, unknown>, A extends readonly unknown[]>(
626
  obj: T,
627
  arr: A
628
): T & A;
629
```
630

631
#### isDefined
632

633
Type guard for checking if value is defined.
634

635
```typescript { .api }
636
/**
637
 * Type guard to check if value is defined (not null or undefined)
638
 * @param val - Value to check
639
 * @returns True if value is defined
640
 */
641
function isDefined<T>(val: T | undefined | null): val is T;
642
```
643

644
#### get
645

646
Get value from MaybeRefOrGetter.
647

648
```typescript { .api }
649
/**
650
 * Get the value from MaybeRefOrGetter
651
 * @param val - Value, ref, or getter function
652
 * @returns Resolved value
653
 */
654
function get<T>(val: MaybeRefOrGetter<T>): T;
655
```
656

657
#### set
658

659
Set value to a ref.
660

661
```typescript { .api }
662
/**
663
 * Set value to a ref
664
 * @param ref - Target ref
665
 * @param val - Value to set
666
 */
667
function set<T>(ref: Ref<T>, val: T): void;
668
```
669

670
### Lifecycle Helpers
671

672
#### tryOnMounted
673

674
Safely call onMounted if inside component instance.
675

676
```typescript { .api }
677
/**
678
 * Safe version of onMounted that works outside component context
679
 * @param fn - Function to call on mounted
680
 * @param sync - Whether to call synchronously if already mounted
681
 * @returns Whether the hook was successfully registered
682
 */
683
function tryOnMounted(fn: Fn, sync?: boolean): boolean;
684
```
685

686
#### tryOnBeforeMount
687

688
Safely call onBeforeMount if inside component instance.
689

690
```typescript { .api }
691
/**
692
 * Safe version of onBeforeMount that works outside component context
693
 * @param fn - Function to call before mount
694
 * @param sync - Whether to call synchronously if component exists
695
 * @returns Whether the hook was successfully registered
696
 */
697
function tryOnBeforeMount(fn: Fn, sync?: boolean): boolean;
698
```
699

700
#### tryOnUnmounted
701

702
Safely call onUnmounted if inside component instance.
703

704
```typescript { .api }
705
/**
706
 * Safe version of onUnmounted that works outside component context
707
 * @param fn - Function to call on unmounted
708
 * @returns Whether the hook was successfully registered
709
 */
710
function tryOnUnmounted(fn: Fn): boolean;
711
```
712

713
#### tryOnScopeDispose
714

715
Safely call onScopeDispose if inside effect scope.
716

717
```typescript { .api }
718
/**
719
 * Safe version of onScopeDispose that works outside effect scope
720
 * @param fn - Function to call on scope dispose
721
 * @returns Whether the hook was successfully registered
722
 */
723
function tryOnScopeDispose(fn: Fn): boolean;
724
```
725

726
## Shared Types
727

728
```typescript { .api }
729
// Core utility types
730
type MaybeRef<T> = T | Ref<T>;
731
type MaybeRefOrGetter<T> = T | MaybeRef<T> | (() => T);
732
type MaybeComputedRef<T> = ComputedRef<T> | MaybeRef<T>;
733

734
// Function types
735
type Fn = () => void;
736
type AnyFn = (...args: any[]) => any;
737

738
// Control interfaces
739
interface Pausable {
740
  isActive: Ref<boolean>;
741
  pause: Fn;
742
  resume: Fn;
743
}
744

745
interface Awaitable<T> {
746
  [Symbol.iterator]: any;
747
  then: PromiseLike<T>['then'];
748
}
749

750
// Filter options
751
interface DebounceFilterOptions {
752
  maxWait?: MaybeRefOrGetter<number>;
753
  rejectOnCancel?: boolean;
754
}
755

756
interface ThrottleFilterOptions {
757
  trailing?: boolean;
758
  leading?: boolean;
759
  rejectOnCancel?: boolean;
760
}
761
```