New way to define `props` and `emits` options

[ktsn]

There is an alternative idea here. Feedback welcome!

Summary

• To provide props and emits helper function to define corresponding component options in class syntax with type safety.

import { props, emits, mixins } from 'vue-class-component'

// Define component props.
// Props is a class component mixin.
const Props = props({
  value: {
    type: Number,
    required: true
  }
})

// Define component emits.
// Emits is a class component mixin.
const Emits = emits({
  input: (value) => typeof value === 'number'
})

// Use the above options by extending them.
export default Counter extends mixins(Props, Emits) {
  mounted() {
    console.log(this.value)
    this.$emit('input', 10)
  }
}

Motivation

We need additional helpers to define props and emits because there are no corresponding concepts in class syntax. You can define them via @Options decorator, but the problem of the decorator approach is that it does not properly type the component type.

@Options({
  props: ['value'],
  emits: ['input']
})
class MyComp extends Vue {
  mounted() {
    this.value // -> type error
    this.$emit('change', 10) // -> no type error (expecting an error)
  }
}

Because props and emits options modify the existing component types $props and $emit, and has runtime declaration (validator, default, etc.) in addition to types, we have to define them as a super class (mixins).

Details

To provide props and emits function. They receive as the same value as component props and emits options.

import { props, emits } from 'vue-class-component'

// prop names
props(['foo', 'bar'])

// props options object
props({
  count: {
    type: Number,
    required: true,
    validator: (value) => {
      return value >= 0
    }
  }
})

// event names
emits(['change', 'input'])

// emits options object
emits({
  input: (value) => typeof value === 'number'
})

They return a class component mixin so that you can use them with mixins helper function:

import { props, emits, mixins } from 'vue-class-component'

// Define props and emits
const Props = props(['value'])
const Emits = emits(['input'])

// Use props and emits definition by extending them with mixins helper
class MyComp extends mixins(Props, Emits) {
  mounted() {
    console.log(this.value)
    this.$emit('input', 10)
  }
}

As they are just Vue constructors, you can just extend it if there are no other mixins to extend:

import { props } from 'vue-class-component'

// Define props
const Props = props(['value'])

// Just extending Props
class MyComp extends Props {
  mounted() {
    console.log(this.value)
  }
}

Why not decorators?

There has been an approach to define props with ES decorators.

@Component
class App extends Vue {
  @prop({ type: Number }) value
}

But the decorator approach has several issues unresolved yet as stated in abandoned Class API RFC for Vue core. Let's bring them here and take a closer look:

• Generic argument still requires the runtime props option declaration - this results in a awkward, redundant double-declaration.

  Since decorators do not modify the original class type, we cannot type $props type with them:

  class MyComp extends Vue {
    @prop value: number
  
    mounted() {
      this.value // number
      this.$props.value // *error
    }
  }

  To properly type props, we have to pass a type parameter to the super class which is a redundant type declaration.

  // 1. Types for $props
  interface Props {
    value: number
  }
  
  class App extends Vue<Props> {
    // 2. props declaration
    @prop value: number
  }

• Using decorators creates a reliance on a stage-2 spec with a lot of uncertainties, especially when TypeScript's current implementation is completely out of sync with the TC39 proposal.

  Although the current decorators proposal is stage 2, TypeScript's decorator implementation (experimentalDecorators) is still based on stage 1 spec. The current Babel decorator (@babel/plugin-proposal-decorators) is based on stage 2 but there is still uncertainty on the spec as the current spec (static decorator) is already different from the original stage 2 proposal (there is a PR to add this syntax in Babel), and also there is another proposal called read/write trapping decorators due to an issue in the static decorators.

  Vue Class Component already uses decorators syntax with @Component (in v8 @Options) but it would be good not to rely on it too much in a new API because of its uncertainty and to reduce the impact of potential breaking changes in the future when we adapt Vue Class Component with the latest spec.

• In addition, there is no way to expose the types of props declared with decorators on this.$props, which breaks TSX support.

  This is similar to the first problem. The Vue component type has Props type parameter that TSX uses for checking available props type. For example, let's say your component has a type { value: number } as the props type, then the component type is Component<{ value: number }> (this is different from the actual Vue type but you can get the idea from it). TSX knows what kind of value should be passed for the component:

  // MyComp type is `Component<{ value: number }>`
  import { MyComp } from './Counter.vue'
  
  <MyComp value={42} /> // Pass the compilation as the value type matches with the prop type
  <MyComp value={'Hello'} /> // Produce a type error as the value is different from the prop type

  It is impossible to define the props type like the above with decorators because decorators cannot intercept the original class types.

  // MyComp type is fixed with Component<{}>, even though there is @prop decorator!
  class MyComp extends Vue {
    @prop value: number
  }

  The above class component can have the property value of type number but it is not defined as props but just a normal property on the type level. Therefore, the component type is like Component<{}> which TSX cannot know about the props.

[Mikilll94]

@ktsn
It would be nice to add also some support/helper function/whatever for watch. Because right now vue-class-component is lacking support for watch.

[zischler]

@ktsn Am I still able to use @Options somehow with this way? Or how am I going to define watchers for example for components using props defined with mixins?

[ktsn]

@zischler You can still use @Options as the current way.

[Mikilll94]

@ktsn
I am also curious how to use "watch" in vue-class-component. I understand that you can put watch in the @Options decorator and use it just like without class syntax. But using it this way you cannot access methods. You can access data via $data and props via $props. But how to access methods?

The docs are also not very helpful. They is no information about watch in the docs

Here is the related issue:
#442

I was also asking about this problem on Vue forum, but I received no answer.

[ktsn]

@Mikilll94

You can still access methods in watch option, can't you...? If you are talking about the usage with TypeScript.

@Option<App>({
  watch: {
    value() {
      this....
    }
  }
})
class App extends Vue {}

Or just use $watch:

class App extends Vue {
  created() {
    this.$watch(() => this..., () => {
      // ...
    })
  }
}

I'm going to hide this comment soon as it's off-topic with this thread.

[zischler]

@ktsn I'm currently trying something like this and it doesn't seem to work. (My linter also gives errors)
Is there something I'm doing wrong? (I can't extend Vue, because I need to extend the props mixin)

const Props = props({
    someProp: {
        type: Number,
        default: 100,
        required: false,
    },
})

@Options<Carousel>({
    watch: {
        this.swipe.hasCursorDown() {
            this.hasCursorDown = !this.hasCursorDown;
        }
    }
})
export default class Carousel extends mixins(Props) {
    swipe = new Swipe();
    hasCursorDown = false;
    .
    .
    .

[ktsn]

@zischler Please open a new issue with a reproduction for a bug report. Thank you.

[Mikilll94]

@ktsn
Thanks. I was struggling with this from a very long time 👍

I didn't know that @Options decorator (or @Component in previous version) accepts a generic type. This is completely not documented and many developers probably don't know about this.

[LifeIsStrange]

I would like to know what other devs are thinking about the pain points I explain here ?
#456

[nicolidin]

I agree that :

(Vue 3 : class-component)

const Props = props({
  firstProp: {
    type: Number,
    required: true
  },
  secondProp: {
    type: Number,
    required: true
  }
})

export default Counter extends mixins(Props, Emits) {

}

---

(Vue 2 class-component + property-decorator)

export default Counter extends Vue {
  @Prop() firstProp!: number;
  @Prop() secondProp!: number;
}

indeed the new Vue version is so much more verbose, less readable, less understandable, and of course less intuitive and less logical for a TypeScript Developer.
`

[ktsn]

@nicolidin

These snippets are unfair to compare. The equivalent props settings are:

const Props = props({
  firstProp: Number,
  secondProp: Number
})

export default Counter extends Props {}

vs.

export default Counter extends Vue {
  @Prop() 
  firstProp?: number

  @Prop()
  secondProp?: number
}

As for verbosity, I don't think there is much difference between the two approaches. You eventually need the same props options if you want to define your props in detail. Rather, I think the decorator approach is slightly more verbose as we have to write @Prop for every occurrence of prop definition while the mixin approach lets us write props once.

I'm curious what aspects of this proposal makes you feel less readable, less understandable, less intuitive and less logical? By using props helper, the definition of props become a separate block which is clearer where the props definition is. Also, it is property typed with actual props definition while the decorator approach can be wrong as we technically can set arbitrary type for the property of @Prop which the former is more logical for me.