BREAKING: refactor(std): Prepend underscores to private modules

[nayeemrmn]

• Move std/util/async.ts to std/async/*.ts.
• Move std/util/sha*.ts to std/hash/sha*.ts.
• Move flags example to std/examples.
• Remove isWindows and EOL from std/path. They don't belong there and shouldn't really require a dependency.
  • Closes Discussion : path.isWindows std#629.
• Remove collectUint8Arrays() from std/util/async.ts. It would be a misuse of Deno.iter()'s result.

[uki00a]

@nayeemrmn
As far as I know, std/util/async.ts is used by deno-redis and deno-postgres.
Shouldn't this file be treated as a public module?

[nayeemrmn]

@ry Please review.

[ry]

LGTM - sorry for the delay @nayeemrmn - Bartek Bert and I had a discussion yesterday about std and stability. We decided to decouple the version from cli and not make stability guarantees yet (#5158). That discussion was holding up landing this patch.

[keroxp]

@ry @nayeemrmn I found some files were made underscored on this PR. What does it mean?
Should we consider them as internal module and prevent developer to use? Those files are still downloadable🤔

About http/io.ts, when I created this, it was designed to be public module for who creates their own http server implementation.

[ry]

underscore means the module should be considered private
https://github.com/denoland/deno/blob/master/docs/contributing/style_guide.md#if-a-filename-starts-with-an-underscore-_foots-do-not-link-to-it

I think http/io.ts was erroneously marked as private, we can make it public again.

[nayeemrmn]

Should we consider them as internal module and prevent developer to use? Those files are still downloadable🤔

Yes. There's no way of making them not downloadable which is why we use the underscore convention to indicate that the exports aren't stable / can be restructured by us at will -- so shouldn't be imported directly.

About http/io.ts, when I created this, it was designed to be public module for who creates their own http server implementation.

The exports of that module have no rhyme or reason at the moment and are definitely tailored to internal usage. For example, emptyReader() doesn't belong there. readRequest() has this weird behaviour where a reader is passed as input, but the writer is assigned externally. It's certainly not ready to be part of any public API.

If anyone is interested, they can make a public io.ts and slowly move over exports refactored to make independent sense.

[keroxp]

@nayeemrmn I agree that current readRequest and ServerRequest implementation is not good, but It is not tailored just for internal usage. Some functionalities in io.ts were originally ported from my project (servest) and currently depends on them (readTrailer, writeTrailer, bodyReader, chunkedBodyReader ) . They can be useful in some situations because they're designed to be pure function as possible. I know few people are using them, but I'll have a trouble if they become not available😓.

I think emptyReader() is very useful for testing so it should be moved into io/readers.ts.