jsftp

What is jsftp?

jsftp is a lightweight FTP client for Node.js that allows you to interact with FTP servers. It supports a variety of FTP operations such as uploading, downloading, renaming, and deleting files, as well as creating and removing directories.

What are jsftp's main functionalities?

Connecting to an FTP server

This code demonstrates how to connect to an FTP server using jsftp. You need to provide the host, username, and password for the FTP server.

const JSFtp = require('jsftp');
const ftp = new JSFtp({
  host: 'ftp.example.com',
  user: 'username',
  pass: 'password'
});
ftp.auth('username', 'password', (err, res) => {
  if (err) return console.error(err);
  console.log('Connected to FTP server');
});

Uploading a file

This code demonstrates how to upload a file from the local filesystem to the FTP server using jsftp.

ftp.put('local/path/to/file.txt', 'remote/path/to/file.txt', err => {
  if (err) return console.error(err);
  console.log('File uploaded successfully');
});

Downloading a file

This code demonstrates how to download a file from the FTP server to the local filesystem using jsftp.

ftp.get('remote/path/to/file.txt', 'local/path/to/file.txt', err => {
  if (err) return console.error(err);
  console.log('File downloaded successfully');
});

Listing files in a directory

This code demonstrates how to list files in a directory on the FTP server using jsftp.

ftp.ls('remote/path/to/directory', (err, res) => {
  if (err) return console.error(err);
  res.forEach(file => {
    console.log(file.name);
  });
});

Deleting a file

This code demonstrates how to delete a file on the FTP server using jsftp.

ftp.raw('DELE', 'remote/path/to/file.txt', (err, res) => {
  if (err) return console.error(err);
  console.log('File deleted successfully');
});

Other packages similar to jsftp

ftp

The 'ftp' package is another FTP client for Node.js. It provides similar functionalities to jsftp, such as connecting to an FTP server, uploading, downloading, and deleting files. However, 'ftp' is known for its simplicity and ease of use, making it a good choice for basic FTP operations.

promise-ftp

The 'promise-ftp' package is a promise-based FTP client for Node.js. It offers similar functionalities to jsftp but uses promises instead of callbacks, which can make the code cleaner and easier to manage, especially for complex workflows.

ssh2-sftp-client

The 'ssh2-sftp-client' package is an SFTP client for Node.js. While it focuses on SFTP rather than FTP, it provides similar functionalities such as uploading, downloading, and managing files on a server. It is built on top of the 'ssh2' package and is known for its reliability and performance.

README

jsftp

A client FTP library for NodeJS that focuses on correctness, clarity and conciseness. It doesn't get in the way and plays nice with streaming APIs.

Starting it up

var JSFtp = require("jsftp");

var Ftp = new JSFtp({
  host: "myserver.com",
  port: 3331, // defaults to 21
  user: "user", // defaults to "anonymous"
  pass: "1234" // defaults to "@anonymous"
});

jsftp gives you access to all the raw commands of the FTP protocol in form of methods in the Ftp object. It also provides several convenience methods for actions that require complex chains of commands (e.g. uploading and retrieving files, passive operations), as shown below.

When raw commands succeed they always pass the response of the server to the callback, in the form of an object that contains two properties: code, which is the response code of the FTP operation, and text, which is the complete text of the response.

Raw (or native) commands are accessible in the form Ftp.raw["command"](params, callback)

Thus, a command like QUIT will be called like this:

Ftp.raw.quit(function(err, data) {
    if (err) return console.error(err);

    console.log("Bye!");
});

and a command like MKD (make directory), which accepts parameters, looks like this:

Ftp.raw.mkd("/new_dir", function(err, data) {
    if (err) return console.error(err);

    console.log(data.text); // Show the FTP response text to the user
    console.log(data.code); // Show the FTP response code to the user
});

API and examples

new Ftp(options)

• options is an object with the following properties:

{
  host: 'localhost', // Host name for the current FTP server.
  port: 3333, // Port number for the current FTP server (defaults to 21).
  user: 'user', // Username
  pass: 'pass', // Password
}

Creates a new Ftp instance.

Ftp.host

Host name for the current FTP server.

Ftp.port

Port number for the current FTP server (defaults to 21).

Ftp.socket

NodeJS socket for the current FTP server.

Ftp.features

Array of feature names for the current FTP server. It is generated when the user authenticates with the auth method.

Ftp.system

Contains the system identification string for the remote FTP server.

Methods

Ftp.raw.FTP_COMMAND([params], callback)

All the standard FTP commands are available under the raw namespace. These commands might accept parameters or not, but they always accept a callback with the signature err, data, in which err is the error response coming from the server (usually a 4xx or 5xx error code) and the data is an object that contains two properties: code and text. code is an integer indicating the response code of the response and text is the response string itself.

Ftp.auth(username, password, callback)

Authenticates the user with the given username and password. If null or empty values are passed for those, auth will use anonymous credentials. callback will be called with the response text in case of successful login or with an error as a first parameter, in normal Node fashion.

Ftp.ls(filePath, callback)

Lists information about files or directories and yields an array of file objects with parsed file properties to the callback. You should use this function instead of stat or list in case you need to do something with the individual file properties.

ftp.ls(".", function(err, res) {
  res.forEach(function(file) {
    console.log(file.name);
  });
});

Ftp.list(filePath, callback)

Lists filePath contents using a passive connection. Calls callback with a string containing the directory contents in long list format.

ftp.list(remoteCWD, function(err, res) {
  console.log(res);
  // Prints something like
  // -rw-r--r--   1 sergi    staff           4 Jun 03 09:32 testfile1.txt
  // -rw-r--r--   1 sergi    staff           4 Jun 03 09:31 testfile2.txt
  // -rw-r--r--   1 sergi    staff           0 May 29 13:05 testfile3.txt
  // ...
});

Ftp.get(remotePath, callback)

Gives back a paused socket with the file contents ready to be streamed, or calls the callback with an error if not successful.

  var str = ""; // Will store the contents of the file
  ftp.get('remote/path/file.txt', function(err, socket) {
    if (err) return;

    socket.on("data", function(d) { str += d.toString(); })
    socket.on("close", function(hadErr) {
      if (hadErr)
        console.error('There was an error retrieving the file.');
    });
    socket.resume();
  });

Ftp.get(remotePath, localPath, callback)

Stores the remote file directly in the given local path.

  ftp.get('remote/file.txt', 'local/file.txt', function(hadErr) {
    if (hadErr)
      console.error('There was an error retrieving the file.');
    else
      console.log('File copied successfully!');
  });

Ftp.put(source, remotePath, callback)

Uploads a file to filePath. It accepts a string with the local path for the file or a Buffer as a source parameter.

ftp.put(buffer, 'path/to/remote/file.txt', function(hadError) {
  if (!hadError)
    console.log("File transferred successfully!");
});

Ftp.rename(from, to, callback)

Renames a file in the server. from and to are both filepaths.

ftp.rename(from, to, function(err, res) {
  if (!err)
    console.log("Renaming successful!");
});

Ftp.keepAlive([wait])

Refreshes the interval thats keep the server connection active. wait is an optional time period (in milliseconds) to wait between intervals.

You can find more usage examples in the unit tests. This documentation will grow as jsftp evolves.

Debugging

In order to enable debug mode in a FTP connection, a debugMode parameter can be used in the constructors's config object:

var Ftp = new JSFtp({
  host: "myserver.com",
  port: 3331,
  user: "user",
  pass: "1234",
  debugMode: true
});

It can also be activated or deactivated by calling the setDebugMode method:

Ftp.setDebugMode(true); // Debug Mode on
Ftp.setDebugMode(false); // Debug mode off

If the debug mode is on, the jsftp instance will emit jsftp_debug events with two parameters: the first is the type of the event and the second and object including data related to the event. There are 3 possible types of events:

• response events: These are response from the FTP server to the user's FTP commands

• user_command events: These are commands that the user issues to the FTP server.

• event:{event name} events: These are other events mostly related to the server connection, such as timeout, connect or disconnect. For example, a timeout event will have the name event:timeout.

In order to react to print all debug events (for example), we would listen to the debug messages like this:

Ftp.on('jsftp_debug', function(eventType, data) {
  console.log('DEBUG: ', eventType);
  console.log(JSON.stringify(data, null, 2));
});

Installation

npm install jsftp

Test coverage

In order to run coverage reports:

npm install --dev
make coverage

Current overall coverage rate:
  lines......: 95.5% (278 of 291 lines)
  functions..: 100% (69 of 69 functions)

Tests

To run tests:

npm install --dev
npm test

License

See LICENSE.