feat: enhance type inference for useEmitAsProps and useForwardPropsEmits (#2643)

Myshkouski · Alexei Myshkouski · zernonia · web-flow · commit f76c5e132dff · 2026-06-10T21:55:27.000+08:00
* feat(core): add typed return values for useEmitAsProps The useEmitAsProps function now properly types the returned props based on the emit function signature, including support for function overloads. This improves TypeScript type inference and provides better IDE autocomplete for event handlers. - Added generic type parameter Fn for the emit function type - Added type utilities for handling function overloads - Result type now accurately reflects the event handler signatures * feat(core): enhance type inference for useForwardPropsEmits Exported WithOptionalBooleans type utility and added function overloads to properly infer ComputedRef return types based on emit parameter. The overloads accurately reflect whether emits are converted to props. * fix(core): correct CamelCase type conversion for kebab-case strings * fix(core): resolve ToEmit type inference for overloaded functions The previous implementation directly pattern-matched on function signatures, which only works for non-overloaded functions. This change utilizes OverloadSignatureTuple to correctly extract and match overload signatures against the expected emit name, enabling proper type inference for functions with multiple overloads. * docs(core): update ExtendSignature @ts-expect-error explanation Expand the comment to clarify that ExtendSignature intentionally extends generic type T to inherit all overloads for the recursive overload walking algorithm, and warn against removing the suppression as it would break the recursion/bottoming-out logic. * refactor(core): rename UnionToOptional to MergeUnion utility type Rename the UnionToOptional type to MergeUnion to better reflect its purpose of converting a union of function signatures into a single merged object type with optional properties. The implementation remains unchanged, only the type name is updated for improved clarity and maintainability. * refactor(core): replace Function with AnyFn for improved type inference Replace the generic `Function` type with `AnyFn` from `@vueuse/shared` across `useEmitAsProps` and `useForwardPropsEmits` utilities. This change improves type inference and type safety by using a more specific function type constraint instead of the overly broad `Function` type, which provides better IDE autocompletion and catches more type errors at compile time. The runtime behavior remains unchanged. * refactor(core): simplify useEmitAsProps type definitions - add package-private overload types from @vue/shared package - simplify utility types * fix(core): export EmitAsProps type from shared index * fix(core): improve camelCase type conversion to handle all word characters * test(core): add type tests for useEmitAsProps and useForwardPropsEmits Compile-time assertions (validated by vue-tsc via tsconfig.check.json) that lock in the new emit type inference: overloaded, single, and loose emit signatures, plus the props+emit merge of useForwardPropsEmits. The file is type-checked by the existing build job but not run by Vitest or bundled. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Alexei Myshkouski <am@samplify.org> Co-authored-by: zernonia <zernonia@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
diff --git a/packages/core/src/shared/index.ts b/packages/core/src/shared/index.ts
@@ -17,7 +17,7 @@ export { useBodyScrollLock } from './useBodyScrollLock'
 export { useComposing } from './useComposing'
 export { type Formatter, useDateFormatter } from './useDateFormatter'
 export { useDirection } from './useDirection'
-export { useEmitAsProps } from './useEmitAsProps'
+export { type EmitAsProps, useEmitAsProps } from './useEmitAsProps'
 export { useFilter } from './useFilter'
 export { useFocusGuards } from './useFocusGuards'
 export { useFormControl } from './useFormControl'
diff --git a/packages/core/src/shared/useEmitAsProps.test-d.ts b/packages/core/src/shared/useEmitAsProps.test-d.ts
@@ -0,0 +1,77 @@
+/**
+ * Compile-time type tests for `useEmitAsProps` and `useForwardPropsEmits`.
+ *
+ * These assertions are validated by `vue-tsc` (the `type-check` / `build` step):
+ * `tsconfig.check.json` includes `src/**` and only excludes `*.test.ts`, so this
+ * `*.test-d.ts` file is type-checked but is neither executed by Vitest (its glob
+ * is `*.test.{ts,js}`) nor bundled (nothing imports it). A regression in the emit
+ * type inference therefore fails the build.
+ */
+import type { ComputedRef } from 'vue'
+import type { EmitAsProps } from './useEmitAsProps'
+import { useEmitAsProps } from './useEmitAsProps'
+import { useForwardPropsEmits } from './useForwardPropsEmits'
+
+// Assertion helpers
+type Expect<T extends true> = T
+type Equal<A, B>
+  = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false
+
+// Fixtures mirroring the emit shapes Vue produces from `defineEmits`
+type OverloadedEmit = {
+  (e: 'update:modelValue', value: string): void
+  (e: 'change', value: number, extra: boolean): void
+}
+declare const overloadedEmit: OverloadedEmit
+
+type SingleEmit = (e: 'close', reason: string) => void
+declare const singleEmit: SingleEmit
+
+// The loose signature used internally by some components must stay assignable
+type LooseEmit = (name: string, ...args: any[]) => void
+declare const looseEmit: LooseEmit
+
+// useEmitAsProps — overloaded emit maps each event to its `onXxx` handler prop
+{
+  const result = useEmitAsProps(overloadedEmit)
+  type Result = typeof result
+  type _keys = Expect<Equal<keyof Result, 'onUpdate:modelValue' | 'onChange'>>
+  type _update = Expect<Equal<Parameters<NonNullable<Result['onUpdate:modelValue']>>, [value: string]>>
+  type _change = Expect<Equal<Parameters<NonNullable<Result['onChange']>>, [value: number, extra: boolean]>>
+}
+
+// useEmitAsProps — single (non-overloaded) emit
+{
+  const result = useEmitAsProps(singleEmit)
+  type Result = typeof result
+  type _keys = Expect<Equal<keyof Result, 'onClose'>>
+  type _args = Expect<Equal<Parameters<NonNullable<Result['onClose']>>, [reason: string]>>
+}
+
+// useEmitAsProps — loose signature stays accepted (backwards compatibility)
+{
+  const result = useEmitAsProps(looseEmit)
+  void result
+}
+
+// EmitAsProps utility — emit signature to handler props
+type _emitAsProps = Expect<Equal<keyof EmitAsProps<OverloadedEmit>, 'onUpdate:modelValue' | 'onChange'>>
+
+// useForwardPropsEmits — fixtures
+interface DemoProps { foo: string, bar: boolean }
+declare const props: DemoProps
+
+// With emit: forwarded props AND emit-as-props are both present and typed
+{
+  const forwarded = useForwardPropsEmits(props, overloadedEmit)
+  type Value = typeof forwarded extends ComputedRef<infer V> ? V : never
+  type _prop = Expect<Equal<Value['foo'], string>>
+  type _emit = Expect<Equal<Parameters<NonNullable<Value['onChange']>>, [value: number, extra: boolean]>>
+}
+
+// Without emit: only forwarded props, no `on*` handler keys leak in
+{
+  const forwarded = useForwardPropsEmits(props)
+  type Value = typeof forwarded extends ComputedRef<infer V> ? V : never
+  type _noHandlers = Expect<Equal<Extract<keyof Value, `on${string}`>, never>>
+}
diff --git a/packages/core/src/shared/useEmitAsProps.ts b/packages/core/src/shared/useEmitAsProps.ts
@@ -1,19 +1,23 @@
+import type { AnyFn } from '@vueuse/shared'
 import { camelize, getCurrentInstance, toHandlerKey } from 'vue'
 
 // Vue doesn't have emits forwarding, in order to bind the emits we have to convert events into `onXXX` handlers
 // issue: https://github.com/vuejs/core/issues/5917
 /**
  * The `useEmitAsProps` function is a TypeScript utility that converts emitted events into props for a
  * Vue component.
+ *
+ * @template Name - The event name string union type.
+ * @template Fn - The emit function type.
+ *
  * @param emit - The `emit` parameter is a function that is used to emit events from a component. It
+ *
  * takes two parameters: `name` which is the name of the event to be emitted, and `...args` which are
  * the arguments to be passed along with the event.
  * @returns The function `useEmitAsProps` returns an object that maps event names to functions that
  * call the `emit` function with the corresponding event name and arguments.
  */
-export function useEmitAsProps<Name extends string>(
-  emit: (name: Name, ...args: any[]) => void,
-) {
+export function useEmitAsProps<Name extends string, Fn extends AnyFn = AnyFn>(emit: Emit<Name, Fn>) {
   const vm = getCurrentInstance()
 
   const events = vm?.type.emits as Name[]
@@ -28,5 +32,80 @@ export function useEmitAsProps<Name extends string>(
   events?.forEach((ev) => {
     result[toHandlerKey(camelize(ev))] = (...arg: any) => emit(ev, ...arg)
   })
-  return result
+
+  return result as EmitAsProps<Fn>
 }
+
+export type EmitAsProps<T extends AnyFn> = Expand<Partial<MergeUnion<EmitUnion<OverloadUnion<T>>>>>
+
+export type Emit<Name extends string, Fn extends AnyFn> = IsEmit<Name, Fn> extends true ? Fn : never
+
+type IsEmit<Name extends string, Fn extends AnyFn>
+  = OverloadUnion<Fn> extends infer T extends AnyFn
+    ? Parameters<T> extends [name: Name, ...args: any[]]
+      ? [ReturnType<T>] extends [void]
+          ? true
+          : false
+      : false
+    : false
+
+type Expand<T> = {
+  [K in keyof T]: T[K]
+} & {}
+
+type MergeUnion<T> = {
+  [K in T extends any ? keyof T : never]: T extends { [P in K]: any } ? T[K] : never;
+}
+
+type EmitUnion<Fn extends AnyFn>
+  = Fn extends (name: infer Name extends string, ...args: infer Args) => infer Return
+    ? { [K in HandlerKey<Name>]: (...args: Args) => Return }
+    : unknown
+
+// Types for prop keys
+
+type WordChar
+  = | 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm'
+    | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z'
+    | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M'
+    | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z'
+    | '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9'
+    | '_'
+
+/**
+ * Type-safe converter for camelize(string) from Vue package
+ */
+export type Camelize<S extends string>
+  = S extends `${infer Prefix}-${infer Rest}`
+    ? Rest extends `${infer Char}${infer After}`
+      ? Char extends WordChar
+        ? `${Camelize<Prefix>}${Uppercase<Char>}${Camelize<After>}`
+        : `${Camelize<Prefix>}-${Camelize<Rest>}`
+      : S
+    : S
+
+type HandlerKey<Name extends string> = Camelize<`on-${Name}`>
+
+// Package-private overload types from @vue/shared
+
+type OverloadProps<TOverload> = Pick<TOverload, keyof TOverload>
+
+type OverloadUnionRecursive<
+  TOverload,
+  TPartialOverload = unknown,
+> = TOverload extends (...args: infer TArgs) => infer TReturn
+  ? TPartialOverload extends TOverload
+    ? never
+    : | OverloadUnionRecursive<
+            TPartialOverload & TOverload,
+            TPartialOverload
+            & ((...args: TArgs) => TReturn)
+            & OverloadProps<TOverload>
+    >
+    | ((...args: TArgs) => TReturn)
+  : never
+
+type OverloadUnion<TOverload extends (...args: any[]) => any> = Exclude<
+  OverloadUnionRecursive<(() => never) & TOverload>,
+  TOverload extends () => never ? never : () => never
+>
diff --git a/packages/core/src/shared/useForwardProps.ts b/packages/core/src/shared/useForwardProps.ts
@@ -12,7 +12,7 @@ interface PropOptions {
  * in the `defineProps` return type. Since `useForwardProps` only returns props that were
  * explicitly assigned, boolean-typed props should remain optional in the return type.
  */
-type WithOptionalBooleans<T> = {
+export type WithOptionalBooleans<T> = {
   [K in keyof T as [T[K]] extends [boolean] ? K : never]?: T[K]
 } & {
   [K in keyof T as [T[K]] extends [boolean] ? never : K]: T[K]
diff --git a/packages/core/src/shared/useForwardPropsEmits.ts b/packages/core/src/shared/useForwardPropsEmits.ts
@@ -1,4 +1,7 @@
-import type { MaybeRefOrGetter } from 'vue'
+import type { AnyFn } from '@vueuse/shared'
+import type { ComputedRef, MaybeRefOrGetter } from 'vue'
+import type { Emit, EmitAsProps } from './useEmitAsProps'
+import type { WithOptionalBooleans } from './useForwardProps'
 import { computed } from 'vue'
 import { useEmitAsProps } from './useEmitAsProps'
 import { useForwardProps } from './useForwardProps'
@@ -15,7 +18,19 @@ import { useForwardProps } from './useForwardProps'
  * @returns a computed property that combines the parsed
  * props and emits as props.
  */
-export function useForwardPropsEmits<T extends Record<string, any>, Name extends string>(props: MaybeRefOrGetter<T>, emit?: (name: Name, ...args: any[]) => void) {
+export function useForwardPropsEmits<
+  T extends Record<string, any>,
+>(props: MaybeRefOrGetter<T>): ComputedRef<WithOptionalBooleans<T>>
+export function useForwardPropsEmits<
+  T extends Record<string, any>,
+  Name extends string,
+  Fn extends AnyFn = AnyFn,
+>(props: MaybeRefOrGetter<T>, emit: Emit<Name, Fn>): ComputedRef<WithOptionalBooleans<T> & EmitAsProps<Fn>>
+export function useForwardPropsEmits<
+  T extends Record<string, any>,
+  Name extends string,
+  Fn extends AnyFn = AnyFn,
+>(props: MaybeRefOrGetter<T>, emit?: Emit<Name, Fn>) {
   const parsedProps = useForwardProps(props)
   const emitsAsProps = emit ? useEmitAsProps(emit) : {}
 
