`// @ts-mutate` decorator/directive

🔍 Search Terms

mutate type, alter type, post-declaration narrow

✅ 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

When doing property assignment to a variable already typed, allow a // @ts-mutate above the assignment which will

• A) Not throw an error trying to assign to a non-existent property
• B) Further narrow the type, encompassing the change

Example:

interface ObjectType {
  bar: string
}

const foo: ObjectType = { bar: 'hello' }

// @ts-mutate
foo.baz = 'hello'

foo
// ^? -- this is now `ObjectType & { baz: string }`

📃 Motivating Example

One specific example of why this would be useful would be a query constructor for type inference. There are GraphQL query constructors out there (GenQL) that query by supplying an object. I've built functions that yield reusable queries but sometimes I want to extend them.

This would allow me to take an existing query object and add an additional field to query, keeping my strict type inference.

💻 Use Cases

1. What do you want to use this for?

This could be used for constructing large objects sequentially and with inference without having to basically duplicate the information

2. What shortcomings exist with current approaches?

If you have an existing variable, you have to alter its type declaration with the type that it is (explicitly) and intersect it with your changes. This also doesn't necessarily narrow correctly. There's no exisiting clean, easy way to do this that works off of type inference and narrowing

3. What workarounds are you using in the meantime?

     // UGLY
     const query: ReturnType<typeof queryProp> & { prop: { addition?: true } } = queryProp(...args)
     query.prop.addition = true

The issue does not identify implementation files, tests, or entry points. Start by reviewing the proposed @ts-mutate behavior and its interaction with assignment checking and type narrowing; the work is done only after the design is accepted and the requested inference behavior is covered by tests.