Port File System APIs in Deno namespace to `@std/fs`

[kt3k]

We aim to make @std/fs cross-runtime (ref #4313). To achieve that we need to port FS APIs from Deno namespace (with Node.js compatibility)

• Deno FS APIs https://docs.deno.com/api/deno/file-system
• deno-shim https://github.com/denoland/node_shims/tree/main/packages/shim-deno/src/deno/stable/functions

Classes

• [ ] FsFile #6524
  • [x] close #6524
  • [x] isTerminal #6524
  • [ ] lock
  • [ ] lockSync
  • [x] read #6524
  • [x] readSync #6524
  • [ ] setRaw
  • [x] stat #6524
  • [x] statSync #6524
  • [x] sync #6524
  • [x] syncSync #6524
  • [x] syncData #6524
  • [x] syncDataSync #6524
  • [x] truncate #6524
  • [x] truncateSync #6524
  • [ ] unlock
  • [x] utime #6524
  • [x] utimeSync #6524
  • [x] write #6524
  • [x] writeSync #6524

Functions

• [x] chmod #6343
• [x] chmodSync #6343
• [x] chown #6552
• [x] chownSync #6552
• [x] copyFile #6425
• [x] copyFileSync #6425
• [x] create #6600
• [x] createSync #6600
• [x] link #6369
• [x] linkSync #6369
• [x] lstat #6276
• [x] lstatSync #6300
• [x] makeTempDir #6391
• [x] makeTempDirSync #6391
• [x] makeTempFile #6469
• [x] makeTempFileSync #6469
• [x] mkdir #6436
• [x] mkdirSync #6436
• [x] open #6524
• [x] openSync #6524
• [x] readDir #6338
• [x] readDirSync #6381
• [x] readFile #6394
• [x] readFileSync #6394
• [x] readLink #6373
• [x] readLinkSync #6373
• [x] readTextFile #6405
• [x] readTextFileSync #6405
• [x] realPath #6366
• [x] realPathSync #6366
• [x] remove #6438
• [x] removeSync #6438
• [x] rename #6379
• [x] renameSync #6396
• [x] stat #6258
• [x] statSync #6300
• [x] symlink #6352
• [x] symlinkSync #6352
• [x] truncate #6416
• [x] truncateSync #6416
• [x] umask #6454
• [x] utime #6446
• [x] utimeSync #6446
• [ ] watchFs
• [x] writeFile #6444
• [x] writeFileSync #6444
• [x] writeTextFile #6463
• [x] writeTextFileSync #6463

shim-deno package already implements Node.js compatible Deno APIs. We can borrow the code from there for the Node.js compatibility part https://github.com/denoland/node_shims/tree/main/packages/shim-deno

[eryue0220]

Are unlink and unlinkSync ignored?

[kt3k]

It looks like Deno doesn't have unlink and unlinkSync. Instead it has remove and removeSync. This list tries to mirror Deno FS APIs.

[eryue0220]

Considering compatibility with Node, should fs.unlink and fs.unlinkSync also be provided?

[kt3k]

Do you suggest unlink would be an alias to remove?

[eryue0220]

Yes, except for compatibility, link and unlink is a pair, which is make more sense and more understandable than remove. WDYT?

[kt3k]

Looked at the docs again, (Deno's) remove has an option like recursive (it can remove the entire directory), but unlink (of Node) doesn't. I feel unlink can't replace remove, and it feels like a limited version of remove.

BTW Node.js also has rm which is similar to Deno's remove.

[jbronder]

TLDR: As a general question, should there be stronger checking of arguments when using the new @std/fs APIs under a Node.js runtime?

For example, the symlink and symlinkSync APIs in Node.js accept string | URL | Buffer types for path and target parameters whereas for Deno, the same APIs would require string | URL types (no Buffer) for these parameters. To meet the design intent of @std/fs APIs satisfying Deno's version of this API, would it be sensible to require rejecting/throwing with TypeErrors when passing Buffer objects when using the @std/fs APIs under a Node.js runtime? TypeError Buffer checking would also affect other @std/fs APIs: rename[Sync], realPath[Sync], et al.

Similarly, the Node.js versions of readFile[Sync] and writeFile[Sync] accept string | URL | Buffer | FileHandle/number (number for file descriptors, fd) types for the path parameter. When compared with Deno, path is restricted to string | URL types. TypeErrors would similarly need to be implemented when attempting to pass Buffer and FileHandle/fd types in the @std/fs versions of read[Text]File[Sync] and write[Text]File[Sync] when running Node.js.

I can either share a proposed approach for error checking here or in a forthcoming PR, whichever you prefer. I'd also be curious to know what your thoughts are about adding TypeError checking for these APIs when running under Node.js.