ssh2-sftp-client 9.0.4 → 9.1.0

package/README.org

@@ -9,81 +9,21 @@ convenience abstraction as well as a Promise based API.
 Documentation on the methods and available options in the underlying modules can
 be found on the [[https://github.com/mscdex/ssh2][SSH2]] project pages.
 
-Current stable release is *v9.0.4*.
+Current stable release is *v9.1.0.
 
-Code has been tested against Node versions 14.20.0, 16.17.2 and 18.8.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. 
 
-** Version 9.x Changes
-  - Fix bug in ~connect()~ method when private key data was corrupted. The method was not
-    handling errors fro corrupted ssh private keys and would hang indefinitely without
-    reporting any error. Now reports that it was unable to parse the private key. 
-  - 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 used 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
-    downloading files, otherwise the slower, but more reliable, ~get()~ method
-    will be used.
-  - The ~uploadDir()~ and ~downloadDir()~ methods now use asynchronous 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.
-  - Re-factoring 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
+** Version 9.1.0 Changes
 
+- 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.
+   
 * Installation
 
 #+begin_src shell
@@ -92,7 +32,7 @@ Node versions < 14.x are not supported.
 
 * Basic Usage
 
-#+begin_src javascript
+#+begin_src js
   let Client = require('ssh2-sftp-client');
   let sftp = new Client();
 
@@ -250,12 +190,12 @@ for that package for an explanation of these values.
     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
@@ -282,7 +222,7 @@ for that package for an explanation of these values.
 
 #+begin_src javascript
   sftp.connect({
-    host: example.com,
+    host: 'example.com',
     port: 22,
     username: 'donald',
     password: 'youarefired'
@@ -313,7 +253,7 @@ directory.
     password: 'my-secret'
   };
 
-  let sftp = new Client;
+  let sftp = new Client();
 
   sftp.connect(config)
     .then(() => {
@@ -336,19 +276,19 @@ The objects in the array returned by ~list()~ have the following properties;
 
 #+begin_src 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
   }
 #+end_src
 
@@ -369,7 +309,7 @@ if it exists or false if it does not.
     password: 'my-secret'
   };
 
-  let sftp = new Client;
+  let sftp = new Client();
 
   sftp.connect(config)
     .then(() => {
@@ -1176,6 +1116,7 @@ Removes the specified listener from the event specified in eventType. Note that
 the ~end()~ method automatically removes all listeners from the client object.
 
 * Platform Quirks & Warnings
+
 ** Server Capabilities
 
    All SFTP servers and platforms are not equal. Some facilities provided by
@@ -1544,6 +1485,7 @@ the =ssh2= README to set the properties in the =algorithms= object.
        await client.end();
      }
    #+end_src
+
 ** Connection hangs or fails for larger files
 
  This was contributed by Ladislav Jacho. Thanks. 
@@ -1557,6 +1499,13 @@ the =ssh2= README to set the properties in the =algorithms= object.
  
  For more explanation, see [[https://github.com/theophilusx/ssh2-sftp-client/issues/342][issue #342]].
  
+** 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.
+
 * Examples
 
 I have started collecting example scripts in the example directory of the
@@ -1730,7 +1679,7 @@ the ~ssh2-sftp-client~ wrapper module.
          await sftp.fastGet(`${d}/foo.txt`, 'bat.txt');
        } catch (e) {
          console.error(e.message);
-       } finally () {
+       } finally {
          await sftp.end();
        }
      }
@@ -1836,6 +1785,7 @@ based on messages which start with 'CLIENT' e.g.
     }
   }
 #+end_src
+
 * Logging Issues
 
 Please log an issue for all bugs, questions, feature and enhancement
@@ -1880,8 +1830,10 @@ 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.
 
@@ -1913,3 +1865,4 @@ Thanks to the following for their contributions -
   Also included test to check for this regression in future.
 - cakemasher :: Contributed fix for removeTempListeners().
   
+  

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ssh2-sftp-client",
-  "version": "9.0.4",
+  "version": "9.1.0",
   "description": "ssh2 sftp client for node",
   "main": "src/index.js",
   "repository": {
@@ -40,7 +40,7 @@
     "eslint-plugin-mocha": "^10.0.3",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-promise": "^6.0.0",
-    "eslint-plugin-unicorn": "^43.0.2",
+    "eslint-plugin-unicorn": "^46.0.0",
     "mocha": "^10.0.0",
     "moment": "^2.29.1",
     "nyc": "^15.1.0",
@@ -51,6 +51,6 @@
   "dependencies": {
     "concat-stream": "^2.0.0",
     "promise-retry": "^2.0.1",
-    "ssh2": "^1.11.0"
+    "ssh2": "^1.12.0"
   }
 }