feat(tokens): [Method] getHolders - Add docs + tests.

Author: taylorjdawson

dist/web3data.min.js

@@ -1633,7 +1633,7 @@ const velocity = await web3data.token.getVelocity('0x06012c8cf97bead5deae237070f
 #### getHolders(hash[, filterOptions])
 
 
-
+Retrieves the latest or historical token holders for the specified address.
 
 
 
@@ -1643,7 +1643,8 @@ const velocity = await web3data.token.getVelocity('0x06012c8cf97bead5deae237070f
 | Name | Type | Description |  |
 | ---- | ---- | ----------- | -------- |
 | hash | `string`  |  The address for which to retrieve token holders. |   |
-| filterOptions | `object`  |  The filters associated with the request. | *Optional* |
+| filterOptions | `object`  |  The filters associated with the request. See [docs](https://docs.amberdata.io/reference#gettokenvelocity) for more details. | *Optional* |
+| filterOptions.holderAddresses | `object`  |  The address for which to retrieve token holders. | *Optional* |
 
 
 
@@ -1652,13 +1653,18 @@ const velocity = await web3data.token.getVelocity('0x06012c8cf97bead5deae237070f
 
 ```javascript
 
+// Latest
+const latestHodlers =  await web3data.token.getHolders('0x06012c8cf97bead5deae237070f9587f8e7a266d');
+
+// Historical
+const historicalHodlers =  await web3data.token.getHolders('0x06012c8cf97bead5deae237070f9587f8e7a266d', {holderAddresses: '0xbbf0cc1c63f509d48a4674e270d26d80ccaf6022'});
 ```
 
 
 ##### Returns
 
 
-- `Promise.<object>`  
+- `Promise.<object>`  The latest or historical token holders for the specified address.
 
 
 
@@ -1667,7 +1673,7 @@ const velocity = await web3data.token.getVelocity('0x06012c8cf97bead5deae237070f
 #### getHoldersHistorical(hash[, filterOptions])
 
 
-
+Retrieves the historical (time series) token holders for the specified token address. If the `holderAddresses` filter is present it will return historical data.
 
 
 
@@ -1685,14 +1691,14 @@ const velocity = await web3data.token.getVelocity('0x06012c8cf97bead5deae237070f
 ##### Examples
 
 ```javascript
-
+const historicalHolders = getHoldersHistorical('0x06012c8cf97bead5deae237070f9587f8e7a266d', {holderAddresses: '0xbbf0cc1c63f509d48a4674e270d26d80ccaf6022'})
 ```
 
 
 ##### Returns
 
 
-- `Promise.<object>`  
+- `Promise.<object>`  The historical (time series) token holders for the specified token address.
 
 
 

docs/api.md

@@ -81,37 +81,51 @@ class Token {
   }
 
   /**
+   * Retrieves the latest or historical token holders for the specified address.
+   *
    * @param {string} hash - The address for which to retrieve token holders.
-   * @param {object} [filterOptions] - The filters associated with the request.
-   * @returns {Promise<object>}
+   * @param {object} [filterOptions] - The filters associated with the request. See [docs](https://docs.amberdata.io/reference#get-token-velocity) for more details.
+   * @param {object} [filterOptions.holderAddresses] - The address for which to retrieve token holders.
+   * @returns {Promise<object>} The latest or historical token holders for the specified address.
    * @example
+   *
+   * // Latest
+   * const latestHodlers =  await web3data.token.getHolders('0x06012c8cf97bead5deae237070f9587f8e7a266d');
+   *
+   * // Historical
+   * const historicalHodlers =  await web3data.token.getHolders('0x06012c8cf97bead5deae237070f9587f8e7a266d', {holderAddresses: '0xbbf0cc1c63f509d48a4674e270d26d80ccaf6022'});
    */
   getHolders(hash, filterOptions = {}) {
     throwIf(is.notHash(hash), NO_ADDRESS)
+    let subendpoint = 'holders/latest'
+    let formatter = {formatter: recordsFormatter}
+
+    // If this parameter is present then we want historical data
+    if (filterOptions.holderAddresses) {
+      subendpoint = 'holders/historical'
+      formatter = {}
+    }
+
     return get(this.web3data, {
       hash,
       endpoint: ENDPOINT,
-      subendpoint: 'holders/latest',
+      subendpoint,
       filterOptions
-    }).then(onFulfilled, onError)
+    }).then(onFulfilled.bind(formatter), onError)
   }
 
   /**
+   * Retrieves the historical (time series) token holders for the specified token address. If the `holderAddresses` filter is present it will return historical data.
+   *
    * @param {string} hash - The address for which to retrieve token holders.
    * @param {object} [filterOptions] - The filters associated with the request.
-   * @returns {Promise<object>}
+   * @returns {Promise<object>} The historical (time series) token holders for the specified token address.
    * @example
+   * const historicalHolders = getHoldersHistorical('0x06012c8cf97bead5deae237070f9587f8e7a266d', {holderAddresses: '0xbbf0cc1c63f509d48a4674e270d26d80ccaf6022'})
    */
-  getHoldersHistorical(hash, filterOptions = {}) {
-    throwIf(is.notHash(hash), NO_ADDRESS)
+  getHoldersHistorical(hash, filterOptions) {
     throwIf(is.notInObject(filterOptions, 'holderAddresses'), NO_HOLDER_ADDRESS)
-
-    return get(this.web3data, {
-      hash,
-      endpoint: ENDPOINT,
-      subendpoint: 'holders/historical',
-      filterOptions
-    }).then(onFulfilled, onError)
+    return this.getHolders(hash, filterOptions)
   }
 
   /**

src/token.js

@@ -71,27 +71,6 @@ returnsObjectWithField.title = (providedTitle = '', input) => `Successfully call
  * -------- Test Tokens -------- *
  **********************************/
 
-test([rejectsPromise], {method: 'getHolders' }, NO_ADDRESS)
-
-test('Successfully gets address Token Holders Historical', async t => {
-    const filters = {holderAddresses: '0xbbf0cc1c63f509d48a4674e270d26d80ccaf6022'}
-    const holdersHistorical = await t.context.web3data.token.getHoldersHistorical(TOKEN_ADDRESS, filters);
-    t.true({}.hasOwnProperty.call(holdersHistorical.data[0], 'timestamp'))
-});
-
-test('Rejects promise if no token address supplied', async t => {
-    let filters = {holderAddresses: ADDRESS}
-    await t.throwsAsync(async () => {
-        await t.context.web3data.token.getHoldersHistorical('',filters);
-    }, { instanceOf: Error, message: NO_ADDRESS })
-});
-
-test('Rejects promise if no holder address supplied', async t => {
-    await t.throwsAsync(async () => {
-        await t.context.web3data.token.getHoldersHistorical(TOKEN_ADDRESS);
-    }, { instanceOf: Error, message: NO_HOLDER_ADDRESS })
-});
-
 /*********** Test getRankings() ***********/
 test('Successfully calls getRankings()', async t => {
     const {data: [rank1]} = await t.context.web3data.token.getRankings();
@@ -137,6 +116,35 @@ test('Successfully calls getVelocity() - with filters', async t => {
     t.true(isISOFormat(volume.metadata.startDate))
 })
 
+/*********** Test getHolders() ***********/
+test([rejectsPromise], {method: 'getHolders' }, NO_ADDRESS)
+
+test('Successfully calls getHolders() - latest', async t => {
+    const [holder] = await t.context.web3data.token.getHolders(TOKEN_ADDRESS);
+    t.true(holder.hasProp('holderAddress'))
+})
+
+test('Successfully calls getHolders() - latest with filters', async t => {
+    const [holder] = await t.context.web3data.token.getHolders(TOKEN_ADDRESS, {includePrice: true});
+    t.true(holder.hasProp('price'))
+})
+
+
+test('Successfully calls getHolders() - historical', async t => {
+    const holders = await t.context.web3data.token.getHolders(TOKEN_ADDRESS, {holderAddresses: '0xbbf0cc1c63f509d48a4674e270d26d80ccaf6022'});
+    t.true(holders.hasProp('metadata'))
+    t.true(holders.metadata.hasProp('columns'))
+    t.is(holders.metadata.columns[0], 'holder*')
+})
+test('Successfully calls getHolders() - historical with filters', async t => {
+    const holders = await t.context.web3data.token.getHolders(TOKEN_ADDRESS, {holderAddresses: '0xbbf0cc1c63f509d48a4674e270d26d80ccaf6022', includePrice: true, timeFormat: 'iso'});
+    t.true(holders.hasProp('metadata'))
+    t.true(holders.metadata.hasProp('columns'))
+    t.is(holders.metadata.columns[0], 'holder*')
+    t.true(isISOFormat(holders.data[0].timestamp))
+})
+
+
 /*********** Test getSupplies() ***********/
 test([rejectsPromise], {method: 'getSupplies'}, NO_ADDRESS)
 test('Successfully calls getSupplies() - latest', async t => {