Composition API reference

[NataliaTepluhina]

This is mostly a copy of https://vue-composition-api-rfc.netlify.app/api.html with few subtle changes. I believe the reference there is sufficient enough (maybe sometimes too detailed). Would be happy to hear your thoughts!

[znck]

There is a lot of information in this PR, I feel I might have missed something so I would do another pass on it. (this week sometime)

[znck]

It's little unclear. We should unambiguously state that context can be destructured but attrs and slots cannot be. Destructuring e.g. setup(props, { attrs: { name } }) would break attrs reactivity.

[NataliaTepluhina]

Agreed. I've split this statement onto 2 parts, so hopefully, it's clearer now:

Unlike props, context argument can be destructured safely so attrs and slots would always expose the latest values even after updates:

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:

const MyComponent = {
  setup(props, { attrs: { foo } }) {
    function onClick() {
      console.log(foo) // won't be the latest reference as we lost `attrs` reactivity with destructuring
    }
  }
}

[znck]

I feel we can drop the if made available as this hypothetical situation is not providing any value. And the previous statement seems enough reasoning for the unavailability of this in setup().

[phanan]

It sounds pretty weird to me that we're saying "this is not available" at first and right after that "[this] will behave quite differently," which implies that it's still available. AFAIK, this is always available. Whether it's the Vue instance or the parent context (global/window) is another story.

[NataliaTepluhina]

I rephrased the explanation so now we rather say this won't be a reference to Vue instance:

• 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:

  setup() {
    const that = this
    function onClick() {
        console.log(this !== that) // not the `this` you'd expect!
    }
  }

[znck]

This stands correct for inline event handlers, which can be confusing, given that the same event handler in setup() would have to use .value. I feel we should add an example for this scenario.

[NataliaTepluhina]

I've added this explanation:

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:

<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>

[znck]

Out of context but :ref="root" behaves differently and it's an easy pitfall to use v-bind with ref as it feels so natural. I feel we should be explicit about it and convey that ref="root" is equivalent to :ref="el => root = el".

[NataliaTepluhina]

Added a warning there:

:::warning
Please note that ref will behave differently when used with v-bind directive. ref="root" would be equivalent to :ref="el => root = el"
:::

However, I don't feel good about it as it adds an unnecessary cognitive load (at least for me it does) 😅

[bencodezen]

Oof yeah that is confusing... 😕

[NataliaTepluhina]

But that's template ref 🤔

[pikax]

Never mind :D 🤦

[znck]

However, I don't feel good about it as it adds an unnecessary cognitive load (at least for me it does) 😅

True! Should we have separate caveats or faq or common pitfalls section?

[znck]

Now I feel this should be handled in runtime. This confusion is an unnecessary burden on users.

[NataliaTepluhina]

@znck I probably should remove it for now

[znck]

This deserves an example.

[NataliaTepluhina]

Added an extended example here:

isReactive

Check if an object is a reactive proxy created by reactive.

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.

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
  }
}

[phanan]

👏👏👏

[phanan]

It sounds pretty weird to me that we're saying "this is not available" at first and right after that "[this] will behave quite differently," which implies that it's still available. AFAIK, this is always available. Whether it's the Vue instance or the parent context (global/window) is another story.

[phanan]

I'm quite sure we don't indent the first level of code inside <script> and <style> 😊

[Jinjiang]

Hi @NataliaTepluhina I'm thinking moving Reactivity-related APIs (Reactivity APIs + Reactivity Utilities + Advanced Reactivity APIs) as a independent page, before Composition API page. Because it's not only useful to Composition API, but also to Options API, even out of Vue Components.

For example:

export default {
  data() {
    return {
      somethingReadonly: readonly(foo),
      somethingWontChange: toRaw(bar)
    }
  }
}

or:

// shared.js
export const someGlobalData = reactive(baz)

<script>
import { someGlobalData } from './shared'
export default {
  setup() {
    return {
      x: someGlobalData
    }
  }
}
</script>

For others like provide, inject and lifecycle hooks, they must be used inside setup. So I think is make sense to leave them here.

WDYT 😅

Thanks.

[Jinjiang]

Should we introduce h somewhere in our API Reference? It seems not appeared so far.

[NataliaTepluhina]

@Jinjiang the suggestion about Reactivity APIs makes perfect sense to me! Will separate it from the Composition API

As for h, I was planning on smth like Global Vue API to have h, defineComponent etc there. Not sure about naming though 🤔

[NataliaTepluhina]

@znck @phanan @Jinjiang thank you all for all the awesome fixes and suggestions! I've changed the PR accordingly, please take a second look whenever you have a chance 🙏

[NataliaTepluhina]

@pikax sorry, I failed to add you to reviewers list on the 1st review 🤦‍♀️

Would be happy if you could take a look!

[Jinjiang]

@NataliaTepluhina for Reactivity APIs I have some further ideas. When I'm trying to find the usage of these APIs for a special purpose like read-only data, I need to know readonly, isReadonly, and shallowReadonly, markRaw at the same time. But they are in 3 different sub pages. It feels like a little bit inconvenient.

I think for guidelines it's better to separate things into basic and advanced parts. But for references, maybe it's better to separate them into groups for different cases or purposes, like:

• All proxy usage: reactive, readonly, isProxy, isReactive, isReadonly, shallowReactive, shallowReadonly, markRaw, toRaw.
• All ref usage: ref, isRef, toRef, toRefs, customRef, shallowRef, unref.
• Computed and watch: computed, watch, watchEffect.

Does that make more sense? ... or just don't group them and assemble them into one page together?

Thanks 😄

[NataliaTepluhina]

@Jinjiang What if we place them on the same page (Reactivity API) but group them with subsections you mentioned?

[Jinjiang]

I personally think that’s great 🙂 @NataliaTepluhina

[NataliaTepluhina]

@Jinjiang I still ended up dividing it onto 3 pages just for the sake of the effective sidebar usage: if we place them to the same page, some sections will go to h4 and they won't be shown on the sidebar. To improve UX with better navigation, I've done this splitting and added lots of cross-links between sections. Could you please take another look?

Also, a huge thanks for these suggestions! It makes lots of sense in terms of structuring the API properly 👍

[bencodezen]

Great job with all the edits and updates @NataliaTepluhina!

This is a very dense section and I have an instinct to come up with a similar approach to the Essentials of Vue.js so we can gradually build people up for a conceptually heavy topic, but it will take some time for me to come up with the proposal.

Nice work!

[bencodezen]

Oof yeah that is confusing... 😕

[Jinjiang]

@NataliaTepluhina that looks much better to me :-) Just one more little struggled idea: how about change the title "Proxy-related APIs" to "Basic" directly? Because:

1. People may not know the Proxy things behind these APIs before them deeply look into it.
2. This part is more like inherited + extended from the "traditional" Vue.observable() way in Vue 2.x.

WDYT? :-)

[NataliaTepluhina]

@Jinjiang done! 😅

[pikax]

is this section the same as https://deploy-preview-97--vue-next.netlify.app/api/options-composition.html#setup ?

[NataliaTepluhina]

Yes and I am still not sure where we should keep it (because it's a component option but it's also a special option

[pikax]

Sorry if I'm being blind, but I can't understand this paragraph with the example context, shouldn't we use onInvalidate on the async effect?

[NataliaTepluhina]

@pikax would something like this work?

const data = ref(null)
watchEffect(async onInvalidate => {
  data.value = await fetchData(props.id)
  onInvalidate(() => {...})
})

[pikax]

that case you would only register onInvalidate after the fetch is done, is useful if you do something like:

export default defineComponent({
  props: {
    id: Number,
  },

  setup(props) {
    const data = ref(null);
    watchEffect(async (onInvalidate) => {
      let controller = new AbortController();
      onInvalidate(() => {
        if (controller) {
          controller.abort();
          console.log("aborted");
        }
      });

      const response = await fetch(`https://swapi.dev/api/people/${props.id}`, {
        signal: controller.signal,

        mode: "cors",
      });

      data.value = await response.json();

      // clear the controller
      controller = null;
    });

    return {
      data,
    };
  },
});

[pikax]

Reviewing again, and on my first pass I misunderstood what this example is all about, probably add a gotcha and be more explicit of using onInvalidate after the promise is resolved might cause unexpected issues. Or add the correct way of doing it, ie register the onInvalidate before the promise resolve.

NOTE: Sorry for my misunderstanding

[NataliaTepluhina]

@pikax no need to be sorry! It wasn't clear indeed.

I fixed an example and added a comment

[Jinjiang]

@NataliaTepluhina looks great. no more from my side. :-)

[NataliaTepluhina]

@pikax thank you for the detailed review! I've addressed your comments, would you mind taking a look again? 😅

[znck]

🎊 👏 looks great!!

[NataliaTepluhina]

Thanks everyone for the review! I am merging this beast so if we have any fixes, let's handle them in the follow-up PRs