A Tour of ref

tour_of_ref.js

// A Tour of ref()

import { ref, reactive } from 'vue'

/**
ref() - Type Definition:

function ref<T>(value: T): Ref<UnwrapRef<T>>

interface Ref<T> {
  value: T
}
**/

// ref() returns a Ref object with a .value property that contains the argument
let name = ref('Damian')
name.value === 'Damian' // true

// Primitives - number, bigint, boolean, string, null, undefined, symbol

ref(0)
ref(1234567890123456789012345678901234567890n)
ref(true)
ref('hello world')
ref(null)
ref(undefined)
ref(Symbol('id'))
/**
These all result in the same basic form of a Ref object with some internal flags and a value property:

RefImpl {
  __v_isShallow: false,
  dep: undefined,
  __v_isRef: true,
  _rawValue: 0,
  _value: 0,
  __proto__: { constructor: ƒ RefImpl(), value: 0 }
}

where value is the argument passed to the ref() function
**/

// Ref object instances are different even when their values are the same
ref(0) === ref(0) // false

// Objects - objects passed to ref() are first made reactive with reactive() and then wrapped in a Ref

let shape = {
  type: 'circle',
  color: 'blue',
  coordinates: { x: 0, y: 0, z: 0 },
}

let shapeRef = ref(shape)
/**
RefImpl {
  __v_isShallow: false,
  dep: undefined,
  __v_isRef: true,
  _rawValue: {
    type: 'circle',
    color: 'blue',
    coordinates: { x: 0, y: 0, z: 0 }
  },
  _value: Proxy [
    {
      type: 'circle',
      color: 'blue',
      coordinates: { x: 0, y: 0, z: 0 }
    },
    {
      get: ƒ get(),
      set: ƒ set(),
      deleteProperty: ƒ deleteProperty(),
      has: ƒ has(),
      ownKeys: ƒ ownKeys()
    }
  ],
  __proto__: {
    constructor: ƒ RefImpl(),
    value: Proxy [
      {
        type: 'circle',
        color: 'blue',
        coordinates: { x: 0, y: 0, z: 0 }
      },
      {
        get: ƒ get(),
        set: ƒ set(),
        deleteProperty: ƒ deleteProperty(),
        has: ƒ has(),
        ownKeys: ƒ ownKeys()
      }
    ]
  }
}
**/

// Note that the Ref's value is now a Proxy instance and not the original object argument
shapeRef.value === shape // false
shapeRef.value === reactive(shape) // true

// ref() with ref()

// Passing a Ref to ref() will result...
let newShapeRef = ref(shapeRef)

// ...in the same Ref being returned
newShapeRef === shapeRef // true
newShapeRef.value === shapeRef.value // true

// ref() with reactive()

// Passing a reactive object to ref() will result...
let reactiveShape = reactive(shape)

let reactiveShapeRef = ref(reactiveShape)
/**
RefImpl {
  __v_isShallow: false,
  dep: undefined,
  __v_isRef: true,
  _rawValue: {
    type: 'circle',
    color: 'blue',
    coordinates: { x: 0, y: 0, z: 0 }
  },
  _value: Proxy [
    {
      type: 'circle',
      color: 'blue',
      coordinates: { x: 0, y: 0, z: 0 }
    },
    {
      get: ƒ get(),
      set: ƒ set(),
      deleteProperty: ƒ deleteProperty(),
      has: ƒ has(),
      ownKeys: ƒ ownKeys()
    }
  ],
  __proto__: {
    constructor: ƒ RefImpl(),
    value: Proxy [
      {
        type: 'circle',
        color: 'blue',
        coordinates: { x: 0, y: 0, z: 0 }
      },
      {
        get: ƒ get(),
        set: ƒ set(),
        deleteProperty: ƒ deleteProperty(),
        has: ƒ has(),
        ownKeys: ƒ ownKeys()
      }
    ]
  }
}
**/

// ...in the reactive object being wrapped in a Ref
reactiveShape === reactiveShapeRef // false
reactiveShape === reactiveShapeRef.value // true