ftp-ts
TypeScript icon, indicating that this package has built-in type declarations

1.1.0 • Public • Published

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 of implemented optional "standard" commands (RFC 959):

List of implemented extended commands (RFC 3659)

Class: FTP, default

new FTP()

Creates a new FTP client.

Class Method: FTP.connect([options])

Event: 'greeting'

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

Emitted after connection.

Event: 'ready'

Emitted when connection and authentication were sucessful.

Event: 'close'

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])

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])

Retrieves a file at path from the server.

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

Sends data to the server to be stored as destPath.

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

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)

Renames oldPath to newPath on the server.

ftp.logout()

Logout the user from the server.

ftp.delete(path)

Deletes the file represented by path on the server.

ftp.cwd(path[, promote])

Changes the current working directory to path.

ftp.abort(immediate)

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

ftp.site(command)

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

ftp.status()

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

ftp.ascii()

Sets the transfer data type to ASCII.

ftp.binary()

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()

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

ftp.pwd()

Retrieves the current working directory.

ftp.system()

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)

Retrieves the size of path.

ftp.lastMod(path)

Retrieves the last modified date and time for path.

ftp.restart(byteOffset)

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

Readme

Keywords

Package Sidebar

Install

npm i ftp-ts

Weekly Downloads

6,418

Version

1.1.0

License

none

Unpacked Size

679 kB

Total Files

44

Last publish

Collaborators

  • timluq
  • lumphe