tessl/npm-vueuse--shared
Collection of essential shared Vue Composition Utilities providing foundational building blocks for reactive Vue applications
- Workspace
- tessl
- Visibility
- Public
- Created
- Last updated
- Describes
To install, run
npx @tessl/cli install tessl/npm-vueuse--shared@13.9.0index.mddocs/
@vueuse/shared
@vueuse/shared is a collection of essential shared Vue Composition API utilities that serve as foundational building blocks for reactive Vue applications. It provides comprehensive state management utilities, reactivity helpers, array manipulation functions, timing utilities, and extensive watch utilities for building modern Vue applications.
Package Information
- Package Name: @vueuse/shared
- Package Type: npm
- Language: TypeScript
- Installation:
npm install @vueuse/shared - Peer Dependencies: Vue 3.5.0+
Core Imports
import {
createGlobalState,
reactify,
syncRef,
useCounter,
whenever
} from "@vueuse/shared";For CommonJS:
const {
createGlobalState,
reactify,
syncRef,
useCounter,
whenever
} = require("@vueuse/shared");Basic Usage
import {
createGlobalState,
syncRef,
useCounter,
whenever,
ref
} from "@vueuse/shared";
// Global state management
const useGlobalCounter = createGlobalState(() => ref(0));
const counter = useGlobalCounter();
// Counter utility with controls
const { count, inc, dec, set, reset } = useCounter(0);
// Ref synchronization
const source = ref('hello');
const target = ref('');
syncRef(source, target); // target will sync with source
// Conditional watching
whenever(count, (value) => {
console.log(`Counter is now: ${value}`);
});Architecture
@vueuse/shared is built around several key architectural patterns:
- Composable Functions: Vue 3 Composition API functions that encapsulate reactive logic
- Global State Management: Utilities for sharing state across component boundaries
- Reactive Programming: Functions that work seamlessly with Vue's reactivity system
- Type Safety: Full TypeScript support with comprehensive type definitions
- Tree Shaking: Modular exports enabling optimal bundle sizes
- Watch Extensions: Enhanced watching capabilities beyond Vue's built-in watchers
Capabilities
State Management
Global and injectable state utilities for sharing reactive state across components and composables.
function createGlobalState<T>(stateFactory: () => T): () => T;
function createInjectionState<Args, Return>(
composable: (...args: Args) => Return
): [
useProvidingState: (...args: Args) => Return,
useInjectedState: () => Return | undefined
];Reactivity Utilities
Core utilities for working with Vue's reactivity system, including conversion between refs and reactive objects.
function reactify<T>(fn: T, options?: ReactifyOptions<boolean>): ReactifyReturn<T>;
function toReactive<T>(objectRef: MaybeRef<T>): T;
function syncRef<L, R>(left: Ref<L>, right: Ref<R>, options?: SyncRefOptions): () => void;Ref Utilities
Enhanced ref utilities with automatic behaviors like debouncing, throttling, and automatic reset.
function refDebounced<T>(
value: Ref<T>,
ms?: number,
options?: DebounceFilterOptions
): Readonly<Ref<T>>;
function refAutoReset<T>(defaultValue: T, afterMs?: number): Ref<T>;
function extendRef<T, Extend>(
ref: Ref<T>,
extend: Extend,
options?: ExtendRefOptions
): ShallowUnwrapRef<Extend> & Ref<T>;Array Utilities
Reactive versions of native Array methods that work with Vue's reactivity system.
function useArrayFilter<T>(
list: MaybeRefOrGetter<T[]>,
fn: (element: T, index: number, array: T[]) => boolean
): ComputedRef<T[]>;
function useArrayMap<T, U>(
list: MaybeRefOrGetter<T[]>,
fn: (element: T, index: number, array: T[]) => U
): ComputedRef<U[]>;
function useArrayReduce<T, U>(
list: MaybeRefOrGetter<T[]>,
reducer: (previous: U, current: T, index: number, array: T[]) => U,
initialValue: MaybeRefOrGetter<U>
): ComputedRef<U>;Time & Async Utilities
Utilities for handling timeouts, intervals, debouncing, throttling, and date formatting with reactive controls.
function useTimeout(interval: number, options?: UseTimeoutOptions): UseTimeoutReturn;
function useInterval(interval?: number, options?: UseIntervalOptions): UseIntervalReturn;
function useDebounceFn<T>(
fn: T,
ms?: MaybeRefOrGetter<number>,
options?: DebounceFilterOptions
): DebouncedFn<T>;
function useDateFormat(
date: MaybeRefOrGetter<DateLike>,
formatStr?: MaybeRefOrGetter<string>,
options?: UseDateFormatOptions
): UseDateFormatReturn;Watch Utilities
Enhanced watching capabilities including debounced, throttled, pausable, and conditional watchers.
function watchDebounced<T>(
source: WatchSource<T>,
cb: WatchCallback<T>,
options?: WatchDebouncedOptions
): WatchStopHandle;
function watchPausable<T>(
source: WatchSource<T>,
cb: WatchCallback<T>,
options?: WatchPausableOptions
): WatchPausableReturn;
function whenever<T>(
source: WatchSource<T | false | null | undefined>,
cb: WatchCallback<T>,
options?: WatchOptions
): WatchStopHandle;Computed Utilities
Enhanced computed utilities with manual control and eager evaluation options.
function computedEager<T>(fn: () => T): Readonly<Ref<T>>;
function computedWithControl<T, S>(
source: WatchSource<S> | WatchSource<S>[],
fn: () => T
): ComputedWithControl<T>;Common Utilities
General purpose utilities including counters, toggles, type conversions, and lifecycle helpers.
function useCounter(initialValue?: number, options?: UseCounterOptions): UseCounterReturn;
function useToggle(initialValue?: boolean): UseToggleReturn;
function get<T>(obj: MaybeRefOrGetter<T>): T;
function set<T>(ref: Ref<T> | ((val: T) => void), value: T): void;Utilities
Core utility functions including filters, type checking, promise helpers, and general-purpose functions that support VueUse shared functionality.
function debounceFilter(ms: MaybeRefOrGetter<number>, options?: DebounceFilterOptions): EventFilter;
function throttleFilter(ms: MaybeRefOrGetter<number>, trailing?: boolean, leading?: boolean, rejectOnCancel?: boolean): EventFilter;
function pausableFilter(extendFilter?: EventFilter): Pausable & { eventFilter: EventFilter };
const isClient: boolean;
const isWorker: boolean;
function isDef<T = any>(val?: T): val is T;
function notNullish<T = any>(val?: T | null | undefined): val is T;
function promiseTimeout(ms: number, throwOnTimeout?: boolean, reason?: string): Promise<void>;
function createSingletonPromise<T>(fn: () => Promise<T>): SingletonPromiseReturn<T>;Core Types
type MaybeRef<T> = T | Ref<T>;
type MaybeRefOrGetter<T> = T | Ref<T> | (() => T);
type Fn = () => void;
type AnyFn = (...args: any[]) => any;
type RemovableRef<T> = Omit<Ref<T>, 'value'> & {
get value(): T;
set value(value: T | null | undefined);
};
type ReadonlyRefOrGetter<T> = ComputedRef<T> | (() => T);
type DeepMaybeRef<T> = T extends Ref<infer V>
? MaybeRef<V>
: T extends Array<any> | object
? { [K in keyof T]: DeepMaybeRef<T[K]> }
: MaybeRef<T>;
type Arrayable<T> = T[] | T;
type ElementOf<T> = T extends (infer E)[] ? E : never;
type ShallowUnwrapRef<T> = T extends Ref<infer P> ? P : T;
type Awaitable<T> = Promise<T> | T;
type ArgumentsType<T> = T extends (...args: infer U) => any ? U : never;
type Promisify<T> = Promise<Awaited<T>>;
type PromisifyFn<T extends AnyFn> = (...args: ArgumentsType<T>) => Promisify<ReturnType<T>>;
type TimerHandle = ReturnType<typeof setTimeout> | undefined;
interface Pausable {
readonly isActive: Readonly<ShallowRef<boolean>>;
pause: Fn;
resume: Fn;
}
interface Stoppable<StartFnArgs extends any[] = any[]> {
readonly isPending: Readonly<Ref<boolean>>;
stop: Fn;
start: (...args: StartFnArgs) => void;
}
interface ConfigurableFlush {
flush?: WatchOptions['flush'];
}
interface ConfigurableFlushSync {
flush?: WatchOptions['flush'];
}
type MultiWatchSources = (WatchSource<unknown> | object)[];
type MapSources<T> = {
[K in keyof T]: T[K] extends WatchSource<infer V> ? V : never;
};
type MapOldSources<T, Immediate> = {
[K in keyof T]: T[K] extends WatchSource<infer V> ? Immediate extends true ? V | undefined : V : never;
};
type Mutable<T> = { -readonly [P in keyof T]: T[P] };
type IfAny<T, Y, N> = 0 extends (1 & T) ? Y : N;
type IsAny<T> = IfAny<T, true, false>;