@svelte-use/core/index.d.ts

Collection of essential Svelte Utilities

import * as _svelte_use_shared from '@svelte-use/shared';
import { MaybeElementReadable, PromiseFn, Fn, MaybeReadable, MaybeWritable, RemovableWritable, Pausable } from '@svelte-use/shared';
export * from '@svelte-use/shared';
import * as svelte_store from 'svelte/store';

interface ConfigurableWindow {
    window?: Window;
}
interface ConfigurableDocument {
    document?: Document;
}

declare type OnClickOutsideEvents = Pick<WindowEventMap, 'click' | 'mousedown' | 'mouseup' | 'touchstart' | 'touchend' | 'pointerdown' | 'pointerup'>;
interface OnClickOutsideOptions<E extends keyof OnClickOutsideEvents> extends ConfigurableWindow {
    event?: E;
}
/**
 * Listen for clicks outside of an element
 *
 * @see https://svelte-use.vercel.app/core/onClickOutside
 * @param target
 * @param handler
 * @param options
 */
declare function onClickOutside<E extends keyof OnClickOutsideEvents = 'pointerdown'>(target: MaybeElementReadable, handler: (evt: OnClickOutsideEvents[E]) => void, options?: OnClickOutsideOptions<E>): _svelte_use_shared.Fn | undefined;

interface AsyncStateOptions {
    /**
     * Delay for executeing the promise. In milliseconds.
     *
     * @default 0
     */
    delay?: number;
    /**
     * Execute the promise right after the function is invoked.
     * Will apply the delay if any.
     *
     * When set to false, you will need to execute it manually.
     *
     * @default true
     */
    immediate?: boolean;
    /**
     * Callback when error is caught.
     */
    onError?: (e: unknown) => void;
    /**
     * Sets the state to initialState before executing the promise.
     *
     * This can be useful when calling the execute function more than once (for
     * example, to refresh data). When set to false, the current state remains
     * unchanged until the promise resolves.
     *
     * @default true
     */
    resetOnExecute?: boolean;
}
/**
 * Reactive async state. Will not block your setup function and will triggers changes once
 * the promise is ready.
 *
 * @see https://svelte-use.vercel.app/core/useAsyncState
 * @param promise         The promise / async function to be resolved
 * @param initialState    The initial state, used until the first evaluation finishes
 * @param options
 */
declare function useAsyncState<T>(promise: Promise<T> | PromiseFn<T>, initialState: T, options?: AsyncStateOptions): {
    state: svelte_store.Writable<T>;
    isReady: svelte_store.Writable<boolean>;
    error: svelte_store.Writable<unknown>;
    execute: (delay?: number, ...args: any[]) => Promise<void>;
};
declare type UseAsyncStateReturn = ReturnType<typeof useAsyncState>;

interface InferEventTarget<Events> {
    addEventListener(event: Events, fn?: any, options?: any): any;
    removeEventListener(event: Events, fn?: any, options?: any): any;
}
declare type WindowEventName = keyof WindowEventMap;
declare type DocumentEventName = keyof DocumentEventMap;
declare type GeneralEventListener<E = Event> = {
    (evt: E): void;
};
/**
 * Register using addEventListener on mount, and removeEventListener automatically on destory
 *
 * Overload 1: Omitted Window target
 *
 * @see https://svelte-use.vercel.app/core/useEventListener
 * @param event
 * @param listener
 * @param options
 */
declare function useEventListener<E extends keyof WindowEventMap>(event: E, listener: (this: Window, ev: WindowEventMap[E]) => any, options?: Boolean | AddEventListenerOptions): Fn;
/**
 * Register using addEventListener on mount, and removeEventListener automatically on destory
 *
 * Overload 2: Explicitly Window target
 *
 * @see https://svelte-use.vercel.app/core/useEventListener
 * @param target
 * @param event
 * @param listener
 * @param options
 */
declare function useEventListener<E extends keyof WindowEventMap>(target: Window, event: E, listener: (this: Window, ev: WindowEventMap[E]) => any, options?: Boolean | AddEventListenerOptions): Fn;
/**
 * Register using addEventListener on mount, and removeEventListener automatically on destory
 *
 * Overload 3: Explicitly Document target
 *
 * @see https://svelte-use.vercel.app/core/useEventListener
 * @param target
 * @param event
 * @param listener
 * @param options
 */
declare function useEventListener<E extends keyof DocumentEventMap>(target: Document, event: E, listener: (this: Window, ev: DocumentEventMap[E]) => any, options?: Boolean | AddEventListenerOptions): Fn;
/**
 * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
 *
 * Overload 4: Custom event target with event type infer
 *
 * @see https://svelte-use.vercel.app/core/useEventListener
 * @param target
 * @param event
 * @param listener
 * @param options
 */
declare function useEventListener<Names extends string, EventType = Event>(target: InferEventTarget<Names>, event: Names, listener: GeneralEventListener<EventType>, options?: boolean | AddEventListenerOptions): Fn;
/**
 * Register using addEventListener on mounted, and removeEventListener automatically on unmounted.
 *
 * Overload 5: Custom event target fallback
 *
 * @see https://svelte-use.vercel.app/core/useEventListener
 * @param target
 * @param event
 * @param listener
 * @param options
 */
declare function useEventListener<EventType = Event>(target: MaybeReadable<EventTarget | null | undefined>, event: string, listener: GeneralEventListener<EventType>, options?: boolean | AddEventListenerOptions): Fn;

declare type Serializer<T> = {
    read(raw: string): T;
    write(value: T): string;
};
declare const StorageSerializers: Record<'boolean' | 'object' | 'number' | 'string' | 'any', Serializer<any>>;
declare type StorageLike = Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
interface StorageOptions<T> extends ConfigurableWindow {
    /**
     * Listen to storage changes, useful for multiple tabs application
     *
     * @default true
     */
    listenToStorageChanges?: boolean;
    /**
     * Custom data serialization
     */
    serializer?: Serializer<T>;
    /**
     * On error callback
     *
     * Default lo error to `console.error`
     */
    onError?: (error: unknown) => void;
}
declare function useStorage(key: string, initialValue: MaybeWritable<string>, storage?: StorageLike, options?: StorageOptions<string>): RemovableWritable<string>;
declare function useStorage(key: string, initialValue: MaybeWritable<boolean>, storage?: StorageLike, options?: StorageOptions<boolean>): RemovableWritable<boolean>;
declare function useStorage(key: string, initialValue: MaybeWritable<number>, storage?: StorageLike, options?: StorageOptions<number>): RemovableWritable<number>;
declare function useStorage<T>(key: string, initialValue: MaybeWritable<T>, storage?: StorageLike, options?: StorageOptions<T>): RemovableWritable<T>;
declare function useStorage<T = unknown>(key: string, initialValue: MaybeWritable<null>, storage?: StorageLike, options?: StorageOptions<T>): RemovableWritable<T>;

declare function useLocalStorage(key: string, initialValue: MaybeWritable<string>, options?: StorageOptions<string>): RemovableWritable<string>;
declare function useLocalStorage(key: string, initialValue: MaybeWritable<boolean>, options?: StorageOptions<boolean>): RemovableWritable<boolean>;
declare function useLocalStorage(key: string, initialValue: MaybeWritable<number>, options?: StorageOptions<number>): RemovableWritable<number>;
declare function useLocalStorage<T>(key: string, initialValue: MaybeWritable<T>, options?: StorageOptions<T>): RemovableWritable<T>;
declare function useLocalStorage<T = unknown>(key: string, initialValue: MaybeWritable<null>, options?: StorageOptions<T>): RemovableWritable<T>;

/**
 * Reactive Media Query
 *
 * @param query
 * @param options
 */
declare function useMediaQuery(query: string, options?: ConfigurableWindow): svelte_store.Readable<boolean>;

interface MutationObserverOptions extends MutationObserverInit, ConfigurableWindow {
}
/**
 * Watch for changes being made to the DOM tree.
 *
 * @see https://svelte-use.vercel.app/core/useMutationObserver
 * @see https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver MutationObserver MDN
 * @param target
 * @param callback
 * @param options
 */
declare function useMutationObserver(target: MaybeElementReadable, callback: MutationCallback, options?: MutationObserverOptions): {
    isSupported: boolean | undefined;
    stop: () => void;
};
declare type UseMutationObserverReturn = ReturnType<typeof useMutationObserver>;

/**
 * Reactive dark theme preference.
 *
 * @param [options]
 */
declare function usePreferredDark(options?: ConfigurableWindow): svelte_store.Readable<boolean>;

interface RafFnOptions extends ConfigurableWindow {
    /**
     * Start the requestAnimationFrame loop immediately on creation
     *
     * @default true
     */
    immediate?: boolean;
}
/**
 * Call function on every `requestAnimationFrame`. With controls of pausing and resuming.
 *
 * @see https://svelte-use.vercel.app/core/useRafFn
 * @param fn
 * @param options
 */
declare function useRafFn(fn: Fn, options?: RafFnOptions): Pausable;

declare function useSessionStorage(key: string, initialValue: MaybeWritable<string>, options?: StorageOptions<string>): RemovableWritable<string>;
declare function useSessionStorage(key: string, initialValue: MaybeWritable<boolean>, options?: StorageOptions<boolean>): RemovableWritable<boolean>;
declare function useSessionStorage(key: string, initialValue: MaybeWritable<number>, options?: StorageOptions<number>): RemovableWritable<number>;
declare function useSessionStorage<T>(key: string, initialValue: MaybeWritable<T>, options?: StorageOptions<T>): RemovableWritable<T>;
declare function useSessionStorage<T = unknown>(key: string, initialValue: MaybeWritable<null>, options?: StorageOptions<T>): RemovableWritable<T>;

interface UseTitleOptions extends ConfigurableDocument {
    /**
     * Observe `document.title` changes using MutationObserver
     *
     * @default false
     */
    observe?: boolean;
}
declare type Title = string | null | undefined;
/**
 * Reactive document title.
 *
 * @see https://svelte-use.vercel.app/core/useTitle
 * @param newTitle
 * @param options
 */
declare function useTitle(newTitle?: MaybeWritable<Title>, options?: UseTitleOptions): svelte_store.Writable<Title>;

export { AsyncStateOptions, DocumentEventName, GeneralEventListener, MutationObserverOptions, OnClickOutsideEvents, OnClickOutsideOptions, RafFnOptions, Serializer, StorageLike, StorageOptions, StorageSerializers, UseAsyncStateReturn, UseMutationObserverReturn, UseTitleOptions, WindowEventName, onClickOutside, useAsyncState, useEventListener, useLocalStorage, useMediaQuery, useMutationObserver, usePreferredDark, useRafFn, useSessionStorage, useStorage, useTitle };