Shared Utilities

/**
 * Eager computed that computes immediately
 * @param fn - Computation function
 * @returns Computed ref that computes eagerly
 */
function computedEager<T>(fn: () => T): ComputedRef<T>;

/**
 * Computed with manual control over when to trigger re-computation
 * @param source - Source function
 * @param fn - Computation function
 * @returns Controlled computed ref with trigger function
 */
function computedWithControl<T, S>(
  source: () => S,
  fn: (source: S, oldValue?: T) => T
): {
  0: ComputedRef<T>;
  1: () => void;
  trigger: () => void;
};

/**
 * Computed that accepts reactive arguments
 * @param fn - Function that accepts reactive arguments
 * @returns Reactive computed function
 */
function reactiveComputed<T extends any[], R>(
  fn: (...args: T) => R
): (...args: ToRefs<T>) => ComputedRef<R>;

/**
 * Ref that automatically resets after a timeout
 * @param defaultValue - Default value to reset to
 * @param afterMs - Milliseconds after which to reset
 * @returns Auto-resetting ref
 */
function refAutoReset<T>(
  defaultValue: T,
  afterMs?: MaybeRefOrGetter<number>
): Ref<T>;

/**
 * Debounced version of a ref
 * @param value - Source ref or value
 * @param ms - Debounce delay in milliseconds
 * @param options - Debounce options
 * @returns Debounced ref
 */
function refDebounced<T>(
  value: MaybeRefOrGetter<T>,
  ms?: MaybeRefOrGetter<number>,
  options?: DebounceFilterOptions
): Readonly<Ref<T>>;

/**
 * Throttled version of a ref
 * @param value - Source ref or value
 * @param delay - Throttle delay in milliseconds
 * @param trailing - Whether to invoke on trailing edge
 * @param leading - Whether to invoke on leading edge
 * @returns Throttled ref
 */
function refThrottled<T>(
  value: MaybeRefOrGetter<T>,
  delay?: number,
  trailing?: boolean,
  leading?: boolean
): Readonly<Ref<T>>;

/**
 * Ref with default value when null or undefined
 * @param source - Source ref
 * @param defaultValue - Default value to use
 * @returns Ref with default fallback
 */
function refDefault<T>(
  source: Ref<T | null | undefined>,
  defaultValue: T
): Ref<T>;

/**
 * Ref with manual control over get/set operations
 * @param initial - Initial value
 * @param options - Control options
 * @returns Controlled ref with additional methods
 */
function refWithControl<T>(
  initial: T,
  options?: RefWithControlOptions<T>
): RefWithControlReturn<T>;

interface RefWithControlReturn<T> extends Ref<T> {
  get: (tracking?: boolean) => T;
  set: (value: T, triggering?: boolean) => void;
  untrackedGet: () => T;
  silentSet: (value: T) => void;
  peek: () => T;
  lay: (value: T) => void;
  trigger: () => void;
}

/**
 * Extend a ref with additional reactive properties
 * @param ref - Source ref
 * @param extend - Object with additional properties
 * @param options - Extension options
 * @returns Extended ref with additional properties
 */
function extendRef<R extends Ref<any>, Extend extends Record<string, any>>(
  ref: R,
  extend: Extend,
  options?: ExtendRefOptions
): ExtendRefReturn<R, Extend>;

/**
 * Debounced version of watch
 * @param source - Watch source
 * @param cb - Callback function
 * @param options - Watch and debounce options
 * @returns Stop function
 */
function watchDebounced<T>(
  source: WatchSource<T>,
  cb: WatchCallback<T>,
  options?: WatchDebouncedOptions
): WatchStopHandle;

/**
 * Throttled version of watch
 * @param source - Watch source
 * @param cb - Callback function
 * @param options - Watch and throttle options
 * @returns Stop function
 */
function watchThrottled<T>(
  source: WatchSource<T>,
  cb: WatchCallback<T>,
  options?: WatchThrottledOptions
): WatchStopHandle;

/**
 * Pausable watcher with pause/resume controls
 * @param source - Watch source
 * @param cb - Callback function
 * @param options - Watch options
 * @returns Pausable watcher controls
 */
function watchPausable<T>(
  source: WatchSource<T>,
  cb: WatchCallback<T>,
  options?: WatchPausableOptions
): PausableWatchReturn<T>;

interface PausableWatchReturn<T> {
  stop: WatchStopHandle;
  pause: () => void;
  resume: () => void;
  isActive: Ref<boolean>;
}

/**
 * Ignorable watcher that can skip notifications
 * @param source - Watch source
 * @param cb - Callback function
 * @param options - Watch options
 * @returns Ignorable watcher controls
 */
function watchIgnorable<T>(
  source: WatchSource<T>,
  cb: WatchCallback<T>,
  options?: WatchIgnorableOptions
): IgnorableWatchReturn;

interface IgnorableWatchReturn {
  stop: WatchStopHandle;
  ignoreUpdates: (updater: () => void) => void;
  ignorePrevAsyncUpdates: () => void;
}

/**
 * Triggerable watcher with manual trigger
 * @param source - Watch source
 * @param cb - Callback function
 * @param options - Watch options
 * @returns Triggerable watcher controls
 */
function watchTriggerable<T>(
  source: WatchSource<T>,
  cb: WatchCallback<T>, 
  options?: WatchTriggerableOptions
): TriggerableWatchReturn;

interface TriggerableWatchReturn {
  stop: WatchStopHandle;
  trigger: () => void;
}

/**
 * Shorthand for watching when condition is truthy
 * @param source - Watch source
 * @param cb - Callback function
 * @param options - Watch options
 * @returns Stop function
 */
function whenever<T>(
  source: WatchSource<T | false | null | undefined>,
  cb: WatchCallback<T>,
  options?: WatchOptions
): WatchStopHandle;

/**
 * Wait for a condition to be truthy
 * @param r - Condition to wait for
 * @returns Promise that resolves when condition is truthy
 */
function until<T>(r: MaybeRefOrGetter<T>): UntilReturn<T>;

interface UntilReturn<T> {
  toMatch: (condition: (v: T) => boolean, options?: UntilToMatchOptions) => Promise<void>;
  changed: (options?: UntilOptions) => Promise<void>;
  changedTimes: (n?: number, options?: UntilOptions) => Promise<void>;
  toBe: <P>(value: MaybeRefOrGetter<P>, options?: UntilOptions) => Promise<void>;
  toBeTruthy: (options?: UntilOptions) => Promise<void>;
  toBeNull: (options?: UntilOptions) => Promise<void>;
  toBeUndefined: (options?: UntilOptions) => Promise<void>;
  not: UntilReturn<T>;
}

/**
 * Reactive array map
 * @param list - Source array or ref
 * @param fn - Map function
 * @returns Reactive mapped array
 */
function useArrayMap<T, U>(
  list: MaybeRefOrGetter<T[]>,
  fn: (element: T, index: number) => U
): ComputedRef<U[]>;

/**
 * Reactive array filter
 * @param list - Source array or ref
 * @param fn - Filter predicate function
 * @returns Reactive filtered array
 */
function useArrayFilter<T>(
  list: MaybeRefOrGetter<T[]>,
  fn: (element: T, index: number) => boolean
): ComputedRef<T[]>;

/**
 * Reactive array find
 * @param list - Source array or ref
 * @param fn - Find predicate function
 * @returns Reactive found element
 */
function useArrayFind<T>(
  list: MaybeRefOrGetter<T[]>,
  fn: (element: T, index: number) => boolean
): ComputedRef<T | undefined>;

/**
 * Reactive array reduce
 * @param list - Source array or ref
 * @param reducer - Reducer function
 * @param initialValue - Initial accumulator value
 * @returns Reactive reduced value
 */
function useArrayReduce<T, U>(
  list: MaybeRefOrGetter<T[]>,
  reducer: (accumulator: U, currentValue: T, currentIndex: number) => U,
  initialValue: MaybeRefOrGetter<U>
): ComputedRef<U>;

/**
 * Reactive array some
 * @param list - Source array or ref
 * @param fn - Test predicate function
 * @returns Reactive boolean result
 */
function useArraySome<T>(
  list: MaybeRefOrGetter<T[]>,
  fn: (element: T, index: number) => boolean
): ComputedRef<boolean>;

/**
 * Reactive array every
 * @param list - Source array or ref
 * @param fn - Test predicate function
 * @returns Reactive boolean result
 */
function useArrayEvery<T>(
  list: MaybeRefOrGetter<T[]>,
  fn: (element: T, index: number) => boolean
): ComputedRef<boolean>;

/**
 * Create global reactive state that persists across component instances
 * @param stateFactory - Function that creates the initial state
 * @returns Global state creator function
 */
function createGlobalState<T>(
  stateFactory: () => T
): () => T;

/**
 * Make a composable function shared across multiple instances
 * @param composable - Composable function to share
 * @returns Shared version of the composable
 */
function createSharedComposable<Fn extends (...args: any[]) => any>(
  composable: Fn
): Fn;

/**
 * Boolean toggle utility with multiple states support
 * @param initialValue - Initial value or array of values
 * @returns Toggle state and functions
 */
function useToggle<T = boolean>(
  initialValue?: MaybeRef<T>
): UseToggleReturn<T>;

interface UseToggleReturn<T> {
  0: Ref<T>;
  1: (value?: T) => T;
  toggle: (value?: T) => T;
}

/**
 * Counter with increment/decrement operations
 * @param initialValue - Initial counter value
 * @param options - Counter options
 * @returns Counter state and operations
 */
function useCounter(
  initialValue?: MaybeRef<number>,
  options?: UseCounterOptions
): UseCounterReturn;

interface UseCounterReturn {
  count: Ref<number>;
  inc: (delta?: number) => number;
  dec: (delta?: number) => number;
  get: () => number;
  set: (val: number) => number;
  reset: (val?: number) => number;
}

/**
 * Reactive interval
 * @param callback - Callback function to execute
 * @param interval - Interval delay in milliseconds
 * @param options - Interval options
 * @returns Interval controls
 */
function useInterval(
  callback: Fn,
  interval?: MaybeRef<number>,
  options?: UseIntervalOptions
): Pausable;

/**
 * Reactive timeout
 * @param callback - Callback function to execute
 * @param interval - Timeout delay in milliseconds
 * @param options - Timeout options
 * @returns Timeout controls
 */
function useTimeout(
  callback: Fn,
  interval: MaybeRef<number>,
  options?: UseTimeoutOptions
): UseTimeoutReturn;

/**
 * Reactive date formatting
 * @param date - Date to format
 * @param format - Format string
 * @param options - Formatting options
 * @returns Reactive formatted date string
 */
function useDateFormat(
  date: MaybeRefOrGetter<Date | number | string>,
  format?: MaybeRefOrGetter<string>,
  options?: UseDateFormatOptions
): ComputedRef<string>;

/**
 * Convert a function to accept refs as arguments
 * @param fn - Function to reactify
 * @returns Reactified function
 */
function reactify<T extends (...args: any[]) => any>(
  fn: T,
  options?: ReactifyOptions<T>
): ReactifyReturn<T>;

/**
 * Convert refs to reactive object
 * @param objectRef - Ref containing an object
 * @returns Reactive version of the object
 */
function toReactive<T extends Record<string, any>>(
  objectRef: MaybeRef<T>
): ToReactive<T>;

/**
 * Make return values suitable for both array and object destructuring
 * @param obj - Object to make destructurable
 * @param arr - Array representation
 * @returns Destructurable object
 */
function makeDestructurable<T extends Record<string, unknown>, A extends readonly unknown[]>(
  obj: T,
  arr: A
): T & A;

/**
 * Type guard to check if value is defined (not null or undefined)
 * @param val - Value to check
 * @returns True if value is defined
 */
function isDefined<T>(val: T | undefined | null): val is T;

/**
 * Get the value from MaybeRefOrGetter
 * @param val - Value, ref, or getter function
 * @returns Resolved value
 */
function get<T>(val: MaybeRefOrGetter<T>): T;

/**
 * Set value to a ref
 * @param ref - Target ref
 * @param val - Value to set
 */
function set<T>(ref: Ref<T>, val: T): void;

/**
 * Safe version of onMounted that works outside component context
 * @param fn - Function to call on mounted
 * @param sync - Whether to call synchronously if already mounted
 * @returns Whether the hook was successfully registered
 */
function tryOnMounted(fn: Fn, sync?: boolean): boolean;

/**
 * Safe version of onBeforeMount that works outside component context
 * @param fn - Function to call before mount
 * @param sync - Whether to call synchronously if component exists
 * @returns Whether the hook was successfully registered
 */
function tryOnBeforeMount(fn: Fn, sync?: boolean): boolean;

/**
 * Safe version of onUnmounted that works outside component context
 * @param fn - Function to call on unmounted
 * @returns Whether the hook was successfully registered
 */
function tryOnUnmounted(fn: Fn): boolean;

/**
 * Safe version of onScopeDispose that works outside effect scope
 * @param fn - Function to call on scope dispose
 * @returns Whether the hook was successfully registered
 */
function tryOnScopeDispose(fn: Fn): boolean;

// Core utility types
type MaybeRef<T> = T | Ref<T>;
type MaybeRefOrGetter<T> = T | MaybeRef<T> | (() => T);
type MaybeComputedRef<T> = ComputedRef<T> | MaybeRef<T>;

// Function types
type Fn = () => void;
type AnyFn = (...args: any[]) => any;

// Control interfaces
interface Pausable {
  isActive: Ref<boolean>;
  pause: Fn;
  resume: Fn;
}

interface Awaitable<T> {
  [Symbol.iterator]: any;
  then: PromiseLike<T>['then'];
}

// Filter options
interface DebounceFilterOptions {
  maxWait?: MaybeRefOrGetter<number>;
  rejectOnCancel?: boolean;
}

interface ThrottleFilterOptions {
  trailing?: boolean;
  leading?: boolean;
  rejectOnCancel?: boolean;
}