nc.http

nc.http.request()

request<T = any>(url: string | URL, options?: HttpOptions): Promise<HttpResponse<T>>

Sends a request and resolves with the response, body already read. Throws an HttpError for error statuses, a TimeoutError when it's too slow and an AbortError when cancelled.

Returns Promise<HttpResponse<T>>

Throws HttpError | TimeoutError | AbortError

Example

const res = await http.request("https://api.example.com/items/42", {
  method: "PUT",
  json: { name: "Lamp" },
  timeout: "10s",
  retry: { attempts: 5, statuses: [429, 503] },
});
res.data; // parsed JSON

nc.http.get()

get<T = any>(url: string | URL, options?: HttpOptions): Promise<HttpResponse<T>>

Sends a GET request.

Returns Promise<HttpResponse<T>>

Example

const { data } = await http.get("https://api.example.com/users", { query: { page: 2, tags: ["a", "b"] } });

nc.http.head()

head<T = undefined>(url: string | URL, options?: HttpOptions): Promise<HttpResponse<T>>

Sends a HEAD request: headers only, no body.

Returns Promise<HttpResponse<T>>

Example

const { headers } = await http.head("https://example.com/big.zip");
headers["content-length"];

nc.http.post()

post<T = any>(url: string | URL, data?: unknown, options?: HttpOptions): Promise<HttpResponse<T>>

Sends a POST request. Objects, arrays, numbers and booleans go as JSON; strings, Buffers, FormData, Blobs and streams go as they are.

Returns Promise<HttpResponse<T>>

Example

const { data: user } = await http.post("https://api.example.com/users", { name: "Ada" });
await http.post(uploadUrl, formData);

nc.http.put()

put<T = any>(url: string | URL, data?: unknown, options?: HttpOptions): Promise<HttpResponse<T>>

Sends a PUT request. The body works like in post().

Returns Promise<HttpResponse<T>>

nc.http.patch()

patch<T = any>(url: string | URL, data?: unknown, options?: HttpOptions): Promise<HttpResponse<T>>

Sends a PATCH request. The body works like in post().

Returns Promise<HttpResponse<T>>

nc.http.delete()

delete<T = any>(url: string | URL, options?: HttpOptions): Promise<HttpResponse<T>>

Sends a DELETE request.

Returns Promise<HttpResponse<T>>

Example

await http.delete(`https://api.example.com/users/${id}`);

nc.http.download()

download(url: string | URL, destination: string, options?: HttpOptions): Promise<{ path: string; size: number; }>

Downloads to a file as a stream, so memory stays flat whatever the size. Folders are created, and a partial file is removed if it fails.

Returns Promise<{ path: string, size: number }>: The absolute path and size in bytes.

Throws HttpError | TimeoutError | AbortError

Example

await http.download("https://example.com/video.mp4", "./downloads/video.mp4", {
  onDownloadProgress: ({ percent }) => bar.update(percent ?? 0),
});

nc.http.create()

create(defaults?: HttpOptions): HttpClient

Creates a client with default options. Options passed to each call are merged on top.

Returns HttpClient

Example

const github = http.create({
  baseURL: "https://api.github.com",
  auth: { bearer: process.env.GITHUB_TOKEN },
  hooks: { afterResponse: [(res) => nc.debug(res.status, res.url)] },
});
const { data: repo } = await github.get("/repos/nodejs/node");

nc.http.HttpErrorproperty

HttpError: typeof HttpError

Thrown by nc.http when the response status isn't 2xx (unless you pass throwHttpErrors: false), and for network failures (status 0).