improve overloads support, attempt 2

[mmkal]

Related to #58
Related to #30

Improve support for overloaded functions (up to 10 overloads). So for an example function type:

type Factorize = {
  (input: number): number[]
  (input: bigint): bigint[]
}

---

.parameters gives you an ExpectTypeOf instance with a union of the parameter-tuple types, so:

expectTypeOf<Factorize>().parameters.toEqualTypeOf<[number] | [bigint]>()

---

.returns gives you an ExpectTypeOf instance with a union of the return types, so

expectTypeOf<Factorize>().returns.toEqualTypeOf<number[] | bigint[]>()

---

.toBeCallableWith(...) now accepts any overload input, not just the "last" like before. And you can now chain it via .returns which gives you the matching return type:

expectTypeOf<Factorize>().toBeCallableWith(5).returns.toEqualTypeOf<number[]>()

---

Implementation

• overload utilities were added
  • initially, I thought all that was needed was a utility that matches F typeargs against a single 10-overload type
  • but the test-types job caught that this doesn't work for typescript <5.3
  • for lower typescript versions, it seems we need an approach more like the one in Support function overloads #58
  • there are some edge cases the tests found for generic functions and parameterless functions, so there is sometimes some "useless" overload info that has to be explicitly excluded
  • there are a couple of intermediate utilities to check if the 10-overload type can be used, and to exclude "useless" overloads
• equivalents added for constructor parameters too
• used the overloaded versions in DeepBrand too

update: moved these changes to #93 to reduce diff

• I felt the megafile index.ts was finally getting too big with the added overload utilties:
  • so those were put in a new overloads.ts
  • since overload utils they rely on some other existing utils, I created utils.ts to avoid circular references
  • index.ts remains as the home for the main ExpectTypeOf exports
  • added export * from './utils' since we have been exporting all the internal utils and I don't want to break people
  • update: moved these changes to create utils file #93 to reduce diff

[aryaemami59]

Sorry I took too long with #58. Does this supersede that one?

[mmkal]

Yes, I wrote this using that as a reference, I'd like it to be a replacement yeah. Need to go through carefully and make sure nothing is dropped between the two though.

[aryaemami59]

Gotcha, I will look through it soon.

[mmkal]

@aryaemami59 I've updated the description of this pull request to explain what's going on in it better, both in terms of the API surface change, and the implementation. Worth having a look at if you're planning on diving into the code.

Would be great to get your thoughts on whether you think this is a good idea, or whether it's too much complexity.

I think it's quite possible there are more edge cases around generics etc., and it could get out of hand if there's more edge case handling needed. On the other hand, kind of the point of this library is to abstract that kind of complexity away from regular typescript users who just want to test their types in a sensible way, so maybe the more complex it is, the more value this library is bringing - even if it does become harder to maintain.

CC @trevorade @sheremet-va @y-polonsk in case you want to weigh in too.

[aryaemami59]

@mmkal, I'm going to take a deep dive today and will let you know my full thoughts on it.

Here are my initial thoughts:

• I really like that you can now chain toBeCallableWith() with .returns. I think this is something we should explore and possibly use more often.
• If .parameters now requires a union of parameter-tuple types and .returns requires a union of return types, does this mean it will cause a breaking change? If so, do you think this is something we should add as an opt-in feature?

[mmkal]

Yes, it could be considered a breaking change since assertions that are currently passing would start failing. But I don't think it should be configurable because:

1. It would add maintenance and API surface complexity and not really add any value other than backcompat
2. People who want the old behaviour for some reason can still get it using the built in Parameters<...> etc.
3. Arguably the assertions that start newly failing are already probably hiding a missing bug so in a way it's the opposite of a breaking change (given this is a testing library)
4. The library is still v0

[mmkal]

Updates since last time:

• convert overloads to a union of functions rather than a tuple
• various simplifications that fall out of that
• constructor parameters support in a similar way
• some non-readme tests in types.test.ts

Next:

• use the overload helpers in DeepBrand - currently it won't distinguish between overloaded functions and we should be consistent

[aryaemami59]

Alright let's get this in.