TypeScript: [Proposal] Type assertion statement (type cast) at block-scope level

Technically we could just consider in as a form of type guards.

But I can still imagine something that says “assume the type of this entity is so-and-so for this block”.

how about adding the typeguard after the if condition itself by re-using the existing typeguard syntax:

if ("width" in obj): obj is AABox {
    // compiler assumes the obj is `AABox` within this scope
}

I found an absurd workaround for this issue. For some reason, using a @ts-ignore before a declare still declares the variable type, but suppresses the warning that Modifiers cannot appear here.

In fact, this could be a possible syntax if this suggestion were to be implemented, since it doesn’t create any new keywords.

interface A {
    x: number;
    z: number;
}

interface B {
    y: number;
    z: number;
}

interface C {
    x: number;
    y: number;
}

type Union = A | B | C;

function check(obj: Union): void {
    if ("x" in obj && "z" in obj) {
        // @ts-ignore
        declare let obj: A

        // obj is now treated as an instance of type A
    }
    else if ("y" in obj && "z" in obj) {
        // @ts-ignore
        declare let obj: B

        // obj is now treated as an instance of type B
    }
    else if ("x" in obj && "y" in obj) {
        // @ts-ignore
        declare let obj: C

        // obj is now treated as an instance of type C
    }
}

EDIT:

This only works in a new scope, for example inside a block. Usually, since this is useful to augment type narrowing, this is not an issue. However, casting variables such as function arguments using let produces a duplicate declaration error, and using var simply fails silently.

A possible solution for the original question with #32695 could look like this (I think):

function assumeType<T>(x: unknown): asserts x is T {
    return; // ¯\_(ツ)_/¯
}

function processGeometry(obj: Geometry): void {
    if ("width" in obj) {
        assumeType<AARect>(obj);
        let width = obj.width;
        // ...
    }
    if ("halfDimX" in obj) {
        assumeType<AABox>(obj);
        let halfDimX = obj.halfDimX;
        // ...
    }
    else if ("radius" in obj) {
        assumeType<Circle>(obj);
        let radius = obj.radius;
        // ...
    }
    // And much more...
}

The assumeType function is a no-op, so any decent minifier like terser or babel-minify should be able to remove those function calls. That should result in zero run-time overhead.

I have to admit it’s not as pretty as the proposed assume x is T syntax. Still, I believe asserts is the more versatile solution and can be applied to other problems, so I’m happy with it. 🙂

@pm-nsimic I like that. It’d also make most existing type narrowing situations just special case sugar:

// Equality
if (a === b) { ... }
if (a === b): a is typeof b { ... } // Desugared
if (a === b): b is typeof a { ... } // Desugared

// Inequality
if (a !== b) { ... }
if (a !== b): a is Exclude<typeof a, typeof b> { ... } // Desugared
if (a !== b): b is Exclude<typeof b, typeof a> { ... } // Desugared

// `== null`
if (a == null) { ... }
if (a == null): a is null | undefined { ... } // Desugared

// `!= null`
if (a != null) { ... }
if (a != null): a is Exclude<typeof a, null | undefined> { ... } // Desugared

// Falsy
if (a) { ... }
if (a): a is "" | 0 | false | null | undefined { ... } // Desugared

// Truthy
if (a) { ... }
if (a): a is Exclude<typeof a, "" | 0 | false | null | undefined> { ... } // Desugared

// `typeof` guard
if (typeof a === "string") { ... }
if (typeof a === "string"): a is string { ... } // Desugared

// `instanceof` guard
if (a instanceof A) { ... }
if (a instanceof A): a is A { ... } // Desugared if `A` has type-level binding

The fact that casting from one type to another still requires reassigning a variable or executing an actual function means that this isn’t really solved for me.

Developers should have the power to control this kind of thing easily:

assume foo as TNuancedTypeThatIsBasicallyImpossibleToNarrowExactlyWithUnions;

// use the new type directly without type errors
foo.knownNewProperty();

The fact is, that entire line can just be removed with the TypeScript compilation process. It doesn’t seem to add so much complexity that its too hard to implement? Its basically just an assertion without needing to call a function (add unnecesary computaitonal complexity- something we always want to strive for no matter how irrelevant it seems because in certain scenarios it can add up).

I agree that unions should be the thing to solve most of this stuff- but the fact is that often times, with large and complex unions this can be a huge challenge and sometimes doesn’t work out how you’d expect because of optional properties or a union that’s based off of something more nuanced than an exact property value.

All in all, I’d like TypeScript to work for me- not against me- when I know exactly what I’m doing. assume foo as * is a purposeful syntax- if its misused, like the any type and lots of other things in TypeScript can be misused, then that’s on the developer.

I know that the current way we are expected to get this functionality (without needing an assert function or re-assign) is to do this:

(foo as TNuancedTypeThatIsBasicallyImpossibleToNarrowExactlyWithUnions).knownNewProperty();
const otherThing = (foo as TNuancedTypeThatIsBasicallyImpossibleToNarrowExactlyWithUnions).internalName();
runProcessOnFoo(foo as TNuancedTypeThatIsBasicallyImpossibleToNarrowExactlyWithUnions);

I don’t think I need to elaborate on why this is terrible… But this is even worse as far as developers making mistakes goes- because now if we don’t remember to type-cast foo every time its actually not the intended type.

I think that this issue can be closed because Typescript already narrows the type correctly (at least since version 3.3, which is the last one that we can test in the playground).

Playground

Redirecting here from #8655, I’m not fond of the idea of requiring an if block. I understand that there’s architectural constraints that requires a syntactic signal for whether to perform narrowing, but requiring an if does not handle the case of assertion functions.

Closure Library and Compiler have had very good success with debug-only assertions, such as

assert(a instanceof A);

The compiler understands this as a type assertion and narrows the type of a through the rest of the control flow. TS can handle this right now with

if (!(a instanceof A)) throw new Error('Assertion failed');

but there’s no good way for an optimizer to remove this later. If we had some way to annotate a function call as a type-narrowing assertion that could show up in the AST to resolve the performance issues, then the function call could be retained and possibly removed in post-processing. Note that I’m not asking for TypeScript to get into the optimization business, but the current design is a particular impediment to working well with third-party optimizers, which seems somewhat in line with goal 3 (“Impose no runtime overhead on emitted programs” - but the current solution does) and in line with the counterpoint to non-goal 2 (“Instead, emit idiomatic JavaScript code that plays well with the performance characteristics of runtime platforms”).

Unfortunately, I’m not thinking of any particularly good syntax to annotate this. It does remind me a bit of the expression-level syntax for non-null type assertions, but I don’t see a good way to extend that at all.

haven’t found anything that isn’t ugly or looks like an expression with side effects.

declare typeof foo: Foo? Not introducing a new keyword and literally (re)declaring the type of foo as Foo. And as TypeScript users we all know declare won’t affect emitted JavaScript.

But again, I find this solution not really satisfying since it still creates persistent helpers functions just for the sake of the type inference and can be overkill for situations when we do not often need to perform type guards.

@yahiko00 User defined type guard functions actually are an important part of the emitted code. They may determine control flow at runtime. Also this is not type inference, it is type assertion (or type assumption 😛 ). If you want shorthand type guards you can write

function is<T>(value, condition: boolean): value is T {
    return condition;
}

then you can write the following

function processGeometry(obj: Geometry): void {
    if (is<AARect>(obj, "width" in obj)) {
        let width = obj.width;
        // ...
    }
    if (is<AABox>(obj, "halfDimX" in obj)) {
        let halfDimX = obj.halfDimX;
        // ...
    }
    else if (is<Circle>(obj, "radius" in obj)) {
        let radius = obj.radius;
        // ...
    }
}

@lostpebble your last workaround doesn’t really address this. The whole purpose of this issue is to make an existing variable be inferred as a different type, not create a new variable nor make function calls that impact runtime. Otherwise the simplest is:

const color = someColorThing as Color;
const asString = testObject as unknown as string;

But again, the whole purpose is to avoid that runtime change entirely.

Okay, so what about an unreasonable optimizer or none at all?

So you are saying the bottom line for type casting in TypeScript is to have useless functions or re-assignments in your code. TypeScript to me has always been about augmenting JavaScript with types for more safety- but here its forcing us to actually add unnecessary JavaScript to get the types we want.

You’re proposing to add a feature, including new syntax no less, that can already be done for free.

The fact is its not “done for free”- it compiles down to an actual function call for something which is completely useless for your end JavaScript code. Whether a developer later uses a great optimizer down the line to get rid of that function is a different topic.

Basically, to achieve type-casting now with how you say we should do it, TypeScript expects our code to end up looking like this:

function assumeAs(thing) {
  return thing;
}

function regularCode(incoming) {
  assumeAs(incoming);
  incoming.runStuff();
}

I don’t really get why we can’t still aim to achieve this instead of being dismissive and conceding that it adds too much complexity for what it achieves. Internally TypeScript appears to have the ability to cast in a block with that assert function- why not just allow the same but with a special syntax.

(I’m not saying the syntax I mentioned has to be the final one either, just that it looks pretty nice and doesn’t clash with current typescript keywords)

I think it is still worth pointing out that there are still some cases of type inference that AFAIK have not been solved yet in Typescript. Playground Example:

type Result = { key: string };

function NodeStyleCallback(err: number, result: null): void;
function NodeStyleCallback(err: null, result: Result): void;
function NodeStyleCallback(err: number|null, result: null|Result) {
    if (err == null) {
        // Based on call signatures, if err is null, then result must be a Result
        // object, but TS is unable to determine that. Type assertions could help
        // here.
        console.log(result.key); // Object is possibly 'null'.(2531)
    }
}

So assertions could really help, either the form of the assume x is _, or inline type guards based on if statements:

if (err == null) : result is Result {
  console.log(result.key);
}

@jdom See #32695. 😃

@aluanhaddad if("width" in obj) could narrow obj to AARect if the declared type of obj is a union like AARect | AABox | Circle.

Why hasn’t this been included for so many years? Reanimated in React-Native really could use it - we have to face multiple architectures, platforms and it would be nice if after checking what platform we are on we could inline type guard some parameters to be platform specific. Since performance is key for us even a couple type guard calls can be too expensive and multiple type assertions are just cluttering the code.

@shicks Thanks! I have seen that workaround, and it mostly works, but does technically break Function.prototype.length for the function. I think in the spirit of this feature request, the desire is for Typescript code to completely compile away. In general, having to write code differently not b/c it is bad practice, but b/c the type engine cannot understand it, is a very frustrating dev experience.

I think having a block-scoped assertion mechanism would really help to act as a stopgap for this and other edge cases in the typing system. As the typing system gets more and more sophisticated, it can be used less and less.

@MattiasBuelens

function assumeType<T>(x: unknown): asserts x is T {
    return; // ¯\_(ツ)_/¯
}

The way I got it working was slightly different

declare function assumeType<T>(x: unknown): asserts x is T;

assumeType<MyType>(obj);

The real world example was to assert the types of redux actions my reducer was processing:

import * as Actions from './actions';

declare function assumeType<T extends (...args: any) => any>(x: unknown): asserts x is ReturnType<T>;

const mouseCords = (state = { x: 1, y: 1 }, action: AnyAction) => {
  switch (action.type) {
    case Actions.CHANGE_CORDS:
      assumeType<typeof Actions.changeCords>(action);
      return action.mouseCords;
    default:
      return state;
  }
};

It works but everyone has to roll their own implementation in the code for what looks like a pretty common use case.

@saschanaz I personally feel assume hits that high bar, though, about as much as keyof did.

But of course, I’m not the arbiter of this, so I’ll dive back into the sidelines now.

So what you are really proposing is a type assertion statement that is otherwise exactly like the existing type assertion expression. For example:

function fn(arg: P) {...}

// Type assertion as an expression (existing syntax)
let x: Q;
f(x as P); // 'x as P' is a type assertion expression

// Type assertion as a statement (proposed new syntax)
let y: Q;
assume y is P; // this is a type assertion statement
f(y); // y has type P here

As with other statement/expression equivalences, this proposed new form of type assertion is used for its side-effects rather than its result, although obviously these are compile-time side-effects, since type assertions are elided at runtime. And as you mention you want the side-effects limited to the block in which the assertion appears.

Why hasn’t this been included for so many years? Reanimated in React-Native really could use it - we have to face multiple architectures, platforms and it would be nice if after checking what platform we are on we could inline type guard some parameters to be platform specific. Since performance is key for us even a couple type guard calls can be too expensive and multiple type assertions are just cluttering the code.

If you write a no-op type guard, you shouldn’t see any performance regression. Nearly every VM will do JIT optimization to inline the empty function call into the calling functions’ bytecode. The only exception I’m aware of is iOS native, which doesn’t allow it, but in that case you’re already bundling, and every bundler can (and will) also inline empty functions in production builds. Such an empty type guard isn’t particularly “safe” (since it’s not actually doing any checking at runtime), but depending on how you type it, it’s no less safe than an ordinary as T type assertion that you’d write without it.

See https://jsbench.me/00ls2rex1g/1

What about these alternatives?

assert X is Y
use X as Y
refine X as Y
narrow X as Y

We could also only allow narrowing in if/else block:

if (...): X is Y {
   ...
} else: X is Z {
   ...
}

@saschanaz

Maybe duplicated type redeclarations should also throw:

I’m not sure it should:

declare typeof x: Node;
if (x.nodeType !== Node.ELEMENT_NODE) return;
declare typeof x: Element;

BTW, my example looks weird to myself because declare has never been allowed in a block.

Yeah, I don’t really like that syntax too well myself. Compare that to this:

// @lemoinem's suggestion
declare typeof x: Node;
if (x.nodeType !== Node.ELEMENT_NODE) return;
declare typeof x: Element;

// Mine
assume x is Node;
if (x.nodeType !== Node.ELEMENT_NODE) return;
assume x is Element;

Maybe duplicated type redeclarations should also throw:

if (x.nodeType === 3) {
  declare typeof x: Text;
  declare typeof x: Element; // !!
}

BTW, my example looks weird to myself because declare has never been allowed in a block.

@lemoinem That’s basically my proposal, just using declare (which doesn’t make as much sense - you’re not declaring anything) instead of a contextual assume.

I like the original proposal’s syntax, because if you need to narrow the scope of the type assertion, you can just add a block and make the assertion in there.

Regarding the alteration of the type of already declared variables in the current scope, with let and cost, the compiler can just throw an error complaining about multiple declarations, which makes total sense.

In my view, this type of type assertion should be nothing more than a type declaration, with the condition that the variable already exists in a higher scope.

Also, I don’t agree with the use of declare keyword here. It should be something new or something unrelated, so their meanings and use don’t conflict with each other.

I don’t think it would be wise for there to be a surrounding block since that would alter the meaning of let and const declarations.

It would be safer to scope the effect of the assertion to the enclosing block.

a && b; sounds good at first but it could have side effects so it’s not inert like, say, a pragma.

Consider:

const checkedFsKey = Symbol();
F[checkedFsKey] = new Set<F>;
F[Symbol.hasInstance] = function (x: object) {
  const hasInstance = // whatever
  if (hasInstance) {
    F[checkedFsKey].add(x);
  }
  return hasInstance;
};

In my mind, <identifier> included both simple variable identifiers and properties. But after checking the grammar specifications, I should have been more precise. 😉 So yes, both identifiers and properties should be allowed in type assertion statements.

BTW I see you’re only proposing this to work on simple identifiers, whereas type assertion expressions work on arbitrary expressions, like foo.bar as string. Type guards also work with properties, like if (isString(foo.bar)) {foo.bar.length}. It might be useful to consider at least some expressions as valid in type assertion statements, for example assert foo.bar as string;

For reference, the spec on type assertion expressions (section 4.16) is here.

The rules and use-cases described there for type assertions would presumably apply to this proposal in exactly the same way.

This looks like the same concept as #9946, but with different syntax.

@tjzel I agree 100% that something like this in the language would be amazing- our comments are almost 1 to 1 (see earlier in the thread).

I’ve found that this is probably the simplest way to do this as of now:

function cast<T>(it: any): T {
  return it;
}

function castTest() {
  const testObject = {
    color: "red",
  };
  
  // asString is now a string type (obviously bad though)
  const asString = cast<string>(testObject);
}

The syntax isn’t so bad- and feels natural enough.

const color = cast<Color>(someColorThing);

But yea, having to do this could be dangerous overall and remove some of the type safety that TypeScript gives to us. But there definitely are places where this comes in handy (not every project is greenfield).

I love this idea. This thread is really long but what’re the current blockers?

Just wanted to drop another use case for this that I documented on StackOverflow.

I came up with a similar solution as @MattiasBuelens’s assumeType<T> assertion. But it still would be nice not to have to rely on tree shaking/dead-code elimination to achieve this without runtime consequences. Especially since that elimination could be prevented by the presumptive possibility of side effects in some cases.

@EnderShadow8 this is interesting 🙂

I did some tests to see if I could break it, but it seems to work - my main worry was the redeclared types would somehow leak to the .d.ts file, but that does not appear to be the case, and IDE support looks sound as well.

I couldn’t find any gotchas - is this really as simple as just lifting the restriction and allowing what already works? 🤷‍♂️

It should probably still have a dedicated syntax though, since let seems to imply we’re actually declaring a new variable with the same name, shadowing a variable in the parent block scope, which isn’t really what’s happening. Although, in practical terms (in terms of typing) I suppose the effects of doing that would be exactly the same.

If nothing else, this makes for a pretty nifty workaround. 😃👍

EDIT: the only caveat I can find is the fact that the new symbol is just that: a new symbol, shadowing the symbol on the parent block scope - which means, your inner obj is an entirely different symbol, disconnected from obj in the parent scope, as you can see if you use “find references” … as you can see in the example here, there’s no relationship with the declaration on line 18:

So the risk of doing this, is it will break if you rename or remove the parent symbol - and emit code that fails.

@yahiko00 It won’t create it, but it will have to emit the call because the call could have side effects (like throwing or object mutation).

@rzvc I personally would prefer both of these forms:

• assume obj is Foo; - This statement within a block scope is equivalent to the following, where assume is a unique global name not exposed to the user:

  // Original
  assume obj is Foo;
  
  // Polyfilled
  while (!assume<Foo>(obj)); // never loops
  
  // Declaration
  function assume<T>(obj: any): obj is T { return true }
  

• obj is Foo - This expression is exactly equivalent to cast<Foo>(obj), where cast is defined as function cast<T>(obj: T): T { return obj }

The syntax can be something like

function incoming(thing: array | number, another: boolean | string): void {
  // thing is array or number
  if (checkSomething()) {
    guard thing as array, another as string {
      // thing is array, another is string
      console.log(thing.length, another.toLowerCase())
    }
  } else {
    guard thing as number {
      // thing is number
      console.log(thing.toFixed())
    }
  }
}

All the current suggestions seem to propose a means of altering the type within the current scope, e.g.:

if (a instanceof A) {
    b is B;
    c is C;
    do_something(a, b, c);
}

How about making the scope of the type-cast explicitly block-scoped? Nope! see comments below.

if (a instanceof A) {
    using (b as B, c as C) {
        do_something(a, b, c);
    }
}

If I had to pick from the options listed by @yahiko00, my favorite is (1):

The use of keyword declare is interesting since it already exists, and emphasizes on the fact this is an annotation that will not be emitted in the JavaScript.

👍

However, it makes me think more of ambient declarations and could suggest we do not have an instanciation of <identifier> before, which is misleading.

That was actually the thing that gave me the same idea - in fact, I was intuitively just trying it when I ran into this problem, hoping it would just work.

I like the fact that this resembles ambient declarations, because it is ambient (doesn’t emit any code) and it is a declaration - even if it isn’t quite an “ambient declaration” in the Typescript sense, it seems pretty intuitive.

Also, I am quite afraid of conflicts with existing use cases of declare.

Unlikely to happen, I think - since ambient declarations are always top-level declarations?

Regarding (3) I find the introduction of a keyword assume is sort of inconsistent with other type-casts, which don’t require a keyword.

Even if (5) is visually ambiguous with other type-casts, I like that option as well, as it’s the closest relative to other type-casts in Typescript. It’s actually not inconsistent with JS itself, where, for example, stand-alone expressions like a && b;, even if they’re completely inert, are syntactically valid.