cp

This page describes @vooya/fs@0.1.1. See Node compatibility and execution policy for native fast paths, Node routes and verified limits.

Copy files and directories recursively. Supports concurrency (Vooya FS extension) for faster tree copy.

Basic usage

import { cp } from '@vooya/fs'
 
await cp('./src', './dest', { recursive: true })
await cp('./src', './dest', { recursive: true, force: true, concurrency: 4 })

Methods

cp(src, dest, options?)

Async. Returns Promise<void>.

UTF-8 Buffer paths are accepted by the native Unix Promise route as a Vooya extension. Node 22/24 Promise copy rejects Buffer paths on the delegated routes, including Windows and filter callbacks. Use strings or file URLs for portable copy calls; delegation preserves the Node error instead of silently converting its input.

Options: filter (sync or Promise callback), mode (copy flags), recursive (boolean), force (boolean, default true), errorOnExist, preserveTimestamps, dereference, verbatimSymlinks, concurrency (number, Vooya FS, default 1).

cpSync(src, dest, options?)

Sync. Returns undefined on success and throws on error. Its filter(src, dest) must return a boolean synchronously; Promise-returning filters are supported only by cp. The public entry calls Node directly. concurrency is validated but does not affect synchronous execution.

import { cpSync } from '@vooya/fs'
 
cpSync('./src', './dest', {
  recursive: true,
  filter: (src) => !src.endsWith('.map'),
})

The filter runs for directories as well as files. Returning false for a directory skips its contents. For asynchronous filtering, use await cp(...) instead.

Performance

See the current batch evidence for measured results.

The scale benchmark uses 4 workers. Tune this for your tree and storage; it is not a universal optimum.

Local scale report

Generated from local performance reports. Do not edit this block by hand.

• Runtime: v22.22.0 on darwin/arm64
• Samples: 2 warmup runs, 10 measured runs
• Aggregation: trimmed mean for wall-clock time; average per-run memory delta for RSS

Notes

• concurrency: Vooya FS extension. Increase (e.g. 4) for large directory trees; default is 1.
• Symlinks: Options dereference and verbatimSymlinks behave like Node.js. Recursive copy does not follow symlinks by default.

Compatibility routing

Promise copies use Rust for the common Unix path. Filters, dereference, copy modes, Windows and non-UTF-8 paths use Node. cpSync uses Node’s native implementation, whose symlink behavior differs from the Promise implementation on supported runtimes. force: true takes precedence over errorOnExist. Copying a path onto itself or into its descendants rejects before destination creation.

Competitor measurements

See the full cp comparison table for Node 22/24, peer libraries, sync/Promise modes, small and batch workloads, execution routes and measurement limits.