Ref Utilities

/**
 * Debounced version of ref
 * @param value - Source ref to debounce
 * @param ms - Debounce delay in milliseconds  
 * @param options - Debounce options
 * @returns Readonly ref with debounced value
 */
function refDebounced<T>(
  value: Ref<T>, 
  ms?: number, 
  options?: DebounceFilterOptions
): Readonly<Ref<T>>;

interface DebounceFilterOptions {
  maxWait?: MaybeRefOrGetter<number>;
  rejectOnCancel?: boolean;
}

import { refDebounced, ref } from "@vueuse/shared";

const input = ref('');
const debouncedInput = refDebounced(input, 500);

// input changes immediately, debouncedInput updates after 500ms delay
input.value = 'h';
input.value = 'he';
input.value = 'hel';
input.value = 'hello'; // Only this final value will appear in debouncedInput

setTimeout(() => {
  console.log(debouncedInput.value); // 'hello'
}, 600);

/**
 * Throttled version of ref
 * @param value - Source ref to throttle
 * @param delay - Throttle delay in milliseconds
 * @param trailing - Execute on trailing edge
 * @param leading - Execute on leading edge
 * @returns Readonly ref with throttled value
 */
function refThrottled<T>(
  value: Ref<T>, 
  delay?: number, 
  trailing?: boolean, 
  leading?: boolean
): Readonly<Ref<T>>;

import { refThrottled, ref } from "@vueuse/shared";

const scrollY = ref(0);
const throttledScrollY = refThrottled(scrollY, 100);

// Rapid scroll updates are throttled to every 100ms
window.addEventListener('scroll', () => {
  scrollY.value = window.scrollY;
});

watch(throttledScrollY, (y) => {
  console.log('Throttled scroll position:', y);
});

/**
 * Ref that automatically resets to default value after timeout
 * @param defaultValue - Default value to reset to
 * @param afterMs - Reset delay in milliseconds
 * @returns Ref that auto-resets
 */
function refAutoReset<T>(defaultValue: T, afterMs?: number): Ref<T>;

import { refAutoReset } from "@vueuse/shared";

// Status message that auto-clears after 3 seconds
const statusMessage = refAutoReset('', 3000);

const showSuccess = () => {
  statusMessage.value = 'Operation successful!';
  // Automatically becomes '' after 3 seconds
};

const showError = () => {
  statusMessage.value = 'Operation failed!';
  // Automatically becomes '' after 3 seconds
};

/**
 * Ref with default value when source is nullish
 * @param source - Source ref
 * @param defaultValue - Default value for nullish cases
 * @returns Ref with default value handling
 */
function refDefault<T>(
  source: Ref<T | undefined | null>, 
  defaultValue: T
): Ref<T>;

import { refDefault, ref } from "@vueuse/shared";

const userName = ref<string | null>(null);
const displayName = refDefault(userName, 'Anonymous');

console.log(displayName.value); // 'Anonymous'

userName.value = 'John';
console.log(displayName.value); // 'John'

userName.value = null;
console.log(displayName.value); // 'Anonymous'

/**
 * Ref with explicit control over its reactivity
 * @param initial - Initial value
 * @param options - Control options
 * @returns Ref with reactivity controls
 */
function refWithControl<T>(initial: T, options?: RefWithControlOptions): RefWithControl<T>;

interface RefWithControlOptions {
  onBeforeChange?: (value: T, oldValue: T) => void | boolean;
  onChanged?: (value: T, oldValue: T) => void;
}

interface RefWithControl<T> extends Ref<T> {
  get(): T;
  set(value: T): void;
  untrackedGet(): T;
  silentSet(value: T): void;
  peek(): T;
  lay(value: T): void;
}

import { refWithControl } from "@vueuse/shared";

const controlledRef = refWithControl('initial', {
  onBeforeChange(value, oldValue) {
    console.log(`Changing from ${oldValue} to ${value}`);
    // Return false to prevent change
    return value !== 'forbidden';
  },
  onChanged(value, oldValue) {
    console.log(`Changed from ${oldValue} to ${value}`);
  }
});

// Normal reactive access
controlledRef.value = 'new value'; // Triggers watchers

// Untracked access (doesn't trigger watchers)
const current = controlledRef.untrackedGet();

// Silent set (doesn't trigger watchers)
controlledRef.silentSet('silent update');

// Peek without tracking
const peeked = controlledRef.peek();

// Lay value (update without triggering onBeforeChange)
controlledRef.lay('laid value');

/**
 * Extends ref with additional properties
 * @param ref - Source ref to extend
 * @param extend - Object with additional properties/methods
 * @param options - Extension options
 * @returns Extended ref with additional properties
 */
function extendRef<T, Extend>(
  ref: Ref<T>, 
  extend: Extend, 
  options?: ExtendRefOptions
): ShallowUnwrapRef<Extend> & Ref<T>;

interface ExtendRefOptions {
  enumerable?: boolean;
  unwrap?: boolean;
}

import { extendRef, ref } from "@vueuse/shared";

const count = ref(0);

const extendedCount = extendRef(count, {
  double: () => count.value * 2,
  reset: () => { count.value = 0; },
  increment: (by = 1) => { count.value += by; },
  get isEven() { return count.value % 2 === 0; }
});

// Use as normal ref
console.log(extendedCount.value); // 0

// Use extended methods
extendedCount.increment(5);
console.log(extendedCount.double()); // 10
console.log(extendedCount.isEven);   // false

extendedCount.reset();
console.log(extendedCount.value);    // 0

/**
 * Enhanced ref creation
 * @param value - Initial value
 * @param options - Creation options
 * @returns Enhanced ref
 */
function createRef<T>(value: T, options?: CreateRefOptions): Ref<T>;

interface CreateRefOptions {
  deep?: boolean;
  onTrack?: (event: DebuggerEvent) => void;
  onTrigger?: (event: DebuggerEvent) => void;
}

/**
 * Enhanced version of Vue's toRef with additional capabilities
 */
function toRef<T>(value: MaybeRef<T>): Ref<T>;
function toRef<T extends object, K extends keyof T>(
  object: T, 
  key: K, 
  defaultValue?: T[K]
): Ref<T[K]>;

/**
 * Enhanced version of Vue's toRefs
 * @param objectRef - Object ref to convert
 * @returns Object with refs for each property
 */
function toRefs<T extends object>(objectRef: MaybeRef<T>): ToRefs<T>;

/**
 * Get the value of value/ref/getter (alias for get)
 * @param r - Value, ref, or getter
 * @returns Unwrapped value
 */
function toValue<T>(r: MaybeRefOrGetter<T>): T;

import { toRef, toRefs, toValue, ref, reactive } from "@vueuse/shared";

// toRef with default value
const obj = reactive({ name: 'John' });
const nameRef = toRef(obj, 'name', 'Anonymous');

// toRefs on ref of object
const userRef = ref({ name: 'John', age: 30 });
const { name, age } = toRefs(userRef);

// toValue with different input types
const staticValue = toValue('hello');           // 'hello'
const refValue = toValue(ref('world'));         // 'world'  
const getterValue = toValue(() => 'computed');  // 'computed'