What is ftp?
The ftp npm package is a client for the File Transfer Protocol (FTP), which allows for the transfer of files between a client and a server on a computer network. It provides methods to read and write files, navigate the directory structure, and manage files and directories on the server.
What are ftp's main functionalities?
Connecting to an FTP server
This code sample demonstrates how to establish a connection to an FTP server using the ftp package. You need to provide the host, user, and password to connect.
const FTP = require('ftp');
const client = new FTP();
client.connect({ host: 'ftp.example.com', user: 'username', password: 'password' });
Listing files in a directory
This code sample shows how to list all files in a specific directory on the FTP server.
client.list('/path/to/directory', (err, list) => {
if (err) throw err;
console.dir(list);
});
Downloading a file
This code sample illustrates how to download a file from the FTP server. It saves the file to a local path.
client.get('remote/file/path.txt', (err, stream) => {
if (err) throw err;
stream.once('close', () => { client.end(); });
stream.pipe(fs.createWriteStream('local/file/path.txt'));
});
Uploading a file
This code sample demonstrates how to upload a file to the FTP server from a local path.
client.put('local/file/path.txt', 'remote/file/path.txt', (err) => {
if (err) throw err;
client.end();
});
Deleting a file
This code sample shows how to delete a file from the FTP server.
client.delete('remote/file/path.txt', (err) => {
if (err) throw err;
console.log('File deleted successfully');
});
Other packages similar to ftp
basic-ftp
The basic-ftp package is an alternative to ftp that provides an easy-to-use API for interacting with an FTP server, including support for modern JavaScript features like async/await. It is designed to be both powerful and beginner-friendly.
jsftp
jsftp is a simple and lightweight FTP client for Node.js, with an emphasis on simplicity and ease of use. It offers a similar set of features to the ftp package but with a different API design.
promise-ftp
promise-ftp is an FTP client that wraps the ftp package's functionality in Promises, making it more suitable for use in modern asynchronous JavaScript code that utilizes async/await syntax.
ftp-srv
ftp-srv is a module for creating an FTP server rather than a client. It is useful for when you want to set up your own FTP server programmatically in Node.js, as opposed to connecting to an existing one.
Description
node-ftp is an FTP client module for node.js that provides an asynchronous interface for communicating with an FTP server.
Requirements
Install
npm install ftp
Examples
- Get a directory listing of the current (remote) working directory:
var FTPClient = require('ftp');
var c = new FTPClient();
c.on('ready', function() {
c.list(function(err, list) {
if (err) throw err;
console.dir(list);
c.end();
});
});
c.connect();
- Download remote file 'foo.txt' and save it to the local file system:
var FTPClient = require('ftp');
var fs = require('fs');
var c = new FTPClient();
c.on('ready', function() {
c.get('foo.txt', function(err, stream) {
if (err) throw err;
stream.once('close', function() { c.end(); });
stream.pipe(fs.createWriteStream('foo.local-copy.txt'));
});
});
c.connect();
- Upload local file 'foo.txt' to the server:
var FTPClient = require('ftp');
var fs = require('fs');
var c = new FTPClient();
c.on('ready', function() {
c.put(fs.createReadStream('foo.txt'), 'foo.remote-copy.txt', function(err) {
if (err) throw err;
c.end();
});
});
c.connect();
API
Events
-
ready() - Emitted when connection and authentication were sucessful.
-
close(< boolean >hadErr) - Emitted when the connection has fully closed.
-
end() - Emitted when the connection has ended.
-
error(< Error >err) - Emitted when an error occurs. In case of protocol-level errors, err
contains a 'code' property that references the related 3-digit FTP response code.
Methods
* Note: As with the 'error' event, any error objects passed to callbacks will have a 'code' property for protocol-level errors.
-
(constructor)() - Creates and returns a new FTP client instance.
-
connect(< object >config) - (void) - Connects to an FTP server. Valid config properties:
-
host - string - The hostname or IP address of the FTP server. Default: 'localhost'
-
port - integer - The port of the FTP server. Default: 21
-
user - string - Username for authentication. Default: 'anonymous'
-
password - string - Password for authentication. Default: 'anonymous@'
-
connTimeout - integer - How long (in milliseconds) to wait for the main connection to be established. Default: 10000
-
pasvTimeout - integer - How long (in milliseconds) to wait for a PASV data connection to be established. Default: 10000
-
keepalive - integer - How often (in milliseconds) to send a 'dummy' (NOOP) command to keep the connection alive. Default: 10000
-
end() - (void) - Closes the connection to the server.
Required "standard" commands (RFC 959)
-
list([< string >path, ]< function >callback) - (void) - Retrieves the directory listing of path
. path
defaults to the current working directory. callback
has 2 parameters: < Error >err, < array >list. list
is an array of objects with these properties:
* name - _string_ - The name of the entry.
* size - _string_ - The size of the entry in bytes.
* date - _Date_ - The last modified date of the entry.
* rights - _object_ - The various permissions for this entry **(*NIX only)**.
* user - _string_ - An empty string or any combination of 'r', 'w', 'x'.
* group - _string_ - An empty string or any combination of 'r', 'w', 'x'.
* other - _string_ - An empty string or any combination of 'r', 'w', 'x'.
* type - _string_ - A single character denoting the entry type: 'd' for directory, '-' for file (or 'l' for symlink on **\*NIX only**).
* owner - _string_ - The user name or ID that this entry belongs to **(*NIX only)**.
* group - _string_ - The group name or ID that this entry belongs to **(*NIX only)**.
* target - _string_ - For symlink entries, this is the symlink's target **(*NIX only)**.
-
get(< string >path, < function >callback) - (void) - Retrieves a file, path
, from the server. callback
has 2 parameters: < Error >err, < ReadableStream >fileStream.
-
put(< mixed >input, < string >path, < function >callback) - (void) - Sends data to the server to be stored as path
. input
can be a ReadableStream or a single Buffer. callback
has 1 parameter: < Error >err.
-
append(< mixed >input, < string >path, < function >callback) - (void) - Same as put(), except if path
already exists, it will be appended to instead of overwritten.
-
rename(< string >oldPath, < string >newPath, < function >callback) - (void) - Renames oldPath
to newPath
on the server. callback
has 1 parameter: < Error >err.
-
delete(< string >path, < function >callback) - (void) - Deletes a file, path
, on the server. callback
has 1 parameter: < Error >err.
-
cwd(< string >path, < function >callback) - (void) - Changes the current working directory to path
. callback
has 1 parameter: < Error >err.
-
abort(< function >callback) - (void) - Aborts the current data transfer (e.g. from get(), put(), or list()). callback
has 1 parameter: < Error >err.
-
status(< function >callback) - (void) - Retrieves human-readable information about the server's status. callback
has 2 parameters: < Error >err, < string >status.
Optional "standard" commands (RFC 959)
-
mkdir(< string >path, < function >callback) - (void) - Creates a new directory, path
, on the server. callback
has 1 parameter: < Error >err.
-
rmdir(< string >path, < function >callback) - (void) - Removes a directory, path
, on the server. callback
has 1 parameter: < Error >err.
-
cdup(< function >callback) - (void) - Changes the working directory to the parent of the current directory. callback
has 1 parameter: < Error >err.
-
pwd(< function >callback) - (void) - Retrieves the current working directory. callback
has 2 parameters: < Error >err, < string >cwd.
-
system(< function >callback) - (void) - Retrieves information about the server's operating system. callback
has 2 parameters: < Error >err, < string >info.
Extended commands (RFC 3659)
-
size(< string >path, < function >callback) - (void) - Retrieves the size of path
. callback
has 2 parameters: < Error >err, < integer >numBytes.
-
lastMod(< string >path, < function >callback) - (void) - Retrieves the last modified date and time for path
. callback
has 2 parameters: < Error >err, < Date >lastModified.
-
restart(< integer >byteOffset, < function >callback) - (void) - Sets the file byte offset for the next file transfer action (get/put/append) to byteOffset
. callback
has 1 parameter: < Error >err.