What do toRef and toRefs do?

<script setup>
import { ref, reactive, toRef, toRefs, computed, defineComponent, h } from "vue";

// A child written with a plain setup(props): destructuring props here is NOT compiled away.
const Greeting = defineComponent({
  props: { name: String },
  setup(props) {
    const { name: copied } = props;          // a plain string, frozen at setup time
    const { name: linked } = toRefs(props);  // a ref that follows the prop
    const shout = computed(() => linked.value.toUpperCase());
    return () => h("p", { id: "child" }, `copied: ${copied} | toRefs: ${linked.value} | computed: ${shout.value}`);
  },
});

// A composable that keeps reactive state inside but hands out refs,
// so callers can destructure the result safely.
function useCart() {
  const state = reactive({ items: 0, total: 0 });
  function add(price) { state.items++; state.total += price; }
  return { ...toRefs(state), add };
}
const { items, total, add } = useCart();

// toRef: one property of a reactive object, as a two-way ref.
const settings = reactive({ theme: "light" });
const theme = toRef(settings, "theme");

const who = ref("Ada");
</script>

<template>
  <Greeting :name="who" />
  <button id="rename" @click="who = who === 'Ada' ? 'Grace' : 'Ada'">Rename</button>
  <p id="cart">{{ items }} items, total {{ total }}</p>
  <button id="add" @click="add(5)">Add 5</button>
  <p id="theme">theme ref: {{ theme }} | settings.theme: {{ settings.theme }}</p>
  <button id="toggle" @click="theme = theme === 'light' ? 'dark' : 'light'">Toggle via ref</button>
</template>

import { reactive, ref, toRef, toRefs, toValue, isRef, isReadonly, readonly, watch, nextTick, unref } from "vue";

const state = reactive({ name: "Ada", age: 36 });

console.log("1. toRef is a two-way link to ONE property");
const age = toRef(state, "age");
age.value++;
console.log(`   after age.value++: state.age=${state.age}`);
state.age = 40;
console.log(`   after state.age=40: age.value=${age.value}`);

console.log("2. toRefs converts EVERY property, so destructuring stays live");
const { name } = toRefs(state);
name.value = "Grace";
console.log(`   state.name=${state.name} | isRef(name)=${isRef(name)}`);

console.log("3. toRefs only sees keys that exist when it is called");
const all = toRefs(state);
state.email = "g@h.io";
console.log(`   keys from toRefs: ${Object.keys(all)} | email in result: ${"email" in all}`);
const email = toRef(state, "email");
console.log(`   toRef for that key works: ${email.value}`);
const missing = toRef(state, "phone");
missing.value = "555";
console.log(`   toRef on a key that did not exist yet, then written: state.phone=${state.phone}`);

console.log("4. toRef with a default value");
const nick = toRef(state, "nick", "anon");
console.log(`   nick.value=${nick.value} (state.nick is ${state.nick})`);

console.log("5. toRef(getter) (3.3+) makes a readonly ref");
const label = toRef(() => `${state.name} (${state.age})`);
console.log(`   label.value=${label.value} | isRef=${isRef(label)} | isReadonly=${isReadonly(label)}`);
try { label.value = "x"; } catch (e) { console.log(`   write throws ${e.constructor.name}: ${e.message}`); }

console.log("6. toRef on a value or ref");
const plain = toRef(5);
const r = ref(1);
console.log(`   toRef(5).value=${plain.value} | toRef(r) === r: ${toRef(r) === r}`);

console.log("7. toRefs on a plain object");
const p = toRefs({ a: 1 });
console.log(`   isRef(p.a)=${isRef(p.a)}`);

console.log("8. toRefs on a readonly proxy keeps it readonly");
const ro = toRefs(readonly(reactive({ x: 1 })));
ro.x.value = 2;
console.log(`   x after write: ${ro.x.value}`);

console.log("9. watching a toRef");
watch(toRef(state, "age"), (v, o) => console.log(`   watch toRef: ${o} -> ${v}`));
state.age = 41; await nextTick();

console.log("10. toValue / unref");
console.log(`   toValue(ref)=${toValue(r)} toValue(getter)=${toValue(() => 7)} unref(getter) is a function: ${typeof unref(() => 7) === "function"}`);