BREAKING(encoding/unstable): Replace encodeRaw with encodeInto & Remove decodeRaw

[BlackAsLight]

This pull request makes three breaking changes:

1. Rename calcMax to calcBase64Size.
   • In my opinion this is a better name than calcMax as it isn't even calculating the max size, but more the minimum required for the previous function to work.
2. Replace encodeRawBase64 with encodeBase64Into.
   • The encodeRawBase64 was in my opinion too complicated for people to use and had very narrow usage requiring the user to first structure their code in very specific way before passing it to this function. This replacement function now does a lot of that heavy lifting for the user. Giving them a much neater and nicer API to deal with. To accomplish these changes two other unrelated bits of code had to also change:
     1. Several constant variables in unstable_base64.ts were moved to _common64.ts with the user facing ones being reexported at unstable_base64.ts.
     2. Base64EncoderStream and Base64DecoderStream were made to rely directly on _common64.ts, removing it's dependency on unstable_base64.ts and in turn, encodeRawBase64 and decodeRawBase64.
3. Remove decodeRawBase64.
   • After further consideration, and with the changes made with the previous point, I didn't see a point in this function existing. A decodeBase64Into also wouldn't be possible given the current structure how the underlying code works.

These same changes were also applied to base32 and hex.

[codecov]

Codecov Report

Attention: Patch coverage is 93.98907% with 11 lines in your changes missing coverage. Please review.

Project coverage is 95.28%. Comparing base (61f9fd3) to head (fe83c8b).

Files with missing lines	Patch %	Lines
encoding/unstable_base32_stream.ts	80.00%	4 Missing ⚠️
encoding/unstable_base32.ts	92.00%	2 Missing ⚠️
encoding/unstable_base64.ts	92.30%	2 Missing ⚠️
encoding/unstable_hex.ts	91.66%	2 Missing ⚠️
encoding/unstable_hex_stream.ts	92.85%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6513      +/-   ##
==========================================
- Coverage   95.29%   95.28%   -0.02%     
==========================================
  Files         576      576              
  Lines       43315    43348      +33     
  Branches     6477     6485       +8     
==========================================
+ Hits        41279    41304      +25     
- Misses       1995     2003       +8     
  Partials       41       41              

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[kt3k]

I'm in favor of the idea. encodeInto looks much easier to use than encodeRaw.

Some suggestions about the names. How about calcSizeBase64 and encodeIntoBase64 instead of calcBase64Size and encodeBase64Into? The encoding name in the middle feels a bit strange to me. What do you think?

[BlackAsLight]

Those names do sound better

[timreichen]

I am not a big fan of calc in the names since it is never used in any js web API, only css. If we rename them, maybe we could do something similar to getBoundingClientRect() or getComputedStyle(), for example getSizeOfBase64().

[BlackAsLight]

I am not a big fan of calc in the names since it is never used in any js web API, only css.

I don't think that is a fair comparison since what web APIs are there that offer similar functionality?

For example, if you wanted to use TextEncoder.encodeInto, to be safe you need to know that the buffer you're encoding into needs to have at least 3x the length of the string you're encoding. I don't know of a function available to abstract this calculation for you. Instead you're required to know how UTF-16 translates to UTF-8.