tessl/npm-vueuse--shared

Collection of essential shared Vue Composition Utilities providing foundational building blocks for reactive Vue applications

—

Pending

Overview

Eval results

Files

Watch Utilities

Name: tessl/npm-vueuse--shared
Author: tessl

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

Capabilities

whenever

Shorthand for watching a value to be truthy.

/**
 * Watch for truthy values
 * @param source - Watch source
 * @param cb - Callback when source becomes truthy
 * @param options - Watch options
 * @returns Stop handle
 */
function whenever<T>(
  source: WatchSource<T | false | null | undefined>, 
  cb: WatchCallback<T>, 
  options?: WatchOptions
): WatchStopHandle;

Usage Example:

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

const name = ref('');

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

name.value = 'John'; // Triggers callback
name.value = '';     // Does not trigger
name.value = 'Jane'; // Triggers callback

watchDebounced

Debounced version of watch.

/**
 * Debounced watch
 * @param source - Watch source
 * @param cb - Watch callback
 * @param options - Watch and debounce options
 * @returns Stop handle
 */
function watchDebounced<T>(
  source: WatchSource<T>, 
  cb: WatchCallback<T>, 
  options?: WatchDebouncedOptions
): WatchStopHandle;

interface WatchDebouncedOptions extends WatchOptions {
  debounce?: number;
  maxWait?: number;
}

Usage Example:

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

const searchQuery = ref('');

// Debounce search API calls
watchDebounced(
  searchQuery,
  async (query) => {
    if (query) {
      const results = await searchAPI(query);
      console.log('Search results:', results);
    }
  },
  { debounce: 500, maxWait: 1000 }
);

watchThrottled

Throttled version of watch.

/**
 * Throttled watch
 * @param source - Watch source
 * @param cb - Watch callback  
 * @param options - Watch and throttle options
 * @returns Stop handle
 */
function watchThrottled<T>(
  source: WatchSource<T>, 
  cb: WatchCallback<T>, 
  options?: WatchThrottledOptions
): WatchStopHandle;

interface WatchThrottledOptions extends WatchOptions {
  throttle?: number;
  leading?: boolean;
  trailing?: boolean;
}

watchPausable

Watch that can be paused and resumed.

/**
 * Pausable watch
 * @param source - Watch source
 * @param cb - Watch callback
 * @param options - Watch options
 * @returns Pausable watch controls
 */
function watchPausable<T>(
  source: WatchSource<T>, 
  cb: WatchCallback<T>, 
  options?: WatchPausableOptions
): WatchPausableReturn;

interface WatchPausableOptions extends WatchOptions {
  eventFilter?: EventFilter;
}

interface WatchPausableReturn extends Pausable {
  stop: WatchStopHandle;
}

Usage Example:

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

const counter = ref(0);

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

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

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

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

stop(); // Stop watching completely

watchIgnorable

Watch that can ignore specific updates.

/**
 * Watch that can ignore updates
 * @param source - Watch source
 * @param cb - Watch callback
 * @param options - Watch options
 * @returns Ignorable watch controls
 */
function watchIgnorable<T>(
  source: WatchSource<T>, 
  cb: WatchCallback<T>, 
  options?: WatchIgnorableOptions
): WatchIgnorableReturn;

interface WatchIgnorableOptions extends WatchOptions {
  eventFilter?: EventFilter;
}

interface WatchIgnorableReturn {
  ignoreUpdates: (updater: () => void) => void;
  ignorePrevAsyncUpdates: () => void;
  stop: WatchStopHandle;
}

Usage Example:

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

const counter = ref(0);

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

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

// Ignore this update
ignoreUpdates(() => {
  counter.value++; // No log
});

counter.value++; // Logs: "Counter: 3"

watchTriggerable

Watch that can be manually triggered.

/**
 * Watch that can be manually triggered
 * @param source - Watch source
 * @param cb - Watch callback
 * @param options - Watch options
 * @returns Triggerable watch controls
 */
function watchTriggerable<T>(
  source: WatchSource<T>, 
  cb: WatchCallback<T>, 
  options?: WatchTriggerableOptions
): WatchTriggerableReturn;

interface WatchTriggerableOptions extends WatchOptions {
  // Standard watch options
}

interface WatchTriggerableReturn {
  trigger: () => void;
  stop: WatchStopHandle;
}

watchAtMost

Watch that only triggers for the first few changes.

/**
 * Watch only the first few changes
 * @param source - Watch source
 * @param cb - Watch callback
 * @param options - Watch options with count limit
 * @returns Stop handle
 */
function watchAtMost<T>(
  source: WatchSource<T>, 
  cb: WatchCallback<T>, 
  options: WatchAtMostOptions
): WatchStopHandle;

interface WatchAtMostOptions extends WatchOptions {
  count: number;
}

Usage Example:

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

const counter = ref(0);

// Only watch first 3 changes
watchAtMost(
  counter,
  (count) => console.log('Counter:', count),
  { count: 3 }
);

counter.value++; // Logs: "Counter: 1"
counter.value++; // Logs: "Counter: 2" 
counter.value++; // Logs: "Counter: 3"
counter.value++; // No log (exceeded count)

watchOnce

Watch that stops after the first trigger.

/**
 * Watch that stops after first trigger
 * @param source - Watch source
 * @param cb - Watch callback
 * @param options - Watch options
 * @returns Stop handle
 */
function watchOnce<T>(
  source: WatchSource<T>, 
  cb: WatchCallback<T>, 
  options?: WatchOptions
): WatchStopHandle;

watchWithFilter

Watch with custom filter logic.

/**
 * Watch with custom filter
 * @param source - Watch source
 * @param cb - Watch callback
 * @param options - Watch options with filter
 * @returns Stop handle
 */
function watchWithFilter<T>(
  source: WatchSource<T>, 
  cb: WatchCallback<T>, 
  options: WatchWithFilterOptions<T>
): WatchStopHandle;

interface WatchWithFilterOptions<T> extends WatchOptions {
  eventFilter: (invoke: Fn, options: FunctionArgs) => void;
}

watchArray

Watch for deep changes on an array.

/**
 * Watch for deep changes on an array
 * @param source - Array to watch
 * @param cb - Array change callback
 * @param options - Watch options
 * @returns Stop handle
 */
function watchArray<T>(
  source: WatchSource<T[]> | T[], 
  cb: WatchArrayCallback<T>, 
  options?: WatchOptions
): WatchStopHandle;

type WatchArrayCallback<T> = (
  newValue: T[],
  oldValue: T[],
  added: T[],
  removed: T[],
  onCleanup: (cleanupFn: () => void) => void
) => void;

Usage Example:

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

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

watchArray(list, (newList, oldList, added, removed) => {
  console.log('New:', newList);
  console.log('Added:', added);
  console.log('Removed:', removed);
});

list.value.push(4); // Logs added: [4]
list.value.splice(0, 1); // Logs removed: [1]

Convenience Watchers

Several watch utilities provide common configurations:

/**
 * Watch with deep: true
 */
function watchDeep<T>(
  source: WatchSource<T>, 
  cb: WatchCallback<T>, 
  options?: WatchOptions
): WatchStopHandle;

/**
 * Watch with immediate: true
 */
function watchImmediate<T>(
  source: WatchSource<T>, 
  cb: WatchCallback<T>, 
  options?: WatchOptions
): WatchStopHandle;

Install with Tessl CLI