@vueuse/shared 6.7.6 → 6.9.2

package/index.d.ts

@@ -31,10 +31,14 @@ declare type MaybeRef<T> = T | Ref<T>;
 /**
  * A ref that allow to set null or undefined
  */
-declare type RemoveableRef<T> = Omit<Ref<T>, 'value'> & {
+declare type RemovableRef<T> = Omit<Ref<T>, 'value'> & {
     get value(): T;
     set value(value: T | null | undefined);
 };
+/**
+ * @deprecated Use `RemovableRef`
+ */
+declare type RemoveableRef<T> = RemovableRef<T>;
 /**
  * Make all the nested attributes of an object or array to MaybeRef<T>
  *
@@ -66,9 +70,9 @@ interface Pausable {
      */
     resume: Fn;
 }
-interface Stopable {
+interface Stoppable {
     /**
-     * A ref indicate whether a stopable instance is executing
+     * A ref indicate whether a stoppable instance is executing
      */
     isPending: Ref<boolean>;
     /**
@@ -80,6 +84,10 @@ interface Stopable {
      */
     start: Fn;
 }
+/**
+ * @deprecated Use `Stoppable`
+ */
+declare type Stopable = Stoppable;
 interface ConfigurableFlush {
     /**
      * Timing for monitoring changes, refer to WatchOptions for more details
@@ -119,6 +127,13 @@ interface ConfigurableEventFilter {
      */
     eventFilter?: EventFilter;
 }
+interface DebounceFilterOptions {
+    /**
+     * The maximum time allowed to be delayed before it's invoked.
+     * In milliseconds.
+     */
+    maxWait?: number;
+}
 /**
  * @internal
  */
@@ -128,8 +143,9 @@ declare const bypassFilter: EventFilter;
  * Create an EventFilter that debounce the events
  *
  * @param ms
+ * @param [maxWait=null]
  */
-declare function debounceFilter(ms: MaybeRef<number>): EventFilter<any[], any>;
+declare function debounceFilter(ms: MaybeRef<number>, options?: DebounceFilterOptions): EventFilter<any[], any>;
 /**
  * Create an EventFilter that throttle the events
  *
@@ -271,6 +287,18 @@ declare type CreateGlobalStateReturn<T> = () => T;
  */
 declare function createGlobalState<T>(stateFactory: () => T): CreateGlobalStateReturn<T>;
 
+declare type Reactify<T> = T extends (...args: infer A) => infer R ? (...args: {
+    [K in keyof A]: MaybeRef<A[K]>;
+}) => ComputedRef<R> : never;
+/**
+ * Converts plain function into a reactive function.
+ * The converted function accepts refs as it's arguments
+ * and returns a ComputedRef, with proper typing.
+ *
+ * @param fn - Source function
+ */
+declare function reactify<T extends Function>(fn: T): Reactify<T>;
+
 /**
  * Make a composable function usable with multiple Vue instances.
  *
@@ -278,6 +306,13 @@ declare function createGlobalState<T>(stateFactory: () => T): CreateGlobalStateR
  */
 declare function createSharedComposable<Fn extends ((...args: any[]) => any)>(composable: Fn): Fn;
 
+/**
+ * Debounce updates of a ref.
+ *
+ * @return A new debounced ref.
+ */
+declare function useDebounce<T>(value: Ref<T>, ms?: number, options?: DebounceFilterOptions): Readonly<Ref<T>>;
+
 interface DebouncedWatchOptions<Immediate> extends WatchOptions<Immediate> {
     debounce?: MaybeRef<number>;
 }
@@ -359,18 +394,6 @@ declare function pausableWatch<T extends Readonly<WatchSource<unknown>[]>, Immed
 declare function pausableWatch<T, Immediate extends Readonly<boolean> = false>(source: WatchSource<T>, cb: WatchCallback<T, Immediate extends true ? T | undefined : T>, options?: WatchWithFilterOptions<Immediate>): PausableWatchReturn;
 declare function pausableWatch<T extends object, Immediate extends Readonly<boolean> = false>(source: T, cb: WatchCallback<T, Immediate extends true ? T | undefined : T>, options?: WatchWithFilterOptions<Immediate>): PausableWatchReturn;
 
-declare type Reactify<T> = T extends (...args: infer A) => infer R ? (...args: {
-    [K in keyof A]: MaybeRef<A[K]>;
-}) => ComputedRef<R> : never;
-/**
- * Converts plain function into a reactive function.
- * The converted function accepts refs as it's arguments
- * and returns a ComputedRef, with proper typing.
- *
- * @param fn - Source function
- */
-declare function reactify<T extends Function>(fn: T): Reactify<T>;
-
 declare type ReactifyNested<T, Keys extends keyof T = keyof T> = {
     [K in Keys]: T[K] extends (...args: any[]) => any ? Reactify<T[K]> : T[K];
 };
@@ -428,7 +451,18 @@ interface SyncRefOptions extends ConfigurableFlushSync {
  * @param source source ref
  * @param targets
  */
-declare function syncRef<R extends Ref<any>>(source: R, targets: R | R[], { flush, deep, immediate, }?: SyncRefOptions): vue_demi.WatchStopHandle;
+declare function syncRef<T>(source: WatchSource<T>, targets: Ref<T> | Ref<T>[], { flush, deep, immediate, }?: SyncRefOptions): vue_demi.WatchStopHandle;
+
+/**
+ * Throttle execution of a function. Especially useful for rate limiting
+ * execution of handlers on events like resize and scroll.
+ *
+ * @param value Ref value to be watched with throttle effect
+ * @param  delay  A zero-or-greater delay in milliseconds. For event callbacks, values around 100 or 250 (or even higher) are most useful.
+ * @param [trailing=true] if true, update the value again after the delay time is up
+ * @param [leading=true] if true, update the value on the leading edge of the ms timeout
+ */
+declare function useThrottle<T>(value: Ref<T>, delay?: number, trailing?: boolean, leading?: boolean): Ref<T>;
 
 interface ThrottledWatchOptions<Immediate> extends WatchOptions<Immediate> {
     throttle?: MaybeRef<number>;
@@ -544,13 +578,18 @@ interface UntilArrayInstance<T> extends UntilBaseInstance<T> {
 declare function until<T extends unknown[]>(r: WatchSource<T> | MaybeRef<T>): UntilArrayInstance<T>;
 declare function until<T>(r: WatchSource<T> | MaybeRef<T>): UntilValueInstance<T>;
 
+interface UseCounterOptions {
+    min?: number;
+    max?: number;
+}
 /**
  * Basic counter with utility functions.
  *
  * @see https://vueuse.org/useCounter
  * @param [initialValue=0]
+ * @param {Object} options
  */
-declare function useCounter(initialValue?: number): {
+declare function useCounter(initialValue?: number, options?: UseCounterOptions): {
     count: vue_demi.Ref<number>;
     inc: (delta?: number) => number;
     dec: (delta?: number) => number;
@@ -559,17 +598,16 @@ declare function useCounter(initialValue?: number): {
     reset: (val?: number) => number;
 };
 
-declare function useDebounce<T>(value: Ref<T>, ms?: number): Readonly<Ref<T>>;
-
 /**
  * Debounce execution of a function.
  *
  * @param  fn          A function to be executed after delay milliseconds debounced.
  * @param  ms          A zero-or-greater delay in milliseconds. For event callbacks, values around 100 or 250 (or even higher) are most useful.
+ * @param  opts        options
  *
  * @return A new, debounce, function.
  */
-declare function useDebounceFn<T extends FunctionArgs>(fn: T, ms?: MaybeRef<number>): T;
+declare function useDebounceFn<T extends FunctionArgs>(fn: T, ms?: MaybeRef<number>, options?: DebounceFilterOptions): T;
 
 interface IntervalOptions<Controls extends boolean> {
     /**
@@ -625,17 +663,6 @@ declare function useLastChanged(source: WatchSource, options?: UseLastChangedOpt
 declare function useLastChanged(source: WatchSource, options: UseLastChangedOptions<true>): Ref<number>;
 declare function useLastChanged(source: WatchSource, options: UseLastChangedOptions<boolean, number>): Ref<number>;
 
-/**
- * Throttle execution of a function. Especially useful for rate limiting
- * execution of handlers on events like resize and scroll.
- *
- * @param value Ref value to be watched with throttle effect
- * @param  delay  A zero-or-greater delay in milliseconds. For event callbacks, values around 100 or 250 (or even higher) are most useful.
- * @param [trailing=true] if true, update the value again after the delay time is up
- * @param [leading=true] if true, update the value on the leading edge of the ms timeout
- */
-declare function useThrottle<T>(value: Ref<T>, delay?: number, trailing?: boolean, leading?: boolean): Ref<T>;
-
 /**
  * Throttle execution of a function. Especially useful for rate limiting
  * execution of handlers on events like resize and scroll.
@@ -667,7 +694,7 @@ interface TimeoutFnOptions {
  * @param interval
  * @param immediate
  */
-declare function useTimeoutFn(cb: (...args: unknown[]) => any, interval: MaybeRef<number>, options?: TimeoutFnOptions): Stopable;
+declare function useTimeoutFn(cb: (...args: unknown[]) => any, interval: MaybeRef<number>, options?: TimeoutFnOptions): Stoppable;
 
 interface TimeoutOptions<Controls extends boolean> extends TimeoutFnOptions {
     /**
@@ -687,7 +714,7 @@ interface TimeoutOptions<Controls extends boolean> extends TimeoutFnOptions {
 declare function useTimeout(interval?: number, options?: TimeoutOptions<false>): ComputedRef<boolean>;
 declare function useTimeout(interval: number, options: TimeoutOptions<true>): {
     ready: ComputedRef<boolean>;
-} & Stopable;
+} & Stoppable;
 
 /**
  * A boolean ref with a toggler
@@ -720,4 +747,4 @@ declare function watchOnce<T, Immediate extends Readonly<boolean> = false>(sourc
  */
 declare function whenever<T>(source: WatchSource<T>, cb: WatchCallback, options?: WatchOptions): vue_demi.WatchStopHandle;
 
-export { ConfigurableEventFilter, ConfigurableFlush, ConfigurableFlushSync, ControlledRefOptions, CreateGlobalStateReturn, DebouncedWatchOptions, DeepMaybeRef, ElementOf, EventFilter, EventHook, EventHookOff, EventHookOn, EventHookTrigger, ExtendRefOptions, Fn, FunctionArgs, FunctionWrapperOptions, IgnorableWatchReturn, IgnoredUpdater, IntervalFnOptions, IntervalOptions, MapOldSources, MapSources, MaybeRef, Pausable, PausableWatchReturn, Reactify, ReactifyNested, ReactifyObjectOptions, RemoveableRef, ShallowUnwrapRef, SingletonPromiseReturn, Stopable, SyncRefOptions, ThrottledWatchOptions, TimeoutFnOptions, TimeoutOptions, UntilArrayInstance, UntilBaseInstance, UntilToMatchOptions, UntilValueInstance, UseLastChangedOptions, WatchAtMostOptions, WatchAtMostReturn, WatchWithFilterOptions, and, assert, biSyncRef, bypassFilter, clamp, containsProp, controlledComputed, controlledRef, createEventHook, createFilterWrapper, createGlobalState, createSharedComposable, createSingletonPromise, debounceFilter, debouncedWatch, eagerComputed, extendRef, get, identity, ignorableWatch, increaseWithUnit, invoke, isBoolean, isClient, isDef, isDefined, isFunction, isNumber, isObject, isString, isWindow, makeDestructurable, noop, not, now, objectPick, or, pausableFilter, pausableWatch, promiseTimeout, rand, reactify, reactifyObject, reactivePick, refDefault, set, syncRef, throttleFilter, throttledWatch, timestamp, toReactive, toRefs, tryOnBeforeUnmount, tryOnMounted, tryOnScopeDispose, tryOnUnmounted, until, useCounter, useDebounce, useDebounceFn, useInterval, useIntervalFn, useLastChanged, useThrottle, useThrottleFn, useTimeout, useTimeoutFn, useToggle, watchAtMost, watchOnce, watchWithFilter, whenever };
+export { ConfigurableEventFilter, ConfigurableFlush, ConfigurableFlushSync, ControlledRefOptions, CreateGlobalStateReturn, DebounceFilterOptions, DebouncedWatchOptions, DeepMaybeRef, ElementOf, EventFilter, EventHook, EventHookOff, EventHookOn, EventHookTrigger, ExtendRefOptions, Fn, FunctionArgs, FunctionWrapperOptions, IgnorableWatchReturn, IgnoredUpdater, IntervalFnOptions, IntervalOptions, MapOldSources, MapSources, MaybeRef, Pausable, PausableWatchReturn, Reactify, ReactifyNested, ReactifyObjectOptions, RemovableRef, RemoveableRef, ShallowUnwrapRef, SingletonPromiseReturn, Stopable, Stoppable, SyncRefOptions, ThrottledWatchOptions, TimeoutFnOptions, TimeoutOptions, UntilArrayInstance, UntilBaseInstance, UntilToMatchOptions, UntilValueInstance, UseCounterOptions, UseLastChangedOptions, WatchAtMostOptions, WatchAtMostReturn, WatchWithFilterOptions, and, assert, biSyncRef, bypassFilter, clamp, containsProp, controlledComputed, controlledRef, createEventHook, createFilterWrapper, createGlobalState, reactify as createReactiveFn, createSharedComposable, createSingletonPromise, debounceFilter, useDebounce as debouncedRef, debouncedWatch, eagerComputed, extendRef, get, identity, ignorableWatch, increaseWithUnit, invoke, isBoolean, isClient, isDef, isDefined, isFunction, isNumber, isObject, isString, isWindow, makeDestructurable, noop, not, now, objectPick, or, pausableFilter, pausableWatch, promiseTimeout, rand, reactify, reactifyObject, reactivePick, refDefault, set, syncRef, throttleFilter, useThrottle as throttledRef, throttledWatch, timestamp, toReactive, toRefs, tryOnBeforeUnmount, tryOnMounted, tryOnScopeDispose, tryOnUnmounted, until, useCounter, useDebounce, useDebounceFn, useInterval, useIntervalFn, useLastChanged, useThrottle, useThrottleFn, useTimeout, useTimeoutFn, useToggle, watchAtMost, watchOnce, watchWithFilter, whenever };