Add TypeScript types to fetchFunc option

[dstaley]

This PR adds more specific TypeScript types to the fetchFunc option.

Using Function is the same as (...args: any) => any, meaning that any function would be accepted as a valid fetchFunc. With this PR, the supplied function will need to conform to the minimal fetch interface. Essentially, functions will need to have the following properties:

export interface FetchHeaders {
  keys(): IterableIterator<string> | string[];
  entries(): IterableIterator<[string, string]> | [string, string][];
  get(name: string): string | null;
  has(name: string): boolean;
}

export interface FetchResponse {
  status: number;
  statusText: string;
  text(): Promise<string>;
  headers: FetchHeaders;
}

export type FetchFunction = (
  input: RequestInfo,
  init?: RequestInit | undefined
) => Promise<FetchResponse>;

Most of this should be easily achievable with XMLHttpRequest, and even easier if you can reuse the browser's Headers class.

I'm fairly confident this also covers all our usage in kinto.js, but if not I'll update the types here to ensure that responses from kinto-http.js have all the bits that kinto.js wants.

(Also, since the new fetchFunc option is for Firefox, these types won't be enforced. They will, however, be a good guide to follow when building since they represent all the functionality that kinto-http.js expects from fetch.)

[github-actions]

Size Change: -6 B (0%)

Total Size: 40.9 kB

ℹ️ View Unchanged

Filename	Size	Change
dist/kinto-http.min.js	9.09 kB	0 B
dist/kinto-http.node.js	15.2 kB	0 B
dist/moz-kinto-http-client.js	16.6 kB	-6 B (0%)

_{compressed-size-action}

[leplatrem]

Thanks for fixing my «haste» 😊

I have a question (that may have an obvious answer but I don't see it): why do we redefine Response and Headers instead of using official types (like you did for RequestInfo and RequestInit)?

[dstaley]

I have a question (that may have an obvious answer but I don't see it): why do we redefine Response and Headers instead of using official types (like you did for RequestInfo and RequestInit)?

Great question! The reason is that Response and Headers have very large interfaces that might be a pain to implement. For instance, here's the interfaces for Response and Headers:

interface Response {
    headers: Headers;
    ok: boolean;
    redirected: boolean;
    status: number;
    statusText: string;
    type: ResponseType;
    url: string;
    clone(): Response;
    body: ReadableStream<Uint8Array> | null;
    bodyUsed: boolean;
    arrayBuffer(): Promise<ArrayBuffer>;
    blob(): Promise<Blob>;
    formData(): Promise<FormData>;
    json(): Promise<any>;
    text(): Promise<string>;
}

interface Headers {
    append(name: string, value: string): void;
    delete(name: string): void;
    get(name: string): string | null;
    has(name: string): boolean;
    set(name: string, value: string): void;
    forEach(callbackfn: (value: string, key: string, parent: Headers) => void, thisArg?: any): void;
}

In order for TypeScript to compile a user's code, the user would need to implement the entirety of those interfaces. By using our own subset of the interface, we can limit the interface to just the behavior that we rely on.

You might be wondering why we use RequestInit instead of defining our own interface. Well, since RequestInit is an input instead of an output, you don't need to do any additional work to handle it. All the implementation effort is around making the return value coform to the interfaces, so we can save us some work by reusing the input interfaces.

[leplatrem]

Merci for the detailed explanation 🙏! That makes total sense :)