ssh2-sftp-client 9.0.3 → 9.1.0

package/README.md

@@ -1,66 +1,67 @@
-- [Overview](#orgd38e3db)
-  - [Version 9.x Changes](#orgbc6dbf7)
-- [Installation](#org8538ac8)
-- [Basic Usage](#org0e586d6)
-- [Documentation](#org8b956c0)
-  - [Specifying Paths](#orge4d511d)
-  - [Methods](#org54a5a5f)
-    - [new SftpClient(name) ===> SFTP client object](#org7e1be88)
-    - [connect(config) ===> SFTP object](#org4d439ac)
-    - [list(path, filter) ==> Array[object]](#org1cdf979)
-    - [exists(path) ==> boolean](#org27dfbbb)
-    - [stat(path) ==> object](#org989df3b)
-    - [get(path, dst, options) ==> String|Stream|Buffer](#orgc4730e8)
-    - [fastGet(remotePath, localPath, options) ===> string](#org2f58141)
-    - [put(src, remotePath, options) ==> string](#org6859ddc)
-    - [fastPut(localPath, remotePath, options) ==> string](#org62993ea)
-    - [append(input, remotePath, options) ==> string](#orgbac60b5)
-    - [mkdir(path, recursive) ==> string](#orgf266033)
-    - [rmdir(path, recursive) ==> string](#orgcb249fd)
-    - [delete(path, noErrorOK) ==> string](#orgfef0bf5)
-    - [rename(fromPath, toPath) ==> string](#org916cc1f)
-    - [posixRename(fromPath, toPath) ==> string](#org590854d)
-    - [chmod(path, mode) ==> string](#orgf437cd4)
-    - [realPath(path) ===> string](#org22161d6)
-    - [cwd() ==> string](#orgdba7a3a)
-    - [uploadDir(srcDir, dstDir, options) ==> string](#org583c51e)
-    - [downloadDir(srcDir, dstDir, options) ==> string](#orgc06694a)
-    - [createReadStream(remotePath, options)) ==> stream object](#org5163593)
-    - [createWriteStream(remotePath, options) ==> stream object](#orgbeba46f)
-    - [rcopy(srcPath, dstPath) ==> string](#orgfab48e5)
-    - [end() ==> boolean](#org9ffad87)
-    - [Add and Remove Listeners](#org5c294b3)
-- [Platform Quirks & Warnings](#org6e33ff1)
-  - [Server Capabilities](#org0b56fde)
-  - [Issues with `fastPut()` and `fastGet()` Methods](#org7c6eba4)
-  - [Promises, Events & Managing Exceptions](#org38e15f9)
-    - [Adding Custom Handlers](#org10f1f65)
-  - [Windows Based Servers](#org7057905)
-  - [Don't Re-use SftpClient Objects](#org1775ff2)
-- [FAQ](#org683ae73)
-  - [Remote server drops connections with only an end event](#org7e12a90)
-  - [How can I pass writable stream as dst for get method?](#org7f93e7e)
-  - [How can I upload files without having to specify a password?](#org6f24d1a)
-  - [How can I connect through a Socks Proxy](#org59a22c0)
-  - [Timeout while waiting for handshake or handshake errors](#org0439a3c)
-  - [How can I limit upload/download speed](#orge773153)
-  - [Connection hangs or fails for larger files](#orgf14374e)
-- [Examples](#orge58bfb0)
-- [Troubleshooting](#org5c3ee29)
-  - [Common Errors](#orgd46a3a1)
-    - [Not returning the promise in a `then()` block](#org41486a0)
-    - [Mixing Promise Chains and Async/Await](#org36f96d6)
-    - [Try/catch and Error Handlers](#org367d856)
-    - [Server Differences](#org180dea0)
-    - [Avoid Concurrent Operations](#org2bfd976)
-  - [Debugging Support](#org9590bf5)
-- [Logging Issues](#orga4f395e)
-- [Pull Requests](#orgbed06d9)
-- [Contributors](#org7b575e4)
-
-
-
-<a id="orgd38e3db"></a>
+- [Overview](#orgd72cafd)
+  - [Version 9.1.0 Changes](#org9aa6de9)
+- [Installation](#orgfa343ca)
+- [Basic Usage](#org4ac2087)
+- [Documentation](#orgd23cd4f)
+  - [Specifying Paths](#org0cb332c)
+  - [Methods](#org67943d5)
+    - [new SftpClient(name) ===> SFTP client object](#orgc12cc98)
+    - [connect(config) ===> SFTP object](#org93b5103)
+    - [list(path, filter) ==> Array[object]](#org330e94d)
+    - [exists(path) ==> boolean](#orgb3e6094)
+    - [stat(path) ==> object](#org2b25315)
+    - [get(path, dst, options) ==> String|Stream|Buffer](#org252a716)
+    - [fastGet(remotePath, localPath, options) ===> string](#org5edb596)
+    - [put(src, remotePath, options) ==> string](#org99d1b64)
+    - [fastPut(localPath, remotePath, options) ==> string](#orgdce84b4)
+    - [append(input, remotePath, options) ==> string](#org86b6dd8)
+    - [mkdir(path, recursive) ==> string](#orga867f75)
+    - [rmdir(path, recursive) ==> string](#org893c3d4)
+    - [delete(path, noErrorOK) ==> string](#org877ca9f)
+    - [rename(fromPath, toPath) ==> string](#orgc41333c)
+    - [posixRename(fromPath, toPath) ==> string](#org9493ebc)
+    - [chmod(path, mode) ==> string](#orgf78d430)
+    - [realPath(path) ===> string](#orgf15a5df)
+    - [cwd() ==> string](#org2f554a8)
+    - [uploadDir(srcDir, dstDir, options) ==> string](#orge085c95)
+    - [downloadDir(srcDir, dstDir, options) ==> string](#orgd7cebbc)
+    - [createReadStream(remotePath, options)) ==> stream object](#orgc133c2f)
+    - [createWriteStream(remotePath, options) ==> stream object](#org44e3122)
+    - [rcopy(srcPath, dstPath) ==> string](#org3394196)
+    - [end() ==> boolean](#org5f0471c)
+    - [Add and Remove Listeners](#orga12e63e)
+- [Platform Quirks & Warnings](#org3cbc095)
+  - [Server Capabilities](#orge04f28e)
+  - [Issues with `fastPut()` and `fastGet()` Methods](#orgc96002e)
+  - [Promises, Events & Managing Exceptions](#org955a771)
+    - [Adding Custom Handlers](#org8f7b2d0)
+  - [Windows Based Servers](#orge15889c)
+  - [Don't Re-use SftpClient Objects](#orgb38b894)
+- [FAQ](#org1e76649)
+  - [Remote server drops connections with only an end event](#orge3e4159)
+  - [How can I pass writeable stream as dst for get method?](#org77ed2d3)
+  - [How can I upload files without having to specify a password?](#orgad09bd5)
+  - [How can I connect through a Socks Proxy](#org175d696)
+  - [Timeout while waiting for handshake or handshake errors](#orgd310a6a)
+  - [How can I limit upload/download speed](#org5a0faa2)
+  - [Connection hangs or fails for larger files](#orgffe3a3c)
+  - [Typescript definition file out of date](#org390645f)
+- [Examples](#orgce20a25)
+- [Troubleshooting](#org31d0059)
+  - [Common Errors](#orgf1c2f29)
+    - [Not returning the promise in a `then()` block](#org14ab27b)
+    - [Mixing Promise Chains and Async/Await](#org6c257e3)
+    - [Try/catch and Error Handlers](#org765b1b2)
+    - [Server Differences](#orge67d910)
+    - [Avoid Concurrent Operations](#org734662f)
+  - [Debugging Support](#org658f3d6)
+- [Logging Issues](#orgb0fbb63)
+- [Pull Requests](#orgc22fdba)
+- [Contributors](#org7bb6675)
+
+
+
+<a id="orgd72cafd"></a>
 
 # Overview
 
@@ -68,35 +69,23 @@ an SFTP client for node.js, a wrapper around [SSH2](https://github.com/mscdex/ss
 
 Documentation on the methods and available options in the underlying modules can be found on the [SSH2](https://github.com/mscdex/ssh2) project pages.
 
-Current stable release is **v9.0.2**.
+Current stable release is \*v9.1.0.
 
-Code has been tested against Node versions 14.19.1, 16.15.0 and 18.1.0
+Code has been tested against Node versions 14.21.3, 16.19.1, 18.16.0 and 20.0.0
 
 Node versions < 14.x are not supported.
 
 
-<a id="orgbc6dbf7"></a>
+<a id="org9aa6de9"></a>
 
-## Version 9.x Changes
+## Version 9.1.0 Changes
 
--   Fix bug in `end()` method where it was possible for the module to attempt calling the underlying ssh2 `end()` method when ssh2 has not been initialised. This could lead to undefined reference errors.
--   Fix bug in `get()` method where supplied destination streams were not close, creating a possible resource leak. If the remote file did not exist, the method would return an error, but failed to close any passed in stream supplied as the destination for the data in the `get()` call.
--   Change the default end and close handlers not to throw error or reject promises. Previously, an end or close event would cause an error to be raised or a promise to be rejected if the event was deemed to be *unexpected*. However, classification of events as being unexpected was unreliable and didn't add much real value. Both these handlers will now invalidate the sftp connection object and log that the event fired and nothing else.
--   Changed when event handled flags are reset. Now they are reset after a new set of temporary listeners are added.
--   Don't throw an error when calling end() if there is no active sftp connection. It does no harm to call end() when there is no connection, so no need to raise an error.
--   Use nullish coalescing when setting retry parameters instead of or'ing with defaults. Allows setting values to 0.
--   **Breaking Change**: This version uses syntax not supported in node versions prior to v14. Therefore, node versions less than v14 will not work.
--   **Breaking Change**: This `list()` method no longer accepts a regular expression for filtering the entries to be returned. You can now specify a filter function instead. The function is called for each item in the list of items to be returned, passing in the item object as its only argument. Essentially, this is just a call to `Array.filter()`, so the filter function should behave in the same way i.e. return true for items to be retained and false for those to be dropped.
--   **Breaking Change**: The ability to set `autoClose` on read and write streams and the ability to set `end` on `pipe` operations has been removed. These options caused confusion for users and were too easy to get wrong, plus it made the methods overly complicated. For those use-cases where you want to control streams at a low level, two new methods have been added, `createReadStream()` and `createWriteStream()`. However, it should be noted that client code is 100% responsible for managing streams obtained using these methods. Use at your own risk!
--   **Breaking Change**: The 3rd argument to `uploadDir()` and `downloadDir()` methods has been change. Previously, the argument was a filter function used to select which directories and files to be transferred. The 3rd argument is now an options object with two supported properties, `filter` and `useFastput` (for `uploadDir()`) or `useFastget` (for `downloadDir()`). If `useFastput` is true, the `fastPut()` method will be pused to upload files. If `false` or missing, the slower, but better supported, `put()` method will be used. Likewise, the `useFastget` options can be set to `true` to use the `fastGet()` method for donwloading files, otherwise the slower, but more reliable, `get()` method will be used.
--   The `uploadDir()` and `downloadDir()` methods now use asynchrounous processes to upload/download files. This should result in improved performance for these two methods.
--   New Methods: Two new methods, `createWriteStream()` and `createReadStream()` have been added. These methods will return a stream object connected to a remote file on the `sftp` server. Client code is responsible for managing these stream objects. This includes adding any necessary event listeners and disposing of the objects once finished with them.
--   Refactoring of Listeners: The library manages temporary listeners in order to provide a way to catch events and processes them inside a `Promise` context. Previously, every method added its own set of temporary listeners. However, this could result in multiple sets of listeners being added, especially for methods which call other methods as part of their processing e.g. `rmdir(),` `uploadDir()` and `dowqnloadDir()`. To avoid this, *internal only* versions of each method have been created. These internal methods use an *underscore* `_` prefix. Client code should not use these methods directly.
--   New method: Added `rcopy()` method to perform a remote copy of a file on the remote SFTP server.
--   Bumped ssh2 version to 1.11.0
+-   Added lstat() method
+-   Fixed bug in option hadnling which was preventing setting file mode in get() and put() methods
+-   Fixed bug where a loss of network connections between establishment of the connection and calling various sftp methods was not handled and could result in an event causing the node process to exit with an error.
 
 
-<a id="org8538ac8"></a>
+<a id="orgfa343ca"></a>
 
 # Installation
 
@@ -105,11 +94,11 @@ npm install ssh2-sftp-client
 ```
 
 
-<a id="org0e586d6"></a>
+<a id="org4ac2087"></a>
 
 # Basic Usage
 
-```javascript
+```js
 let Client = require('ssh2-sftp-client');
 let sftp = new Client();
 
@@ -128,7 +117,7 @@ sftp.connect({
 ```
 
 
-<a id="org8b956c0"></a>
+<a id="orgd23cd4f"></a>
 
 # Documentation
 
@@ -137,7 +126,7 @@ The connection options are the same as those offered by the underlying SSH2 modu
 All the methods will return a Promise, except for `on()` and `removeListener()`, which are typically only used in special use cases.
 
 
-<a id="orge4d511d"></a>
+<a id="org0cb332c"></a>
 
 ## Specifying Paths
 
@@ -149,13 +138,13 @@ It is important to recognise that the current remote directory may not always be
 
 There is a small performance hit for using `./` and `../` as the module must query the remote server to determine what the root path is and derive the absolute path. Using absolute paths are therefore more efficient and likely more robust.
 
-When specifying file paths, ensure to include a full path i.e. include the remote filename. Don't expect the module to append the local file name to the path you provide. For example, the following will not work
+When specifying file paths, ensure to include a full path i.e. include the remote file name. Don't expect the module to append the local file name to the path you provide. For example, the following will not work
 
 ```javascript
 client.put('/home/fred/test.txt', '/remote/dir');
 ```
 
-will not result in the file `test.txt` being copied to `/remote/dir/test.txt`. You need to specify the target filename as well e.g.
+will not result in the file `test.txt` being copied to `/remote/dir/test.txt`. You need to specify the target file name as well e.g.
 
 ```javascript
 client.put('/home/fred/test.txt', '/remote/dir/test.txt');
@@ -170,12 +159,12 @@ client.put('/home/fred/test.txt', '/remote/dir/test-copy.txt');
 This will copy the local file `test.txt` to the remote file `test-copy.txt` in the directory `/remote/dir`.
 
 
-<a id="org54a5a5f"></a>
+<a id="org67943d5"></a>
 
 ## Methods
 
 
-<a id="org7e1be88"></a>
+<a id="orgc12cc98"></a>
 
 ### new SftpClient(name) ===> SFTP client object
 
@@ -214,7 +203,7 @@ Constructor to create a new `ssh2-sftp-client` object. An optional `name` string
     ```
 
 
-<a id="org4d439ac"></a>
+<a id="org93b5103"></a>
 
 ### connect(config) ===> SFTP object
 
@@ -240,12 +229,12 @@ Connect to an sftp server. Full documentation for connection options is availabl
       privateKey: fs.readFileSync('/path/to/key'), // Buffer or string that contains
       passphrase: 'a pass phrase', // string - For an encrypted private key
       readyTimeout: 20000, // integer How long (in ms) to wait for the SSH handshake
-      strictVendor: true // boolean - Performs a strict server vendor check
-      debug: myDebug // function - Set this to a function that receives a single
+      strictVendor: true, // boolean - Performs a strict server vendor check
+      debug: myDebug,// function - Set this to a function that receives a single
                     // string argument to get detailed (local) debug information.
-      retries: 2 // integer. Number of times to retry connecting
-      retry_factor: 2 // integer. Time factor used to calculate time between retries
-      retry_minTimeout: 2000 // integer. Minimum timeout between attempts
+      retries: 2, // integer. Number of times to retry connecting
+      retry_factor: 2, // integer. Time factor used to calculate time between retries
+      retry_minTimeout: 2000, // integer. Minimum timeout between attempts
     };
     
     // rarely used options
@@ -272,7 +261,7 @@ Connect to an sftp server. Full documentation for connection options is availabl
 
     ```javascript
     sftp.connect({
-      host: example.com,
+      host: 'example.com',
       port: 22,
       username: 'donald',
       password: 'youarefired'
@@ -280,7 +269,7 @@ Connect to an sftp server. Full documentation for connection options is availabl
     ```
 
 
-<a id="org1cdf979"></a>
+<a id="org330e94d"></a>
 
 ### list(path, filter) ==> Array[object]
 
@@ -301,7 +290,7 @@ Retrieves a directory listing. This method returns a Promise, which once realise
       password: 'my-secret'
     };
     
-    let sftp = new Client;
+    let sftp = new Client();
     
     sftp.connect(config)
       .then(() => {
@@ -324,24 +313,24 @@ Retrieves a directory listing. This method returns a Promise, which once realise
     
     ```javascript
     {
-      type: // file type(-, d, l)
-      name: // file name
-      size: // file size
-      modifyTime: // file timestamp of modified time
-      accessTime: // file timestamp of access time
+      type: '-', // file type(-, d, l)
+      name: 'example.txt', // file name
+      size: 43, // file size
+      modifyTime: 1675645360000, // file timestamp of modified time
+      accessTime: 1675645360000, // file timestamp of access time
       rights: {
-        user:
-        group:
-        other:
+        user: 'rw',
+        group: 'r',
+        other: 'r',
       },
-      owner: // user ID
-      group: // group ID
-      longname: // like ls -l line
+      owner: 1000, // user ID
+      group: 1000, // group ID
+      longname: '-rw-r--r--  1 fred  fred  43 Feb 6 12:02 exaple.txt', // like ls -l line
     }
     ```
 
 
-<a id="org27dfbbb"></a>
+<a id="orgb3e6094"></a>
 
 ### exists(path) ==> boolean
 
@@ -359,7 +348,7 @@ Tests to see if remote file or directory exists. Returns type of remote object i
       password: 'my-secret'
     };
     
-    let sftp = new Client;
+    let sftp = new Client();
     
     sftp.connect(config)
       .then(() => {
@@ -377,7 +366,7 @@ Tests to see if remote file or directory exists. Returns type of remote object i
     ```
 
 
-<a id="org989df3b"></a>
+<a id="org2b25315"></a>
 
 ### stat(path) ==> object
 
@@ -428,7 +417,7 @@ Returns the attributes associated with the object pointed to by `path`.
     ```
 
 
-<a id="orgc4730e8"></a>
+<a id="org252a716"></a>
 
 ### get(path, dst, options) ==> String|Stream|Buffer
 
@@ -484,7 +473,7 @@ In general, if you're going to pass in a string as the destination, you are bett
     -   **Tip:** See examples file in the Git repository for more examples. You can pass any writeable stream in as the destination. For example, if you pass in `zlib.createGunzip()` writeable stream, you can both download and decompress a gzip file 'on the fly'.
 
 
-<a id="org2f58141"></a>
+<a id="org5edb596"></a>
 
 ### fastGet(remotePath, localPath, options) ===> string
 
@@ -527,7 +516,7 @@ Downloads a file at remotePath to localPath using parallel reads for faster thro
     ```
 
 
-<a id="org6859ddc"></a>
+<a id="org99d1b64"></a>
 
 ### put(src, remotePath, options) ==> string
 
@@ -577,7 +566,7 @@ Upload data from local system to remote server. If the `src` argument is a strin
     -   **Tip:** If the src argument is a path string, consider just using `fastPut()`.
 
 
-<a id="org62993ea"></a>
+<a id="orgdce84b4"></a>
 
 ### fastPut(localPath, remotePath, options) ==> string
 
@@ -621,7 +610,7 @@ Uploads the data in file at `localPath` to a new file on remote server at `remot
     ```
 
 
-<a id="orgbac60b5"></a>
+<a id="org86b6dd8"></a>
 
 ### append(input, remotePath, options) ==> string
 
@@ -665,7 +654,7 @@ Append the `input` data to an existing remote file. There is no integrity checki
     ```
 
 
-<a id="orgf266033"></a>
+<a id="orga867f75"></a>
 
 ### mkdir(path, recursive) ==> string
 
@@ -693,7 +682,7 @@ Create a new directory. If the recursive flag is set to true, the method will cr
     ```
 
 
-<a id="orgcb249fd"></a>
+<a id="org893c3d4"></a>
 
 ### rmdir(path, recursive) ==> string
 
@@ -723,7 +712,7 @@ Remove a directory. If removing a directory and recursive flag is set to `true`,
     ```
 
 
-<a id="orgfef0bf5"></a>
+<a id="org877ca9f"></a>
 
 ### delete(path, noErrorOK) ==> string
 
@@ -752,7 +741,7 @@ Delete a file on the remote server.
     ```
 
 
-<a id="org916cc1f"></a>
+<a id="orgc41333c"></a>
 
 ### rename(fromPath, toPath) ==> string
 
@@ -781,11 +770,11 @@ Rename a file or directory from `fromPath` to `toPath`. You must have the necess
     ```
 
 
-<a id="org590854d"></a>
+<a id="org9493ebc"></a>
 
 ### posixRename(fromPath, toPath) ==> string
 
-This method uses the openssh POSIX rename extension introduced in OpenSSH 4.8. The advantage of this version of rename over standard SFTP rename is that it is an atomic operation and will allow renaming a resource where the destination name exists. The POSIX rename will also work on some filesystems which do not support standard SFTP rename because they don't support the system hardlink() call. The POSIX rename extension is available on all openSSH servers from 4.8 and some other implementations. This is an extension to the standard SFTP protocol and therefore is not supported on all sSFTP servers.
+This method uses the openssh POSIX rename extension introduced in OpenSSH 4.8. The advantage of this version of rename over standard SFTP rename is that it is an atomic operation and will allow renaming a resource where the destination name exists. The POSIX rename will also work on some file systems which do not support standard SFTP rename because they don't support the system hardlink() call. The POSIX rename extension is available on all openSSH servers from 4.8 and some other implementations. This is an extension to the standard SFTP protocol and therefore is not supported on all sftp servers.
 
 -   **fromPath:** string. Path to existing file to be renamed.
 -   **toPath:** string. Path for new name. If it already exists, it will be replaced by file specified in fromPath
@@ -808,7 +797,7 @@ client.connect(config)
 ```
 
 
-<a id="orgf437cd4"></a>
+<a id="orgf78d430"></a>
 
 ### chmod(path, mode) ==> string
 
@@ -837,7 +826,7 @@ Change the mode (read, write or execute permissions) of a remote file or directo
     ```
 
 
-<a id="org22161d6"></a>
+<a id="orgf15a5df"></a>
 
 ### realPath(path) ===> string
 
@@ -848,14 +837,14 @@ Converts a relative path to an absolute path on the remote server. This method i
 -   **path:** A file path, either relative or absolute. Can handle '.' and '..', but does not expand '~'.
 
 
-<a id="orgdba7a3a"></a>
+<a id="org2f554a8"></a>
 
 ### cwd() ==> string
 
 Returns what the server believes is the current remote working directory.
 
 
-<a id="org583c51e"></a>
+<a id="orge085c95"></a>
 
 ### uploadDir(srcDir, dstDir, options) ==> string
 
@@ -924,13 +913,13 @@ The `useFastput` option is a boolean option. If `true`, the method will use the
     ```
 
 
-<a id="orgc06694a"></a>
+<a id="orgd7cebbc"></a>
 
 ### downloadDir(srcDir, dstDir, options) ==> string
 
 Download the remote directory specified by `srcDir` to the local file system directory specified by `dstDir`. The `dstDir` directory will be created if required. All sub directories within `srcDir` will also be copied. Any existing files in the local path will be overwritten. No files in the local path will be deleted.
 
-The method also emites `download` events to provide a way to monitor download progress. The download event listener is called with one argument, an object with two properties, source and destination. The source property is the path to the remote file that has been downloaded and the destination is the local path to where the file was downloaded to. You can add a listener for this event using the `on()` method.
+The method also emits `download` events to provide a way to monitor download progress. The download event listener is called with one argument, an object with two properties, source and destination. The source property is the path to the remote file that has been downloaded and the destination is the local path to where the file was downloaded to. You can add a listener for this event using the `on()` method.
 
 The `options` argument is an options object with two supported properties, `filter` and `useFastget`. The `filter` argument is a predicate function which will be called with two arguments for each potential item to be downloaded. The first argument is the full path of the item and the second argument is a boolean, which will be true if the item is a directory. If the function returns true, the item will be included in the download. If it returns false, it will be filtered and ignored. The filter function is called via the `Array.filter` method. These array comprehension methods are known to be unsafe for asynchronous functions. Therefore, only synchronous filter functions are supported at this time.
 
@@ -938,7 +927,7 @@ If the `useFastget` property is set to `true`, the method will use `fastGet()` t
 
 -   **srcDir:** A remote file path specified as a string
 -   **dstDir:** A local file path specified as a string
--   **options:** An object with two supported properties, `filter` and `useFastget`. The filter property is a function accepting two arguments, the full path to an item and a boolean value which will be true if the item is a directory. The function is called for each item in the download path and should return true to include the item and false to exclude it in the download. The `useFastget` property is a boolean. If true, the `fastGet()` method will be used to transfer files. If `false` (the default), the slower but better supported `get()` mehtod is used. .
+-   **options:** An object with two supported properties, `filter` and `useFastget`. The filter property is a function accepting two arguments, the full path to an item and a boolean value which will be true if the item is a directory. The function is called for each item in the download path and should return true to include the item and false to exclude it in the download. The `useFastget` property is a boolean. If true, the `fastGet()` method will be used to transfer files. If `false` (the default), the slower but better supported `get()` method is used. .
 
 1.  Example
 
@@ -989,7 +978,7 @@ If the `useFastget` property is set to `true`, the method will use `fastGet()` t
     ```
 
 
-<a id="org5163593"></a>
+<a id="orgc133c2f"></a>
 
 ### createReadStream(remotePath, options)) ==> stream object
 
@@ -1003,35 +992,35 @@ Returns a read stream object which is attached to the remote file specified by t
     -   **mode:** 0o666
     -   **autoClose:** defaults to true. If set to false, client code is responsible for closing file descriptors when finished
     -   **start:** Default 0. Position to start reading bytes from (inclusive)
-    -   **end:** Postion to stop reading bytes (inclusive).
+    -   **end:** Position to stop reading bytes (inclusive).
 
 
-<a id="orgbeba46f"></a>
+<a id="org44e3122"></a>
 
 ### createWriteStream(remotePath, options) ==> stream object
 
-Returns a write stream object which is attached to the remote file specified in the `remotePath` argument. This is a low legvel function which just returns the stream object. Client code is fully responsible for managing that object, including closing any file descriptiors and removing listeners etc.
+Returns a write stream object which is attached to the remote file specified in the `remotePath` argument. This is a low level function which just returns the stream object. Client code is fully responsible for managing that object, including closing any file descriptors and removing listeners etc.
 
 -   **remotePath:** Path to the remote file specified as a string
 -   **options:** An object containing stream options. Supported properties include
     -   **flags:** default 'w'
-    -   **encoding:** defulat null
+    -   **encoding:** default null
     -   **mode:** 0o666
     -   **autoClose:** true
     -   **start:** Byte position to start writing from (inclusive). May require changing flag to 'r+'.
 
 
-<a id="orgfab48e5"></a>
+<a id="org3394196"></a>
 
 ### rcopy(srcPath, dstPath) ==> string
 
-Perfrom a remote file copy. The file identified by the `srcPath` argument will be copied to the file specified as the `dstPath` argument. The directory where `dstPath` will be placed must exist, but the actual file must not i.e. no overwrites allowed.
+Perform a remote file copy. The file identified by the `srcPath` argument will be copied to the file specified as the `dstPath` argument. The directory where `dstPath` will be placed must exist, but the actual file must not i.e. no overwrites allowed.
 
 -   **srcPath:** Path to remote file to be copied specified as a string
--   **dstPath:** Path to where the copy will be creaeted specified as a string
+-   **dstPath:** Path to where the copy will be created specified as a string
 
 
-<a id="org9ffad87"></a>
+<a id="org5f0471c"></a>
 
 ### end() ==> boolean
 
@@ -1055,7 +1044,7 @@ Ends the current client session, releasing the client socket and associated reso
     ```
 
 
-<a id="org5c294b3"></a>
+<a id="orga12e63e"></a>
 
 ### Add and Remove Listeners
 
@@ -1076,56 +1065,56 @@ Although normally not required, you can add and remove custom listeners on the s
     Removes the specified listener from the event specified in eventType. Note that the `end()` method automatically removes all listeners from the client object.
 
 
-<a id="org6e33ff1"></a>
+<a id="org3cbc095"></a>
 
 # Platform Quirks & Warnings
 
 
-<a id="org0b56fde"></a>
+<a id="orge04f28e"></a>
 
 ## Server Capabilities
 
-All SFTP servers and platforms are not equal. Some facilities provided by `ssh2-sftp-client` either depend on capabilities of the remote server or the underlying capabilities of the remote server platform. As an example, consider `chmod()`. This command depends on a remote filesystem which implements the 'nix' concept of users and groups. The *win32* platform does not have the same concept of users and groups, so `chmod()` will not behave in the same way.
+All SFTP servers and platforms are not equal. Some facilities provided by `ssh2-sftp-client` either depend on capabilities of the remote server or the underlying capabilities of the remote server platform. As an example, consider `chmod()`. This command depends on a remote file system which implements the 'nix' concept of users and groups. The *win32* platform does not have the same concept of users and groups, so `chmod()` will not behave in the same way.
 
 One way to determine whether an issue you are encountering is due to `ssh2-sftp-client` or due to the remote server or server platform is to use a simple CLI sftp program, such as openSSH's sftp command. If you observe the same behaviour using plain `sftp` on the command line, the issue is likely due to server or remote platform limitations. Note that you should not use a GUI sftp client, like `Filezilla` or `winSCP` as such GUI programs often attempt to hide these server and platform incompatibilities and will take additional steps to simulate missing functionality etc. You want to use a CLI program which does as little as possible.
 
 
-<a id="org7c6eba4"></a>
+<a id="orgc96002e"></a>
 
 ## Issues with `fastPut()` and `fastGet()` Methods
 
-The `fastPut()` and `fastGet()` methods are known to be somewhat dependent on SFTP server capabilities. Some SFTP servers just do not work correctly with concurrent connections and some are known to have issues with negotiating packet sizes. These issues can sometimes be resolved by tweaking the options supplied to the methods, such as setting number of concurrent connections or a psecific packet size.
+The `fastPut()` and `fastGet()` methods are known to be somewhat dependent on SFTP server capabilities. Some SFTP servers just do not work correctly with concurrent connections and some are known to have issues with negotiating packet sizes. These issues can sometimes be resolved by tweaking the options supplied to the methods, such as setting number of concurrent connections or a specific packet size.
 
 To see an example of the type of issues you can observe with `fastPut()` or `fastGet()`, have a look at [issue 407](https://github.com/theophilusx/ssh2-sftp-client/issues/407), which describes the experiences of one user. Bottom line, when it works, it tends to work well and be significantly faster than using just `get()` or `put()`. However, when developing code to run against different SFTP servers, especially where you are unable to test against each server, you are likely better off just using `get()` and `put()` or structuring your code so that users can select which method to use (this is what `ssh2-sftp-client` does - for example, see the `!downloadDir()` and `uploadDir()` methods.
 
 
-<a id="org38e15f9"></a>
+<a id="org955a771"></a>
 
 ## Promises, Events & Managing Exceptions
 
 One of the challenges in providing a Promise based API over a module like SSH2, which is event based is how to ensure events are handled appropriately. The challenge is due to the synchronous nature of events. You cannot use `try/catch` for events because you have no way of knowing when the event might fire. For example, it could easily fire after your `try/catch` block as completed execution.
 
-Things become even more complicated once you mix in Promises. When you define a promise, you have to methods which can be called to fulfil a promise, `resolve` and `reject`. Only one can be called - once you call `resolve`, you cannot call `reject` (well, you can call it, but it won't have any impact on the fulfilment status of the promise). The problem arises when an event, for exmaple an `error` event is fired either after you have resolved a promise or possibly in-between promises. If you don't catch the `error` event, your script will likely crash with an `uncaught exception` error.
+Things become even more complicated once you mix in Promises. When you define a promise, you have to methods which can be called to fulfil a promise, `resolve` and `reject`. Only one can be called - once you call `resolve`, you cannot call `reject` (well, you can call it, but it won't have any impact on the fulfilment status of the promise). The problem arises when an event, for example an `error` event is fired either after you have resolved a promise or possibly in-between promises. If you don't catch the `error` event, your script will likely crash with an `uncaught exception` error.
 
 To make matters worse, some servers, particularly servers running on a Windows platform, will raise multiple errors for the same error *event*. For example, when you attempt to connect with a bad username or password, you will get a `All authentication methods have failed` exception. However, under Windows, you will also get a `Connection reset by peer` exception. If we reject the connect promise based on the authentication failure exception, what do we do with the `reset by peer` exception? More critically, what will handle that exception given the promise has already been fulfilled and completed? To make matters worse, it seems that Windows based servers also raise an error event for *non-errors*. For example, when you call the `end()` method, the connection is closed. On windows, this also results in a *connection reset by peer* error. While it could be argued that the remote server resetting the connection after receiving a disconnect request is not an error, it doesn't change the fact that one is raised and we need to somehow deal with it.
 
-To handle this, `ssh2-sftp-client` implements a couple of strategies. Firstly, when you call one of the module's methods, it adds `error`, `end` and `close` event listeners which will call the `reject` moethod on the enclosing promise. It also keeps track of whether an error has been handled and if it has, it ignores any subsequent errors until the promise ends. Typically, the first error caught has the most relevant information and any subsequent error events are less critical or informative, so ignoring them has no negative impact. Provided one of the events is raised before the promise is fulfilled, these handlers will consume the event and deal with it appropriately.
+To handle this, `ssh2-sftp-client` implements a couple of strategies. Firstly, when you call one of the module's methods, it adds `error`, `end` and `close` event listeners which will call the `reject` method on the enclosing promise. It also keeps track of whether an error has been handled and if it has, it ignores any subsequent errors until the promise ends. Typically, the first error caught has the most relevant information and any subsequent error events are less critical or informative, so ignoring them has no negative impact. Provided one of the events is raised before the promise is fulfilled, these handlers will consume the event and deal with it appropriately.
 
 In testing, it was found that in some situations, particularly during connect operations, subsequent errors fired with a small delay. This prevents the errors from being handled by the event handlers associated with the connect promise. To deal with this, a small 500ms delay has been added to the connect() method, which effectively delays the removal of the event handlers until all events have been caught.
 
-The other area where additional events are fired is during the end() call. To deal with these events, the `end()` method setus up listeners which will simply ignore additional `error`, `end` and `close` events. It is assumed that once you have called `end()` you really only care about any main error which occurs and no longer care about other errors that may be raised as the connection is terminated.
+The other area where additional events are fired is during the end() call. To deal with these events, the `end()` method sets up listeners which will simply ignore additional `error`, `end` and `close` events. It is assumed that once you have called `end()` you really only care about any main error which occurs and no longer care about other errors that may be raised as the connection is terminated.
 
 In addition to the promise based event handlers, `ssh2-sftp-client` also implements global event handlers which will catch any `error`, `end` or `close` events. Essentially, these global handlers only reset the `sftp` property of the client object, effectively ensuring any subsequent calls are rejected and in the case of an error, send the error to the console.
 
 
-<a id="org10f1f65"></a>
+<a id="org8f7b2d0"></a>
 
 ### Adding Custom Handlers
 
 While the above strategies appear to work for the majority of use cases, there are always going to be edge cases which require more flexible or powerful event handling. To support this, the `on()` and `removeListener()` methods are provided. Any event listener added using the `on()` method will be added at the beginning of the list of handlers for that event, ensuring it will be called before any global or promise local events. See the documentation for the `on()` method for details.
 
 
-<a id="org7057905"></a>
+<a id="orge15889c"></a>
 
 ## Windows Based Servers
 
@@ -1134,7 +1123,7 @@ It appears that when the sftp server is running on Windows, a *ECONNRESET* error
 The best way to avoid this issue is to not re-use client objects. Always generate a new sftp client object for each new connection.
 
 
-<a id="org1775ff2"></a>
+<a id="orgb38b894"></a>
 
 ## Don't Re-use SftpClient Objects
 
@@ -1143,12 +1132,12 @@ Due to an issue with *ECONNRESET* error signals when connecting to Windows based
 To avoid this problem, don't re-use SftpClient objects. Generate a new SftpClient object for each connection. You can perform multiple actions with a single connection e.g. upload multiple files, download multiple files etc, but after you have called end(), you should not try to re-use the object with a further connect() call. Create a new object instead.
 
 
-<a id="org683ae73"></a>
+<a id="org1e76649"></a>
 
 # FAQ
 
 
-<a id="org7e12a90"></a>
+<a id="orge3e4159"></a>
 
 ## Remote server drops connections with only an end event
 
@@ -1159,9 +1148,9 @@ Clients first make an unauthenticated connection to the SFTP server to begin neg
 One way to avoid this type of issue is to add a delay between connection attempts. It does not need to be a very long delay - just sufficient to permit the previous connection to be authenticated. In fact, the default setting for openSSH is `10:30:60`, so you really just need to have enough delay to ensure that the 1st connection has completed authentication before the 11th connection is attempted.
 
 
-<a id="org7f93e7e"></a>
+<a id="org77ed2d3"></a>
 
-## How can I pass writable stream as dst for get method?
+## How can I pass writeable stream as dst for get method?
 
 If the dst argument passed to the get method is a writeable stream, the remote file will be piped into that writeable. If the writeable you pass in is a writeable stream created with `fs.createWriteStream()`, the data will be written to the file specified in the constructor call to `createWriteStream()`.
 
@@ -1218,7 +1207,7 @@ sftp
 ```
 
 
-<a id="org6f24d1a"></a>
+<a id="orgad09bd5"></a>
 
 ## How can I upload files without having to specify a password?
 
@@ -1253,7 +1242,7 @@ sftp.connect({
 ```
 
 
-<a id="org59a22c0"></a>
+<a id="org175d696"></a>
 
 ## How can I connect through a Socks Proxy
 
@@ -1289,16 +1278,16 @@ client.connect({
 ```
 
 
-<a id="org0439a3c"></a>
+<a id="orgd310a6a"></a>
 
 ## Timeout while waiting for handshake or handshake errors
 
 Some users have encountered the error 'Timeout while waiting for handshake' or 'Handshake failed, no matching client->server ciphers. This is often due to the client not having the correct configuration for the transport layer algorithms used by ssh2. One of the connect options provided by the ssh2 module is `algorithm`, which is an object that allows you to explicitly set the key exchange, ciphers, hmac and compression algorithms as well as server host key used to establish the initial secure connection. See the SSH2 documentation for details. Getting these parameters correct usually resolves the issue.
 
-When encountering this type of problem, one worthwhile approach is to use openSSH's CLI sftp program with the `-v` switch to raise loggin levels. This will show you what algorithms the CLI is using. You can then use this information to match the names with the accepted algorithm names documented in the `ssh2` README to set the properties in the `algorithms` object.
+When encountering this type of problem, one worthwhile approach is to use openSSH's CLI sftp program with the `-v` switch to raise logging levels. This will show you what algorithms the CLI is using. You can then use this information to match the names with the accepted algorithm names documented in the `ssh2` README to set the properties in the `algorithms` object.
 
 
-<a id="orge773153"></a>
+<a id="org5a0faa2"></a>
 
 ## How can I limit upload/download speed
 
@@ -1338,7 +1327,7 @@ try {
 ```
 
 
-<a id="orgf14374e"></a>
+<a id="orgffe3a3c"></a>
 
 ## Connection hangs or fails for larger files
 
@@ -1349,14 +1338,21 @@ A symptom of this issue is that you are able to upload small files, but uploadin
 For more explanation, see [issue #342](https://github.com/theophilusx/ssh2-sftp-client/issues/342).
 
 
-<a id="orge58bfb0"></a>
+<a id="org390645f"></a>
+
+## Typescript definition file out of date
+
+This project does not use Typescript. However, typescript definition files are provided by other 3rd parties. Sometimes, these definition files have not stayed up-to-date with the current version of this module. If you encounter this issue, you need to report it to the party responsible for the definition file, not this project.
+
+
+<a id="orgce20a25"></a>
 
 # Examples
 
 I have started collecting example scripts in the example directory of the repository. These are mainly scripts I have put together in order to investigate issues or provide samples for users. They are not robust, lack adequate error handling and may contain errors. However, I think they are still useful for helping developers see how the module and API can be used.
 
 
-<a id="org5c3ee29"></a>
+<a id="org31d0059"></a>
 
 # Troubleshooting
 
@@ -1371,14 +1367,14 @@ Note also that in the repository there are two useful directories. The first is
 The second directory is the validation directory. I have some very simple scripts in this directory which perform basic tasks using only the `ssh2` modules (no `ssh2-sftp-client` module). These can be useful when trying to determine if the issue is with the underlying `ssh2` module or the `ssh2-sftp-client` wrapper module.
 
 
-<a id="orgd46a3a1"></a>
+<a id="orgf1c2f29"></a>
 
 ## Common Errors
 
-There are some common errors people tend to make when using Promises or Asyc/Await. These are by far the most common problem found in issues logged against this module. Please check for some of these before logging your issue.
+There are some common errors people tend to make when using Promises or Async/Await. These are by far the most common problem found in issues logged against this module. Please check for some of these before logging your issue.
 
 
-<a id="org41486a0"></a>
+<a id="org14ab27b"></a>
 
 ### Not returning the promise in a `then()` block
 
@@ -1415,7 +1411,7 @@ Note the `return` statements. These ensure that the Promise returned by the clie
 A common symptom of this type of error is for file uploads or download to fail to complete or for data in those files to be truncated. What is happening is that the connection is being ended before the transfer has completed.
 
 
-<a id="org36f96d6"></a>
+<a id="org6c257e3"></a>
 
 ### Mixing Promise Chains and Async/Await
 
@@ -1468,32 +1464,32 @@ async function doSftp() {
     await sftp.fastGet(`${d}/foo.txt`, 'bat.txt');
   } catch (e) {
     console.error(e.message);
-  } finally () {
+  } finally {
     await sftp.end();
   }
 }
 ```
 
 
-<a id="org367d856"></a>
+<a id="org765b1b2"></a>
 
 ### Try/catch and Error Handlers
 
 Another common error is to try and use a try/catch block to catch event signals, such as an error event. In general, you cannot use try/catch blocks for asynchronous code and expect errors to be caught by the `catch` block. Handling errors in asynchronous code is one of the key reasons we now have the Promise and async/await frameworks.
 
-The basic problem is that the try/catch block will have completed execution before the asynchronous code has completed. If the asynchronous code has not compleed, then there is a potential for it to raise an error. However, as the try/catch block has already completed, there is no *catch* waiting to catch the error. It will bubble up and probably result in your script exiting with an uncaught exception error.
+The basic problem is that the try/catch block will have completed execution before the asynchronous code has completed. If the asynchronous code has not completed, then there is a potential for it to raise an error. However, as the try/catch block has already completed, there is no *catch* waiting to catch the error. It will bubble up and probably result in your script exiting with an uncaught exception error.
 
 Error events are essentially asynchronous code. You don't know when such events will fire. Therefore, you cannot use a try/catch block to catch such event errors. Even creating an error handler which then throws an exception won't help as the key problem is that your try/catch block has already executed. There are a number of alternative ways to deal with this situation. However, the key symptom is that you see occasional uncaught error exceptions that cause your script to exit abnormally despite having try/catch blocks in your script. What you need to do is look at your code and find where errors are raised asynchronously and use an event handler or some other mechanism to manage any errors raised.
 
 
-<a id="org180dea0"></a>
+<a id="orge67d910"></a>
 
 ### Server Differences
 
 Not all SFTP servers are the same. Like most standards, the SFTP protocol has some level of interpretation and allows different levels of compliance. This means there can be differences in behaviour between different servers and code which works with one server will not work the same with another. For example, the value returned by *realpath* for non-existent objects can differ significantly. Some servers will throw an error for a particular operation while others will just return null, some servers support concurrent operations (such as used by fastGet/fastPut) while others will not and of course, the text of error messages can vary significantly. In particular, we have noticed significant differences across different platforms. It is therefore advisable to do comprehensive testing when the SFTP server is moved to a new platform. This includes moving from to a cloud based service even if the underlying platform remains the same. I have noticed that some cloud platforms can generate unexpected events, possibly related to additional functionality or features associated with the cloud implementation. For example, it appears SFTP servers running under Azure will generate an error event when the connection is closed even when the client has requested the connection be terminated. The same SFTP server running natively on Windows does not appear to exhibit such behaviour.
 
 
-<a id="org2bfd976"></a>
+<a id="org734662f"></a>
 
 ### Avoid Concurrent Operations
 
@@ -1502,7 +1498,7 @@ Technically, SFTP should be able to perform multiple operations concurrently. As
 If you are going to try and perform concurrent operations, you need to test extensively and ensure you are using data which is large enough that context switching does occur (i.e. the request is not completed in a single run). Some SFTP servers will handle concurrent operations better than others.
 
 
-<a id="org9590bf5"></a>
+<a id="org658f3d6"></a>
 
 ## Debugging Support
 
@@ -1535,7 +1531,7 @@ If you just want to see debug messages from `ssh2-sftp-client` and exclude debug
 ```
 
 
-<a id="orga4f395e"></a>
+<a id="orgb0fbb63"></a>
 
 # Logging Issues
 
@@ -1552,7 +1548,7 @@ I am happy to try and help diagnose and fix any issues you encounter while using
 Perhaps the best assistance is a minimal reproducible example of the issue. Once the issue can be readily reproduced, it can usually be fixed very quickly.
 
 
-<a id="orgbed06d9"></a>
+<a id="orgc22fdba"></a>
 
 # Pull Requests
 
@@ -1563,11 +1559,13 @@ Pull requests are always welcomed. However, please ensure your changes pass all
 This module will adopt a standard semantic versioning policy. Please indicate in your pull request what level of change it represents i.e.
 
 -   **Major:** Change to API or major change in functionality which will require an increase in major version number.
+
 -   **Minor:** Minor change, enhancement or new feature which does not change existing API and will not break existing client code.
+
 -   **Bug Fix:** No change to functionality or features. Simple fix of an existing bug.
 
 
-<a id="org7b575e4"></a>
+<a id="org7bb6675"></a>
 
 # Contributors