artesanias/node_modules/ftp-client/README.md

Description

node-ftp-client is a wrapper for the popular FTP client module for node.js - node-ftp, which provides an easy way of manipulating FTP transfers.

Requirements

• node.js -- v0.8.0 or newer

Dependencies

• node-ftp -- v0.3.6
• glob -- v3.2.9
• lodash -- v2.4.1
• async -- v0.8.0

Installation

npm install ftp-client

Usage

Initialization

To crate an instance of the wrapper use the following code:

var ftpClient = require('ftp-client'),
client = new ftpClient(config, options);

where config contains the ftp server configuration (these are the default values):

{
    host: 'localhost',
    port: 21,
    user: 'anonymous',
    password: 'anonymous@'
}

and the options object may contain the following keys:

• logging (String): ‘none’, ‘basic’, ‘debug’ - level of logging for all the tasks - use ‘debug’ in case of any issues
• overwrite (String): ‘none’, ‘older’, ‘all’ - determines which files should be overwritten when downloading/uploading - ‘older’ compares the date of modification of local and remote files

Connecting

After creating the new object you have to manually connect to the server by using the connect method:

client.connect(callback);

And passing the callback which should be executed when the client is ready.

Methods

• download(< String > remoteDir, < String > localDir, < Object > options, < Function > callback) - downloads the contents of remoteDir to localDir if both exist, and executes the callback if one is supplied with the following object as a parameter:

  {
  downloadedFiles: [(filename)],
  errors: {
      (filename): (error)
  }
  }
  

  options is an object with the following possible keys

  • overwrite (String): ‘none’, ‘older’, ‘all’ - determines which files should be overwritten

• upload(< mixed > source, < String > remoteDir, < Object > options, < Function > callback) - expands the source paths using the glob module, uploads all found files and directories to the specified remoteDir , and executes the callback if one is supplied with the following object as a parameter:

  {
  uploadedFiles: [(filename)],
  uploadedDirectories: [(dirname)],
  errors: {
      (filename/dirname): (error)
  }
  }
  

  source can be a string or an array of strings, and options is an object with the following possible keys

  • overwrite (String): ‘none’, ‘older’, ‘all’ - determines which files should be overwritten
  • baseDir (String) - local base path relative to the remote directory, e.g. if you want to upload file uploads/sample.js to public_html/uploads, baseDir has to be set to uploads

Examples

In this example we connect to a server, and simultaneously upload all files from the test directory, overwriting only older files found on the server, and download files from /public_html/test directory.

var ftpClient = require('./lib/client.js'),
    config = {
        host: 'localhost',
        port: 21,
        user: 'anonymous',
        password: 'anonymous@'
    },
    options = {
        logging: 'basic'
    },
    client = new ftpClient(config, options);

client.connect(function () {

    client.upload(['test/**'], '/public_html/test', {
        baseDir: 'test',
        overwrite: 'older'
    }, function (result) {
        console.log(result);
    });

    client.download('/public_html/test2', 'test2/', {
        overwrite: 'all'
    }, function (result) {
        console.log(result);
    });

});

TODO

• Methods chaining
• Queuing downloads/uploads with async in a single session
• Connecting in constructor, with possibility to end the connection manually