Utility Functions

/**
 * Cache function results based on arguments
 * @param resolver - Function to memoize
 * @param options - Configuration options
 * @returns Memoized function
 */
function useMemoize<Args extends any[], Return>(
  resolver: (...args: Args) => Return,
  options?: UseMemoizeOptions<Args, Return>
): (...args: Args) => Return;

interface UseMemoizeOptions<Args extends any[], Return> {
  getKey?: (...args: Args) => string | number;
  cache?: UseMemoizeCache<string | number, Return>;
}

interface UseMemoizeCache<Key, Value> {
  has: (key: Key) => boolean;
  get: (key: Key) => Value | undefined;
  set: (key: Key, value: Value) => void;
  delete: (key: Key) => boolean;
  clear: () => void;
}

import { useMemoize } from "@vueuse/core";

// Expensive calculation
const fibonacci = useMemoize((n: number): number => {
  if (n <= 1) return n;
  return fibonacci(n - 1) + fibonacci(n - 2);
});

// API calls with caching
const fetchUser = useMemoize(async (id: string) => {
  const response = await fetch(`/api/users/${id}`);
  return response.json();
});

// Custom cache key
const cachedFn = useMemoize(
  (a: number, b: string) => `${a}-${b}`,
  {
    getKey: (a, b) => `${a}:${b}`
  }
);

/**
 * Create function that accepts refs and returns unreffed values
 * @param fn - Function to wrap
 * @returns Function that auto-unrefs arguments
 */
function createUnrefFn<T extends Function>(fn: T): T;

/**
 * Check if a browser feature is supported
 * @param callback - Feature detection callback
 * @param sync - Run synchronously
 * @returns Reactive support state
 */
function useSupported(
  callback: () => unknown,
  sync?: boolean
): ComputedRef<boolean>;

import { useSupported } from "@vueuse/core";

// Check for specific APIs
const isSupported = useSupported(() => navigator.geolocation);
const hasWebGL = useSupported(() => {
  const canvas = document.createElement('canvas');
  return canvas.getContext('webgl');
});

// Use in components
if (isSupported.value) {
  // Use the feature
}

/**
 * Reactive clone of a ref
 * @param source - Source ref to clone
 * @param options - Configuration options
 * @returns Cloned value utilities
 */
function useCloned<T>(
  source: MaybeRefOrGetter<T>,
  options?: UseClonedOptions<T>
): UseClonedReturn<T>;

interface UseClonedReturn<T> {
  cloned: ComputedRef<T>;
  sync: () => void;
}

interface UseClonedOptions<T> {
  manual?: boolean;
  clone?: CloneFn<T> | boolean;
}

type CloneFn<T> = (source: T) => T;

/**
 * Reactive array sorting
 * @param source - Source array or ref
 * @param compareFn - Comparison function or options
 * @param options - Configuration options when compareFn is provided
 * @returns Sorted array ref
 */
function useSorted<T>(
  source: MaybeRefOrGetter<T[]>,
  compareFn?: (a: T, b: T) => number,
  options?: UseSortedOptions<T>
): ComputedRef<T[]>;

function useSorted<T>(
  source: MaybeRefOrGetter<T[]>,
  options?: UseSortedOptions<T>
): ComputedRef<T[]>;

interface UseSortedOptions<T> {
  dirty?: Ref<boolean>;
  compareFn?: (a: T, b: T) => number;
}

/**
 * Cycle through a list of items
 * @param list - List of items to cycle through
 * @param options - Configuration options
 * @returns Cycle utilities
 */
function useCycleList<T>(
  list: MaybeRef<T[]>,
  options?: UseCycleListOptions<T>
): UseCycleListReturn<T>;

interface UseCycleListReturn<T> {
  state: Ref<T>;
  index: Ref<number>;
  next: (n?: number) => T;
  prev: (n?: number) => T;
  go: (i: number) => T;
}

interface UseCycleListOptions<T> {
  initialValue?: MaybeRef<T>;
  fallbackIndex?: number;
  getIndexOf?: (value: T, list: T[]) => number;
}

/**
 * Get the previous value of a ref
 * @param value - Source ref
 * @param initialValue - Initial previous value
 * @returns Previous value ref
 */
function usePrevious<T>(
  value: MaybeRef<T>,
  initialValue?: T
): Readonly<Ref<T | undefined>>;

/**
 * Reactive Base64 encoding and decoding
 * @param text - Text to encode/decode
 * @param options - Configuration options
 * @returns Base64 utilities
 */
function useBase64(
  text: MaybeRefOrGetter<string>,
  options?: UseBase64Options
): UseBase64Return;

interface UseBase64Return {
  base64: ComputedRef<string>;
  buffer: ComputedRef<ArrayBuffer>;
  promise: ComputedRef<Promise<string>>;
}

interface UseBase64Options {
  serializer?: UseBase64Serializer;
}

interface UseBase64Serializer {
  read: (text: string) => string;
  write: (text: string) => string;
}

/**
 * Reactive text direction
 * @param options - Configuration options
 * @returns Text direction utilities
 */
function useTextDirection(options?: UseTextDirectionOptions): UseTextDirectionReturn;

interface UseTextDirectionReturn {
  dir: WritableComputedRef<UseTextDirectionValue>;
}

interface UseTextDirectionOptions extends ConfigurableDocument {
  selector?: string;
  observe?: boolean;
  initialValue?: UseTextDirectionValue;
}

type UseTextDirectionValue = 'ltr' | 'rtl' | 'auto';

/**
 * Reactive text selection
 * @param options - Configuration options
 * @returns Text selection state
 */
function useTextSelection(options?: UseTextSelectionOptions): UseTextSelectionReturn;

interface UseTextSelectionReturn {
  text: ComputedRef<string>;
  rects: ComputedRef<DOMRect[]>;
  ranges: ComputedRef<Range[]>;
  selection: ComputedRef<Selection | null>;
}

/**
 * Auto-resize textarea based on content
 * @param element - Textarea element or ref
 * @param input - Input value (reactive)
 * @param options - Configuration options
 * @returns Textarea utilities
 */
function useTextareaAutosize(
  element?: MaybeElementRef<HTMLTextAreaElement>,
  input?: MaybeRef<string>,
  options?: UseTextareaAutosizeOptions
): UseTextareaAutosizeReturn;

interface UseTextareaAutosizeReturn {
  textarea: Ref<HTMLTextAreaElement | undefined>;
  input: Ref<string>;
  triggerResize: () => void;
}

interface UseTextareaAutosizeOptions {
  watch?: MaybeElementRef | MaybeElementRef[];
  onResize?: () => void;
  styleProp?: string;
}

/**
 * Reactive image loading with status tracking
 * @param options - Configuration options
 * @returns Image loading state and utilities
 */
function useImage(options: UseImageOptions): UseImageReturn;

interface UseImageReturn {
  isLoading: Ref<boolean>;
  error: Ref<Event | null>;
  execute: (options?: UseImageOptions) => Promise<HTMLImageElement>;
}

interface UseImageOptions {
  src: string;
  srcset?: string;
  sizes?: string;
  class?: string;
  loading?: 'eager' | 'lazy';
  crossorigin?: 'anonymous' | 'use-credentials' | '';
  referrerPolicy?: 'no-referrer' | 'no-referrer-when-downgrade' | 'origin' | 'origin-when-cross-origin' | 'same-origin' | 'strict-origin' | 'strict-origin-when-cross-origin' | 'unsafe-url';
}

/**
 * Create and manage object URLs for Blob/File objects
 * @param object - Blob, File, or MediaSource object
 * @returns Object URL utilities
 */
function useObjectUrl(object: MaybeRef<Blob | MediaSource | undefined>): ComputedRef<string | undefined>;

/**
 * Reactive current timestamp
 * @param options - Configuration options
 * @returns Current timestamp ref
 */
function useNow(options?: UseNowOptions): Ref<Date>;

interface UseNowOptions<Controls extends boolean = false> {
  controls?: Controls;
  interval?: 'requestAnimationFrame' | number;
}

/**
 * Reactive timestamp with millisecond precision
 * @param options - Configuration options
 * @returns Timestamp utilities
 */
function useTimestamp(options?: UseTimestampOptions): UseTimestampReturn;

interface UseTimestampReturn {
  timestamp: Ref<number>;
  pause: Fn;
  resume: Fn;
}

interface UseTimestampOptions<Controls extends boolean = false> {
  controls?: Controls;
  offset?: number;
  immediate?: boolean;
  interval?: 'requestAnimationFrame' | number;
  callback?: (timestamp: number) => void;
}

/**
 * Reactive time ago formatting
 * @param time - Time to format
 * @param options - Configuration options
 * @returns Formatted time ago string
 */
function useTimeAgo(
  time: MaybeComputedRef<Date | number | string>,
  options?: UseTimeAgoOptions<boolean>
): ComputedRef<string>;

interface UseTimeAgoOptions<Controls extends boolean = false> {
  controls?: Controls;
  updateInterval?: number;
  max?: string | number | Date | UseTimeAgoUnit;
  fullDateFormatter?: (date: Date) => string;
  messages?: UseTimeAgoMessages;
  rounding?: number;
  showSecond?: boolean;
  unit?: UseTimeAgoUnitNamesDefault;
}

type UseTimeAgoUnit = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year';

/**
 * Reactive timeout-based polling
 * @param fn - Function to poll
 * @param interval - Poll interval in milliseconds
 * @param options - Configuration options
 * @returns Poll utilities
 */
function useTimeoutPoll(
  fn: () => Awaitable<void>,
  interval: MaybeRef<number>,
  options?: UseTimeoutPollOptions
): UseTimeoutPollReturn;

interface UseTimeoutPollReturn extends Pausable {
  isActive: Ref<boolean>;
}

/**
 * Reactive countdown timer
 * @param count - Initial count or target date
 * @param options - Configuration options
 * @returns Countdown utilities
 */
function useCountdown(
  count: MaybeRef<number>,
  options?: UseCountdownOptions
): UseCountdownReturn;

interface UseCountdownReturn {
  count: Ref<number>;
  start: () => void;
  pause: () => void;
  resume: () => void;
  stop: () => void;
  reset: (newCount?: number) => void;
  restart: (newCount?: number) => void;
  isActive: Ref<boolean>;
}

interface UseCountdownOptions {
  interval?: number;
  onFinish?: () => void;
  onUpdate?: (count: number) => void;
}

/**
 * Reactive offset-based pagination
 * @param options - Configuration options
 * @returns Pagination utilities
 */
function useOffsetPagination(options: UseOffsetPaginationOptions): UseOffsetPaginationReturn;

interface UseOffsetPaginationReturn {
  currentPage: Ref<number>;
  currentPageSize: Ref<number>;
  pageCount: ComputedRef<number>;
  isFirstPage: ComputedRef<boolean>;
  isLastPage: ComputedRef<boolean>;
  prev: () => void;
  next: () => void;
}

interface UseOffsetPaginationOptions {
  total: MaybeRefOrGetter<number>;
  page?: MaybeRef<number>;
  pageSize?: MaybeRef<number>;
  onPageChange?: (returnValue: UseOffsetPaginationReturn) => void;
  onPageSizeChange?: (returnValue: UseOffsetPaginationReturn) => void;
}