Add new request interface, implement first few request typings (#843)

* Add request interface & typings

- src/api: add basic implementation of request/requestAll()
- src/ledgers/account_info: refactor to simplify with request()
- src/ledgers/balances: refactor to simplify with request()
- src/ledgers/orderbook: refactor to simplify with requestAll()
- src/ledgers/orders: refactor to simplify with requestAll()
- src/ledgers/trustlines: refactor to simplify with requestAll()

* standardize on Formatted prefix

src/api.ts

@@ -39,10 +39,19 @@ import signPaymentChannelClaim from './offline/sign-payment-channel-claim'
 import verifyPaymentChannelClaim from './offline/verify-payment-channel-claim'
 import getLedger from './ledger/ledger'
 
+import {
+  AccountOffersRequest, AccountOffersResponse,
+  AccountInfoRequest, AccountInfoResponse,
+  AccountLinesRequest, AccountLinesResponse,
+  BookOffersRequest, BookOffersResponse,
+  GatewayBalancesRequest, GatewayBalancesResponse
+} from './common/types/commands'
+
 
 import RangeSet from './common/rangeset'
 import * as ledgerUtils from './ledger/utils'
 import * as schemaValidator from './common/schema-validator'
+import {clamp} from './ledger/utils'
 
 type APIOptions = {
   server?: string,
@@ -52,6 +61,23 @@ type APIOptions = {
   timeout?: number
 }
 
+/**
+ * Get the response key / property name that contains the listed data for a
+ * command. This varies from command to command, but we need to know it to
+ * properly count across many requests.
+ */
+function getCollectKeyFromCommand(command: string): string|undefined {
+  switch (command) {
+    case 'account_offers':
+    case 'book_offers':
+      return 'offers'
+    case 'account_lines':
+      return 'lines'
+    default:
+      return undefined
+  }
+}
+
 // prevent access to non-validated ledger versions
 class RestrictedConnection extends Connection {
   request(request: any, timeout?: number) {
@@ -106,6 +132,92 @@ class RippleAPI extends EventEmitter {
     }
   }
 
+  /**
+   * Makes a simple request to the API with the given command and any
+   * additional request body parameters.
+   *
+   * NOTE: This command is under development and should not yet be relied
+   * on by external consumers.
+   */
+  async _request(command: 'account_info', params: AccountInfoRequest):
+    Promise<AccountInfoResponse>
+  async _request(command: 'account_lines', params: AccountLinesRequest):
+    Promise<AccountLinesResponse>
+  async _request(command: 'account_offers', params: AccountOffersRequest):
+  Promise<AccountOffersResponse>
+  async _request(command: 'book_offers', params: BookOffersRequest):
+    Promise<BookOffersResponse>
+  async _request(command: 'gateway_balances', params: GatewayBalancesRequest):
+    Promise<GatewayBalancesResponse>
+  async _request(command: string, params: any = {}) {
+    return this.connection.request({
+      ...params,
+      command
+    })
+  }
+
+  /**
+   * Makes multiple paged requests to the API to return a given number of
+   * resources. __requestAll() will make multiple requests until the `limit`
+   * number of resources is reached (if no `limit` is provided, a single request
+   * will be made).
+   *
+   * If the command is unknown, an additional `collect` property is required to
+   * know which response key contains the array of resources.
+   *
+   * NOTE: This command is under development and should not yet be relied
+   * on by external consumers.
+   */
+  async _requestAll(command: 'account_offers', params: AccountOffersRequest):
+    Promise<AccountOffersResponse[]>
+  async _requestAll(command: 'book_offers', params: BookOffersRequest):
+    Promise<BookOffersResponse[]>
+  async _requestAll(command: 'account_lines', params: AccountLinesRequest):
+    Promise<AccountLinesResponse[]>
+  async _requestAll(
+    command: string,
+    params: any = {},
+    options: {collect?: string} = {}): Promise<any[]> {
+    // The data under collection is keyed based on the command. Fail if command
+    // not recognized and collection key not provided.
+    const collectKey = options.collect || getCollectKeyFromCommand(command)
+    if (!collectKey) {
+      throw new errors.ValidationError(`no collect key for command ${command}`)
+    }
+    // If limit is not provided, fetches all data over multiple requests.
+    // NOTE: This may return much more than needed. Set limit when possible.
+    const countTo: number =
+        (params.limit !== undefined) ? params.limit : Infinity
+    let count: number = 0
+    let marker: string = params.marker
+    let lastBatchLength: number
+    const results = []
+    do {
+      const countRemaining = clamp(countTo - count, 10, 400)
+      const repeatProps = {
+        ...params,
+        limit: countRemaining,
+        marker
+      }
+      // NOTE: We have to generalize the `this._request()` function signature
+      // here until we add support for unknown commands (since command is some
+      // unknown string).
+      const singleResult = await (<Function>this._request)(command, repeatProps)
+      const collectedData = singleResult[collectKey]
+      marker = singleResult.marker
+      results.push(singleResult)
+      // Make sure we handle when no data (not even an empty array) is returned.
+      const isExpectedFormat = Array.isArray(collectedData)
+      if (isExpectedFormat) {
+        count += collectedData.length
+        lastBatchLength = collectedData.length
+      } else {
+        lastBatchLength = 0
+      }
+    } while(!!marker && count < countTo && lastBatchLength !== 0)
+    return results
+  }
+
   connect = connect
   disconnect = disconnect
   isConnected = isConnected