Stabilize `fs.cp()`, `fs.cpSync()`, `fsPromises.cp()` methods

[theoludwig]

What is the problem this feature will solve?

Currently, these methods are marked as Experimental (Stability: 1):

• fs.cp()
• fs.cpSync()
• fsPromises.cp()

There were no major changes since their introduction in Node.js v16.7.0, so it should be safe to mark them Stable (Stability: 2) as per the Stability index.

If somehow, these methods are still not ready to be stable, this is a tracking issue/roadmap to know what are the needed TODOs before marking them as stable.

What is the feature you are proposing to solve the problem?

Marking fs.cp(), fs.cpSync(), fsPromises.cp() methods as stable (Stability: 2).

For automated test purposes, mocking fs module is a must. Currently, the most used userland library for that is probably mock-fs, and doesn't support these methods. Before marking this API stable, Node.js should provide the needed feature(s) for mocking this API in userland, or even better, include mock-fs in Node.js core, this can be well suited with the new test_runner module.

Related issues: https://github.com/tschaub/mock-fs/issues/358, https://github.com/nodejs/node/issues/37746.

What alternatives have you considered?

I think it's best to avoid using experimental APIs, avoid warnings, and simply use features subject to semantic-versioning for easier Node.js upgrades.

The current workaround, I personally use and end up copy/pasting in several projects (too small to be an npm package IMO):

import fs from 'node:fs'
import path from 'node:path'

export const copyDirectory = async (
  source: string,
  destination: string
): Promise<void> => {
  const filesToCreate = await fs.promises.readdir(source)
  for (const file of filesToCreate) {
    const originalFilePath = path.join(source, file)
    const stats = await fs.promises.stat(originalFilePath)
    if (stats.isFile()) {
      const writePath = path.join(destination, file)
      await fs.promises.copyFile(originalFilePath, writePath)
    } else if (stats.isDirectory()) {
      await fs.promises.mkdir(path.join(destination, file))
      await copyDirectory(path.join(source, file), path.join(destination, file))
    }
  }
}

By marking this API as stable, I should be able to use it like this:

import fs from 'node:fs'

await fs.promises.cp(source, destination, { recursive: true })

[aduh95]

@nodejs/fs

[piedar]

:+1: This is a useful API, but the documentation regarding recursive directory copies should be clarified. It currently states

When copying a directory to another directory, globs are not supported and behavior is similar to cp dir1/ dir2/.

But this is not quite right, as cp -r dir1/ dir2/ copies dir1 into dir2 like ./dir2/dir1/. This command is actually more like cp -r --no-target-directory dir1/ dir2/ which copies the contents of dir1 into dir2.

[theoludwig]

Possible to stabilize them before v20? https://github.com/nodejs/node/pull/47381

[FStefanni]

Hi,

just to report a strange behavior, I am not sure if it is intended or a bug. When copy a file to a directory:

fsPromises.cp(
      sourceFile,
      destinationDir,
      {"recursive": true}
);

I get this error:

  code: 'ERR_FS_CP_NON_DIR_TO_DIR',
  info: {
    message: 'cannot overwrite non-directory /tmp/my-file.txt with directory /home/myuser',
    path: '/home/myuser',
    syscall: 'cp',
    errno: 20,
    code: 'ENOTDIR'
  },

To fix, I have to use:

fsPromises.cp(
      sourceFile,
      destinationDir + "/dstFileName.txt",
      {"recursive": true}
);

I was expecting a behavior basically as close as possible to the standard bash cp command... This is weird. Also, the message seems misleading, since it seems to do the opposite of the intended behavior.

My node is v20.2.0.

Regards

[github-actions[bot]]

There has been no activity on this feature request for 5 months and it is unlikely to be implemented. It will be closed 6 months after the last non-automated comment.

For more information on how the project manages feature requests, please consult the feature request management document.

[theoludwig]

Still relevant, as it's still not stable yet.

[github-actions[bot]]

There has been no activity on this feature request for 5 months. To help maintain relevant open issues, please add the https://github.com/nodejs/node/labels/never-stale label or close this issue if it should be closed. If not, the issue will be automatically closed 6 months after the last non-automated comment. For more information on how the project manages feature requests, please consult the feature request management document.

[theoludwig]

Should be worth adding the never-stale label to this issue, as the issue is relevant until these fs methods are marked as stable.