@vueuse/shared 6.3.2 → 6.5.3

package/index.d.ts

@@ -1,6 +1,5 @@
 import * as vue_demi from 'vue-demi';
 import { Ref, WatchOptions, WatchSource, ComputedRef, WatchCallback, WatchStopHandle, ShallowUnwrapRef as ShallowUnwrapRef$1, UnwrapRef, ToRefs } from 'vue-demi';
-import { Pausable as Pausable$1 } from '@vueuse/core';
 
 declare const isClient: boolean;
 declare const isDef: <T = any>(val?: T | undefined) => val is T;
@@ -29,6 +28,13 @@ declare type Fn = () => void;
  * ```
  */
 declare type MaybeRef<T> = T | Ref<T>;
+/**
+ * A ref that allow to set null or undefined
+ */
+declare type RemoveableRef<T> = Omit<Ref<T>, 'value'> & {
+    get value(): T;
+    set value(value: T | null | undefined);
+};
 /**
  * Make all the nested attributes of an object or array to MaybeRef<T>
  *
@@ -106,6 +112,11 @@ interface FunctionWrapperOptions<Args extends any[] = any[], This = any> {
 }
 declare type EventFilter<Args extends any[] = any[], This = any> = (invoke: Fn, options: FunctionWrapperOptions<Args, This>) => void;
 interface ConfigurableEventFilter {
+    /**
+     * Filter for if events should to be received.
+     *
+     * @see https://vueuse.org/guide/config.html#event-filters
+     */
     eventFilter?: EventFilter;
 }
 /**
@@ -124,8 +135,9 @@ declare function debounceFilter(ms: MaybeRef<number>): EventFilter<any[], any>;
  *
  * @param ms
  * @param [trailing=true]
+ * @param [leading=true]
  */
-declare function throttleFilter(ms: MaybeRef<number>, trailing?: boolean): EventFilter<any[], any>;
+declare function throttleFilter(ms: MaybeRef<number>, trailing?: boolean, leading?: boolean): EventFilter<any[], any>;
 /**
  * EventFilter that gives extra controls to pause and resume the filter
  *
@@ -562,7 +574,7 @@ interface IntervalOptions<Controls extends boolean> {
 declare function useInterval(interval?: number, options?: IntervalOptions<false>): Ref<number>;
 declare function useInterval(interval: number, options: IntervalOptions<true>): {
     counter: Ref<number>;
-} & Pausable$1;
+} & Pausable;
 
 interface IntervalFnOptions {
     /**
@@ -603,9 +615,12 @@ declare function useLastChanged(source: WatchSource, options: UseLastChangedOpti
  * 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): Ref<T>;
+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
@@ -615,9 +630,13 @@ declare function useThrottle<T>(value: Ref<T>, delay?: number): Ref<T>;
  *                                    to `callback` when the throttled-function is executed.
  * @param   ms             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, call fn again after the time is up
+ *
+ * @param [leading=true] if true, call fn on the leading edge of the ms timeout
+ *
  * @return  A new, throttled, function.
  */
-declare function useThrottleFn<T extends FunctionArgs>(fn: T, ms?: MaybeRef<number>, trailing?: boolean): T;
+declare function useThrottleFn<T extends FunctionArgs>(fn: T, ms?: MaybeRef<number>, trailing?: boolean, leading?: boolean): T;
 
 interface TimeoutFnOptions {
     /**
@@ -665,6 +684,21 @@ declare function useTimeout(interval: number, options: TimeoutOptions<true>): {
 declare function useToggle(value: Ref<boolean>): (value?: boolean) => boolean;
 declare function useToggle(initialValue?: boolean): [Ref<boolean>, (value?: boolean) => boolean];
 
+interface WatchAtMostOptions<Immediate> extends WatchWithFilterOptions<Immediate> {
+    count: MaybeRef<number>;
+}
+interface WatchAtMostReturn {
+    stop: WatchStopHandle;
+    count: Ref<number>;
+}
+declare function watchAtMost<T extends Readonly<WatchSource<unknown>[]>, Immediate extends Readonly<boolean> = false>(source: T, cb: WatchCallback<MapSources<T>, MapOldSources<T, Immediate>>, options: WatchAtMostOptions<Immediate>): WatchAtMostReturn;
+declare function watchAtMost<T extends Readonly<WatchSource<unknown>[]>, Immediate extends Readonly<boolean> = false>(source: T, cb: WatchCallback<MapSources<T>, MapOldSources<T, Immediate>>, options: WatchAtMostOptions<Immediate>): WatchAtMostReturn;
+declare function watchAtMost<T, Immediate extends Readonly<boolean> = false>(sources: WatchSource<T>, cb: WatchCallback<T, Immediate extends true ? T | undefined : T>, options: WatchAtMostOptions<Immediate>): WatchAtMostReturn;
+
+declare function watchOnce<T extends Readonly<WatchSource<unknown>[]>, Immediate extends Readonly<boolean> = false>(source: T, cb: WatchCallback<MapSources<T>, MapOldSources<T, Immediate>>, options?: WatchOptions<Immediate>): void;
+declare function watchOnce<T extends Readonly<WatchSource<unknown>[]>, Immediate extends Readonly<boolean> = false>(source: T, cb: WatchCallback<MapSources<T>, MapOldSources<T, Immediate>>, options?: WatchOptions<Immediate>): void;
+declare function watchOnce<T, Immediate extends Readonly<boolean> = false>(sources: WatchSource<T>, cb: WatchCallback<T, Immediate extends true ? T | undefined : T>, options?: WatchOptions<Immediate>): void;
+
 /**
  * Shorthand for watching value to be truthy
  *
@@ -672,4 +706,4 @@ declare function useToggle(initialValue?: boolean): [Ref<boolean>, (value?: bool
  */
 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, ShallowUnwrapRef, SingletonPromiseReturn, Stopable, SyncRefOptions, ThrottledWatchOptions, TimeoutFnOptions, TimeoutOptions, UntilArrayInstance, UntilBaseInstance, UntilToMatchOptions, UntilValueInstance, UseLastChangedOptions, 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, isFunction, isNumber, isObject, isString, isWindow, makeDestructurable, noop, not, now, objectPick, or, pausableFilter, pausableWatch, promiseTimeout, rand, reactify, reactifyObject, reactivePick, set, syncRef, throttleFilter, throttledWatch, timestamp, toReactive, toRefs, tryOnBeforeUnmount, tryOnMounted, tryOnScopeDispose, tryOnUnmounted, until, useCounter, useDebounce, useDebounceFn, useInterval, useIntervalFn, useLastChanged, useThrottle, useThrottleFn, useTimeout, useTimeoutFn, useToggle, watchWithFilter, whenever };
+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, isFunction, isNumber, isObject, isString, isWindow, makeDestructurable, noop, not, now, objectPick, or, pausableFilter, pausableWatch, promiseTimeout, rand, reactify, reactifyObject, reactivePick, 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 };