Add support for reading/writing with multiple encodings

[icidasset]

With Webnative 0.35 you can only read and write Uint8Arrays.
There should be support for other encoding, such as UTF8 strings.

@matheus23 suggested the encoding option from https://nodejs.org/api/fs.html#filehandlereadfileoptions

We could do something like:

fs.write({ bytes: Uint8Array })
fs.write({ text: "Text", encoding: "utf8" })

[matheus23]

This may be a duplicate of #269 now.

I'm biased, but I'd vouch for the 2 positional parameters and an optional third "options" parameter that contains the { encoding: "utf8" } object (as I've suggested in that issue).
For read this looks like: fs.read(path, { encoding: "utf8" }).
This means it's less of a breaking change & it's potentially more familiar to JS developers.

For write, I feel like we have the option of "auto-detecting" the encoding. I.e. if a string is passed, we assume UTF8.
However, that may not be ideal: It may be surprising that .write accepts a string but subsequently returns a Uint8Array if the same file is .read.
So perhaps, it'd make sense to only allow passing a string if the encoding parameter is explicitly set to UTF8.

So, personally I'd be in favor of these types:

fs.read(path: FilePath): Promise<Uint8Array>
fs.read(path: FilePath, options: { encoding: "utf8" }): Promise<string>

fs.write(path: FilePath, bytes: Uint8Array)
fs.write(path: FilePath, text: string, options: { encoding: "utf8" })

[icidasset]

Oh whoops, forgot about that issue.

fs.write(path: FilePath, bytes: Uint8Array)
fs.write(path: FilePath, text: string, options: { encoding: "utf8" })

That works too yeah, I have no strong preference.

So perhaps, it'd make sense to only allow passing a string if the encoding parameter is explicitly set to UTF8.

Yes exactly, that's what I was trying to achieve as well. I assumed it'd be easier to do in Typescript with my syntax, rather than yours, but I could be wrong. But yeah, your syntax is more familiar.

[matheus23]

Yes exactly, that's what I was trying to achieve as well. I assumed it'd be easier to do in Typescript with my syntax, rather than yours, but I could be wrong. But yeah, your syntax is more familiar.

You are correct about that version being harder, but it's still possible. Here's how node.js defines the readFile type:
https://github.com/DefinitelyTyped/DefinitelyTyped/blob/4805c8405fb64154def301a763c40328ccfb612c/types/node/fs.d.ts#L2532-L2554

Essentially it'd boil down to function type overloading. Something like this in our case:

export function read(path: FilePath): Promise<Uint8Array>;
export function read(path: FilePath, options: { encoding: "utf8" }): Promise<string>;
export function read(path: FilePath, options?: { encoding?: string }): Promise<Uint8Array | string> {
  // impl
}

[icidasset]

Oh you can do function overloading in Typescript?! How did I not know this 😲
Ok yeah, that's better 👍

[icidasset]

Implemented in #500
Part of #501