# easy-ftp

> easy ftp and sftp

Latest version **0.4.2** (published 2021-03-09) · MIT license · 0 weekly downloads

## Install

```sh
npm install easy-ftp
pnpm add easy-ftp
yarn add easy-ftp
bun add easy-ftp
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.4.2 |
| Published | 2021-03-09 |
| First published | 2016-04-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 4 |
| Unpacked size | 44.4 KB |
| Known vulnerabilities | 0 (+1 in 1 direct dependencies) |
| Install scripts | no |
| GitHub stars | 35 |
| Author | humy2833 |
| Maintainers | humy2833 |
| Keywords | ftp, sftp, ssh, tls, ftps, upload, remote, download |

## Links

- npm: https://www.npmjs.com/package/easy-ftp
- Repository: https://github.com/humy2833/easy-ftp
- Homepage: https://github.com/humy2833/easy-ftp#readme
- Issues: https://github.com/humy2833/easy-ftp/issues
- npm.io page: https://npm.io/package/easy-ftp

## Dependencies (4)

- [ssh2](https://npm.io/package/ssh2.md) ^0.8.9
- [fs-extra](https://npm.io/package/fs-extra.md) ^7.0.1
- [easy-loop](https://npm.io/package/easy-loop.md) ^1.7.2
- [ftp-simple](https://npm.io/package/ftp-simple.md) ^0.3.2

## Recent versions

- 0.4.2 (latest) — 2021-03-09
- 0.4.1 — 2019-10-08
- 0.4.0 — 2019-02-13
- 0.3.44 — 2018-06-26
- 0.3.43 — 2018-06-18
- 0.3.42 — 2018-06-18
- 0.3.41 — 2018-06-15
- 0.3.40 — 2018-03-21
- 0.3.37 — 2017-09-21
- 0.3.36 — 2017-07-24
- 0.3.35 — 2017-07-17
- 0.3.34 — 2017-06-22
- 0.3.33 — 2017-06-22
- 0.3.32 — 2017-06-19
- 0.3.31 — 2017-06-13
- … 44 more at https://npm.io/package/easy-ftp/versions

## README

easy-ftp
===========
- Easy control FTP or SFTP
- 간단한 설정만으로 편리하게 FTP 혹은 SFTP 의 기능을 이용할 수 있습니다.
- 이 모듈은 [ftp-simple](https://www.npmjs.com/package/ftp-simple) 와 [ssh2](https://www.npmjs.com/package/ssh2) 모듈을 참조하였습니다.

Caution
===========
If Node.js version is 8 or higher, use `0.4.0` or higher. Otherwise, use version `0.3.44`.


Install
=======
If Node.js version is 8 or higher.
    
    npm install easy-ftp

Otherwise
    
    npm install easy-ftp@0.3.44




Usage
===========
```javascript
var EasyFtp = require('easy-ftp');
var ftp = new EasyFtp();
var config = {
    host: '',
    port: 21,
    username: '',
    password: '',
    type : 'ftp'
};

//서버 접속(connect)
ftp.connect(config);		

//폴더 변경(directory change)
ftp.cd("/", function(err, path){});	

//파일 or 폴더 삭제(하위 파일 및 폴더 포함)(file or directory remove(recursive))
ftp.rm("/filename", function(err){});	

//폴더 생성(하위 폴더 포함 생성)(make directory)
ftp.mkdir("/directory", function(err){});	

//파일 or 폴더 이동 혹은 이름 변경(file or directory move or change filename)
ftp.mv("/filename", "/newFilename", function(err, newPath){});	

//폴더 내 파일목록 반환(show files in directory)
ftp.ls("/directory", function(err, list){});	

//ftp 서버상의 현재 작업 경로 반환(return server path)
ftp.pwd(function(err, path){});	

//서버에 파일이 존재하는지 여부 반환(boolean)
ftp.exist("/filename", function(exist){});


//파일 or 폴더 업로드(file or directory upload)
ftp.upload("/test.txt", "/test.txt", function(err){});  	//result => /test.txt
ftp.upload("/test.txt", "/test123.txt", function(err){});  //result => /test123.txt 
ftp.upload("/test.txt", "/", function(err){});			//result => /test.txt
ftp.upload("/directory", "/", function(err){});			//result => /directory

//Array - Object({local:'localPath', remote:'remotePath'})
var arr = [{local:"/test.txt", remote:"/test.txt"}, {local:"/test1.txt", remote:"/abcd/test2.txt"}, {local:"/directory", remote:"/"}];
ftp.upload(arr, function(err){});	// 2 arguments;
/* result
/test.txt
/abcd/test2.txt
/directory
*/

//Array - String
var arr = ["/test.txt", "/abcd/test2.txt", "/directory"];
ftp.upload(arr, "/", function(err){});	// 3 arguments;
/* result
/test.txt
/abcd/test2.txt
/directory
*/

//Array - Object and String
var arr = [{local:"/test.txt", remote:"/directory/test.txt"}, "/abcd/test2.txt", "/directory"];
ftp.upload(arr, "/", function(err){});	// 3 arguments;
/* result
/directory/test.txt
/abcd/test2.txt
/directory
*/


//파일 or 폴더 다운로드(file or directory download)
ftp.download("/test.txt", "/test.txt", function(err){});	//result => /test.txt
ftp.download("/test.txt", "/test123.txt", function(err){});	//result => /test123.txt 
ftp.download("/test.txt", "/", function(err){});		//result => /test.txt 
ftp.download("/directory", "/", function(err){});		//result => /directory 

//Array - Object({local:'localPath', remote:'remotePath'})
var arr = [{remote:"/test.txt", local:"/test.txt"}, {remote:"/test1.txt", local:"/abcd/test2.txt"}, {remote:"/directory", local:"/"}];
ftp.download(arr, function(err){});	// 2 arguments;
/* result
/test.txt
/abcd/test2.txt
/directory
*/

//Array - String
var arr = ["/test.txt", "/abcd/test2.txt", "/directory"];
ftp.download(arr, "/", function(err){});	// 3 arguments;
/* result
/test.txt
/abcd/test2.txt
/directory
*/

//Array - Object and String
var arr = [{remote:"/test.txt", local:"/directory/test.txt"}, "/abcd/test2.txt", "/directory"];
ftp.download(arr, "/", function(err){});	// 3 arguments;
/* result
/directory/test.txt
/abcd/test2.txt
/directory
*/



//접속 종료(disconnect)
ftp.close();	
```



API
===========
Methods
-------
* **connect**(< _object_ >config) 

    * host - _string_	- server domain or ip **Default:** 'localhost'
    * port - _number_	- port (default : 21)
    * type - _string_	- ftp type. 'ftp' or 'sftp' (default : 'ftp')
    * username - _string_ - username for authentication **Default:** 'anonymous',
    * password - _string_	- password for authentication. **Default:** 'anonymous@'
    * privateKey - _string_	- (only sftp)string that contains a private key for either key-based or hostbased user authentication (OpenSSH format) **Default:** none
    * path - _string_	- start path.
    * secure - _boolean_ - (only ftp) Explicit FTPS over TLS, default: false
    * secureOptions - _object_ - (only ftp) Options for TLS, same as for `tls.connect()` in Node.js.


* **cd**(< _string_ >path, < _function_ >callback) - Changes the working directory. callback has 1 parameter: < Error >err.

* **rm**(< _string_ >path, < _function_ >callback) - Deletes a file or directory(include child files) path on the server. callback has 1 parameter: < Error >err.
    
* **mkdir**(< _string_ >path, < _function_ >callback) - Creates a new directory recursive. callback has 1 parameter: < Error >err.

* **mv**(< _string_ >oldPath, < _string_ >newPath, < _function_ >callback) - Renames or Move oldPath to newPath on the server. callback has 2 parameter: < Error >err, < String >newPath.

* **ls**(< _string_ >path, < _function_ >callback) - Retrieves the directory listing of path. callback has 2 parameter: < Error >err, < Array >list.
    
    * name - _string_ - file name
    * size - _number_ - file size
    * type - _string_ - file type. 'd' => directory,  'f' => file
    * date - _date_ - file last modified date


* **pwd**(< _function_ >callback) - Retrieves the current working directory. callback has 2 parameters: < Error >err, < string >cwd.

* **exist**(< _function_ >callback) - whether a file or direcotry exists. callback has 1 parameters: < boolean >exist.

* **upload**(< _mixed_ >localPath, < _string_ >remotePath, < _function_ >callback) - Sends data to the server to be stored as remotePath. If direcotry path, include self directory and child files. If you want only child files, localPath is "/directory/**". callback has 1 parameter: < Error >err. 
    
    * file		- ex) upload("/test.txt", "/a/b/test.txt", ...)	=>  result : /a/b/test.txt
    * directory		- ex) upload("/directory", "/a/b", ...)		=>  result : /a/b/directory
    * only child files	- ex) upload("/directory/**", "/a/b", ...)	=>  result : /a/b/child files...
    * array	- ex) upload(["/directory/**", "/test.txt"], "/a/b", ...)	=>  result : "/a/b/test.txt" and "/a/b/child files..."


* **download**(< _mixed_ >remotePath, < _string_ >localPath, < _function_ >callback) - Retrieves a file or directory at path from the server. If directory path, include child files. callback has 1 parameter: < Error >err. 

	* file		- ex) download("/test.txt", "/a/b/test.txt", ...)	=>  result : /a/b/test.txt
    * directory		- ex) download("/directory", "/a/b", ...)		=>  result : /a/b/directory
    * only child files	- ex) download("/directory/**", "/a/b", ...)	=>  result : /a/b/child files...
    * array	- ex) download(["/directory/**", "/test.txt"], "/a/b", ...)	=>  result : "/a/b/test.txt" and "/a/b/child files..."
    

* **close**() - Closes the connection to the server after any/all enqueued commands have been executed.




Event
-------
* **open**(< _FTPClient_ >client) - Emitted when connection and authentication were sucessful.

* **close** - Emitted when the connection has fully closed.

* **error**(< _Error_ >err) - Emitted when the connection has fully closed.

* **upload**(< _string_ >uploadedRemotePath) - Emitted when file or directory uploaded.

* **uploading**(< _object_ >data) - (sftp only) Emitted when file was transferred.

* **download**(< _string_ >downloadedLocalPath) - Emitted when file or directory downloaded.

* **downloading**(< _object_ >data) - (sftp only) Emitted when file was transferred.



Examples
===========
```javascript
//Connect
var ftp = new EasyFTP();
var config = {
    host: 'localhost',
    port: 21,
    username: 'id',
    password: 'password',
    type : 'ftp'
};
ftp.connect(config);




/* 
Ex) Directory structure
/test/test.txt
/test/child1
/test/child1/image.png
/test/child1/child2
/test/child1/child2/shell.sh
*/

//Case1. files Upload
var ftp = new EasyFTP();
ftp.connect({...});
//"/test/test.txt", "/test.txt"   or   "/test/test.txt", "/"
ftp.upload("/test/test.txt", "/test.txt", function(err){
	ftp.close();
});
/* result
/test.txt
*/



//Case2. child files Upload
var ftp = new EasyFTP();
ftp.connect({...});
// '/test/**' or '/test/*'
ftp.upload("/test/**", "/", function(err){
	ftp.close();
});
/* result
/test.txt
/child1
/child1/image.png
/child1/child2
/child1/child2/shell.sh
*/



//Case3. directory Upload
var ftp = new EasyFTP();
ftp.connect({...});
ftp.upload("/test", "/", function(err){
	ftp.close();	
});
/* result
/test/test.txt
/test/child1
/test/child1/image.png
/test/child1/child2
/test/child1/child2/shell.sh
*/

//Case4. Multi file Upload
//Array - Object({local:'localPath', remote:'remotePath'})
var arr = [{local:"/test.txt", remote:"/test.txt"}, {local:"/test1.txt", remote:"/abcd/test2.txt"}, {local:"/directory", remote:"/"}];
ftp.upload(arr, function(err){ftp.close();});	// 2 arguments;
/* result
/test.txt
/abcd/test2.txt
/directory
*/

//Array - String
var arr = ["/test.txt", "/abcd/test2.txt", "/directory"];
ftp.upload(arr, "/", function(err){ftp.close();});	// 3 arguments;
/* result
/test.txt
/abcd/test2.txt
/directory
*/

//Array - Object and String
var arr = [{local:"/test.txt", remote:"/directory/test.txt"}, "/abcd/test2.txt", "/directory"];
ftp.upload(arr, "/", function(err){ftp.close();});	// 3 arguments;
/* result
/directory/test.txt
/abcd/test2.txt
/directory
*/



//Case5. file download
var ftp = new EasyFTP();
ftp.connect({...});
//"/test/test.txt", "/test.txt"   or   "/test/test.txt", "/"
ftp.download("/test/test.txt", "/test.txt", function(err){
	ftp.close();	
});
/* result
/test.txt
*/



//Case6. direcotry download
var ftp = new EasyFTP();
ftp.connect({...});
ftp.download("/test", "/", function(err){
	ftp.close();	
});
/* result
/test/test.txt
/test/child1
/test/child1/image.png
/test/child1/child2
/test/child1/child2/shell.sh
*/



//Case7. Multi file download
//Array - Object({local:'localPath', remote:'remotePath'})
var arr = [{remote:"/test.txt", local:"/test.txt"}, {remote:"/test1.txt", local:"/abcd/test2.txt"}, {remote:"/directory", local:"/"}];
ftp.download(arr, function(err){ftp.close();});	// 2 arguments;
/* result
/test.txt
/abcd/test2.txt
/directory
*/

//Array - String
var arr = ["/test.txt", "/abcd/test2.txt", "/directory"];
ftp.download(arr, "/", function(err){ftp.close();});	// 3 arguments;
/* result
/test.txt
/abcd/test2.txt
/directory
*/

//Array - Object and String
var arr = [{remote:"/test.txt", local:"/directory/test.txt"}, "/abcd/test2.txt", "/directory"];
ftp.download(arr, "/", function(err){ftp.close();});	// 3 arguments;
/* result
/directory/test.txt
/abcd/test2.txt
/directory
*/
```

---
_Source: https://npm.io/package/easy-ftp · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._