29:null 2a:["$","title",null,{"children":"Excess property checking in TypeScript | Daryl Koopersmith | Observable"}] 2f:T882,However, this is an edge case. If an object is passed indirectly (via a variable) or a function uses a type parameter, **TypeScript will not error if the objects have at least one property in common**. This behavior feels counterintuitive when applied to our example: ```ts const propsC = {hello: 'world', id: 'example'}; set(propsC); function ComponentC(): JSX.Element { return

} ``` It also is often counterintuitive when using generic type parameters: ```ts function set(props: T) {} set({hello: 'world', id: 'example'}); ``` **Why doesn’t TypeScript error here?** Common JavaScript patterns often take advantage of indirection and there are legitimate use cases for passing extra properties. A method may act on part of a user object without knowing the full signature of the user object. Libraries often decorate objects with extra properties. When working with React components, this has several negative consequences: * We pass `hello` through to the DOM, which is not a valid property. React throws a warning. * When `hello` changes, we accidentally invalidate a component’s props, causing the component to unintentionally re-render. * We allow users to misspell props without consequence. These misspelled props could lead to subtle bugs, and result in incorrect [cargo-culted](https://en.wikipedia.org/wiki/Cargo_cult) code. [Facebook’s Flow](https://flow.org/) solves this problem by establishing two types of objects: **inexact objects** which allow extra properties, and **exact objects** which only accept a specific set of properties. There’s a longstanding [proposal](https://github.com/microsoft/TypeScript/issues/12936) to add exact objects to TypeScript, but the TypeScript team believes that [improving excess property checking](https://github.com/microsoft/TypeScript/issues/12936#issuecomment-284590083) is the path forward: > *“For the most part where people want exact types, we'd prefer to fix that by making \[excess property checking\] smarter.”* Weak type detection was one such improvement. Five years later, this use case isn’t addressed. Is there anything we can do in the meantime?30:T5f8,**Note that the following techniques can negatively impact your [type checking performance](https://github.com/microsoft/TypeScript/wiki/Performance) because they track additional information at each call site. Use them carefully and [profile your TypeScript project](https://github.com/microsoft/TypeScript/wiki/Performance-Tracing) when in doubt.** To detect excess properties, we can use a [generic type](https://www.typescriptlang.org/docs/handbook/2/generics.html) to compare the actual input against an expected type. Let’s redefine our `set` function to track the actual input using a type parameter, `T`: ```ts function set(props: T) {} ``` This alone won’t detect excess properties (in fact, this suppresses TypeScript’s built-in excess property checks). Next, we need to compare our input `T` to our expected type `Props`. If we find any property that exists in `T` and _doesn’t_ exist in `Props`, we assign it to `never`. This will cause TypeScript to throw an error, because the `never` type is [incompatible with all other types](https://www.typescriptlang.org/docs/handbook/basic-types.html#never). ```ts function set(props: T & { // For every property K in T, if K is also a property in Props, ignore that property. // If the property is in T and isn’t in Props, we found an excess property! Set it to never. [K in keyof T as K extends keyof Props ? never : K]: never; }) {} ``` Let’s try using an object with an excess property with our new `set` method: 31:T8ad,### Recursively detecting excess properties The types above only work for shallow object types. To detect excess properties in deep objects, we need to combine this technique with a technique to generate recursive types. TypeScript’s `Array.flat()` implementation contains a type called [`FlatArray`](https://github.com/microsoft/TypeScript/blob/main/lib/lib.es2019.array.d.ts#L21-L26) which demonstrates a clever technique for creating recursive types. The type uses an object to separate the base case (`"done"`) from the recursive case (`"recur"`) and use a tuple of numbers with their indices offset by 1 to simulate `n - 1`. The resulting types also safely handle optional types and assign any excess properties to a required `never` (ensuring a type failure). Instead of using the [mapped type](https://www.typescriptlang.org/docs/handbook/2/mapped-types.html) to generate the type of the result, we preserve the actual object type (`T &` in `CheckExcessProperties`), add support for autocomplete by redeclaring the expected object type (`Shape &` in `CheckExcessProperties`) and use the base case to mark which properties exist in both the actual and expected types (using `unknown` as a marker). We then skip any property that contains the `unknown` marker to ensure that the resulting type only contains the excess properties that exist in the provided input `T` and _not_ the expected type `Shape`. ```ts export type CheckExcessProperties = T & Shape & ExtractExcessProperties; export type ExtractExcessProperties = { done: unknown; recur: { [K in keyof T]: K extends keyof Required ? T[K] extends object ? ExtractExcessProperties< T[K], Required[K], [-1, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20][Depth] > : unknown : `Excess property: Property \`\${K extends string ? K : string}\` is not defined on this object type.`; } extends infer I ? { [K in keyof I as unknown extends I[K] ? never : K]-?: I[K]; } : never; }[Depth extends 0 ? 'done' : 'recur']; ```32:[] 2d:{"id":"862e2f2f41f7498d","slug":"excess-property-checking-in-typescript","title":"Excess property checking in TypeScript","thumbnail":"627dd47986f0d0e4027aba31ebfc1ede3bde22dcd5061211c4a6497233c80aba","access_level":"public","create_time":"$D2021-10-14T22:34:38.309Z","update_time":"$D2024-07-19T15:42:57.542Z","view_time":null,"first_public_time":"$D2023-01-23T22:32:42.237Z","has_unpublished_edits":null,"fork":false,"stars":1,"starred":false,"owner":{"type":"team","id":"ff12d9058b1837a8","login":"koop","name":"Daryl Koopersmith","avatar_url":"https://avatars-next.observableusercontent.com/abcdba2190856b54f4cdafafdc27685c00415fc74a6eae1ab3279569c5c771a5","tier":"starter_2024"},"version":847,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"05daae4d450d1579","login":"koop","name":"Daryl Koopersmith","avatar_url":"https://avatars-next.observableusercontent.com/abcdba2190856b54f4cdafafdc27685c00415fc74a6eae1ab3279569c5c771a5","tier":null}],"members":[{"type":"individual","id":"05daae4d450d1579","login":"koop","name":"Daryl Koopersmith","avatar_url":"https://avatars-next.observableusercontent.com/abcdba2190856b54f4cdafafdc27685c00415fc74a6eae1ab3279569c5c771a5","tier":null,"role":"editor"}],"comments":[],"custom_thumbnail":false,"trashed":false,"lapsed":null,"subscribed":null,"forks":0,"collection":null,"type":"notebook","body":{"title":"Excess property checking in TypeScript","cells":[{"id":392,"value":"# Excess property checking in TypeScript\n\nTypeScript includes a feature called “excess property checking” which detects and surfaces errors for unexpected properties in objects. This process includes some unintuitive edge cases. Let’s explore them.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":400,"value":"Say we have a type, `Props`, which is an object with an optional `id` and a method to set those props, `set(props)`:\n\n```typescript\ninterface Props {\n id?: string;\n};\n\nfunction set(props: Props) {}\n```","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":508,"value":"section(`Directly setting an unknown property`);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":514,"value":"If we try to pass an object with an unknown property, we get an error:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":559,"value":"squiggles(\n 'typescript',\n `set({hello: 'world'})`,\n {\n 1: [[5, 19]],\n },\n);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":33,"value":"error(\n 'Object literal may only specify known properties',\n md`Argument of type \\`'{ hello: string; }'\\` is not assignable to parameter of type \\`'{ id?: string | undefined; }'\\`.\n Object literal may only specify known properties, and \\`'hello'\\` does not exist in type \\`'{ id?: string | undefined; }'\\`.(2345)`, \n);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":451,"value":"This same process occurs when we create JSX elements:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":555,"value":"squiggles(\n 'typescript',\n `function ComponentA() {\n return

\n}`,\n {\n 2: [[14, 19]],\n },\n);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":455,"value":"error(\n 'Property does not exist on type',\n md`Type \\`'{ hello: string; }'\\` is not assignable to type \\`'DetailedHTMLProps, HTMLDivElement>'\\`.\n Property \\`'hello'\\` does not exist on type \\`'DetailedHTMLProps, HTMLDivElement>'\\`.(2322)`, \n);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":635,"value":"This process is called “[excess property checking](https://www.typescriptlang.org/docs/handbook/interfaces.html#excess-property-checks)” and only applies to object literals:\n\n> *“Object literals get special treatment and undergo excess property checking when assigning them to other variables, or passing them as arguments.”*\n\nLet’s explore what happens when excess property checking *doesn’t* kick in.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":525,"value":"section('Using a variable with no properties in common');","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":462,"value":"When we extract the props to another variable, TypeScript throws an error… but it turns out that this error only applies in a very specific case:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":545,"value":"squiggles(\n 'typescript',\n `const propsB = {hello: 'world'};\n\nset(propsB);\n\nfunction ComponentB(): JSX.Element {\n return

\n}`,\n {\n 3: [[4, 10]],\n 6: [[10, 13]],\n },\n);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":491,"value":"error(\n 'No properties in common',\n md`Type \\`'{ hello: string; }'\\` has no properties in common with type \\`'{ id?: string | undefined; }'\\`.(2559)`, \n);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":580,"value":"error(\n 'No properties in common',\n md`Type \\`'{ hello: string; }'\\` has no properties in common with type \\`'DetailedHTMLProps, HTMLDivElement>'\\`.(2559)`, \n);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":662,"value":"This process is called “[weak type detection](https://github.com/microsoft/TypeScript/pull/3842)” and only applies to objects which have only optional properties (“weak types”). This includes any type created by the [`Partial`](https://www.typescriptlang.org/docs/handbook/utility-types.html#partialtype) utility type. Since these types are exceptionally flexible, TypeScript includes a special error when an object doesn’t overlap with any of the properties in the weak type:\n\n> *“A weak type is one which has only optional properties and is not empty. Because these types are assignable from anything except types with matching non-assignable properties, they are very weakly typechecked. The simple fix here is to require that a type is only assignable to a weak type if they are not completely disjoint.”*\n\nIt turns out that `Props` is a weak type. So what happens when properties *do* overlap?","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":596,"value":"section('Using a variable with at least one property in common');","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":764,"value":"This is where things get confusing. When we directly call `set` with an extra property, TypeScript will detect that property and throw an error:\n\n","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":772,"value":"squiggles(\n 'typescript',\n `set({id: 'example', hello: 'world'})`,\n {\n 1: [[20, 34]],\n },\n);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":768,"value":"error(\n 'Object literal may only specify known properties',\n md`Argument of type \\`'{ hello: string; }'\\` is not assignable to parameter of type \\`'{ id?: string | undefined; }'\\`.\n Object literal may only specify known properties, and \\`'hello'\\` does not exist in type \\`'{ id?: string | undefined; }'\\`.(2345)`, \n);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":597,"value":"$2f","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":698,"value":"section('Detecting excess properties')","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":700,"value":"$30","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":745,"value":"squiggles(\n 'typescript',\n `set({id: 'example', hello: 'world'});`,\n {\n 1: [[20, 25]],\n },\n);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":752,"value":"error(\n `Type 'string' is not assignable to type 'never'.`,\n md`The expected type comes from property \\`'hello'\\` which is declared here on type \\`'{ id: string; hello: string; } & { hello: never; }'\\``,\n);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":787,"value":"This results in a different error than before: one that persists even when we extract the object out to a variable.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":791,"value":"squiggles(\n 'typescript',\n `const propsC = {id: 'example', hello: 'world'};\n\nset(propsC);`,\n {\n 3: [[4, 10]],\n },\n);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":789,"value":"error(\n `Type 'string' is not assignable to type 'never'.`,\n md`Argument of type \\`'{ id: string; hello: string; }'\\` is not assignable to parameter of type \\`'{ id: string; hello: string; } & { hello: never; }'\\`.\n Type \\`'{ id: string; hello: string; }'\\` is not assignable to type \\`'{ hello: never; }'\\`.\n Types of property \\`'hello'\\` are incompatible.\n Type \\`'string'\\` is not assignable to type \\`'never'\\`.(2345)`,\n);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":802,"value":"It even works when we use the same technique in a React component:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":809,"value":"squiggles(\n 'typescript',\n `function Component(props: T & {\n [K in keyof T as K extends keyof Props ? never : K]: never;\n}): JSX.Element {\n return

;\n}\n\n`,\n {\n 7: [[1, 10]],\n },\n);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":816,"value":"error(\n `Type 'string' is not assignable to type 'never'.`,\n md`Argument of type \\`'{ id: string; hello: string; }'\\` is not assignable to parameter of type \\`'{ id: string; hello: string; } & { hello: never; }'\\`.\n Type \\`'{ id: string; hello: string; }'\\` is not assignable to type \\`'{ hello: never; }'\\`.\n Types of property \\`'hello'\\` are incompatible.\n Type \\`'string'\\` is not assignable to type \\`'never'\\`.(2345)`,\n);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":819,"value":"$31","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"","database":"$undefined"},{"id":719,"value":"---\n[*View this code in the TypeScript playground →*](https://www.typescriptlang.org/play?#code/JYWwDg9gTgLgBAKjgQwM5wEoFNkGN4BmUEIcA5FDvmQNwCwAUI8AHYxZQF5ZwAKxYdAG9GcOMAAmAfgBccVDCisA5vQYBfRowIBXFvmAQW8rDAAUYAajn8IggJRyAbhElwhmpgwD03uABFgSnwAGwBPExgYFRRjPQBrFggAd2NLOw4YMMZUUzMhAAssEJCIOTJk6BCJMnV7LQZdfWijOABhEkgWLDYAQTN7d1E4ShgdKGMAHglgJzgikogAXgAiSqhqlbhvAD5GT0ZfOABVVBjkOCdkJWQAIxCeZOAYArgkuHSwTOAsdFY4XAkEBGRiAlgKD5WABCcCW7gWpXK62qtTUOTyn1QUPsaMaegMrQ64CMPRgUIGcgAUgBlAAaADoAKIPECkoYMMSjcZTGZzIT0gWYqHqbZ7DQNI6nc6Xa7AO4POBPF4oeAPNDwEmQjKwCL-QEgYEsUFGCGYtqw+HFRHkZE1AA04gk5SwAA9kOAHqiGrlzGacQ0mgTjESuqS2hS4DSGcysKy2OzOaZuXBprN3AL6WaRbt9kA)","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":13,"value":"---\n### *Definitions*","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"},{"id":0,"value":"import {error, section, squiggles} from '@koop/fiddle';","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W32","stdlib":"1","titling":"auto"}} 2e:"$2d:body"