Pass request options to Database.query() etc.

[Yogu]

I would like to have a way to pass some request-related options when calling high-level methods like Database.query(), Database.executeTransaction() etc. I'm mainly interested in beforeRequest and afterResponse, but I think all of CommonRequestOptions would make sense. In addition, the options could include a signal to be able to abort a request.

My use cases

• Our frontends cancel requests when they are no longer needed (e.g. when the user changes filter criteria). If this happens, I would like to abort the request to the ArangoDB server as well, or remove it from the task queue if it's not been started yet. This would be possible by throwing conditionally in beforeRequest, or with a new signal option that I could abort.
• I would like to track how long a request spent in the arangojs-internal request queue, and correlate this with contextual information. This is not possible with a beforeRequest callback per Database instance, but it would be possible with a beforeRequest option on the .query() call

Other potential use cases

• Different HTTP timeouts depending on the context (e.g. a longer timeout on queries you know will take a long time)
• Different values for retryOnConflict depending on the context, e.g. enable them for simple queries, but disable them if you want to retry on a higher level instead, or increase the number of retries for certain queries
• Set custom HTTP headers like a request ID that will be processed somewhere on the network stack, on a reverse proxy etc.

Suggested API

// New type. Not sure about the name - CommonRequestOptions would be fitting but is already taken for the global options
type ExtraRequestOptions = CommonRequestOptions & {
  signal: AbortSignal

  /**
   * Headers object containing any additional headers to send with the request.
   *
   * Note that the `Authorization` header will be overridden if the `auth`
   * configuration option is set.
   */
  headers?:
    | string[][]
    | Record<string, string | ReadonlyArray<string>>
    | Headers;
}

// Existing type
type QueryOptions = ExtraRequestOptions & {
  // ... existing properties
}

// Existing type
type TransactionOptions = ExtraRequestOptions & {  
  // ... existing properties
}

class Database {
  // Example for a method that currently does not have an options argument
  exists(options: ExtraRequestOptions) {
    // ...
  }
}

The new options could be merged into all option arguments that perform a request. Personally, I'm mostly interested in query, executeTransaction, beginTransaction, Transaction.commit(), Transaction.abort() and the cursor APIs (although we currently don't use cursors).

Alternatively, the request options could also be nested to separate them from the function-specific options

// Existing type
type QueryOptions = {
  // ... existing properties
  requestOptions: ExtraRequestOptions
}