reactivity-api/utilities

42 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

isRef() function signature and type predicate

isRef() checks if a value is a ref object. The function signature is `function isRef<T>(r: Ref<T> | unknown): r is Ref<T>`. The return type is a type predicate, which means isRef can be used as a type guard to narrow the type of a variable to Ref<unknown> when true.

unref() function signature and behavior

unref() returns the inner value if the argument is a ref, otherwise returns the argument itself. The function signature is `function unref<T>(ref: T | Ref<T>): T`. It is a sugar function equivalent to `val = isRef(val) ? val.value : val`.

toRef() normalization signature (3.3+)

toRef() can normalize values, refs, and getters into refs. The normalization signature is `function toRef<T>(value: T): T extends () => infer R ? Readonly<Ref<R>> : T extends Ref ? T : Ref<UnwrapRef<T>>`. When passed an existing ref, it returns it as-is. When passed a getter function, it creates a readonly ref that calls the getter on .value access. When passed a non-function value, it creates a normal ref.

toRef() object property signature

toRef() can create a ref for a property on a source reactive object. The object property signature is `function toRef<T extends object, K extends keyof T>(object: T, key: K, defaultValue?: T[K]): ToRef<T[K]>` where `type ToRef<T> = T extends Ref ? T : Ref<T>`. The created ref is synced with its source property: mutating the source property updates the ref, and vice-versa.

toRef() vs ref() with object properties

When using toRef() with object properties, the ref is synced with the original property. When using ref() directly on a property value like `ref(state.foo)`, the ref is not synced with state.foo because ref() receives a plain value. toRef() is useful when passing the ref of a prop to a composable function.

toRef() with component props restrictions

When toRef() is used with component props, the usual restrictions around mutating props still apply. Attempting to assign a new value to the ref is equivalent to trying to modify the prop directly and is not allowed. In that scenario, consider using computed() with get and set instead.

toRef() with optional properties

When using toRef() with the object property signature, toRef() will return a usable ref even if the source property doesn't currently exist. This makes it possible to work with optional properties, which would not be picked up by toRefs().

toValue() function signature and behavior

toValue() normalizes values, refs, and getters to values. The function signature is `function toValue<T>(source: T | Ref<T> | (() => T)): T`. Only supported in 3.3+. Similar to unref(), except it also normalizes getters by invoking them and returning their return value.

toRefs() two-way synchronization

toRefs() creates refs that are linked to the original properties. Mutating the original reactive object updates the refs, and mutating the refs updates the original object.

toValue() usage in composables

toValue() can be used in composables to normalize an argument that can be either a value, a ref, or a getter. It supports the MaybeRefOrGetter type from Vue.

toValue() example

toValue(1) returns 1. toValue(ref(1)) returns 1. toValue(() => 1) returns 1.

toRefs() function signature

toRefs() converts a reactive object to a plain object where each property of the resulting object is a ref. The function signature is `function toRefs<T extends object>(object: T): { [K in keyof T]: ToRef<T[K]> }` where `type ToRef = T extends Ref ? T : Ref<T>`. Each individual ref is created using toRef().

toRefs() in composable return patterns

toRefs() is useful when returning a reactive object from a composable function so that the consuming component can destructure or spread the returned object without losing reactivity.

toRefs() enumerable properties limitation

toRefs() will only generate refs for properties that are enumerable on the source object at call time. To create a ref for a property that may not exist yet, use toRef() instead.

isProxy() function signature

isProxy() checks if an object is a proxy created by reactive(), readonly(), shallowReactive(), or shallowReadonly(). The function signature is `function isProxy(value: any): boolean`.

isReactive() function signature

isReactive() checks if an object is a proxy created by reactive() or shallowReactive(). The function signature is `function isReactive(value: unknown): boolean`.

isReadonly() function signature

isReadonly() checks whether the passed value is a readonly object. The properties of a readonly object can change, but they can't be assigned directly via the passed object. The function signature is `function isReadonly(value: unknown): boolean`. Proxies created by readonly() and shallowReadonly() are both considered readonly, as is a computed() ref without a set function.

isShallow() function signature

isShallow() checks if an object is a proxy created by shallowRef, shallowReactive(), or shallowReadonly(). The function signature is `function isShallow(value: unknown): boolean`.

CSSProperties for augmenting style property bindings

CSSProperties is used to augment allowed values in style property bindings. It must be declared in a module using declare module 'vue'. Example: declare module 'vue' { interface CSSProperties { [key: `--${string}`]: string } } allows custom CSS properties like { '--bg-color': 'blue' }. Augmentations must be placed in a module .ts or .d.ts file.

PropType utility type for runtime prop declarations

PropType<T> is imported from 'vue' and used to annotate a prop with more advanced types when using runtime props declarations. It wraps the type in a runtime type declaration. Example: type: Object as PropType<Book> provides more specific type information to the Object type constructor in a props option.

MaybeRef utility type

MaybeRef<T> is an alias for T | Ref<T>. It is only supported in Vue 3.3+. It is useful for annotating arguments of composables.

MaybeRefOrGetter utility type

MaybeRefOrGetter<T> is an alias for T | Ref<T> | (() => T). It is only supported in Vue 3.3+. It is useful for annotating arguments of composables.

ExtractPropTypes extracts internal-facing prop types

ExtractPropTypes<T> extracts prop types from a runtime props options object. The extracted types are internal-facing, meaning the resolved props received by the component. Boolean props and props with default values are always defined, even if they are not required. Example: from { foo: String, bar: Boolean, baz: { type: Number, required: true }, qux: { type: Number, default: 1 } } it extracts { foo?: string, bar: boolean, baz: number, qux: number }.

ExtractPublicPropTypes extracts public-facing prop types

ExtractPublicPropTypes<T> is only supported in Vue 3.3+. It extracts prop types from a runtime props options object as public-facing types, meaning the props that the parent is allowed to pass. Example: from { foo: String, bar: Boolean, baz: { type: Number, required: true }, qux: { type: Number, default: 1 } } it extracts { foo?: string, bar?: boolean, baz: number, qux?: number }. Unlike ExtractPropTypes, optional properties without required: true remain optional, and props with defaults become optional.

ComponentCustomProperties for augmenting global properties

ComponentCustomProperties is used to augment the component instance type to support custom global properties. It must be declared in a module using declare module 'vue'. Example: declare module 'vue' { interface ComponentCustomProperties { $http: typeof axios, $translate: (key: string) => string } }. Augmentations must be placed in a module .ts or .d.ts file.

ComponentCustomOptions for augmenting component options

ComponentCustomOptions is used to augment the component options type to support custom options. It must be declared in a module using declare module 'vue'. Example: declare module 'vue' { interface ComponentCustomOptions { beforeRouteEnter?(to: any, from: any, next: () => void): void } }. Augmentations must be placed in a module .ts or .d.ts file.

ComponentCustomProps for augmenting TSX props

ComponentCustomProps is used to augment allowed TSX props in order to use non-declared props on TSX elements. It must be declared in a module using declare module 'vue'. Example: declare module 'vue' { interface ComponentCustomProps { hello?: string } }. This allows non-declared props like <MyComponent hello="world" /> to work in TSX. Augmentations must be placed in a module .ts or .d.ts file.

v-bind() CSS function for dynamic component state in styles

SFC <style> tags support linking CSS values to dynamic component state using the v-bind() CSS function. This allows for custom properties without type augmentation, as an alternative to augmenting CSSProperties.

nextTick() waits for DOM update completion

The nextTick() global API allows you to wait for the DOM update to complete after a state change. Usage: await nextTick() after mutating state, after which the DOM is updated.

$ref() macro compile-time behavior

The $ref() macro is a compile-time macro, not an actual runtime method. The Vue compiler uses it as a hint to treat the resulting variable as a reactive variable. Reactive variables can be accessed and re-assigned just like normal variables, but these operations are compiled into refs with .value.

$-prefixed macro equivalents for reactivity APIs

Every reactivity API that returns refs has a $-prefixed macro equivalent: ref -> $ref, computed -> $computed, shallowRef -> $shallowRef, customRef -> $customRef, toRef -> $toRef. These macros are globally available and do not need to be imported when Reactivity Transform is enabled, but can optionally be imported from vue/macros.

$() macro for destructuring reactive objects and refs

The $() macro allows destructuring composition functions that return objects of refs. It works on both reactive objects and plain objects containing refs. If a destructured value is already a ref, toRef will return it as-is. If a destructured value is not a ref (e.g. a function), it will be wrapped in a ref.

$() macro converts existing refs to reactive variables

The $() macro can be used to convert any existing refs into reactive variables, allowing wrapped functions that return refs to work with the reactivity transform system.

$$() macro prevents .value appending on reactive variables

The $$() macro is an escape hint that serves to prevent .value from being appended to reactive variables inside it. It is used when passing reactive variables across function boundaries as arguments or when returning them from functions.

$$() on function arguments to retain ref type

When passing a reactive variable as an argument to a function expecting a Ref type, wrap it with $$() to prevent the compiler from extracting the .value. Without $$(), a number would be passed instead of the ref itself.

$$() on returned objects to preserve reactivity

When returning reactive variables from a function, wrap the returned object with $$() to ensure the actual refs are returned rather than their current values. Any reference to reactive variables inside the $$() call will retain the reference to their underlying refs.

TypeScript integration for reactivity transform macros

Vue provides typings for the reactivity transform macros globally and all types work as expected. Macros can work in any files where valid JS/TS are allowed, not just inside Vue SFCs. Type reference can be added with /// <reference types="vue/macros-global" /> or imported explicitly from vue/macros.

$ref() macro example

Example showing $ref() in <script setup>: ```vue <script setup> let count = $ref(0) console.log(count) function increment() { count++ } </script> <template> <button @click="increment">{{ count }}</button> </template> ``` This compiles to use ref(0) with .value access.

$() macro destructuring example

Example showing $() for destructuring: ```js import { useMouse } from '@vueuse/core' const { x, y } = $(useMouse()) console.log(x, y) ``` This compiles to use toRef for each destructured value.

$$() escape hint on function argument example

Example showing $$() to retain ref type when passing as argument: ```ts function trackChange(x: Ref<number>) { watch(x, (x) => { console.log('x changed!') }) } let count = $ref(0) trackChange($$(count)) ``` Without $$(), count.value (a number) would be passed instead of the ref.

Reactivity Transform removed in Vue 3.4

Reactivity Transform was an experimental feature that has been removed in the latest 3.4 release. If you still intend to use it, it is now available via the Vue Macros plugin.

$$() escape hint on return object example

Example showing $$() to preserve reactivity in returned object: ```ts function useMouse() { let x = $ref(0) let y = $ref(0) return $$({x, y}) } ``` Without $$(), the function would return the current values instead of refs.

Give your agent this brain