vueposu/index.d.ts

A hooks library based on Vue Composition-API

import type { CounterNumber } from '@vueposu/utils';
import type { DebouncedFunc } from 'lodash-es';
import { DeepReadonly } from 'vue-demi';
import type { Fn } from '@vueposu/utils';
import { Ref } from 'vue-demi';
import { Ref as Ref_2 } from 'vue';
import type { RefTyped } from '@vueposu/utils';
import * as swr_2 from '@vueposu/swr';
import type { Target } from '@vueposu/utils';
import type { ToRefs } from 'vue-demi';
import type { UnwrapRef } from 'vue-demi';
import { useSWR } from '@vueposu/swr';
import { useSWRGlobalConfig } from '@vueposu/swr';
import type { WatchCallback } from 'vue-demi';
import type { WatchSource } from 'vue-demi';
import type { WatchStopHandle } from 'vue-demi';

declare interface CounterOptions {
    min?: CounterNumber;
    max?: CounterNumber;
    step?: CounterNumber;
}

declare type EventType = MouseEvent | TouchEvent;

declare type Listener = (...stream: any[]) => void;

declare interface MouseCursorState {
    pageX: number;
    pageY: number;
    screenX: number;
    screenY: number;
    clientX: number;
    clientY: number;
}

export declare interface QueueMethodsReturnType<T> {
    add: (item: T) => void;
    remove: () => T;
    first: T;
    last: T;
    reset: () => void;
    empty: () => void;
    size: number;
}

declare interface ScrollState {
    x: number;
    y: number;
}

declare type ScrollTarget = HTMLElement | Document;

declare interface SetActions<K> {
    add: (key: K) => void;
    remove: (key: K) => void;
    has: (key: K) => boolean;
    reset: () => void;
    clear: () => void;
}

export declare const swr: {
    cache: {
        get: ($key: swr_2.SWRKey) => any;
        set: ($key: swr_2.SWRKey, value: any) => void;
        del: ($key: swr_2.SWRKey) => void;
        has: ($key: swr_2.SWRKey) => boolean;
        clear: () => void;
        keys: () => any[];
        serializeKey: (key: swr_2.SWRKey) => [string, any, string, string];
    };
    trigger: ($key: swr_2.SWRKey, shouldRevalidate?: boolean) => Promise<any>;
    mutate: swr_2.Mutate<any>;
};

/**
 * useClickOutside function
 *
 * @param target Execution handler target.
 * @param eventHandler Handler function on external click.
 * @param eventName Event trigger. default `click`.
 */
export declare function useClickOutside(target: Target | Target[], eventHandler: RefTyped<(event: EventType) => void>, eventName?: RefTyped<string | string[]>): WatchStopHandle;

export declare function useClipboard(): UseClipboardReturnType;

export declare type UseClipboardReturnType = {
    copy: (text: string) => Promise<void>;
    text: Ref<string>;
    supported: boolean;
};

export declare function useCookie(): void;

export declare type useCookieActions<T> = [
T,
    {
    set: () => void;
    reset: () => void;
    remove: () => void;
}
];

export declare interface useCookieOptions<T> {
    key: string;
    value: T;
    defaultValue: T;
    expires: string;
    path: string;
    domain: string;
    secure: boolean;
    sameSite: 'strict' | 'lax' | 'none';
}

export declare function useCounter(initialValue?: CounterNumber, options?: CounterOptions): UseCounterReturnType;

declare type UseCounterActions = {
    inc: (n?: CounterNumber) => void;
    dec: (n?: CounterNumber) => void;
    set: (value: CounterNumber | ((currentValue: number) => number)) => void;
    reset: () => void;
};

export declare function useCounterInterval(options?: UseCounterIntervalOptions): UseCounterIntervalReturnType;

declare type UseCounterIntervalActions = {
    start: () => void;
    stop: () => void;
};

declare interface UseCounterIntervalOptions {
    initialValue?: CounterNumber;
    type?: RefTyped<"inc" | "dec">;
    step?: RefTyped<number>;
    total?: RefTyped<number>;
    interval?: RefTyped<number>;
    immediateStart?: RefTyped<boolean>;
}

declare type UseCounterIntervalReturnType = {
    count: CounterNumber;
    isActive: Ref<boolean>;
} & UseCounterIntervalActions;

declare type UseCounterReturnType = {
    count: Ref<number>;
} & UseCounterActions;

export declare function useDebounce<T>(value: Ref<T>, wait?: RefTyped<number>): Readonly<Ref<DeepReadonly<T>>>;

export declare function useDebounceEffect<T>(listener: WatchCallback<T, T>, deps: WatchSource<T>, wait?: RefTyped<number>): void;

export declare function useDebounceEffect<T extends object>(listener: WatchCallback<T, T>, deps: T, wait?: RefTyped<number>): void;

/**
 * useDebounceFn function
 * @param callback The function or a promise to debounce.
 * @param wait The number of milliseconds to delay.
 *
 * @returns debounced ref function
 * @returns debounced.value.cancel function
 * @returns debounced.value.flush function
 */
export declare function useDebounceFn<T extends Fn>(callback: T, wait?: RefTyped<number>): Readonly<Ref<DebouncedFunc<T>>>;

export declare function useDynamicList<T extends Array<unknown>, S = T[number]>(initValue?: T | undefined[]): UseDynamicListReturnType<T, S>;

export declare interface UseDynamicListActions<S> {
    move(to: number, from: number): void;
    insert(index: number, n: S): void;
    insertBefore(index: number, n: S): void;
    insertAfter(index: number, val: S): void;
    remove(index: number): void;
    replace(to: number, from: number): void;
    unshift(...items: S[]): void;
    shift(): void;
    pop(): void;
    push(val: S): void;
}

export declare type UseDynamicListReturnType<T, S> = {
    list: Ref<T>;
} & UseDynamicListActions<S>;

export declare function useEventEmitter(): UseEventEmitterReturnType;

declare type UseEventEmitterReturnType = {
    emit: (...args: any[]) => void;
    on: (listener: Listener) => void;
};

export declare function useEventListener<K extends keyof WindowEventMap>(target: Window, type: RefTyped<K>, listener: (this: Window, ev: WindowEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;

export declare function useEventListener(type: RefTyped<string>, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;

export declare function useEventListener<K extends keyof DocumentEventMap>(target: Document, type: RefTyped<K>, listener: (this: Document, ev: DocumentEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;

export declare function useEventListener<K extends keyof HTMLElementEventMap>(target: HTMLElement, type: RefTyped<K>, listener: (this: HTMLElement, ev: HTMLElementEventMap[K]) => any, options?: boolean | AddEventListenerOptions): void;

export declare function useEventListener(target: Target<HTMLElement | Document>, type: RefTyped<string>, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;

/**
 * useFavicon - change site icon
 *
 * @param url favicon url
 */
export declare function useFavicon(url?: string): UseFaviconReturnType;

declare type UseFaviconReturnType = {
    changeIcon: (url: string) => void;
    restoreIcon: () => void;
};

export declare function useFullscreen<T extends HTMLElement>(target: T, onFullscreenStatusChange?: () => void): UseFullscreenReturnType;

declare type UseFullscreenReturnType = {
    isFullscreen: Ref<boolean>;
    enterFullscreen: () => void;
    exitFullscreen: () => void;
    toggleFullscreen: (status?: RefTyped<boolean>) => void;
};

export declare function useInterval(callback: () => void, interval?: RefTyped<number>, immediate?: RefTyped<boolean>): UseIntervalReturnType;

declare type UseIntervalReturnType = {
    isActive: Ref<boolean>;
    start: () => void;
    stop: () => void;
};

export declare function useLocalStorage<T>(key: string, defaultValue?: T): Ref_2<T | null> | {
    value: null;
};

export declare function useMouse(): ToRefs<Readonly<MouseCursorState>>;

/**
 * usePageHidden function
 * when user `leave`/`back` current tab will trigger this hook
 * always execute the last one
 *
 * @param onHiddenStatusChange change handler function for usePageHidden
 */
export declare function usePageHidden(): Ref<boolean>;

export declare function useQueue<T>(initialValue?: T[]): QueueMethodsReturnType<T>;

export declare function useRequest(url: string, init?: RequestInit): Promise<any>;

export declare function useScroll(target?: Target<ScrollTarget>): ToRefs<Readonly<ScrollState>>;

export declare function useSessionStorage<T>(key: string, defaultValue?: T): Ref_2<T | null> | {
    value: null;
};

export declare function useSet<K = any>(initialSet?: RefTyped<Iterable<K>>): UseSetReturnType<K>;

declare type UseSetReturnType<K> = {
    set: DeepReadonly<Ref<Set<K>>>;
} & SetActions<K>;

export declare function useStorage<T>(key: string, defaultValue?: T, storage?: Storage): Ref<T | null> | {
    value: null;
};

export { useSWR }

export { useSWRGlobalConfig }

export declare function useThrottle<T>(value: Ref<T>, wait?: RefTyped<number>): any;

export declare function useThrottleEffect<T>(listener: WatchCallback<T, T>, deps: WatchSource<T>, wait?: RefTyped<number>): void;

export declare function useThrottleEffect<T extends object>(listener: WatchCallback<T, T>, deps: T, wait?: RefTyped<number>): void;

/**
 * useThrottleFn function
 * @param callback The function or a promise to debounce.
 * @param wait The number of milliseconds to delay.
 *
 * @returns throttled function
 * @returns throttled.cancel function
 * @returns throttled.flush function
 */
export declare function useThrottleFn<T extends Fn>(callback: T, wait?: RefTyped<number>): Readonly<Ref<DebouncedFunc<T>>>;

export declare function useTimeout(callback: () => void, timeout?: RefTyped<number>, immediate?: RefTyped<boolean>): UseTimeoutReturnType;

declare type UseTimeoutReturnType = {
    isActive: Ref<boolean>;
    start: () => void;
    stop: () => void;
};

/**
 * set the string to the page title.
 *
 * @param overridedTitle The string to set to the page title.
 * @param restoreOnUnmount whether need restore the title on unmount.
 */
export declare function useTitle(overridedTitle?: RefTyped<string>, restoreOnUnmount?: RefTyped<boolean>): UseTitleReturnType;

declare type UseTitleReturnType = {
    title: Ref<string>;
    restoreTitle: () => void;
};

/**
 * useToggle function
 *
 * @param defaultValue Truth value, default is `true`  - an optional parameter
 * @param reverseValue False value, default is `false` - an optional parameter
 *
 * @returns { status, toggle, setLeft, setRight } ]
     */
 export declare function useToggle<D extends RefTyped<UseToggleState>, R extends RefTyped<UseToggleState>>(defaultValue?: D, reverseValue?: R): UseToggleReturnType<D, R>;

 declare interface UseToggleActions {
     setLeft: () => void;
     setRight: () => void;
     toggle: (value?: any) => void;
 }

 declare type UseToggleReturnType<D, R> = {
     state: Ref<UnwrapRef<D> | UnwrapRef<R>>;
 } & UseToggleActions;

 declare type UseToggleState = string | number | boolean | null | undefined;

 export { }