{"id":6443,"date":"2025-07-03T09:47:14","date_gmt":"2025-07-03T14:47:14","guid":{"rendered":"https:\/\/frontendmasters.com\/blog\/?p=6443"},"modified":"2025-07-03T09:47:15","modified_gmt":"2025-07-03T14:47:15","slug":"satisfies-in-typescript","status":"publish","type":"post","link":"https:\/\/frontendmasters.com\/blog\/satisfies-in-typescript\/","title":{"rendered":"Satisfies in TypeScript"},"content":{"rendered":"\n

This is a post about one of TypeScript’s less common features: the satisfies<\/code> keyword. It’s occasionally incredibly useful, and knowing how to properly wield it is a valuable trick to have up your sleeve. Let’s take a look!<\/p>\n\n\n\n

A quick intro on structural typing<\/h2>\n\n\n\n

In a nutshell, structural typing means that TypeScript cares only about the structure<\/em> of your values, not the types they were declared with. That means the following code contains no errors:<\/p>\n\n\n

class<\/span> Thing1 {\n  name: string<\/span> = \"\"<\/span>;\n}\n\nclass<\/span> Thing2 {\n  name: string<\/span> = \"\"<\/span>;\n}\n\nlet<\/span> thing1: Thing1 = new<\/span> Thing1();\nlet<\/span> thing2: Thing1 = new<\/span> Thing2();\nlet<\/span> thing3: Thing1 = { name: \"\"<\/span> };<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Types are essentially contracts, and TypeScript cares only that you satisfy the contract with something that has what the original type specified.<\/p>\n\n\n\n
Interestingly, this also means you can supply extraneous, superfluous “stuff” when satisfying types: the following also has no errors.<\/p>\n\n\n
const<\/span> val = {\n  name: \"\"<\/span>,\n  xyz: 12<\/span>,\n};\n\nlet<\/span> thing4: Thing1 = val;<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
The Thing1<\/code> type only calls for a name<\/code> property that’s a string<\/code>. If you also specify other<\/em> properties, TypeScript is (usually) OK with it. This might seem surprising coming from other languages, but it’s a pragmatic tradeoff given that TypeScript’s primary purpose is to provide some manner of type safety to a completely untyped programming language: JavaScript.<\/p>\n\n\n\n
I said usually<\/em> above because occasionally TypeScript will be a bit stricter about not allowing “extra” values like we saw above. In particular, when assigning an object literal to a variable that’s declared with a type, TypeScript will require a strict matching.<\/p>\n\n\n
let<\/span> thing4: Thing1 = val;\n\nconst<\/span> val2: Thing1 = {\n  name: \"\"<\/span>,\n  xyz: 12<\/span>,\n  \/\/ Error: Object literal may only specify known properties, and 'xyz' does not exist in type 'Thing1'<\/span>\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
This is called “excess property checking.” It happens when assigning an object literal to a variable with a declared type, like we just saw, and also when passing an object literal to a function parameter that has a declared type.<\/p>\n\n\n\n
The satisfies<\/code> keyword<\/h2>\n\n\n\n
To provide the most simplistic example of using satisfies<\/code>, let’s go back to this code<\/p>\n\n\n
const<\/span> val3 = {\n  name: \"\"<\/span>,\n  xyz: 12<\/span>,\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Right now val3<\/code> has the inferred type<\/p>\n\n\n
{\n  name: string<\/span>;\n  xyz: number<\/span>;\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
If we wanted, we could write this code like this:<\/p>\n\n\n
const<\/span> val3 = {\n  name: \"\"<\/span>,\n  xyz: 12<\/span>,\n  \/\/ Error: Object literal may only specify known properties, and 'xyz' does not exist in type 'Thing1'<\/span>\n} satisfies Thing1;<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
That produced the same error we saw before, and the same error we would have<\/em> gotten if we had declared val3<\/code> as Thing1<\/code>.<\/p>\n\n\n
const<\/span> val3: Thing1 = {\n  name<\/span>: \"\"<\/span>,\n  xyz<\/span>: 12<\/span>,\n  \/\/ Error: Object literal may only specify known properties, and 'xyz' does not exist in type 'Thing1'<\/span>\n};<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
The satisfies<\/code> keyword allows you to assert that a certain value “satisfies” a given type, while preventing<\/em> a wider type from being inferred.<\/p>\n\n\n\n
Bear with me.<\/p>\n\n\n\n
You’re probably thinking that this is completely pointless, since we can just move Thing1<\/code> up into a proper type declaration, and even save a few keystrokes while doing so!<\/p>\n\n\n\n
But not all situations lend themselves to this solution.<\/p>\n\n\n\n
Let’s take a look at a slightly more complex, more realistic example.<\/p>\n\n\n\n
The satisfies<\/code> Keyword in the Wild<\/h2>\n\n\n\n
This is a situation I actually ran into. I’ll do my best to simplify it, while keeping the realistic parts.<\/p>\n\n\n\n
Imagine we’re writing an inventory management system. We have an inventory item type.<\/p>\n\n\n
type<\/span> InventoryItem = {\n  sku: string<\/span>;\n  description: string<\/span>;\n  originCode?: string<\/span>;\n};<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Maybe we have some external backend systems we need to fetch data from.<\/p>\n\n\n
type<\/span> BackendResponse = {\n  item_sku: string<\/span>;\n  item_description: string<\/span>;\n  item_metadata: Record<string<\/span>, string<\/span>>;\n  item_origin_code: string<\/span>;\n};\n\nfunction<\/span> getBackendResponse<\/span>(<\/span>): BackendResponse<\/span>[] <\/span>{\n  return<\/span> [];\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
The getBackendResponse<\/code> function is hard coded to return an empty array, but just pretend it makes a request and returns actual data. Then pretend we want to take that data and actually insert it. We have a function to do the inserting; we’re only interested in the types though, so we’ll leave the implementation empty<\/p>\n\n\n
function<\/span> insertInventoryItems<\/span>(items: InventoryItem[]<\/span>) <\/span>{}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Let’s put things together. Fetch some items from our external system, manipulate them into the proper structure for our own InventoryItem<\/code> type, and then call our insertInventoryItems<\/code> function<\/p>\n\n\n
function<\/span> main<\/span>(<\/span>) <\/span>{\n  const<\/span> backendItems = getBackendResponse();\n  insertInventoryItems(\n    backendItems.map(item<\/span> =><\/span> {\n      return<\/span> {\n        sku<\/span>: item.item_sku,\n        description<\/span>: item.item_description,\n        originCodeXXXXX<\/span>: item.item_origin_code,\n      };\n    })\n  );\n}<\/code><\/span>Code language:<\/span> JavaScript<\/span> (<\/span>javascript<\/span>)<\/span><\/small><\/pre>\n\n\n
Unfortunately, this code has no errors<\/strong>, even though we completely fat-fingered the originCode<\/code> property. <\/p>\n\n\n\n
You already know that TypeScript will allow you to provide “extra” properties in places where excess property checking doesn’t exist, but you may be wondering why it’s not an error that we completely left off<\/em> the real originCode<\/code> property. The reason is that this is an optional property! That makes it all the more important that we disallow excess cruft.<\/p>\n\n\n\n
You might be thinking that we can just restructure our code so that excess property checking is in place, and we certainly could do that<\/p>\n\n\n
function<\/span> main<\/span>(<\/span>) <\/span>{\n  const<\/span> backendItems = getBackendResponse();\n  insertInventoryItems(\n    backendItems.map(item<\/span> =><\/span> {\n      const<\/span> result: InventoryItem = {\n        sku: item.item_sku,\n        description: item.item_description,\n        originCodeXXXXX: item.item_origin_code,\n        \/\/ Error: Object literal may only specify known properties, but 'originCodeXXXXX'<\/span>\n        \/\/ does not exist in type 'InventoryItem'. Did you mean to write 'originCode'<\/span>\n      };\n      return<\/span> result;\n    })\n  );\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
This works and produces the error we want to see. But it’s just a byproduct of the (frankly weird) way we chose to write it, and this protection would disappear if anyone were to come along, see this weird, pointless intermediate variable declaration, and “helpfully” refactor the code to just immediately return the object literal like we just had.<\/p>\n\n\n\n
The better solution is to use satisfies<\/code> to prevent the unwanted widening; that’s why it exists!<\/p>\n\n\n
function<\/span> main<\/span>(<\/span>) <\/span>{\n  const<\/span> backendItems = getBackendResponse();\n  insertInventoryItems(\n    backendItems.map(item<\/span> =><\/span> {\n      return<\/span> {\n        sku: item.item_sku,\n        description: item.item_description,\n        originCodeXXXXX: item.item_origin_code,\n        \/\/ Error: Object literal may only specify known properties, but 'originCodeXXXXX'<\/span>\n        \/\/ does not exist in type 'InventoryItem'. Did you mean to write 'originCode'<\/span>\n      } satisfies InventoryItem;\n    })\n  );\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
Now we’re back to the more idiomatic code we started with, with the same strict checks we’re looking for.<\/p>\n\n\n\n
Before we wrap up, let’s briefly consider this alternative you might be wondering about<\/p>\n\n\n
function<\/span> main<\/span>(<\/span>) <\/span>{\n  const<\/span> backendItems = getBackendResponse();\n  insertInventoryItems(\n    backendItems.map(item<\/span> =><\/span> {\n      return<\/span> {\n        sku: item.item_sku,\n        description: item.item_description,\n        originCodeXXXXX: item.item_origin_code,\n      } as<\/span> InventoryItem;\n    })\n  );\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
This produces no errors at all. The as<\/code> keyword is a typecast. It’s something to avoid; it essentially allows you to “lie” to the type checker and assert<\/em> that a given expression matches a given type. In this case, the cast pointless because this object already matches the InventoryItem<\/code> type. It has a sku, and a description. It also has some extra “stuff” but TypeScript doesn’t really mind. It’s the satisfies<\/code> keyword which additionally forces TypeScript to also not<\/em> allow a wider type, and therefor start<\/em> minding about extra properties.<\/p>\n\n\n\n
For completeness, this version of the casting code actually does fail<\/p>\n\n\n
function<\/span> main3<\/span>(<\/span>) <\/span>{\n  const<\/span> backendItems = getBackendResponse();\n  insertInventoryItems(\n    backendItems.map(item<\/span> =><\/span> {\n      return<\/span> {\n        sku: item.item_sku,\n        descriptionXXX: item.item_description,\n        \/\/ Error: Conversion of type '{ sku: string; descriptionXXX:<\/span> string; originCodeXXXXX:<\/span> string; }' to type<\/span>\n        \/\/ 'InventoryItem' may be a mistake because neither type sufficiently overlaps with the other. If this<\/span>\n        \/\/ was intentional, convert the expression to 'unknown' first. Property 'description' is missing in type<\/span>\n        \/\/ '{ sku: string; descriptionXXX:<\/span> string; originCodeXXXXX:<\/span> string; }' but required in type 'InventoryItem'.<\/span>\n        originCodeXXXXX: item.item_origin_code,\n      } as<\/span> InventoryItem;\n    })\n  );\n}<\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
TypeScript will allow you to lie, but only so far. If the cast makes absolutely no sense, TypeScript won’t allow it. As the error indicates, if you, for some reason, actually wanted to go through with this code, you could do:<\/p>\n\n\n
<code>as<\/span> unknown as<\/span> InventoryItem;<\/code><\/span><\/code><\/span>Code language:<\/span> TypeScript<\/span> (<\/span>typescript<\/span>)<\/span><\/small><\/pre>\n\n\n
since unknown<\/code> is a “top” type, which means anything can be cast to it, and from it.<\/p>\n\n\n\n
Wrapping up<\/h2>\n\n\n\n
Use satisfies<\/code> when you want to prevent type<\/em> widenings<\/em>, in situations where a top-level variable declaration doesn’t quite fit well.<\/p>\n","protected":false},"excerpt":{"rendered":"
The `satisfies` keyword allows you to assert that a certain value “satisfies” a given type, while preventing a wider type from being inferred.<\/p>\n","protected":false},"author":21,"featured_media":6454,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"sig_custom_text":"","sig_image_type":"featured-image","sig_custom_image":0,"sig_is_disabled":false,"inline_featured_image":false,"_jetpack_memberships_contains_paid_content":false,"footnotes":""},"categories":[1],"tags":[363,184],"class_list":["post-6443","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-blog-post","tag-satisfies","tag-typescript"],"acf":[],"jetpack_featured_media_url":"https:\/\/i0.wp.com\/frontendmasters.com\/blog\/wp-content\/uploads\/2025\/07\/Satisfies-in-TypeScript-v2.jpg?fit=1140%2C676&ssl=1","jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts\/6443","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/users\/21"}],"replies":[{"embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/comments?post=6443"}],"version-history":[{"count":6,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts\/6443\/revisions"}],"predecessor-version":[{"id":6455,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/posts\/6443\/revisions\/6455"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/media\/6454"}],"wp:attachment":[{"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/media?parent=6443"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/categories?post=6443"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/frontendmasters.com\/blog\/wp-json\/wp\/v2\/tags?post=6443"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}