Feature Request/Question: Lift the explicit type requirement in assertions for participation in CFA

Suggestion

🔍 Search Terms

explicit type, assertion, CFA

✅ 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 feature would agree with the rest of TypeScript's Design Goals.

⭐ Suggestion

As stated in #32695, functions using asserts require explicitly typed/annotated like so:

declare let x: unknown;
const aFoo = a.literal("foo");
aFoo(x); // error
// Assertions require every name in the call target to be declared with an explicit type annotation.(2775)
//  input.ts(2, 7): 'aFoo' needs an explicit type annotation.

const _aBar = a.literal("bar")
const aBar: typeof _aBar = _aBar;
aBar(x); // works
let test1: "bar" = x

declare let y: unknown;
a.string(y) // works
let test2: string = y;

namespace a {
  export function literal<T>(t: InferLiteral<T>){
    return function(v: unknown): asserts v is T {
      if (v !== t) throw new Error()
    }
  }

  export function string(v: unknown): asserts v is string {
    if (typeof v !== "string") throw new Error();
  }
}
type InferLiteral<T> =
  | (T extends string ? T : string)
  | (T extends number ? T : number)
  | (T extends boolean ? T : boolean)

The reason stated in the PR is "This particular rule exists so that control flow analysis of potential assertion calls doesn't circularly trigger further analysis."

My question is, umm, what does this mean in more layman terms? My impression was it's to not allow recursive usage but looks like that's not the case because this compiles... So not sure what the above statement means

  namespace a {
    export function literal<T>(t: InferLiteral<T>){
      return function(v: unknown): asserts v is T {
+        let _aLol = a.literal("lol")
+        let aLol: typeof _aLol = _aLol;
+        let x = {} as unknown;
+        aLol(x)
+        let test: "lol" = x;
        if (v !== t) throw new Error()
      }
    }

Also I understand it's a "design limitation" but, excuse my ignorance, is it really that hard to lift it? Because it's quite annoying to make make two variables for the same function then annotated the other, makes me think "Eh why can't the compiler do this for itself" haha. Maybe lift the restriction in some scenarios?

📃 Motivating Example

💻 Use Cases

I was writing a fail-fast parser that basically composes assertion functions something like this... But I have to use the mentioned workaround. Even if this is too much of a feature request, an explanation why the requirement exists would make me feel less annoyed when I redeclare and annotate assertions :P

Playground (Hit on run to see the ParseError with message "At Person.age: Expected a number")

namespace a {
  export const string: Asserter<string> =
    (v, p) => invariant(typeof v === "string", "Expected a string", v, p)

  export const number: Asserter<number> =
    (v, p) => invariant(typeof v === "number", "Expected a number", v, p)
  
  export const object =
    <O extends { [_ in string]: Asserter }>(tO: O):
      Asserter<{ [K in keyof O]: O[K] extends Asserter<infer T> ? T : never }> =>
        (v, p) => {
          invariant((v): v is object => typeof v === "object", "Expected an object", v, p);
          for (let k in tO) {
            (tO[k] as any)((v as any)[k], `${p}.${k}`)
          }
        }
  
  export class ParseError extends Error {
    constructor(message: string, public actual: unknown, public path: string) {
      super(`At ${path}: ${message}`)
    }
  }

  function invariant(test: boolean, message: string, actual: unknown, path: string): void
  function invariant<T, U extends T>(test: (v: T) => v is U, message: string, actual: T, path: string): asserts actual is U
  function invariant<T>(test: (v: T) => boolean, message: string, actual: T, path: string): void
  function invariant(test: boolean | ((v: unknown) => boolean), message: string, actual: unknown, path: string) {
    if (typeof test === "function" ? !test(actual) : !test)
      throw new ParseError(message, actual, path);
  }
}
type Asserter<T = unknown> = (v: unknown, path: string) => asserts v is T


const _aPerson = a.object({ name: a.string, age: a.number })
const aPerson: typeof _aPerson = _aPerson;

let person = { name: "Devansh", age: true } as unknown;
aPerson(person, "Person");
let test: string = person.name

Comienza reproduciendo el comportamiento de las llamadas de aserción en el TypeScript Playground enlazado y lee la discusión referenciada en #32695. Sigue cómo el análisis de flujo de control gestiona las llamadas de aserción y determina el comportamiento previsto para las variables de función de aserción inferidas; el trabajo estará completo cuando incluya la semántica acordada, pruebas de regresión y ningún cambio no intencionado en JavaScript.