API changes

[ry]

gathered from notes in #4882

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

• Deno.Buffer.toString() should be removed (BREAKING: remove custom implementation of Deno.Buffer.toString() #4992)
• Deno.Buffer shouldn't implement async read/write (Make Deno.Buffer implement only sync I/O #4960) Needs further discussion because Buffer won't be able to use copy.
• update d.ts for "sanitizeOps" // Defaults to false
• Remove export function test(fn: () => void | Promise<void>): void; (BREAKING: remove overload of Deno.test() #4951)
• Make TestMessage, RunTestsOptions secret internal fix: remove bootstrap methods from global scope after bootstrapping #4869
• Deno.loadavg should be unstable - There are questions around which permission this needs. And maybe should be renamed (loadAverage?) loadavg and osRelease made unstable #4938
• 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. loadavg and osRelease made unstable #4938
• Deno.env... Use Map like API. (Map-like interface Deno.env #4942) Complete API review - marked up the d.ts file with many comments. #4882 (comment)
• Deno.dir should be unstable - maybe renamed to Deno.systemPath? Make Deno.dir unstable #4924
• Deno.chdir - Need allow-read check, then is stable. (require --allow-read for chdir #4956) not needed f8d8336
• Deno.umask - Needs unstable ttps://github.com/Mark Deno.umask unstable #4935
• Should be Deno.SeekMode.Start and Deno.SeekMode.Current Then can be made stable. (refactor: rename SeekMode variants to camelCase and stabilize #4946)
• Rename SyncReader to ReaderSync (SyncWriter, SyncSeeker) (refactor: rename sync io interfaces #4945)
• Remove these combined interfaces replace EG ReadCloser with Reader & Closer (remove combined io interface like ReadCloser #4944)
• Deno.copy reorder arguments reorder copyN arguments to match Deno.copy #4900 BREAKING CHANGE: change order of args in Deno.copy() #4885
• Deno.iter should take options argument instead of bufSize, stabilize Deno.iter() and Deno.iterSync() #4890
• Remove the "w+" version of open BREAKING CHANGE: remove Deno.OpenMode #4884
• Replace interface Stdin with Reader & SyncReader & Closer & { rid: number } (also stdout, stderr) (refactor: remove stdio interfaces, use intersection types #4952)
• Make Deno.isatty stable (errnoously made unstable in Make Deno.setRaw and Deno.isatty unstable #4925) Remove check_state from isatty op #4937
• utime/utimeSync should be made unstable make utime unstable #4955
• Deno.FileInfo isFile, isDirectory, isSymlink should be getter methods to match node's api https://nodejs.org/api/fs.html#fs_class_fs_stats Rename FileInfo time fields and represent them as Date objects #4932
• Deno.FileInfo make modified, accessed, created to Date objects. should we rename to match node's fields? modified -> mtime, accessed -> atime, created -> birthtime Rename FileInfo time fields and represent them as Date objects #4932
• 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. ( Include limited metadata in 'DirEntry' objects #4941)
• linkSync, link, symlinkSync, symlink should be made unstable due to security concerns introduce unstable flag, make a few things unstable #4892
• UnixAddr UnixConnectOptions UnixListenOptions should have address renamed to path (Unix address rename to path #4959)
• Deno.shutdown should be made unstable and should be async. Make shutdown unstable and async #4940
• Remove Deno.closeRead and Deno.closeWrite should be unstable. Remove Conn.closeRead #4970
• Deno.listener - when breaking out of async iterator it should use the return method of async iterator to close the listener. (refactor: Deno.listener closes when breaking out of async iterator #4976)
• Deno.listener should be broken into Deno.listenDatagram for udp and unixpacket. listenDatagram should be unstable. (refactor: factor out datagram listeners, make them unstable #4968)
• Rename ListenTLSOptions to ListenTlsOptions (also listenTLS, ConnectTLSOptions, connectTLS) BREAKING CHANGE: rename TLS APIs to camel case #4888
• Deno.connect - unix sockets should also require allow-write. Make unix sockets require allow-write #4939
• 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) (mark Deno.startTls as unstable #4965)
• Deno.Metrics should be made stable. doc: remove unstable API marker form Deno.Metrics and Deno.RunOptions #4949
• Deno.resources should be stable and ResourceMap should have any instead of string BREAKING CHANGE: change return type of Deno.resources() #4893
• Rename Deno.fsEvents to Deno.watchFs BREAKING CHANGE: rename Deno.fsEvents() to Deno.watchFs() #4886
• Deno.Process.kill should be unstable. Make Deno.kill unstable #4950
• ProcessStatus should have three variants | { success: false; signal: number; } (split ProcessStatus into three variants #4966) Doesn't work as well as we had thought.
• RunOptions should be made stable
• InspectOptions remove because non-functional, but inspect can be made stable. (refactor: change InspectOptions, make Deno.inspect stable #4967)
• import maps should be unstable discussion: Import maps should be an unstable feature #4931
• Update Deno.build to use LLVM target triple somehow https://clang.llvm.org/docs/CrossCompilation.html. llvm target triple for Deno.build #4948
• Remove Deno.symbols namespace, move Deno.symbols.customInspect to Deno.customInspect. Remove Deno.symbols.internal from d.ts file. Remove Deno.symbols namespace 2 #4936
• Deno.EOF stays. Update docs. Or remove refactor(cli/js/io): Remove Deno.EOF, use null instead #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).