@mcsb/api / Exports / HttpClient

Class: HttpClient ​

The HttpClient class is how our API classes, such as HypixelAPI and MojangAPI interact with their respective HTTP services. The HttpClient is responsible for caching responses and setting request headers. Otherwise, the fetch method largely matches the Fetch API.

Table of contents ​

Constructors ​

• constructor

Properties ​

• cache
• userAgent

Methods ​

• destroy
• fetch
• genHeaders
• hashRequest

Constructors ​

constructor ​

• new HttpClient(userAgent?, cache?)

Constructor for a new HTTP client.

Parameters ​

Defined in ​

packages/api/src/http/HttpClient.ts:43

Properties ​

cache ​

• Readonly cache: null | Cache<SerializableResponse>

The Cache being used by this HttpClient, or null if caching is disabled for this HttpClient.

Defined in ​

packages/api/src/http/HttpClient.ts:35

userAgent ​

• userAgent: null | string

User agent to send with requests in the User-Agent HTTP header. Assigned in the constructor, but can be reassigned later.

Defined in ​

packages/api/src/http/HttpClient.ts:31

Methods ​

destroy ​

▸ destroy(): void

Destroy this HttpClient. This method will free up resources (primarily in the Cache), and further use of this HttpClient may result in unexpected behavior. This method should be called if you're attempting to discard this HttpClient instance, but are not yet shutting down your program entirely.

Returns ​

void

Defined in ​

packages/api/src/http/HttpClient.ts:160

fetch ​

▸ fetch(url, init?, cacheOnly?): Promise<Response>

Send an HTTP Request to the provided URL or Request. The specification for this method mirrors that of the Fetch API, minus the differences outlined below. HttpClient will generate default headers for the request. By default, this is just the User-Agent, however overrides can add additional headers. Generated headers will be overwritten by any headers already defined in the Request or RequestInit objects, if provided. If both a Request and RequestInit object are provided, any values defined within the RequestInit take precedence over values already defined in the Request (this is the way Bun's fetch function works). Any values in the Request that are not defined in the RequestInit will still be used. This only applies to the top level (i.e., if the headers property exists in the RequestInit object, the headers defined in the Request will be ignored). You can attempt to fetch the Response exclusively from the cache with the cacheOnly argument. If there's no hit in the cache, null will be returned.

Parameters ​

Returns ​

Promise<Response>

The HTTP Response corresponding to the given Request and RequestInit. If this HttpClient has a cache, this will return the cached Response instead, and an HTTP request will not be sent. If there is no hit in the cache, it will return null if cacheOnly was set to true. If cacheOnly is set to false, the HTTP request will be set and the Response will be returned.

Throws

• Error if an invalid URL is provided
• Error if the HTTP request fails

Defined in ​

packages/api/src/http/HttpClient.ts:75

▸ fetch(url, init?, cacheOnly?): Promise<null | Response>

Send an HTTP Request to the provided URL or Request. The specification for this method mirrors that of the Fetch API, minus the differences outlined below. HttpClient will generate default headers for the request. By default, this is just the User-Agent, however overrides can add additional headers. Generated headers will be overwritten by any headers already defined in the Request or RequestInit objects, if provided. If both a Request and RequestInit object are provided, any values defined within the RequestInit take precedence over values already defined in the Request (this is the way Bun's fetch function works). Any values in the Request that are not defined in the RequestInit will still be used. This only applies to the top level (i.e., if the headers property exists in the RequestInit object, the headers defined in the Request will be ignored). You can attempt to fetch the Response exclusively from the cache with the cacheOnly argument. If there's no hit in the cache, null will be returned.

Parameters ​

Returns ​

Promise<null | Response>

The HTTP Response corresponding to the given Request and RequestInit. If this HttpClient has a cache, this will return the cached Response instead, and an HTTP request will not be sent. If there is no hit in the cache, it will return null if cacheOnly was set to true. If cacheOnly is set to false, the HTTP request will be set and the Response will be returned.

Throws

• Error if an invalid URL is provided
• Error if the HTTP request fails

Defined in ​

packages/api/src/http/HttpClient.ts:103

genHeaders ​

▸ Protected genHeaders(): Headers

Generate a Headers object to apply to and send with Requests via fetch. By default, this is just the User-Agent, but more can be added in overrides. Any headers which are explicitly provided in the fetch input will take precedence over headers generated by this method.

Returns ​

Headers

a Headers object with the default headers added.

Defined in ​

packages/api/src/http/HttpClient.ts:197

hashRequest ​

▸ Protected hashRequest(req): Promise<string>

Generate a hash string for a Request. Request hashes are used by this HttpClient in managing the cache. The hash for a given Request is used as a key within the cache to reference the accompanying Response. If a Cache is not provided to an instance of this HttpClient, this method won't be used by default.

Parameters ​

Returns ​

Promise<string>

A string which uniquely identifies this Request's associated Response.By default, this is in the form of an MD5 hash to a string resembling the HTTP message format as defined in 2616, but with the HTTP version removed from the start line. However, this method could be overridden to provide custom hashing functionality, such as shared caches between URLs, or to ignore headers or other parameters.

Defined in ​

packages/api/src/http/HttpClient.ts:176