Deno: API changes

[ry]

gathered from notes in https://github.com/denoland/deno/pull/4882

Hint: Ops are made unstable using State::check_unstable (example)

• [x] Deno.Buffer.toString() should be removed (#4992)
• [x] Deno.Buffer shouldn't implement async read/write (#4960) Needs further discussion because Buffer won't be able to use copy.
• [x] update d.ts for "sanitizeOps" // Defaults to false
• [x] Remove export function test(fn: () => void | Promise<void>): void; (#4951)
• [x] Make TestMessage, RunTestsOptions secret internal #4869
• [x] Deno.loadavg should be unstable - There are questions around which permission this needs. And maybe should be renamed (loadAverage?) https://github.com/denoland/deno/pull/4938
• [x] Deno.osRelease() should be unstable. new API maybe move to Deno.build or Deno.versions? Depends on sys-info, which we don't necessarily want to depend on. https://github.com/denoland/deno/pull/4938
• [x] Deno.env... Use Map like API. (#4942) https://github.com/denoland/deno/pull/4882#discussion_r414907148
• [x] Deno.dir should be unstable - maybe renamed to Deno.systemPath? #4924
• [x] Deno.chdir - Need allow-read check, then is stable. (#4956) not needed f8d83361cd11d3aa42333171ecb6b129fdcbefeb
• [x] Deno.umask - Needs unstable ttps://github.com/denoland/deno/pull/4935
• [x] Should be Deno.SeekMode.Start and Deno.SeekMode.Current Then can be made stable. (#4946)
• [x] Rename SyncReader to ReaderSync (SyncWriter, SyncSeeker) (#4945)
• [x] Remove these combined interfaces replace EG ReadCloser with Reader & Closer (#4944)
• [x] Deno.copy reorder arguments #4900 #4885
• [x] Deno.iter should take options argument instead of bufSize, #4890
• [x] Remove the "w+" version of open #4884
• [x] Replace interface Stdin with Reader & SyncReader & Closer & { rid: number } (also stdout, stderr) (#4952)
• [x] Make Deno.isatty stable (errnoously made unstable in #4925) https://github.com/denoland/deno/pull/4937
• [x] utime/utimeSync should be made unstable https://github.com/denoland/deno/pull/4955
• [x] Deno.FileInfo isFile, isDirectory, isSymlink should be getter methods to match node's api https://nodejs.org/api/fs.html#fs_class_fs_stats https://github.com/denoland/deno/pull/4932
• [x] Deno.FileInfo make modified, accessed, created to Date objects. should we rename to match node's fields? modified -> mtime, accessed -> atime, created -> birthtime https://github.com/denoland/deno/pull/4932
• [x] Deno.DirEntry should not extend FileInfo but include a member called "info" which has the stat info. This allows us in the future to potentially not include this for a light weight version of readdir which does not call stat on each file. (#4941)
• [x] linkSync, link, symlinkSync, symlink should be made unstable due to security concerns #4892
• [x] UnixAddr UnixConnectOptions UnixListenOptions should have address renamed to path (#4959)
• [x] Deno.shutdown should be made unstable and should be async. https://github.com/denoland/deno/pull/4940
• [x] Remove Deno.closeRead and Deno.closeWrite should be unstable. https://github.com/denoland/deno/pull/4970
• [x] Deno.listener - when breaking out of async iterator it should use the return method of async iterator to close the listener. (#4976)
• [x] Deno.listener should be broken into Deno.listenDatagram for udp and unixpacket. listenDatagram should be unstable. (#4968)
• [x] Rename ListenTLSOptions to ListenTlsOptions (also listenTLS, ConnectTLSOptions, connectTLS) #4888
• [x] Deno.connect - unix sockets should also require allow-write. https://github.com/denoland/deno/pull/4939
• [x] Deno.startTls should be made unstable. certFile might need allow-read permission. you should be able to provide string for cert rather than path. (this is a feature that extends interface, shouldn't be done now) (#4965)
• [x] Deno.Metrics should be made stable. https://github.com/denoland/deno/pull/4949
• [x] Deno.resources should be stable and ResourceMap should have any instead of string #4893
• [x] Rename Deno.fsEvents to Deno.watchFs #4886
• [x] Deno.Process.kill should be unstable. https://github.com/denoland/deno/pull/4950
• [x] ProcessStatus should have three variants | { success: false; signal: number; } (#4966) Doesn't work as well as we had thought.
• [x] RunOptions should be made stable
• [x] InspectOptions remove because non-functional, but inspect can be made stable. (#4967)
• [x] import maps should be unstable #4931
• [x] Update Deno.build to use LLVM target triple somehow https://clang.llvm.org/docs/CrossCompilation.html. https://github.com/denoland/deno/pull/4948
• [x] Remove Deno.symbols namespace, move Deno.symbols.customInspect to Deno.customInspect. Remove Deno.symbols.internal from d.ts file. https://github.com/denoland/deno/pull/4936
• [x] Deno.EOF stays. Update docs. Or remove https://github.com/denoland/deno/pull/4953

[nayeemrmn]

Deno.FileInfo isFile, isDirectory, isSymlink should be getter methods to match node's api https://nodejs.org/api/fs.html#fs_class_fs_stats #4932

-1. They are simple constants just like everything else in FileInfo. If the problem is that these values need to agree with each other, we should just model it properly with

interface FileInfo {
  type: "file" | "directory" | "symlink";
  // ...
}

[shian15810]

For things like import maps, isn't it should be experimental rather than unstable?

Could there be a specific flag to opt in to a specific experimental feature, in this case import maps, rather than --unstable which would opt me in to all unstable APIs?

Edited: The original --importmap has already implied an intention to opt in this feature.

[kitsonk]

@shian15810 lets move the discussion over to #4958, so we don't overload this issue.

[ry]

Thanks for the help everyone, we completed the API changes. We are tentatively API stable now.

[luvies]

I know 1.0 is coming very soon, but was there any consideration on @nayeemrmn's idea of using

type: "file" | "directory" | "symlink"

instead of the current multiple field method? It's much more ergonomic and works nicely with typescript's discrimination testing (like filtering for items with specific names and types). Since isFile, isDirectory and isSymlink are mutually exclusive, it makes much more sense in terms of typing to do this (the current fields look, at a glance, that they might not but mutually exclusive).