Interface Fetcher

Overview

A simple adapter interface that allows you to define a custom HTTP request strategy that astra-db-ts may use to make requests.

See FetchH2 and FetchNative on the astra-db-ts GitHub repo for example implementations.

Disclaimer

Ensure that you take into account all request information when making the request, or you may run into errors or unexpected behavior from your implementation.

Thorough testing is heavily recommended to ensure that your implementation works as expected.

If desired, the astra-db-ts repo may be forked and have its test suite be run against your custom implementation to ensure complete compatibility.

Use cases

You may want to use a custom Fetcher implementation if:

  • You want to use a different fetch library (e.g. Axios, Superagent, etc.)
  • You want to extend an existing fetch implementation with your own custom logic
  • You want to add extra logging information to the response
Implementation

It is heavily recommended that you take a look at the aforementioned implementations to get a better idea of how to implement your own.

The basic idea is that you create a class or object implementing the Fetcher interface, and pass it to httpOptions in the DataAPIClient constructor.

See the Fetcher.fetch and Fetcher.close methods for information on how to implement those methods, along with a checklist of things to consider.

Example

class CustomFetcher implements Fetcher {
  async fetch(info: FetcherRequestInfo): Promise<FetcherResponseInfo> {
    // Custom fetch implementation
  }

  async close(): Promise<void> {
    // Custom cleanup logic (optional)
  }
}

const client = new DataAPIClient({
  httpOptions: { client: 'custom', fetcher: new CustomFetcher() },
});

See

  • FetcherRequestInfo
  • FetcherResponseInfo
  • CustomHttpClientOptions
interface Fetcher {
    close?(): Promise<void>;
    fetch(info): Promise<FetcherResponseInfo>;
}

Implemented by

Methods

close? fetch

Methods

Optional close

fetch

  • fetch(info): Promise<FetcherResponseInfo>
  • Overview

    Makes the actual API request for the given request information. Please take all request information into account when making the request, or you may run into errors or unexpected behavior from your implementation.

    Be sure to check out FetcherRequestInfo and FetcherResponseInfo for more information on the input and output objects.

    What you don't need to worry about
    • The appropriate content-type, user-agent, Authorization, etc., headers are already set
    • The body (if present) has already been stringify-ed, and any query parameters, already appended to the URL
    What you do need to worry about
    • Make sure the requested HTTP method is used
      • Only GET, POST, DELETE, but more may be required in the future
    • The timeout must be respected using an AbortSignal or another valid timeout mechanism.
      • e.g. axios's timeout option
    • If a timeout occurs, catch the error and throw info.mkTimeoutError() instead.
      • This will make a generic timeout error that's uniform between all fetchers
      • All other errors should be rethrown as-is
    • The response headers should be normalized into a plain JS object
      • E.g.Object.fromEntries(resp.headers.entries())
    • The response body should be returned as a plain string
      • E.g. await resp.text()
    • If info.forceHttp1 is true, ensure the request only uses HTTP/1[.1], even if HTTP/2 is supported.
      • This is because the DevOps API does not support HTTP/2
    • Any additional information you want to add to logging output may be included in extraLogInfo

    Parameters

    Returns Promise<FetcherResponseInfo>

Settings

Member Visibility

Theme

On This Page

closefetch