Skip assignment narrowing when declaring & initializing a variable in the same statement

[mkantor]

🔍 Search Terms

declare, assign, declaration, assignment, narrow, narrowing, union, variable, "control flow analysis"

✅ 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

Currently TypeScript performs assignment narrowing whenever a variable with a union type is written to.

I propose that assignment narrowing should not occur in the specific case where a variable is declared and initialized in a single statement with a type annotation (e.g. immediately following let a: B = c, a would be guaranteed to have exactly type B). This behavior may need to live behind a compiler flag to avoid problems in existing code which assumes such narrowing happens. If the current narrowing behavior is desired at some particular assignment, it could be done in a separate statement (let a: B; a = c).

There have been many issues filed related to assignment narrowing, but I haven't seen this specific idea suggested as a "feature request" anywhere. Apologies if I missed a duplicate.

📃 Motivating Example

There are tons of existing issues with relevant examples:

• why does initialization narrow type? #8513
• Control flow analysis fails to account for possible assignments to captured variables in closures. #30097
• let-union_type is narrowed incorrectly #31580
• Explicit boolean type not honored without cast #34691
• Type narrowing loses explicit type, forces me to re-cast to explicit type #36530
• Is type assignment a simple compatibility check? Or is it an assertion? TypeScript says "both, sometimes" #42656
• "Condition will always return false": declared type not being used? #42702
• Type of variable is narrowed immediately after definition #44824
• Type narrowing not working properly for unions in let declarations #48038
• TypeScript doesn't respect declared function argument type definition #51487
• Type inference ignores explicit type annotation #55330
• Assingment type inference is broken with map, forEach #61755
• …probably many I missed

While some of the above touch on #9998 and related CFA limitations, as far as I can tell the specific examples in those issues would all cease being problematic if this suggestion were implemented.

I think type inference has trained me (and perhaps others) to take a mental shortcut: it's easy to conceptualize most assignments as if the type checker examined the right-hand side first (before dealing with the left), in which case it feels like the : B should "win" in let a: B = c and act as an upcast (because : B would be applied after determining the type of c). I know that's not literally how things work, but the actual behavior is harder to explain and keep front-of-mind at all times. This is made worse by the fact that when B is a non-union type then it does act like an upcast (e.g. a is unknown rather than string after let a: unknown = 'blah').

💻 Use Cases

1. What do you want to use this for?
   Declaring a union-typed variable and giving it an initial value without having to work around the type checker.

2. What shortcomings exist with current approaches?
   As far as I can tell the suggested approach is usually a type assertion (instead of let a: B = c, write let a = c as B). Shortcomings of that approach include:

   • it's not always obvious when it will be necessary, especially when the union is hiding behind a type alias
   • it's easy to accidentally assert the wrong type (or change the type/value in a future refactor) without getting any feedback, leading to runtime bugs that could have easily been caught by the type checker
   • if you have a lint rule banning type assertions it needs to be disabled

3. What workarounds are you using in the meantime?
   Type assertions as mentioned above, or an identity function.

   The "safe upcast" version of satisfies would have provided another workaround, but that's not the version that shipped.

[mkantor]

This comment claims:

it's very confusing if

let x: T = e;

behaves differently from

let x: T;
x = e;

Which I sympathize with, but clearly the current behavior is also very confusing as evidenced by the sheer number of issues involving it. There's a confusion tradeoff here, with arguments for both sides.

[mkantor]

The discussions in these particular issues are especially relevant and probably worth a read before commenting here:

• why does initialization narrow type? #8513
• Type narrowing loses explicit type, forces me to re-cast to explicit type #36530
• Is type assignment a simple compatibility check? Or is it an assertion? TypeScript says "both, sometimes" #42656
• "Condition will always return false": declared type not being used? #42702
• Type inference ignores explicit type annotation #55330

[jcalz]

You checked

“This wouldn't be a breaking change in existing TypeScript/JavaScript”

But of course it would break existing TS code. A compiler flag doesn’t really stop it from breaking people, because all that does is double the supported configuration space, and for half of that space it’s a breaking change.

[mkantor]

But of course it would break existing TS code. A compiler flag doesn’t really stop it from breaking people, because all that does is double the supported configuration space, and for half of that space it’s a breaking change.

I might be misunderstanding what you mean, but if people have to explicitly opt-in it's not going to (unintentionally) break them. Isn't this the same story as other opt-in flags like noUncheckedSideEffectImports, isolatedDeclarations, exactOptionalPropertyTypes, etc? If you turn stuff like that on in an existing codebase you wouldn't be surprised to see new errors.

I definitely understand that if this does need to be behind a flag that it's much less palatable, though. Like you said: it doubles the configuration space.

[jcalz]

I guess it's semantics. I think it is literally true that "if you don't enable the feature then it's not going to break your code" but I feel it's misleading to lump that in the same category as a feature that doesn't break things even if you enable it. If I said cigarettes don't cause cancer because smoking is opt-in, I'd expect people to disagree.

Anyway, semantics aside, we agree that this feature breaks people if enabled, right? You're suggesting that it would be preferable for there to be a flag where you turn it on and then the following should produce compiler errors:

let foo: string | number = 123;
foo = foo.toFixed(); // error?! 
foo.toUpperCase(); // error?!

Whether or not that's considered a true "breaking change" seems less important than hearing some really good justification for why any compiler config should result in such behavior.

[mkantor]

the following should produce compiler errors: [...]

Yes, I imagine those would be errors. let foo: string | number = 123 would be the same as let foo: string | number = 123 as string | number as far as foo's type is concerned.

really good justification for why any compiler config should result in such behavior

Many people find the current behavior unintuitive (see all the linked issues, but this also comes up a lot on the TypeScript Community Discord, StackOverflow, Reddit, etc), and it can lead to real bugs (which would arguably be better addressed by making CFA smarter, but I'm skeptical that everything in #9998 will or even can be solved).

As said above there's absolutely a tradeoff here. I don't know how to empirically judge whether the current behavior or my proposed behavior is more confusing, but I think it's at least plausible that the proposed behavior would lead to fewer surprises. I have a bit more conviction that it would lead to fewer bugs (of the kind linked above), at the expense of people having to occasionally to do extra narrowing/assertions to convince the type checker that code like your example is safe. That sort of thing is not uncommon in TypeScript though.

[jcalz]

Given the TS team's responses in all the linked issues above, I sincerely doubt this will ever be implemented. I just wrote up several paragraphs but to avoid cluttering up this issue further, I'll just say that I think a combination of #45870 (display both the declared/inferred and the narrowed/apparent types in IntelliSense) and #49669 (individual variables could be voltatile to opt out of assignment narrowing) would be a more plausible way forward.

[mkantor]

I edited it out before submitting, but originally had a note here about how displaying both read and write types in type info (mentioned in #45870) might help reduce the confusion around this stuff. And, yeah, #49669 would probably make this unnecessary (though I don't have high hopes for that one either).

TL;DR: I agree. 😄

[RyanCavanaugh]

Many people find the current behavior unintuitive

People found the pre-CFA behavior unintuitive too, which is why we added CFA at all.

You would frequently get into problems where code that should work just doesn't, e.g. you write something like this and TypeScript makes an inference for a case that observably cannot happen:

function foo(s: string | undefined) {
    let result: string | string[] = "it's okay";
    if (s !== undefined) {
        result = [result, s];
    }
    // Inferred return type should be string | string[],
    // inferring string | string[] | string[][] is "wrong"
    return result;
}

I think there's a confusion here conflating this with 9998-related CFA limitations. I would argue the correctness of CFA is unchanged by just doing less CFA: either you have a mutation outside of CFA's scope or you don't. Failing to perform a valid CFA just induces people to downcast, which is actually more unsafe.

The net effect of this change would be that it'd become very idiomatic to write

let s: string | number;
s = "hello";

and then you'd still have exactly the same problem:

function mut() { s = 42; }
let s: string | number;
s = "hello";
mut();
console.log(s.toLowerCase());

Fundamentally I just don't see a principled reason why control flow analysis should reason about some effects of a variable's value, but not others. A lot of the time, the type of the initializer of a variable is part of the correctness of your program. I don't know how I'd explain to someone why every assignment except the ones that occur as part of a binding are subject to analysis.

I don't think a commandline flag is the right approach here either. It's not like half of programs think initialization should narrow and half shouldn't - it's half of variables, which are diffused throughout the program.

It would be at least interesting to see a PR that we could run the top800 for the sake of discussion, though.

[jcalz]

it's half of variables, which are diffused throughout the program.

Right, so then maybe #49669 is better? Something like let volatile x: string | number = "abc" could imply that TS should not even try to narrow x.

Although to me that implies even if (typeof x === "string") { f(); console.log(x.toUpperCase()); } should fail, since who knows what f() might do to x. Meaning either volatile becomes really really annoying to work with (assert everywhere? copy to a const before narrowing? etc) or people really do just want let x = "abc" as string | number so they can control exactly when things narrow? Great, now my head hurts. 🤕

[RyanCavanaugh]

My proposal to allow e satisfias T as a synonym for e satisfies T as T was met with unanimous derision

[jcalz]

What about the sassafras operator?
let x = "abc" sassafras string | number

[mkantor]

@RyanCavanaugh

You would frequently get into problems where code that should work just doesn't

That function looks like unusual code to me which I'd probably suggest changing if I saw in a pull request. If this proposal were implemented I can think of multiple alternative ways to structure that to ensure the return type is string | string[]. No need to manufacture/find other examples though, I'll take your word for it that this is realistic enough to warrant consideration.

For what it's worth I think you'd get an error in the reassignment on line 4 under this proposal (rather than a "wrong" inferred return type).

I think there's a confusion here conflating this with 9998-related CFA limitations

Even if CFA were perfect I think that the current behavior would still confuse people who think let a: B = c implies that a now has type B (who I believe to be the majority). I'm claiming that at-initialization assignment narrowing is more often not what people want/expect, and therefore the two-statement escape hatch would be rarely used (I'd be surprised if it "becomes very idiomatic"). But that's just, like, my opinion, man. Honestly the current behavior is surprising enough that I can imagine bringing it up as a trick question in an interview as I've seen done with hoisting or coercion gotchas in JavaScript.

In any case I do think that if CFA were infinitely smart it'd make this less important.

I don't think a commandline flag is the right approach here either

Yeah, the more I think about it I'm leaning towards a flag requirement being enough to kill this idea entirely. If TypeScript had Rust-like "editions" or similar I'd propose this change happen in an edition, but that's not a thing.

[mkantor]

Putting the current behavior more upfront in the documentation could also help reduce confusion (at least for the subset of people who actually RTFM). Maybe the assignment narrowing section could include an example where there's an explicit type annotation like this, and maybe the variable annotation section could link to the assignment narrowing section?