From 3008ca69b05ce7bffb54993ee20478ca472e45f9 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sun, 17 May 2020 20:20:51 +0300
Subject: [PATCH 01/35] feat: added composition API reference

---
 src/.vuepress/config.js    |   15 +-
 src/api/composition-api.md | 1058 ++++++++++++++++++++++++++++++++++++
 2 files changed, 1064 insertions(+), 9 deletions(-)
 create mode 100644 src/api/composition-api.md

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index f95a65c933..abc3a880d0 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -52,11 +52,7 @@ const sidebar = {
     {
       title: 'Scaling Up',
       collapsable: false,
-      children: [
-        '/guide/routing',
-        '/guide/state-management',
-        '/guide/ssr'
-      ]
+      children: ['/guide/routing', '/guide/state-management', '/guide/ssr']
     },
     {
       title: 'Migration to Vue 3',
@@ -84,10 +80,11 @@ const sidebar = {
         '/api/options-misc'
       ]
     },
-    '/api/instance-properties.md',
-    '/api/instance-methods.md',
-    '/api/directives.md',
-    '/api/special-attributes.md'
+    '/api/instance-properties',
+    '/api/instance-methods',
+    '/api/directives',
+    '/api/special-attributes',
+    '/api/composition-api'
   ]
 }
 
diff --git a/src/api/composition-api.md b/src/api/composition-api.md
new file mode 100644
index 0000000000..0180602c3c
--- /dev/null
+++ b/src/api/composition-api.md
@@ -0,0 +1,1058 @@
+# Composition API
+
+> This section uses [single-file component](TODO: SFC) syntax for code examples
+
+## `setup`
+
+The `setup` function is a new component option. It serves as the entry point for using the Composition API inside components.
+
+- **Invocation Timing**
+
+  `setup` is called right after the initial props resolution when a component instance is created. Lifecycle-wise, it is called before the `beforeCreate` hook.
+
+- **Usage with Templates**
+
+  If `setup` returns an object, the properties on the object will be merged on to the render context for the component's template:
+
+  ```html
+  <template>
+    <div>{{ count }} {{ object.foo }}</div>
+  </template>
+
+  <script>
+    import { ref, reactive } from 'vue'
+
+    export default {
+      setup() {
+        const count = ref(0)
+        const object = reactive({ foo: 'bar' })
+
+        // expose to template
+        return {
+          count,
+          object
+        }
+      }
+    }
+  </script>
+  ```
+
+  Note that refs returned from `setup` are automatically unwrapped when accessed in the template so there's no need for `.value` in templates.
+
+- **Usage with Render Functions / JSX**
+
+  `setup` can also return a render function, which can directly make use of reactive state declared in the same scope:
+
+  ```js
+  import { h, ref, reactive } from 'vue'
+
+  export default {
+    setup() {
+      const count = ref(0)
+      const object = reactive({ foo: 'bar' })
+
+      return () => h('div', [count.value, object.foo])
+    }
+  }
+  ```
+
+- **Arguments**
+
+  The function receives the resolved props as its first argument:
+
+  ```js
+  export default {
+    props: {
+      name: String
+    },
+    setup(props) {
+      console.log(props.name)
+    }
+  }
+  ```
+
+  Note this `props` object is reactive - i.e. it is updated when new props are passed in, and can be observed and reacted upon using `watchEffect` or `watch`:
+
+  ```js
+  export default {
+    props: {
+      name: String
+    },
+    setup(props) {
+      watchEffect(() => {
+        console.log(`name is: ` + props.name)
+      })
+    }
+  }
+  ```
+
+  However, **do NOT destructure** the `props` object, as it will lose reactivity:
+
+  ```js
+  export default {
+    props: {
+      name: String
+    },
+    setup({ name }) {
+      watchEffect(() => {
+        console.log(`name is: ` + name) // Will not be reactive!
+      })
+    }
+  }
+  ```
+
+  The `props` object is immutable during development (will emit warning if user code attempts to mutate it).
+
+  The second argument provides a context object which exposes a selective list of properties that were previously exposed on `this` in 2.x APIs:
+
+  ```js
+  const MyComponent = {
+    setup(props, context) {
+      context.attrs
+      context.slots
+      context.emit
+    }
+  }
+  ```
+
+  `attrs` and `slots` are proxies to the corresponding values on the internal component instance. This ensures they always expose the latest values even after updates so that we can destructure them without worrying accessing a stale reference:
+
+  ```js
+  const MyComponent = {
+    setup(props, { attrs }) {
+      // a function that may get called at a later stage
+      function onClick() {
+        console.log(attrs.foo) // guaranteed to be the latest reference
+      }
+    }
+  }
+  ```
+
+- **Usage of `this`**
+
+  **`this` is not available inside `setup()`.** Since `setup()` is called before other component options are resolved, `this` inside `setup()` (if made available) will behave quite differently from `this` in other options. Making it available will likely cause confusions when using `setup()` along other 2.x options. Another reason for avoiding `this` in `setup()` is a very common pitfall for beginners:
+
+  ```js
+  setup() {
+    function onClick() {
+      this // not the `this` you'd expect!
+    }
+  }
+  ```
+
+- **Typing**
+
+  ```ts
+  interface Data {
+    [key: string]: unknown
+  }
+
+  interface SetupContext {
+    attrs: Data
+    slots: Slots
+    emit: (event: string, ...args: unknown[]) => void
+  }
+
+  function setup(props: Data, context: SetupContext): Data
+  ```
+
+  ::: tip
+  To get type inference for the arguments passed to `setup()`, the use of [`defineComponent`](#defineComponent) is needed.
+  :::
+
+## Reactivity APIs
+
+### `reactive`
+
+Takes an object and returns a reactive proxy of the original.
+
+```js
+const obj = reactive({ count: 0 })
+```
+
+The reactive conversion is "deep": it affects all nested properties. In the [ES2015 Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) based implementation, the returned proxy is **not** equal to the original object. It is recommended to work exclusively with the reactive proxy and avoid relying on the original object.
+
+- **Typing**
+
+  ```ts
+  function reactive<T extends object>(raw: T): T
+  ```
+
+### `ref`
+
+Takes an inner value and returns a reactive and mutable ref object. The ref object has a single property `.value` that points to the inner value.
+
+```js
+const count = ref(0)
+console.log(count.value) // 0
+
+count.value++
+console.log(count.value) // 1
+```
+
+If an object is assigned as a ref's value, the object is made deeply reactive by the `reactive` method.
+
+- **Access in Templates**
+
+  When a ref is returned as a property on the render context (the object returned from `setup()`) and accessed in the template, it automatically unwraps to the inner value. There is no need to append `.value` in the template:
+
+  ```html
+  <template>
+    <div>{{ count }}</div>
+  </template>
+
+  <script>
+    export default {
+      setup() {
+        return {
+          count: ref(0)
+        }
+      }
+    }
+  </script>
+  ```
+
+- **Access in Reactive Objects**
+
+  When a ref is accessed or mutated as a property of a reactive object, it automatically unwraps to the inner value so it behaves like a normal property:
+
+  ```js
+  const count = ref(0)
+  const state = reactive({
+    count
+  })
+
+  console.log(state.count) // 0
+
+  state.count = 1
+  console.log(count.value) // 1
+  ```
+
+  Note that if a new ref is assigned to a property linked to an existing ref, it will replace the old ref:
+
+  ```js
+  const otherCount = ref(2)
+
+  state.count = otherCount
+  console.log(state.count) // 2
+  console.log(count.value) // 1
+  ```
+
+  Note that ref unwrapping only happens when nested inside a reactive `Object`. There is no unwrapping performed when the ref is accessed from an `Array` or a native collection type like `Map`:
+
+  ```js
+  const arr = reactive([ref(0)])
+  // need .value here
+  console.log(arr[0].value)
+
+  const map = reactive(new Map([['foo', ref(0)]]))
+  // need .value here
+  console.log(map.get('foo').value)
+  ```
+
+- **Typing**
+
+  ```ts
+  interface Ref<T> {
+    value: T
+  }
+
+  function ref<T>(value: T): Ref<T>
+  ```
+
+  Sometimes we may need to specify complex types for a ref's inner value. We can do that succinctly by passing a generics argument when calling `ref` to override the default inference:
+
+  ```ts
+  const foo = ref<string | number>('foo') // foo's type: Ref<string | number>
+
+  foo.value = 123 // ok!
+  ```
+
+### `computed`
+
+Takes a getter function and returns an immutable reactive ref object for the returned value from the getter.
+
+```js
+const count = ref(1)
+const plusOne = computed(() => count.value + 1)
+
+console.log(plusOne.value) // 2
+
+plusOne.value++ // error
+```
+
+Alternatively, it can take an object with `get` and `set` functions to create a writable ref object.
+
+```js
+const count = ref(1)
+const plusOne = computed({
+  get: () => count.value + 1,
+  set: val => {
+    count.value = val - 1
+  }
+})
+
+plusOne.value = 1
+console.log(count.value) // 0
+```
+
+- **Typing**
+
+  ```ts
+  // read-only
+  function computed<T>(getter: () => T): Readonly<Ref<Readonly<T>>>
+
+  // writable
+  function computed<T>(options: {
+    get: () => T
+    set: (value: T) => void
+  }): Ref<T>
+  ```
+
+### `readonly`
+
+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.
+
+```js
+const original = reactive({ count: 0 })
+
+const copy = readonly(original)
+
+watchEffect(() => {
+  // 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!
+```
+
+### `watchEffect`
+
+Run a function immediately while reactively tracking its dependencies, and re-run it whenever the dependencies have changed.
+
+```js
+const count = ref(0)
+
+watchEffect(() => console.log(count.value))
+// -> logs 0
+
+setTimeout(() => {
+  count.value++
+  // -> logs 1
+}, 100)
+```
+
+#### Stopping the Watcher
+
+When `watchEffect` is called during a component's `setup()` function or lifecycle hooks, the watcher is linked to the component's lifecycle, and will be automatically stopped when the component is unmounted.
+
+In other cases, it returns a stop handle which can be called to explicitly stop the watcher:
+
+```js
+const stop = watchEffect(() => {
+  /* ... */
+})
+
+// later
+stop()
+```
+
+#### Side Effect Invalidation
+
+Sometimes the watched effect function will perform async side effects that need to be cleaned up when it is invalidated (i.e state changed before the effects can be completed). The effect function receives an `onInvalidate` function that can be used to register a invalidation callback. The invalidation callback is called when:
+
+- the effect is about to re-run
+- the watcher is stopped (i.e. when the component is unmounted if `watchEffect` is used inside `setup()` or lifecycle hooks)
+
+```js
+watchEffect(onInvalidate => {
+  const token = performAsyncOperation(id.value)
+  onInvalidate(() => {
+    // id has changed or watcher is stopped.
+    // invalidate previously pending async operation
+    token.cancel()
+  })
+})
+```
+
+We are registering the invalidation callback via a passed-in function instead of returning it from the callback because the return value is important for async error handling. It is very common for the effect function to be an async function when performing data fetching:
+
+```js
+const data = ref(null)
+watchEffect(async () => {
+  data.value = await fetchData(props.id)
+})
+```
+
+An async function implicitly returns a Promise, but the cleanup function needs to be registered immediately before the Promise resolves. In addition, Vue relies on the returned Promise to automatically handle potential errors in the Promise chain.
+
+#### Effect Flush Timing
+
+Vue's reactivity system buffers invalidated effects and flush them asynchronously to avoid unnecessary duplicate invocation when there are many state mutations happening in the same "tick". Internally, a component's update function is also a watched effect. When a user effect is queued, it is always invoked after all component update effects:
+
+```html
+<template>
+  <div>{{ count }}</div>
+</template>
+
+<script>
+  export default {
+    setup() {
+      const count = ref(0)
+
+      watchEffect(() => {
+        console.log(count.value)
+      })
+
+      return {
+        count
+      }
+    }
+  }
+</script>
+```
+
+In this example:
+
+- The count will be logged synchronously on initial run.
+- When `count` is mutated, the callback will be called **after** the component has updated.
+
+Note the first run is executed before the component is mounted. So if you wish to access the DOM (or template refs) in a watched effect, do it in the mounted hook:
+
+```js
+onMounted(() => {
+  watchEffect(() => {
+    // access the DOM or template refs
+  })
+})
+```
+
+In cases where a watcher effect needs to be re-run synchronously or before component updates, we can pass an additional options object with the `flush` option (default is `'post'`):
+
+```js
+// fire synchronously
+watchEffect(
+  () => {
+    /* ... */
+  },
+  {
+    flush: 'sync'
+  }
+)
+
+// fire before component updates
+watchEffect(
+  () => {
+    /* ... */
+  },
+  {
+    flush: 'pre'
+  }
+)
+```
+
+#### Watcher Debugging
+
+The `onTrack` and `onTrigger` options can be used to debug a watcher's behavior.
+
+- `onTrack` will be called when a reactive property or ref is tracked as a dependency
+- `onTrigger` will be called when the watcher callback is triggered by the mutation of a dependency
+
+Both callbacks will receive a debugger event which contains information on the dependency in question. It is recommended to place a `debugger` statement in these callbacks to interactively inspect the dependency:
+
+```js
+watchEffect(
+  () => {
+    /* side effect */
+  },
+  {
+    onTrigger(e) {
+      debugger
+    }
+  }
+)
+```
+
+`onTrack` and `onTrigger` only works in development mode.
+
+- **Typing**
+
+  ```ts
+  function watchEffect(
+    effect: (onInvalidate: InvalidateCbRegistrator) => void,
+    options?: WatchEffectOptions
+  ): StopHandle
+
+  interface WatchEffectOptions {
+    flush?: 'pre' | 'post' | 'sync'
+    onTrack?: (event: DebuggerEvent) => void
+    onTrigger?: (event: DebuggerEvent) => void
+  }
+
+  interface DebuggerEvent {
+    effect: ReactiveEffect
+    target: any
+    type: OperationTypes
+    key: string | symbol | undefined
+  }
+
+  type InvalidateCbRegistrator = (invalidate: () => void) => void
+
+  type StopHandle = () => void
+  ```
+
+### `watch`
+
+The `watch` API is the exact equivalent of the Options API [`this.$watch`](./instance-methods.html#watch) (and the corresponding `watch` option). `watch` requires watching a specific data source, and applies side effects in a separate callback function. It also is lazy by default - i.e. the callback is only called when the watched source has changed.
+
+- Compared to `watchEffect`, `watch` allows us to:
+
+  - Perform the side effect lazily;
+  - Be more specific about what state should trigger the watcher to re-run;
+  - Access both the previous and current value of the watched state.
+
+- **Watching a Single Source**
+
+  A watcher data source can either be a getter function that returns a value, or directly a ref:
+
+  ```js
+  // watching a getter
+  const state = reactive({ count: 0 })
+  watch(
+    () => state.count,
+    (count, prevCount) => {
+      /* ... */
+    }
+  )
+
+  // directly watching a ref
+  const count = ref(0)
+  watch(count, (count, prevCount) => {
+    /* ... */
+  })
+  ```
+
+- **Watching Multiple Sources**
+
+  A watcher can also watch multiple sources at the same time using an Array:
+
+  ```js
+  watch([fooRef, barRef], ([foo, bar], [prevFoo, prevBar]) => {
+    /* ... */
+  })
+  ```
+
+* **Shared Behavior with `watchEffect`**
+
+  `watch` shares behavior with `watchEffect` in terms of [manual stoppage](#stopping-the-watcher), [side effect invalidation](#side-effect-invalidation) (with `onInvalidate` passed to the callback as the 3rd argument instead), [flush timing](#effect-flush-timing) and [debugging](#watcher-debugging).
+
+* **Typing**
+
+  ```ts
+  // wacthing single source
+  function watch<T>(
+    source: WatcherSource<T>,
+    callback: (
+      value: T,
+      oldValue: T,
+      onInvalidate: InvalidateCbRegistrator
+    ) => void,
+    options?: WatchOptions
+  ): StopHandle
+
+  // watching multiple sources
+  function watch<T extends WatcherSource<unknown>[]>(
+    sources: T
+    callback: (
+      values: MapSources<T>,
+      oldValues: MapSources<T>,
+      onInvalidate: InvalidateCbRegistrator
+    ) => void,
+    options? : WatchOptions
+  ): StopHandle
+
+  type WatcherSource<T> = Ref<T> | (() => T)
+
+  type MapSources<T> = {
+    [K in keyof T]: T[K] extends WatcherSource<infer V> ? V : never
+  }
+
+  // see `watchEffect` typing for shared options
+  interface WatchOptions extends WatchEffectOptions {
+    immediate?: boolean // default: false
+    deep?: boolean
+  }
+  ```
+
+## Lifecycle Hooks
+
+Lifecycle hooks can be registered with directly imported `onXXX` functions:
+
+```js
+import { onMounted, onUpdated, onUnmounted } from 'vue'
+
+const MyComponent = {
+  setup() {
+    onMounted(() => {
+      console.log('mounted!')
+    })
+    onUpdated(() => {
+      console.log('updated!')
+    })
+    onUnmounted(() => {
+      console.log('unmounted!')
+    })
+  }
+}
+```
+
+These lifecycle hook registration functions can only be used synchronously during `setup()`, since they rely on internal global state to locate the current active instance (the component instance whose `setup()` is being called right now). Calling them without a current active instance will result in an error.
+
+The component instance context is also set during the synchronous execution of lifecycle hooks, so watchers and computed properties created inside synchronously inside lifecycle hooks are also automatically tore down when the component unmounts.
+
+- **Mapping between Options API Lifecycle Options and Composition API**
+
+  - ~~`beforeCreate`~~ -> use `setup()`
+  - ~~`created`~~ -> use `setup()`
+  - `beforeMount` -> `onBeforeMount`
+  - `mounted` -> `onMounted`
+  - `beforeUpdate` -> `onBeforeUpdate`
+  - `updated` -> `onUpdated`
+  - `beforeUnmount` -> `onBeforeUnmount`
+  - `unmounted` -> `onUnmounted`
+  - `errorCaptured` -> `onErrorCaptured`
+  - `renderTracked` -> `onRenderTracked`
+  - `renderTriggered` -> `onRenderTriggered`
+
+## Dependency Injection
+
+`provide` and `inject` enables dependency injection. Both can only be called during `setup()` with a current active instance.
+
+```js
+import { provide, inject } from 'vue'
+
+const ThemeSymbol = Symbol()
+
+const Ancestor = {
+  setup() {
+    provide(ThemeSymbol, 'dark')
+  }
+}
+
+const Descendent = {
+  setup() {
+    const theme = inject(ThemeSymbol, 'light' /* optional default value */)
+    return {
+      theme
+    }
+  }
+}
+```
+
+`inject` accepts an optional default value as the 2nd argument. If a default value is not provided and the property is not found on the provide context, `inject` returns `undefined`.
+
+- **Injection Reactivity**
+
+  To retain reactivity between provided and injected values, a ref can be used:
+
+  ```js
+  // in provider
+  const themeRef = ref('dark')
+  provide(ThemeSymbol, themeRef)
+
+  // in consumer
+  const theme = inject(ThemeSymbol, ref('light'))
+  watchEffect(() => {
+    console.log(`theme set to: ${theme.value}`)
+  })
+  ```
+
+  If a reactive object is injected, it can also be reactively observed.
+
+- **Typing**
+
+  ```ts
+  interface InjectionKey<T> extends Symbol {}
+
+  function provide<T>(key: InjectionKey<T> | string, value: T): void
+
+  // without default value
+  function inject<T>(key: InjectionKey<T> | string): T | undefined
+  // with default value
+  function inject<T>(key: InjectionKey<T> | string, defaultValue: T): T
+  ```
+
+  Vue provides a `InjectionKey` interface which is a generic type that extends `Symbol`. It can be used to sync the type of the injected value between the provider and the consumer:
+
+  ```ts
+  import { InjectionKey, provide, inject } from 'vue'
+
+  const key: InjectionKey<string> = Symbol()
+
+  provide(key, 'foo') // providing non-string value will result in error
+
+  const foo = inject(key) // type of foo: string | undefined
+  ```
+
+  If using string keys or non-typed symbols, the type of the injected value will need to be explicitly declared:
+
+  ```ts
+  const foo = inject<string>('foo') // string | undefined
+  ```
+
+## Template Refs
+
+When using the Composition API, the concept of _reactive refs_ and [template refs](TODO) are unified. In order to obtain a reference to an in-template element or component instance, we can declare a ref as usual and return it from `setup()`:
+
+```html
+<template>
+  <div ref="root"></div>
+</template>
+
+<script>
+  import { ref, onMounted } from 'vue'
+
+  export default {
+    setup() {
+      const root = ref(null)
+
+      onMounted(() => {
+        // the DOM element will be assigned to the ref after initial render
+        console.log(root.value) // <div/>
+      })
+
+      return {
+        root
+      }
+    }
+  }
+</script>
+```
+
+Here we are exposing `root` on the render context and binding it to the div as its ref via `ref="root"`. In the Virtual DOM patching algorithm, if a VNode's `ref` key corresponds to a ref on the render context, then the VNode's corresponding element or component instance will be assigned to the value of that ref. This is performed during the Virtual DOM mount / patch process, so template refs will only get assigned values after the initial render.
+
+Refs used as templates refs behave just like any other refs: they are reactive and can be passed into (or returned from) composition functions.
+
+- **Usage with Render Function / JSX**
+
+  ```js
+  export default {
+    setup() {
+      const root = ref(null)
+
+      return () =>
+        h('div', {
+          ref: root
+        })
+
+      // with JSX
+      return () => <div ref={root} />
+    }
+  }
+  ```
+
+- **Usage inside `v-for`**
+
+  Composition API template refs do not have special handling when used inside `v-for`. Instead, use function refs to perform custom handling:
+
+  ```html
+  <template>
+    <div v-for="(item, i) in list" :ref="el => { divs[i] = el }">
+      {{ item }}
+    </div>
+  </template>
+
+  <script>
+    import { ref, reactive, onBeforeUpdate } from 'vue'
+
+    export default {
+      setup() {
+        const list = reactive([1, 2, 3])
+        const divs = ref([])
+
+        // make sure to reset the refs before each update
+        onBeforeUpdate(() => {
+          divs.value = []
+        })
+
+        return {
+          list,
+          divs
+        }
+      }
+    }
+  </script>
+  ```
+
+## Reactivity Utilities
+
+### `unref`
+
+Returns the inner value if the argument is a ref, otherwise return the argument itself. This is a sugar function for `val = isRef(val) ? val.value : val`.
+
+```js
+function useFoo(x: number | Ref<number>) {
+  const unwrapped = unref(x) // unwrapped is guaranteed to be number now
+}
+```
+
+### `toRef`
+
+`toRef` can be used to create a ref for a property on a source reactive object. The ref can then be passed around and retains the reactive connection to its source property.
+
+```js
+const state = reactive({
+  foo: 1,
+  bar: 2
+})
+
+const fooRef = toRef(state, 'foo')
+
+fooRef.value++
+console.log(state.foo) // 2
+
+state.foo++
+console.log(fooRef.value) // 3
+```
+
+`toRef` is useful when you want to pass the ref of a prop to a composition function:
+
+```js
+export default {
+  setup(props) {
+    useSomeFeature(toRef(props, 'foo'))
+  }
+}
+```
+
+### `toRefs`
+
+Convert a reactive object to a plain object, where each property on the resulting object is a ref pointing to the corresponding property in the original object.
+
+```js
+const state = reactive({
+  foo: 1,
+  bar: 2
+})
+
+const stateAsRefs = toRefs(state)
+/*
+Type of stateAsRefs:
+
+{
+  foo: Ref<number>,
+  bar: Ref<number>
+}
+*/
+
+// The ref and the original property is "linked"
+state.foo++
+console.log(stateAsRefs.foo) // 2
+
+stateAsRefs.foo.value++
+console.log(state.foo) // 3
+```
+
+`toRefs` is useful when returning a reactive object from a composition function so that the consuming component can destructure / spread the returned object without losing reactivity:
+
+```js
+function useFeatureX() {
+  const state = reactive({
+    foo: 1,
+    bar: 2
+  })
+
+  // logic operating on state
+
+  // convert to refs when returning
+  return toRefs(state)
+}
+
+export default {
+  setup() {
+    // can destructure without losing reactivity
+    const { foo, bar } = useFeatureX()
+
+    return {
+      foo,
+      bar
+    }
+  }
+}
+```
+
+### `isRef`
+
+Check if a value is a ref object.
+
+### `isProxy`
+
+Check if an object is a proxy created by `reactive` or `readonly`.
+
+### `isReactive`
+
+Check if an object is a reactive proxy created by `reactive`.
+
+It also returns `true` if the proxy is created by `readonly`, but is wrapping another proxy created by `reactive`.
+
+### `isReadonly`
+
+Check if an object is a readonly proxy created by `readonly`.
+
+## Advanced Reactivity APIs
+
+### `customRef`
+
+Create a customized ref with explicit control over its dependency tracking and update triggering. It expects a factory function. The factory function receives `track` and `trigger` functions as arguments and should return an object with `get` and `set`.
+
+- Example using a custom ref to implement debounce with `v-model`:
+
+  ```html
+  <input v-model="text" />
+  ```
+
+  ```js
+  function useDebouncedRef(value, delay = 200) {
+    let timeout
+    return customRef((track, trigger) => {
+      return {
+        get() {
+          track()
+          return value
+        },
+        set(newValue) {
+          clearTimeout(timeout)
+          timeout = setTimeout(() => {
+            value = newValue
+            trigger()
+          }, delay)
+        }
+      }
+    })
+  }
+
+  export default {
+    setup() {
+      return {
+        text: useDebouncedRef('hello')
+      }
+    }
+  }
+  ```
+
+- **Typing**
+
+  ```ts
+  function customRef<T>(factory: CustomRefFactory<T>): Ref<T>
+
+  type CustomRefFactory<T> = (
+    track: () => void,
+    trigger: () => void
+  ) => {
+    get: () => T
+    set: (value: T) => void
+  }
+  ```
+
+### `markRaw`
+
+Mark an object so that it will never be converted to a proxy. Returns the object itself.
+
+```js
+const foo = markRaw({})
+console.log(isReactive(reactive(foo))) // false
+
+// also works when nested inside other reactive objects
+const bar = reactive({ foo })
+console.log(isReactive(bar.foo)) // false
+```
+
+::: warning
+`markRaw` and the shallowXXX APIs below allow you to selectively opt-out of the default deep reactive / readonly conversion and embed raw, non-proxied objects in your state graph. They can be used for various reasons:
+
+- Some values simply should not be made reactive, for example a complex 3rd party class instance, or a Vue component object.
+
+- Skipping proxy conversion can provide performance improvements when rendering large lists with immutable data sources.
+
+They are considered advanced because the raw opt-out is only at the root level, so if you set a nested, non-marked raw object into a reactive object and then access it again, you get the proxied version back. This can lead to **identity hazards** - i.e. performing an operation that relies on object identity but using both the raw and the proxied version of the same object:
+
+```js
+const foo = markRaw({
+  nested: {}
+})
+
+const bar = reactive({
+  // although `foo` is marked as raw, foo.nested is not.
+  nested: foo.nested
+})
+
+console.log(foo.nested === bar.nested) // false
+```
+
+Identity hazards are in general rare. But to properly utilize these APIs while safely avoiding identity hazards requires a solid understanding of how the reactivity system works.
+:::
+
+### `shallowReactive`
+
+Create a reactive proxy that tracks reactivity of its own properties, but does not perform deep reactive conversion of nested objects (exposes raw values).
+
+```js
+const state = shallowReactive({
+  foo: 1,
+  nested: {
+    bar: 2
+  }
+})
+
+// mutating state's own properties is reactive
+state.foo++
+// ...but does not convert nested objects
+isReactive(state.nested) // false
+state.nested.bar++ // non-reactive
+```
+
+### `shallowReadonly`
+
+Create a proxy that makes its own properties readonly, but does not perform deep readonly conversion of nested objects (exposes raw values).
+
+```js
+const state = shallowReadonly({
+  foo: 1,
+  nested: {
+    bar: 2
+  }
+})
+
+// mutating state's own properties will fail
+state.foo++
+// ...but works on nested objects
+isReadonly(state.nested) // false
+state.nested.bar++ // works
+```
+
+### `shallowRef`
+
+Create a ref that tracks its own `.value` mutation but doesn't make its value reactive.
+
+```js
+const foo = shallowRef({})
+// mutating the ref's value is reactive
+foo.value = {}
+// but the value will not be converted.
+isReactive(foo.value) // false
+```
+
+### `toRaw`
+
+Return the raw, original object of a `reactive` or `readonly` proxy. This is an escape hatch that can be used to temporarily read without incurring proxy access / tracking overhead or write without triggering changes. It is **not** recommended to hold a persistent reference to the original object. Use with caution.
+
+```js
+const foo = {}
+const reactiveFoo = reactive(foo)
+
+console.log(toRaw(reactiveFoo) === foo) // true
+```

From 8110964d9dbc01ba8e976584b6c87cec3b22ba12 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sun, 17 May 2020 20:21:49 +0300
Subject: [PATCH 02/35] fix: changed define component link

---
 src/api/composition-api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index 0180602c3c..05632456e5 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -157,7 +157,7 @@ The `setup` function is a new component option. It serves as the entry point for
   ```
 
   ::: tip
-  To get type inference for the arguments passed to `setup()`, the use of [`defineComponent`](#defineComponent) is needed.
+  To get type inference for the arguments passed to `setup()`, the use of [`defineComponent`](TODO) is needed.
   :::
 
 ## Reactivity APIs

From 6574800f4c6e0834ea716105fdc4235f103579de Mon Sep 17 00:00:00 2001
From: Natalia Tepluhina <tarya.se@gmail.com>
Date: Mon, 18 May 2020 19:21:28 +0300
Subject: [PATCH 03/35] Update src/api/composition-api.md

Co-authored-by: Rahul Kadyan <hi@znck.me>
---
 src/api/composition-api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index 05632456e5..fd46983616 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -737,7 +737,7 @@ Here we are exposing `root` on the render context and binding it to the div as i
 
 Refs used as templates refs behave just like any other refs: they are reactive and can be passed into (or returned from) composition functions.
 
-- **Usage with Render Function / JSX**
+- **Usage with JSX**
 
   ```js
   export default {

From 02dbca45579a8064322ac849b5f22f7c83b08e29 Mon Sep 17 00:00:00 2001
From: Natalia Tepluhina <tarya.se@gmail.com>
Date: Mon, 18 May 2020 19:21:56 +0300
Subject: [PATCH 04/35] Update src/api/composition-api.md

Co-authored-by: Rahul Kadyan <hi@znck.me>
---
 src/api/composition-api.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index fd46983616..15a93d1e57 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -134,6 +134,10 @@ The `setup` function is a new component option. It serves as the entry point for
 
   ```js
   setup() {
+    const that = this
+    function onClick() {
+        console.log(this !== that) // not the `this` you'd expect!
+    }
     function onClick() {
       this // not the `this` you'd expect!
     }

From 0d0b79363319120b95eb13c704967d8ea6b5bbb1 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sun, 17 May 2020 20:20:51 +0300
Subject: [PATCH 05/35] feat: added composition API reference

---
 src/.vuepress/config.js    |    9 +-
 src/api/composition-api.md | 1058 ++++++++++++++++++++++++++++++++++++
 2 files changed, 1063 insertions(+), 4 deletions(-)
 create mode 100644 src/api/composition-api.md

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index cdb3b88400..4c256932dd 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -81,10 +81,11 @@ const sidebar = {
         '/api/options-misc'
       ]
     },
-    '/api/instance-properties.md',
-    '/api/instance-methods.md',
-    '/api/directives.md',
-    '/api/special-attributes.md'
+    '/api/instance-properties',
+    '/api/instance-methods',
+    '/api/directives',
+    '/api/special-attributes',
+    '/api/composition-api'
   ]
 }
 
diff --git a/src/api/composition-api.md b/src/api/composition-api.md
new file mode 100644
index 0000000000..0180602c3c
--- /dev/null
+++ b/src/api/composition-api.md
@@ -0,0 +1,1058 @@
+# Composition API
+
+> This section uses [single-file component](TODO: SFC) syntax for code examples
+
+## `setup`
+
+The `setup` function is a new component option. It serves as the entry point for using the Composition API inside components.
+
+- **Invocation Timing**
+
+  `setup` is called right after the initial props resolution when a component instance is created. Lifecycle-wise, it is called before the `beforeCreate` hook.
+
+- **Usage with Templates**
+
+  If `setup` returns an object, the properties on the object will be merged on to the render context for the component's template:
+
+  ```html
+  <template>
+    <div>{{ count }} {{ object.foo }}</div>
+  </template>
+
+  <script>
+    import { ref, reactive } from 'vue'
+
+    export default {
+      setup() {
+        const count = ref(0)
+        const object = reactive({ foo: 'bar' })
+
+        // expose to template
+        return {
+          count,
+          object
+        }
+      }
+    }
+  </script>
+  ```
+
+  Note that refs returned from `setup` are automatically unwrapped when accessed in the template so there's no need for `.value` in templates.
+
+- **Usage with Render Functions / JSX**
+
+  `setup` can also return a render function, which can directly make use of reactive state declared in the same scope:
+
+  ```js
+  import { h, ref, reactive } from 'vue'
+
+  export default {
+    setup() {
+      const count = ref(0)
+      const object = reactive({ foo: 'bar' })
+
+      return () => h('div', [count.value, object.foo])
+    }
+  }
+  ```
+
+- **Arguments**
+
+  The function receives the resolved props as its first argument:
+
+  ```js
+  export default {
+    props: {
+      name: String
+    },
+    setup(props) {
+      console.log(props.name)
+    }
+  }
+  ```
+
+  Note this `props` object is reactive - i.e. it is updated when new props are passed in, and can be observed and reacted upon using `watchEffect` or `watch`:
+
+  ```js
+  export default {
+    props: {
+      name: String
+    },
+    setup(props) {
+      watchEffect(() => {
+        console.log(`name is: ` + props.name)
+      })
+    }
+  }
+  ```
+
+  However, **do NOT destructure** the `props` object, as it will lose reactivity:
+
+  ```js
+  export default {
+    props: {
+      name: String
+    },
+    setup({ name }) {
+      watchEffect(() => {
+        console.log(`name is: ` + name) // Will not be reactive!
+      })
+    }
+  }
+  ```
+
+  The `props` object is immutable during development (will emit warning if user code attempts to mutate it).
+
+  The second argument provides a context object which exposes a selective list of properties that were previously exposed on `this` in 2.x APIs:
+
+  ```js
+  const MyComponent = {
+    setup(props, context) {
+      context.attrs
+      context.slots
+      context.emit
+    }
+  }
+  ```
+
+  `attrs` and `slots` are proxies to the corresponding values on the internal component instance. This ensures they always expose the latest values even after updates so that we can destructure them without worrying accessing a stale reference:
+
+  ```js
+  const MyComponent = {
+    setup(props, { attrs }) {
+      // a function that may get called at a later stage
+      function onClick() {
+        console.log(attrs.foo) // guaranteed to be the latest reference
+      }
+    }
+  }
+  ```
+
+- **Usage of `this`**
+
+  **`this` is not available inside `setup()`.** Since `setup()` is called before other component options are resolved, `this` inside `setup()` (if made available) will behave quite differently from `this` in other options. Making it available will likely cause confusions when using `setup()` along other 2.x options. Another reason for avoiding `this` in `setup()` is a very common pitfall for beginners:
+
+  ```js
+  setup() {
+    function onClick() {
+      this // not the `this` you'd expect!
+    }
+  }
+  ```
+
+- **Typing**
+
+  ```ts
+  interface Data {
+    [key: string]: unknown
+  }
+
+  interface SetupContext {
+    attrs: Data
+    slots: Slots
+    emit: (event: string, ...args: unknown[]) => void
+  }
+
+  function setup(props: Data, context: SetupContext): Data
+  ```
+
+  ::: tip
+  To get type inference for the arguments passed to `setup()`, the use of [`defineComponent`](#defineComponent) is needed.
+  :::
+
+## Reactivity APIs
+
+### `reactive`
+
+Takes an object and returns a reactive proxy of the original.
+
+```js
+const obj = reactive({ count: 0 })
+```
+
+The reactive conversion is "deep": it affects all nested properties. In the [ES2015 Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) based implementation, the returned proxy is **not** equal to the original object. It is recommended to work exclusively with the reactive proxy and avoid relying on the original object.
+
+- **Typing**
+
+  ```ts
+  function reactive<T extends object>(raw: T): T
+  ```
+
+### `ref`
+
+Takes an inner value and returns a reactive and mutable ref object. The ref object has a single property `.value` that points to the inner value.
+
+```js
+const count = ref(0)
+console.log(count.value) // 0
+
+count.value++
+console.log(count.value) // 1
+```
+
+If an object is assigned as a ref's value, the object is made deeply reactive by the `reactive` method.
+
+- **Access in Templates**
+
+  When a ref is returned as a property on the render context (the object returned from `setup()`) and accessed in the template, it automatically unwraps to the inner value. There is no need to append `.value` in the template:
+
+  ```html
+  <template>
+    <div>{{ count }}</div>
+  </template>
+
+  <script>
+    export default {
+      setup() {
+        return {
+          count: ref(0)
+        }
+      }
+    }
+  </script>
+  ```
+
+- **Access in Reactive Objects**
+
+  When a ref is accessed or mutated as a property of a reactive object, it automatically unwraps to the inner value so it behaves like a normal property:
+
+  ```js
+  const count = ref(0)
+  const state = reactive({
+    count
+  })
+
+  console.log(state.count) // 0
+
+  state.count = 1
+  console.log(count.value) // 1
+  ```
+
+  Note that if a new ref is assigned to a property linked to an existing ref, it will replace the old ref:
+
+  ```js
+  const otherCount = ref(2)
+
+  state.count = otherCount
+  console.log(state.count) // 2
+  console.log(count.value) // 1
+  ```
+
+  Note that ref unwrapping only happens when nested inside a reactive `Object`. There is no unwrapping performed when the ref is accessed from an `Array` or a native collection type like `Map`:
+
+  ```js
+  const arr = reactive([ref(0)])
+  // need .value here
+  console.log(arr[0].value)
+
+  const map = reactive(new Map([['foo', ref(0)]]))
+  // need .value here
+  console.log(map.get('foo').value)
+  ```
+
+- **Typing**
+
+  ```ts
+  interface Ref<T> {
+    value: T
+  }
+
+  function ref<T>(value: T): Ref<T>
+  ```
+
+  Sometimes we may need to specify complex types for a ref's inner value. We can do that succinctly by passing a generics argument when calling `ref` to override the default inference:
+
+  ```ts
+  const foo = ref<string | number>('foo') // foo's type: Ref<string | number>
+
+  foo.value = 123 // ok!
+  ```
+
+### `computed`
+
+Takes a getter function and returns an immutable reactive ref object for the returned value from the getter.
+
+```js
+const count = ref(1)
+const plusOne = computed(() => count.value + 1)
+
+console.log(plusOne.value) // 2
+
+plusOne.value++ // error
+```
+
+Alternatively, it can take an object with `get` and `set` functions to create a writable ref object.
+
+```js
+const count = ref(1)
+const plusOne = computed({
+  get: () => count.value + 1,
+  set: val => {
+    count.value = val - 1
+  }
+})
+
+plusOne.value = 1
+console.log(count.value) // 0
+```
+
+- **Typing**
+
+  ```ts
+  // read-only
+  function computed<T>(getter: () => T): Readonly<Ref<Readonly<T>>>
+
+  // writable
+  function computed<T>(options: {
+    get: () => T
+    set: (value: T) => void
+  }): Ref<T>
+  ```
+
+### `readonly`
+
+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.
+
+```js
+const original = reactive({ count: 0 })
+
+const copy = readonly(original)
+
+watchEffect(() => {
+  // 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!
+```
+
+### `watchEffect`
+
+Run a function immediately while reactively tracking its dependencies, and re-run it whenever the dependencies have changed.
+
+```js
+const count = ref(0)
+
+watchEffect(() => console.log(count.value))
+// -> logs 0
+
+setTimeout(() => {
+  count.value++
+  // -> logs 1
+}, 100)
+```
+
+#### Stopping the Watcher
+
+When `watchEffect` is called during a component's `setup()` function or lifecycle hooks, the watcher is linked to the component's lifecycle, and will be automatically stopped when the component is unmounted.
+
+In other cases, it returns a stop handle which can be called to explicitly stop the watcher:
+
+```js
+const stop = watchEffect(() => {
+  /* ... */
+})
+
+// later
+stop()
+```
+
+#### Side Effect Invalidation
+
+Sometimes the watched effect function will perform async side effects that need to be cleaned up when it is invalidated (i.e state changed before the effects can be completed). The effect function receives an `onInvalidate` function that can be used to register a invalidation callback. The invalidation callback is called when:
+
+- the effect is about to re-run
+- the watcher is stopped (i.e. when the component is unmounted if `watchEffect` is used inside `setup()` or lifecycle hooks)
+
+```js
+watchEffect(onInvalidate => {
+  const token = performAsyncOperation(id.value)
+  onInvalidate(() => {
+    // id has changed or watcher is stopped.
+    // invalidate previously pending async operation
+    token.cancel()
+  })
+})
+```
+
+We are registering the invalidation callback via a passed-in function instead of returning it from the callback because the return value is important for async error handling. It is very common for the effect function to be an async function when performing data fetching:
+
+```js
+const data = ref(null)
+watchEffect(async () => {
+  data.value = await fetchData(props.id)
+})
+```
+
+An async function implicitly returns a Promise, but the cleanup function needs to be registered immediately before the Promise resolves. In addition, Vue relies on the returned Promise to automatically handle potential errors in the Promise chain.
+
+#### Effect Flush Timing
+
+Vue's reactivity system buffers invalidated effects and flush them asynchronously to avoid unnecessary duplicate invocation when there are many state mutations happening in the same "tick". Internally, a component's update function is also a watched effect. When a user effect is queued, it is always invoked after all component update effects:
+
+```html
+<template>
+  <div>{{ count }}</div>
+</template>
+
+<script>
+  export default {
+    setup() {
+      const count = ref(0)
+
+      watchEffect(() => {
+        console.log(count.value)
+      })
+
+      return {
+        count
+      }
+    }
+  }
+</script>
+```
+
+In this example:
+
+- The count will be logged synchronously on initial run.
+- When `count` is mutated, the callback will be called **after** the component has updated.
+
+Note the first run is executed before the component is mounted. So if you wish to access the DOM (or template refs) in a watched effect, do it in the mounted hook:
+
+```js
+onMounted(() => {
+  watchEffect(() => {
+    // access the DOM or template refs
+  })
+})
+```
+
+In cases where a watcher effect needs to be re-run synchronously or before component updates, we can pass an additional options object with the `flush` option (default is `'post'`):
+
+```js
+// fire synchronously
+watchEffect(
+  () => {
+    /* ... */
+  },
+  {
+    flush: 'sync'
+  }
+)
+
+// fire before component updates
+watchEffect(
+  () => {
+    /* ... */
+  },
+  {
+    flush: 'pre'
+  }
+)
+```
+
+#### Watcher Debugging
+
+The `onTrack` and `onTrigger` options can be used to debug a watcher's behavior.
+
+- `onTrack` will be called when a reactive property or ref is tracked as a dependency
+- `onTrigger` will be called when the watcher callback is triggered by the mutation of a dependency
+
+Both callbacks will receive a debugger event which contains information on the dependency in question. It is recommended to place a `debugger` statement in these callbacks to interactively inspect the dependency:
+
+```js
+watchEffect(
+  () => {
+    /* side effect */
+  },
+  {
+    onTrigger(e) {
+      debugger
+    }
+  }
+)
+```
+
+`onTrack` and `onTrigger` only works in development mode.
+
+- **Typing**
+
+  ```ts
+  function watchEffect(
+    effect: (onInvalidate: InvalidateCbRegistrator) => void,
+    options?: WatchEffectOptions
+  ): StopHandle
+
+  interface WatchEffectOptions {
+    flush?: 'pre' | 'post' | 'sync'
+    onTrack?: (event: DebuggerEvent) => void
+    onTrigger?: (event: DebuggerEvent) => void
+  }
+
+  interface DebuggerEvent {
+    effect: ReactiveEffect
+    target: any
+    type: OperationTypes
+    key: string | symbol | undefined
+  }
+
+  type InvalidateCbRegistrator = (invalidate: () => void) => void
+
+  type StopHandle = () => void
+  ```
+
+### `watch`
+
+The `watch` API is the exact equivalent of the Options API [`this.$watch`](./instance-methods.html#watch) (and the corresponding `watch` option). `watch` requires watching a specific data source, and applies side effects in a separate callback function. It also is lazy by default - i.e. the callback is only called when the watched source has changed.
+
+- Compared to `watchEffect`, `watch` allows us to:
+
+  - Perform the side effect lazily;
+  - Be more specific about what state should trigger the watcher to re-run;
+  - Access both the previous and current value of the watched state.
+
+- **Watching a Single Source**
+
+  A watcher data source can either be a getter function that returns a value, or directly a ref:
+
+  ```js
+  // watching a getter
+  const state = reactive({ count: 0 })
+  watch(
+    () => state.count,
+    (count, prevCount) => {
+      /* ... */
+    }
+  )
+
+  // directly watching a ref
+  const count = ref(0)
+  watch(count, (count, prevCount) => {
+    /* ... */
+  })
+  ```
+
+- **Watching Multiple Sources**
+
+  A watcher can also watch multiple sources at the same time using an Array:
+
+  ```js
+  watch([fooRef, barRef], ([foo, bar], [prevFoo, prevBar]) => {
+    /* ... */
+  })
+  ```
+
+* **Shared Behavior with `watchEffect`**
+
+  `watch` shares behavior with `watchEffect` in terms of [manual stoppage](#stopping-the-watcher), [side effect invalidation](#side-effect-invalidation) (with `onInvalidate` passed to the callback as the 3rd argument instead), [flush timing](#effect-flush-timing) and [debugging](#watcher-debugging).
+
+* **Typing**
+
+  ```ts
+  // wacthing single source
+  function watch<T>(
+    source: WatcherSource<T>,
+    callback: (
+      value: T,
+      oldValue: T,
+      onInvalidate: InvalidateCbRegistrator
+    ) => void,
+    options?: WatchOptions
+  ): StopHandle
+
+  // watching multiple sources
+  function watch<T extends WatcherSource<unknown>[]>(
+    sources: T
+    callback: (
+      values: MapSources<T>,
+      oldValues: MapSources<T>,
+      onInvalidate: InvalidateCbRegistrator
+    ) => void,
+    options? : WatchOptions
+  ): StopHandle
+
+  type WatcherSource<T> = Ref<T> | (() => T)
+
+  type MapSources<T> = {
+    [K in keyof T]: T[K] extends WatcherSource<infer V> ? V : never
+  }
+
+  // see `watchEffect` typing for shared options
+  interface WatchOptions extends WatchEffectOptions {
+    immediate?: boolean // default: false
+    deep?: boolean
+  }
+  ```
+
+## Lifecycle Hooks
+
+Lifecycle hooks can be registered with directly imported `onXXX` functions:
+
+```js
+import { onMounted, onUpdated, onUnmounted } from 'vue'
+
+const MyComponent = {
+  setup() {
+    onMounted(() => {
+      console.log('mounted!')
+    })
+    onUpdated(() => {
+      console.log('updated!')
+    })
+    onUnmounted(() => {
+      console.log('unmounted!')
+    })
+  }
+}
+```
+
+These lifecycle hook registration functions can only be used synchronously during `setup()`, since they rely on internal global state to locate the current active instance (the component instance whose `setup()` is being called right now). Calling them without a current active instance will result in an error.
+
+The component instance context is also set during the synchronous execution of lifecycle hooks, so watchers and computed properties created inside synchronously inside lifecycle hooks are also automatically tore down when the component unmounts.
+
+- **Mapping between Options API Lifecycle Options and Composition API**
+
+  - ~~`beforeCreate`~~ -> use `setup()`
+  - ~~`created`~~ -> use `setup()`
+  - `beforeMount` -> `onBeforeMount`
+  - `mounted` -> `onMounted`
+  - `beforeUpdate` -> `onBeforeUpdate`
+  - `updated` -> `onUpdated`
+  - `beforeUnmount` -> `onBeforeUnmount`
+  - `unmounted` -> `onUnmounted`
+  - `errorCaptured` -> `onErrorCaptured`
+  - `renderTracked` -> `onRenderTracked`
+  - `renderTriggered` -> `onRenderTriggered`
+
+## Dependency Injection
+
+`provide` and `inject` enables dependency injection. Both can only be called during `setup()` with a current active instance.
+
+```js
+import { provide, inject } from 'vue'
+
+const ThemeSymbol = Symbol()
+
+const Ancestor = {
+  setup() {
+    provide(ThemeSymbol, 'dark')
+  }
+}
+
+const Descendent = {
+  setup() {
+    const theme = inject(ThemeSymbol, 'light' /* optional default value */)
+    return {
+      theme
+    }
+  }
+}
+```
+
+`inject` accepts an optional default value as the 2nd argument. If a default value is not provided and the property is not found on the provide context, `inject` returns `undefined`.
+
+- **Injection Reactivity**
+
+  To retain reactivity between provided and injected values, a ref can be used:
+
+  ```js
+  // in provider
+  const themeRef = ref('dark')
+  provide(ThemeSymbol, themeRef)
+
+  // in consumer
+  const theme = inject(ThemeSymbol, ref('light'))
+  watchEffect(() => {
+    console.log(`theme set to: ${theme.value}`)
+  })
+  ```
+
+  If a reactive object is injected, it can also be reactively observed.
+
+- **Typing**
+
+  ```ts
+  interface InjectionKey<T> extends Symbol {}
+
+  function provide<T>(key: InjectionKey<T> | string, value: T): void
+
+  // without default value
+  function inject<T>(key: InjectionKey<T> | string): T | undefined
+  // with default value
+  function inject<T>(key: InjectionKey<T> | string, defaultValue: T): T
+  ```
+
+  Vue provides a `InjectionKey` interface which is a generic type that extends `Symbol`. It can be used to sync the type of the injected value between the provider and the consumer:
+
+  ```ts
+  import { InjectionKey, provide, inject } from 'vue'
+
+  const key: InjectionKey<string> = Symbol()
+
+  provide(key, 'foo') // providing non-string value will result in error
+
+  const foo = inject(key) // type of foo: string | undefined
+  ```
+
+  If using string keys or non-typed symbols, the type of the injected value will need to be explicitly declared:
+
+  ```ts
+  const foo = inject<string>('foo') // string | undefined
+  ```
+
+## Template Refs
+
+When using the Composition API, the concept of _reactive refs_ and [template refs](TODO) are unified. In order to obtain a reference to an in-template element or component instance, we can declare a ref as usual and return it from `setup()`:
+
+```html
+<template>
+  <div ref="root"></div>
+</template>
+
+<script>
+  import { ref, onMounted } from 'vue'
+
+  export default {
+    setup() {
+      const root = ref(null)
+
+      onMounted(() => {
+        // the DOM element will be assigned to the ref after initial render
+        console.log(root.value) // <div/>
+      })
+
+      return {
+        root
+      }
+    }
+  }
+</script>
+```
+
+Here we are exposing `root` on the render context and binding it to the div as its ref via `ref="root"`. In the Virtual DOM patching algorithm, if a VNode's `ref` key corresponds to a ref on the render context, then the VNode's corresponding element or component instance will be assigned to the value of that ref. This is performed during the Virtual DOM mount / patch process, so template refs will only get assigned values after the initial render.
+
+Refs used as templates refs behave just like any other refs: they are reactive and can be passed into (or returned from) composition functions.
+
+- **Usage with Render Function / JSX**
+
+  ```js
+  export default {
+    setup() {
+      const root = ref(null)
+
+      return () =>
+        h('div', {
+          ref: root
+        })
+
+      // with JSX
+      return () => <div ref={root} />
+    }
+  }
+  ```
+
+- **Usage inside `v-for`**
+
+  Composition API template refs do not have special handling when used inside `v-for`. Instead, use function refs to perform custom handling:
+
+  ```html
+  <template>
+    <div v-for="(item, i) in list" :ref="el => { divs[i] = el }">
+      {{ item }}
+    </div>
+  </template>
+
+  <script>
+    import { ref, reactive, onBeforeUpdate } from 'vue'
+
+    export default {
+      setup() {
+        const list = reactive([1, 2, 3])
+        const divs = ref([])
+
+        // make sure to reset the refs before each update
+        onBeforeUpdate(() => {
+          divs.value = []
+        })
+
+        return {
+          list,
+          divs
+        }
+      }
+    }
+  </script>
+  ```
+
+## Reactivity Utilities
+
+### `unref`
+
+Returns the inner value if the argument is a ref, otherwise return the argument itself. This is a sugar function for `val = isRef(val) ? val.value : val`.
+
+```js
+function useFoo(x: number | Ref<number>) {
+  const unwrapped = unref(x) // unwrapped is guaranteed to be number now
+}
+```
+
+### `toRef`
+
+`toRef` can be used to create a ref for a property on a source reactive object. The ref can then be passed around and retains the reactive connection to its source property.
+
+```js
+const state = reactive({
+  foo: 1,
+  bar: 2
+})
+
+const fooRef = toRef(state, 'foo')
+
+fooRef.value++
+console.log(state.foo) // 2
+
+state.foo++
+console.log(fooRef.value) // 3
+```
+
+`toRef` is useful when you want to pass the ref of a prop to a composition function:
+
+```js
+export default {
+  setup(props) {
+    useSomeFeature(toRef(props, 'foo'))
+  }
+}
+```
+
+### `toRefs`
+
+Convert a reactive object to a plain object, where each property on the resulting object is a ref pointing to the corresponding property in the original object.
+
+```js
+const state = reactive({
+  foo: 1,
+  bar: 2
+})
+
+const stateAsRefs = toRefs(state)
+/*
+Type of stateAsRefs:
+
+{
+  foo: Ref<number>,
+  bar: Ref<number>
+}
+*/
+
+// The ref and the original property is "linked"
+state.foo++
+console.log(stateAsRefs.foo) // 2
+
+stateAsRefs.foo.value++
+console.log(state.foo) // 3
+```
+
+`toRefs` is useful when returning a reactive object from a composition function so that the consuming component can destructure / spread the returned object without losing reactivity:
+
+```js
+function useFeatureX() {
+  const state = reactive({
+    foo: 1,
+    bar: 2
+  })
+
+  // logic operating on state
+
+  // convert to refs when returning
+  return toRefs(state)
+}
+
+export default {
+  setup() {
+    // can destructure without losing reactivity
+    const { foo, bar } = useFeatureX()
+
+    return {
+      foo,
+      bar
+    }
+  }
+}
+```
+
+### `isRef`
+
+Check if a value is a ref object.
+
+### `isProxy`
+
+Check if an object is a proxy created by `reactive` or `readonly`.
+
+### `isReactive`
+
+Check if an object is a reactive proxy created by `reactive`.
+
+It also returns `true` if the proxy is created by `readonly`, but is wrapping another proxy created by `reactive`.
+
+### `isReadonly`
+
+Check if an object is a readonly proxy created by `readonly`.
+
+## Advanced Reactivity APIs
+
+### `customRef`
+
+Create a customized ref with explicit control over its dependency tracking and update triggering. It expects a factory function. The factory function receives `track` and `trigger` functions as arguments and should return an object with `get` and `set`.
+
+- Example using a custom ref to implement debounce with `v-model`:
+
+  ```html
+  <input v-model="text" />
+  ```
+
+  ```js
+  function useDebouncedRef(value, delay = 200) {
+    let timeout
+    return customRef((track, trigger) => {
+      return {
+        get() {
+          track()
+          return value
+        },
+        set(newValue) {
+          clearTimeout(timeout)
+          timeout = setTimeout(() => {
+            value = newValue
+            trigger()
+          }, delay)
+        }
+      }
+    })
+  }
+
+  export default {
+    setup() {
+      return {
+        text: useDebouncedRef('hello')
+      }
+    }
+  }
+  ```
+
+- **Typing**
+
+  ```ts
+  function customRef<T>(factory: CustomRefFactory<T>): Ref<T>
+
+  type CustomRefFactory<T> = (
+    track: () => void,
+    trigger: () => void
+  ) => {
+    get: () => T
+    set: (value: T) => void
+  }
+  ```
+
+### `markRaw`
+
+Mark an object so that it will never be converted to a proxy. Returns the object itself.
+
+```js
+const foo = markRaw({})
+console.log(isReactive(reactive(foo))) // false
+
+// also works when nested inside other reactive objects
+const bar = reactive({ foo })
+console.log(isReactive(bar.foo)) // false
+```
+
+::: warning
+`markRaw` and the shallowXXX APIs below allow you to selectively opt-out of the default deep reactive / readonly conversion and embed raw, non-proxied objects in your state graph. They can be used for various reasons:
+
+- Some values simply should not be made reactive, for example a complex 3rd party class instance, or a Vue component object.
+
+- Skipping proxy conversion can provide performance improvements when rendering large lists with immutable data sources.
+
+They are considered advanced because the raw opt-out is only at the root level, so if you set a nested, non-marked raw object into a reactive object and then access it again, you get the proxied version back. This can lead to **identity hazards** - i.e. performing an operation that relies on object identity but using both the raw and the proxied version of the same object:
+
+```js
+const foo = markRaw({
+  nested: {}
+})
+
+const bar = reactive({
+  // although `foo` is marked as raw, foo.nested is not.
+  nested: foo.nested
+})
+
+console.log(foo.nested === bar.nested) // false
+```
+
+Identity hazards are in general rare. But to properly utilize these APIs while safely avoiding identity hazards requires a solid understanding of how the reactivity system works.
+:::
+
+### `shallowReactive`
+
+Create a reactive proxy that tracks reactivity of its own properties, but does not perform deep reactive conversion of nested objects (exposes raw values).
+
+```js
+const state = shallowReactive({
+  foo: 1,
+  nested: {
+    bar: 2
+  }
+})
+
+// mutating state's own properties is reactive
+state.foo++
+// ...but does not convert nested objects
+isReactive(state.nested) // false
+state.nested.bar++ // non-reactive
+```
+
+### `shallowReadonly`
+
+Create a proxy that makes its own properties readonly, but does not perform deep readonly conversion of nested objects (exposes raw values).
+
+```js
+const state = shallowReadonly({
+  foo: 1,
+  nested: {
+    bar: 2
+  }
+})
+
+// mutating state's own properties will fail
+state.foo++
+// ...but works on nested objects
+isReadonly(state.nested) // false
+state.nested.bar++ // works
+```
+
+### `shallowRef`
+
+Create a ref that tracks its own `.value` mutation but doesn't make its value reactive.
+
+```js
+const foo = shallowRef({})
+// mutating the ref's value is reactive
+foo.value = {}
+// but the value will not be converted.
+isReactive(foo.value) // false
+```
+
+### `toRaw`
+
+Return the raw, original object of a `reactive` or `readonly` proxy. This is an escape hatch that can be used to temporarily read without incurring proxy access / tracking overhead or write without triggering changes. It is **not** recommended to hold a persistent reference to the original object. Use with caution.
+
+```js
+const foo = {}
+const reactiveFoo = reactive(foo)
+
+console.log(toRaw(reactiveFoo) === foo) // true
+```

From cbf00f83f16116793c4b04ad512eda8aa2ba6718 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sun, 17 May 2020 20:21:49 +0300
Subject: [PATCH 06/35] fix: changed define component link

---
 src/api/composition-api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index 0180602c3c..05632456e5 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -157,7 +157,7 @@ The `setup` function is a new component option. It serves as the entry point for
   ```
 
   ::: tip
-  To get type inference for the arguments passed to `setup()`, the use of [`defineComponent`](#defineComponent) is needed.
+  To get type inference for the arguments passed to `setup()`, the use of [`defineComponent`](TODO) is needed.
   :::
 
 ## Reactivity APIs

From 16f3ff5f9f94f08ba5005cc538ba76b2f8f83fe1 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sat, 23 May 2020 16:21:14 +0300
Subject: [PATCH 07/35] fix: move arguments above usecases

---
 src/api/composition-api.md | 92 +++++++++++++++++++-------------------
 1 file changed, 46 insertions(+), 46 deletions(-)

diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index 89384b73ad..780d249ebb 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -10,52 +10,6 @@ The `setup` function is a new component option. It serves as the entry point for
 
   `setup` is called right after the initial props resolution when a component instance is created. Lifecycle-wise, it is called before the `beforeCreate` hook.
 
-- **Usage with Templates**
-
-  If `setup` returns an object, the properties on the object will be merged on to the render context for the component's template:
-
-  ```html
-  <template>
-    <div>{{ count }} {{ object.foo }}</div>
-  </template>
-
-  <script>
-    import { ref, reactive } from 'vue'
-
-    export default {
-      setup() {
-        const count = ref(0)
-        const object = reactive({ foo: 'bar' })
-
-        // expose to template
-        return {
-          count,
-          object
-        }
-      }
-    }
-  </script>
-  ```
-
-  Note that refs returned from `setup` are automatically unwrapped when accessed in the template so there's no need for `.value` in templates.
-
-- **Usage with Render Functions / JSX**
-
-  `setup` can also return a render function, which can directly make use of reactive state declared in the same scope:
-
-  ```js
-  import { h, ref, reactive } from 'vue'
-
-  export default {
-    setup() {
-      const count = ref(0)
-      const object = reactive({ foo: 'bar' })
-
-      return () => h('div', [count.value, object.foo])
-    }
-  }
-  ```
-
 - **Arguments**
 
   The function receives the resolved props as its first argument:
@@ -128,6 +82,52 @@ The `setup` function is a new component option. It serves as the entry point for
   }
   ```
 
+- **Usage with Templates**
+
+  If `setup` returns an object, the properties on the object will be merged on to the render context for the component's template:
+
+  ```html
+  <template>
+    <div>{{ count }} {{ object.foo }}</div>
+  </template>
+
+  <script>
+    import { ref, reactive } from 'vue'
+
+    export default {
+      setup() {
+        const count = ref(0)
+        const object = reactive({ foo: 'bar' })
+
+        // expose to template
+        return {
+          count,
+          object
+        }
+      }
+    }
+  </script>
+  ```
+
+  Note that refs returned from `setup` are automatically unwrapped when accessed in the template so there's no need for `.value` in templates.
+
+- **Usage with Render Functions**
+
+  `setup` can also return a render function, which can directly make use of reactive state declared in the same scope:
+
+  ```js
+  import { h, ref, reactive } from 'vue'
+
+  export default {
+    setup() {
+      const count = ref(0)
+      const object = reactive({ foo: 'bar' })
+
+      return () => h('div', [count.value, object.foo])
+    }
+  }
+  ```
+
 - **Usage of `this`**
 
   **`this` is not available inside `setup()`.** Since `setup()` is called before other component options are resolved, `this` inside `setup()` (if made available) will behave quite differently from `this` in other options. Making it available will likely cause confusions when using `setup()` along other 2.x options. Another reason for avoiding `this` in `setup()` is a very common pitfall for beginners:

From 99ca2869513c684f3d05a3af0f2455c442205da0 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sat, 23 May 2020 16:29:24 +0300
Subject: [PATCH 08/35] feat: added example for attrs destructuring

---
 src/api/composition-api.md | 54 +++++++++++++++++++++++---------------
 1 file changed, 33 insertions(+), 21 deletions(-)

diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index 780d249ebb..05bc0ca432 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -69,7 +69,7 @@ The `setup` function is a new component option. It serves as the entry point for
   }
   ```
 
-  `attrs` and `slots` are proxies to the corresponding values on the internal component instance. This ensures they always expose the latest values even after updates so that we can destructure them without worrying accessing a stale reference:
+  Unlike `props`, `context` argument can be destructured safely so `attrs` and `slots` would always expose the latest values even after updates:
 
   ```js
   const MyComponent = {
@@ -82,34 +82,46 @@ The `setup` function is a new component option. It serves as the entry point for
   }
   ```
 
-- **Usage with Templates**
+  However, `attrs` and `slots` themselves cannot be destructured without losing reactivity:
 
-  If `setup` returns an object, the properties on the object will be merged on to the render context for the component's template:
+  ```js
+  const MyComponent = {
+    setup(props, { attrs: { foo } }) {
+      function onClick() {
+        console.log(foo) // won't be the latest reference as we lost `attrs` reactivity with destructuring
+      }
+    }
+  }
+  ```
 
-  ```html
-  <template>
-    <div>{{ count }} {{ object.foo }}</div>
-  </template>
+**Usage with Templates**
 
-  <script>
-    import { ref, reactive } from 'vue'
+If `setup` returns an object, the properties on the object will be merged on to the render context for the component's template:
 
-    export default {
-      setup() {
-        const count = ref(0)
-        const object = reactive({ foo: 'bar' })
+```html
+<template>
+  <div>{{ count }} {{ object.foo }}</div>
+</template>
 
-        // expose to template
-        return {
-          count,
-          object
-        }
+<script>
+  import { ref, reactive } from 'vue'
+
+  export default {
+    setup() {
+      const count = ref(0)
+      const object = reactive({ foo: 'bar' })
+
+      // expose to template
+      return {
+        count,
+        object
       }
     }
-  </script>
-  ```
+  }
+</script>
+```
 
-  Note that refs returned from `setup` are automatically unwrapped when accessed in the template so there's no need for `.value` in templates.
+Note that refs returned from `setup` are automatically unwrapped when accessed in the template so there's no need for `.value` in templates.
 
 - **Usage with Render Functions**
 

From 17b8e47833caf8fab77255cb6b53f3b4ec7820b0 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sat, 23 May 2020 16:32:19 +0300
Subject: [PATCH 09/35] fix: fixed `this` usage explanation

---
 src/api/composition-api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index 05bc0ca432..ef821ead45 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -142,7 +142,7 @@ Note that refs returned from `setup` are automatically unwrapped when accessed i
 
 - **Usage of `this`**
 
-  **`this` is not available inside `setup()`.** Since `setup()` is called before other component options are resolved, `this` inside `setup()` (if made available) will behave quite differently from `this` in other options. Making it available will likely cause confusions when using `setup()` along other 2.x options. Another reason for avoiding `this` in `setup()` is a very common pitfall for beginners:
+  **Inside `setup()`, `this` won't be a reference to Vue instance** Since `setup()` is called before other component options are resolved, `this` inside `setup()` will behave quite differently from `this` in other options. This might cause confusions when using `setup()` along other Options API. Another reason for avoiding `this` in `setup()` is a very common pitfall for beginners:
 
   ```js
   setup() {

From 0d78a4bd8deaa7b1bac2053b0eb19d77ae109024 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sat, 23 May 2020 16:48:31 +0300
Subject: [PATCH 10/35] feat: added explanation about inline event handler

---
 src/api/composition-api.md | 40 ++++++++++++++++++++++++++++++++++----
 1 file changed, 36 insertions(+), 4 deletions(-)

diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index ef821ead45..8dcd40fa4c 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -211,21 +211,53 @@ If an object is assigned as a ref's value, the object is made deeply reactive by
 
   ```html
   <template>
-    <div>{{ count }}</div>
+    <div>
+      <span>{{ count }}</span>
+      <button @click="count ++">Increment count</button>
+    </div>
+  </template>
+
+  <script>
+    import { ref } from 'vue'
+    export default {
+      setup() {
+        const count = ref(0)
+        return {
+          count
+        }
+      }
+    }
+  </script>
+  ```
+
+  However, if we decide to change the inline event handler on button click to the component method declared in `setup`, we need to remember that `ref` is not unwrapped there:
+
+  ```html
+  <template>
+    <div>
+      <span>{{ count }}</span>
+      <button @click="increment">Increment count</button>
+    </div>
   </template>
 
   <script>
+    import { ref } from 'vue'
     export default {
       setup() {
+        const count = ref(0)
+        function increment() {
+          count.value++ // ref is not unwrapped outside the template, so we need to use .value here
+        }
         return {
-          count: ref(0)
+          count,
+          increment
         }
       }
     }
   </script>
   ```
 
-- **Access in Reactive Objects**
+* **Access in Reactive Objects**
 
   When a ref is accessed or mutated as a property of a reactive object, it automatically unwraps to the inner value so it behaves like a normal property:
 
@@ -263,7 +295,7 @@ If an object is assigned as a ref's value, the object is made deeply reactive by
   console.log(map.get('foo').value)
   ```
 
-- **Typing**
+* **Typing**
 
   ```ts
   interface Ref<T> {

From 3c99243222ae19f8b4d348c47a6d09d9808db4e6 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sat, 23 May 2020 17:09:42 +0300
Subject: [PATCH 11/35] fix: added example to `isReactive`

---
 src/api/composition-api.md | 36 ++++++++++++++++++++++++++++++++++++
 1 file changed, 36 insertions(+)

diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index 8dcd40fa4c..f4c757fccf 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -782,6 +782,10 @@ Here we are exposing `root` on the render context and binding it to the div as i
 
 Refs used as templates refs behave just like any other refs: they are reactive and can be passed into (or returned from) composition functions.
 
+:::warning
+Please note that `ref` will behave differently when used with `v-bind` directive. `ref="root"` would be equivalent to `:ref="el => root = el"`
+:::
+
 - **Usage with JSX**
 
   ```js
@@ -942,8 +946,40 @@ Check if an object is a proxy created by `reactive` or `readonly`.
 
 Check if an object is a reactive proxy created by `reactive`.
 
+```js
+import { reactive, isReactive } from 'vue'
+export default {
+  setup() {
+    const state = reactive({
+      name: 'John'
+    })
+    console.log(isReactive(state)) // -> true
+  }
+}
+```
+
 It also returns `true` if the proxy is created by `readonly`, but is wrapping another proxy created by `reactive`.
 
+```js{7-15}
+import { reactive, isReactive, readonly } from 'vue'
+export default {
+  setup() {
+    const state = reactive({
+      name: 'John'
+    })
+    // readonly proxy created from plain object
+    const plain = readonly({
+      name: 'Mary'
+    })
+    console.log(isReactive(plain)) // -> false
+
+    // readonly proxy created from reactive proxy
+    const stateCopy = readonly(state)
+    console.log(isReactive(stateCopy)) // -> true
+  }
+}
+```
+
 ### `isReadonly`
 
 Check if an object is a readonly proxy created by `readonly`.

From 43a7c2ba687076573e64f645105377d94858f83a Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sat, 23 May 2020 17:11:14 +0300
Subject: [PATCH 12/35] fix: grammar

---
 src/api/composition-api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index f4c757fccf..c4457f76b3 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -96,7 +96,7 @@ The `setup` function is a new component option. It serves as the entry point for
 
 **Usage with Templates**
 
-If `setup` returns an object, the properties on the object will be merged on to the render context for the component's template:
+If `setup` returns an object, the properties on the object will be merged into the render context of the component's template:
 
 ```html
 <template>

From 355523e91823002b4346ce97a1f3258d1415bb6e Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sat, 23 May 2020 17:14:37 +0300
Subject: [PATCH 13/35] fix: grammar

---
 src/api/composition-api.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index c4457f76b3..ed882f6404 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -121,11 +121,11 @@ If `setup` returns an object, the properties on the object will be merged into t
 </script>
 ```
 
-Note that refs returned from `setup` are automatically unwrapped when accessed in the template so there's no need for `.value` in templates.
+Note that refs returned from `setup` are automatically unwrapped when accessed in the template so you shouldn't use `.value` in templates.
 
 - **Usage with Render Functions**
 
-  `setup` can also return a render function, which can directly make use of reactive state declared in the same scope:
+  `setup` can also return a render function, which can directly make use of the reactive state declared in the same scope:
 
   ```js
   import { h, ref, reactive } from 'vue'

From 8bdb2c34ceff62d32f868ed4f1388ae8834294c9 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sat, 23 May 2020 17:16:20 +0300
Subject: [PATCH 14/35] fix: removed raw values mention

---
 src/api/composition-api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index ed882f6404..000be48bb0 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -1079,7 +1079,7 @@ Identity hazards are in general rare. But to properly utilize these APIs while s
 
 ### `shallowReactive`
 
-Create a reactive proxy that tracks reactivity of its own properties, but does not perform deep reactive conversion of nested objects (exposes raw values).
+Create a reactive proxy that tracks reactivity of its own properties, but does not perform deep reactive conversion of nested objects.
 
 ```js
 const state = shallowReactive({

From a4b6494d3e54c3ca6e4cf00ee455cf12553b0f62 Mon Sep 17 00:00:00 2001
From: Natalia Tepluhina <tarya.se@gmail.com>
Date: Sat, 23 May 2020 17:15:01 +0300
Subject: [PATCH 15/35] Addressed reviewers comments

---
 src/api/composition-api.md | 72 +++++++++++++++++++-------------------
 1 file changed, 36 insertions(+), 36 deletions(-)

diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index 000be48bb0..d8210a7a4d 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -8,7 +8,7 @@ The `setup` function is a new component option. It serves as the entry point for
 
 - **Invocation Timing**
 
-  `setup` is called right after the initial props resolution when a component instance is created. Lifecycle-wise, it is called before the `beforeCreate` hook.
+  `setup` is called right after the initial props resolution when a component instance is created. [Lifecycle-wise](/guide/instance.html#instance-lifecycle-hooks), it is called before the `beforeCreate` hook.
 
 - **Arguments**
 
@@ -25,7 +25,7 @@ The `setup` function is a new component option. It serves as the entry point for
   }
   ```
 
-  Note this `props` object is reactive - i.e. it is updated when new props are passed in, and can be observed and reacted upon using `watchEffect` or `watch`:
+  Note that this `props` object is reactive - i.e. it is updated when new props are passed in, and can be observed and reacted upon using `watchEffect` or `watch`:
 
   ```js
   export default {
@@ -40,7 +40,7 @@ The `setup` function is a new component option. It serves as the entry point for
   }
   ```
 
-  However, **do NOT destructure** the `props` object, as it will lose reactivity:
+  However, **do NOT destructure** the `props` object! If you do so, the unpacked values won't have reactivity:
 
   ```js
   export default {
@@ -55,9 +55,9 @@ The `setup` function is a new component option. It serves as the entry point for
   }
   ```
 
-  The `props` object is immutable during development (will emit warning if user code attempts to mutate it).
+  The `props` object is immutable during development. Vue will emit a warning if there's an attempt to mutate it.
 
-  The second argument provides a context object which exposes a selective list of properties that were previously exposed on `this` in 2.x APIs:
+  The second argument of `setup` provides a context object which exposes a selective list of the properties that were previously exposed on `this` in 2.x APIs:
 
   ```js
   const MyComponent = {
@@ -125,7 +125,7 @@ Note that refs returned from `setup` are automatically unwrapped when accessed i
 
 - **Usage with Render Functions**
 
-  `setup` can also return a render function, which can directly make use of the reactive state declared in the same scope:
+  `setup` can also return a render function which can directly make use of the reactive state declared in the same scope:
 
   ```js
   import { h, ref, reactive } from 'vue'
@@ -183,7 +183,7 @@ Takes an object and returns a reactive proxy of the original.
 const obj = reactive({ count: 0 })
 ```
 
-The reactive conversion is "deep": it affects all nested properties. In the [ES2015 Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) based implementation, the returned proxy is **not** equal to the original object. It is recommended to work exclusively with the reactive proxy and avoid relying on the original object.
+The reactive conversion is "deep"—it affects all nested properties. In the [ES2015 Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) based implementation, the returned proxy is **not** equal to the original object. It is recommended to work exclusively with the reactive proxy and avoid relying on the original object.
 
 - **Typing**
 
@@ -273,7 +273,7 @@ If an object is assigned as a ref's value, the object is made deeply reactive by
   console.log(count.value) // 1
   ```
 
-  Note that if a new ref is assigned to a property linked to an existing ref, it will replace the old ref:
+  If a new ref is assigned to a property linked to an existing ref, it will replace the old ref:
 
   ```js
   const otherCount = ref(2)
@@ -283,7 +283,7 @@ If an object is assigned as a ref's value, the object is made deeply reactive by
   console.log(count.value) // 1
   ```
 
-  Note that ref unwrapping only happens when nested inside a reactive `Object`. There is no unwrapping performed when the ref is accessed from an `Array` or a native collection type like `Map`:
+  Ref unwrapping only happens when nested inside a reactive `Object`. There is no unwrapping performed when the ref is accessed from an `Array` or a native collection type like `Map`:
 
   ```js
   const arr = reactive([ref(0)])
@@ -377,7 +377,7 @@ copy.count++ // warning!
 
 ### `watchEffect`
 
-Run a function immediately while reactively tracking its dependencies, and re-run it whenever the dependencies have changed.
+Runs a function immediately while reactively tracking its dependencies and re-runs it whenever the dependencies are changed.
 
 ```js
 const count = ref(0)
@@ -393,7 +393,7 @@ setTimeout(() => {
 
 #### Stopping the Watcher
 
-When `watchEffect` is called during a component's `setup()` function or lifecycle hooks, the watcher is linked to the component's lifecycle, and will be automatically stopped when the component is unmounted.
+When `watchEffect` is called during a component's `setup()` function or lifecycle hooks, the watcher is linked to the component's lifecycle and will be automatically stopped when the component is unmounted.
 
 In other cases, it returns a stop handle which can be called to explicitly stop the watcher:
 
@@ -408,7 +408,7 @@ stop()
 
 #### Side Effect Invalidation
 
-Sometimes the watched effect function will perform async side effects that need to be cleaned up when it is invalidated (i.e state changed before the effects can be completed). The effect function receives an `onInvalidate` function that can be used to register a invalidation callback. The invalidation callback is called when:
+Sometimes the watched effect function will perform asynchronous side effects that need to be cleaned up when it is invalidated (i.e state changed before the effects can be completed). The effect function receives an `onInvalidate` function that can be used to register an invalidation callback. This invalidation callback is called when:
 
 - the effect is about to re-run
 - the watcher is stopped (i.e. when the component is unmounted if `watchEffect` is used inside `setup()` or lifecycle hooks)
@@ -437,7 +437,7 @@ An async function implicitly returns a Promise, but the cleanup function needs t
 
 #### Effect Flush Timing
 
-Vue's reactivity system buffers invalidated effects and flush them asynchronously to avoid unnecessary duplicate invocation when there are many state mutations happening in the same "tick". Internally, a component's update function is also a watched effect. When a user effect is queued, it is always invoked after all component update effects:
+Vue's reactivity system buffers invalidated effects and flushes them asynchronously to avoid unnecessary duplicate invocation when there are many state mutations happening in the same "tick". Internally, a component's `update` function is also a watched effect. When a user effect is queued, it is always invoked after all component `update` effects:
 
 ```html
 <template>
@@ -476,7 +476,7 @@ onMounted(() => {
 })
 ```
 
-In cases where a watcher effect needs to be re-run synchronously or before component updates, we can pass an additional options object with the `flush` option (default is `'post'`):
+In cases where a watcher effect needs to be re-run synchronously or before component updates, we can pass an additional `options` object with the `flush` option (default is `'post'`):
 
 ```js
 // fire synchronously
@@ -522,7 +522,7 @@ watchEffect(
 )
 ```
 
-`onTrack` and `onTrigger` only works in development mode.
+`onTrack` and `onTrigger` only work in development mode.
 
 - **Typing**
 
@@ -552,7 +552,7 @@ watchEffect(
 
 ### `watch`
 
-The `watch` API is the exact equivalent of the Options API [`this.$watch`](./instance-methods.html#watch) (and the corresponding `watch` option). `watch` requires watching a specific data source, and applies side effects in a separate callback function. It also is lazy by default - i.e. the callback is only called when the watched source has changed.
+The `watch` API is the exact equivalent of the Options API [`this.$watch`](./instance-methods.html#watch) (and the corresponding `watch` option). `watch` requires watching a specific data source and applies side effects in a separate callback function. It also is lazy by default - i.e. the callback is only called when the watched source has changed.
 
 - Compared to `watchEffect`, `watch` allows us to:
 
@@ -583,7 +583,7 @@ The `watch` API is the exact equivalent of the Options API [`this.$watch`](./ins
 
 - **Watching Multiple Sources**
 
-  A watcher can also watch multiple sources at the same time using an Array:
+  A watcher can also watch multiple sources at the same time using an array:
 
   ```js
   watch([fooRef, barRef], ([foo, bar], [prevFoo, prevBar]) => {
@@ -635,7 +635,7 @@ The `watch` API is the exact equivalent of the Options API [`this.$watch`](./ins
 
 ## Lifecycle Hooks
 
-Lifecycle hooks can be registered with directly imported `onXXX` functions:
+Lifecycle hooks can be registered with directly-imported `onX` functions:
 
 ```js
 import { onMounted, onUpdated, onUnmounted } from 'vue'
@@ -702,7 +702,7 @@ const Descendent = {
 
 - **Injection Reactivity**
 
-  To retain reactivity between provided and injected values, a ref can be used:
+  To retain reactivity between provided and injected values, we can use a ref:
 
   ```js
   // in provider
@@ -731,7 +731,7 @@ const Descendent = {
   function inject<T>(key: InjectionKey<T> | string, defaultValue: T): T
   ```
 
-  Vue provides a `InjectionKey` interface which is a generic type that extends `Symbol`. It can be used to sync the type of the injected value between the provider and the consumer:
+  Vue provides an `InjectionKey` interface which is a generic type that extends `Symbol`. It can be used to sync the type of the injected value between the provider and the consumer:
 
   ```ts
   import { InjectionKey, provide, inject } from 'vue'
@@ -778,7 +778,7 @@ When using the Composition API, the concept of _reactive refs_ and [template ref
 </script>
 ```
 
-Here we are exposing `root` on the render context and binding it to the div as its ref via `ref="root"`. In the Virtual DOM patching algorithm, if a VNode's `ref` key corresponds to a ref on the render context, then the VNode's corresponding element or component instance will be assigned to the value of that ref. This is performed during the Virtual DOM mount / patch process, so template refs will only get assigned values after the initial render.
+Here we are exposing `root` on the render context and binding it to the div as its ref via `ref="root"`. In the Virtual DOM patching algorithm, if a VNode's `ref` key corresponds to a ref on the render context, the VNode's corresponding element or component instance will be assigned to the value of that ref. This is performed during the Virtual DOM mount / patch process, so template refs will only get assigned values after the initial render.
 
 Refs used as templates refs behave just like any other refs: they are reactive and can be passed into (or returned from) composition functions.
 
@@ -851,7 +851,7 @@ function useFoo(x: number | Ref<number>) {
 
 ### `toRef`
 
-`toRef` can be used to create a ref for a property on a source reactive object. The ref can then be passed around and retains the reactive connection to its source property.
+Can be used to create a ref for a property on a source reactive object. The ref can then be passed around, retaining the reactive connection to its source property.
 
 ```js
 const state = reactive({
@@ -880,7 +880,7 @@ export default {
 
 ### `toRefs`
 
-Convert a reactive object to a plain object, where each property on the resulting object is a ref pointing to the corresponding property in the original object.
+Converts a reactive object to a plain object where each property of the resulting object is a ref pointing to the corresponding property of the original object.
 
 ```js
 const state = reactive({
@@ -906,7 +906,7 @@ stateAsRefs.foo.value++
 console.log(state.foo) // 3
 ```
 
-`toRefs` is useful when returning a reactive object from a composition function so that the consuming component can destructure / spread the returned object without losing reactivity:
+`toRefs` is useful when returning a reactive object from a composition function so that the consuming component can destructure/spread the returned object without losing reactivity:
 
 ```js
 function useFeatureX() {
@@ -936,15 +936,15 @@ export default {
 
 ### `isRef`
 
-Check if a value is a ref object.
+Checks if a value is a ref object.
 
 ### `isProxy`
 
-Check if an object is a proxy created by `reactive` or `readonly`.
+Checks if an object is a proxy created by `reactive` or `readonly`.
 
 ### `isReactive`
 
-Check if an object is a reactive proxy created by `reactive`.
+Checks if an object is a reactive proxy created by `reactive`.
 
 ```js
 import { reactive, isReactive } from 'vue'
@@ -982,13 +982,13 @@ export default {
 
 ### `isReadonly`
 
-Check if an object is a readonly proxy created by `readonly`.
+Checks if an object is a readonly proxy created by `readonly`.
 
 ## Advanced Reactivity APIs
 
 ### `customRef`
 
-Create a customized ref with explicit control over its dependency tracking and update triggering. It expects a factory function. The factory function receives `track` and `trigger` functions as arguments and should return an object with `get` and `set`.
+Creates a customized ref with explicit control over its dependency tracking and updates triggering. It expects a factory function, which receives `track` and `trigger` functions as arguments and should return an object with `get` and `set`.
 
 - Example using a custom ref to implement debounce with `v-model`:
 
@@ -1041,7 +1041,7 @@ Create a customized ref with explicit control over its dependency tracking and u
 
 ### `markRaw`
 
-Mark an object so that it will never be converted to a proxy. Returns the object itself.
+Marks an object so that it will never be converted to a proxy. Returns the object itself.
 
 ```js
 const foo = markRaw({})
@@ -1053,7 +1053,7 @@ console.log(isReactive(bar.foo)) // false
 ```
 
 ::: warning
-`markRaw` and the shallowXXX APIs below allow you to selectively opt-out of the default deep reactive / readonly conversion and embed raw, non-proxied objects in your state graph. They can be used for various reasons:
+`markRaw` and the shallowXXX APIs below allow you to selectively opt-out of the default deep reactive/readonly conversion and embed raw, non-proxied objects in your state graph. They can be used for various reasons:
 
 - Some values simply should not be made reactive, for example a complex 3rd party class instance, or a Vue component object.
 
@@ -1074,12 +1074,12 @@ const bar = reactive({
 console.log(foo.nested === bar.nested) // false
 ```
 
-Identity hazards are in general rare. But to properly utilize these APIs while safely avoiding identity hazards requires a solid understanding of how the reactivity system works.
+Identity hazards are in general rare. However, to properly utilize these APIs while safely avoiding identity hazards requires a solid understanding of how the reactivity system works.
 :::
 
 ### `shallowReactive`
 
-Create a reactive proxy that tracks reactivity of its own properties, but does not perform deep reactive conversion of nested objects.
+Creates a reactive proxy that tracks reactivity of its own properties but does not perform deep reactive conversion of nested objects (exposes raw values).
 
 ```js
 const state = shallowReactive({
@@ -1098,7 +1098,7 @@ state.nested.bar++ // non-reactive
 
 ### `shallowReadonly`
 
-Create a proxy that makes its own properties readonly, but does not perform deep readonly conversion of nested objects (exposes raw values).
+Creates a proxy that makes its own properties readonly, but does not perform deep readonly conversion of nested objects (exposes raw values).
 
 ```js
 const state = shallowReadonly({
@@ -1117,7 +1117,7 @@ state.nested.bar++ // works
 
 ### `shallowRef`
 
-Create a ref that tracks its own `.value` mutation but doesn't make its value reactive.
+Creates a ref that tracks its own `.value` mutation but doesn't make its value reactive.
 
 ```js
 const foo = shallowRef({})
@@ -1129,7 +1129,7 @@ isReactive(foo.value) // false
 
 ### `toRaw`
 
-Return the raw, original object of a `reactive` or `readonly` proxy. This is an escape hatch that can be used to temporarily read without incurring proxy access / tracking overhead or write without triggering changes. It is **not** recommended to hold a persistent reference to the original object. Use with caution.
+Returns the raw, original object of a `reactive` or `readonly` proxy. This is an escape hatch that can be used to temporarily read without incurring proxy access/tracking overhead or write without triggering changes. It is **not** recommended to hold a persistent reference to the original object. Use with caution.
 
 ```js
 const foo = {}

From f2b2f11839a212fafb87732f2e31268c2e53b6d4 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sat, 23 May 2020 17:48:38 +0300
Subject: [PATCH 16/35] feat: moved reactivity APIs

---
 src/.vuepress/config.js         |   5 +
 src/api/composition-api.md      | 460 --------------------------------
 src/api/reactivity-api.md       | 456 +++++++++++++++++++++++++++++++
 src/api/reactivity-utilities.md |   0
 4 files changed, 461 insertions(+), 460 deletions(-)
 create mode 100644 src/api/reactivity-api.md
 create mode 100644 src/api/reactivity-utilities.md

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index 4c256932dd..6b09813dc1 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -85,6 +85,11 @@ const sidebar = {
     '/api/instance-methods',
     '/api/directives',
     '/api/special-attributes',
+    {
+      title: 'Reactivity-related API',
+      collapsable: false,
+      children: ['/api/reactivity-api', '/api/reactivity-utilities']
+    },
     '/api/composition-api'
   ]
 }
diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index d8210a7a4d..2fc0b9b13e 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -173,466 +173,6 @@ Note that refs returned from `setup` are automatically unwrapped when accessed i
   To get type inference for the arguments passed to `setup()`, the use of [`defineComponent`](TODO) is needed.
   :::
 
-## Reactivity APIs
-
-### `reactive`
-
-Takes an object and returns a reactive proxy of the original.
-
-```js
-const obj = reactive({ count: 0 })
-```
-
-The reactive conversion is "deep"—it affects all nested properties. In the [ES2015 Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) based implementation, the returned proxy is **not** equal to the original object. It is recommended to work exclusively with the reactive proxy and avoid relying on the original object.
-
-- **Typing**
-
-  ```ts
-  function reactive<T extends object>(raw: T): T
-  ```
-
-### `ref`
-
-Takes an inner value and returns a reactive and mutable ref object. The ref object has a single property `.value` that points to the inner value.
-
-```js
-const count = ref(0)
-console.log(count.value) // 0
-
-count.value++
-console.log(count.value) // 1
-```
-
-If an object is assigned as a ref's value, the object is made deeply reactive by the `reactive` method.
-
-- **Access in Templates**
-
-  When a ref is returned as a property on the render context (the object returned from `setup()`) and accessed in the template, it automatically unwraps to the inner value. There is no need to append `.value` in the template:
-
-  ```html
-  <template>
-    <div>
-      <span>{{ count }}</span>
-      <button @click="count ++">Increment count</button>
-    </div>
-  </template>
-
-  <script>
-    import { ref } from 'vue'
-    export default {
-      setup() {
-        const count = ref(0)
-        return {
-          count
-        }
-      }
-    }
-  </script>
-  ```
-
-  However, if we decide to change the inline event handler on button click to the component method declared in `setup`, we need to remember that `ref` is not unwrapped there:
-
-  ```html
-  <template>
-    <div>
-      <span>{{ count }}</span>
-      <button @click="increment">Increment count</button>
-    </div>
-  </template>
-
-  <script>
-    import { ref } from 'vue'
-    export default {
-      setup() {
-        const count = ref(0)
-        function increment() {
-          count.value++ // ref is not unwrapped outside the template, so we need to use .value here
-        }
-        return {
-          count,
-          increment
-        }
-      }
-    }
-  </script>
-  ```
-
-* **Access in Reactive Objects**
-
-  When a ref is accessed or mutated as a property of a reactive object, it automatically unwraps to the inner value so it behaves like a normal property:
-
-  ```js
-  const count = ref(0)
-  const state = reactive({
-    count
-  })
-
-  console.log(state.count) // 0
-
-  state.count = 1
-  console.log(count.value) // 1
-  ```
-
-  If a new ref is assigned to a property linked to an existing ref, it will replace the old ref:
-
-  ```js
-  const otherCount = ref(2)
-
-  state.count = otherCount
-  console.log(state.count) // 2
-  console.log(count.value) // 1
-  ```
-
-  Ref unwrapping only happens when nested inside a reactive `Object`. There is no unwrapping performed when the ref is accessed from an `Array` or a native collection type like `Map`:
-
-  ```js
-  const arr = reactive([ref(0)])
-  // need .value here
-  console.log(arr[0].value)
-
-  const map = reactive(new Map([['foo', ref(0)]]))
-  // need .value here
-  console.log(map.get('foo').value)
-  ```
-
-* **Typing**
-
-  ```ts
-  interface Ref<T> {
-    value: T
-  }
-
-  function ref<T>(value: T): Ref<T>
-  ```
-
-  Sometimes we may need to specify complex types for a ref's inner value. We can do that succinctly by passing a generics argument when calling `ref` to override the default inference:
-
-  ```ts
-  const foo = ref<string | number>('foo') // foo's type: Ref<string | number>
-
-  foo.value = 123 // ok!
-  ```
-
-### `computed`
-
-Takes a getter function and returns an immutable reactive ref object for the returned value from the getter.
-
-```js
-const count = ref(1)
-const plusOne = computed(() => count.value + 1)
-
-console.log(plusOne.value) // 2
-
-plusOne.value++ // error
-```
-
-Alternatively, it can take an object with `get` and `set` functions to create a writable ref object.
-
-```js
-const count = ref(1)
-const plusOne = computed({
-  get: () => count.value + 1,
-  set: val => {
-    count.value = val - 1
-  }
-})
-
-plusOne.value = 1
-console.log(count.value) // 0
-```
-
-- **Typing**
-
-  ```ts
-  // read-only
-  function computed<T>(getter: () => T): Readonly<Ref<Readonly<T>>>
-
-  // writable
-  function computed<T>(options: {
-    get: () => T
-    set: (value: T) => void
-  }): Ref<T>
-  ```
-
-### `readonly`
-
-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.
-
-```js
-const original = reactive({ count: 0 })
-
-const copy = readonly(original)
-
-watchEffect(() => {
-  // 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!
-```
-
-### `watchEffect`
-
-Runs a function immediately while reactively tracking its dependencies and re-runs it whenever the dependencies are changed.
-
-```js
-const count = ref(0)
-
-watchEffect(() => console.log(count.value))
-// -> logs 0
-
-setTimeout(() => {
-  count.value++
-  // -> logs 1
-}, 100)
-```
-
-#### Stopping the Watcher
-
-When `watchEffect` is called during a component's `setup()` function or lifecycle hooks, the watcher is linked to the component's lifecycle and will be automatically stopped when the component is unmounted.
-
-In other cases, it returns a stop handle which can be called to explicitly stop the watcher:
-
-```js
-const stop = watchEffect(() => {
-  /* ... */
-})
-
-// later
-stop()
-```
-
-#### Side Effect Invalidation
-
-Sometimes the watched effect function will perform asynchronous side effects that need to be cleaned up when it is invalidated (i.e state changed before the effects can be completed). The effect function receives an `onInvalidate` function that can be used to register an invalidation callback. This invalidation callback is called when:
-
-- the effect is about to re-run
-- the watcher is stopped (i.e. when the component is unmounted if `watchEffect` is used inside `setup()` or lifecycle hooks)
-
-```js
-watchEffect(onInvalidate => {
-  const token = performAsyncOperation(id.value)
-  onInvalidate(() => {
-    // id has changed or watcher is stopped.
-    // invalidate previously pending async operation
-    token.cancel()
-  })
-})
-```
-
-We are registering the invalidation callback via a passed-in function instead of returning it from the callback because the return value is important for async error handling. It is very common for the effect function to be an async function when performing data fetching:
-
-```js
-const data = ref(null)
-watchEffect(async () => {
-  data.value = await fetchData(props.id)
-})
-```
-
-An async function implicitly returns a Promise, but the cleanup function needs to be registered immediately before the Promise resolves. In addition, Vue relies on the returned Promise to automatically handle potential errors in the Promise chain.
-
-#### Effect Flush Timing
-
-Vue's reactivity system buffers invalidated effects and flushes them asynchronously to avoid unnecessary duplicate invocation when there are many state mutations happening in the same "tick". Internally, a component's `update` function is also a watched effect. When a user effect is queued, it is always invoked after all component `update` effects:
-
-```html
-<template>
-  <div>{{ count }}</div>
-</template>
-
-<script>
-  export default {
-    setup() {
-      const count = ref(0)
-
-      watchEffect(() => {
-        console.log(count.value)
-      })
-
-      return {
-        count
-      }
-    }
-  }
-</script>
-```
-
-In this example:
-
-- The count will be logged synchronously on initial run.
-- When `count` is mutated, the callback will be called **after** the component has updated.
-
-Note the first run is executed before the component is mounted. So if you wish to access the DOM (or template refs) in a watched effect, do it in the mounted hook:
-
-```js
-onMounted(() => {
-  watchEffect(() => {
-    // access the DOM or template refs
-  })
-})
-```
-
-In cases where a watcher effect needs to be re-run synchronously or before component updates, we can pass an additional `options` object with the `flush` option (default is `'post'`):
-
-```js
-// fire synchronously
-watchEffect(
-  () => {
-    /* ... */
-  },
-  {
-    flush: 'sync'
-  }
-)
-
-// fire before component updates
-watchEffect(
-  () => {
-    /* ... */
-  },
-  {
-    flush: 'pre'
-  }
-)
-```
-
-#### Watcher Debugging
-
-The `onTrack` and `onTrigger` options can be used to debug a watcher's behavior.
-
-- `onTrack` will be called when a reactive property or ref is tracked as a dependency
-- `onTrigger` will be called when the watcher callback is triggered by the mutation of a dependency
-
-Both callbacks will receive a debugger event which contains information on the dependency in question. It is recommended to place a `debugger` statement in these callbacks to interactively inspect the dependency:
-
-```js
-watchEffect(
-  () => {
-    /* side effect */
-  },
-  {
-    onTrigger(e) {
-      debugger
-    }
-  }
-)
-```
-
-`onTrack` and `onTrigger` only work in development mode.
-
-- **Typing**
-
-  ```ts
-  function watchEffect(
-    effect: (onInvalidate: InvalidateCbRegistrator) => void,
-    options?: WatchEffectOptions
-  ): StopHandle
-
-  interface WatchEffectOptions {
-    flush?: 'pre' | 'post' | 'sync'
-    onTrack?: (event: DebuggerEvent) => void
-    onTrigger?: (event: DebuggerEvent) => void
-  }
-
-  interface DebuggerEvent {
-    effect: ReactiveEffect
-    target: any
-    type: OperationTypes
-    key: string | symbol | undefined
-  }
-
-  type InvalidateCbRegistrator = (invalidate: () => void) => void
-
-  type StopHandle = () => void
-  ```
-
-### `watch`
-
-The `watch` API is the exact equivalent of the Options API [`this.$watch`](./instance-methods.html#watch) (and the corresponding `watch` option). `watch` requires watching a specific data source and applies side effects in a separate callback function. It also is lazy by default - i.e. the callback is only called when the watched source has changed.
-
-- Compared to `watchEffect`, `watch` allows us to:
-
-  - Perform the side effect lazily;
-  - Be more specific about what state should trigger the watcher to re-run;
-  - Access both the previous and current value of the watched state.
-
-- **Watching a Single Source**
-
-  A watcher data source can either be a getter function that returns a value, or directly a ref:
-
-  ```js
-  // watching a getter
-  const state = reactive({ count: 0 })
-  watch(
-    () => state.count,
-    (count, prevCount) => {
-      /* ... */
-    }
-  )
-
-  // directly watching a ref
-  const count = ref(0)
-  watch(count, (count, prevCount) => {
-    /* ... */
-  })
-  ```
-
-- **Watching Multiple Sources**
-
-  A watcher can also watch multiple sources at the same time using an array:
-
-  ```js
-  watch([fooRef, barRef], ([foo, bar], [prevFoo, prevBar]) => {
-    /* ... */
-  })
-  ```
-
-* **Shared Behavior with `watchEffect`**
-
-  `watch` shares behavior with `watchEffect` in terms of [manual stoppage](#stopping-the-watcher), [side effect invalidation](#side-effect-invalidation) (with `onInvalidate` passed to the callback as the 3rd argument instead), [flush timing](#effect-flush-timing) and [debugging](#watcher-debugging).
-
-* **Typing**
-
-  ```ts
-  // wacthing single source
-  function watch<T>(
-    source: WatcherSource<T>,
-    callback: (
-      value: T,
-      oldValue: T,
-      onInvalidate: InvalidateCbRegistrator
-    ) => void,
-    options?: WatchOptions
-  ): StopHandle
-
-  // watching multiple sources
-  function watch<T extends WatcherSource<unknown>[]>(
-    sources: T
-    callback: (
-      values: MapSources<T>,
-      oldValues: MapSources<T>,
-      onInvalidate: InvalidateCbRegistrator
-    ) => void,
-    options? : WatchOptions
-  ): StopHandle
-
-  type WatcherSource<T> = Ref<T> | (() => T)
-
-  type MapSources<T> = {
-    [K in keyof T]: T[K] extends WatcherSource<infer V> ? V : never
-  }
-
-  // see `watchEffect` typing for shared options
-  interface WatchOptions extends WatchEffectOptions {
-    immediate?: boolean // default: false
-    deep?: boolean
-  }
-  ```
-
 ## Lifecycle Hooks
 
 Lifecycle hooks can be registered with directly-imported `onX` functions:
diff --git a/src/api/reactivity-api.md b/src/api/reactivity-api.md
new file mode 100644
index 0000000000..1e0dab27c1
--- /dev/null
+++ b/src/api/reactivity-api.md
@@ -0,0 +1,456 @@
+# Reactivity APIs
+
+## `reactive`
+
+Takes an object and returns a reactive proxy of the original.
+
+```js
+const obj = reactive({ count: 0 })
+```
+
+The reactive conversion is "deep"—it affects all nested properties. In the [ES2015 Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) based implementation, the returned proxy is **not** equal to the original object. It is recommended to work exclusively with the reactive proxy and avoid relying on the original object.
+
+### Typing
+
+```ts
+function reactive<T extends object>(raw: T): T
+```
+
+## `ref`
+
+Takes an inner value and returns a reactive and mutable ref object. The ref object has a single property `.value` that points to the inner value.
+
+```js
+const count = ref(0)
+console.log(count.value) // 0
+
+count.value++
+console.log(count.value) // 1
+```
+
+If an object is assigned as a ref's value, the object is made deeply reactive by the `reactive` method.
+
+### Access in Templates
+
+When a ref is returned as a property on the render context (the object returned from `setup()`) and accessed in the template, it automatically unwraps to the inner value. There is no need to append `.value` in the template:
+
+```html
+<template>
+  <div>
+    <span>{{ count }}</span>
+    <button @click="count ++">Increment count</button>
+  </div>
+</template>
+
+<script>
+  import { ref } from 'vue'
+  export default {
+    setup() {
+      const count = ref(0)
+      return {
+        count
+      }
+    }
+  }
+</script>
+```
+
+However, if we decide to change the inline event handler on button click to the component method declared in `setup`, we need to remember that `ref` is not unwrapped there:
+
+```html
+<template>
+  <div>
+    <span>{{ count }}</span>
+    <button @click="increment">Increment count</button>
+  </div>
+</template>
+
+<script>
+  import { ref } from 'vue'
+  export default {
+    setup() {
+      const count = ref(0)
+      function increment() {
+        count.value++ // ref is not unwrapped outside the template
+      }
+      return {
+        count,
+        increment
+      }
+    }
+  }
+</script>
+```
+
+### Access in Reactive Objects
+
+When a ref is accessed or mutated as a property of a reactive object, it automatically unwraps to the inner value so it behaves like a normal property:
+
+```js
+const count = ref(0)
+const state = reactive({
+  count
+})
+
+console.log(state.count) // 0
+
+state.count = 1
+console.log(count.value) // 1
+```
+
+If a new ref is assigned to a property linked to an existing ref, it will replace the old ref:
+
+```js
+const otherCount = ref(2)
+
+state.count = otherCount
+console.log(state.count) // 2
+console.log(count.value) // 1
+```
+
+Ref unwrapping only happens when nested inside a reactive `Object`. There is no unwrapping performed when the ref is accessed from an `Array` or a native collection type like `Map`:
+
+```js
+const arr = reactive([ref(0)])
+// need .value here
+console.log(arr[0].value)
+
+const map = reactive(new Map([['foo', ref(0)]]))
+// need .value here
+console.log(map.get('foo').value)
+```
+
+### Typing
+
+```ts
+interface Ref<T> {
+  value: T
+}
+
+function ref<T>(value: T): Ref<T>
+```
+
+Sometimes we may need to specify complex types for a ref's inner value. We can do that succinctly by passing a generics argument when calling `ref` to override the default inference:
+
+```ts
+const foo = ref<string | number>('foo') // foo's type: Ref<string | number>
+
+foo.value = 123 // ok!
+```
+
+## `computed`
+
+Takes a getter function and returns an immutable reactive ref object for the returned value from the getter.
+
+```js
+const count = ref(1)
+const plusOne = computed(() => count.value + 1)
+
+console.log(plusOne.value) // 2
+
+plusOne.value++ // error
+```
+
+Alternatively, it can take an object with `get` and `set` functions to create a writable ref object.
+
+```js
+const count = ref(1)
+const plusOne = computed({
+  get: () => count.value + 1,
+  set: val => {
+    count.value = val - 1
+  }
+})
+
+plusOne.value = 1
+console.log(count.value) // 0
+```
+
+### Typing
+
+```ts
+// read-only
+function computed<T>(getter: () => T): Readonly<Ref<Readonly<T>>>
+
+// writable
+function computed<T>(options: { get: () => T; set: (value: T) => void }): Ref<T>
+```
+
+## `readonly`
+
+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.
+
+```js
+const original = reactive({ count: 0 })
+
+const copy = readonly(original)
+
+watchEffect(() => {
+  // 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!
+```
+
+## `watchEffect`
+
+Runs a function immediately while reactively tracking its dependencies and re-runs it whenever the dependencies are changed.
+
+```js
+const count = ref(0)
+
+watchEffect(() => console.log(count.value))
+// -> logs 0
+
+setTimeout(() => {
+  count.value++
+  // -> logs 1
+}, 100)
+```
+
+### Stopping the Watcher
+
+When `watchEffect` is called during a component's `setup()` function or lifecycle hooks, the watcher is linked to the component's lifecycle and will be automatically stopped when the component is unmounted.
+
+In other cases, it returns a stop handle which can be called to explicitly stop the watcher:
+
+```js
+const stop = watchEffect(() => {
+  /* ... */
+})
+
+// later
+stop()
+```
+
+### Side Effect Invalidation
+
+Sometimes the watched effect function will perform asynchronous side effects that need to be cleaned up when it is invalidated (i.e state changed before the effects can be completed). The effect function receives an `onInvalidate` function that can be used to register an invalidation callback. This invalidation callback is called when:
+
+- the effect is about to re-run
+- the watcher is stopped (i.e. when the component is unmounted if `watchEffect` is used inside `setup()` or lifecycle hooks)
+
+```js
+watchEffect(onInvalidate => {
+  const token = performAsyncOperation(id.value)
+  onInvalidate(() => {
+    // id has changed or watcher is stopped.
+    // invalidate previously pending async operation
+    token.cancel()
+  })
+})
+```
+
+We are registering the invalidation callback via a passed-in function instead of returning it from the callback because the return value is important for async error handling. It is very common for the effect function to be an async function when performing data fetching:
+
+```js
+const data = ref(null)
+watchEffect(async () => {
+  data.value = await fetchData(props.id)
+})
+```
+
+An async function implicitly returns a Promise, but the cleanup function needs to be registered immediately before the Promise resolves. In addition, Vue relies on the returned Promise to automatically handle potential errors in the Promise chain.
+
+### Effect Flush Timing
+
+Vue's reactivity system buffers invalidated effects and flushes them asynchronously to avoid unnecessary duplicate invocation when there are many state mutations happening in the same "tick". Internally, a component's `update` function is also a watched effect. When a user effect is queued, it is always invoked after all component `update` effects:
+
+```html
+<template>
+  <div>{{ count }}</div>
+</template>
+
+<script>
+  export default {
+    setup() {
+      const count = ref(0)
+
+      watchEffect(() => {
+        console.log(count.value)
+      })
+
+      return {
+        count
+      }
+    }
+  }
+</script>
+```
+
+In this example:
+
+- The count will be logged synchronously on initial run.
+- When `count` is mutated, the callback will be called **after** the component has updated.
+
+Note the first run is executed before the component is mounted. So if you wish to access the DOM (or template refs) in a watched effect, do it in the mounted hook:
+
+```js
+onMounted(() => {
+  watchEffect(() => {
+    // access the DOM or template refs
+  })
+})
+```
+
+In cases where a watcher effect needs to be re-run synchronously or before component updates, we can pass an additional `options` object with the `flush` option (default is `'post'`):
+
+```js
+// fire synchronously
+watchEffect(
+  () => {
+    /* ... */
+  },
+  {
+    flush: 'sync'
+  }
+)
+
+// fire before component updates
+watchEffect(
+  () => {
+    /* ... */
+  },
+  {
+    flush: 'pre'
+  }
+)
+```
+
+### Watcher Debugging
+
+The `onTrack` and `onTrigger` options can be used to debug a watcher's behavior.
+
+- `onTrack` will be called when a reactive property or ref is tracked as a dependency
+- `onTrigger` will be called when the watcher callback is triggered by the mutation of a dependency
+
+Both callbacks will receive a debugger event which contains information on the dependency in question. It is recommended to place a `debugger` statement in these callbacks to interactively inspect the dependency:
+
+```js
+watchEffect(
+  () => {
+    /* side effect */
+  },
+  {
+    onTrigger(e) {
+      debugger
+    }
+  }
+)
+```
+
+`onTrack` and `onTrigger` only work in development mode.
+
+### Typing
+
+```ts
+function watchEffect(
+  effect: (onInvalidate: InvalidateCbRegistrator) => void,
+  options?: WatchEffectOptions
+): StopHandle
+
+interface WatchEffectOptions {
+  flush?: 'pre' | 'post' | 'sync'
+  onTrack?: (event: DebuggerEvent) => void
+  onTrigger?: (event: DebuggerEvent) => void
+}
+
+interface DebuggerEvent {
+  effect: ReactiveEffect
+  target: any
+  type: OperationTypes
+  key: string | symbol | undefined
+}
+
+type InvalidateCbRegistrator = (invalidate: () => void) => void
+
+type StopHandle = () => void
+```
+
+## `watch`
+
+The `watch` API is the exact equivalent of the Options API [`this.$watch`](./instance-methods.html#watch) (and the corresponding `watch` option). `watch` requires watching a specific data source and applies side effects in a separate callback function. It also is lazy by default - i.e. the callback is only called when the watched source has changed.
+
+- Compared to `watchEffect`, `watch` allows us to:
+
+  - Perform the side effect lazily;
+  - Be more specific about what state should trigger the watcher to re-run;
+  - Access both the previous and current value of the watched state.
+
+### Watching a Single Source
+
+A watcher data source can either be a getter function that returns a value, or directly a ref:
+
+```js
+// watching a getter
+const state = reactive({ count: 0 })
+watch(
+  () => state.count,
+  (count, prevCount) => {
+    /* ... */
+  }
+)
+
+// directly watching a ref
+const count = ref(0)
+watch(count, (count, prevCount) => {
+  /* ... */
+})
+```
+
+### Watching Multiple Sources
+
+A watcher can also watch multiple sources at the same time using an array:
+
+```js
+watch([fooRef, barRef], ([foo, bar], [prevFoo, prevBar]) => {
+  /* ... */
+})
+```
+
+### Shared Behavior with `watchEffect`
+
+`watch` shares behavior with `watchEffect` in terms of [manual stoppage](#stopping-the-watcher), [side effect invalidation](#side-effect-invalidation) (with `onInvalidate` passed to the callback as the 3rd argument instead), [flush timing](#effect-flush-timing) and [debugging](#watcher-debugging).
+
+### Typing
+
+```ts
+// wacthing single source
+function watch<T>(
+  source: WatcherSource<T>,
+  callback: (
+    value: T,
+    oldValue: T,
+    onInvalidate: InvalidateCbRegistrator
+  ) => void,
+  options?: WatchOptions
+): StopHandle
+
+// watching multiple sources
+function watch<T extends WatcherSource<unknown>[]>(
+  sources: T
+  callback: (
+    values: MapSources<T>,
+    oldValues: MapSources<T>,
+    onInvalidate: InvalidateCbRegistrator
+  ) => void,
+  options? : WatchOptions
+): StopHandle
+
+type WatcherSource<T> = Ref<T> | (() => T)
+
+type MapSources<T> = {
+  [K in keyof T]: T[K] extends WatcherSource<infer V> ? V : never
+}
+
+// see `watchEffect` typing for shared options
+interface WatchOptions extends WatchEffectOptions {
+  immediate?: boolean // default: false
+  deep?: boolean
+}
+```
diff --git a/src/api/reactivity-utilities.md b/src/api/reactivity-utilities.md
new file mode 100644
index 0000000000..e69de29bb2

From a2756dc4b2fb014722eb9a0e3f07d80a6a74752b Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sat, 23 May 2020 17:53:35 +0300
Subject: [PATCH 17/35] feat: moved reactivity utilities

---
 src/api/composition-api.md      | 481 +++++++++++---------------------
 src/api/reactivity-utilities.md | 146 ++++++++++
 2 files changed, 313 insertions(+), 314 deletions(-)

diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index 2fc0b9b13e..4ddbf19eca 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -6,95 +6,95 @@
 
 The `setup` function is a new component option. It serves as the entry point for using the Composition API inside components.
 
-- **Invocation Timing**
+### Invocation Timing
 
-  `setup` is called right after the initial props resolution when a component instance is created. [Lifecycle-wise](/guide/instance.html#instance-lifecycle-hooks), it is called before the `beforeCreate` hook.
+`setup` is called right after the initial props resolution when a component instance is created. [Lifecycle-wise](../guide/instance.html#instance-lifecycle-hooks), it is called before the `beforeCreate` hook.
 
-- **Arguments**
+### Arguments
 
-  The function receives the resolved props as its first argument:
+The function receives the resolved props as its first argument:
 
-  ```js
-  export default {
-    props: {
-      name: String
-    },
-    setup(props) {
-      console.log(props.name)
-    }
+```js
+export default {
+  props: {
+    name: String
+  },
+  setup(props) {
+    console.log(props.name)
   }
-  ```
+}
+```
 
-  Note that this `props` object is reactive - i.e. it is updated when new props are passed in, and can be observed and reacted upon using `watchEffect` or `watch`:
+Note that this `props` object is reactive - i.e. it is updated when new props are passed in, and can be observed and reacted upon using `watchEffect` or `watch`:
 
-  ```js
-  export default {
-    props: {
-      name: String
-    },
-    setup(props) {
-      watchEffect(() => {
-        console.log(`name is: ` + props.name)
-      })
-    }
+```js
+export default {
+  props: {
+    name: String
+  },
+  setup(props) {
+    watchEffect(() => {
+      console.log(`name is: ` + props.name)
+    })
   }
-  ```
+}
+```
 
-  However, **do NOT destructure** the `props` object! If you do so, the unpacked values won't have reactivity:
+However, **do NOT destructure** the `props` object! If you do so, the unpacked values won't have reactivity:
 
-  ```js
-  export default {
-    props: {
-      name: String
-    },
-    setup({ name }) {
-      watchEffect(() => {
-        console.log(`name is: ` + name) // Will not be reactive!
-      })
-    }
+```js
+export default {
+  props: {
+    name: String
+  },
+  setup({ name }) {
+    watchEffect(() => {
+      console.log(`name is: ` + name) // Will not be reactive!
+    })
   }
-  ```
+}
+```
 
-  The `props` object is immutable during development. Vue will emit a warning if there's an attempt to mutate it.
+The `props` object is immutable during development. Vue will emit a warning if there's an attempt to mutate it.
 
-  The second argument of `setup` provides a context object which exposes a selective list of the properties that were previously exposed on `this` in 2.x APIs:
+The second argument of `setup` provides a context object which exposes a selective list of the properties that were previously exposed on `this` in 2.x APIs:
 
-  ```js
-  const MyComponent = {
-    setup(props, context) {
-      context.attrs
-      context.slots
-      context.emit
-    }
+```js
+const MyComponent = {
+  setup(props, context) {
+    context.attrs
+    context.slots
+    context.emit
   }
-  ```
+}
+```
 
-  Unlike `props`, `context` argument can be destructured safely so `attrs` and `slots` would always expose the latest values even after updates:
+Unlike `props`, `context` argument can be destructured safely so `attrs` and `slots` would always expose the latest values even after updates:
 
-  ```js
-  const MyComponent = {
-    setup(props, { attrs }) {
-      // a function that may get called at a later stage
-      function onClick() {
-        console.log(attrs.foo) // guaranteed to be the latest reference
-      }
+```js
+const MyComponent = {
+  setup(props, { attrs }) {
+    // a function that may get called at a later stage
+    function onClick() {
+      console.log(attrs.foo) // guaranteed to be the latest reference
     }
   }
-  ```
+}
+```
 
-  However, `attrs` and `slots` themselves cannot be destructured without losing reactivity:
+However, `attrs` and `slots` themselves cannot be destructured without losing reactivity:
 
-  ```js
-  const MyComponent = {
-    setup(props, { attrs: { foo } }) {
-      function onClick() {
-        console.log(foo) // won't be the latest reference as we lost `attrs` reactivity with destructuring
-      }
+```js
+const MyComponent = {
+  setup(props, { attrs: { foo } }) {
+    function onClick() {
+      console.log(foo) // won't be the latest reference as we lost `attrs` reactivity with destructuring
     }
   }
-  ```
+}
+```
 
-**Usage with Templates**
+### Usage with Templates
 
 If `setup` returns an object, the properties on the object will be merged into the render context of the component's template:
 
@@ -123,55 +123,55 @@ If `setup` returns an object, the properties on the object will be merged into t
 
 Note that refs returned from `setup` are automatically unwrapped when accessed in the template so you shouldn't use `.value` in templates.
 
-- **Usage with Render Functions**
+### Usage with Render Functions
 
-  `setup` can also return a render function which can directly make use of the reactive state declared in the same scope:
+`setup` can also return a render function which can directly make use of the reactive state declared in the same scope:
 
-  ```js
-  import { h, ref, reactive } from 'vue'
+```js
+import { h, ref, reactive } from 'vue'
 
-  export default {
-    setup() {
-      const count = ref(0)
-      const object = reactive({ foo: 'bar' })
+export default {
+  setup() {
+    const count = ref(0)
+    const object = reactive({ foo: 'bar' })
 
-      return () => h('div', [count.value, object.foo])
-    }
+    return () => h('div', [count.value, object.foo])
   }
-  ```
+}
+```
 
-- **Usage of `this`**
+### Usage of `this`
 
-  **Inside `setup()`, `this` won't be a reference to Vue instance** Since `setup()` is called before other component options are resolved, `this` inside `setup()` will behave quite differently from `this` in other options. This might cause confusions when using `setup()` along other Options API. Another reason for avoiding `this` in `setup()` is a very common pitfall for beginners:
+**Inside `setup()`, `this` won't be a reference to Vue instance** Since `setup()` is called before other component options are resolved, `this` inside `setup()` will behave quite differently from `this` in other options. This might cause confusions when using `setup()` along other Options API. Another reason for avoiding `this` in `setup()` is a very common pitfall for beginners:
 
-  ```js
-  setup() {
-    const that = this
-    function onClick() {
-        console.log(this !== that) // not the `this` you'd expect!
-    }
+```js
+setup() {
+  const that = this
+  function onClick() {
+      console.log(this !== that) // not the `this` you'd expect!
   }
-  ```
+}
+```
 
-- **Typing**
+### Typing
 
-  ```ts
-  interface Data {
-    [key: string]: unknown
-  }
+```ts
+interface Data {
+  [key: string]: unknown
+}
 
-  interface SetupContext {
-    attrs: Data
-    slots: Slots
-    emit: (event: string, ...args: unknown[]) => void
-  }
+interface SetupContext {
+  attrs: Data
+  slots: Slots
+  emit: (event: string, ...args: unknown[]) => void
+}
 
-  function setup(props: Data, context: SetupContext): Data
-  ```
+function setup(props: Data, context: SetupContext): Data
+```
 
-  ::: tip
-  To get type inference for the arguments passed to `setup()`, the use of [`defineComponent`](TODO) is needed.
-  :::
+::: tip
+To get type inference for the arguments passed to `setup()`, the use of [`defineComponent`](TODO) is needed.
+:::
 
 ## Lifecycle Hooks
 
@@ -240,54 +240,54 @@ const Descendent = {
 
 `inject` accepts an optional default value as the 2nd argument. If a default value is not provided and the property is not found on the provide context, `inject` returns `undefined`.
 
-- **Injection Reactivity**
+### Injection Reactivity
 
-  To retain reactivity between provided and injected values, we can use a ref:
+To retain reactivity between provided and injected values, we can use a ref:
 
-  ```js
-  // in provider
-  const themeRef = ref('dark')
-  provide(ThemeSymbol, themeRef)
-
-  // in consumer
-  const theme = inject(ThemeSymbol, ref('light'))
-  watchEffect(() => {
-    console.log(`theme set to: ${theme.value}`)
-  })
-  ```
+```js
+// in provider
+const themeRef = ref('dark')
+provide(ThemeSymbol, themeRef)
+
+// in consumer
+const theme = inject(ThemeSymbol, ref('light'))
+watchEffect(() => {
+  console.log(`theme set to: ${theme.value}`)
+})
+```
 
-  If a reactive object is injected, it can also be reactively observed.
+If a reactive object is injected, it can also be reactively observed.
 
-- **Typing**
+### Typing
 
-  ```ts
-  interface InjectionKey<T> extends Symbol {}
+```ts
+interface InjectionKey<T> extends Symbol {}
 
-  function provide<T>(key: InjectionKey<T> | string, value: T): void
+function provide<T>(key: InjectionKey<T> | string, value: T): void
 
-  // without default value
-  function inject<T>(key: InjectionKey<T> | string): T | undefined
-  // with default value
-  function inject<T>(key: InjectionKey<T> | string, defaultValue: T): T
-  ```
+// without default value
+function inject<T>(key: InjectionKey<T> | string): T | undefined
+// with default value
+function inject<T>(key: InjectionKey<T> | string, defaultValue: T): T
+```
 
-  Vue provides an `InjectionKey` interface which is a generic type that extends `Symbol`. It can be used to sync the type of the injected value between the provider and the consumer:
+Vue provides an `InjectionKey` interface which is a generic type that extends `Symbol`. It can be used to sync the type of the injected value between the provider and the consumer:
 
-  ```ts
-  import { InjectionKey, provide, inject } from 'vue'
+```ts
+import { InjectionKey, provide, inject } from 'vue'
 
-  const key: InjectionKey<string> = Symbol()
+const key: InjectionKey<string> = Symbol()
 
-  provide(key, 'foo') // providing non-string value will result in error
+provide(key, 'foo') // providing non-string value will result in error
 
-  const foo = inject(key) // type of foo: string | undefined
-  ```
+const foo = inject(key) // type of foo: string | undefined
+```
 
-  If using string keys or non-typed symbols, the type of the injected value will need to be explicitly declared:
+If using string keys or non-typed symbols, the type of the injected value will need to be explicitly declared:
 
-  ```ts
-  const foo = inject<string>('foo') // string | undefined
-  ```
+```ts
+const foo = inject<string>('foo') // string | undefined
+```
 
 ## Template Refs
 
@@ -326,204 +326,57 @@ Refs used as templates refs behave just like any other refs: they are reactive a
 Please note that `ref` will behave differently when used with `v-bind` directive. `ref="root"` would be equivalent to `:ref="el => root = el"`
 :::
 
-- **Usage with JSX**
-
-  ```js
-  export default {
-    setup() {
-      const root = ref(null)
-
-      return () =>
-        h('div', {
-          ref: root
-        })
-
-      // with JSX
-      return () => <div ref={root} />
-    }
-  }
-  ```
-
-- **Usage inside `v-for`**
-
-  Composition API template refs do not have special handling when used inside `v-for`. Instead, use function refs to perform custom handling:
-
-  ```html
-  <template>
-    <div v-for="(item, i) in list" :ref="el => { divs[i] = el }">
-      {{ item }}
-    </div>
-  </template>
-
-  <script>
-    import { ref, reactive, onBeforeUpdate } from 'vue'
-
-    export default {
-      setup() {
-        const list = reactive([1, 2, 3])
-        const divs = ref([])
-
-        // make sure to reset the refs before each update
-        onBeforeUpdate(() => {
-          divs.value = []
-        })
-
-        return {
-          list,
-          divs
-        }
-      }
-    }
-  </script>
-  ```
-
-## Reactivity Utilities
-
-### `unref`
-
-Returns the inner value if the argument is a ref, otherwise return the argument itself. This is a sugar function for `val = isRef(val) ? val.value : val`.
-
-```js
-function useFoo(x: number | Ref<number>) {
-  const unwrapped = unref(x) // unwrapped is guaranteed to be number now
-}
-```
-
-### `toRef`
-
-Can be used to create a ref for a property on a source reactive object. The ref can then be passed around, retaining the reactive connection to its source property.
-
-```js
-const state = reactive({
-  foo: 1,
-  bar: 2
-})
-
-const fooRef = toRef(state, 'foo')
-
-fooRef.value++
-console.log(state.foo) // 2
-
-state.foo++
-console.log(fooRef.value) // 3
-```
-
-`toRef` is useful when you want to pass the ref of a prop to a composition function:
-
-```js
-export default {
-  setup(props) {
-    useSomeFeature(toRef(props, 'foo'))
-  }
-}
-```
-
-### `toRefs`
-
-Converts a reactive object to a plain object where each property of the resulting object is a ref pointing to the corresponding property of the original object.
-
-```js
-const state = reactive({
-  foo: 1,
-  bar: 2
-})
-
-const stateAsRefs = toRefs(state)
-/*
-Type of stateAsRefs:
-
-{
-  foo: Ref<number>,
-  bar: Ref<number>
-}
-*/
-
-// The ref and the original property is "linked"
-state.foo++
-console.log(stateAsRefs.foo) // 2
-
-stateAsRefs.foo.value++
-console.log(state.foo) // 3
-```
-
-`toRefs` is useful when returning a reactive object from a composition function so that the consuming component can destructure/spread the returned object without losing reactivity:
+### Usage with JSX
 
 ```js
-function useFeatureX() {
-  const state = reactive({
-    foo: 1,
-    bar: 2
-  })
-
-  // logic operating on state
-
-  // convert to refs when returning
-  return toRefs(state)
-}
-
 export default {
   setup() {
-    // can destructure without losing reactivity
-    const { foo, bar } = useFeatureX()
+    const root = ref(null)
 
-    return {
-      foo,
-      bar
-    }
+    return () =>
+      h('div', {
+        ref: root
+      })
+
+    // with JSX
+    return () => <div ref={root} />
   }
 }
 ```
 
-### `isRef`
-
-Checks if a value is a ref object.
+### Usage inside `v-for`
 
-### `isProxy`
+Composition API template refs do not have special handling when used inside `v-for`. Instead, use function refs to perform custom handling:
 
-Checks if an object is a proxy created by `reactive` or `readonly`.
-
-### `isReactive`
-
-Checks if an object is a reactive proxy created by `reactive`.
+```html
+<template>
+  <div v-for="(item, i) in list" :ref="el => { divs[i] = el }">
+    {{ item }}
+  </div>
+</template>
 
-```js
-import { reactive, isReactive } from 'vue'
-export default {
-  setup() {
-    const state = reactive({
-      name: 'John'
-    })
-    console.log(isReactive(state)) // -> true
-  }
-}
-```
+<script>
+  import { ref, reactive, onBeforeUpdate } from 'vue'
 
-It also returns `true` if the proxy is created by `readonly`, but is wrapping another proxy created by `reactive`.
+  export default {
+    setup() {
+      const list = reactive([1, 2, 3])
+      const divs = ref([])
 
-```js{7-15}
-import { reactive, isReactive, readonly } from 'vue'
-export default {
-  setup() {
-    const state = reactive({
-      name: 'John'
-    })
-    // readonly proxy created from plain object
-    const plain = readonly({
-      name: 'Mary'
-    })
-    console.log(isReactive(plain)) // -> false
+      // make sure to reset the refs before each update
+      onBeforeUpdate(() => {
+        divs.value = []
+      })
 
-    // readonly proxy created from reactive proxy
-    const stateCopy = readonly(state)
-    console.log(isReactive(stateCopy)) // -> true
+      return {
+        list,
+        divs
+      }
+    }
   }
-}
+</script>
 ```
 
-### `isReadonly`
-
-Checks if an object is a readonly proxy created by `readonly`.
-
 ## Advanced Reactivity APIs
 
 ### `customRef`
diff --git a/src/api/reactivity-utilities.md b/src/api/reactivity-utilities.md
index e69de29bb2..1d56c804b1 100644
--- a/src/api/reactivity-utilities.md
+++ b/src/api/reactivity-utilities.md
@@ -0,0 +1,146 @@
+# Reactivity Utilities
+
+## `unref`
+
+Returns the inner value if the argument is a ref, otherwise return the argument itself. This is a sugar function for `val = isRef(val) ? val.value : val`.
+
+```js
+function useFoo(x: number | Ref<number>) {
+  const unwrapped = unref(x) // unwrapped is guaranteed to be number now
+}
+```
+
+## `toRef`
+
+Can be used to create a ref for a property on a source reactive object. The ref can then be passed around, retaining the reactive connection to its source property.
+
+```js
+const state = reactive({
+  foo: 1,
+  bar: 2
+})
+
+const fooRef = toRef(state, 'foo')
+
+fooRef.value++
+console.log(state.foo) // 2
+
+state.foo++
+console.log(fooRef.value) // 3
+```
+
+`toRef` is useful when you want to pass the ref of a prop to a composition function:
+
+```js
+export default {
+  setup(props) {
+    useSomeFeature(toRef(props, 'foo'))
+  }
+}
+```
+
+## `toRefs`
+
+Converts a reactive object to a plain object where each property of the resulting object is a ref pointing to the corresponding property of the original object.
+
+```js
+const state = reactive({
+  foo: 1,
+  bar: 2
+})
+
+const stateAsRefs = toRefs(state)
+/*
+Type of stateAsRefs:
+
+{
+  foo: Ref<number>,
+  bar: Ref<number>
+}
+*/
+
+// The ref and the original property is "linked"
+state.foo++
+console.log(stateAsRefs.foo) // 2
+
+stateAsRefs.foo.value++
+console.log(state.foo) // 3
+```
+
+`toRefs` is useful when returning a reactive object from a composition function so that the consuming component can destructure/spread the returned object without losing reactivity:
+
+```js
+function useFeatureX() {
+  const state = reactive({
+    foo: 1,
+    bar: 2
+  })
+
+  // logic operating on state
+
+  // convert to refs when returning
+  return toRefs(state)
+}
+
+export default {
+  setup() {
+    // can destructure without losing reactivity
+    const { foo, bar } = useFeatureX()
+
+    return {
+      foo,
+      bar
+    }
+  }
+}
+```
+
+## `isRef`
+
+Checks if a value is a ref object.
+
+## `isProxy`
+
+Checks if an object is a proxy created by `reactive` or `readonly`.
+
+## `isReactive`
+
+Checks if an object is a reactive proxy created by `reactive`.
+
+```js
+import { reactive, isReactive } from 'vue'
+export default {
+  setup() {
+    const state = reactive({
+      name: 'John'
+    })
+    console.log(isReactive(state)) // -> true
+  }
+}
+```
+
+It also returns `true` if the proxy is created by `readonly`, but is wrapping another proxy created by `reactive`.
+
+```js{7-15}
+import { reactive, isReactive, readonly } from 'vue'
+export default {
+  setup() {
+    const state = reactive({
+      name: 'John'
+    })
+    // readonly proxy created from plain object
+    const plain = readonly({
+      name: 'Mary'
+    })
+    console.log(isReactive(plain)) // -> false
+
+    // readonly proxy created from reactive proxy
+    const stateCopy = readonly(state)
+    console.log(isReactive(stateCopy)) // -> true
+  }
+}
+```
+
+## `isReadonly`
+
+Checks if an object is a readonly proxy created by `readonly`.

From fa755d5669968ad411cdd0bd4cd7ffb9512f7f11 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sat, 23 May 2020 18:00:50 +0300
Subject: [PATCH 18/35] feat: separated advanced reactivity apis

---
 src/.vuepress/config.js            |   6 +-
 src/api/advanced-reactivity-api.md | 153 ++++++++++++++++++++++++++++
 src/api/composition-api.md         | 154 -----------------------------
 3 files changed, 158 insertions(+), 155 deletions(-)
 create mode 100644 src/api/advanced-reactivity-api.md

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index 6b09813dc1..7633695d98 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -88,7 +88,11 @@ const sidebar = {
     {
       title: 'Reactivity-related API',
       collapsable: false,
-      children: ['/api/reactivity-api', '/api/reactivity-utilities']
+      children: [
+        '/api/reactivity-api',
+        '/api/reactivity-utilities',
+        '/api/advanced-reactivity-api'
+      ]
     },
     '/api/composition-api'
   ]
diff --git a/src/api/advanced-reactivity-api.md b/src/api/advanced-reactivity-api.md
new file mode 100644
index 0000000000..977ef66cae
--- /dev/null
+++ b/src/api/advanced-reactivity-api.md
@@ -0,0 +1,153 @@
+# Advanced Reactivity APIs
+
+## `customRef`
+
+Creates a customized ref with explicit control over its dependency tracking and updates triggering. It expects a factory function, which receives `track` and `trigger` functions as arguments and should return an object with `get` and `set`.
+
+- Example using a custom ref to implement debounce with `v-model`:
+
+  ```html
+  <input v-model="text" />
+  ```
+
+  ```js
+  function useDebouncedRef(value, delay = 200) {
+    let timeout
+    return customRef((track, trigger) => {
+      return {
+        get() {
+          track()
+          return value
+        },
+        set(newValue) {
+          clearTimeout(timeout)
+          timeout = setTimeout(() => {
+            value = newValue
+            trigger()
+          }, delay)
+        }
+      }
+    })
+  }
+
+  export default {
+    setup() {
+      return {
+        text: useDebouncedRef('hello')
+      }
+    }
+  }
+  ```
+
+- **Typing**
+
+  ```ts
+  function customRef<T>(factory: CustomRefFactory<T>): Ref<T>
+
+  type CustomRefFactory<T> = (
+    track: () => void,
+    trigger: () => void
+  ) => {
+    get: () => T
+    set: (value: T) => void
+  }
+  ```
+
+## `markRaw`
+
+Marks an object so that it will never be converted to a proxy. Returns the object itself.
+
+```js
+const foo = markRaw({})
+console.log(isReactive(reactive(foo))) // false
+
+// also works when nested inside other reactive objects
+const bar = reactive({ foo })
+console.log(isReactive(bar.foo)) // false
+```
+
+::: warning
+`markRaw` and the shallowXXX APIs below allow you to selectively opt-out of the default deep reactive/readonly conversion and embed raw, non-proxied objects in your state graph. They can be used for various reasons:
+
+- Some values simply should not be made reactive, for example a complex 3rd party class instance, or a Vue component object.
+
+- Skipping proxy conversion can provide performance improvements when rendering large lists with immutable data sources.
+
+They are considered advanced because the raw opt-out is only at the root level, so if you set a nested, non-marked raw object into a reactive object and then access it again, you get the proxied version back. This can lead to **identity hazards** - i.e. performing an operation that relies on object identity but using both the raw and the proxied version of the same object:
+
+```js
+const foo = markRaw({
+  nested: {}
+})
+
+const bar = reactive({
+  // although `foo` is marked as raw, foo.nested is not.
+  nested: foo.nested
+})
+
+console.log(foo.nested === bar.nested) // false
+```
+
+Identity hazards are in general rare. However, to properly utilize these APIs while safely avoiding identity hazards requires a solid understanding of how the reactivity system works.
+:::
+
+## `shallowReactive`
+
+Creates a reactive proxy that tracks reactivity of its own properties but does not perform deep reactive conversion of nested objects (exposes raw values).
+
+```js
+const state = shallowReactive({
+  foo: 1,
+  nested: {
+    bar: 2
+  }
+})
+
+// mutating state's own properties is reactive
+state.foo++
+// ...but does not convert nested objects
+isReactive(state.nested) // false
+state.nested.bar++ // non-reactive
+```
+
+## `shallowReadonly`
+
+Creates a proxy that makes its own properties readonly, but does not perform deep readonly conversion of nested objects (exposes raw values).
+
+```js
+const state = shallowReadonly({
+  foo: 1,
+  nested: {
+    bar: 2
+  }
+})
+
+// mutating state's own properties will fail
+state.foo++
+// ...but works on nested objects
+isReadonly(state.nested) // false
+state.nested.bar++ // works
+```
+
+## `shallowRef`
+
+Creates a ref that tracks its own `.value` mutation but doesn't make its value reactive.
+
+```js
+const foo = shallowRef({})
+// mutating the ref's value is reactive
+foo.value = {}
+// but the value will not be converted.
+isReactive(foo.value) // false
+```
+
+## `toRaw`
+
+Returns the raw, original object of a `reactive` or `readonly` proxy. This is an escape hatch that can be used to temporarily read without incurring proxy access/tracking overhead or write without triggering changes. It is **not** recommended to hold a persistent reference to the original object. Use with caution.
+
+```js
+const foo = {}
+const reactiveFoo = reactive(foo)
+
+console.log(toRaw(reactiveFoo) === foo) // true
+```
diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index 4ddbf19eca..0509d8bf46 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -376,157 +376,3 @@ Composition API template refs do not have special handling when used inside `v-f
   }
 </script>
 ```
-
-## Advanced Reactivity APIs
-
-### `customRef`
-
-Creates a customized ref with explicit control over its dependency tracking and updates triggering. It expects a factory function, which receives `track` and `trigger` functions as arguments and should return an object with `get` and `set`.
-
-- Example using a custom ref to implement debounce with `v-model`:
-
-  ```html
-  <input v-model="text" />
-  ```
-
-  ```js
-  function useDebouncedRef(value, delay = 200) {
-    let timeout
-    return customRef((track, trigger) => {
-      return {
-        get() {
-          track()
-          return value
-        },
-        set(newValue) {
-          clearTimeout(timeout)
-          timeout = setTimeout(() => {
-            value = newValue
-            trigger()
-          }, delay)
-        }
-      }
-    })
-  }
-
-  export default {
-    setup() {
-      return {
-        text: useDebouncedRef('hello')
-      }
-    }
-  }
-  ```
-
-- **Typing**
-
-  ```ts
-  function customRef<T>(factory: CustomRefFactory<T>): Ref<T>
-
-  type CustomRefFactory<T> = (
-    track: () => void,
-    trigger: () => void
-  ) => {
-    get: () => T
-    set: (value: T) => void
-  }
-  ```
-
-### `markRaw`
-
-Marks an object so that it will never be converted to a proxy. Returns the object itself.
-
-```js
-const foo = markRaw({})
-console.log(isReactive(reactive(foo))) // false
-
-// also works when nested inside other reactive objects
-const bar = reactive({ foo })
-console.log(isReactive(bar.foo)) // false
-```
-
-::: warning
-`markRaw` and the shallowXXX APIs below allow you to selectively opt-out of the default deep reactive/readonly conversion and embed raw, non-proxied objects in your state graph. They can be used for various reasons:
-
-- Some values simply should not be made reactive, for example a complex 3rd party class instance, or a Vue component object.
-
-- Skipping proxy conversion can provide performance improvements when rendering large lists with immutable data sources.
-
-They are considered advanced because the raw opt-out is only at the root level, so if you set a nested, non-marked raw object into a reactive object and then access it again, you get the proxied version back. This can lead to **identity hazards** - i.e. performing an operation that relies on object identity but using both the raw and the proxied version of the same object:
-
-```js
-const foo = markRaw({
-  nested: {}
-})
-
-const bar = reactive({
-  // although `foo` is marked as raw, foo.nested is not.
-  nested: foo.nested
-})
-
-console.log(foo.nested === bar.nested) // false
-```
-
-Identity hazards are in general rare. However, to properly utilize these APIs while safely avoiding identity hazards requires a solid understanding of how the reactivity system works.
-:::
-
-### `shallowReactive`
-
-Creates a reactive proxy that tracks reactivity of its own properties but does not perform deep reactive conversion of nested objects (exposes raw values).
-
-```js
-const state = shallowReactive({
-  foo: 1,
-  nested: {
-    bar: 2
-  }
-})
-
-// mutating state's own properties is reactive
-state.foo++
-// ...but does not convert nested objects
-isReactive(state.nested) // false
-state.nested.bar++ // non-reactive
-```
-
-### `shallowReadonly`
-
-Creates a proxy that makes its own properties readonly, but does not perform deep readonly conversion of nested objects (exposes raw values).
-
-```js
-const state = shallowReadonly({
-  foo: 1,
-  nested: {
-    bar: 2
-  }
-})
-
-// mutating state's own properties will fail
-state.foo++
-// ...but works on nested objects
-isReadonly(state.nested) // false
-state.nested.bar++ // works
-```
-
-### `shallowRef`
-
-Creates a ref that tracks its own `.value` mutation but doesn't make its value reactive.
-
-```js
-const foo = shallowRef({})
-// mutating the ref's value is reactive
-foo.value = {}
-// but the value will not be converted.
-isReactive(foo.value) // false
-```
-
-### `toRaw`
-
-Returns the raw, original object of a `reactive` or `readonly` proxy. This is an escape hatch that can be used to temporarily read without incurring proxy access/tracking overhead or write without triggering changes. It is **not** recommended to hold a persistent reference to the original object. Use with caution.
-
-```js
-const foo = {}
-const reactiveFoo = reactive(foo)
-
-console.log(toRaw(reactiveFoo) === foo) // true
-```

From a1166c1f7dc5f474cd732332c3fb27d3f57b3cfd Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sat, 23 May 2020 18:05:38 +0300
Subject: [PATCH 19/35] fix: fixed indentation

---
 src/api/advanced-reactivity-api.md | 24 +++++-----
 src/api/composition-api.md         | 72 +++++++++++++++---------------
 src/api/reactivity-api.md          | 54 +++++++++++-----------
 3 files changed, 76 insertions(+), 74 deletions(-)

diff --git a/src/api/advanced-reactivity-api.md b/src/api/advanced-reactivity-api.md
index 977ef66cae..6fa3ca8e6e 100644
--- a/src/api/advanced-reactivity-api.md
+++ b/src/api/advanced-reactivity-api.md
@@ -1,5 +1,7 @@
 # Advanced Reactivity APIs
 
+> This section uses [single-file component](TODO: SFC) syntax for code examples
+
 ## `customRef`
 
 Creates a customized ref with explicit control over its dependency tracking and updates triggering. It expects a factory function, which receives `track` and `trigger` functions as arguments and should return an object with `get` and `set`.
@@ -39,19 +41,19 @@ Creates a customized ref with explicit control over its dependency tracking and
   }
   ```
 
-- **Typing**
+### Typing
 
-  ```ts
-  function customRef<T>(factory: CustomRefFactory<T>): Ref<T>
+```ts
+function customRef<T>(factory: CustomRefFactory<T>): Ref<T>
 
-  type CustomRefFactory<T> = (
-    track: () => void,
-    trigger: () => void
-  ) => {
-    get: () => T
-    set: (value: T) => void
-  }
-  ```
+type CustomRefFactory<T> = (
+  track: () => void,
+  trigger: () => void
+) => {
+  get: () => T
+  set: (value: T) => void
+}
+```
 
 ## `markRaw`
 
diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index 0509d8bf46..51c3b9f672 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -104,20 +104,20 @@ If `setup` returns an object, the properties on the object will be merged into t
 </template>
 
 <script>
-  import { ref, reactive } from 'vue'
-
-  export default {
-    setup() {
-      const count = ref(0)
-      const object = reactive({ foo: 'bar' })
-
-      // expose to template
-      return {
-        count,
-        object
-      }
+import { ref, reactive } from 'vue'
+
+export default {
+  setup() {
+    const count = ref(0)
+    const object = reactive({ foo: 'bar' })
+
+    // expose to template
+    return {
+      count,
+      object
     }
   }
+}
 </script>
 ```
 
@@ -299,22 +299,22 @@ When using the Composition API, the concept of _reactive refs_ and [template ref
 </template>
 
 <script>
-  import { ref, onMounted } from 'vue'
+import { ref, onMounted } from 'vue'
 
-  export default {
-    setup() {
-      const root = ref(null)
+export default {
+  setup() {
+    const root = ref(null)
 
-      onMounted(() => {
-        // the DOM element will be assigned to the ref after initial render
-        console.log(root.value) // <div/>
-      })
+    onMounted(() => {
+      // the DOM element will be assigned to the ref after initial render
+      console.log(root.value) // <div/>
+    })
 
-      return {
-        root
-      }
+    return {
+      root
     }
   }
+}
 </script>
 ```
 
@@ -356,23 +356,23 @@ Composition API template refs do not have special handling when used inside `v-f
 </template>
 
 <script>
-  import { ref, reactive, onBeforeUpdate } from 'vue'
+import { ref, reactive, onBeforeUpdate } from 'vue'
 
-  export default {
-    setup() {
-      const list = reactive([1, 2, 3])
-      const divs = ref([])
+export default {
+  setup() {
+    const list = reactive([1, 2, 3])
+    const divs = ref([])
 
-      // make sure to reset the refs before each update
-      onBeforeUpdate(() => {
-        divs.value = []
-      })
+    // make sure to reset the refs before each update
+    onBeforeUpdate(() => {
+      divs.value = []
+    })
 
-      return {
-        list,
-        divs
-      }
+    return {
+      list,
+      divs
     }
   }
+}
 </script>
 ```
diff --git a/src/api/reactivity-api.md b/src/api/reactivity-api.md
index 1e0dab27c1..2ff95d1796 100644
--- a/src/api/reactivity-api.md
+++ b/src/api/reactivity-api.md
@@ -43,15 +43,15 @@ When a ref is returned as a property on the render context (the object returned
 </template>
 
 <script>
-  import { ref } from 'vue'
-  export default {
-    setup() {
-      const count = ref(0)
-      return {
-        count
-      }
+import { ref } from 'vue'
+export default {
+  setup() {
+    const count = ref(0)
+    return {
+      count
     }
   }
+}
 </script>
 ```
 
@@ -66,19 +66,19 @@ However, if we decide to change the inline event handler on button click to the
 </template>
 
 <script>
-  import { ref } from 'vue'
-  export default {
-    setup() {
-      const count = ref(0)
-      function increment() {
-        count.value++ // ref is not unwrapped outside the template
-      }
-      return {
-        count,
-        increment
-      }
+import { ref } from 'vue'
+export default {
+  setup() {
+    const count = ref(0)
+    function increment() {
+      count.value++ // ref is not unwrapped outside the template
+    }
+    return {
+      count,
+      increment
     }
   }
+}
 </script>
 ```
 
@@ -267,19 +267,19 @@ Vue's reactivity system buffers invalidated effects and flushes them asynchronou
 </template>
 
 <script>
-  export default {
-    setup() {
-      const count = ref(0)
+export default {
+  setup() {
+    const count = ref(0)
 
-      watchEffect(() => {
-        console.log(count.value)
-      })
+    watchEffect(() => {
+      console.log(count.value)
+    })
 
-      return {
-        count
-      }
+    return {
+      count
     }
   }
+}
 </script>
 ```
 

From c5428e95225ad9c65677801b844f4cb9a79a9243 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sun, 24 May 2020 10:10:44 +0300
Subject: [PATCH 20/35] fix: refactored reactivity API structure

---
 src/.vuepress/config.js                       |   8 +-
 ...eactivity-api.md => computed-watch-api.md} | 191 ++----------
 ...dvanced-reactivity-api.md => proxy-api.md} | 156 +++++-----
 src/api/reactivity-utilities.md               | 146 ---------
 src/api/refs-api.md                           | 289 ++++++++++++++++++
 5 files changed, 397 insertions(+), 393 deletions(-)
 rename src/api/{reactivity-api.md => computed-watch-api.md} (56%)
 rename src/api/{advanced-reactivity-api.md => proxy-api.md} (51%)
 delete mode 100644 src/api/reactivity-utilities.md
 create mode 100644 src/api/refs-api.md

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index 7633695d98..2ccb62247c 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -86,12 +86,12 @@ const sidebar = {
     '/api/directives',
     '/api/special-attributes',
     {
-      title: 'Reactivity-related API',
+      title: 'Reactivity API',
       collapsable: false,
       children: [
-        '/api/reactivity-api',
-        '/api/reactivity-utilities',
-        '/api/advanced-reactivity-api'
+        '/api/proxy-api',
+        '/api/refs-api',
+        '/api/computed-watch-api'
       ]
     },
     '/api/composition-api'
diff --git a/src/api/reactivity-api.md b/src/api/computed-watch-api.md
similarity index 56%
rename from src/api/reactivity-api.md
rename to src/api/computed-watch-api.md
index 2ff95d1796..10f974c26a 100644
--- a/src/api/reactivity-api.md
+++ b/src/api/computed-watch-api.md
@@ -1,146 +1,10 @@
-# Reactivity APIs
+# Computed and watch
 
-## `reactive`
-
-Takes an object and returns a reactive proxy of the original.
-
-```js
-const obj = reactive({ count: 0 })
-```
-
-The reactive conversion is "deep"—it affects all nested properties. In the [ES2015 Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) based implementation, the returned proxy is **not** equal to the original object. It is recommended to work exclusively with the reactive proxy and avoid relying on the original object.
-
-### Typing
-
-```ts
-function reactive<T extends object>(raw: T): T
-```
-
-## `ref`
-
-Takes an inner value and returns a reactive and mutable ref object. The ref object has a single property `.value` that points to the inner value.
-
-```js
-const count = ref(0)
-console.log(count.value) // 0
-
-count.value++
-console.log(count.value) // 1
-```
-
-If an object is assigned as a ref's value, the object is made deeply reactive by the `reactive` method.
-
-### Access in Templates
-
-When a ref is returned as a property on the render context (the object returned from `setup()`) and accessed in the template, it automatically unwraps to the inner value. There is no need to append `.value` in the template:
-
-```html
-<template>
-  <div>
-    <span>{{ count }}</span>
-    <button @click="count ++">Increment count</button>
-  </div>
-</template>
-
-<script>
-import { ref } from 'vue'
-export default {
-  setup() {
-    const count = ref(0)
-    return {
-      count
-    }
-  }
-}
-</script>
-```
-
-However, if we decide to change the inline event handler on button click to the component method declared in `setup`, we need to remember that `ref` is not unwrapped there:
-
-```html
-<template>
-  <div>
-    <span>{{ count }}</span>
-    <button @click="increment">Increment count</button>
-  </div>
-</template>
-
-<script>
-import { ref } from 'vue'
-export default {
-  setup() {
-    const count = ref(0)
-    function increment() {
-      count.value++ // ref is not unwrapped outside the template
-    }
-    return {
-      count,
-      increment
-    }
-  }
-}
-</script>
-```
-
-### Access in Reactive Objects
-
-When a ref is accessed or mutated as a property of a reactive object, it automatically unwraps to the inner value so it behaves like a normal property:
-
-```js
-const count = ref(0)
-const state = reactive({
-  count
-})
-
-console.log(state.count) // 0
-
-state.count = 1
-console.log(count.value) // 1
-```
-
-If a new ref is assigned to a property linked to an existing ref, it will replace the old ref:
-
-```js
-const otherCount = ref(2)
-
-state.count = otherCount
-console.log(state.count) // 2
-console.log(count.value) // 1
-```
-
-Ref unwrapping only happens when nested inside a reactive `Object`. There is no unwrapping performed when the ref is accessed from an `Array` or a native collection type like `Map`:
-
-```js
-const arr = reactive([ref(0)])
-// need .value here
-console.log(arr[0].value)
-
-const map = reactive(new Map([['foo', ref(0)]]))
-// need .value here
-console.log(map.get('foo').value)
-```
-
-### Typing
-
-```ts
-interface Ref<T> {
-  value: T
-}
-
-function ref<T>(value: T): Ref<T>
-```
-
-Sometimes we may need to specify complex types for a ref's inner value. We can do that succinctly by passing a generics argument when calling `ref` to override the default inference:
-
-```ts
-const foo = ref<string | number>('foo') // foo's type: Ref<string | number>
-
-foo.value = 123 // ok!
-```
+> This section uses [single-file component](TODO: SFC) syntax for code examples
 
 ## `computed`
 
-Takes a getter function and returns an immutable reactive ref object for the returned value from the getter.
+Takes a getter function and returns an immutable reactive [ref](./refs-api.html#ref) object for the returned value from the getter.
 
 ```js
 const count = ref(1)
@@ -176,27 +40,6 @@ function computed<T>(getter: () => T): Readonly<Ref<Readonly<T>>>
 function computed<T>(options: { get: () => T; set: (value: T) => void }): Ref<T>
 ```
 
-## `readonly`
-
-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.
-
-```js
-const original = reactive({ count: 0 })
-
-const copy = readonly(original)
-
-watchEffect(() => {
-  // 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!
-```
-
 ## `watchEffect`
 
 Runs a function immediately while reactively tracking its dependencies and re-runs it whenever the dependencies are changed.
@@ -215,7 +58,7 @@ setTimeout(() => {
 
 ### Stopping the Watcher
 
-When `watchEffect` is called during a component's `setup()` function or lifecycle hooks, the watcher is linked to the component's lifecycle and will be automatically stopped when the component is unmounted.
+When `watchEffect` is called during a component's [setup()](./composition-api.html#setup) function or [lifecycle hooks](./composition-api.html#lifecycle-hooks), the watcher is linked to the component's lifecycle and will be automatically stopped when the component is unmounted.
 
 In other cases, it returns a stop handle which can be called to explicitly stop the watcher:
 
@@ -267,19 +110,19 @@ Vue's reactivity system buffers invalidated effects and flushes them asynchronou
 </template>
 
 <script>
-export default {
-  setup() {
-    const count = ref(0)
+  export default {
+    setup() {
+      const count = ref(0)
 
-    watchEffect(() => {
-      console.log(count.value)
-    })
+      watchEffect(() => {
+        console.log(count.value)
+      })
 
-    return {
-      count
+      return {
+        count
+      }
     }
   }
-}
 </script>
 ```
 
@@ -374,9 +217,9 @@ type StopHandle = () => void
 
 ## `watch`
 
-The `watch` API is the exact equivalent of the Options API [`this.$watch`](./instance-methods.html#watch) (and the corresponding `watch` option). `watch` requires watching a specific data source and applies side effects in a separate callback function. It also is lazy by default - i.e. the callback is only called when the watched source has changed.
+The `watch` API is the exact equivalent of the Options API [this.$watch](./instance-methods.html#watch) (and the corresponding [watch](./options-data.html#watch) option). `watch` requires watching a specific data source and applies side effects in a separate callback function. It also is lazy by default - i.e. the callback is only called when the watched source has changed.
 
-- Compared to `watchEffect`, `watch` allows us to:
+- Compared to [watchEffect](#watcheffect), `watch` allows us to:
 
   - Perform the side effect lazily;
   - Be more specific about what state should trigger the watcher to re-run;
@@ -384,7 +227,7 @@ The `watch` API is the exact equivalent of the Options API [`this.$watch`](./ins
 
 ### Watching a Single Source
 
-A watcher data source can either be a getter function that returns a value, or directly a ref:
+A watcher data source can either be a getter function that returns a value, or directly a [ref](./refs-api.html#ref):
 
 ```js
 // watching a getter
@@ -415,7 +258,7 @@ watch([fooRef, barRef], ([foo, bar], [prevFoo, prevBar]) => {
 
 ### Shared Behavior with `watchEffect`
 
-`watch` shares behavior with `watchEffect` in terms of [manual stoppage](#stopping-the-watcher), [side effect invalidation](#side-effect-invalidation) (with `onInvalidate` passed to the callback as the 3rd argument instead), [flush timing](#effect-flush-timing) and [debugging](#watcher-debugging).
+`watch` shares behavior with [`watchEffect`](#watcheffect) in terms of [manual stoppage](#stopping-the-watcher), [side effect invalidation](#side-effect-invalidation) (with `onInvalidate` passed to the callback as the 3rd argument instead), [flush timing](#effect-flush-timing) and [debugging](#watcher-debugging).
 
 ### Typing
 
diff --git a/src/api/advanced-reactivity-api.md b/src/api/proxy-api.md
similarity index 51%
rename from src/api/advanced-reactivity-api.md
rename to src/api/proxy-api.md
index 6fa3ca8e6e..d0341c866a 100644
--- a/src/api/advanced-reactivity-api.md
+++ b/src/api/proxy-api.md
@@ -1,60 +1,101 @@
-# Advanced Reactivity APIs
+# Proxy-related APIs
 
 > This section uses [single-file component](TODO: SFC) syntax for code examples
 
-## `customRef`
-
-Creates a customized ref with explicit control over its dependency tracking and updates triggering. It expects a factory function, which receives `track` and `trigger` functions as arguments and should return an object with `get` and `set`.
-
-- Example using a custom ref to implement debounce with `v-model`:
-
-  ```html
-  <input v-model="text" />
-  ```
-
-  ```js
-  function useDebouncedRef(value, delay = 200) {
-    let timeout
-    return customRef((track, trigger) => {
-      return {
-        get() {
-          track()
-          return value
-        },
-        set(newValue) {
-          clearTimeout(timeout)
-          timeout = setTimeout(() => {
-            value = newValue
-            trigger()
-          }, delay)
-        }
-      }
-    })
-  }
+## `reactive`
 
-  export default {
-    setup() {
-      return {
-        text: useDebouncedRef('hello')
-      }
-    }
-  }
-  ```
+Takes an object and returns a reactive proxy of the original.
+
+```js
+const obj = reactive({ count: 0 })
+```
+
+The reactive conversion is "deep"—it affects all nested properties. In the [ES2015 Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) based implementation, the returned proxy is **not** equal to the original object. It is recommended to work exclusively with the reactive proxy and avoid relying on the original object.
 
 ### Typing
 
 ```ts
-function customRef<T>(factory: CustomRefFactory<T>): Ref<T>
-
-type CustomRefFactory<T> = (
-  track: () => void,
-  trigger: () => void
-) => {
-  get: () => T
-  set: (value: T) => void
+function reactive<T extends object>(raw: T): T
+```
+
+## `readonly`
+
+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.
+
+```js
+const original = reactive({ count: 0 })
+
+const copy = readonly(original)
+
+watchEffect(() => {
+  // 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!
+```
+
+## `isProxy`
+
+Checks if an object is a proxy created by [`reactive`](#reactive) or [`readonly`](#readonly).
+
+## `isReactive`
+
+Checks if an object is a reactive proxy created by [`reactive`](#reactive).
+
+```js
+import { reactive, isReactive } from 'vue'
+export default {
+  setup() {
+    const state = reactive({
+      name: 'John'
+    })
+    console.log(isReactive(state)) // -> true
+  }
 }
 ```
 
+It also returns `true` if the proxy is created by [`readonly`](#readonly), but is wrapping another proxy created by [`reactive`](#reactive).
+
+```js{7-15}
+import { reactive, isReactive, readonly } from 'vue'
+export default {
+  setup() {
+    const state = reactive({
+      name: 'John'
+    })
+    // readonly proxy created from plain object
+    const plain = readonly({
+      name: 'Mary'
+    })
+    console.log(isReactive(plain)) // -> false
+
+    // readonly proxy created from reactive proxy
+    const stateCopy = readonly(state)
+    console.log(isReactive(stateCopy)) // -> true
+  }
+}
+```
+
+## `isReadonly`
+
+Checks if an object is a readonly proxy created by [`readonly`](#readonly).
+
+## `toRaw`
+
+Returns the raw, original object of a [`reactive`](#reactive) or [`readonly`](#readonly) proxy. This is an escape hatch that can be used to temporarily read without incurring proxy access/tracking overhead or write without triggering changes. It is **not** recommended to hold a persistent reference to the original object. Use with caution.
+
+```js
+const foo = {}
+const reactiveFoo = reactive(foo)
+
+console.log(toRaw(reactiveFoo) === foo) // true
+```
+
 ## `markRaw`
 
 Marks an object so that it will never be converted to a proxy. Returns the object itself.
@@ -130,26 +171,3 @@ state.foo++
 isReadonly(state.nested) // false
 state.nested.bar++ // works
 ```
-
-## `shallowRef`
-
-Creates a ref that tracks its own `.value` mutation but doesn't make its value reactive.
-
-```js
-const foo = shallowRef({})
-// mutating the ref's value is reactive
-foo.value = {}
-// but the value will not be converted.
-isReactive(foo.value) // false
-```
-
-## `toRaw`
-
-Returns the raw, original object of a `reactive` or `readonly` proxy. This is an escape hatch that can be used to temporarily read without incurring proxy access/tracking overhead or write without triggering changes. It is **not** recommended to hold a persistent reference to the original object. Use with caution.
-
-```js
-const foo = {}
-const reactiveFoo = reactive(foo)
-
-console.log(toRaw(reactiveFoo) === foo) // true
-```
diff --git a/src/api/reactivity-utilities.md b/src/api/reactivity-utilities.md
deleted file mode 100644
index 1d56c804b1..0000000000
--- a/src/api/reactivity-utilities.md
+++ /dev/null
@@ -1,146 +0,0 @@
-# Reactivity Utilities
-
-## `unref`
-
-Returns the inner value if the argument is a ref, otherwise return the argument itself. This is a sugar function for `val = isRef(val) ? val.value : val`.
-
-```js
-function useFoo(x: number | Ref<number>) {
-  const unwrapped = unref(x) // unwrapped is guaranteed to be number now
-}
-```
-
-## `toRef`
-
-Can be used to create a ref for a property on a source reactive object. The ref can then be passed around, retaining the reactive connection to its source property.
-
-```js
-const state = reactive({
-  foo: 1,
-  bar: 2
-})
-
-const fooRef = toRef(state, 'foo')
-
-fooRef.value++
-console.log(state.foo) // 2
-
-state.foo++
-console.log(fooRef.value) // 3
-```
-
-`toRef` is useful when you want to pass the ref of a prop to a composition function:
-
-```js
-export default {
-  setup(props) {
-    useSomeFeature(toRef(props, 'foo'))
-  }
-}
-```
-
-## `toRefs`
-
-Converts a reactive object to a plain object where each property of the resulting object is a ref pointing to the corresponding property of the original object.
-
-```js
-const state = reactive({
-  foo: 1,
-  bar: 2
-})
-
-const stateAsRefs = toRefs(state)
-/*
-Type of stateAsRefs:
-
-{
-  foo: Ref<number>,
-  bar: Ref<number>
-}
-*/
-
-// The ref and the original property is "linked"
-state.foo++
-console.log(stateAsRefs.foo) // 2
-
-stateAsRefs.foo.value++
-console.log(state.foo) // 3
-```
-
-`toRefs` is useful when returning a reactive object from a composition function so that the consuming component can destructure/spread the returned object without losing reactivity:
-
-```js
-function useFeatureX() {
-  const state = reactive({
-    foo: 1,
-    bar: 2
-  })
-
-  // logic operating on state
-
-  // convert to refs when returning
-  return toRefs(state)
-}
-
-export default {
-  setup() {
-    // can destructure without losing reactivity
-    const { foo, bar } = useFeatureX()
-
-    return {
-      foo,
-      bar
-    }
-  }
-}
-```
-
-## `isRef`
-
-Checks if a value is a ref object.
-
-## `isProxy`
-
-Checks if an object is a proxy created by `reactive` or `readonly`.
-
-## `isReactive`
-
-Checks if an object is a reactive proxy created by `reactive`.
-
-```js
-import { reactive, isReactive } from 'vue'
-export default {
-  setup() {
-    const state = reactive({
-      name: 'John'
-    })
-    console.log(isReactive(state)) // -> true
-  }
-}
-```
-
-It also returns `true` if the proxy is created by `readonly`, but is wrapping another proxy created by `reactive`.
-
-```js{7-15}
-import { reactive, isReactive, readonly } from 'vue'
-export default {
-  setup() {
-    const state = reactive({
-      name: 'John'
-    })
-    // readonly proxy created from plain object
-    const plain = readonly({
-      name: 'Mary'
-    })
-    console.log(isReactive(plain)) // -> false
-
-    // readonly proxy created from reactive proxy
-    const stateCopy = readonly(state)
-    console.log(isReactive(stateCopy)) // -> true
-  }
-}
-```
-
-## `isReadonly`
-
-Checks if an object is a readonly proxy created by `readonly`.
diff --git a/src/api/refs-api.md b/src/api/refs-api.md
new file mode 100644
index 0000000000..d443eb2601
--- /dev/null
+++ b/src/api/refs-api.md
@@ -0,0 +1,289 @@
+# Refs
+
+> This section uses [single-file component](TODO: SFC) syntax for code examples
+
+## `ref`
+
+Takes an inner value and returns a reactive and mutable ref object. The ref object has a single property `.value` that points to the inner value.
+
+```js
+const count = ref(0)
+console.log(count.value) // 0
+
+count.value++
+console.log(count.value) // 1
+```
+
+If an object is assigned as a ref's value, the object is made deeply reactive by the [reactive](./proxy-api.html#reactive) method.
+
+### Access in Templates
+
+When a ref is returned as a property on the render context (the object returned from [setup()](./composition-api.html#setup)) and accessed in the template, it automatically unwraps to the inner value. There is no need to append `.value` in the template:
+
+```html
+<template>
+  <div>
+    <span>{{ count }}</span>
+    <button @click="count ++">Increment count</button>
+  </div>
+</template>
+
+<script>
+import { ref } from 'vue'
+export default {
+  setup() {
+    const count = ref(0)
+    return {
+      count
+    }
+  }
+}
+</script>
+```
+
+However, if we decide to change the inline event handler on button click to the component method declared in `setup`, we need to remember that `ref` is not unwrapped there:
+
+```html
+<template>
+  <div>
+    <span>{{ count }}</span>
+    <button @click="increment">Increment count</button>
+  </div>
+</template>
+
+<script>
+import { ref } from 'vue'
+export default {
+  setup() {
+    const count = ref(0)
+    function increment() {
+      count.value++ // ref is not unwrapped outside the template
+    }
+    return {
+      count,
+      increment
+    }
+  }
+}
+</script>
+```
+
+### Access in Reactive Objects
+
+When a ref is accessed or mutated as a property of a reactive object, it automatically unwraps to the inner value so it behaves like a normal property:
+
+```js
+const count = ref(0)
+const state = reactive({
+  count
+})
+
+console.log(state.count) // 0
+
+state.count = 1
+console.log(count.value) // 1
+```
+
+If a new ref is assigned to a property linked to an existing ref, it will replace the old ref:
+
+```js
+const otherCount = ref(2)
+
+state.count = otherCount
+console.log(state.count) // 2
+console.log(count.value) // 1
+```
+
+Ref unwrapping only happens when nested inside a reactive `Object`. There is no unwrapping performed when the ref is accessed from an `Array` or a native collection type like [`Map`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map):
+
+```js
+const arr = reactive([ref(0)])
+// need .value here
+console.log(arr[0].value)
+
+const map = reactive(new Map([['foo', ref(0)]]))
+// need .value here
+console.log(map.get('foo').value)
+```
+
+### Typing
+
+```ts
+interface Ref<T> {
+  value: T
+}
+
+function ref<T>(value: T): Ref<T>
+```
+
+Sometimes we may need to specify complex types for a ref's inner value. We can do that succinctly by passing a generics argument when calling `ref` to override the default inference:
+
+```ts
+const foo = ref<string | number>('foo') // foo's type: Ref<string | number>
+
+foo.value = 123 // ok!
+```
+
+## `unref`
+
+Returns the inner value if the argument is a [`ref`](#ref), otherwise return the argument itself. This is a sugar function for `val = isRef(val) ? val.value : val`.
+
+```js
+function useFoo(x: number | Ref<number>) {
+  const unwrapped = unref(x) // unwrapped is guaranteed to be number now
+}
+```
+
+## `toRef`
+
+Can be used to create a [`ref`](#ref) for a property on a source reactive object. The ref can then be passed around, retaining the reactive connection to its source property.
+
+```js
+const state = reactive({
+  foo: 1,
+  bar: 2
+})
+
+const fooRef = toRef(state, 'foo')
+
+fooRef.value++
+console.log(state.foo) // 2
+
+state.foo++
+console.log(fooRef.value) // 3
+```
+
+`toRef` is useful when you want to pass the ref of a prop to a composition function:
+
+```js
+export default {
+  setup(props) {
+    useSomeFeature(toRef(props, 'foo'))
+  }
+}
+```
+
+## `toRefs`
+
+Converts a reactive object to a plain object where each property of the resulting object is a [`ref`](#ref) pointing to the corresponding property of the original object.
+
+```js
+const state = reactive({
+  foo: 1,
+  bar: 2
+})
+
+const stateAsRefs = toRefs(state)
+/*
+Type of stateAsRefs:
+
+{
+  foo: Ref<number>,
+  bar: Ref<number>
+}
+*/
+
+// The ref and the original property is "linked"
+state.foo++
+console.log(stateAsRefs.foo) // 2
+
+stateAsRefs.foo.value++
+console.log(state.foo) // 3
+```
+
+`toRefs` is useful when returning a reactive object from a composition function so that the consuming component can destructure/spread the returned object without losing reactivity:
+
+```js
+function useFeatureX() {
+  const state = reactive({
+    foo: 1,
+    bar: 2
+  })
+
+  // logic operating on state
+
+  // convert to refs when returning
+  return toRefs(state)
+}
+
+export default {
+  setup() {
+    // can destructure without losing reactivity
+    const { foo, bar } = useFeatureX()
+
+    return {
+      foo,
+      bar
+    }
+  }
+}
+```
+
+## `isRef`
+
+Checks if a value is a ref object.
+
+## `customRef`
+
+Creates a customized ref with explicit control over its dependency tracking and updates triggering. It expects a factory function, which receives `track` and `trigger` functions as arguments and should return an object with `get` and `set`.
+
+- Example using a custom ref to implement debounce with `v-model`:
+
+  ```html
+  <input v-model="text" />
+  ```
+
+  ```js
+  function useDebouncedRef(value, delay = 200) {
+    let timeout
+    return customRef((track, trigger) => {
+      return {
+        get() {
+          track()
+          return value
+        },
+        set(newValue) {
+          clearTimeout(timeout)
+          timeout = setTimeout(() => {
+            value = newValue
+            trigger()
+          }, delay)
+        }
+      }
+    })
+  }
+
+  export default {
+    setup() {
+      return {
+        text: useDebouncedRef('hello')
+      }
+    }
+  }
+  ```
+
+### Typing
+
+```ts
+function customRef<T>(factory: CustomRefFactory<T>): Ref<T>
+
+type CustomRefFactory<T> = (
+  track: () => void,
+  trigger: () => void
+) => {
+  get: () => T
+  set: (value: T) => void
+}
+```
+
+## `shallowRef`
+
+Creates a ref that tracks its own `.value` mutation but doesn't make its value reactive.
+
+```js
+const foo = shallowRef({})
+// mutating the ref's value is reactive
+foo.value = {}
+// but the value will not be converted.
+isReactive(foo.value) // false
+```

From 16349e379cc1b9094d7543afacd72acb72887878 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sun, 24 May 2020 10:18:12 +0300
Subject: [PATCH 21/35] feat: added links to composition API

---
 src/api/composition-api.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index 51c3b9f672..7cdc28662e 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -12,7 +12,7 @@ The `setup` function is a new component option. It serves as the entry point for
 
 ### Arguments
 
-The function receives the resolved props as its first argument:
+The function receives the resolved [props](../guide/component-props.html) as its first argument:
 
 ```js
 export default {
@@ -25,7 +25,7 @@ export default {
 }
 ```
 
-Note that this `props` object is reactive - i.e. it is updated when new props are passed in, and can be observed and reacted upon using `watchEffect` or `watch`:
+Note that this `props` object is reactive - i.e. it is updated when new props are passed in, and can be observed and reacted upon using [watchEffect](./computed-watch-api.html#watcheffect) or [watch](./computed-watch-api.html#watch):
 
 ```js
 export default {
@@ -69,7 +69,7 @@ const MyComponent = {
 }
 ```
 
-Unlike `props`, `context` argument can be destructured safely so `attrs` and `slots` would always expose the latest values even after updates:
+Unlike `props`, `context` argument can be destructured safely so [attrs](./instance-properties.html#attrs) and [slots](./instance-properties.html#slots) would always expose the latest values even after updates:
 
 ```js
 const MyComponent = {
@@ -121,7 +121,7 @@ export default {
 </script>
 ```
 
-Note that refs returned from `setup` are automatically unwrapped when accessed in the template so you shouldn't use `.value` in templates.
+Note that [refs](./refs-api.html#ref) returned from `setup` are automatically unwrapped when accessed in the template so you shouldn't use `.value` in templates.
 
 ### Usage with Render Functions
 
@@ -195,7 +195,7 @@ const MyComponent = {
 }
 ```
 
-These lifecycle hook registration functions can only be used synchronously during `setup()`, since they rely on internal global state to locate the current active instance (the component instance whose `setup()` is being called right now). Calling them without a current active instance will result in an error.
+These lifecycle hook registration functions can only be used synchronously during [`setup()`](#setup), since they rely on internal global state to locate the current active instance (the component instance whose `setup()` is being called right now). Calling them without a current active instance will result in an error.
 
 The component instance context is also set during the synchronous execution of lifecycle hooks, so watchers and computed properties created inside synchronously inside lifecycle hooks are also automatically tore down when the component unmounts.
 
@@ -215,7 +215,7 @@ The component instance context is also set during the synchronous execution of l
 
 ## Dependency Injection
 
-`provide` and `inject` enables dependency injection. Both can only be called during `setup()` with a current active instance.
+`provide` and `inject` enables dependency injection. Both can only be called during [`setup()`](#setup) with a current active instance.
 
 ```js
 import { provide, inject } from 'vue'
@@ -242,7 +242,7 @@ const Descendent = {
 
 ### Injection Reactivity
 
-To retain reactivity between provided and injected values, we can use a ref:
+To retain reactivity between provided and injected values, we can use a [ref](./refs-api.html#ref):
 
 ```js
 // in provider
@@ -291,7 +291,7 @@ const foo = inject<string>('foo') // string | undefined
 
 ## Template Refs
 
-When using the Composition API, the concept of _reactive refs_ and [template refs](TODO) are unified. In order to obtain a reference to an in-template element or component instance, we can declare a ref as usual and return it from `setup()`:
+When using the Composition API, the concept of [reactive refs](./refs-api.html#ref) and [template refs](TODO) are unified. In order to obtain a reference to an in-template element or component instance, we can declare a ref as usual and return it from `setup()`:
 
 ```html
 <template>

From 1d20443a621764932f119f5f401daaf284a00f1d Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Mon, 25 May 2020 08:50:36 +0300
Subject: [PATCH 22/35] fix: renamed proxy APIs to basic

---
 src/.vuepress/config.js                       | 2 +-
 src/api/{proxy-api.md => basic-reactivity.md} | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)
 rename src/api/{proxy-api.md => basic-reactivity.md} (99%)

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index 2ccb62247c..573e3b5b73 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -89,7 +89,7 @@ const sidebar = {
       title: 'Reactivity API',
       collapsable: false,
       children: [
-        '/api/proxy-api',
+        '/api/basic-reactivity',
         '/api/refs-api',
         '/api/computed-watch-api'
       ]
diff --git a/src/api/proxy-api.md b/src/api/basic-reactivity.md
similarity index 99%
rename from src/api/proxy-api.md
rename to src/api/basic-reactivity.md
index d0341c866a..5f27f097ec 100644
--- a/src/api/proxy-api.md
+++ b/src/api/basic-reactivity.md
@@ -1,4 +1,4 @@
-# Proxy-related APIs
+# Basic Reactivity APIs
 
 > This section uses [single-file component](TODO: SFC) syntax for code examples
 

From 0a8f39ad0a41e5e3a2c36f3526f2da37120b5374 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Tue, 26 May 2020 20:33:22 +0300
Subject: [PATCH 23/35] fix: fixed reactive typing

---
 src/api/basic-reactivity.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/api/basic-reactivity.md b/src/api/basic-reactivity.md
index 5f27f097ec..0d908a3ffd 100644
--- a/src/api/basic-reactivity.md
+++ b/src/api/basic-reactivity.md
@@ -15,7 +15,7 @@ The reactive conversion is "deep"—it affects all nested properties. In the [ES
 ### Typing
 
 ```ts
-function reactive<T extends object>(raw: T): T
+function reactive<T extends object>(target: T): UnwrapNestedRefs<T>
 ```
 
 ## `readonly`

From 59a8a5ddf0c326203d49a8a56b227cb1c52a341c Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Tue, 26 May 2020 20:40:27 +0300
Subject: [PATCH 24/35] fix: addressed reviewers comments

---
 src/api/basic-reactivity.md | 4 ++--
 src/api/composition-api.md  | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/api/basic-reactivity.md b/src/api/basic-reactivity.md
index 0d908a3ffd..99af8aff3e 100644
--- a/src/api/basic-reactivity.md
+++ b/src/api/basic-reactivity.md
@@ -4,7 +4,7 @@
 
 ## `reactive`
 
-Takes an object and returns a reactive proxy of the original.
+Returns a reactive copy of the object.
 
 ```js
 const obj = reactive({ count: 0 })
@@ -20,7 +20,7 @@ function reactive<T extends object>(target: T): UnwrapNestedRefs<T>
 
 ## `readonly`
 
-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.
+Takes an object (reactive or plain) or a [ref](./refs-api.html#ref) and returns a readonly proxy to the original. A readonly proxy is deep: any nested property accessed will be readonly as well.
 
 ```js
 const original = reactive({ count: 0 })
diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index 7cdc28662e..201454eba8 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -121,7 +121,7 @@ export default {
 </script>
 ```
 
-Note that [refs](./refs-api.html#ref) returned from `setup` are automatically unwrapped when accessed in the template so you shouldn't use `.value` in templates.
+Note that [refs](./refs-api.html#ref) returned from `setup` are [automatically unwrapped](./refs-api.html#access-in-templates) when accessed in the template so you shouldn't use `.value` in templates.
 
 ### Usage with Render Functions
 

From 0439ac1715a1a8ea7da2215dfdbc70ad1bfd66d9 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Tue, 26 May 2020 20:53:03 +0300
Subject: [PATCH 25/35] fix: added async onInvalidate

---
 src/api/composition-api.md    | 2 +-
 src/api/computed-watch-api.md | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index 201454eba8..376d9d2a2b 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -121,7 +121,7 @@ export default {
 </script>
 ```
 
-Note that [refs](./refs-api.html#ref) returned from `setup` are [automatically unwrapped](./refs-api.html#access-in-templates) when accessed in the template so you shouldn't use `.value` in templates.
+Note that [refs](./refs-api.html#ref) returned from `setup` are [automatically unwrapped](./refs-api.html#access-in-templates ) when accessed in the template so you shouldn't use `.value` in templates.
 
 ### Usage with Render Functions
 
diff --git a/src/api/computed-watch-api.md b/src/api/computed-watch-api.md
index 10f974c26a..dd853cddf5 100644
--- a/src/api/computed-watch-api.md
+++ b/src/api/computed-watch-api.md
@@ -93,8 +93,9 @@ We are registering the invalidation callback via a passed-in function instead of
 
 ```js
 const data = ref(null)
-watchEffect(async () => {
+watchEffect(async onInvalidate => {
   data.value = await fetchData(props.id)
+  onInvalidate(() => {...})
 })
 ```
 

From 31d992fb7922e27491ea7817403779b4e6de0013 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Tue, 26 May 2020 20:58:57 +0300
Subject: [PATCH 26/35] feat: added example for generic with unknown type

---
 src/api/refs-api.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/src/api/refs-api.md b/src/api/refs-api.md
index d443eb2601..f3b09c074a 100644
--- a/src/api/refs-api.md
+++ b/src/api/refs-api.md
@@ -124,6 +124,15 @@ const foo = ref<string | number>('foo') // foo's type: Ref<string | number>
 foo.value = 123 // ok!
 ```
 
+If the type of the generic is unknown, it's recommended to cast `ref` to `Ref<T>`:
+
+```js
+function useState<State extends string>(initial: State) {
+  const state = ref(initial) as Ref<State> // state.value -> State extends string
+  return state
+}
+```
+
 ## `unref`
 
 Returns the inner value if the argument is a [`ref`](#ref), otherwise return the argument itself. This is a sugar function for `val = isRef(val) ? val.value : val`.

From 0585c6c6a22fd2e5aa456dcb92d70fdff3e47b4b Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sun, 31 May 2020 20:59:53 +0300
Subject: [PATCH 27/35] feat: created table of contents

---
 src/api/global-api.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)
 create mode 100644 src/api/global-api.md

diff --git a/src/api/global-api.md b/src/api/global-api.md
new file mode 100644
index 0000000000..abcffcf9cf
--- /dev/null
+++ b/src/api/global-api.md
@@ -0,0 +1,15 @@
+# Global API
+
+## createApp
+
+## h
+
+## defineComponent
+
+## defineAsyncComponent
+
+## createRenderer
+
+## getCurrentInstance
+
+## nextTick

From 69cb500e98fd83d76b8b4f77df49f0b9dc5486d6 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sun, 31 May 2020 21:30:22 +0300
Subject: [PATCH 28/35] feat: added createApp description

---
 src/api/global-api.md         | 56 +++++++++++++++++++++++++++++++++++
 src/guide/component-basics.md |  2 +-
 2 files changed, 57 insertions(+), 1 deletion(-)

diff --git a/src/api/global-api.md b/src/api/global-api.md
index abcffcf9cf..54fc349002 100644
--- a/src/api/global-api.md
+++ b/src/api/global-api.md
@@ -2,6 +2,62 @@
 
 ## createApp
 
+Returns an application instance which provides an application context. The entire component tree mounted by the application instance share the same context.
+
+```js
+const app = Vue.createApp({})
+```
+
+You can chain other methods after `createApp`, they can be found in [Application API](./application-api.html)
+
+### Arguments
+
+The function receives a root component options object as a first parameter:
+
+```js
+const app = Vue.createApp({
+  data() {
+    return {
+      ...
+    }
+  },
+  methods: {...},
+  computed: {...}
+  ...
+})
+```
+
+With the second parameter, we can pass root props to the application:
+
+```html
+<div id="app">
+  <!-- Will display 'Evan' -->
+  {{ username }}
+</div>
+```
+
+```js
+const app = Vue.createApp(
+  {
+    props: ['username']
+  },
+  { username: 'Evan' }
+)
+```
+
+### Typing
+
+```ts
+interface Data {
+  [key: string]: unknown
+}
+
+export type CreateAppFunction<HostElement> = (
+  rootComponent: PublicAPIComponent,
+  rootProps?: Data | null
+) => App<HostElement>
+```
+
 ## h
 
 ## defineComponent
diff --git a/src/guide/component-basics.md b/src/guide/component-basics.md
index 617dd94cd4..395a357d63 100644
--- a/src/guide/component-basics.md
+++ b/src/guide/component-basics.md
@@ -75,7 +75,7 @@ For example, you might have components for a header, sidebar, and content area,
 To use these components in templates, they must be registered so that Vue knows about them. There are two types of component registration: **global** and **local**. So far, we've only registered components globally, using `component` method of created app:
 
 ```js
-const app = Vue.createApp()
+const app = Vue.createApp({})
 
 app.component('my-component-name', {
   // ... options ...

From 610f83b1cdb5cbf0743953583e87e7a444f517c0 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sun, 31 May 2020 21:46:12 +0300
Subject: [PATCH 29/35] feat: added h

---
 src/api/global-api.md | 46 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/src/api/global-api.md b/src/api/global-api.md
index 54fc349002..5a70f63ed0 100644
--- a/src/api/global-api.md
+++ b/src/api/global-api.md
@@ -60,6 +60,52 @@ export type CreateAppFunction<HostElement> = (
 
 ## h
 
+Returns a returns "virtual node", usually abbreviated to **VNode**: a plain object which contains information describing to Vue what kind of node it should render on the page, including descriptions of any child nodes. It is intended for manually written [render functions](../guide/render-function.md):
+
+```js
+render() {
+  return Vue.h('h1', {},'Some title')
+}
+```
+
+### Arguments
+
+Accepts three arguments: tag, props and children
+
+#### tag
+
+- **Type:** `String | Object | Function | null`
+
+- **Details:**
+
+  An HTML tag name, a component, an async component or null. Using null would render a comment. This parameter is required
+
+#### props
+
+- **Type:** `Object`
+
+- **Details:**
+
+  An object corresponding to the attributes, props and events we would use in a template. Optional
+
+#### children
+
+- **Type:** `String | Array | Object`
+
+- **Details:**
+
+  Children VNodes, built using `h()`, or using strings to get 'text VNodes' or an object with slots. Optional
+
+  ```js
+  h('div', {}, [
+    'Some text comes first.',
+    h('h1', 'A headline'),
+    h(MyComponent, {
+      someProp: 'foobar'
+    })
+  ])
+  ```
+
 ## defineComponent
 
 ## defineAsyncComponent

From a4b8adbfedb5992fee4b33d0badd207d40dcad55 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Fri, 12 Jun 2020 19:00:21 +0300
Subject: [PATCH 30/35] feat: added defineComponent

---
 src/api/global-api.md                | 90 +++++++++++++++++++++++++++-
 src/guide/component-dynamic-async.md |  2 +-
 2 files changed, 89 insertions(+), 3 deletions(-)

diff --git a/src/api/global-api.md b/src/api/global-api.md
index 5a70f63ed0..1294898cc4 100644
--- a/src/api/global-api.md
+++ b/src/api/global-api.md
@@ -108,10 +108,96 @@ Accepts three arguments: tag, props and children
 
 ## defineComponent
 
+Implementation-wise `defineComponent` returns the object passed to it. However, in terms of typing, the returned value has a synthetic type of a constructor for manual render function, TSX and IDE tooling support.
+
+### Arguments
+
+An object with component options
+
+```js
+import { defineComponent } from 'vue'
+
+const MyComponent = defineComponent({
+  data() {
+    return { count: 1 }
+  },
+  methods: {
+    increment() {
+      this.count++
+    }
+  }
+})
+```
+
 ## defineAsyncComponent
 
-## createRenderer
+Creates an async component that will be loaded only when it's necessary.
 
-## getCurrentInstance
+### Arguments
+
+For basic usage, `defineAsyncComponent` can accept a a factory function returning a `Promise`. Promise's `resolve` callback should be called when you have retrieved your component definition from the server. You can also call `reject(reason)` to indicate the load has failed.
+
+```js
+import { defineAsyncComponent } from 'vue'
+
+const AsyncComp = defineAsyncComponent(() =>
+  import('./components/AsyncComponent.vue')
+)
+
+app.component('async-component', AsyncComp)
+```
+
+When using [local registration](../guide/component-registration.html#local-registration), you can also directly provide a function that returns a `Promise`:
+
+```js
+import { createApp, defineAsyncComponent } from 'vue'
+
+createApp({
+  // ...
+  components: {
+    components: {
+      AsyncComponent: defineAsyncComponent(() =>
+        import('./components/AsyncComponent.vue')
+      )
+    }
+  }
+})
+```
+
+For advanced usage, `defineAsyncComponent` can accept an object:
+
+The `defineAsyncComponent` method can also return an object of the following format:
+
+```js
+import { defineAsyncComponent } from 'vue'
+
+const AsyncComp = defineAsyncComponent({
+  // The factory function
+  loader: () => import('./Foo.vue')
+  // A component to use while the async component is loading
+  loadingComponent: LoadingComponent,
+  // A component to use if the load fails
+  errorComponent: ErrorComponent,
+  // Delay before showing the loading component. Default: 200ms.
+  delay: 200,
+  // The error component will be displayed if a timeout is
+  // provided and exceeded. Default: Infinity.
+  timeout: 3000,
+  // A function that returns a boolean indicating whether the async component should retry when the loader promise rejects
+  retryWhen: error => error.code !== 404,
+  // Maximum allowed retries number
+  maxRetries: 3,
+  // Defining if component is suspensible
+  suspensible: false
+})
+```
+
+**See also**: [Dynamic and Async components](../guide/component-dynamic-async.html)
 
 ## nextTick
+
+Defer the callback to be executed after the next DOM update cycle. Use it immediately after you’ve changed some data to wait for the DOM update.
+
+```js
+import { createApp, nextTick } from 'vue'
+```
diff --git a/src/guide/component-dynamic-async.md b/src/guide/component-dynamic-async.md
index adce11fc9a..7aa67ea197 100644
--- a/src/guide/component-dynamic-async.md
+++ b/src/guide/component-dynamic-async.md
@@ -76,7 +76,7 @@ const AsyncComp = defineAsyncComponent(() =>
 app.component('async-component', AsyncComp)
 ```
 
-You can also use `defineAsyncComponent` when [registering a component locally](components-registration.html#Local-Registration):
+You can also use `defineAsyncComponent` when [registering a component locally](component-registration.html#local-registration):
 
 ```js
 import { createApp, defineAsyncComponent } from 'vue'

From 1d47bea5ed34384308d6d7fcb78a7bca8d1939b3 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sat, 13 Jun 2020 18:54:35 +0300
Subject: [PATCH 31/35] chore: fixed todos

---
 src/.vuepress/config.js              | 14 ++++++++++----
 src/api/application-api.md           |  2 +-
 src/api/composition-api.md           |  2 +-
 src/api/global-api.md                | 15 ++++++++++++++-
 src/api/instance-methods.md          |  4 ++--
 src/api/options-composition.md       |  4 ++--
 src/api/options-dom.md               |  2 +-
 src/guide/component-dynamic-async.md |  2 +-
 src/guide/custom-directive.md        |  6 +++---
 src/guide/list.md                    |  2 +-
 src/guide/mixins.md                  |  2 +-
 src/guide/render-function.md         |  1 -
 src/guide/state-management.md        |  3 ---
 src/guide/template-syntax.md         |  6 +++---
 14 files changed, 40 insertions(+), 25 deletions(-)

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index b41320971d..12b02812d1 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -14,7 +14,7 @@ const sidebar = {
         '/guide/list',
         '/guide/events',
         '/guide/forms',
-        '/guide/component-basics',
+        '/guide/component-basics'
       ]
     },
     {
@@ -25,7 +25,8 @@ const sidebar = {
         '/guide/component-props',
         '/guide/component-custom-events',
         '/guide/component-slots',
-        '/guide/component-provide-inject'
+        '/guide/component-provide-inject',
+        '/guide/component-dynamic-async',
       ]
     },
     {
@@ -33,7 +34,6 @@ const sidebar = {
       collapsable: false,
       children: [
         '/guide/reactivity',
-        '/guide/component-dynamic-async',
         '/guide/optimizations',
         '/guide/change-detection'
       ]
@@ -52,7 +52,12 @@ const sidebar = {
     {
       title: 'Scaling Up',
       collapsable: false,
-      children: ['/guide/routing', '/guide/state-management', '/guide/ssr', '/guide/accessibility']
+      children: [
+        '/guide/routing',
+        '/guide/state-management',
+        '/guide/ssr',
+        '/guide/accessibility'
+      ]
     },
     {
       title: 'Migration to Vue 3',
@@ -68,6 +73,7 @@ const sidebar = {
   api: [
     '/api/application-config',
     '/api/application-api',
+    '/api/global-api',
     {
       title: 'Options',
       collapsable: false,
diff --git a/src/api/application-api.md b/src/api/application-api.md
index 8e2651ca97..7d3239ab48 100644
--- a/src/api/application-api.md
+++ b/src/api/application-api.md
@@ -271,4 +271,4 @@ setTimeout(() => app.unmount('#my-app'), 5000)
 
   When this method is called on the same plugin multiple times, the plugin will be installed only once.
 
-- **See also:** [Plugins](TODO)
+- **See also:** [Plugins](../guide/plugins.html)
diff --git a/src/api/composition-api.md b/src/api/composition-api.md
index ef4843c068..2454bc6ca2 100644
--- a/src/api/composition-api.md
+++ b/src/api/composition-api.md
@@ -170,7 +170,7 @@ function setup(props: Data, context: SetupContext): Data
 ```
 
 ::: tip
-To get type inference for the arguments passed to `setup()`, the use of [`defineComponent`](TODO) is needed.
+To get type inference for the arguments passed to `setup()`, the use of [defineComponent](global-api.html#definecomponent) is needed.
 :::
 
 ## Lifecycle Hooks
diff --git a/src/api/global-api.md b/src/api/global-api.md
index 1294898cc4..b4953838b7 100644
--- a/src/api/global-api.md
+++ b/src/api/global-api.md
@@ -108,7 +108,7 @@ Accepts three arguments: tag, props and children
 
 ## defineComponent
 
-Implementation-wise `defineComponent` returns the object passed to it. However, in terms of typing, the returned value has a synthetic type of a constructor for manual render function, TSX and IDE tooling support.
+Implementation-wise `defineComponent` does nothing but return the object passed to it. However, in terms of typing, the returned value has a synthetic type of a constructor for manual render function, TSX and IDE tooling support.
 
 ### Arguments
 
@@ -200,4 +200,17 @@ Defer the callback to be executed after the next DOM update cycle. Use it immedi
 
 ```js
 import { createApp, nextTick } from 'vue'
+
+const app = createApp({
+  setup() {
+    const message = ref('Hello!')
+    const changeMessage = async newMessage => {
+      message.value = newMessage
+      await nextTick()
+      console.log('Now DOM is updated')
+    }
+  }
+})
 ```
+
+**See also**: [`$nextTick` instance method](instance-methods.html#nexttick)
diff --git a/src/api/instance-methods.md b/src/api/instance-methods.md
index 21482fa45c..b5f490c832 100644
--- a/src/api/instance-methods.md
+++ b/src/api/instance-methods.md
@@ -251,7 +251,7 @@
 
 - **Usage:**
 
-  Defer the callback to be executed after the next DOM update cycle. Use it immediately after you've changed some data to wait for the DOM update. This is the same as the global `Vue.nextTick`, except that the callback's `this` context is automatically bound to the instance calling this method.
+  Defer the callback to be executed after the next DOM update cycle. Use it immediately after you've changed some data to wait for the DOM update. This is the same as the global `nextTick`, except that the callback's `this` context is automatically bound to the instance calling this method.
 
 - **Example:**
 
@@ -274,4 +274,4 @@
   })
   ```
 
-- **See also:** [Vue.nextTick](TODO)
+- **See also:** [nextTick](global-api.html#nexttick)
diff --git a/src/api/options-composition.md b/src/api/options-composition.md
index 375aa79a31..689b01f685 100644
--- a/src/api/options-composition.md
+++ b/src/api/options-composition.md
@@ -221,7 +221,7 @@ The `setup` function is a new component option. It serves as the entry point for
   </script>
   ```
 
-  Note that [refs](TODO) returned from `setup` are automatically unwrapped when accessed in the template so there's no need for `.value` in templates.
+  Note that [refs](refs-api.html#ref) returned from `setup` are automatically unwrapped when accessed in the template so there's no need for `.value` in templates.
 
 - **Usage with Render Functions / JSX**
 
@@ -318,4 +318,4 @@ The `setup` function is a new component option. It serves as the entry point for
 
   - Having `props` as a separate argument makes it easier to type it individually without messing up the types of other properties on the context. It also makes it possible to keep a consistent signature across `setup`, `render` and plain functional components with TSX support.
 
-- **See also:** [Composition API](TODO)
+- **See also:** [Composition API](composition-api.html)
diff --git a/src/api/options-dom.md b/src/api/options-dom.md
index a101afa87a..6ed7ec7837 100644
--- a/src/api/options-dom.md
+++ b/src/api/options-dom.md
@@ -62,4 +62,4 @@
   The `render` function has priority over the render function compiled from `template` option or in-DOM HTML template of the mounting element
   :::
 
-- **See also:** [Render Functions](TODO)
+- **See also:** [Render Functions](../guide/render-function.html)
diff --git a/src/guide/component-dynamic-async.md b/src/guide/component-dynamic-async.md
index 7aa67ea197..4035f19c78 100644
--- a/src/guide/component-dynamic-async.md
+++ b/src/guide/component-dynamic-async.md
@@ -97,4 +97,4 @@ Async components are _suspensible_ by default. This means if it has a [`<Suspens
 
 The async component can opt-out of `Suspense` control and let the component always control its own loading state by specifying `suspensible: false` in its options.
 
-You can check the list of available options in the [API Reference](TODO)
+You can check the list of available options in the [API Reference](../api/global-api.html#arguments-4)
diff --git a/src/guide/custom-directive.md b/src/guide/custom-directive.md
index 689e3a7755..5f3bad1a21 100644
--- a/src/guide/custom-directive.md
+++ b/src/guide/custom-directive.md
@@ -57,7 +57,7 @@ A directive definition object can provide several hook functions (all optional):
 - `beforeUpdate`: called before the containing component's VNode is updated
 
 :::tip Note
-We'll cover VNodes in more detail [later](TODO:/render-function.html#The-Virtual-DOM), when we discuss [render functions](TODO:./render-function.html).
+We'll cover VNodes in more detail [later](render-function.html#the-virtual-dom-tree), when we discuss render functions.
 :::
 
 - `updated`: called after the containing component's VNode **and the VNodes of its children** have updated.
@@ -66,7 +66,7 @@ We'll cover VNodes in more detail [later](TODO:/render-function.html#The-Virtual
 
 - `unmounted`: called only once, when the directive is unbound from the element and the parent component is unmounted.
 
-You can check the arguments passed into these hooks (i.e. `el`, `binding`, `vnode`, and `prevVnode`) in [Custom Directive API](../api/global-api.html#directive)
+You can check the arguments passed into these hooks (i.e. `el`, `binding`, `vnode`, and `prevVnode`) in [Custom Directive API](../api/application-api.html#directive)
 
 ### Dynamic Directive Arguments
 
@@ -227,7 +227,7 @@ return withDirectives(h('div'), [[vDemo, test]])
 
 Where `vDemo` will be the directive object written by the user, which contains hooks like `mounted` and `updated`.
 
-`withDirectives` returns a cloned VNode with the user hooks wrapped and injected as VNode lifecycle hooks (see [Render Function](TODO:Render-functions) for more details):
+`withDirectives` returns a cloned VNode with the user hooks wrapped and injected as VNode lifecycle hooks (see [Render Function](render-function.html) for more details):
 
 ```js
 {
diff --git a/src/guide/list.md b/src/guide/list.md
index 007829bdd4..dbb037ecc8 100644
--- a/src/guide/list.md
+++ b/src/guide/list.md
@@ -158,7 +158,7 @@ Since it's a generic mechanism for Vue to identify nodes, the `key` also has oth
 Don't use non-primitive values like objects and arrays as `v-for` keys. Use string or numeric values instead.
 :::
 
-For detailed usage of the `key` attribute, please see the [`key` API documentation](TODO:https://vuejs.org/v2/api/#key).
+For detailed usage of the `key` attribute, please see the [`key` API documentation](../api/special-attributes.html#key).
 
 ## Array Change Detection
 
diff --git a/src/guide/mixins.md b/src/guide/mixins.md
index b0cbe035a1..23af3c8017 100644
--- a/src/guide/mixins.md
+++ b/src/guide/mixins.md
@@ -160,7 +160,7 @@ app.mount('#mixins-global')
 // => "hello from component!"
 ```
 
-In most cases, you should only use it for custom option handling like demonstrated in the example above. It's also a good idea to ship them as [Plugins](TODO) to avoid duplicate application.
+In most cases, you should only use it for custom option handling like demonstrated in the example above. It's also a good idea to ship them as [Plugins](plugins.html) to avoid duplicate application.
 
 ## Custom Option Merge Strategies
 
diff --git a/src/guide/render-function.md b/src/guide/render-function.md
index 905471dce4..7319c815e3 100644
--- a/src/guide/render-function.md
+++ b/src/guide/render-function.md
@@ -89,7 +89,6 @@ Before we dive into render functions, it’s important to know a little about ho
 <div>
   <h1>My title</h1>
   Some text content
-  <!-- TODO: Add tagline -->
 </div>
 ```
 
diff --git a/src/guide/state-management.md b/src/guide/state-management.md
index ceac0866b3..381b8cc2e9 100644
--- a/src/guide/state-management.md
+++ b/src/guide/state-management.md
@@ -4,9 +4,6 @@
 
 Large applications can often grow in complexity, due to multiple pieces of state scattered across many components and the interactions between them. To solve this problem, Vue offers [vuex](https://github.com/vuejs/vuex), our own Elm-inspired state management library. It even integrates into [vue-devtools](https://github.com/vuejs/vue-devtools), providing zero-setup access to [time travel debugging](https://raw.githubusercontent.com/vuejs/vue-devtools/master/media/demo.gif).
 
-<!--TODO: use an updated tutorial for 3.0?-->
-<div class="vue-mastery"><a href="https://www.vuemastery.com/courses/mastering-vuex/intro-to-vuex/" target="_blank" rel="sponsored noopener" title="Vuex Tutorial">Watch a video explanation on Vue Mastery</a></div>
-
 ### Information for React Developers
 
 If you're coming from React, you may be wondering how vuex compares to [redux](https://github.com/reactjs/redux), the most popular Flux implementation in that ecosystem. Redux is actually view-layer agnostic, so it can easily be used with Vue via [simple bindings](https://classic.yarnpkg.com/en/packages?q=redux%20vue&p=1). Vuex is different in that it _knows_ it's in a Vue app. This allows it to better integrate with Vue, offering a more intuitive API and improved development experience.
diff --git a/src/guide/template-syntax.md b/src/guide/template-syntax.md
index 683b4d5858..818ae19601 100644
--- a/src/guide/template-syntax.md
+++ b/src/guide/template-syntax.md
@@ -4,7 +4,7 @@ Vue.js uses an HTML-based template syntax that allows you to declaratively bind
 
 Under the hood, Vue compiles the templates into Virtual DOM render functions. Combined with the reactivity system, Vue is able to intelligently figure out the minimal number of components to re-render and apply the minimal amount of DOM manipulations when the app state changes.
 
-If you are familiar with Virtual DOM concepts and prefer the raw power of JavaScript, you can also [directly write render functions](TODO:render-function.html) instead of templates, with optional JSX support.
+If you are familiar with Virtual DOM concepts and prefer the raw power of JavaScript, you can also [directly write render functions](render-function.html) instead of templates, with optional JSX support.
 
 ## Interpolations
 
@@ -18,7 +18,7 @@ The most basic form of data binding is text interpolation using the "Mustache" s
 
 The mustache tag will be replaced with the value of the `msg` property on the corresponding data object. It will also be updated whenever the data object's `msg` property changes.
 
-You can also perform one-time interpolations that do not update on data change by using the [v-once directive](TODO:../api/#v-once), but keep in mind this will also affect any other bindings on the same node:
+You can also perform one-time interpolations that do not update on data change by using the [v-once directive](../api/directives.html#v-once), but keep in mind this will also affect any other bindings on the same node:
 
 ```html
 <span v-once>This will never change: {{ msg }}</span>
@@ -26,7 +26,7 @@ You can also perform one-time interpolations that do not update on data change b
 
 ### Raw HTML
 
-The double mustaches interprets the data as plain text, not HTML. In order to output real HTML, you will need to use the [`v-html` directive](TODO:../api/#v-html):
+The double mustaches interprets the data as plain text, not HTML. In order to output real HTML, you will need to use the [`v-html` directive](../api/directives.html#v-html):
 
 ```html
 <p>Using mustaches: {{ rawHtml }}</p>

From 520ceb5ceba5d7a2bd3cc79e253921c5e5f1828c Mon Sep 17 00:00:00 2001
From: Natalia Tepluhina <tarya.se@gmail.com>
Date: Sun, 14 Jun 2020 13:34:19 +0300
Subject: [PATCH 32/35] Update src/api/global-api.md

Co-authored-by: Carlos Rodrigues <david-181@hotmail.com>
---
 src/api/global-api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/api/global-api.md b/src/api/global-api.md
index b4953838b7..5b00c831b2 100644
--- a/src/api/global-api.md
+++ b/src/api/global-api.md
@@ -64,7 +64,7 @@ Returns a returns "virtual node", usually abbreviated to **VNode**: a plain obje
 
 ```js
 render() {
-  return Vue.h('h1', {},'Some title')
+  return Vue.h('h1', {}, 'Some title')
 }
 ```
 

From f315eb8ee6399ac5e6c2c2b03265ae4c56f9ca21 Mon Sep 17 00:00:00 2001
From: Natalia Tepluhina <tarya.se@gmail.com>
Date: Sun, 14 Jun 2020 13:34:31 +0300
Subject: [PATCH 33/35] Update src/api/global-api.md

Co-authored-by: Carlos Rodrigues <david-181@hotmail.com>
---
 src/api/global-api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/api/global-api.md b/src/api/global-api.md
index 5b00c831b2..5c82cde497 100644
--- a/src/api/global-api.md
+++ b/src/api/global-api.md
@@ -70,7 +70,7 @@ render() {
 
 ### Arguments
 
-Accepts three arguments: tag, props and children
+Accepts three arguments: `tag`, `props` and `children`
 
 #### tag
 

From 0b132326fb80aba8faf9933536412b867a3983ba Mon Sep 17 00:00:00 2001
From: Natalia Tepluhina <tarya.se@gmail.com>
Date: Sun, 14 Jun 2020 13:34:45 +0300
Subject: [PATCH 34/35] Update src/api/global-api.md

Co-authored-by: Carlos Rodrigues <david-181@hotmail.com>
---
 src/api/global-api.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/api/global-api.md b/src/api/global-api.md
index 5c82cde497..fdaef3b6d9 100644
--- a/src/api/global-api.md
+++ b/src/api/global-api.md
@@ -94,7 +94,7 @@ Accepts three arguments: `tag`, `props` and `children`
 
 - **Details:**
 
-  Children VNodes, built using `h()`, or using strings to get 'text VNodes' or an object with slots. Optional
+  Children VNodes, built using `h()`, or using strings to get "text VNodes" or an object with slots. Optional
 
   ```js
   h('div', {}, [

From 65e4220839080e85340100c6dab435fae3022a83 Mon Sep 17 00:00:00 2001
From: NataliaTepluhina <tarya.se@gmail.com>
Date: Sun, 14 Jun 2020 15:38:06 +0300
Subject: [PATCH 35/35] fix: reordered examples

---
 src/api/global-api.md | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/src/api/global-api.md b/src/api/global-api.md
index b4953838b7..7781f7527a 100644
--- a/src/api/global-api.md
+++ b/src/api/global-api.md
@@ -29,13 +29,6 @@ const app = Vue.createApp({
 
 With the second parameter, we can pass root props to the application:
 
-```html
-<div id="app">
-  <!-- Will display 'Evan' -->
-  {{ username }}
-</div>
-```
-
 ```js
 const app = Vue.createApp(
   {
@@ -45,6 +38,14 @@ const app = Vue.createApp(
 )
 ```
 
+
+```html
+<div id="app">
+  <!-- Will display 'Evan' -->
+  {{ username }}
+</div>
+```
+
 ### Typing
 
 ```ts