ssh2-sftp-client 9.0.3 → 9.1.0

package/README.org

@@ -9,87 +9,30 @@ 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.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. 
 
-** Version 9.x 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
+** 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
-npm install ssh2-sftp-client
+  npm install ssh2-sftp-client
 #+end_src
 
 * Basic Usage
 
-#+begin_src javascript
+#+begin_src js
   let Client = require('ssh2-sftp-client');
   let sftp = new Client();
 
@@ -151,7 +94,7 @@ All the methods will return a Promise, except for ~on()~ and
    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
+   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
 
    #+begin_src javascript
@@ -159,7 +102,7 @@ All the methods will return a Promise, except for ~on()~ and
    #+end_src
 
    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.
+   ~/remote/dir/test.txt~. You need to specify the target file name as well e.g.
 
    #+begin_src javascript
      client.put('/home/fred/test.txt', '/remote/dir/test.txt');
@@ -247,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
@@ -279,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'
@@ -310,7 +253,7 @@ directory.
     password: 'my-secret'
   };
 
-  let sftp = new Client;
+  let sftp = new Client();
 
   sftp.connect(config)
     .then(() => {
@@ -333,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
 
@@ -366,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(() => {
@@ -824,11 +767,11 @@ necessary permissions to modify the remote file.
 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
+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 sSFTP servers.
+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
@@ -1001,7 +944,7 @@ 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
+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
@@ -1030,7 +973,7 @@ services.
   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
+  files. If ~false~ (the default), the slower but better supported ~get()~ method is
   used. .
   
 **** Example
@@ -1098,19 +1041,19 @@ services.
     - 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). 
 
 *** 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
+   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 descriptiors and removing listeners etc.
+   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
@@ -1118,13 +1061,13 @@ services.
 
 *** rcopy(srcPath, dstPath) ==> string
 
-   Perfrom a remote file copy. The file identified by the ~srcPath~ argument will
+   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
 
 *** end() ==> boolean
 
@@ -1173,12 +1116,13 @@ 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
    ~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
+   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.
@@ -1200,7 +1144,7 @@ the ~end()~ method automatically removes all listeners from the client object.
    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.
+   a specific packet size.
 
    To see an example of the type of issues you can observe with ~fastPut()~ or
    ~fastGet()~, have a look at [[https://github.com/theophilusx/ssh2-sftp-client/issues/407][issue 407]], which describes the experiences of one
@@ -1226,7 +1170,7 @@ the ~end()~ method automatically removes all listeners from the client object.
    =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
+   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.
 
@@ -1248,7 +1192,7 @@ the ~end()~ method automatically removes all listeners from the client object.
 
    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
+   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
@@ -1265,7 +1209,7 @@ the ~end()~ method automatically removes all listeners from the client object.
    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
+   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
@@ -1350,7 +1294,7 @@ 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.
 
-** 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
@@ -1495,7 +1439,7 @@ 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
+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.
@@ -1541,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. 
@@ -1554,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
@@ -1603,7 +1555,7 @@ the ~ssh2-sftp-client~ wrapper module.
 ** 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
+   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.
 
@@ -1727,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();
        }
      }
@@ -1743,7 +1695,7 @@ the ~ssh2-sftp-client~ wrapper module.
 
     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
+    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.
@@ -1833,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
@@ -1877,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.
 
@@ -1910,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.3",
+  "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"
   }
 }