search

realtymaps / promise-ftp

a promise-based ftp client for node.js
MIT License
81 stars 27 forks source link

readme

Description

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

This module is a wrapper around the node-ftp module, and provides some additional features as well as a convenient promise-based API.

This library is written primarily in CoffeeScript, but may be used just as easily in a Node app using Javascript or CoffeeScript. Promises in this module are provided by Bluebird.

Change Log

Requirements

Install

npm install promise-ftp

Examples

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

  var PromiseFtp = require('promise-ftp');

  var ftp = new PromiseFtp();
  ftp.connect({host: host, user: user, password: password})
  .then(function (serverMessage) {
    console.log('Server message: '+serverMessage);
    return ftp.list('/');
  }).then(function (list) {
    console.log('Directory listing:');
    console.dir(list);
    return ftp.end();
  });

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

  var PromiseFtp = require('promise-ftp');
  var fs = require('fs');

  var ftp = new PromiseFtp();
  ftp.connect({host: host, user: user, password: password})
  .then(function (serverMessage) {
    return ftp.get('foo.txt');
  }).then(function (stream) {
    return new Promise(function (resolve, reject) {
      stream.once('close', resolve);
      stream.once('error', reject);
      stream.pipe(fs.createWriteStream('foo.local-copy.txt'));
    });
  }).then(function () {
    return ftp.end();
  });

Upload local file 'foo.txt' to the server:

  var PromiseFtp = require('promise-ftp');
  var fs = require('fs');

  var ftp = new PromiseFtp();
  ftp.connect({host: host, user: user, password: password})
  .then(function (serverMessage) {
    return ftp.put('foo.txt', 'foo.remote-copy.txt');
  }).then(function () {
    return ftp.end();
  });

API

For the most part, this module's API mirrors node-ftp's API, except that it returns promises which resolve or reject, rather than emitting events or calling callbacks. However, there are some minor differences and some additional features. If you need access to the underlying events or callback-based methods, you can access the raw node-ftp client via rawClient property.

Errors

Errors generated by this module will be instances of one of the following:

In addition, errors from the underlying node-ftp library may be rejected unchanged through method calls. In the case of protocol-level errors, the rejected error will contain a code property that references the related 3-digit FTP response code. This code may be translated into a (generic) human-readable text explanation by referencing the map PromiseFtp.ERROR_CODES.

Methods

Required "standard" commands (RFC 959)

Optional "standard" commands (RFC 959)

Extended commands (RFC 3659)