FTP-ts

FTP-ts is an FTP client module for node.js that provides an asynchronous interface for communicating with a FTP server.

It is a rewritten version of the ftp package from mscdex.

Requirements

node.js -- v8.0 or newer

Note: For node version < 10, one of the --harmony_async_iteration or --harmony flags must be used.

Install

npm install ftp-ts

Examples

Get a directory listing of the current (remote) working directory

  import Client from "ftp-ts";

  // connect to localhost:21 as anonymous
  Client.connect({host: "127.0.0.1", port: 21}).then(async (c) => {
    console.dir(await c.list());
    c.end();
  });

Download remote file 'foo.txt' and save it to the local file system

  import Client from "ftp-ts";
  import { createWriteStream } from "fs";

  // connect to localhost:21 as anonymous
  Client.connect({host: "127.0.0.1", port: 21}).then(async (c) => {
    const stream = await c.get('foo.txt');
    stream.pipe(createWriteStream('foo.local-copy.txt'));
    c.end();
  });

Upload local file 'foo.txt' to the server

  import Client from "ftp-ts";

  // connect to localhost:21 as anonymous
  Client.connect({host: "127.0.0.1", port: 21}).then((c) => {
    c.put('foo.txt', 'foo.remote-copy.txt');
    c.end();
  })

Fallback to using PORT for data connections

  import Client from "ftp-ts";

  // connect to localhost:21 as anonymous
  // Config PORT address and PORT range
  Client.connect({host: "127.0.0.1", port: 2111, portAddress: "127.0.0.1", portRange: "6000-7000"}).then(async (c) => {
    console.dir(await c.list());
    c.end();
  });

Implementation

List of implemented required "standard" commands (RFC 959):

• list
• get
• put
• append
• rename
• logout
• delete
• cwd
• abort
• site
• status
• ascii
• binary

List of implemented optional "standard" commands (RFC 959):

• mkdir
• rmdir
• cdup
• pwd
• system
• listSafe

List of implemented extended commands (RFC 3659)

• size
• lastMod
• restart

Class: FTP, default

new FTP()

Creates a new FTP client.

Class Method: FTP.connect([options])

• options <Object> See ftp.connect for which options are available.
• Returns: <Promise<FTP>> The promise is resolved to a FTP.

Event: 'greeting'

• <string> the text the server sent upon connection.

Emitted after connection.

Event: 'ready'

Emitted when connection and authentication were sucessful.

Event: 'close'

• <boolean> if closed becouse of error

Emitted when the connection has fully closed.

Event: 'end'

Emitted when the connection has ended.

Event: 'error'

• <Error> the error when an error occurs

Emitted when an error occurs. In case of protocol-level errors, the error contains a code property that references the related 3-digit FTP response code.

Override: ftp.localPort(bindIp[, portRange])

• bindIp <string> The IP to bind the PORT socket to.
• portRange <string> The range of ports to use when setting up PORT sockets.
• Returns: <Promise<[string, string | number]>> The promise is resolved to the following object.
  • 0 <string> The bindIp to actually bind to.
  • 1 <string> The portRange or portNumber to bind to.

This method may be overridden on the instance to allow for better managed PORT/EPRT commands.

For example, you may wish to bind only to a specific network interface for security reasons. In that case you may override this method to return the bindIp with a value of 127.0.0.1 instead of 0.0.0.0 to only allow incoming connections from localhost.

Another reason may be to decide upon a port number and await some NAT rules to propagate before the remote server connects.

This could also be useful if your external IP family does not match the family of your interface due to proxying or NAT rules. By default the zero bindIp will always be in the same IP family as the external IP set as portAddress in the IOption object.

ftp.connect([options])

• options <Object>
  • host <string> The hostname or IP address of the FTP server. Default: 'localhost'.
  • port <number> The port of the FTP server. Default: 21.
  • portAddress <string> The external IP address for the server to connect to when using PORT.
  • portRange <string> The range of ports to use when setting up PORT sockets.
  • secure <boolean> | <string> Set to true for both control and data connection encryption, 'control' for control connection encryption only, or 'implicit' for implicitly encrypted control connection (this mode is deprecated in modern times, but usually uses port 990) Default: false.
  • secureOptions <Object> Additional options to be passed to tls.connect().
  • user <string> Username for authentication. Default: 'anonymous'.
  • password <string> Password for authentication. Default: 'anonymous@'.
  • connTimeout <number> How long (in milliseconds) to wait for the control connection to be established. Default: 10000.
  • dataTimeout <number> How long (in milliseconds) to wait for a PASV/PORT data connection to be established. Default: 10000.
  • keepalive <number> How often (in milliseconds) to send a 'dummy' (NOOP) command to keep the connection alive. Default: 10000.

Connects to an FTP server.

ftp.end()

Closes the connection to the server after any/all enqueued commands have been executed.

ftp.destroy()

Closes the connection to the server immediately.

ftp.list([path[, useCompression]])

• path <string> Default: current directory.
• useCompression <boolean> Default: false.
• Returns: <Promise<Object>> The promise is resolved to the following object.
  • type <string> A single character denoting the entry type: 'd' for directory, '-' for file (or 'l' for symlink on *NIX only).
  • name <string> The name of the entry.
  • size <number> 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'.
  • 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).
  • sticky <boolean> true if the sticky bit is set for this entry (*NIX only).

Get a directory listing from the server.

ftp.get(path[, useCompression])

• path <string> The name of the file to retreive.
• useCompression <boolean> Default: false.
• Returns: <Promise<stream.Readable>> The promise is resolved to a stream.Readable.

Retrieves a file at path from the server.

ftp.put(input, destPath[, useCompression])

• input <string> | <buffer> | <stream.Readable> The file name as a string, the file content as a buffer, the file content as a stream.
• destPath <string> The name of the file to write.
• useCompression <boolean> Default: false.
• Returns: <Promise>

Sends data to the server to be stored as destPath.

ftp.append(input, destPath[, useCompression])

• input <string> | <buffer> | <stream.Readable> The file name as a string, the file content as a buffer, the file content as a stream.
• destPath <string> The name of the file to write.
• useCompression <boolean> Default: false.
• Returns: <Promise>

Sends data to the server to be stored as destPath, except if destPath already exists, it will be appended to instead of overwritten.

ftp.rename(oldPath, newPath)

• oldPath <string> The name of the file to move.
• newPath <string> The new name of the file.
• Returns: <Promise>

Renames oldPath to newPath on the server.

ftp.logout()

• Returns: <Promise>

Logout the user from the server.

ftp.delete(path)

• path <string> The name of the file to delete.
• Returns: <Promise>

Deletes the file represented by path on the server.

ftp.cwd(path[, promote])

• path <string> The path to the new working directory.
• promote <boolean> Default: false.
• Returns: <Promise<string | undefined>> The promise is resolved to a string or undefined.

Changes the current working directory to path.

ftp.abort(immediate)

• immediate <boolean> Default: true.
• Returns: <Promise>

Aborts the current data transfer (e.g. from get(), put(), or list()).

ftp.site(command)

• command <string> SITE command to send.
• Returns: <Promise> The promise is resolved to a tuple of a number and an optional string

Sends command (e.g. 'CHMOD 755 foo', 'QUOTA') using SITE.

ftp.status()

• Returns: <Promise<string>> The promise is resolved to a string

Retrieves human-readable information about the server's status.

ftp.ascii()

• Returns: <Promise>

Sets the transfer data type to ASCII.

ftp.binary()

• Returns: <Promise>

Sets the transfer data type to binary (default at time of connection).

ftp.mkdir(path[, recursive])

• path <string> The path to the new directory.
• recursive <boolean> Is for enabling a 'mkdir -p' algorithm Default: false.
• Returns: <Promise>

Creates a new directory, path, on the server.

ftp.rmdir(path[, recursive])

• path <string> The path of the directory to delete.
• recursive <boolean> Will delete the contents of the directory if it is not empty Default: false.
• Returns: <Promise>

Removes a directory, path, on the server.

ftp.cdup()

• Returns: <Promise>

Changes the working directory to the parent of the current directory.

ftp.pwd()

• Returns: <Promise<string | undefined>> The promise is resolved to a string when the server replies with a path.

Retrieves the current working directory.

ftp.system()

• Returns: <Promise<string>> The promise is resolved to a string when the server sends a reply.

Retrieves the server's operating system.

ftp.listSafe([path[, useCompression]])

• path <string> Default: current directory.
• useCompression <boolean> Default: false.
• Returns: <Promise<Object>> The promise is resolved to the following object.
  • type <string> A single character denoting the entry type: 'd' for directory, '-' for file (or 'l' for symlink on *NIX only).
  • name <string> The name of the entry.
  • size <number> 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'.
  • 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).
  • sticky <boolean> true if the sticky bit is set for this entry (*NIX only).

Similar to list(), except the directory is temporarily changed to path to retrieve the directory listing. This is useful for servers that do not handle characters like spaces and quotes in directory names well for the LIST command. This function is "optional" because it relies on pwd() being available.

ftp.size(path)

• path <string> The path of the file.
• Returns: <Promise<number>> The promise is resolved to a number

Retrieves the size of path.

ftp.lastMod(path)

• path <string> The path of the file.
• Returns: <Promise<date>> The promise is resolved to a date

Retrieves the last modified date and time for path.

ftp.restart(byteOffset)

• byteOffset <number>
• Returns: <Promise>

Sets the file byte offset for the next file transfer action (get/put) to byteOffset.