📄 `filters`¶

📊 Analysis Summary¶

Metric	Count
🔧 Functions	16
📦 Imports	15
⚡ Async/Await Patterns	4
📐 Interfaces	6
📑 Type Aliases	3

📚 Table of Contents¶

Imports
Async/Await Patterns
Functions
Interfaces
Type Aliases

🛠️ File Location:¶

📂 packages/shared/utils/filters.ts

📦 Imports¶

Name	Source
`MaybeRefOrGetter`	`vue`
`Ref`	`vue`
`AnyFn`	`./types`
`ArgumentsType`	`./types`
`Awaited`	`./types`
`Pausable`	`./types`
`Promisify`	`./types`
`PromisifyFn`	`./types`
`TimerHandle`	`./types`
`isRef`	`vue`
`shallowReadonly`	`vue`
`shallowRef`	`vue`
`toValue`	`vue`
`toRef`	`../toRef`
`noop`	`./is`

Async/Await Patterns¶

Type	Function	Await Expressions	Promise Chains
promise-chain	`wrapper`	none	new Promise(...), Promise.resolve(filter(() => fn.apply(this, args), { fn, th...
promise-chain	`debounceFilter`	none	Promise.resolve, new Promise(...)
promise-chain	`handler`	none	Promise.resolve, new Promise(...)
promise-chain	`filter`	none	new Promise(...)

Functions¶

`createFilterWrapper(filter: CancelableEventFilter, fn: T): CancelablePromisifyFn<T>`¶

Tags: @internal

Raw JSDoc

/**
 * @internal
 */

Code

export function createFilterWrapper<T extends AnyFn>(filter: CancelableEventFilter, fn: T): CancelablePromisifyFn<T>

`bypassFilter(invoke: AnyFn): any`¶

Parameters:

invoke AnyFn

Returns: any

Calls:

invoke

Code

(invoke) => {
  return invoke()
}

`debounceFilter(ms: MaybeRefOrGetter<number>, options: DebounceFilterOptions): CancelableEventFilter`¶

Create an EventFilter that debounce the events

Raw JSDoc

/**
 * Create an EventFilter that debounce the events
 */

Calls:

shallowRef (from vue)
clearTimeout
lastRejector
toValue (from vue)
_clearTimeout
Promise.resolve
invoke
setTimeout
resolve
lastInvoker
Object.assign
shallowReadonly (from vue)

Internal Comments:

// Create the maxTimer. Clears the regular timer on invoke
// Create the regular timer. Clears the max timer on invoke (x3)
// Use native clearTimeout (not _clearTimeout) to avoid
// calling lastRejector — we resolve via lastResolve instead

Code

export function debounceFilter(ms: MaybeRefOrGetter<number>, options: DebounceFilterOptions = {}): CancelableEventFilter {
  let timer: TimerHandle
  let maxTimer: TimerHandle
  let lastRejector: AnyFn = noop
  let lastResolve: AnyFn = noop
  const _pending = shallowRef(false)

  const _clearTimeout = (timer: TimerHandle) => {
    clearTimeout(timer)
    lastRejector()
    lastRejector = noop
  }

  let lastInvoker: () => void

  const handler = (invoke: AnyFn) => {
    const duration = toValue(ms)
    const maxDuration = toValue(options.maxWait)

    if (timer)
      _clearTimeout(timer)

    if (duration <= 0 || (maxDuration !== undefined && maxDuration <= 0)) {
      if (maxTimer) {
        _clearTimeout(maxTimer)
        maxTimer = undefined
      }
      _pending.value = false
      return Promise.resolve(invoke())
    }

    _pending.value = true

    return new Promise((resolve, reject) => {
      lastRejector = options.rejectOnCancel ? reject : resolve
      lastResolve = resolve
      lastInvoker = invoke
      // Create the maxTimer. Clears the regular timer on invoke
      if (maxDuration && !maxTimer) {
        maxTimer = setTimeout(() => {
          if (timer)
            _clearTimeout(timer)
          maxTimer = undefined
          _pending.value = false
          resolve(lastInvoker())
        }, maxDuration)
      }

      // Create the regular timer. Clears the max timer on invoke
      timer = setTimeout(() => {
        if (maxTimer)
          _clearTimeout(maxTimer)
        maxTimer = undefined
        _pending.value = false
        resolve(invoke())
      }, duration)
    })
  }

  const filter: CancelableEventFilter = Object.assign(handler, {
    cancel: () => {
      if (timer) {
        _clearTimeout(timer)
        timer = undefined
      }
      if (maxTimer) {
        _clearTimeout(maxTimer)
        maxTimer = undefined
      }
      _pending.value = false
      lastResolve = noop
    },
    flush: () => {
      if (_pending.value) {
        // Use native clearTimeout (not _clearTimeout) to avoid
        // calling lastRejector — we resolve via lastResolve instead
        if (timer) {
          clearTimeout(timer)
          timer = undefined
        }
        if (maxTimer) {
          clearTimeout(maxTimer)
          maxTimer = undefined
        }
        _pending.value = false
        const resolve = lastResolve
        lastRejector = noop
        lastResolve = noop
        resolve(lastInvoker())
      }
    },
    isPending: shallowReadonly(_pending),
  })

  return filter
}

`throttleFilter(ms: MaybeRefOrGetter<number>, trailing: boolean, leading: boolean, rejectOnCancel: boolean): EventFilter`¶

Create an EventFilter that throttle the events

Raw JSDoc

/**
 * Create an EventFilter that throttle the events
 */

Code

export function throttleFilter(ms: MaybeRefOrGetter<number>, trailing?: boolean, leading?: boolean, rejectOnCancel?: boolean): EventFilter

`pausableFilter(extendFilter: EventFilter, options: PausableFilterOptions): Pausable & { eventFilter: EventFilter }`¶

EventFilter that gives extra controls to pause and resume the filter

Parameters:

extendFilter any: Extra filter to apply when the PausableFilter is active, default to none
options any: Options to configure the filter

Raw JSDoc

/**
 * EventFilter that gives extra controls to pause and resume the filter
 *
 * @param extendFilter  Extra filter to apply when the PausableFilter is active, default to none
 * @param options Options to configure the filter
 */

Calls:

toRef (from ../toRef)
extendFilter
shallowReadonly (from vue)

Code

export function pausableFilter(extendFilter: EventFilter = bypassFilter, options: PausableFilterOptions = {}): Pausable & { eventFilter: EventFilter } {
  const {
    initialState = 'active',
  } = options

  const isActive = toRef(initialState === 'active')

  function pause() {
    isActive.value = false
  }
  function resume() {
    isActive.value = true
  }

  const eventFilter: EventFilter = (...args) => {
    if (isActive.value)
      extendFilter(...args)
  }

  return { isActive: shallowReadonly(isActive), pause, resume, eventFilter }
}

Internal helpers¶

Declared inside another function in this file.

`wrapper(this: any, args: ArgumentsType<T>): Promise<Awaited<ReturnType<T>>>`¶

Parameters:

this any
args ArgumentsType<T>

Returns: Promise<Awaited<ReturnType<T>>>

Calls:

Promise.resolve(filter(() => fn.apply(this, args), { fn, thisArg: this, args })) .then(resolve) .catch

Internal Comments:

// make sure it's a promise (x8)

Code

function wrapper(this: any, ...args: ArgumentsType<T>) {
    return new Promise<Awaited<ReturnType<T>>>((resolve, reject) => {
      // make sure it's a promise
      Promise.resolve(filter(() => fn.apply(this, args), { fn, thisArg: this, args }))
        .then(resolve)
        .catch(reject)
    })
  }

`_clearTimeout(timer: TimerHandle): void`¶

Parameters:

timer TimerHandle

Returns: void

Calls:

clearTimeout
lastRejector

Code

(timer: TimerHandle) => {
    clearTimeout(timer)
    lastRejector()
    lastRejector = noop
  }

`handler(invoke: AnyFn): Promise<any>`¶

Parameters:

invoke AnyFn

Returns: Promise<any>

Calls:

toValue (from vue)
_clearTimeout
Promise.resolve
invoke
setTimeout
resolve
lastInvoker

Internal Comments:

// Create the maxTimer. Clears the regular timer on invoke
// Create the regular timer. Clears the max timer on invoke (x3)

Code

(invoke: AnyFn) => {
    const duration = toValue(ms)
    const maxDuration = toValue(options.maxWait)

    if (timer)
      _clearTimeout(timer)

    if (duration <= 0 || (maxDuration !== undefined && maxDuration <= 0)) {
      if (maxTimer) {
        _clearTimeout(maxTimer)
        maxTimer = undefined
      }
      _pending.value = false
      return Promise.resolve(invoke())
    }

    _pending.value = true

    return new Promise((resolve, reject) => {
      lastRejector = options.rejectOnCancel ? reject : resolve
      lastResolve = resolve
      lastInvoker = invoke
      // Create the maxTimer. Clears the regular timer on invoke
      if (maxDuration && !maxTimer) {
        maxTimer = setTimeout(() => {
          if (timer)
            _clearTimeout(timer)
          maxTimer = undefined
          _pending.value = false
          resolve(lastInvoker())
        }, maxDuration)
      }

      // Create the regular timer. Clears the max timer on invoke
      timer = setTimeout(() => {
        if (maxTimer)
          _clearTimeout(maxTimer)
        maxTimer = undefined
        _pending.value = false
        resolve(invoke())
      }, duration)
    })
  }

`cancel(): void`¶

Returns: void

Calls:

_clearTimeout

Code

() => {
      if (timer) {
        _clearTimeout(timer)
        timer = undefined
      }
      if (maxTimer) {
        _clearTimeout(maxTimer)
        maxTimer = undefined
      }
      _pending.value = false
      lastResolve = noop
    }

`flush(): void`¶

Returns: void

Calls:

clearTimeout
resolve
lastInvoker

Internal Comments:

// Use native clearTimeout (not _clearTimeout) to avoid
// calling lastRejector — we resolve via lastResolve instead

Code

() => {
      if (_pending.value) {
        // Use native clearTimeout (not _clearTimeout) to avoid
        // calling lastRejector — we resolve via lastResolve instead
        if (timer) {
          clearTimeout(timer)
          timer = undefined
        }
        if (maxTimer) {
          clearTimeout(maxTimer)
          maxTimer = undefined
        }
        _pending.value = false
        const resolve = lastResolve
        lastRejector = noop
        lastResolve = noop
        resolve(lastInvoker())
      }
    }

`clear(): void`¶

Returns: void

Calls:

clearTimeout
lastRejector

Code

() => {
    if (timer) {
      clearTimeout(timer)
      timer = undefined
      lastRejector()
      lastRejector = noop
    }
  }

`filter(_invoke: AnyFn): any`¶

Parameters:

_invoke AnyFn

Returns: any

Calls:

toValue (from vue)
Date.now
_invoke
clear
invoke
setTimeout
resolve
Math.max

Code

(_invoke) => {
    const duration = toValue(ms)
    const elapsed = Date.now() - lastExec
    const invoke = () => {
      return lastValue = _invoke()
    }

    clear()

    if (duration <= 0) {
      lastExec = Date.now()
      return invoke()
    }
    if (elapsed > duration) {
      lastExec = Date.now()
      if (leading || !isLeading)
        invoke()
    }
    else if (trailing) {
      lastValue = new Promise((resolve, reject) => {
        lastRejector = rejectOnCancel ? reject : resolve
        timer = setTimeout(() => {
          lastExec = Date.now()
          isLeading = true
          resolve(invoke())
          clear()
        }, Math.max(0, duration - elapsed))
      })
    }

    if (!leading && !timer)
      timer = setTimeout(() => isLeading = true, duration)

    isLeading = false
    return lastValue
  }

`invoke(): any`¶

Returns: any

Calls:

_invoke

Code

() => {
      return lastValue = _invoke()
    }

`pause(): void`¶

Returns: void

Code

function pause() {
    isActive.value = false
  }

`resume(): void`¶

Returns: void

Code

function resume() {
    isActive.value = true
  }

`eventFilter(args: [invoke: AnyFn, options: FunctionWrappe…): void`¶

Parameters:

args [invoke: AnyFn, options: FunctionWrapperOptions<any[], any>]

Returns: void

Calls:

extendFilter

Code

(...args) => {
    if (isActive.value)
      extendFilter(...args)
  }

Interfaces¶

`FunctionWrapperOptions<Args extends any[] = any[], This = any>`¶

Interface Code

export interface FunctionWrapperOptions<Args extends any[] = any[], This = any> {
  fn: FunctionArgs<Args, This>
  args: Args
  thisArg: This
}

Properties¶

Name	Type	Optional	Description
`fn`	`FunctionArgs<Args, This>`	✗	not shown
`args`	`Args`	✗	not shown
`thisArg`	`This`	✗	not shown

`CancelableEventFilter<Args extends any[] = any[], This = any, Invoke extends AnyFn = AnyFn>`¶

Interface Code

export interface CancelableEventFilter<Args extends any[] = any[], This = any, Invoke extends AnyFn = AnyFn> {
  (invoke: Invoke, options: FunctionWrapperOptions<Args, This>): ReturnType<Invoke> | Promisify<ReturnType<Invoke>>
  cancel: () => void
  flush: () => void
  readonly isPending: Readonly<Ref<boolean>>
}

Properties¶

Name	Type	Optional	Description
`cancel`	`() => void`	✗	not shown
`flush`	`() => void`	✗	not shown
`isPending`	`Readonly<Ref<boolean>>`	✗	not shown

`ConfigurableEventFilter`¶

Interface Code

export interface ConfigurableEventFilter {
  /**
   * Filter for if events should to be received.
   *
   * @see https://vueuse.org/guide/config.html#event-filters
   */
  eventFilter?: EventFilter
}

Properties¶

Name	Type	Optional	Description
`eventFilter`	`EventFilter`	✓	not shown

`DebounceFilterOptions`¶

Interface Code

export interface DebounceFilterOptions {
  /**
   * The maximum time allowed to be delayed before it's invoked.
   * In milliseconds.
   */
  maxWait?: MaybeRefOrGetter<number>

  /**
   * Whether to reject the last call if it's been cancel.
   *
   * @default false
   */
  rejectOnCancel?: boolean
}

Properties¶

Name	Type	Optional	Description
`maxWait`	`MaybeRefOrGetter<number>`	✓	not shown
`rejectOnCancel`	`boolean`	✓	not shown

`ThrottleFilterOptions`¶

Interface Code

export interface ThrottleFilterOptions {
  /**
   * The maximum time allowed to be delayed before it's invoked.
   */
  delay: MaybeRefOrGetter<number>
  /**
   * Whether to invoke on the trailing edge of the timeout.
   */
  trailing?: boolean
  /**
   * Whether to invoke on the leading edge of the timeout.
   */
  leading?: boolean
  /**
   * Whether to reject the last call if it's been cancel.
   */
  rejectOnCancel?: boolean
}

Properties¶

Name	Type	Optional	Description
`delay`	`MaybeRefOrGetter<number>`	✗	not shown
`trailing`	`boolean`	✓	not shown
`leading`	`boolean`	✓	not shown
`rejectOnCancel`	`boolean`	✓	not shown

`PausableFilterOptions`¶

Interface Code

export interface PausableFilterOptions {
  /**
   * The initial state
   *
   * @default 'active'
   */
  initialState?: 'active' | 'paused'
}

Properties¶

Name	Type	Optional	Description
`initialState`	`'active' \\| 'paused'`	✓	not shown

Type Aliases¶

`FunctionArgs<Args extends any[] = any[], Return = unknown>`¶

type FunctionArgs<Args extends any[] = any[], Return = unknown> = (...args: Args) => Return;

`EventFilter<Args extends any[] = any[], This = any, Invoke extends AnyFn = AnyFn>`¶

type EventFilter<Args extends any[] = any[], This = any, Invoke extends AnyFn = AnyFn> = (
  invoke: Invoke,
  options: FunctionWrapperOptions<Args, This>,
) => ReturnType<Invoke> | Promisify<ReturnType<Invoke>>;

`CancelablePromisifyFn<T extends AnyFn>`¶

type CancelablePromisifyFn<T extends AnyFn> = PromisifyFn<T> & {
  cancel: () => void
  flush: () => void
  readonly isPending: Readonly<Ref<boolean>>
};

Generated by Syntax Scribe

📄 filters¶

📊 Analysis Summary¶

📚 Table of Contents¶

🛠️ File Location:¶

📦 Imports¶

Async/Await Patterns¶

Functions¶

createFilterWrapper(filter: CancelableEventFilter, fn: T): CancelablePromisifyFn<T>¶

bypassFilter(invoke: AnyFn): any¶

debounceFilter(ms: MaybeRefOrGetter<number>, options: DebounceFilterOptions): CancelableEventFilter¶

throttleFilter(ms: MaybeRefOrGetter<number>, trailing: boolean, leading: boolean, rejectOnCancel: boolean): EventFilter¶

pausableFilter(extendFilter: EventFilter, options: PausableFilterOptions): Pausable & { eventFilter: EventFilter }¶

Internal helpers¶

wrapper(this: any, args: ArgumentsType<T>): Promise<Awaited<ReturnType<T>>>¶

_clearTimeout(timer: TimerHandle): void¶

handler(invoke: AnyFn): Promise<any>¶

cancel(): void¶

flush(): void¶

clear(): void¶

filter(_invoke: AnyFn): any¶

invoke(): any¶

pause(): void¶

resume(): void¶

eventFilter(args: [invoke: AnyFn, options: FunctionWrappe…): void¶

Interfaces¶

FunctionWrapperOptions<Args extends any[] = any[], This = any>¶

Properties¶

CancelableEventFilter<Args extends any[] = any[], This = any, Invoke extends AnyFn = AnyFn>¶

Properties¶

ConfigurableEventFilter¶

Properties¶

DebounceFilterOptions¶

Properties¶

ThrottleFilterOptions¶

Properties¶

PausableFilterOptions¶

Properties¶

Type Aliases¶

FunctionArgs<Args extends any[] = any[], Return = unknown>¶

EventFilter<Args extends any[] = any[], This = any, Invoke extends AnyFn = AnyFn>¶

CancelablePromisifyFn<T extends AnyFn>¶

📄 `filters`¶

`createFilterWrapper(filter: CancelableEventFilter, fn: T): CancelablePromisifyFn<T>`¶

`bypassFilter(invoke: AnyFn): any`¶

`debounceFilter(ms: MaybeRefOrGetter<number>, options: DebounceFilterOptions): CancelableEventFilter`¶

`throttleFilter(ms: MaybeRefOrGetter<number>, trailing: boolean, leading: boolean, rejectOnCancel: boolean): EventFilter`¶

`pausableFilter(extendFilter: EventFilter, options: PausableFilterOptions): Pausable & { eventFilter: EventFilter }`¶

`wrapper(this: any, args: ArgumentsType<T>): Promise<Awaited<ReturnType<T>>>`¶

`_clearTimeout(timer: TimerHandle): void`¶

`handler(invoke: AnyFn): Promise<any>`¶

`cancel(): void`¶

`flush(): void`¶

`clear(): void`¶

`filter(_invoke: AnyFn): any`¶

`invoke(): any`¶

`pause(): void`¶

`resume(): void`¶

`eventFilter(args: [invoke: AnyFn, options: FunctionWrappe…): void`¶

`FunctionWrapperOptions<Args extends any[] = any[], This = any>`¶

`CancelableEventFilter<Args extends any[] = any[], This = any, Invoke extends AnyFn = AnyFn>`¶

`ConfigurableEventFilter`¶

`DebounceFilterOptions`¶

`ThrottleFilterOptions`¶

`PausableFilterOptions`¶

`FunctionArgs<Args extends any[] = any[], Return = unknown>`¶

`EventFilter<Args extends any[] = any[], This = any, Invoke extends AnyFn = AnyFn>`¶

`CancelablePromisifyFn<T extends AnyFn>`¶