From 79b20355206c806d1e3292d0d4036b5f4f5fc799 Mon Sep 17 00:00:00 2001 From: Henry Lin Date: Mon, 22 May 2023 23:18:42 +0800 Subject: [PATCH] docs: add docs for core functions --- src/core.ts | 240 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 240 insertions(+) diff --git a/src/core.ts b/src/core.ts index 8f9c064..c3f4c91 100644 --- a/src/core.ts +++ b/src/core.ts @@ -25,6 +25,26 @@ import { useRef } from 'react'; export { ref, computed, reactive, readonly } from '@vue/reactivity'; +/** + * The hook version of `ref` from `@vue/reactivity`. + * In addition to values accepted by `ref`, you can also pass an initializer function returning the value. + * + * This hook version allows the ref to be created when the component first render, then cached for future re-renders. + * If you pass in an initializer function, it will only be called on first render. + * + * ----------------------------- + * + * Takes an inner value and returns a reactive and mutable ref object, which + * has a single property `.value` that points to the inner value. + * + * @example + * ```js + * const count = useReference(1) + * ``` + * + * @param value - The object to wrap in the ref, or a function that returns the object. + * @see {@link https://vuejs.org/api/reactivity-core.html#ref} + */ export const useReference = (value: T | (() => T)): Ref> => { const reactiveRef = useRef> | null>(null); if (reactiveRef.current === null) { @@ -44,6 +64,48 @@ interface UseComputed { ): WritableComputedRef; } +/** + * The hook version of `computed` from `@vue/reactivity`. + * + * This hook version allows the computed ref to be created when the component first render, then cached for future re-renders. + * + * ----------------------------- + * + * Takes a getter function and returns a readonly reactive ref object for the + * returned value from the getter. It can also take an object with get and set + * functions to create a writable ref object. + * + * @example + * ```js + * // Inside a function component: + * // Creating a readonly computed ref: + * const count = useReference(1) + * const plusOne = useComputed(() => count.value + 1) + * + * console.log(plusOne.value) // 2 + * plusOne.value++ // error + * ``` + * + * @example + * ```js + * // Inside a function component: + * // Creating a writable computed ref: + * const count = useReference(1) + * const plusOne = useComputed({ + * get: () => count.value + 1, + * set: (val) => { + * count.value = val - 1 + * } + * }) + * + * plusOne.value = 1 + * console.log(count.value) // 0 + * ``` + * + * @param getter - Function that produces the next value. + * @param debugOptions - For debugging. See {@link https://vuejs.org/guide/extras/reactivity-in-depth.html#computed-debugging}. + * @see {@link https://vuejs.org/api/reactivity-core.html#computed} + */ export const useComputed: UseComputed = (( optionsOrGetter: ComputedGetter | WritableComputedOptions, debugOptions?: DebuggerOptions @@ -60,6 +122,35 @@ export const useComputed: UseComputed = (( return reactiveRef.current; }) as UseComputed; +/** + * The hook version of `reactive` from `@vue/reactivity`. + * In addition to values accepted by `reactive`, you can also pass an initializer function returning the value. + * + * This hook version allows the reactive object to be created when the component first render, then cached for future + * re-renders. + * If you pass in an initializer function, it will only be called on first render. + * + * ----------------------------- + * + * Returns a reactive proxy of the object. + * + * The reactive conversion is "deep": it affects all nested properties. A + * reactive object also deeply unwraps any properties that are refs while + * maintaining reactivity. + * + * @example + * ```js + * const obj = useReactive({ count: 0 }) + * ``` + * + * @example + * ```js + * const obj = useReactive(() => ({ count: 0 })) + * ``` + * + * @param target - The source object, or a function that returns the object. + * @see {@link https://vuejs.org/api/reactivity-core.html#reactive} + */ export const useReactive = ( target: T | (() => T) ): UnwrapNestedRefs => { @@ -70,6 +161,45 @@ export const useReactive = ( return reactiveRef.current; }; +/** + * The hook version of `readonly` from `@vue/reactivity`. + * In addition to values accepted by `readonly`, you can also pass an initializer function returning the value. + * + * This hook version allows the readonly ref to be created when the component first render, then cached for future + * re-renders. + * If you pass in an initializer function, it will only be called on first render. + * + * ----------------------------- + * + * Takes an object (reactive or plain) or a ref and returns a readonly proxy to + * the original. + * + * A readonly proxy is deep: any nested property accessed will be readonly as + * well. It also has the same ref-unwrapping behavior as {@link reactive()}, + * except the unwrapped values will also be made readonly. + * + * @example + * ```js + * // Inside a function component: + * const original = useReactive({ count: 0 }) + * + * const copy = useReadonly(original) + * + * useWatchEffect(() => { + * // works for reactivity tracking + * console.log(copy.count) + * }) + * + * // mutating original will trigger watchers relying on the copy + * original.count++ + * + * // mutating the copy will fail and result in a warning + * copy.count++ // warning! + * ``` + * + * @param target - The source object, or a function that returns the object. + * @see {@link https://vuejs.org/api/reactivity-core.html#readonly} + */ export const useReadonly = ( target: T | (() => T) ): DeepReadonly> => { @@ -92,6 +222,36 @@ interface UseWatchEffectRef { cleanup?: CleanupFn | undefined; } +/** + * The hook version of `effect` from `@vue/reactivity`. + * + * This hook version allows the effect to be set up when the component first render, then automatically stopped + * when the component unmounts. + * + * You may return a cleanup function from the given function to clean up side effects before the given function re-runs. + * Note that this syntax follows that of `useEffect` from React, and is not the same as `watchEffect` from Vue. + * + * ----------------------------- + * + * Registers the given function to track reactive updates. + * + * The given function will be run once immediately. Every time any reactive + * property that's accessed within it gets updated, the function will run again. + * + * @example + * ```js + * // Inside a function component: + * const count = useReference(0) + * useWatchEffect(() => { + * console.log(count.value) + * return () => console.log('cleanup') + * }) + * count.value++ + * ``` + * + * @param fn - The function that will track reactive updates. The return value from this function will be used as a cleanup function. + * @param options - Allows to control the effect's behaviour. + */ export const useWatchEffect = ( fn: () => CleanupFn | void, options?: UseWatchEffectOptions @@ -111,6 +271,30 @@ export const useWatchEffect = ( } }; +/** + * An enhanced version of `effect` from `@vue/reactivity`, adding support for a cleanup function. + * + * --------------------------- + * + * Registers the given function to track reactive updates. + * + * The given function will be run once immediately. Every time any reactive + * property that's accessed within it gets updated, the function will run again. + * + * @example + * ```js + * const count = ref(0) + * effect(() => { + * console.log(count.value) + * return () => console.log('cleanup') + * }) + * count.value++ + * ``` + * + * @param fn - The function that will track reactive updates. The return value from this function will be used as a cleanup function. + * @param options - Allows to control the effect's behaviour. + * @returns A runner that can be used to control the effect after creation. + */ export const effect = ( fn: () => CleanupFn | void, options?: ReactiveEffectOptions @@ -187,6 +371,29 @@ interface WatchOverloads { ): WatchStopHandle; } +/** + * Watches one or more reactive data sources and invokes a callback function when the sources change. + * + * @example + * ```js + * const count = ref(0) + * watch(count, (count) => { + * console.log(count) + * return () => console.log('cleanup') + * }) + * count.value++ + * ``` + * + * @param sources - The watcher's source. The source can be one of the following: + * - A getter function that returns a value + * - A ref + * - A reactive object + * - ...or an array of the above. + * @param cb - The callback that will be called when the source changes. It receives the new and old value(s) as arguments. + * @param options - Allows to control the watch's behaviour. + * @returns A function that can be called to stop the watch. + * @see {@link https://vuejs.org/api/reactivity-core.html#watch} + */ export const watch: WatchOverloads = < T extends MultiWatchSources, Immediate extends Readonly = false @@ -318,6 +525,39 @@ interface UseWatchOverloads { ): void; } +/** + * The hook version of `watch`. + * + * This hook version allows the watch to be set up when the component first render, then automatically stopped + * when the component unmounts. + * + * You may return a cleanup function from the callback to clean up side effects before the callback re-runs. + * Note that this syntax follows that of `useEffect` from React, and is not the same as `watch` from Vue. + * + * ----------------------------- + * + * Watches one or more reactive data sources and invokes a callback function when the sources change. + * + * @example + * ```js + * // Inside a function component: + * const count = useReference(0) + * useWatch(count, (count) => { + * console.log(count) + * return () => console.log('cleanup') + * }) + * count.value++ + * ``` + * + * @param sources - The watcher's source. The source can be one of the following: + * - A getter function that returns a value + * - A ref + * - A reactive object + * - ...or an array of the above. + * @param cb - The callback that will be called when the source changes. It receives the new and old value(s) as arguments. + * @param options - Allows to control the watch's behaviour. + * @see {@link https://vuejs.org/api/reactivity-core.html#watch} + */ export const useWatch: UseWatchOverloads = < T extends MultiWatchSources, Immediate extends Readonly = false