Types for the pagination properties.

[PopGoesTheWza]

Typically I create a got client with the following (simplified) pattern:

import got from 'got';
import type {ExtendOptions, Got} from 'got';

const paginate = (response, allItems, currentItems) => {
  // necessary code not relevant to this discussion
  return false;
};

const transform = (response) => (response.body as ThirdPartyType).entities;

export const client = (): Got => {
  const defaultOptions: ExtendOptions = {
    pagination: {paginate, transform},
  };

  return got.extend(defaultOptions);
};

First issue I have is that there is no exported type definition to the pagination properties. Hence the paginate and transform functions cannot be typed just by their own.

We can workaround that by defining some custom types in order to extract those missing types:

import type {PaginationOptions} from 'got';

type Pagination1<T> = Required<PaginationOptions<T, unknown>>['pagination'];
type Pagination2<T, R> = Required<PaginationOptions<T, R>>['pagination'];
export type Transform<T = unknown, R = unknown> = NonNullable<Pagination2<T, R>['transform']>;
export type Filter<T = unknown> = NonNullable<Pagination1<T>['filter']>;
export type Paginate<T = unknown, R = unknown> = NonNullable<Pagination2<T, R>['paginate']>;
export type ShouldContinue<T = unknown> = NonNullable<Pagination1<T>['shouldContinue']>;

Those types now allow us to write typed pagination functions like:

const transform: Transform = (response) => (response.body as ThirdPartyType).entities;

And since the Transform, Filter, Paginate and ShouldContinue types support generics, we can use finer typing such as:

const transform: Transform<Result, ThirdPartyType> = (response) => response.body.entities;

Except that we now have the second issue and conflicting types where we define pagination: {paginate, transform}! That is because the type ExtendOptions extends Options, which extends PromiseOnly.Options, which extends PaginationOptions<unknown, unknown>

Type '((response: Response<ThirdPartyType<Result>>) => Result[] | Promise<Result[]>) | ((response: Response<...>) => unknown[] | Promise<...>) | undefined' is not assignable to type '((response: Response<unknown>) => unknown[] | Promise<unknown[]>) | undefined'.
  Type '(response: Response<ThirdPartyType<Result>>) => Result[] | Promise<Result[]>' is not assignable to type '(response: Response<unknown>) => unknown[] | Promise<unknown[]>'.
    Types of parameters 'response' and 'response' are incompatible.
      Type 'Response<unknown>' is not assignable to type 'Response<ThirdPartyType<Result>>'.
        Type 'unknown' is not assignable to type 'ThirdPartyType<Result>'.

Annoying, though not critical at this point, I felt like sharing this with the comunity.

[szmarczak]

Unfortunately you have to either force cast it or use guards like is

[PopGoesTheWza]

Unfortunately you have to either force cast it or use guards like is

Or you have to add <T = unknown, R = unknown> to ExtendOptions, Options and PromiseOnly.Options, which will trickle down to PaginationOptions and fulfill my insatiable need for over-typing things... ;)

Yes, I can imagine how cumbersome it could look into the code base, and that it can likely break things in the long run.

P.S. : I am unsure which use of is you have in mind here.
P.P.S. : Perhaps exposing Transform, Filter, Paginate and ShouldContinue from a PaginationOptions<unknown, unknown> context is a "good enough" solution.

[szmarczak]

P.S. : I am unsure which use of is you have in mind here.

Assertions.

---

/cc @sindresorhus

[sindresorhus]

P.P.S. : Perhaps exposing Transform, Filter, Paginate and ShouldContinue from a PaginationOptions<unknown, unknown> context is a "good enough" solution.

Yes, we should definitely export these types. Pull request welcome for that.

[sindresorhus]

I don't think making everything more generic is worth it just to get some nicer typings for pagination. However, we could maybe make the response parameter strongly typed in the transform option as I think we have the response type.

[szmarczak]

The properties are already accessible via PaginationOptions<ElementType, BodyType>['transform'] etc.