1-promise.md

> Back to homepage

Promise API

Source code: source/as-promise/index.ts

The main Got function returns a Promise.
Although in order to support cancelation, PCancelable is used instead of pure Promise.

got(url: string | URL, options?: OptionsInit, defaults?: Options)

Returns: Promise<Response>

The most common way is to pass the URL as the first argument, then the options as the second.

import got from 'got';

const {headers} = await got(
	'https://httpbin.org/anything',
	{
		headers: {
			foo: 'bar'
		}
	}
).json();

got(options: OptionsInit)

Returns: Promise<Response>

Alternatively, you can pass only options containing a url property.

import got from 'got';

const {headers} = await got(
	{
		url: 'https://httpbin.org/anything',
		headers: {
			foo: 'bar'
		}
	}
).json();

This is semantically the same as the first approach.

promise.json<T>()

Returns: Promise<T>

A shortcut method that gives a Promise returning a JSON object.

It is semantically the same as settings options.resolveBodyOnly to true and options.responseType to 'json'.

promise.buffer()

Returns: Promise<Buffer>

A shortcut method that gives a Promise returning a Buffer.

It is semantically the same as settings options.resolveBodyOnly to true and options.responseType to 'buffer'.

promise.text()

Returns: Promise<string>

A shortcut method that gives a Promise returning a string.

It is semantically the same as settings options.resolveBodyOnly to true and options.responseType to 'text'.

promise.cancel(reason?: string)

Cancels the request and optionally provide a reason.

The cancellation is synchronous.
Calling it after the promise has settled or multiple times does nothing.

This will cause the promise to reject with CancelError.

promise.isCanceled

Type: boolean

Whether the promise is canceled.

promise.on(event, handler)

The events are the same as in Stream API.

promise.off(event, handler)

Removes listener registered with promise.on

import {createReadStream} from 'node:fs';
import got from 'got';

const ongoingRequestPromise = got.post(uploadUrl, {
    body: createReadStream('sample.txt')
});

const eventListener = (progress: Progress) => {
    console.log(progress);
};

ongoingRequestPromise.on('uploadProgress', eventListener);

setTimeout(() => {
    ongoingRequestPromise.off('uploadProgress', eventListener);
}, 500);

await ongoingRequestPromise;