Documentation / @zerotal/core / http / Http

Class: Http

Fluent facade for outgoing (server-to-server) HTTP requests. Static verb methods (Http.get, Http.post, …) return a PendingRequest that can be awaited directly or chained (.json(), .text()). Prefix a request with configuration (Http.withHeaders, Http.withToken, Http.timeout, Http.retry) to apply it before the verb.

The fake/assert* helpers intercept requests in tests so no real network traffic occurs.

Example

// GET with a custom header, retry, and timeout
const users = await Http
  .withHeaders({ "X-Trace": "abc" })
  .retry(3, 200)      // up to 3 attempts, 200ms apart
  .timeout(5000)      // abort after 5s
  .get("https://api.example.com/users")
  .json();

// POST a JSON body with a bearer token
const created = await Http
  .withToken("secret")
  .post("https://api.example.com/users", { name: "Alice" })
  .json();

// Testing — intercept requests
Http.fake([{ url: "https://api.example.com/*", body: { ok: true } }]);
await Http.get("https://api.example.com/users");
Http.assertSent((req) => req.url.includes("/users"));
Http.resetFakes();

Constructors

Constructor

new Http(): Http

Returns

Http

Configuration

withHeaders()

static withHeaders(headers): _Builder

Defined in: http/Http.ts:55

Start a request with the given headers applied. Returns a builder whose get/post/etc. methods issue the actual request.

Parameters

headers

Record<string, string>

Returns

_Builder

withToken()

static withToken(token): _Builder

Defined in: http/Http.ts:63

Set a Bearer token on the next request.

Parameters

token

string

Returns

_Builder

withBasicAuth()

static withBasicAuth(username, password): _Builder

Defined in: http/Http.ts:71

Set HTTP Basic Auth credentials.

Parameters

username

string

password

string

Returns

_Builder

Requests

get()

static get(url): PendingRequest

Defined in: http/Http.ts:97

Begin a GET request to url.

Parameters

url

string

Returns

PendingRequest

post()

static post(url, data?): PendingRequest

Defined in: http/Http.ts:105

Begin a POST request to url, attaching data as a JSON body when given.

Parameters

url

string

data?

unknown

Returns

PendingRequest

put()

static put(url, data?): PendingRequest

Defined in: http/Http.ts:115

Begin a PUT request to url, attaching data as a JSON body when given.

Parameters

url

string

data?

unknown

Returns

PendingRequest

patch()

static patch(url, data?): PendingRequest

Defined in: http/Http.ts:125

Begin a PATCH request to url, attaching data as a JSON body when given.

Parameters

url

string

data?

unknown

Returns

PendingRequest

delete()

static delete(url): PendingRequest

Defined in: http/Http.ts:135

Begin a DELETE request to url.

Parameters

url

string

Returns

PendingRequest

head()

static head(url): PendingRequest

Defined in: http/Http.ts:143

Begin a HEAD request to url.

Parameters

url

string

Returns

PendingRequest

Retries & resilience

timeout()

static timeout(milliseconds): _Builder

Defined in: http/Http.ts:79

Set the request timeout in milliseconds.

Parameters

milliseconds

number

Returns

_Builder

retry()

static retry(times, delay?): _Builder

Defined in: http/Http.ts:87

Retry up to times times with optional delay.

Parameters

times

number

delay?

number

Returns

_Builder

Testing

fake()

static fake(stubs?): void

Defined in: http/Http.ts:161

Intercept all outgoing HTTP requests with the given stubs. No real HTTP requests will be made while fakes are active.

Parameters

stubs?

FakeStub[] = ...

Array of URL-response pairs. Use '*' to match any URL.

Returns

void

Example

Http.fake([
  { url: 'https://api.example.com/users', body: [{ id: 1 }] },
  { url: '*', status: 503 },
]);

resetFakes()

static resetFakes(): void

Defined in: http/Http.ts:169

Remove all fake stubs and restore real HTTP behaviour.

Returns

void

recorded()

static recorded(): object[]

Defined in: http/Http.ts:177

Return all requests recorded since Http.fake() was called.

Returns

object[]

assertSent()

static assertSent(predicate): void

Defined in: http/Http.ts:186

Assert that at least one recorded request matches the predicate.

Parameters

predicate

(req) => boolean

Returns

void

Throws

when no recorded request matches.

assertNotSent()

static assertNotSent(predicate): void

Defined in: http/Http.ts:206

Assert that no recorded request matches the predicate.

Parameters

predicate

(req) => boolean

Returns

void

Throws

when a recorded request matches.

assertSentCount()

static assertSentCount(count): void

Defined in: http/Http.ts:220

Assert that exactly count requests were recorded.

Parameters

count

number

Returns

void

Throws

when the recorded count differs from count.

assertNothingSent()

static assertNothingSent(): void

Defined in: http/Http.ts:232

Assert that no requests were recorded.

Returns

void

Throws

when any request was recorded.