CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-ncp

Asynchronous recursive file copy utility for Node.js with configurable concurrency and filtering options.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

ncp

ncp (Node Copy) is an asynchronous recursive file and directory copying utility for Node.js that serves as a pure JavaScript alternative to the Unix cp -r command. It provides both programmatic API and command-line interface functionality with advanced features like concurrency control, file filtering, streaming transforms, and flexible error handling.

Package Information

  • Package Name: ncp
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install ncp

Core Imports

const ncp = require('ncp').ncp;

Alternative import (equivalent):

const ncp = require('ncp');

Basic Usage

const ncp = require('ncp').ncp;

// Basic file/directory copying
ncp('/path/to/source', '/path/to/destination', function (err) {
  if (err) {
    return console.error(err);
  }
  console.log('Copy completed successfully!');
});

// With options
ncp(source, destination, {
  filter: /\.js$/,    // Only copy .js files
  limit: 32,          // Higher concurrency
  clobber: false,     // Don't overwrite existing files
  stopOnErr: true     // Stop on first error
}, function (err) {
  if (err) {
    return console.error(err);
  }
  console.log('Copy completed with options!');
});

Capabilities

File Copying Function

Asynchronously copies files and directories from source to destination with comprehensive options for controlling the copy behavior.

/**
 * Copy files and directories asynchronously
 * @param {string} source - Source file or directory path
 * @param {string} dest - Destination file or directory path
 * @param {function} callback - Completion callback function(err)
 */
function ncp(source, dest, callback);

/**
 * Copy files and directories asynchronously with options
 * @param {string} source - Source file or directory path
 * @param {string} dest - Destination file or directory path
 * @param {object} options - Copy options object
 * @param {function} callback - Completion callback function(err)
 */
function ncp(source, dest, options, callback);

Global Concurrency Control

Set global concurrency limit for all ncp operations.

/**
 * Global concurrency limit for file system operations
 * @type {number}
 * @default 16
 */
ncp.limit = 16;

Alternative Access

Alternative way to access the ncp function.

/**
 * Alternative access to the main ncp function
 * @type {function}
 */
ncp.ncp;

Options

File Filtering

Control which files get copied using regular expressions or custom functions.

/**
 * Filter files to be copied
 * @typedef {RegExp|function} FilterOption
 * @property {RegExp} filter - Regular expression to match file paths
 * @property {function} filter - Function(filePath) returning boolean
 */
options.filter;

Usage Examples:

// Regular expression filter - only copy .js files
const options = {
  filter: /\.js$/
};

// Function filter - copy only files modified in last 24 hours
const options = {
  filter: function(filePath) {
    const stats = require('fs').statSync(filePath);
    const dayAgo = Date.now() - (24 * 60 * 60 * 1000);
    return stats.mtime.getTime() > dayAgo;
  }
};

Stream Transforms

Apply streaming transformations during the copy process.

/**
 * Stream transformation function
 * @typedef {function} TransformFunction
 * @param {ReadableStream} readStream - Source file read stream
 * @param {WritableStream} writeStream - Destination file write stream
 * @param {object} file - File metadata object with name, mode, mtime, atime
 */
options.transform;

Usage Example:

const options = {
  transform: function(readStream, writeStream, file) {
    if (file.name.endsWith('.txt')) {
      // Transform text files to uppercase
      readStream
        .pipe(require('stream').Transform({
          transform(chunk, encoding, callback) {
            callback(null, chunk.toString().toUpperCase());
          }
        }))
        .pipe(writeStream);
    } else {
      // Copy other files normally
      readStream.pipe(writeStream);
    }
  }
};

File Overwrite Control

Control whether to overwrite existing destination files.

/**
 * Whether to overwrite existing destination files
 * @typedef {boolean} ClobberOption
 * @default true
 */
options.clobber;

Symbolic Link Handling

Control how symbolic links are processed during copying.

/**
 * Whether to follow symbolic links
 * @typedef {boolean} DereferenceOption
 * @default false
 */
options.dereference;

Concurrency Control

Set the maximum number of concurrent file system operations.

/**
 * Concurrency limit for file system operations
 * @typedef {number} LimitOption
 * @default 16
 * @min 1
 * @max 512
 */
options.limit;

Error Handling

Control error handling behavior and error output destination.

/**
 * Whether to stop on first error
 * @typedef {boolean} StopOnErrOption
 * @default false
 */
options.stopOnErr;

// Note: The CLI uses --stoponerr but the API uses stopOnErr

/**
 * Error output destination
 * @typedef {string|Stream} ErrorsOption
 * @property {string} errs - File path for error logging
 * @property {Stream} errs - Writable stream for error output
 */
options.errs;

File Path Renaming

Transform destination file paths during copying.

/**
 * Function to rename destination paths
 * @typedef {function} RenameFunction
 * @param {string} targetPath - Original destination path
 * @returns {string} - Modified destination path
 */
options.rename;

Timestamp-based Copying

Only copy files if source is newer than destination.

/**
 * Only copy if source file is newer than destination
 * @typedef {boolean} ModifiedOption
 * @default false
 */
options.modified;

Command Line Interface

The ncp package includes a command-line tool for file copying operations.

CLI Usage

ncp [source] [destination] [--filter=pattern] [--limit=N] [--stoponerr]

CLI Options

# Set concurrency limit
--limit=16

# Set filter pattern (RegExp)
--filter=\\.js$

# Stop on first error
--stoponerr

CLI Examples:

# Basic copy
ncp /source/path /dest/path

# Copy with concurrency limit
ncp /source/path /dest/path --limit=32

# Copy only JavaScript files
ncp /source/path /dest/path --filter=\\.js$

# Copy with error stopping
ncp /source/path /dest/path --stoponerr

Error Handling

Error Types

The callback function receives different error types based on the stopOnError option:

/**
 * Single error (when stopOnError is true)
 * @typedef {Error} SingleError
 * @property {string} message - Error description
 * @property {string} stack - Error stack trace
 */

/**
 * Multiple errors (when stopOnError is false)
 * @typedef {Error[]} ErrorArray
 * @property {Error[]} errors - Array of error objects
 */

Error Scenarios

Common error conditions that may occur during copying:

  • File system permission errors
  • Non-existent source paths
  • Broken symbolic links (when dereference: true)
  • Destination write failures
  • Network file system errors

Error Handling Examples:

ncp(source, dest, { stopOnErr: false }, function(err) {
  if (Array.isArray(err)) {
    console.error('Multiple errors occurred:');
    err.forEach(function(error) {
      console.error('- ' + error.message);
    });
  } else if (err) {
    console.error('Single error:', err.message);
  } else {
    console.log('Copy completed successfully');
  }
});

// Error logging to file
ncp(source, dest, { 
  stopOnErr: false,
  errs: './copy-errors.log'
}, function(err) {
  // Errors are also written to copy-errors.log
  if (err) {
    console.error('Errors occurred, check copy-errors.log');
  }
});

Advanced Usage Patterns

Conditional Copying

// Copy only recently modified files
ncp(source, dest, {
  filter: function(filePath) {
    const stats = require('fs').statSync(filePath);
    const hourAgo = Date.now() - (60 * 60 * 1000);
    return stats.mtime.getTime() > hourAgo;
  },
  modified: true  // Additional timestamp check
}, callback);

High-Performance Copying

// Optimize for large file operations
ncp(source, dest, {
  limit: 64,        // Higher concurrency
  clobber: true,    // Overwrite without checks
  dereference: false // Don't resolve symlinks
}, callback);

Safe Incremental Copying

// Safe copying with comprehensive error handling
ncp(source, dest, {
  clobber: false,   // Don't overwrite existing files
  modified: true,   // Only copy if newer
  stopOnErr: false, // Continue on errors
  errs: process.stderr, // Log errors to stderr
  filter: function(filePath) {
    // Skip hidden files and directories
    return !require('path').basename(filePath).startsWith('.');
  }
}, function(err) {
  if (Array.isArray(err)) {
    console.log(`Copy completed with ${err.length} errors`);
  } else if (err) {
    console.error('Copy failed:', err.message);
  } else {
    console.log('Copy completed successfully');
  }
});
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/ncp@2.0.x
Publish Source
CLI
Badge
tessl/npm-ncp badge