add debug option (#339)

* add debug option to config and parse

* cleanup switch from warn to debug

* console.debug is node v8 and above

* replace quasi-jsdoc with flow

* standard should ignore flow-typed files

.flowconfig

@@ -0,0 +1,23 @@
+[ignore]
+
+[include]
+
+[libs]
+
+[lints]
+all=warn
+
+[options]
+emoji=true
+include_warnings=true
+
+[strict]
+nonstrict-import
+sketchy-null
+unclear-type
+unsafe-getters-setters
+untyped-import
+untyped-type-import
+
+[version]
+^0.82.0

.gitignore

@@ -1,13 +1,7 @@
-# Coverage directory used by tools like istanbul
-coverage
+# Coverage directory
 .nyc_output
 
 # Dependency directory
-# Commenting this out is preferred by some people, see
-# https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git-
 node_modules
 
-# Users Environment Variables
-.lock-wscript
-
 .DS_Store

README.md

@@ -91,7 +91,7 @@ You can additionally, pass options to `config`.
 
 Default: `path.resolve(process.cwd(), '.env')`
 
-You can specify a custom path if your file containing environment variables is
+You may specify a custom path if your file containing environment variables is
 named or located differently.
 
 ```js
@@ -109,6 +109,16 @@ using this option.
 require('dotenv').config({ encoding: 'base64' })
 ```
 
+#### Debug
+
+Default: `false`
+
+You may turn on logging to help debug why certain keys or values are not being set as you expect.
+
+```js
+require('dotenv').config({ debug: process.env.DEBUG })
+```
+
 ## Parse
 
 The engine which parses the contents of your file containing environment
@@ -122,6 +132,22 @@ const config = dotenv.parse(buf) // will return an object
 console.log(typeof config, config) // object { BASIC : 'basic' }
 ```
 
+### Options
+
+#### Debug
+
+Default: `false`
+
+You may turn on logging to help debug why certain keys or values are not being set as you expect.
+
+```js
+const dotenv = require('dotenv')
+const buf = Buffer.from('hello world')
+const opt = { debug: true }
+const config = dotenv.parse(buf, opt)
+// expect a debug message because the buffer is not in KEY=VAL form
+```
+
 ### Rules
 
 The parsing engine currently supports the following rules:

config.js

@@ -1,3 +1,5 @@
+/* @flow */
+
 (function () {
   require('./lib/main').config(
     require('./lib/cli-options')(process.argv)