feat(testing/unstable): add type test for mutual assignability

[KnorpelSenf]

If you write complex types, you often have large unions that you want to narrow down according to some rules. Testing these types therefore requires you to check if the union was narrowed down correctly.

When your union types get complex enough, it is no longer feasible to work with Extract because it iterates the union type and checks assignability with each union member. This takes too long for any practical applications. Instead, a better approach is to use type intersections with union types. The TypeScript compiler is very fast at narrowing down such structures.

However, even though the resulting types work correctly, they are structurally different from the types Extract produces. In a nutshell, Extract<string | RegExpMatchArray, string> produces string while (string | RegExpMatchArray) & string isn't simplified further.

Currently, std provides no way of testing these types. Using Has does not check if the union type was narrowed down correctly, and using IsExact fails for intersections of unions despite mutual assignability.

This pull request fills that gap. It adds a new type for type testing called IsMutuallyAssignable. This new type checks if the two provided type parameters are assignable to each other, no matter how they are produced.

This is often less strict than IsExact because the two type parameters are allowed to have a different structure as long as they are assignable to each other. This is often more strict than Has because none of the two type parameters may be a union that contains the other, as this would fail the check for mutual assignability.

// false because E is not assignable to A
assertType<IsMutuallyAssignable<string & RegExpMatchArray, string>>(false);
// false because A is not assignable to E
assertType<IsMutuallyAssignable<string | RegExpMatchArray, string>>(false);
// true because both types are assignable to each other
assertType<IsMutuallyAssignable<string | (string & RegExpMatchArray), string>>(true);

[CLAassistant]

All committers have signed the CLA.

[KnorpelSenf]

I'm open to renaming the type. It is very descriptive now IMO, but it's also a bit long.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.52%. Comparing base (ff6037a) to head (ba50803).
Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6154   +/-   ##
=======================================
  Coverage   96.51%   96.52%           
=======================================
  Files         536      536           
  Lines       40765    40765           
  Branches     6118     6118           
=======================================
+ Hits        39346    39347    +1     
+ Misses       1375     1374    -1     
  Partials       44       44           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[kt3k]

Sounds a fair suggestion to me.

Can you move this API to the file of the name unstable_types.ts (and link it as unstable-types in testing/deno.json) as we want to separate stable features and new (unstable) features.

[KnorpelSenf]

Done!

[kt3k]

LGTM. Thanks!

[KnorpelSenf]

@kt3k can you link me to a place where I can read about the stabilization process? I only found a single sentence in the contribution guide that says that things will be stabilized “after receiving sufficient feedback from the community and the core team” … is there a place where this is being elaborated?

[kt3k]

We haven't defined the process yet

[KnorpelSenf]

Alright! I'll just follow along with the JSR meetings then