Class API

[yyx990803]

This is a reference of the current implemented version and open to discussion.

Update: don't know since when but latest Chrome Canary now enables class fields by default, so we can already play with the following API without a transpiler.

Plain ES usage:

import { h, Component } from '@vue/renderer-dom'

class App extends Component {
  static props = {
    msg: String
  }

  // data
  count = 0

  // lifecycle
  created() {
    console.log(this.count)
  }

  // getters are converted to computed properties
  get plusOne() {
    return this.count + 1
  }
  
  // a method
  increment() {
    this.count++
  }

  render(props) {
    return h('div', [
      h('span', this.count),
      h('span', props.msg,
      h('button', {
        // methods are auto-bound when they are accessed via the render proxy
        onClick: this.increment
      }, 'increment')
    ])
  }
}

TS Usage:

import { h, Component, ComponentWatchOptions } from '@vue/renderer-dom'

interface Props {
  msg: string
}

interface Data {
  count: number
}

class App extends Component<Props, Data> {
  static props = {
    msg: String
  }
  
  // data fields
  count: number = 0

  // ComponentWatchOptions type is only needed if `this` inference
  // is needed inside options, e.g. in watch callbacks
  static watch: ComponentWatchOptions<App> {
    count(value) {
      console.log(value)
    }
  }

  created() {
    console.log(this.count)
  }

  get plusOne() {
    return this.count + 1
  }

  increment() {
    this.count++
  }

  render(props) {
    // ...
  }
}

[znck]

import { h, Component } from '@vue/renderer-dom'

Doesn't using h and Component from '@vue/renderer-dom' couples component to one renderer?

[phanan]

open question: should we rename them to onXxx to differentiate from methods?

I'm all for it. Even for v2.0 and below (where methods are contained within their own object obviously), I always find myself itching for the convention. Another approach might be to use the denoting $ (though I'm not leaning toward this because it looks a tad ugly).

EDIT: But then again, users can add onXxx methods on their own e.g. event handlers, so on on its own (heh, pun intended) might not cut it.

[yyx990803]

@znck h is just re-exported from @vue/core for convenience. It works regardless of render target. You can also import it from @vue/core.

[phanan]

// getters are converted to computed properties

While it's convenient (and I like the syntax), is it always the expected behavior?

[yyx990803]

@phanan as long as we document this.

[kazupon]

open question: should we rename them to onXxx to differentiate from methods?

IMO, we should not change the lifecycle method names in v3, because of we should be avoided migration fatigue to v3 from v2 as possible, however, as official blog mentioned, we will plan to support about the compatible features for 2.x, so I think It maybe not much of the problem.

Additionally If we will be able to support the migration tool, it's wonderful.

[phanan]

because of we should be avoided migration fatigue to v3 from v2 as possible, however, as official blog mentioned, we will plan to support about the compatible features for 2.x

While I hear this, we might as well keep in mind that these kinds of backward API changes can only be introduced with major versions, which means if we don't take this opportunity, we'll have to wait for v4 (another 2 years perhaps?) 😄

[chrisvfritz]

static options: ComponentOptions<App> = {

To me, it looks very hacky to keep some options top-level and some under an options field. Is there a way we can keep everything top-level? E.g.:

static props: ComponentProps<App> = {
  // ...
}

App.options = options

This pains me. 😅 Since we're relying on a stabilized class API for Vue 3, why can't we use static field declarations for the non-TS version as well? E.g.:

static props = {
  // ...
}

props: {
msg: String
}

This probably isn't possible or would come with too many edge cases, but in TS, I think it'd be great if we could avoid defining types twice for each prop. Is there possibly some way (e.g. with a fancy TS compiler option) that we could access TS type info at runtime in development?

should we rename them to onXxx to differentiate from methods?

I agree with @kazupon in this instance. We already have a nice convention for lifecycle methods that differentiate them from methods: either past tense verb, or before + imperative verb. Changing to onXxx would increase confusion I think, since I currently see a lot of methods use that convention (e.g. onRowHover, onButtonClick) - even though I personally find it to be an anti-pattern in most cases (I think we should describe what we're doing in the method name, not when we happen to call it).

we might as well keep in mind that these kinds of backward API changes can only be introduced with major versions

@phanan I agree with this, but I still think there has to be significant benefit if we're going to force users to relearn something.

[Jinjiang]

we might as well keep in mind that these kinds of backward API changes can only be introduced with major versions

The naming difference could be adapted through createComponentClassFromOptions(options) in https://github.com/vuejs/vue-next/blob/ba62deb5d938c43c41ec5e7686dc006a91d809b8/packages/core/src/componentUtils.ts#L170 I guess, fine for v2 component options.

I think it'd be great if we could avoid defining types twice for each prop.

Agree.

[yyx990803]

@chrisvfritz static class fields are not in the spec yet. Currently in plain ES you can only do static getters.

Is there a way we can keep everything top-level?

Maybe. Having the options as an object is easier for compatibility reasons. Making them flat involves extracting these flat properties back into an object for easier reflection.

I think it'd be great if we could avoid defining types twice for each prop.

This is unlikely because the static types and the options serve slightly different purposes:

1. The options performs runtime checking which is more meaningful for component consumers instead of authors. It also can contain things like required: true, custom validators and default values, which cannot be expressed in the interface.

2. On the other hand, the interface allows for more intricate typing constraints (e.g. object shapes) that cannot be easily expressed through the options.

[yyx990803]

Edit: changed options to be flat static properties on the class

[HerringtonDarkholme]

open question: should we rename them to onXxx to differentiate from methods?

IMO, we should not change the lifecycle method names in v3, because of we should be avoided migration fatigue to v3 from v2 as possible.

From the perspective of vue-class-component, builtin lifecycle names haven't caused many problems or confusion. On the other hand onXXX as @chrisvfritz has said is used widely by users.

---

Computed properties can also have a lazy option. But it looks like Vue 3 will make computed lazy by default. https://github.com/vuejs/vue-next/blob/bf38fea31388dd8c3a2f4206221089a2ed92e841/packages/observer/src/computed.ts#L9
So we don't need the lazy option any, do we?

[chrisvfritz]

static class fields are not in the spec yet. Currently in plain ES you can only do static getters.

@yyx990803 I might have misunderstood, but I thought we were waiting to release Vue 3 until class features had stabilized. Field declarations and static class fields are both stage 3 right now, so I was assuming we'd be able to rely on them by the time of release.

To me, field declarations (both static and instance-based) are an absolutely essential feature of any class API from a DX perspective - and for the record, these are the only existing class proposals I feel that way about. Beyond breaking the logical options order we've recommended for readable components, tacking on extra properties after the initial definition is hacky enough that I think it'd become impossible to sell classes as an improvement.

We're already going to get a lot of pushback from people who prefer the object-based API. It's so simple and well-organized that outside of TS, it's rare to hear anything but praise for it. That means probably most users will feel threatened initially, because they'll see classes as a step towards deprecating the object-based API they love (and their assumption is probably accurate). For that reason, I feel like the experience has to be at least as good with classes.

[yyx990803]

@chrisvfritz

Ideally, we want to wait until class fields become part of the spec before releasing 3.0. I'm thinking somewhere around mid 2019, and with them being currently stage 3, it's unlikely for them to make it into ES2019. However, it's hopeful that they are stage 4 around that point, and that would be safe enough to recommend usage via transpilers (which most serious users will still need, for the time being). If we've reached a day where most users are shipping non-transpiled code, I'm pretty sure class fields would have landed by then.

Also, we can actually make static getters work:

class Foo extends Component {
  static get props() {
    return {
      msg: String
    }
  }
}

Finally, we are not going to deprecate object-based syntax in 3.x, those who prefer it can keep using it. As I said, this is the less "feeling threatened" way to look at it: Components have always been internally represented as classes, even in 2.x (as function constructors). We are just converting options objects into classes. However, in 2.x there's no way to directly author this internal class using the class syntax. 3.0 provides a way to do that, while still keeping the option to use objects.

Note that while there are users who strongly prefer the object syntax, there are other users who strongly prefer the class-based syntax too (especially for users coming from languages where class is the norm). Shying away from classes essentially sacrifices the DX for the class-preferring group where the only benefit is making the object-preferring group feel "comfortable" or "safe".