Safe type assertion (upcast / widening) operator

🔍 Search Terms

as, satisfies, type assertion, type casting

✅ Viability Checklist

This wouldn't be a breaking change in existing TypeScript/JavaScript code
This wouldn't change the runtime behavior of existing JavaScript code
This could be implemented without emitting different JS based on the types of the expressions
This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

I suggest adding a safe type assertion operator, a kind of middle ground between current as and satisfies.

Like as, it should cast the expression to the asserted type
Like satisfies, it should only allow assertion if the asserted type is wider than the expression type

Here's what it might look like:

type Foo = { a: number }

const foo1 = { a: 1 } as! Foo // OK. foo1: Foo

const foo2 = { a: 1, b: 2 } as! Foo // OK, foo2: Foo

const foo3 = { b: 2 } as! Foo // Error, { b: number } is not assignable to Foo

const foo4 = { } as! Foo // Error, {} is not assignable to Foo

📃 Motivating Example

For example, such operator will allow to safely give named types to expressions without declaring extra variables or helper functions.

Consider an async function f that returns an object of type Foo:

type Foo = { a: number }

const f = async () => ({ a: 1 })

I want the returned object to strictly be of Foo type, how do I enforce this?

Hard code the return type

const f = async (): Promise<Foo> => ({ a: 1 })

The problem here is that I must write Promise<Foo> instead of just Foo, but the Promise part can be inferred just fine. In real world these generics can be arbitrarily complex.

Declare a variable

const f = async () => {
  const result: Foo = { a: 1 }

  return result
}

This is better than retyping generics but still pretty verbose.

Use a helper function

const safeAssert = <T>(value: T): T => value

const f = async () => safeAssert<Foo>({ a: 1 })

This is ok but still requires writing/importing helper functions.

as is not an option here because it's unsafe, satisfies is neither because it doesn't name the type. Naming a type can be important for documentation purposes, this proposal allows to do this with less boilerplate.

const f = async () => ({ a: 1}) as! Foo // f: () => Promise<Foo>

💻 Use Cases

As described above, this feature can be used to safely cast expressions to specified types. A practical example when it can be useful is naming a type in an expression. Currently this is only covered by custom helper functions such as <T>(value: T): T => value.

This was discussed a bit at #47920. Your example is missing what I'd consider the most straightforward solution:

const f: () => Promise<Foo> = async () => ({ a: 1 })

This was discussed a bit at #47920. Your example is missing what I'd consider the most straightforward solution:
const f: () => Promise<Foo> = async () => ({ a: 1 })

This has the same problem as my 1st example, you have to retype generics

Here's a more complex example to show why it's inconvenient:

type Foo<T> = { foo: T }
type Bar<T> = { bar: T }

declare function makeFoo<T>(value: T): Foo<T>
declare function makeBar<T>(value: T): Bar<T>

type Value = { value: number }

const f = async () => makeFoo(makeBar({ value: 1 }))

Now I have to type 3 generics:

const f: () => Promise<Foo<Bar<Value>>> = async () => makeFoo(makeBar({ value: 1 }))

you have to retype generics

This only applies to Promise, though. In all other cases, you're writing the full type again.

you have to retype generics

This only applies to Promise, though. In all other cases, you're writing the full type again.

I used promises because it's the most obvious example, but you can have all kinds of functions that take your value and wrap it in different generics. I updated my example to demonstrate this.

The most painful thing this would remedy is cases such as #9998, which forces you to do true as boolean. I believe there are "best practices" these days that force you to do x satisfies T as T—based on feature requests we've closed in ts-eslint.

We would find this feature very useful since by using playwright, we create mocks for our application and we are using satisfies to ensure that the mock is correct for the given type. however we also have to use as to provide better intellisense in vscode for the given mock resulting in many satisfies T as T where T may be a very long string since we use types generated by grpc.

Joshua Chen (@Josh-Cena)

I was about to create a feature request, but I think this is asking for the same thing. Basically, I just want something like
X satisfies as T to be syntactic sugar for X satisfies T as T. As mentioned by Joshua Chen (@Josh-Cena) and @raythurnevoid, this seems to be a common and sometimes verbose pattern. Just some simple syntactic sugar to remove the duplication of T would be fantastic.

Also, just to link it, this feature would pretty much address: #13626

cross-linking satisfiesas, satisfias, sassafras
#61789 (comment)
#51853 (comment)

This is effectively type ascription.

One question : would the operator model type annotation semantics 1:1 (notably assignability + excess property checks on fresh object literals)?

Example:

type MyConfig = { port: number }
setConfig({ port: 440, excess: 'hi' } ascribe MyConfig) // should probably error

declare function setConfig(cfg: unknown): void; // no excess property checks there

Since I keep finding myself needing this too, here are my two cents regarding the syntax:

x : T // models type annotation syntax
x ascribe T // explicit but verbose, though satisfies is also verbose
x be T // short like as
x to T // implies conversion

I think x ascribe T would fit in best for modern TypeScript though the terminology might be confusing to beginners.

In vacuum I like ascribe or widen for this keyword, but my vote actually goes to x satisfies as T¹—it requires no new keywords, is an easy thing to write if you have an existing satisfies or as clause, and is currently a syntax error. It's even naturally discoverable as folks will end up typing it on the way from x as T to x satisfies T as T.

I think x as satisfies T should continue to be a syntax error. I could imagine it desugaring to x as T satisfies T for symmetry, but that's a pointless thing to write and I can't imagine anyone intentionally wanting this, only writing x as satisfies T by accident when they intended to write x satisfies as T ↩

Matt Kantor (@mkantor)

Matt Kantor (@mkantor) is is better IMO.

is is currently only used in type guards, so x is T also currently a syntax error in this context. For a type guard, the return type is specifying whether the type is satisifed. For this feature, the programmer is specifying that the type is satisfied (and should be an error if it isn't). I think there's a nice symmetry there.

It's also shorter and reads like English: here's an x which is a T.

The biggest isssue is that x is T can be visually mistaken for x as T. The problem mostly comes when you write as and meant is, rather than the opposite, since as is unsafe. But tooling can probably mitigate this. A good linter rule could probably determine that is was intended.

Since it's only a single word, it doesn't have the cognitive burden of remembering satisfies as or as satisfies that you mentioned.

Navigation Menu

Repository navigation

Safe type assertion (upcast / widening) operator #56235

🔍 Search Terms

✅ Viability Checklist

⭐ Suggestion

📃 Motivating Example

💻 Use Cases

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Safe type assertion (upcast / widening) operator #56235

Description

🔍 Search Terms

✅ Viability Checklist

⭐ Suggestion

📃 Motivating Example

💻 Use Cases

Activity

RyanCavanaugh commented on Oct 27, 2023

bgenia commented on Oct 27, 2023

RyanCavanaugh commented on Oct 27, 2023

bgenia commented on Oct 27, 2023

Josh-Cena commented on Oct 28, 2023

raythurnvoid commented on Jan 4, 2024

saltman424 commented on Mar 28, 2024

jcalz commented on Jul 31, 2025

5cover commented on Mar 27, 2026

mkantor commented on May 25, 2026

Footnotes

michaelboyles commented on Jun 20, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions