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

Functions

• chmod feat(fs/unstable): add chmod and chmodSync #6343
• chmodSync feat(fs/unstable): add chmod and chmodSync #6343
• chown
• chownSync
• copyFile feat(fs/unstable): add copyFile and copyFileSync #6425
• copyFileSync feat(fs/unstable): add copyFile and copyFileSync #6425
• create
• createSync
• link feat(fs/unstable): add link and linkSync #6369
• linkSync feat(fs/unstable): add link and linkSync #6369
• lstat feat(fs/unstable): add fs.lstat #6276
• lstatSync feat(fs/unstable): add statSync and lstatSync #6300
• makeTempDir feat(fs/unstable): add makeTempDir and makeTempDirSync #6391
• makeTempDirSync feat(fs/unstable): add makeTempDir and makeTempDirSync #6391
• makeTempFile
• makeTempFileSync
• mkdir feat(fs/unstable): add mkdir and mkdirSync #6436
• mkdirSync feat(fs/unstable): add mkdir and mkdirSync #6436
• open
• openSync
• readDir feat(fs/unstable): add readDir #6338
• readDirSync feat(fs/unstable): add readDirSync #6381
• readFile feat(fs/unstable): add readFile and readFileSync #6394
• readFileSync feat(fs/unstable): add readFile and readFileSync #6394
• readLink feat(fs/unstable): add readLink and readLinkSync #6373
• readLinkSync feat(fs/unstable): add readLink and readLinkSync #6373
• readTextFile feat(fs/unstable): add readTextFileSync and readTextFile #6405
• readTextFileSync feat(fs/unstable): add readTextFileSync and readTextFile #6405
• realPath feat(fs/unstable): add realPath and realPathSync #6366
• realPathSync feat(fs/unstable): add realPath and realPathSync #6366
• remove feat(fs/unstable): add remove and removeSync api. #6438
• removeSync feat(fs/unstable): add remove and removeSync api. #6438
• rename feat(fs/unstable): add rename #6379
• renameSync feat(fs/unstable): add renameSync #6396
• stat feat(fs/unstable): add fs.stat #6258
• statSync feat(fs/unstable): add statSync and lstatSync #6300
• symlink feat(fs/unstable): add symlink and symlinkSync #6352
• symlinkSync feat(fs/unstable): add symlink and symlinkSync #6352
• truncate feat(fs/unstable): add truncate and truncateSync #6416
• truncateSync feat(fs/unstable): add truncate and truncateSync #6416
• umask feat(fs/unstable): add umask #6454
• utime feat(fs/unstable): add utime and utimeSync #6446
• utimeSync feat(fs/unstable): add utime and utimeSync #6446
• watchFs
• writeFile feat(fs/unstable): add writeFile and writeFileSync #6444
• writeFileSync feat(fs/unstable): add writeFile and writeFileSync #6444
• writeTextFile feat(fs/unstable): add writeTextFile and writeTextFileSync #6463
• writeTextFileSync feat(fs/unstable): add writeTextFile and 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.