jsftp

library2.1.3jsnpmunverified

jsftp is a client library for the File Transfer Protocol (FTP) specifically designed for Node.js environments. It emphasizes correctness, clarity, and conciseness, providing both low-level access to raw FTP commands and higher-level convenience methods for common operations like file transfers and directory listings. The current stable version is 2.1.3, released on an as-needed basis for bug fixes and feature enhancements, with previous major versions dropping older Node.js compatibility and updating APIs. A key differentiator is its integration with Node.js streaming APIs, allowing for efficient handling of file data. It exposes the underlying FTP protocol responses with `code` and `text` properties, giving developers granular control and insight into server interactions.

http-networking

npm install jsftp

github ↗package ↗

INSTALL

IMPORT

SIG · JSFTP

jsftp

http-networkingjavascriptv2.1.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

jsftp (constructor)

✓ const JsFtp = require('jsftp');

✗ import JsFtp from 'jsftp';

This library is primarily designed for CommonJS. While Node.js supports ESM, the primary usage pattern demonstrated is using `require()` to import the constructor function.

JsFtp instance

✓ const ftp = new JsFtp({ host: '...' });

✗ const ftp = jsftp({ host: '...' });

The imported `jsftp` is a constructor function and must be called with `new` to create an FTP client instance.

raw command method

✓ ftp.raw('quit', (err, data) => { /* ... */ });

✗ ftp.quit((err, data) => { /* ... */ });

All native FTP commands are accessed via the `ftp.raw(command, [...args], callback)` method. There are convenience methods for common operations, but direct protocol commands use `raw`.

This code demonstrates how to establish a connection to an FTP server, retrieve its system information using a raw command, and then gracefully disconnect. It uses environment variables for host, port, user, and password for secure configuration.

Debug

Known issues

breakingThe `raw` API underwent significant changes in version 2.0.0. Code relying on the exact structure or behavior of `raw` command responses from prior versions may break.

fix

Review the documentation for `jsftp` v2.0.0 to understand the new `raw` API and adapt your code accordingly. Responses now consistently return an object with `code` and `text` properties.

affects: >=2.0.0

breakingCompatibility for Node.js versions older than 0.8 was dropped in version 1.5.0. Running `jsftp` on very old Node.js environments will lead to errors.

fix

Ensure your Node.js environment is at least version 6.x or newer, as specified in the package's engine requirements (`engines.node: ">=6"`).

affects: >=1.5.0

gotchaPrior to version 1.3.7, attempting two simultaneous passive (PASV) requests could result in an `ECONNREFUSED` error and potentially crash the application due to improper error handling.

fix

Upgrade `jsftp` to version 1.3.7 or newer. This version introduces proper error generation for simultaneous PASV requests, allowing your application to handle the error gracefully instead of crashing. It is still recommended to sequentialize passive operations where possible.

affects: <1.3.7

gotchaIn versions prior to 1.3.4, issuing a `LIST` command (directly or via `Ftp.ls`) for a non-existent file or directory would not reliably catch the error or notify the `ls` callback, leading to unhandled promises or stalled operations.

fix

Update `jsftp` to version 1.3.4 or higher to ensure that `LIST` commands for invalid paths correctly propagate errors to the callback.

affects: <1.3.4

gotchaBefore version 1.3.1, the `get` method could sometimes attempt to retrieve a file even if there was an error obtaining the passive socket, leading to unexpected behavior or resource leaks.

fix

Upgrade `jsftp` to version 1.3.1 or newer. This version fixed the `get` method to correctly abort file retrieval when passive socket errors occur.

affects: <1.3.1

Errors

Common errors & fixes

ECONNREFUSED on two consecutive PASV operations

Attempting to perform two passive FTP operations (e.g., file transfers or directory listings) concurrently before `jsftp` version 1.3.7.

fix

Upgrade to `jsftp` v1.3.7 or higher, which will instead generate an error for this scenario. Prefer sequentializing passive operations or ensure robust error handling for concurrent requests.

LIST command or Ftp.ls callback not fired for non-existent path

Using the `LIST` command or the `Ftp.ls` convenience method on an invalid or non-existent remote path when using `jsftp` versions older than 1.3.4.

fix

Update `jsftp` to version 1.3.4 or newer to ensure that errors for non-existent paths are correctly passed to the callback.

File transfer with Ftp.get proceeds despite passive socket error

A bug in `jsftp` versions prior to 1.3.1 where the `get` method would not properly halt file retrieval even if there was a preceding error in establishing the passive data connection.

fix

Upgrade `jsftp` to version 1.3.1 or a later version to fix this behavior, ensuring `get` respects passive socket errors.

Upgrade

Version history

2.1.3latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/sergi/jsftp ↗

packagehttps://www.npmjs.com/package/jsftp ↗