Repository: TypeScript
Issue: allow narrowing of types and values outside of a function's parameters
Labels: Suggestion,Awaiting More Feedback

# Suggestion

<!--
  Please fill in each section completely. Thank you!
-->

## 🔍 Search Terms
narrowing global types assertion function type predicate

## ✅ Viability Checklist

<!--
   Suggestions that don't meet all these criteria are very, very unlikely to be accepted.
   We always recommend reviewing the TypeScript design goals before investing time writing
   a proposal for ideas outside the scope of the project.
-->
My suggestion meets these guidelines:

* [X] This wouldn't be a breaking change in existing TypeScript/JavaScript code
* [X] This wouldn't change the runtime behavior of existing JavaScript code
* [X] This could be implemented without emitting different JS based on the types of the expressions
* [X] This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, new syntax sugar for JS, etc.)
* [X] This feature would agree with the rest of [TypeScript's Design Goals](https://github.com/Microsoft/TypeScript/wiki/TypeScript-Design-Goals).


## ⭐ Suggestion
allow assertion functions (and type predicate functions) to:
- change the type of values outside of the function's parameters
- extend globally declared interfaces

## 📃 Motivating Example
it would be very useful for things like prototype extensions, where you have to define the type of the new property twice:
```ts
declare global {
    interface String {
        foo: (value: string) => string
    }
}
Object.defineProperty(String.prototype, 'foo', {
  value: (value: string) => value,
  enumerable: false,
})
```
instead you could define a wrapper function that does both:
```ts
export function defineProperty<T, Key extends string | number | symbol, Value>(
  object: T,
  key: Key,
  value: Value
): asserts InstanceType<T> /* this can now be either a value or a type*/ is T & { [K in Key]: Value } {
  Object.defineProperty(object, key, { value, enumerable: false })
}

defineProperty(String.prototype, 'foo', (value: string) => value);

['hi'].foo('value')
```

## 💻 Use Cases
for tools like cypress where to add new functions you have to define their signatures twice (see https://docs.cypress.io/api/cypress-api/custom-commands)
```ts
declare global {
    interface Chainable {
        foo(bar: number): string
    }
}

Cypress.Commands.add('foo', (bar: number) => "foo")
```
Instead you'd be able to define both at the same time using an assertion function 
```ts
//(pseudocode, the actual function signature to make this accurate to how commands work in cypress is like 60 lines long)
function addCommand<Name extends string, Func extends (...args: any[]) => any>(
  name: Name,
  func: Func
): asserts Chainable is Chainable & { [Key in Name]: Func } /* new syntax */ {
  Cypress.Commands.add(name, func)
}

//add the new command
addCommand(cy, 'foo', (bar: number) => "foo")

//use the new command
cy.foo(1)
```

currently, you can sort of do it like this:
```ts
function addCommand<Name extends string, Func extends (...args: any[]) => any>(
  _cy: typeof cy, //need to pass the unused cy object in order for the function to be able to change its type
  name: Name,
  func: Func
): asserts _cy is typeof _cy & { [Key in Name]: Func } {
  Cypress.Commands.add(name, func)
}
```
problems with the current approach:
- you have to needlessly pass the global `cy` object to the function, otherwise its type can't be asserted
- only the `cy` `Chainable` instance is narrowed, instead of the `Chainable` interface itself, which means you can't use this new method if you're chaining it off a previous command:
    ```ts
    cy.get('foo').foo(1) //error: property 'foo' doesn't exist on Chainable
    ```
- the narrowed type is not exportable - see #43772