chore(README): clean and reorganize (#29)

README.md

@@ -16,177 +16,257 @@ npm install -S @marsaud/smb2
 
 ## API
 
-### var smb2Client = new SMB2 ( options )
+### Asynchronicity
+
+All async methods can be used with Node-style callbacks or return promises if
+none is passed:
+
+```js
+// Node-style callback
+smb2Client.readFile('foo.txt', function(err, content) {
+  if (err) throw err;
+  console.log(content);
+});
+
+// With promise, ideal with ES2017 async functions
+const content = await smb2Client.readFile('foo.txt');
+console.log(content);
+```
+
+### Construction
+
+> `var smb2Client = new SMB2 ( options )`
+
 The SMB2 class is the constructor of your SMB2 client.
 
-the parameter ```options``` accepts this list of attributes:
+the parameter `options` accepts this list of attributes:
 
-- ```share``` (mandatory): the share you want to access
-- ```domain``` (mandatory): the domain of which the user is registred
-- ```username``` (mandatory): the username of the user that access the share
-- ```password``` (mandatory): the password
-- ```port``` (optional): default ```445```, the port of the SMB server
-- ```packetConcurrency``` (optional): default ```20```, the number of simulatanous packet when writting / reading data from the share
-- ```autoCloseTimeout``` (optional): default ```10000```, the timeout in milliseconds before to close the SMB2 session and the socket, if setted to ```0``` the connection will never be closed unless you do it 
+- `share`: the share you want to access
+- `domain`: the domain of which the user is registered
+- `username`: the username of the user that access the share
+- `password`: the password
+- `port` (optional): default `445`, the port of the SMB server
+- `packetConcurrency` (optional): default `20`, the number of simultaneous packet when writing / reading data from the share
+- `autoCloseTimeout` (optional): default `0`, the timeout in milliseconds before to close the SMB2 session and the socket, if set to `0` the connection will never be closed unless you do it
 
 Example:
+
 ```javascript
 // load the library
 var SMB2 = require('smb2');
 
 // create an SMB2 instance
 var smb2Client = new SMB2({
-  share:'\\\\000.000.000.000\\c$'
-, domain:'DOMAIN'
-, username:'username'
-, password:'password!'
+  share: '\\\\000.000.000.000\\c$',
+  domain: 'DOMAIN',
+  username: 'username',
+  password: 'password!',
 });
 ```
 
-### smb2Client.readdir ( path, callback )
-Asynchronous readdir(3). Reads the contents of a directory. The callback gets two arguments (err, files) where files is an array of the names of the files in the directory excluding '.' and '..'.
+### Connection management
+
+The connection to the SMB server will be automatically open when necessary.
+
+Unless you have set `autoCloseTimeout` to `0` during client construction, the connection will be closed automatically.
+
+If you have set `autoCloseTimeout` to `0`, the connection MUST be closed manually:
+
+```js
+smb2Client.disconnect();
+```
+
+### High level methods
+
+> `smb2Client.ensureDir ( path, callback )`
+
+Ensures that the directory exists. If the directory structure does not exist, it is created.
 
 Example:
+
 ```javascript
-smb2Client.readdir('Windows\\System32', function(err, files){
-    if(err) throw err;
-    console.log(files);
+smb2Client.ensureDir('path\\to\\directory', function(err) {
+  if (err) throw err;
+  console.log('directory structure has been created');
 });
 ```
 
-### smb2Client.readFile ( filename, [options], callback )
-- ```filename``` String
-- ```options``` Object
-    - ```encoding``` String | Null default = null
-- ```callback``` Function
+> `smb2Client.exists ( path, callback )`
+
+Test whether or not the given path exists by checking with the file system.
+
+Example:
 
-Asynchronously reads the entire contents of a file. Example:
 ```javascript
-smb2Client.readFile('path\\to\\my\\file.txt', function(err, data){
-    if(err) throw err;
-    console.log(data);
+smb2Client.exists('path\\to\\my\\file.txt', function(err, exists) {
+  if (err) throw err;
+  console.log(exists ? "it's there" : "it's not there!");
 });
 ```
-The callback is passed two arguments (err, data), where data is the contents of the file.
 
-If no encoding is specified, then the raw buffer is returned.
+> `smb2Client.mkdir ( path, [mode], callback )`
 
-### smb2Client.writeFile ( filename, data, [options], callback )
-- ```filename``` String
-- ```data``` String | Buffer
-- ```options``` Object
-    - ```encoding``` String | Null default = 'utf8'
-- ```callback``` Function
+Asynchronous `mkdir(2)`: create a directory.
 
-Asynchronously writes data to a file, replacing the file if it already exists. data can be a string or a buffer.
-
-The encoding option is ignored if data is a buffer. It defaults to 'utf8'.
+`mode` defaults to `0o777`.
 
 Example:
+
 ```javascript
-smb2Client.writeFile('path\\to\\my\\file.txt', 'Hello Node', function (err) {
-    if (err) throw err;
-    console.log('It\'s saved!');
+smb2Client.mkdir('path\\to\\the\\directory', function(err) {
+  if (err) throw err;
+  console.log('Directory created!');
 });
 ```
 
-### smb2Client.mkdir ( path, [mode], callback )
-Asynchronous mkdir(2). No arguments other than a possible exception are given to the completion callback. mode defaults to 0777.
+> `smb2Client.readdir ( path, callback )`
+
+Asynchronous `readdir(3)`: reads the contents of a directory.
+
+The result is an array of the names of the files in the directory excluding `'.'` and `'..'`.
 
 Example:
+
 ```javascript
-smb2Client.mkdir('path\\to\\the\\folder', function (err) {
-    if (err) throw err;
-    console.log('Folder created!');
+smb2Client.readdir('Windows\\System32', function(err, files) {
+  if (err) throw err;
+  console.log(files);
 });
 ```
 
-### smb2Client.rmdir ( path, callback )
-Asynchronous rmdir(2). No arguments other than a possible exception are given to the completion callback.
+> `smb2Client.readFile ( path, [options], callback )`
+
+- `path` String
+- `options` Object
+  - `encoding` String | Null default = null
+- `callback` Function
+
+Asynchronously reads the entire content of a file.
 
 Example:
+
 ```javascript
-smb2Client.rmdir('path\\to\\the\\folder', function (err) {
-    if (err) throw err;
-    console.log('Folder deleted!');
+smb2Client.readFile('path\\to\\my\\file.txt', function(err, content) {
+  if (err) throw err;
+  console.log(content);
 });
 ```
 
-### smb2Client.exists ( path, callback )
-Test whether or not the given path exists by checking with the file system. Then call the callback argument with either true or false. Example:
+If no encoding is specified, then the raw buffer is returned.
+
+> `smb2Client.rename ( oldPath, newPath, callback )`
+
+Asynchronous `rename(2)`: rename a file.
+
 ```javascript
-smb2Client.exists('path\\to\\my\\file.txt', function (err, exists) {
+smb2Client.rename(
+  'path\\to\\my\\file.txt',
+  'new\\path\\to\\my\\new-file-name.txt',
+  function(err) {
     if (err) throw err;
-    console.log(exists ? "it's there" : "it's not there!");
-});
+    console.log('file has been renamed');
+  }
+);
 ```
 
-### smb2Client.unlink ( path, callback )
-Asynchronous unlink(2). No arguments other than a possible exception are given to the completion callback.
+> `smb2Client.rmdir ( path, callback )`
+
+Asynchronous `rmdir(2)`: delete an empty directory.
+
+Example:
+
 ```javascript
-smb2Client.unlink('path\\to\\my\\file.txt', function (err) {
-    if (err) throw err;
-    console.log("file has been deleted");
+smb2Client.rmdir('path\\to\\the\\directory', function(err) {
+  if (err) throw err;
+  console.log('Directory deleted!');
 });
 ```
 
-### smb2Client.rename ( oldPath, newPath, callback )
-Asynchronous rename(2). No arguments other than a possible exception are given to the completion callback.
+> `smb2Client.unlink ( path, callback )`
+
+Asynchronous `unlink(2)`: delete a file.
+
 ```javascript
-smb2Client.rename('path\\to\\my\\file.txt', 'new\\path\\to\\my\\new-file-name.txt', function (err) {
-    if (err) throw err;
-    console.log("file has been renamed");
+smb2Client.unlink('path\\to\\my\\file.txt', function(err) {
+  if (err) throw err;
+  console.log('file has been deleted');
 });
 ```
 
-### smb2Client.disconnect ( )
-This function will close the open connection if opened, it will be called automatically after ```autoCloseTimeout``` ms of no SMB2 call on the server.
+> `smb2Client.writeFile ( filename, data, [options], callback )`
 
-### smb2Client.createReadStream ( fileName, [options], callback )
-Returns a read stream on the file. Unlike fs.createReadStream, this function is asynchronous, as we need use asynchronous smb requests to get the stream.
+- `filename` String
+- `data` String | Buffer
+- `options` Object
+  - `encoding` String | Null default = `'utf8'`
+- `callback` Function
+
+Asynchronously writes data to a file, replacing the file if it already exists. data can be a string or a buffer.
+
+The encoding option is ignored if data is a buffer.
 
 Example:
+
 ```javascript
-smb2Client.createReadStream('path\\to\\the\\file', function (err, readStream) {
-    if (err) throw err;
-    var writeStream = fs.createWriteStream('localFile')
-    readStream.pipe(writeStream)
+smb2Client.writeFile('path\\to\\my\\file.txt', 'Hello Node', function(err) {
+  if (err) throw err;
+  console.log("It's saved!");
 });
 ```
 
-### smb2Client.createWriteStream ( fileName, [options], callback )
-Returns a write stream on the file. Unlike fs.createWriteStream, this function is asynchronous, as we need use asynchronous smb requests to get the stream.
+### Streams
+
+> `smb2Client.createReadStream ( fileName, [options], callback )`
+
+Returns a read stream on the file.
+
+> Unlike `fs.createReadStream`, this function is asynchronous, as we need use asynchronous smb requests to get the stream.
 
 Example:
+
 ```javascript
-smb2Client.createWriteStream('path\\to\\the\\file', function (err, readStream) {
-    if (err) throw err;
-    var readStream = fs.createReadStream('localFile')
-    readStream.pipe(writeStream)
+smb2Client.createReadStream('path\\to\\the\\file', function(err, readStream) {
+  if (err) throw err;
+  var writeStream = fs.createWriteStream('localFile');
+  readStream.pipe(writeStream);
 });
 ```
-### smb2Client.ensureDir ( path, callback )
-Ensures that the directory exists. If the directory structure does not exist, it is created.
 
-### Low-level API
+> `smb2Client.createWriteStream ( fileName, [options], callback )`
+
+Returns a write stream on the file.
+
+> Unlike `fs.createWriteStream`, this function is asynchronous, as we need use asynchronous smb requests to get the stream.
+
+Example:
 
 ```javascript
-smb2Client.open('path\\to\\the\\file', function (err, fd) {
-    if (err) throw err;
+smb2Client.createWriteStream('path\\to\\the\\file', function(err, readStream) {
+  if (err) throw err;
+  var readStream = fs.createReadStream('localFile');
+  readStream.pipe(writeStream);
+});
+```
 
-    smb2Client.read(
-        Buffer.alloc(10), // buffer where to store the data
-        0,                // offset in the buffer
-        10,               // number of bytes to read
-        0,                // offset in the file
-        function (err, bytesRead, buffer) {
-            smb2Client.close(fd, function () {})
+### Low-level API
 
-            if (err) throw cb(err)
-            console.log(bytesRead, buffer)
-        }
-    )
-})
+```javascript
+smb2Client.open('path\\to\\the\\file', function(err, fd) {
+  if (err) throw err;
+
+  smb2Client.read(
+    Buffer.alloc(10), // buffer where to store the data
+    0, // offset in the buffer
+    10, // number of bytes to read
+    0, // offset in the file
+    function(err, bytesRead, buffer) {
+      smb2Client.close(fd, function() {});
+
+      if (err) throw cb(err);
+      console.log(bytesRead, buffer);
+    }
+  );
+});
 ```
 
 > This API is modeled after Node's `fs` module.
@@ -194,6 +274,7 @@ smb2Client.open('path\\to\\the\\file', function (err, fd) {
 > Note: be careful of `autoCloseTimeout` with this process as it is not intended to cover multiple method calls, you should set it to `0` and manually `disconnect()`.
 
 ## Contributors
+
 - [Benjamin Chelli](https://github.com/bchelli)
 - [Fabrice Marsaud](https://github.com/marsaud)