Refactor: Documentation Update 1.0.10

.babelrc

@@ -1,9 +1,13 @@
 {
 	"presets": [
-		"env"
+    ["@babel/preset-env", {
+      "targets": {
+        "node": "8.3.0"
+      }
+    }]
 	],
 	"plugins": [
-		"transform-regenerator",
-		"transform-object-rest-spread"
+		"@babel/plugin-transform-regenerator",
+		"@babel/plugin-proposal-object-rest-spread"
 	]
 }

.eslintrc.json

@@ -1,26 +1,44 @@
 {
-  "parser": "babel-eslint",
-  "extends": [
-    "standard"
+  "root": true,
+
+  "plugins": [
+    "jsdoc",
+    "mocha"
   ],
-  "rules": {
-    "jsx-quotes": ["error", "prefer-single"],
-    "semi": [1, "never"],
-    "max-len": 0,
-    "import/no-named-as-default": 0,
-    "import/no-named-as-default-member": 0
+
+  "env": {
+    "es6": true,
+    "node": true,
+    "es2020": true
   },
-  "settings": {
-    "import/resolver": {
-      "node": {
-        "moduleDirectory": [
-          "node_modules",
-          "lib"
-        ]
-      }
-    }
+
+  "extends": [
+    "standard",
+    "eslint:recommended",
+    "plugin:promise/recommended",
+    "plugin:node/recommended",
+    "plugin:import/errors",
+    "plugin:import/warnings",
+    "plugin:lodash/recommended",
+    "plugin:mocha/recommended",
+    "plugin:jsdoc/recommended"
+  ],
+
+  "parserOptions": {
+    "ecmaVersion": 2020
   },
-  "env": {
-    "jest": true
+
+  "rules": {
+    "jsdoc/check-tag-names": 0,
+    "jsdoc/no-undefined-types": 0,
+    "no-multiple-empty-lines": ["error", { "max": 1, "maxEOF": 1 }],
+    "promise/no-callback-in-promise": 0,
+    "lodash/prefer-lodash-method": 0,
+    "lodash/prefer-noop": 0,
+    "lodash/prefer-constant": 0,
+    "node/no-unpublished-require": 0,
+    "mocha/no-mocha-arrows": 0,
+    "mocha/no-setup-in-describe": 0,
+    "mocha/no-skipped-tests": 0
   }
 }

.gitignore

@@ -9,3 +9,6 @@ todo
 package-lock.json
 .env
 dist/
+tags
+.nyc_output
+coverage

CHANGELOG

@@ -1,3 +1,8 @@
+# 1.0.10
+- meta: bump deps
+- meta: normalize eslint config
+- refactor: improve doclets
+
 # 1.0.9
 - meta: bump bignumber.js dep to 9.0.0
 

README.md

@@ -27,7 +27,8 @@ const n = nonce()
 
 ### Docs
 
-[Refer to `docs/func_docs.md`](/docs/func_docs.md) for JSDoc-generated API documentation
+API documentation can be found in [`docs/reference.md`](docs/reference.md), and
+examples in the [`examples`](examples) folder.
 
 ### Example: Padding Candles
 

docs/func_docs.md → docs/reference.md

@@ -1,28 +1,39 @@
+## Modules
+
+<dl>
+<dt><a href="#module_bfx-api-node-util">bfx-api-node-util</a></dt>
+<dd><p>This module contains minor utilities shared by the Bitfinex Node.JS API
+libraries.</p>
+</dd>
+</dl>
+
 ## Functions
 
 <dl>
-<dt><a href="#genAuthSig">genAuthSig(apiSecret, payload)</a> ⇒ <code>Object</code></dt>
+<dt><a href="#genAuthSig">genAuthSig(secret, [payload])</a> ⇒ <code><a href="#AuthSignature">AuthSignature</a></code></dt>
 <dd><p>Generates an auth signature, payload, and nonce for passing to the WS &amp; REST
 APIs</p>
 </dd>
 <dt><a href="#isClass">isClass(f)</a> ⇒ <code>boolean</code></dt>
-<dd></dd>
+<dd><p>Query if the provided argument is a class</p>
+</dd>
 <dt><a href="#isSnapshot">isSnapshot(msg)</a> ⇒ <code>boolean</code></dt>
-<dd></dd>
+<dd><p>Query if the provided message is a websocket snapshot packet</p>
+</dd>
 <dt><a href="#nonce">nonce()</a> ⇒ <code>number</code></dt>
 <dd><p>Generates a new nonce for usage with the Bitfinex APIs</p>
 </dd>
 <dt><a href="#padCandles">padCandles(candles, candleWidth)</a> ⇒ <code>Array.&lt;Array&gt;</code></dt>
 <dd><p>Fills in missing (0 volume) candles on the provided dataset. The result is a
 new array (does not mutate)</p>
 </dd>
-<dt><a href="#setSigFig">setSigFig(n, maxSigs)</a> ⇒ <code>string</code></dt>
+<dt><a href="#setSigFig">setSigFig(number, [maxSigs])</a> ⇒ <code>string</code></dt>
 <dd><p>Smartly set the precision (decimal) on a value based off of the significant
 digit maximum. For example, calling with 3.34 when the max sig figs allowed
 is 5 would return &#39;3.3400&#39;, the representation number of decimals IF they
 weren&#39;t zeros.</p>
 </dd>
-<dt><a href="#setPrecision">setPrecision(number, decimals)</a> ⇒ <code>string</code></dt>
+<dt><a href="#setPrecision">setPrecision(number, [decimals])</a> ⇒ <code>string</code></dt>
 <dd><p>Casts the provided value to a number if required, and limits the number of
 decimals to the specified value. Returns a decimal string.</p>
 </dd>
@@ -34,39 +45,58 @@ decimals to the specified value. Returns a decimal string.</p>
 </dd>
 </dl>
 
+## Typedefs
+
+<dl>
+<dt><a href="#AuthSignature">AuthSignature</a> : <code>object</code></dt>
+<dd><p>Authorization signature for WS &amp; REST APIs.</p>
+</dd>
+</dl>
+
+<a name="module_bfx-api-node-util"></a>
+
+## bfx-api-node-util
+This module contains minor utilities shared by the Bitfinex Node.JS API
+libraries.
+
+**License**: MIT  
 <a name="genAuthSig"></a>
 
-## genAuthSig(apiSecret, payload) ⇒ <code>Object</code>
+## genAuthSig(secret, [payload]) ⇒ [<code>AuthSignature</code>](#AuthSignature)
 Generates an auth signature, payload, and nonce for passing to the WS & REST
 APIs
 
 **Kind**: global function  
-**Returns**: <code>Object</code> - authSignature  
+**Returns**: [<code>AuthSignature</code>](#AuthSignature) - authSignature  
 
-| Param | Type | Description |
-| --- | --- | --- |
-| apiSecret | <code>string</code> |  |
-| payload | <code>string</code> | optional signature payload, generated by default |
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| secret | <code>string</code> |  | API secret |
+| [payload] | <code>string</code> | <code>&quot;&#x27;&#x27;&quot;</code> | signature payload, generated by default |
 
 <a name="isClass"></a>
 
 ## isClass(f) ⇒ <code>boolean</code>
+Query if the provided argument is a class
+
 **Kind**: global function  
 **Returns**: <code>boolean</code> - isClass  
 
-| Param | Type |
-| --- | --- |
-| f | <code>Class</code> | 
+| Param | Type | Description |
+| --- | --- | --- |
+| f | <code>function</code> | function to check |
 
 <a name="isSnapshot"></a>
 
 ## isSnapshot(msg) ⇒ <code>boolean</code>
+Query if the provided message is a websocket snapshot packet
+
 **Kind**: global function  
 **Returns**: <code>boolean</code> - isSnapshot  
 
-| Param | Type |
-| --- | --- |
-| msg | <code>Array</code> \| <code>Array.&lt;Array&gt;</code> | 
+| Param | Type | Description |
+| --- | --- | --- |
+| msg | <code>Array</code> \| <code>Array.&lt;Array&gt;</code> | message |
 
 <a name="nonce"></a>
 
@@ -91,7 +121,7 @@ new array (does not mutate)
 
 <a name="setSigFig"></a>
 
-## setSigFig(n, maxSigs) ⇒ <code>string</code>
+## setSigFig(number, [maxSigs]) ⇒ <code>string</code>
 Smartly set the precision (decimal) on a value based off of the significant
 digit maximum. For example, calling with 3.34 when the max sig figs allowed
 is 5 would return '3.3400', the representation number of decimals IF they
@@ -100,24 +130,24 @@ weren't zeros.
 **Kind**: global function  
 **Returns**: <code>string</code> - str  
 
-| Param | Type | Description |
-| --- | --- | --- |
-| n | <code>number</code> |  |
-| maxSigs | <code>number</code> | default 5 |
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| number | <code>number</code> | <code>0</code> | number |
+| [maxSigs] | <code>number</code> | <code>5</code> | max significant figures |
 
 <a name="setPrecision"></a>
 
-## setPrecision(number, decimals) ⇒ <code>string</code>
+## setPrecision(number, [decimals]) ⇒ <code>string</code>
 Casts the provided value to a number if required, and limits the number of
 decimals to the specified value. Returns a decimal string.
 
 **Kind**: global function  
 **Returns**: <code>string</code> - result  
 
-| Param | Type | Default |
-| --- | --- | --- |
-| number | <code>number</code> \| <code>string</code> | <code>0</code> | 
-| decimals | <code>number</code> | <code>0</code> | 
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| number | <code>number</code> \| <code>string</code> | <code>0</code> | number |
+| [decimals] | <code>number</code> | <code>0</code> | decimal precision |
 
 <a name="prepareAmount"></a>
 
@@ -127,9 +157,9 @@ Prepares a amount for submitting via the API
 **Kind**: global function  
 **Returns**: <code>string</code> - preparedAmount  
 
-| Param | Type | Default |
-| --- | --- | --- |
-| amount | <code>number</code> \| <code>string</code> | <code>0</code> | 
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| amount | <code>number</code> \| <code>string</code> | <code>0</code> | amount |
 
 <a name="preparePrice"></a>
 
@@ -139,7 +169,21 @@ Prepares a price for submitting via the API
 **Kind**: global function  
 **Returns**: <code>string</code> - preparedPrice  
 
-| Param | Type | Default |
+| Param | Type | Default | Description |
+| --- | --- | --- | --- |
+| price | <code>number</code> \| <code>string</code> | <code>0</code> | price |
+
+<a name="AuthSignature"></a>
+
+## AuthSignature : <code>object</code>
+Authorization signature for WS & REST APIs.
+
+**Kind**: global typedef  
+**Properties**
+
+| Name | Type | Description |
 | --- | --- | --- |
-| price | <code>number</code> \| <code>string</code> | <code>0</code> | 
+| payload | <code>string</code> | request payload, default   'AUTH${nonce}${nonce}'' |
+| sig | <code>string</code> | signature in hexadecimal |
+| nonce | <code>number</code> | used nonce |
 

index.js

@@ -7,6 +7,14 @@ const isSnapshot = require('./lib/is_snapshot')
 const isClass = require('./lib/is_class')
 const padCandles = require('./lib/pad_candles')
 
+/**
+ * This module contains minor utilities shared by the Bitfinex Node.JS API
+ * libraries.
+ *
+ * @license MIT
+ * @module bfx-api-node-util
+ */
+
 module.exports = {
   ...precision,
   nonce,

lib/gen_auth_sig.js

@@ -3,12 +3,23 @@
 const crypto = require('crypto')
 const getNonce = require('./nonce')
 
+/**
+ * Authorization signature for WS & REST APIs.
+ *
+ * @typedef {object} AuthSignature
+ * @property {string} payload - request payload, default
+ *   'AUTH${nonce}${nonce}''
+ * @property {string} sig - signature in hexadecimal
+ * @property {number} nonce - used nonce
+ */
+
 /**
  * Generates an auth signature, payload, and nonce for passing to the WS & REST
  * APIs
- * @param {string} apiSecret
- * @param {string?} payload - optional signature payload, generated by default
- * @return {Object} authSignature
+ *
+ * @param {string} secret - API secret
+ * @param {string} [payload=''] - signature payload, generated by default
+ * @returns {AuthSignature} authSignature
  */
 const genAuthSig = (secret, payload = '') => {
   const nonce = getNonce()

lib/is_class.js

@@ -1,14 +1,16 @@
 'use strict'
 
+const _isFunction = require('lodash/isFunction')
+
 /**
- * @param {Class} f
- * @return {boolean} isClass
+ * Query if the provided argument is a class
+ *
+ * @param {Function} f - function to check
+ * @returns {boolean} isClass
  */
-const isClass = (f) => {
-  return (
-    (typeof f === 'function') &&
-    (/^class\s/.test(Function.prototype.toString.call(f)))
-  )
-}
+const isClass = f => (
+  _isFunction(f) &&
+  (/^class\s/.test(Function.prototype.toString.call(f)))
+)
 
 module.exports = isClass

lib/is_snapshot.js

@@ -1,9 +1,13 @@
 'use strict'
 
+const _isArray = require('lodash/isArray')
+
 /**
- * @param {Array|Array[]} msg
- * @return {boolean} isSnapshot
+ * Query if the provided message is a websocket snapshot packet
+ *
+ * @param {Array|Array[]} msg - message
+ * @returns {boolean} isSnapshot
  */
-const isSnapshot = msg => msg[0] && Array.isArray(msg[0])
+const isSnapshot = msg => msg[0] && _isArray(msg[0])
 
 module.exports = isSnapshot