Expose API discussion (#343)

[yyx990803]

• Pull Request
• Full Rendered Proposal

---

• Start Date: 2020-09-06
• Target Major Version: 3.x
• Reference Issues: Component's public API #135, Add a composition API to explicitly expose() public members #210

Summary

Provide the ability for components to control what is publicly exposed on its component instance. This proposal unifies #135 and #210 with additional details.

Basic example

Options API

export defualt {
  expose: ['increment'],

  data() {
    return {
      count: 0
    }
  },
  methods: {
    increment() {
      this.count++
    }
  }
}

Composition API

import { ref } from 'vue'

export default {
  setup(props, { expose }) {
    const count = ref(0)

    function increment() {
      count.value++
    }

    // public
    expose({
      increment
    })

    // private
    return { increment, count }
  }
}

Here in the both cases, other components would only be able to access the increment method from this component, and nothing else.

Motivation

In Vue, we have a few ways to retrieve the "public instance" of a component:

• Via template refs
• Via the $parent or $root properties

Up until now, the concept of the "public instance" equivalent to the this context inside a component. However, this creates a number of issues:

1. A component's public and internal interface isn't always the same. A component may have internal properties that it doesn't want to expose to other components, or a component may want to expose methods that are specifically meant to be used by other components.

2. A component returning render function from setup() encloses all its state inside the setup() closure, so nothing is exposed on the public instance, and there's currently no way to selectively expose properties while using this pattern.

3. <script setup> is also compiled into (2) so has the same issue.

The proposed APIs solve these issues by giving components the ability to explicitly declare publicly exposed properties.

Detailed design

Options API

A new option, expose is introduced. It expects an array of property keys to be exposed:

// Child.vue
export defualt {
  expose: ['increment'],

  data() {
    return {
      count: 0
    }
  },
  methods: {
    increment() {
      this.count++
    }
  }
}

In a parent component:

<Child ref="child" />

this.$refs.child.increment() // ok
this.$refs.child.count // undefined

If expose is an empty array, then the component would be considered "closed" and no properties would be exposed.

Note: expose option is only respected in the base component and ignored when used in mixins.

Composition API

In Composition API, the 2nd argument of setup (aka the "setup context") now also provides the expose method:

import { ref } from 'vue'

export default {
  setup(props, { expose }) {
    const count = ref(0)

    function increment() {
      count.value++
    }

    // public
    expose({
      increment
    })

    // private
    return { increment, count }
  }
}

The expose method expects an object of the actual values to be exposed.

In <script setup>

The defineExpose() macro compiles into runtime expose() call.

<script setup>
  const count = ref(0)

  function increment() {
    count.value++
  }

  defineExpose({
    increment
  })
</script>

See relevant section in the <script setup> RFC.

Exposed Ref Unwrapping Behavior

Note the exposed instance unwraps refs similar to the normal public instance:

// in child
const count = ref(0)
expose({
  count
})

// in parent
this.$refs.child.count // 0

Limiting Expose Control to Base Component

As raised in the discussions for a previous draft (#210), it would be very confusing if mixins and external composition functions are able to expose arbitrary properties. Therefore, the API is designed to restrict the capability to the base component only:

• The expose option is ignored when encountered in mixins or extends sources.
• The Composition API expose function is provided via the setup context instead of a global API (so that it cannot be imported in external composition functions) and can only be called once.

Additionally Exposed Properties

An experimental implementation has been shipped in prior versions and we found in some cases there are patterns or tools (e.g. vue-test-utils) that relies on the presence of Vue built-in instance properties like $el or $refs.

The public instance with explicit expose thus still exposes these built-in instance properties.

Drawbacks

N/A

Alternatives

N/A

Adoption strategy

This feature is additive and doesn't affect existing usage.

Unresolved Questions

Type Inference

Currently no Vue tooling has the ability to infer types of child component instances obtained from a ref.

A workaround is to explicitly export the public interface from the child component:

<!-- Child.vue -->
<script lang="ts">
  export interface Api {
    // ...
  }
</script>

In parent:

<script setup lang="ts">
  import { ref } from 'vue'
  import Child from './Child.vue'
  import type { Api } from './Child.vue'

  const childRef = ref<Api>()
</script>

<template>
  <Child ref="childRef" />
</template>

The above does not affect the runtime API design and therefore should not block this RFC from being merged.

[CyberAP]

I am so glad expose API is getting its final shape, but I also have some questions regarding the implementation:

What will happen if we try to access private component methods?

If an expose option was set I would really like for Vue to log console error only saying that the private API was accessed but at the same time to still be able to use that API. I think this is very important because creating a good component API is hard and it's even harder to work with a component that has a poor component API, especially when you can't do anything about that.

A perfect example here is Composition API where an author can severely limit what can be accessed by parent components. Let's say we are bound to a library that doesn't emit event while it could. In Options API we could subscribe to some of its internal data or methods and simulate these events. With Composition API that interface is hidden from us and there's nothing we could do about that. I would really like for Options API to retain the current level of flexibility along with improved developer experience.

How state mutations are going to be affected?

Let's say we exposed some internal component's state to the parent component and our parent component mutates that state via $refs.fooComponent.fooState = 1. Should there be a warning that mutation happend outside of owner component?

Should Vue warn that exposed member is undefined?

A common scenario with Public API is that it might get removed by accident because it's not used by the component itself. Maybe that's a good idea to notifiy developers as soon as it gets removed?

[yyx990803]

What will happen if we try to access private component methods?

It will be undefined. I think only emitting warnings defeats the purpose of this proposal. That said, you do still have access to the internal instance via .$ so that's your escape hatch.

How state mutations are going to be affected?

If you expose it as-is, then you are saying it can be mutated. If you want to prevent it from being mutated from the outside, expose a getter, readonly ref, or a computed property.

Should Vue warn that exposed member is undefined?

Yes, that can be an implementation improvement.

[wenfangdu]

An experimental implementation has been shipped in prior versions and we found in some cases there are patterns or tools (e.g. vue-test-utils) that rely on the presence of Vue built-in instance properties like $el or $refs.

The public instance with explicit expose thus still exposes these built-in instance properties.

Just tried this, seems a public instance with explicit expose doesn't expose $el, $refs etc.

[wenfangdu]

@yyx990803 I'm running 3.1.4, adding expose: [] to a child component, and log the child instance in the parent doesn't print $el. Remove expose: [] will print $el.

[yyx990803]

Just tested and it's working as intended. Just note the built-in keys do not show up in key iterations, but if you access them they do exist.

[wenfangdu]

@yyx990803 It feels a bit inconsistent, here's the screenshot of no expose specified:

Here's with expose: []:

If not by printing child.value.$el explicitly, I'm not able to tell if this object contains built-in properties like $el with expose: [] specified.

[wenfangdu]

@yyx990803 And if I go one level deeper, I still can't see the built-in properties:

[wenfangdu]

@yyx990803 Can we make the built-in properties being printed the same way with/without expose specified?

[smolinari]

[posva]

Exposing methods and properties would be more the norm than the exception, I believe, right?

I would say not: by default, the public API of a component is its props and emitted events. By default, nothing else should be used outside of a component.

That being said, right now non script setup expose everything returned in setup() so I guess they will still expose everything if no expose is used

[smolinari]

I would say not: by default, the public API of a component is its props and emitted events. By default, nothing else should be used outside of a component.

Ok. Yeah. Silly me. Been in the backend world too long. Nevermind then and thanks for the reply.

Scott

[yyx990803]

@posva

That being said, right now non script setup expose everything returned in setup() so I guess they will still expose everything if no expose is used

No, <script setup> is closed by default: https://github.com/vuejs/rfcs/blob/master/active-rfcs/0040-script-setup.md#exposing-components-public-interface

[posva]

yeah, I meant regular script without the setup attribute with non script setup 😆

[yyx990803]

Oh I misread that lol

[yyx990803]

This RFC is now in final comments stage. An RFC in final comments stage means that:

The core team has reviewed the feedback and reached consensus about the general direction of the RFC and believe that this RFC is a worthwhile addition to the framework.
Final comments stage does not mean the RFC's design details are final - we may still tweak the details as we implement it and discover new technical insights or constraints. It may even be further adjusted based on user feedback after it lands in an alpha/beta release.
If no major objections with solid supporting arguments have been presented after a week, the RFC will be merged and become an active RFC.

[bperel]

Really small detail, but there is a typo in 2 of the snippets: export defualt is written instead of export default

[yyx990803]

This RFC has been merged.