feat: generate InternalFetch signature

[danielroe]

🔗 Linked issue

❓ Type of change

• 📖 Documentation (updates to the documentation, readme, or JSdoc annotations)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

This PR reworks how our internal API routes are typed. This aims to do more of the work at build time rather than asking typescript to do it. Testing in our fixture showed type-checking speed improvement of up of 45%.

Note: The reason that this is so much faster is that we use function overloads, which means that we do not yet support all the matching patterns that our existing type-only algorithm does. It matches only one result so if you have multiple overlapping patterns, like /api/test/**/thing and /api/test/bob/thing then if you request $fetch('/api/test/${someUnknownString}') then we won't be able to give a union of the two return times as before.

It adds the following type-safety functionalities:

• it will throw a type error if you make a request that needs a specific method without an options object with that method defined
• it will throw a type error if you make a request that needs specific input types without those values
• type error if you make a request that needs specific input types without an options object
• when $fetch.create is called with a baseURL, the result is not strongly typed but just a normal external $fetch

Further enhancements needed:

• auto-completion when used with endpoints with typed inputs (this would be very desirable for better DX)

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[codecov]

Codecov Report

Merging #1532 (7290307) into main (7fa8408) will increase coverage by 0.27%.
Report is 1 commits behind head on main.
The diff coverage is 100.00%.

❗ Current head 7290307 differs from pull request most recent head 2cc871f. Consider uploading reports for the commit 2cc871f to get more accurate results

@@            Coverage Diff             @@
##             main    #1532      +/-   ##
==========================================
+ Coverage   76.49%   76.76%   +0.27%     
==========================================
  Files          73       73              
  Lines        7580     7671      +91     
  Branches      751      768      +17     
==========================================
+ Hits         5798     5889      +91     
  Misses       1781     1781              
  Partials        1        1              

Files Changed	Coverage Δ
src/build.ts	87.58% <100.00%> (+1.64%)	⬆️
src/types/fetch.ts	100.00% <100.00%> (ø)

[manniL]

Note: The reason that this is so much faster is that we use function overloads, which means that we do not yet support all the matching patterns that our existing type-only algorithm does. It matches only one result so if you have multiple overlapping patterns, like /api/test/**/thing and /api/test/bob/thing then if you request $fetch('/api/test/${someUnknownString}') then we won't be able to give a union of the two return times as before.

Will this be possible in the future with the function overloading approach?

[septatrix]

Will it be possible with the way it is implemented in this PR to augment the OpenAPI documentation #1162?

[ImBoop]

This PR has been outstanding as a draft for a year now, are there any updates you can share?

[pi0]

This is taking longer than expected because we are working on a better standard ecosystem-wise and testable solution.

I have created a tracker issue: #2758

(closing this one mainly for triage, let's keep track via issue)