{"id":13432959,"url":"https://github.com/sergi/jsftp","last_synced_at":"2025-05-14T20:08:39.322Z","repository":{"id":50280835,"uuid":"2029395","full_name":"sergi/jsftp","owner":"sergi","description":"Light and complete FTP client implementation for Node.js","archived":false,"fork":false,"pushed_at":"2020-12-14T23:15:01.000Z","size":701,"stargazers_count":812,"open_issues_count":57,"forks_count":154,"subscribers_count":16,"default_branch":"master","last_synced_at":"2025-05-09T02:58:47.211Z","etag":null,"topics":["callback","ftp","ftp-client","javascript","jsftp","networking","storage"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sergi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2011-07-11T09:17:58.000Z","updated_at":"2025-05-02T22:23:26.000Z","dependencies_parsed_at":"2022-09-26T21:02:03.559Z","dependency_job_id":null,"html_url":"https://github.com/sergi/jsftp","commit_stats":null,"previous_names":[],"tags_count":64,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergi%2Fjsftp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergi%2Fjsftp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergi%2Fjsftp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sergi%2Fjsftp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sergi","download_url":"https://codeload.github.com/sergi/jsftp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253584492,"owners_count":21931547,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["callback","ftp","ftp-client","javascript","jsftp","networking","storage"],"created_at":"2024-07-31T02:01:19.026Z","updated_at":"2025-05-14T20:08:39.284Z","avatar_url":"https://github.com/sergi.png","language":"JavaScript","readme":"# jsftp\n\n[![travis][travis-image]][travis-url] [![npm][npm-image]][npm-url]\n[![downloads][downloads-image]][downloads-url]\n[![styled with prettier](https://img.shields.io/badge/styled_with-prettier-ff69b4.svg)](https://github.com/prettier/prettier)\n\n[travis-image]: https://img.shields.io/travis/sergi/jsftp.svg?style=flat\n[travis-url]: https://travis-ci.org/sergi/jsftp\n[npm-image]: https://img.shields.io/npm/v/jsftp.svg?style=flat\n[npm-url]: https://npmjs.org/package/jsftp\n[downloads-image]: https://img.shields.io/npm/dm/jsftp.svg?style=flat\n[downloads-url]: https://npmjs.org/package/jsftp(https://github.com/prettier/prettier)\n\nA client FTP library for NodeJS that focuses on correctness, clarity and\nconciseness. It doesn't get in the way and plays nice with streaming APIs.\n\n## Starting it up\n\n```javascript\nconst jsftp = require(\"jsftp\");\n\nconst Ftp = new jsftp({\n  host: \"myserver.com\",\n  port: 3331, // defaults to 21\n  user: \"user\", // defaults to \"anonymous\"\n  pass: \"1234\" // defaults to \"@anonymous\"\n});\n```\n\njsftp gives you access to all the raw commands of the FTP protocol in form of\nmethods in the `Ftp` object. It also provides several convenience methods for\nactions that require complex chains of commands (e.g. uploading and retrieving\nfiles, passive operations), as shown below.\n\nWhen raw commands succeed they always pass the response of the server to the\ncallback, in the form of an object that contains two properties: `code`, which\nis the response code of the FTP operation, and `text`, which is the complete\ntext of the response.\n\nRaw (or native) commands are accessible in the form `Ftp.raw(command, params, callback)`\n\nThus, a command like `QUIT` will be called like this:\n\n```javascript\nFtp.raw(\"quit\", (err, data) =\u003e {\n  if (err) {\n    return console.error(err);\n  }\n\n  console.log(\"Bye!\");\n});\n```\n\nand a command like `MKD` (make directory), which accepts parameters, looks like\nthis:\n\n```javascript\nFtp.raw(\"mkd\", \"/new_dir\", (err, data) =\u003e {\n  if (err) {\n    return console.error(err);\n  }\n  console.log(data.text); // Show the FTP response text to the user\n  console.log(data.code); // Show the FTP response code to the user\n});\n```\n\n## API and examples\n\n#### new Ftp(options)\n\n* `options` is an object with the following properties:\n\n```javascript\n{\n  host: 'localhost', // Host name for the current FTP server.\n  port: 3333, // Port number for the current FTP server (defaults to 21).\n  user: 'user', // Username\n  pass: 'pass', // Password\n  createSocket: ({port, host}, firstAction) =\u003e {\n    return net.createConnection({port, host}, firstAction);\n  }, // function that creates the socket, default uses net.createConnection\n}\n```\n\n* `options.createSocket` could be used to implement a proxy for the ftp socket, e.g. socksv5\n\n```javascript\nconst {SocksClient} = require('socks');\nconst ftp = new Ffp({\n  host: 'localhost',\n  port: 3333,\n  user: 'user',\n  pass: 'password',\n  createSocket: ({port, host}, firstAction) =\u003e {\n    return SocksClient.createConnection({\n      proxy: {\n        ipaddress: '159.203.75.200'\n        port: 1080,\n        type: 5\n      },\n\n      command: 'connect',\n\n      destination: {\n        host,\n        port\n      }\n    })\n  }\n})\n```\n\nCreates a new Ftp instance.\n\n#### Ftp.host\n\nHost name for the current FTP server.\n\n#### Ftp.port\n\nPort number for the current FTP server (defaults to 21).\n\n#### Ftp.socket\n\nNodeJS socket for the current FTP server.\n\n#### Ftp.features\n\nArray of feature names for the current FTP server. It is generated when the user\nauthenticates with the `auth` method.\n\n#### Ftp.system\n\nContains the system identification string for the remote FTP server.\n\n### Methods\n\n#### Ftp.raw(command, [...args], callback)\n\nWith the `raw` method you can send any FTP command to the server. The method\naccepts a callback with the signature `err, data`, in which `err` is the error\nresponse coming from the server (usually a 4xx or 5xx error code) and the data\nis an object that contains two properties: `code` and `text`. `code` is an\ninteger indicating the response code of the response and `text` is the response\nstring itself.\n\n#### Ftp.auth(username, password, callback)\n\nAuthenticates the user with the given username and password. If null or empty\nvalues are passed for those, `auth` will use anonymous credentials. `callback`\nwill be called with the response text in case of successful login or with an\nerror as a first parameter, in normal Node fashion.\n\n#### Ftp.ls(filePath, callback)\n\nLists information about files or directories and yields an array of file objects\nwith parsed file properties to the `callback`. You should use this function\ninstead of `stat` or `list` in case you need to do something with the individual\nfile properties.\n\n```javascript\nftp.ls(\".\", (err, res) =\u003e {\n  res.forEach(file =\u003e console.log(file.name));\n});\n```\n\n#### Ftp.list(filePath, callback)\n\nLists `filePath` contents using a passive connection. Calls callback with a\nstring containing the directory contents in long list format.\n\n```javascript\nftp.list(remoteCWD, (err, res) =\u003e {\n  console.log(res);\n  // Prints something like\n  // -rw-r--r--   1 sergi    staff           4 Jun 03 09:32 testfile1.txt\n  // -rw-r--r--   1 sergi    staff           4 Jun 03 09:31 testfile2.txt\n  // -rw-r--r--   1 sergi    staff           0 May 29 13:05 testfile3.txt\n  // ...\n});\n```\n\n#### Ftp.get(remotePath, callback)\n\nGives back a paused socket with the file contents ready to be streamed, or calls\nthe callback with an error if not successful.\n\n```javascript\nvar str = \"\"; // Will store the contents of the file\nftp.get(\"remote/path/file.txt\", (err, socket) =\u003e {\n  if (err) {\n    return;\n  }\n\n  socket.on(\"data\", d =\u003e {\n    str += d.toString();\n  });\n\n  socket.on(\"close\", err =\u003e {\n    if (hadErr) {\n      console.error(\"There was an error retrieving the file.\");\n    }\n  });\n\n  socket.resume();\n});\n```\n\n#### Ftp.get(remotePath, localPath, callback)\n\nStores the remote file directly in the given local path.\n\n```javascript\nftp.get(\"remote/file.txt\", \"local/file.txt\", err =\u003e {\n  if (hadErr) {\n    return console.error(\"There was an error retrieving the file.\");\n  }\n  console.log(\"File copied successfully!\");\n});\n```\n\n#### Ftp.put(source, remotePath, callback)\n\nUploads a file to `filePath`. It accepts a string with the local path for the\nfile, a `Buffer`, or a Readable stream as a `source` parameter.\n\n```javascript\nftp.put(buffer, \"path/to/remote/file.txt\", err =\u003e {\n  if (!err) {\n    console.log(\"File transferred successfully!\");\n  }\n});\n```\n\n#### Ftp.rename(from, to, callback)\n\nRenames a file in the server. `from` and `to` are both filepaths.\n\n```javascript\nftp.rename(from, to, (err, res) =\u003e {\n  if (!err) {\n    console.log(\"Renaming successful!\");\n  }\n});\n```\n\n#### Ftp.keepAlive([wait])\n\nRefreshes the interval thats keep the server connection active. `wait` is an\noptional time period (in milliseconds) to wait between intervals.\n\nYou can find more usage examples in the\n[unit tests](https://github.com/sergi/jsftp/blob/master/test/jsftp_test.js).\nThis documentation will grow as jsftp evolves.\n\n\u003c!-- ## Debugging\n\nIn order to enable debug mode in a FTP connection, a `debugMode` parameter can\nbe used in the constructors's config object:\n\n```javascript\nvar Ftp = new JSFtp({\n  host: \"myserver.com\",\n  port: 3331,\n  user: \"user\",\n  pass: \"1234\",\n  debugMode: true\n});\n```\n\nIt can also be activated or deactivated by calling the `setDebugMode` method:\n\n```javascript\nFtp.setDebugMode(true); // Debug Mode on\nFtp.setDebugMode(false); // Debug mode off\n```\n\nIf the debug mode is on, the jsftp instance will emit `jsftp_debug` events with\ntwo parameters: the first is the type of the event and the second and object\nincluding data related to the event. There are 3 possible types of events:\n\n* `response` events: These are response from the FTP server to the user's FTP\n  commands\n\n* `user_command` events: These are commands that the user issues to the FTP\n  server.\n\n* `event:{event name}` events: These are other events mostly related to the\n  server connection, such as `timeout`, `connect` or `disconnect`. For example,\n  a timeout event will have the name `event:timeout`.\n\nIn order to react to print all debug events (for example), we would listen to\nthe debug messages like this:\n\n```javascript\nFtp.on(\"jsftp_debug\", function(eventType, data) {\n  console.log(\"DEBUG: \", eventType);\n  console.log(JSON.stringify(data, null, 2));\n});\n``` --\u003e\n\n## Installation\n\n    npm install jsftp\n\n## Tests and Coverage\n\nJSFtp tests against ProFTPD by default. To accomplish that, it uses a Docker set-up, so you'll need Docker installed in your machine in order to run tests.\n\nPlease note that the first time you run the tests it will take a while, given that it has to download, configure and run the containerized ProFTPD server.\n\nTo run tests and coverage reports:\n\n    npm test\n\n    ...\n    43 passing (10s)\n\n    |-----------|----------|----------|----------|----------|----------------|\n    |File       |  % Stmts | % Branch |  % Funcs |  % Lines |Uncovered Lines |\n    |-----------|----------|----------|----------|----------|----------------|\n    |All files  |    86.47 |    73.17 |    95.45 |    86.47 |                |\n    |jsftp      |      100 |      100 |      100 |      100 |                |\n    |  index.js |      100 |      100 |      100 |      100 |                |\n    |jsftp/lib  |    86.43 |    73.17 |    95.45 |    86.43 |                |\n    |  jsftp.js |    86.43 |    73.17 |    95.45 |    86.43 |... 722,724,733 |\n    |-----------|----------|----------|----------|----------|----------------|\n\n## License\n\nSee LICENSE.\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsergi%2Fjsftp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsergi%2Fjsftp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsergi%2Fjsftp/lists"}