Merge 7cb2612 into ddd7930

source/as-promise/core.ts

@@ -46,6 +46,9 @@ export const parseBody = (response: Response, responseType: ResponseType, parseJ
 	}
 };
 
+/**
+A Got request sub-class that will return a promise.
+*/
 export default class PromisableRequest extends Request {
 	['constructor']: typeof PromisableRequest;
 	declare options: NormalizedOptions;

source/as-promise/types.ts

@@ -32,13 +32,107 @@ export interface RequiredRetryOptions {
 
 export interface PaginationOptions<T, R> {
 	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?: (response: Response<R>, allItems: T[], currentItems: 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;
 	};
 }