types.ts

import * as PCancelable from 'p-cancelable';
import Request, {
	Options,
	Response,
	RequestError,
	RequestEvents
} from '../core/index';

/**
All parsing methods supported by Got.
*/
export type ResponseType = 'json' | 'buffer' | 'text';

export interface PaginateData<R, T> {
	response: Response<R>;
	allItems: T[];
	currentItems: T[];
}

export interface PaginationOptions<T, R> {
	/**
	All options accepted by `got.paginate()`.
	*/
	pagination?: {
		/**
		A function that transform [`Response`](#response) into an array of items.
		This is where you should do the parsing.

		@default response => JSON.parse(response.body)
		*/
		transform?: (response: Response<R>) => Promise<T[]> | T[];

		/**
		Checks whether the item should be emitted or not.

		@default (item, allItems, currentItems) => true
		*/
		filter?: (item: T, allItems: T[], currentItems: T[]) => boolean;

		/**
		The function takes three arguments:
		- `response` - The current response object.
		- `allItems` - An array of the emitted items.
		- `currentItems` - Items from the current response.

		It should return an object representing Got options pointing to the next page.
		The options are merged automatically with the previous request, therefore the options returned `pagination.paginate(...)` must reflect changes only.
		If there are no more pages, `false` should be returned.

		@example
		```
		const got = require('got');

		(async () => {
			const limit = 10;

			const items = got.paginate('https://example.com/items', {
				searchParams: {
					limit,
					offset: 0
				},
				pagination: {
					paginate: (response, allItems, currentItems) => {
						const previousSearchParams = response.request.options.searchParams;
						const previousOffset = previousSearchParams.get('offset');

						if (currentItems.length < limit) {
							return false;
						}

						return {
							searchParams: {
								...previousSearchParams,
								offset: Number(previousOffset) + limit,
							}
						};
					}
				}
			});

			console.log('Items from all pages:', items);
		})();
		```
		*/
		paginate?: (paginate: PaginateData<R, T>) => Options | false;

		/**
		Checks whether the pagination should continue.

		For example, if you need to stop **before** emitting an entry with some flag, you should use `(item, allItems, currentItems) => !item.flag`.
		If you want to stop **after** emitting the entry, you should use `(item, allItems, currentItems) => allItems.some(entry => entry.flag)` instead.

		@default (item, allItems, currentItems) => true
		*/
		shouldContinue?: (item: T, allItems: T[], currentItems: T[]) => boolean;

		/**
		The maximum amount of items that should be emitted.

		@default Infinity
		*/
		countLimit?: number;

		/**
		Milliseconds to wait before the next request is triggered.

		@default 0
		*/
		backoff?: number;
		/**
		The maximum amount of request that should be triggered.
		Retries on failure are not counted towards this limit.

		For example, it can be helpful during development to avoid an infinite number of requests.

		@default 10000
		*/
		requestLimit?: number;

		/**
		Defines how the parameter `allItems` in pagination.paginate, pagination.filter and pagination.shouldContinue is managed.
		When set to `false`, the parameter `allItems` is always an empty array.

		This option can be helpful to save on memory usage when working with a large dataset.
		*/
		stackAllItems?: boolean;
	};
}

export type AfterResponseHook<ResponseType = unknown> = (response: Response<ResponseType>, retryWithMergedOptions: (options: Options) => CancelableRequest<Response>) => Response | CancelableRequest<Response> | Promise<Response | CancelableRequest<Response>>;

// These should be merged into Options in core/index.ts
export namespace PromiseOnly {
	export interface Hooks {
		/**
		Called with [response object](#response) and a retry function.
		Calling the retry function will trigger `beforeRetry` hooks.

		Each function should return the response.
		This is especially useful when you want to refresh an access token.

		__Note__: When using streams, this hook is ignored.

		@example
		```
		const got = require('got');

		const instance = got.extend({
			hooks: {
				afterResponse: [
					(response, retryWithMergedOptions) => {
						if (response.statusCode === 401) { // Unauthorized
							const updatedOptions = {
								headers: {
									token: getNewToken() // Refresh the access token
								}
							};

							// Save for further requests
							instance.defaults.options = got.mergeOptions(instance.defaults.options, updatedOptions);

							// Make a new retry
							return retryWithMergedOptions(updatedOptions);
						}

						// No changes otherwise
						return response;
					}
				],
				beforeRetry: [
					(options, error, retryCount) => {
						// This will be called on `retryWithMergedOptions(...)`
					}
				]
			},
			mutableDefaults: true
		});
		```
		*/
		afterResponse?: AfterResponseHook[];
	}

	export interface Options extends PaginationOptions<unknown, unknown> {
		/**
		The parsing method.

		The promise also has `.text()`, `.json()` and `.buffer()` methods which return another Got promise for the parsed body.

		It's like setting the options to `{responseType: 'json', resolveBodyOnly: true}` but without affecting the main Got promise.

		__Note__: When using streams, this option is ignored.

		@example
		```
		(async () => {
			const responsePromise = got(url);
			const bufferPromise = responsePromise.buffer();
			const jsonPromise = responsePromise.json();

			const [response, buffer, json] = Promise.all([responsePromise, bufferPromise, jsonPromise]);
			// `response` is an instance of Got Response
			// `buffer` is an instance of Buffer
			// `json` is an object
		})();
		```

		@example
		```
		// This
		const body = await got(url).json();

		// is semantically the same as this
		const body = await got(url, {responseType: 'json', resolveBodyOnly: true});
		```
		*/
		responseType?: ResponseType;

		/**
		When set to `true` the promise will return the Response body instead of the Response object.

		@default false
		*/
		resolveBodyOnly?: boolean;

		/**
		Returns a `Stream` instead of a `Promise`.
		This is equivalent to calling `got.stream(url, options?)`.

		@default false
		*/
		isStream?: boolean;

		/**
		[Encoding](https://nodejs.org/api/buffer.html#buffer_buffers_and_character_encodings) to be used on `setEncoding` of the response data.

		To get a [`Buffer`](https://nodejs.org/api/buffer.html), you need to set `responseType` to `buffer` instead.
		Don't set this option to `null`.

		__Note__: This doesn't affect streams! Instead, you need to do `got.stream(...).setEncoding(encoding)`.

		@default 'utf-8'
		*/
		encoding?: BufferEncoding;
	}

	export interface NormalizedOptions {
		responseType: ResponseType;
		resolveBodyOnly: boolean;
		isStream: boolean;
		encoding?: BufferEncoding;
		pagination?: Required<PaginationOptions<unknown, unknown>['pagination']>;
	}

	export interface Defaults {
		responseType: ResponseType;
		resolveBodyOnly: boolean;
		isStream: boolean;
		pagination?: Required<PaginationOptions<unknown, unknown>['pagination']>;
	}

	export type HookEvent = 'afterResponse';
}

/**
An error to be thrown when server response code is 2xx, and parsing body fails.
Includes a `response` property.
*/
export class ParseError extends RequestError {
	declare readonly response: Response;

	constructor(error: Error, response: Response) {
		const {options} = response.request;

		super(`${error.message} in "${options.url.toString()}"`, error, response.request);
		this.name = 'ParseError';
	}
}

/**
An error to be thrown when the request is aborted with `.cancel()`.
*/
export class CancelError extends RequestError {
	declare readonly response: Response;

	constructor(request: Request) {
		super('Promise was canceled', {}, request);
		this.name = 'CancelError';
	}

	get isCanceled() {
		return true;
	}
}

export interface CancelableRequest<T extends Response | Response['body'] = Response['body']> extends PCancelable<T>, RequestEvents<CancelableRequest<T>> {
	json: <ReturnType>() => CancelableRequest<ReturnType>;
	buffer: () => CancelableRequest<Buffer>;
	text: () => CancelableRequest<string>;
}

export * from '../core';