From 6785194c5106efc52496d1a4f65eeb24c3aaf140 Mon Sep 17 00:00:00 2001
From: Tempo <wjs-tech@users.noreply.github.com>
Date: Sun, 20 Sep 2026 11:42:18 +0800
Subject: [PATCH] docs(typescript): clarify excess property checks in
 computed<T>() typing

A generic argument such as computed<Foo>(...) only requires the getter's return value to be assignable to Foo. Because TypeScript does not run excess property checks when inferring into a generic, returning an object with extra properties is silently allowed.

Add a tip to the Typing computed() section showing the loose generic behavior, the stricter return-type-annotation alternative, and the satisfies operator as a concise way to enforce an exact shape.

close #3286
---
 src/guide/typescript/composition-api.md | 35 +++++++++++++++++++++++++
 1 file changed, 35 insertions(+)

diff --git a/src/guide/typescript/composition-api.md b/src/guide/typescript/composition-api.md
index 26fc38e2b5..6b161234d0 100644
--- a/src/guide/typescript/composition-api.md
+++ b/src/guide/typescript/composition-api.md
@@ -311,6 +311,41 @@ const double = computed<number>(() => {
 })
 ```
 
+::: tip Note
+A generic argument like `computed<Foo>(...)` only requires the getter's return value to be *assignable* to `Foo`. Because TypeScript does not run excess property checks when inferring into a generic, returning an object with extra properties won't be flagged:
+
+```ts
+interface Foo {
+  foo: boolean
+}
+
+// no error: the extra `bar` property is silently allowed
+const loose = computed<Foo>(() => ({
+  foo: true,
+  bar: 'oops'
+}))
+```
+
+Annotate the getter's return type instead if you want stricter checking that rejects extra properties:
+
+```ts
+// TS Error: Object literal may only specify known properties
+const strict = computed((): Foo => ({
+  foo: true,
+  bar: 'oops'
+}))
+```
+
+You can also use the `satisfies` operator to keep the concise style while still enforcing an exact shape:
+
+```ts
+const exact = computed(() => ({
+  foo: true,
+  bar: 'oops' // TS Error
+}) satisfies Foo)
+```
+:::
+
 ## Typing Event Handlers {#typing-event-handlers}
 
 When dealing with native DOM events, it might be useful to type the argument we pass to the handler correctly. Let's take a look at this example: