types(defineComponent): Stricter Component Type + helpers

[pikax]

closes #7259 #9296

Breaking Changes

This PR causes breaking changes, because the types become more stricter on Component in general, this is necessary to prevent false type safety by preventing the DefineComponent and Component from being any.

Ecosystem

There's companion PRs for the ecosystem

• docs: typescript advanced docs#2577
• WIP: Support for vue type helpers changes test-utils#2242
• WIP: Update to utility types pr language-tools#3731
• WIP types: Add support for vue type helpers router#2039
• types: vue types utilities vuetifyjs/vuetify#18785
• types: fix type error with Vue #9556 vueuse/vueuse#3574

Preliminary work as been done, once 3.5 alpha is released I'll update the PRs to add the alpha as dependency.

I expect Component libraries to be broken, please reach out to me through Discord on #typescript channel, tagging @pikax.

Details

Added the ability to extract the original options which the component was created:

const comp = defineComponent({
  randomOption: 'option',
})
expectType<string>(comp.randomOption)

This will be used to build the component types helpers

Improvements

defineComponent

defineComponent has become more stricter, now is possible to extract component options as they were passed

const comp = defineComponent({ myFoo: { a: 1 } })
comp.myFoo // { a: 1 }

defineAsyncComponent

defineAsyncComponent got it's types improved now correctly exposes it's own type as options and on rendering the innerComponent.

const Comp = defineAsyncComponent(async  ()=> defineComponent( { name: 'myComp'}));

Comp.name // 'AsyncComponentWrapper'
Comp.__asyncResolved // DefineComponent | undefined

defineCustomElement

defineCustomElement improvement on resolving the props for passed components, it should correctly infer props from passed components.

---

Helpers

There's 2 types of helpers introduced, Extract* and Component* , the Extract will extract the original type passed to define the component, the Component will provide the typescript type.

Extract can be used to enhanced the component options, eg: add more props

• ExtractComponentOptions
• ExtractComponentProp
• ExtractComponentSlots
• ExtractComponentEmits
• ComponentProps
• ComponentSlots
• ComponentEmits

ExtractComponentOptions

Extract the original options from the component.

NOTE: It does not work with functional components, because it causes the Generics information to be lost.

const options = {
 props: { foo: String },
 setup(){
   // ...
 }
}

const Comp = defineComponent(options)
expectType<ExtractComponentOptions<typeof Comp>>(options)

ExtractComponentProp

Extracts the object passed to create options or if options are not available it will provide the typescript object definition.

const options = {
 props: { foo: String },
 setup(){
   // ...
 }
}

const Comp = defineComponent(options)
expectType<ExtractComponentProp<typeof Comp>>(options.props)

// if the original options are not provided, eg: Volar or functional components
const Comp = defineComponent((props: { a: 1 }) => () => {})
expectType<ExtractComponentProp<typeof Comp>>({ a: 1 as 1 })
// @ts-expect-error not valid type
expectType<ExtractComponentProp<typeof Comp>>({ a: 2 /* the type is { a: 1 } */ })

ExtractComponentSlots

Extracts original slot options from the component, if no options are available it won't be able to infer them, since slots are not exposed on functional components, that information is lost on defineComponent

const options = {
  slots: {
    default(arg: { msg: string }) {}
  },
  setup() {
    // ...
  }
}

const Comp = defineComponent(options)
expectType<ExtractComponentSlots<typeof Comp>>(options.slots)

ExtractComponentEmits

Extracts original emits options from the component, if no options are available it won't be able to infer them, since emits are not exposed on functional components, that information is lost on defineComponent. You can use ComponentProps to get the runtime type, props on functional components includes on*.

const options = {
  emits: {
    foo: (payload: { bar: number }) => true
  },
  setup() {
    // ...
  }
}

const Comp = defineComponent(options)
expectType<ExtractComponentEmits<typeof Comp>>(options.emits)

ComponentProps

Provides the typescript representation of component props, it appends emits props by default.

const options = {
  props: { foo: String },
  setup() {
    // ...
  }
}

const Comp = defineComponent(options)
expectType<{
  foo?: string | undefined
}>({} as ComponentProps<typeof Comp>)

// with emits
const optionsEmits = {
  props: { modelValue: String },
  emits: {
    'update:modelValue': (payload: string) => true
  },
  setup() {
    // ...
  }
}

const Comp = defineComponent(optionsEmits)
expectType<{
  foo?: string | undefined
  'onUpdate:modelValue'?: (payload: string) => void
}>({} as ComponentProps<typeof Comp>)

// exclude emits
const a = {} as ComponentProps<typeof Comp, true>
// @ts-expect-error
a['onUpdate:modelValue']

ComponentSlots

const optionsSlots = {
  slots: {} as {
    test: (payload: string) => any
  },
  setup() {
    // ...
  }
}

const Comp = defineComponent(optionsSlots)

expectType<{
  test: (payload: string) => any
}>({} as ComponentSlots<typeof Comp>)

ComponentEmits

DeclareComponent

DeclareComponent is an helper to create Vue components through types without needing to pass 16 arguments to the type.

It contains 5 arguments:

export type DeclareComponent<
  Props extends Record<string, any> | { new (): ComponentPublicInstance } = {},
  Data extends Record<string, any> = {},
  Emits extends EmitsOptions = {},
  Slots extends SlotsType = {},
  Options extends Record<PropertyKey, any> = {},
>

Props

It allows to pass just props object or a new Component generic, if a component is passed it will short-circuit the type.

Data

Data exposed publicly when using template :ref.

Options

Allowing to Provide custom properties to the Options object.

[github-actions]

Size Report

Bundles

File	Size	Gzip	Brotli
runtime-dom.global.prod.js	89.3 kB	34 kB	30.6 kB
vue.global.prod.js	146 kB	53.2 kB	47.6 kB

Usages

Name	Size	Gzip	Brotli
createApp	49.7 kB	19.5 kB	17.8 kB
createSSRApp	53 kB	20.8 kB	19 kB
defineCustomElement	52 kB	20.2 kB	18.4 kB
overall	63.2 kB	24.4 kB	22.2 kB

[vue-bot]

📝 Ran ecosystem CI: Open

suite	result	latest scheduled
language-tools	❌ failure	❌ failure
nuxt	❌ failure	✅ success
pinia	✅ success	✅ success
quasar	✅ success	✅ success
router	❌ failure	✅ success
test-utils	❌ failure	✅ success
vant	✅ success	✅ success
vite-plugin-vue	❌ failure	✅ success
vitepress	✅ success	✅ success
vue-i18n	✅ success	✅ success
vue-macros	❌ failure	❌ failure
vuetify	❌ failure	❌ failure
vueuse	❌ failure	✅ success
vue-simple-compiler	✅ success	✅ success

[jd-solanki]

Will this help resolve question I asked? unovue/shadcn-vue#277

Thanks for TS Magic 🪄

[pikax]

Will this help resolve question I asked? radix-vue/shadcn-vue#277

@jd-solanki no, the issue you linked is related with the vue compiler being able to infer props like that, bear in mind the compiler must know all the available props ahead of time ,to be able to generate the vue props object. When you extend or implement the type might lose that information.

[sadeghbarati]

@pikax Hey!

Please check the Svelte type helpers ComponentProps, and ComponentType in this source

https://github.com/wobsoriano/svelte-sonner/blob/main/src/lib/types.ts#L30C2-L31C51

What is the equivalent of this source with your Vue type helpers?

Thanks and sorry for tag 🙏

[pikax]

@sadeghbarati what type are you looking for, the two lines you sent one is the component and the other is props, we have:

• Component is ComponentType
• ComponentProps is ComponentProps

[sadeghbarati]

@pikax

I have something like this in Vue to get props, I have to use typeof keyword in ComponentProps right? but it doesn't work in types

export type ToastT<T extends Component = Component> =  {
  component?: T; // T is Vue component but how to get types without typeof 
  componentProps?: ComponentProps<typeof T>; // 'T' only refers to a type, but is being used as a value here.
}

Please take a look at svelte-sonner

• https://github.com/wobsoriano/svelte-sonner/blob/main/src/lib/state.ts
• https://github.com/wobsoriano/svelte-sonner/blob/main/src/lib/types.ts

[daaanny90]

Hey! Any news on this? It would be cool to use and test generics! Without this merge, vuejs/test-utils#2254 cannot be closed, and we cannot really use generics. Can I help in some way to move this forward?