⬅️ Back to Table of Contents

📄 index.ts

📊 Analysis Summary

Metric	Count
🔧 Functions	7
📦 Imports	3
📊 Variables & Constants	5
📐 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
source	T	let/var	initial	✗
track	Fn	let/var	*not shown*	✗
trigger	Fn	let/var	*not shown*	✗
old	T	const	source	✗
controlledRef	<T>(initial: T, options?: ControlledRefOptions<T>) => any	const	refWithControl	✓

---

Functions

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

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 },
  )
}

• JSDoc:

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

• Parameters:

• initial: T
• options: ControlledRefOptions<T>
• Return Type: any
• 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)
  

get(tracking: boolean): T

Code

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

• Parameters:
• tracking: boolean
• Return Type: T
• Calls:
• track

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

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()
  }

• Parameters:
• value: T
• triggering: boolean
• Return Type: void
• Calls:
• options.onBeforeChange
• options.onChanged
• trigger

untrackedGet(): T

Code

() => get(false)

• Return Type: T
• Calls:
• get

silentSet(v: T): void

Code

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

• Parameters:
• v: T
• Return Type: void
• Calls:
• set

peek(): T

Code

() => get(false)

• Return Type: T
• Calls:
• get

lay(v: T): void

Code

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

• Parameters:
• v: T
• Return Type: void
• Calls:
• set

---

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	✓
onChanged	(value: T, oldValue: T) => void	✓

---