⬅️ Back to Table of Contents

📄 refWithControl

📊 Analysis Summary

Metric	Count
🔧 Functions	7
📦 Imports	3
📊 Variables & Constants	1
📐 Interfaces	1

📚 Table of Contents

• Imports
• Variables & Constants
• Functions
• Interfaces

🛠️ File Location:

📂 packages/shared/refWithControl/index.ts

📦 Imports

Name	Source
Fn	../utils
customRef	vue
extendRef	../extendRef

---

Variables & Constants

Name	Type	Kind	Value	Exported
controlledRef	<T>(initial: T, options?: ControlledR...	const	refWithControl	✓

---

Functions

refWithControl(initial: T, options: ControlledRefOptions<T>): any

Fine-grained controls over ref and its reactivity.

Tags: @__NO_SIDE_EFFECTS__

Raw JSDoc

/**
 * Fine-grained controls over ref and its reactivity.
 *
 * @__NO_SIDE_EFFECTS__
 */

Calls:

• customRef (from vue)
• get
• set
• track
• options.onBeforeChange
• options.onChanged
• trigger
• extendRef (from ../extendRef)

Internal Comments:

/**
   * Get the value without tracked in the reactivity system
   */ (x2)
/**
   * Set the value without triggering the reactivity system
   */ (x2)
/**
   * Get the value without tracked in the reactivity system.
   *
   * Alias for `untrackedGet()`
   */ (x2)
/**
   * Set the value without triggering the reactivity system
   *
   * Alias for `silentSet(v)`
   */ (x2)

Code

export function refWithControl<T>(
  initial: T,
  options: ControlledRefOptions<T> = {},
) {
  let source = initial
  let track: Fn
  let trigger: Fn

  const ref = customRef<T>((_track, _trigger) => {
    track = _track
    trigger = _trigger

    return {
      get() {
        return get()
      },
      set(v) {
        set(v)
      },
    }
  })

  function get(tracking = true) {
    if (tracking)
      track()
    return source
  }

  function set(value: T, triggering = true) {
    if (value === source)
      return

    const old = source
    if (options.onBeforeChange?.(value, old) === false)
      return // dismissed

    source = value

    options.onChanged?.(value, old)

    if (triggering)
      trigger()
  }

  /**
   * Get the value without tracked in the reactivity system
   */
  const untrackedGet = () => get(false)
  /**
   * Set the value without triggering the reactivity system
   */
  const silentSet = (v: T) => set(v, false)

  /**
   * Get the value without tracked in the reactivity system.
   *
   * Alias for `untrackedGet()`
   */
  const peek = () => get(false)

  /**
   * Set the value without triggering the reactivity system
   *
   * Alias for `silentSet(v)`
   */
  const lay = (v: T) => set(v, false)

  return extendRef(
    ref,
    {
      get,
      set,
      untrackedGet,
      silentSet,
      peek,
      lay,
    },
    { enumerable: true },
  )
}

Internal helpers

Declared inside another function in this file.

get(tracking: boolean): T

Parameters:

• tracking boolean

Returns: T

Calls:

• track

Code

function get(tracking = true) {
    if (tracking)
      track()
    return source
  }

set(value: T, triggering: boolean): void

Parameters:

• value T
• triggering boolean

Returns: void

Calls:

• options.onBeforeChange
• options.onChanged
• trigger

Code

function set(value: T, triggering = true) {
    if (value === source)
      return

    const old = source
    if (options.onBeforeChange?.(value, old) === false)
      return // dismissed

    source = value

    options.onChanged?.(value, old)

    if (triggering)
      trigger()
  }

untrackedGet(): T

Returns: T

Calls:

• get

Code

() => get(false)

silentSet(v: T): void

Parameters:

• v T

Returns: void

Calls:

• set

Code

(v: T) => set(v, false)

peek(): T

Returns: T

Calls:

• get

Code

() => get(false)

lay(v: T): void

Parameters:

• v T

Returns: void

Calls:

• set

Code

(v: T) => set(v, false)

---

Interfaces

ControlledRefOptions<T>

Interface Code

export interface ControlledRefOptions<T> {
  /**
   * Callback function before the ref changing.
   *
   * Returning `false` to dismiss the change.
   */
  onBeforeChange?: (value: T, oldValue: T) => void | boolean

  /**
   * Callback function after the ref changed
   *
   * This happens synchronously, with less overhead compare to `watch`
   */
  onChanged?: (value: T, oldValue: T) => void
}

Properties

Name	Type	Optional	Description
onBeforeChange	(value: T, oldValue: T) => void \| boolean	✓	not shown
onChanged	(value: T, oldValue: T) => void	✓	not shown

---

Generated by Syntax Scribe