`satisfies` for return types

🔍 Search Terms

satisfies
return

✅ 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 isn't a request to add a new utility type: https://github.com/microsoft/TypeScript/wiki/No-New-Utility-Types
• This feature would agree with the rest of our Design Goals: https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals

⭐ Suggestion

type AcceptableType = string | number | boolean | undefined | null | object[]

/** `const fn: () => "asdf" | 8 | undefined` */
const fn = (): satisfies AcceptableType => {
  if (someCondition) {
    return "asdf"
  } else if(otherCondition) {
    return 8
  } else {
    return undefined
  }
}

📃 Motivating Example

function getResult(): satisfies { a: string, b: number } {
  // type-errors until `satisfies` condition is met
  return {
    // type-hints and type-checking for:
    // (property) a: string
    // (property) b: number
  }
}

💻 Use Cases

The satisfies operator has been immensely useful for ensuring expressions match some wider type while also inferring their narrower type

However, because satisfies works only on expressions, getting the same behavior on function return types requires workarounds with several drawbacks. For example, if a function has multiple return values, we need to type satisfies SomeType for every single one of them, which is not only cumbersome but also prone to human error

/** `const fn: () => "asdf" | 8 | undefined` */
const fn = () => {
  if (someCondition) {
    return "asdf" satisfies AcceptableType
  } else if(otherCondition) {
    return 8 satisfies AcceptableType
  } else {
    return undefined satisfies AcceptableType
  }
}

playground link

This style is also incompatible with codebases that prefer/require their contributors to declare the return type of their functions (e.g. through eslint)

Another workaround exists by using satisfies on the entire function:

const fn = (() => { /* ... */ }) satisfies () => AcceptableType

playground link

but having to parenthesize the entire function just to be able to operate on it as an expression and then include the function signature in the satisfies type is at best impractical and at worst not even an option, in the case of function fn() { /* ... */ } declarations. Of course, function declarations will be available as expressions after the declaration, at which point satisfies can be used, but not to its full extent because the type-inference will no longer be able to guide the implementation of the function declaration from within the function body

// this correctly errors but...
getResult satisfies () => { a: string, b: number }

function getResult() {
  return {
    // you don't get any type-hints or type-checking here
  }
}

playground link

Being able to specify that the return type of a function satisfies a type would resolve all of the above drawbacks

No repository files or tests are named. Start by comparing the existing satisfies operator behavior with the linked Playground examples and the proposed return-type syntax. Done would mean an agreed implementation that checks function returns while preserving narrow inference and works for both function expressions and declarations.