feat: Support custom options for custom fetch() functions (#36)

Closes Support extending the possible options that can be passed to the custom data-fetching function #22.

Author: webJose

README.md

@@ -11,7 +11,7 @@ This package:
 + **Supports abortable HTTP requests; no boilerplate.**
 + **Can auto-abort HTTP requests in favor of newer request versions, with optional delaying (debouncing).**
 + Works in any runtime that implements `fetch()` (browsers, NodeJS, etc.).
-+ Is probably the tiniest fetch wrapper you'll ever need:  **342 LOC** including typing (`npx cloc .\src --exclude-dir=tests`).
++ Is probably the tiniest fetch wrapper you'll ever need:  **364 LOC** including typing (`npx cloc .\src --exclude-dir=tests`).
 
 ## Does a Non-OK Status Code Warrant an Error?
 
@@ -564,9 +564,9 @@ a simple class, the `fetch-api-progress` NPM package and a custom body processor
 [Live demo in the Svelte REPL](https://svelte.dev/playground/ddeedfb44ab74727ac40df320c552b92)
 
 > [!NOTE]
-> If you wanted to, `fetch-api-progress` also supports upload progress.  As of **v0.9.0** of this library, however, is 
-> not too simple to integrate.  Soon, the ability to pass custom options to the core `fetch()` function will be a 
-> feature and will solve this integration scenario quite elegantly.  Stay tuned.
+> If you wanted to, `fetch-api-progress` also supports upload progress.  This is achieved by calling 
+> `trackRequestProgress` to create a specialized `RequestInit` object.  See [the next subsection](#custom-fetch-options) 
+> for details.
 
 ```ts
 import { trackResponseProgress } from "fetch-api-progress";
@@ -631,7 +631,57 @@ When the button is clicked, the download is started.  The custom processor simpl
 `DownloadProgress` class.  Svelte's reactivity system takes care of the rest, effectively bringing the progress element 
 to life as the download progresses.
 
+### Custom Fetch Options
+
+> Since **v0.10.0**
+
+If your custom data-fetching function (your custom `fetch()`) has abilities that require extra custom options from the 
+caller, you're in luck:  You can and TypeScript and Intellisense will fully work for you.
+
+To exemplify, let's do **upload progress** with the `fetch-api-progress` NPM package.
+
+First, create your custom data-fetching function:
+
+```typescript
+// uploader.ts
+import { DrFetch, type FetchFnUrl, type FetchFnInit } from "dr-fetch";
+import { trackRequestProgress, type FetchProgressEvent } from "fetch-api-progress";
+
+export type UploaderInit = FetchFnInit & {
+    onProgress?: (progress: FetchProgressEvent) => void;
+}
+
+function uploadingFetch(url: FetchFnUrl, init?: UploaderInit) {
+    const trackedRequest = trackRequestProgress(init, init.onProgress);
+    return fetch(url, trackedRequest);
+}
+
+export default new DrFetch(uploadingFetch); // This will be fully typed to support onProgress.
+```
+
+This is it.  From this point forward, you just use this uploader object and the uploads will report progress:
+
+```typescript
+import uploader from './uploader.js';
+
+const response = await uploader
+    .for<200, undefined>()
+    .post(
+        '/upload/big/data',
+        bigDataBody,
+        {
+            onProgress: (p) => console.log('Progress: %s', (p.lengthComputable && (p.loaded / p.total).toFixed(2)) || 0)
+        }
+    );
+```
+
+And there you were, learning all sorts of weird syntax, writing callbacks left and right to achieve things like this 
+with interceptors in `axios` and `ky`. :smile:
+
 ### I want fancier!
 
-Ok, more features are incoming, but if you feel you definitely need more, remember that `DrFetch` is a class.  You can 
-always extend it as per JavaScript's own rules.
+If you feel you definitely need more, remember that `DrFetch` is a class.  You can always extend it as per JavaScript's 
+own rules.
+
+Also, feel free to [open a new issue](https://github.com/WJSoftware/dr-fetch/issues) if you have an idea for a feature 
+that cannot be easily achievable in "user land".

src/DrFetch.ts

@@ -115,13 +115,18 @@ function textParser(response: Response) {
  * existing one using the parent's `clone` function.  When cloning, pass a new data-fetching function (if required) so 
  * the clone uses this one instead of the one of the parent fetcher.
  */
-export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abortable extends boolean = false> {
-    #fetchFn: FetchFn;
+export class DrFetch<
+    TStatusCode extends number = StatusCode,
+    TFetchInit extends FetchFnInit = FetchFnInit,
+    T = unknown,
+    Abortable extends boolean = false
+> {
+    #fetchFn: FetchFn<TFetchInit>;
     #customProcessors: [ProcessorPattern, (response: Response, stockParsers: { json: BodyParserFn<any>; text: BodyParserFn<string>; }) => Promise<any>][] = [];
-    #fetchImpl: (url: FetchFnUrl, init?: FetchFnInit) => Promise<any>;
+    #fetchImpl: (url: FetchFnUrl, init?: TFetchInit) => Promise<any>;
     #autoAbortMap: Map<AutoAbortKey, AbortController> | undefined;
 
-    async #abortableFetch(url: FetchFnUrl, init?: FetchFnInit) {
+    async #abortableFetch(url: FetchFnUrl, init?: TFetchInit) {
         try {
             return await this.#simpleFetch(url, init);
         }
@@ -136,7 +141,7 @@ export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abort
         }
     }
 
-    async #simpleFetch(url: FetchFnUrl, init?: FetchFnInit) {
+    async #simpleFetch(url: FetchFnUrl, init?: TFetchInit) {
         const response = await this.#fetchFn(url, init);
         const body = await this.#readBody(response);
         return {
@@ -182,7 +187,7 @@ export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abort
      * function to register a custom body processor.
      * @param fetchFn Optional data-fetching function to use instead of the stock `fetch` function.
      */
-    constructor(fetchFn?: FetchFn) {
+    constructor(fetchFn?: FetchFn<TFetchInit>) {
         this.#fetchFn = fetchFn ?? fetch.bind(globalThis.window || global);
         this.#fetchImpl = this.#simpleFetch.bind(this);
     }
@@ -219,7 +224,7 @@ export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abort
         if (opts.preserveAbortable && this.isAbortable) {
             newClone.abortable();
         }
-        return newClone as DrFetch<TStatusCode, TInherit extends true ? T : unknown, CloneAbortable>;
+        return newClone as DrFetch<TStatusCode, TFetchInit, TInherit extends true ? T : unknown, CloneAbortable>;
     }
 
     /**
@@ -249,7 +254,7 @@ export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abort
      * @returns This fetcher object with its response type modified to include the body specification provided.
      */
     for<TStatus extends TStatusCode, TBody = {}>() {
-        return this as DrFetch<TStatusCode, FetchResult<T, TStatus, TBody>, Abortable>;
+        return this as DrFetch<TStatusCode, TFetchInit, FetchResult<T, TStatus, TBody>, Abortable>;
     }
 
     #contentMatchesType(contentType: string, response: Response, ...types: ProcessorPattern[]) {
@@ -308,7 +313,7 @@ export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abort
     abortable() {
         this.#fetchImpl = this.#abortableFetch.bind(this);
         this.#autoAbortMap ??= new Map<AutoAbortKey, AbortController>();
-        return this as DrFetch<TStatusCode, T, true>;
+        return this as DrFetch<TStatusCode, TFetchInit, T, true>;
     }
 
     /**
@@ -318,7 +323,7 @@ export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abort
      * @param init Options for the data-fetching function.
      * @returns A response object with the HTTP response's `ok`, `status`, `statusText` and `body` properties.
      */
-    async fetch(url: FetchFnUrl, init?: FetchFnInit): Promise<(Abortable extends true ? {
+    async fetch(url: FetchFnUrl, init?: TFetchInit): Promise<(Abortable extends true ? {
         aborted: true;
         error: DOMException;
     } | T : T)> {
@@ -333,7 +338,7 @@ export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abort
             this.#autoAbortMap?.get(autoAbort.key)?.abort();
             const ac = new AbortController();
             this.#autoAbortMap!.set(autoAbort.key, ac);
-            init ??= {};
+            init ??= {} as TFetchInit;
             init.signal = ac.signal;
             if (autoAbort.delay !== undefined) {
                 const aborted = await new Promise<boolean>((rs) => {
@@ -371,17 +376,17 @@ export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abort
      * @param url URL for the fetch function call.
      * @returns A response object with the HTTP response's `ok`, `status`, `statusText` and `body` properties.
      */
-    get(url: URL | string, init?: Omit<FetchFnInit, 'method' | 'body'>) {
-        return this.fetch(url, { ...init, method: 'GET' });
+    get(url: URL | string, init?: Omit<TFetchInit, 'method' | 'body'>) {
+        return this.fetch(url, { ...init, method: 'GET' } as TFetchInit);
     }
 
     /**
      * Shortcut method to emit a HEAD HTTP request.
      * @param url URL for the fetch function call.
      * @returns A response object with the HTTP response's `ok`, `status`, `statusText` and `body` properties.
      */
-    head(url: URL | string, init?: Omit<FetchFnInit, 'method' | 'body'>) {
-        return this.fetch(url, { ...init, method: 'HEAD' });
+    head(url: URL | string, init?: Omit<TFetchInit, 'method' | 'body'>) {
+        return this.fetch(url, { ...init, method: 'HEAD' } as TFetchInit);
     }
 
     /**
@@ -398,10 +403,10 @@ export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abort
      * does in those cases.
      * @returns A response object with the HTTP response's `ok`, `status`, `statusText` and `body` properties.
      */
-    post(url: URL | string, body?: BodyInit | null | Record<string, any>, init?: Omit<FetchFnInit, 'method' | 'body'>) {
+    post(url: URL | string, body?: BodyInit | null | Record<string, any>, init?: Omit<TFetchInit, 'method' | 'body'>) {
         const fullInit = this.#createInit(body, init);
         fullInit.method = 'POST';
-        return this.fetch(url, fullInit);
+        return this.fetch(url, fullInit as TFetchInit);
     }
 
     /**
@@ -418,10 +423,10 @@ export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abort
      * does in those cases.
      * @returns A response object with the HTTP response's `ok`, `status`, `statusText` and `body` properties.
      */
-    patch(url: URL | string, body?: BodyInit | null | Record<string, any>, init?: Omit<FetchFnInit, 'method' | 'body'>) {
+    patch(url: URL | string, body?: BodyInit | null | Record<string, any>, init?: Omit<TFetchInit, 'method' | 'body'>) {
         const fullInit = this.#createInit(body, init);
         fullInit.method = 'PATCH';
-        return this.fetch(url, fullInit);
+        return this.fetch(url, fullInit as TFetchInit);
     }
 
     /**
@@ -438,10 +443,10 @@ export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abort
      * does in those cases.
      * @returns A response object with the HTTP response's `ok`, `status`, `statusText` and `body` properties.
      */
-    delete(url: URL | string, body?: BodyInit | null | Record<string, any>, init?: Omit<FetchFnInit, 'method' | 'body'>) {
+    delete(url: URL | string, body?: BodyInit | null | Record<string, any>, init?: Omit<TFetchInit, 'method' | 'body'>) {
         const fullInit = this.#createInit(body, init);
         fullInit.method = 'DELETE';
-        return this.fetch(url, fullInit);
+        return this.fetch(url, fullInit as TFetchInit);
     }
 
     /**
@@ -458,9 +463,9 @@ export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abort
      * does in those cases.
      * @returns A response object with the HTTP response's `ok`, `status`, `statusText` and `body` properties.
      */
-    put(url: URL | string, body?: BodyInit | null | Record<string, any>, init?: Omit<FetchFnInit, 'method' | 'body'>) {
+    put(url: URL | string, body?: BodyInit | null | Record<string, any>, init?: Omit<TFetchInit, 'method' | 'body'>) {
         const fullInit = this.#createInit(body, init);
         fullInit.method = 'PUT';
-        return this.fetch(url, fullInit);
+        return this.fetch(url, fullInit as TFetchInit);
     }
 }

src/types.ts

@@ -51,15 +51,10 @@ export type FetchResult<T, TStatus extends number, TBody = undefined> =
         T | CoreFetchResult<TStatus, TBody>
     ) extends infer R ? R : never;
 
-/**
- * Type of the stock fetch function.
- */
-export type FetchFn = typeof fetch;
-
 /**
  * Type of the fetch function's URL parameter.
  */
-export type FetchFnUrl = Parameters<FetchFn>[0];
+export type FetchFnUrl = Parameters<typeof fetch>[0];
 
 /**
  * Possible types of keys accepted by the `autoAbort` option.
@@ -69,7 +64,7 @@ export type AutoAbortKey = string | symbol | number;
 /**
  * Type of the fetch function's init parameter.
  */
-export type FetchFnInit = Parameters<FetchFn>[1] & {
+export type FetchFnInit = Parameters<typeof fetch>[1] & {
     /**
      * Specifies the options for auto-aborting the HTTP request.
      * 
@@ -89,6 +84,11 @@ export type FetchFnInit = Parameters<FetchFn>[1] & {
     };
 };
 
+/**
+ * Type of the stock fetch function.
+ */
+export type FetchFn<TInit extends FetchFnInit = FetchFnInit> = (url: FetchFnUrl, init?: TInit) => Promise<Response>;
+
 /**
  * Fetcher cloning options.
  */