feat: Add auto-abort of HTTP requests (#29)

webJose · web-flow · commit eb86c90fd3d8 · 2025-03-31T11:12:45.000-06:00
diff --git a/README.md b/README.md
@@ -9,8 +9,9 @@ This package:
 + Does **not** throw on non-OK HTTP responses.
 + **Can fully type all possible HTTP responses depending on the HTTP status code, even non-standard ones like 499.**
 + **Supports abortable HTTP requests; no boilerplate.**
++ **Can Auto-abort HTTP requests in favor of newer request versions.**
 + Works in any runtime that implements `fetch()` (browsers, NodeJS, etc.).
-+ Probably the tiniest fetch wrapper you'll ever need.
++ Is probably the tiniest fetch wrapper you'll ever need:  **342 LOC** including typing (`npx cloc .\src --exclude-dir=tests`).
 
 ## Does a Non-OK Status Code Warrant an Error?
 
@@ -262,7 +263,7 @@ export const rootFetcher new DrFetch(myFetch)
 export const abortableRootFetcher = rootFetcher.clone().abortable();
 ```
 
-We clone it because `abortable()` has permanent side effects on the object's state.  Cloning also helps with other 
+We clone it because `abortable()` has permanent side effects on the object's state.  Cloning can also help with other 
 scenarios, as explained next.
 
 ### Specializing the Root Fetcher
@@ -300,10 +301,88 @@ const specialFetcher = rootFetcher.clone({ preserveAbortable: false });
 > `preserveTyping` is a TypeScript trick and cannot be a variable of type `boolean`.  Its value doesn't matter in 
 > runtime because types are not a runtime thing, and TypeScript depends on knowing if the value is `true` or `false`.
 > 
-> On the other hand, `preserveAbortable` is a hybrid:  It uses the same TypeScript trick, but its value does matter in 
-> runtime because an abortable fetcher object has different inner state than a stock fetcher object.  In this sense, 
-> supporting a variable would be ideal, but there's just no way to properly reconcile the TypeScript side with a 
-> variable of type `boolean`.  Therefore, try to always use constant values.
+> On the other hand, `preserveAbortable` (since **v0.9.0**) is a hybrid:  It uses the same TypeScript trick, but its 
+> value does matter in runtime because an abortable fetcher object has different inner state than a stock fetcher 
+> object.  In this sense, supporting a variable would be ideal, but there's just no way to properly reconcile the 
+> TypeScript side with a variable of type `boolean`.  Therefore, try to always use constant values.
+
+## Auto-Abortable HTTP Requests
+
+> Since **v0.9.0**
+
+An HTTP request can automatically abort whenever a new version of the HTTP request is executed.  This is useful in 
+cases like server-sided autocomplete components, where an HTTP request is made every time a user stops typing in the 
+search textbox.  As soon as a new HTTP request is made, the previous has no value.  With `dr-fetch`, this chore is 
+fully automated.
+
+To illustrate, this is how it would be done "by hand", as if auto-abortable wasn't a feature:
+
+```typescript
+import { abortableRootFetcher } from './root-fetchers.js';
+import type { SimpleItem } from './my-types.js';
+
+let ac: AbortController;
+
+async function fetchAutocompleteList(searchTerm: string) {
+    ac?.abort();
+    ac = new AbortController();
+    const response = await abortableRootFetcher
+        .for<200, SimpleItem[]>()
+        .get(`/my/data?s=${searchTerm}`, { signal: ac.signal });
+    if (!response.aborted) {
+        ...
+    }
+}
+```
+
+While this is not too bad, it can actually be like this:
+
+```typescript
+import { abortableRootFetcher } from './root-fetchers.js';
+import type { SimpleItem } from './my-types.js';
+
+async function fetchAutocompleteList(searchTerm: string) {
+    const response = await abortableRootFetcher
+        .for<200, SimpleItem[]>()
+        .get(`/my/data?s=${searchTerm}`, { autoAbort: 'my-key' });
+    if (!response.aborted) {
+        ...
+    }
+}
+```
+
+> [!NOTE]
+> The key can be a string, a number or a unique symbol.  Keys are not shared between fetcher instances, and cloning 
+> does not clone any existing keys.
+
+`DrFetch` instances create and keep track of abort controllers by key.  All one must do is provide a key when starting 
+the HTTP request.  Furthermore, the abort controllers are disposed as soon as the HTTP request resolves or rejects.
+
+### Delaying an Auto-Abortable HTTP Request
+
+Aborting the HTTP request (the call to `fetch()`) is usually not the only thing that front-end developers do in cases 
+like the autocomplete component.  Developers usually also debounce the action of making the HTTP request for a short 
+period of time (around 500 milliseconds).
+
+You can do this very easily as well with `dr-fetch`.  There is no need to program the debouncing externally.
+
+This is the previous example, with a delay specified:
+
+```typescript
+import { abortableRootFetcher } from './root-fetchers.js';
+import type { SimpleItem } from './my-types.js';
+
+async function fetchAutocompleteList(searchTerm: string) {
+    const response = await abortableRootFetcher
+        .for<200, SimpleItem[]>()
+        .get(`/my/data?s=${searchTerm}`, { autoAbort: { key: 'my-key', delay: 500 }});
+    if (!response.aborted) {
+        ...
+    }
+}
+```
+
+By using the object form of `autoAbort`, one can specify the desired delay, in milliseconds.
 
 ## Shortcut Functions
 
diff --git a/src/DrFetch.ts b/src/DrFetch.ts
@@ -1,5 +1,5 @@
 import { aborted } from "util";
-import type { BodyParserFn, CloneOptions, FetchFn, FetchFnInit, FetchFnUrl, FetchResult, StatusCode } from "./types.js";
+import type { AutoAbortKey, BodyParserFn, CloneOptions, FetchFn, FetchFnInit, FetchFnUrl, FetchResult, StatusCode } from "./types.js";
 import { hasHeader, setHeaders } from "./headers.js";
 
 /**
@@ -109,8 +109,8 @@ function textParser(response: Response) {
 export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abortable extends boolean = false> {
     #fetchFn: FetchFn;
     #customProcessors: [string | RegExp, (response: Response, stockParsers: { json: BodyParserFn<any>; text: BodyParserFn<string>; }) => Promise<any>][] = [];
-    #fetchImpl: Function;
-    #isAbortable: boolean = false;
+    #fetchImpl: (url: FetchFnUrl, init?: FetchFnInit) => Promise<any>;
+    #autoAbortMap: Map<AutoAbortKey, AbortController> | undefined;
 
     async #abortableFetch(url: FetchFnUrl, init?: FetchFnInit) {
         try {
@@ -178,6 +178,15 @@ export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abort
         this.#fetchImpl = this.#simpleFetch.bind(this);
     }
 
+    /**
+     * Gets a Boolean value indicating whether this fetcher object is in abortable mode or not.
+     * 
+     * **NOTE**:  Once in abortable mode, the fetcher object cannot be reverted to non-abortable mode.
+     */
+    get isAbortable() {
+        return !!this.#autoAbortMap;
+    }
+
     /**
      * Clones this fetcher object by creating a new fetcher object with the same data-fetching function, custom 
      * body processors, and data typing unless specified otherwise via the options parameter.
@@ -198,7 +207,7 @@ export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abort
         if (opts.includeProcessors) {
             newClone.#customProcessors = [...this.#customProcessors];
         }
-        if (opts.preserveAbortable && this.#isAbortable) {
+        if (opts.preserveAbortable && this.isAbortable) {
             newClone.abortable();
         }
         return newClone as DrFetch<TStatusCode, TInherit extends true ? T : unknown, CloneAbortable>;
@@ -281,7 +290,7 @@ export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abort
 
     abortable() {
         this.#fetchImpl = this.#abortableFetch.bind(this);
-        this.#isAbortable = true;
+        this.#autoAbortMap ??= new Map<AutoAbortKey, AbortController>();
         return this as DrFetch<TStatusCode, T, true>;
     }
 
@@ -292,11 +301,38 @@ 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.
      */
-    fetch(url: FetchFnUrl, init?: FetchFnInit) {
-        return this.#fetchImpl(url, init) as (Abortable extends true ? Promise<{
-            aborted: true;
-            error: DOMException;
-        } | T> : Promise<T>);
+    async fetch(url: FetchFnUrl, init?: FetchFnInit): Promise<(Abortable extends true ? {
+        aborted: true;
+        error: DOMException;
+    } | T : T)> {
+        if (!this.#autoAbortMap && init?.autoAbort) {
+            throw new Error('Cannot use autoAbort if the fetcher is not in abortable mode.  Call "abortable()" first.');
+        }
+        const autoAbort = {
+            key: typeof init?.autoAbort === 'object' ? init.autoAbort.key : init?.autoAbort,
+            delay: typeof init?.autoAbort === 'object' ? init.autoAbort.delay : undefined,
+        };
+        if (autoAbort.key) {
+            this.#autoAbortMap?.get(autoAbort.key)?.abort();
+            const ac = new AbortController();
+            this.#autoAbortMap!.set(autoAbort.key, ac);
+            init ??= {};
+            init.signal = ac.signal;
+            if (autoAbort.delay !== undefined) {
+                const aborted = await new Promise<boolean>((rs) => {
+                    setTimeout(() => rs(ac.signal.aborted), autoAbort.delay);
+                });
+                if (aborted) {
+                    // @ts-expect-error TS2322: A runtime check is in place to ensure that the type is correct.
+                    return {
+                        aborted: true,
+                        error: new DOMException('Aborted while delayed.', 'AbortError')
+                    };
+                }
+            }
+        }
+        return await this.#fetchImpl(url, init)
+            .finally(() => autoAbort.key && this.#autoAbortMap?.delete(autoAbort.key));
     }
 
     #createInit(body: BodyInit | null | Record<string, any> | undefined, init?: FetchFnInit) {
@@ -319,8 +355,7 @@ export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abort
      * @returns A response object with the HTTP response's `ok`, `status`, `statusText` and `body` properties.
      */
     get(url: URL | string, init?: Omit<FetchFnInit, 'method' | 'body'>) {
-        init = { ...init, method: 'GET' };
-        return this.fetch(url, init);
+        return this.fetch(url, { ...init, method: 'GET' });
     }
 
     /**
@@ -329,8 +364,7 @@ export class DrFetch<TStatusCode extends number = StatusCode, T = unknown, Abort
      * @returns A response object with the HTTP response's `ok`, `status`, `statusText` and `body` properties.
      */
     head(url: URL | string, init?: Omit<FetchFnInit, 'method' | 'body'>) {
-        init = { ...init, method: 'HEAD' };
-        return this.fetch(url, init);
+        return this.fetch(url, { ...init, method: 'HEAD' });
     }
 
     /**
diff --git a/src/tests/DrFetch.test.ts b/src/tests/DrFetch.test.ts
@@ -2,7 +2,7 @@ import { expect } from "chai";
 import { describe, test } from "mocha";
 import { fake } from 'sinon';
 import { DrFetch } from "../DrFetch.js";
-import type { StatusCode } from "../types.js";
+import type { FetchFnInit, FetchFnUrl, StatusCode } from "../types.js";
 import { getHeader } from "../headers.js";
 
 const shortcutMethodsWithBody = [
@@ -261,7 +261,99 @@ describe('DrFetch', () => {
                 // Assert.
                 expect(processorFn.calledOnce).to.be.true;
             });
-        })
+        });
+        test("Should throw and error if 'autoAbort' is used without calling 'abortable()'.", async () => {
+            // Arrange.
+            const fetchFn = fake.resolves(new Response(null));
+            const fetcher = new DrFetch(fetchFn);
+            let didThrow = false;
+
+            // Act.
+            try {
+                await fetcher.fetch('x', { autoAbort: 'abc' });
+            }
+            catch {
+                didThrow = true;
+            }
+
+            // Assert.
+            expect(didThrow).to.be.true;
+        });
+        test("Should not throw an error if 'autoAbort' is used with 'abortable()'.", async () => {
+            // Arrange.
+            const fetchFn = fake.resolves(new Response(null));
+            const fetcher = new DrFetch(fetchFn).abortable();
+            let didThrow = false;
+
+            // Act.
+            try {
+                await fetcher.fetch('x', { autoAbort: 'abc' });
+            }
+            catch {
+                didThrow = true;
+            }
+
+            // Assert.
+            expect(didThrow).to.be.false;
+        });
+        [
+            {
+                autoAbort: 'abc',
+                text: 'a string',
+            },
+            {
+                autoAbort: { key: 'abc' },
+                text: 'an object',
+            },
+        ].forEach(tc => {
+            test(`Should abort the previous HTTP request whenever 'autoAbort' is used as ${tc.text}.`, async () => {
+                // Arrange.
+                const fetchFn = fake((url: FetchFnUrl, init?: FetchFnInit) => new Promise<Response>((rs, rj) => setTimeout(() => {
+                    if (init?.signal?.aborted) {
+                        rj(new DOMException('Test:  Aborted.', 'AbortError'));
+                    }
+                    rs(new Response(null));
+                }, 0)));
+                const fetcher = new DrFetch(fetchFn).abortable().for<StatusCode, {}>();
+                const request1 = fetcher.fetch('x', { autoAbort: tc.autoAbort });
+                const request2 = fetcher.fetch('y', { autoAbort: tc.autoAbort });
+
+                // Act.
+                const response = await request1;
+
+                // Assert.
+                expect(fetchFn.calledTwice).to.be.true;
+                expect(response.aborted).to.be.true;
+                expect(response.aborted && response.error).to.be.instanceOf(DOMException);
+                expect(response.aborted && response.error.name).to.equal('AbortError');
+
+                // Clean up.
+                await request2;
+            });
+        });
+        test("Should delay the HTTP request whenever a delay is specified.", async () => {
+            // Arrange.
+            const fetchFn = fake((url: FetchFnUrl, init?: FetchFnInit) => new Promise<Response>((rs, rj) => setTimeout(() => {
+                if (init?.signal?.aborted) {
+                    rj(new DOMException('Test:  Aborted.', 'AbortError'));
+                }
+                rs(new Response(null));
+            }, 0)));
+            const fetcher = new DrFetch(fetchFn).abortable().for<StatusCode, {}>();
+            const request1 = fetcher.fetch('x', { autoAbort: { key: 'abc', delay: 0 } });
+            const request2 = fetcher.fetch('y', { autoAbort: { key: 'abc', delay: 0 } });
+            // Act.
+            const response = await request1;
+
+            // Assert.
+            expect(fetchFn.called, 'Fetch was called.').to.be.false;
+            expect(response.aborted, 'Response is not aborted.').to.be.true;
+            expect(response.aborted && response.error).to.be.instanceOf(DOMException);
+            expect(response.aborted && response.error.name).to.equal('AbortError');
+
+            // Clean up.
+            await request2;
+        });
     });
     describe('Shortcut Functions', () => {
         allShortcutMethods.map(x => ({
@@ -377,11 +469,11 @@ describe('DrFetch', () => {
                 const init = {
                     headers: { 'x-test': 'abc' },
                     signal: new AbortController().signal,
-                    mode: 'cors',
-                    credentials: 'include',
-                    redirect: 'follow',
+                    mode: 'cors' as const,
+                    credentials: 'include' as const,
+                    redirect: 'follow' as const,
                     referrer: 'test',
-                    referrerPolicy: 'no-referrer',
+                    referrerPolicy: 'no-referrer' as const,
                     integrity: 'sha256-abc'
                 };
 
diff --git a/src/types.ts b/src/types.ts
@@ -61,10 +61,33 @@ export type FetchFn = typeof fetch;
  */
 export type FetchFnUrl = Parameters<FetchFn>[0];
 
+/**
+ * Possible types of keys accepted by the `autoAbort` option.
+ */
+export type AutoAbortKey = string | symbol | number;
+
 /**
  * Type of the fetch function's init parameter.
  */
-export type FetchFnInit = Parameters<FetchFn>[1];
+export type FetchFnInit = Parameters<FetchFn>[1] & {
+    /**
+     * Specifies the options for auto-aborting the HTTP request.
+     * 
+     * If a string is provided, it will be used as the key for the abort signal; provide an object to specify further 
+     * options.
+     */
+    autoAbort?: AutoAbortKey | {
+        /**
+         * The key used to identify the abort signal.
+         */
+        key: AutoAbortKey;
+        /**
+         * The amount of time (in milliseconds) to wait before emitting the request. If not specified, then no delay 
+         * is applied.
+         */
+        delay?: number;
+    };
+};
 
 /**
  * Fetcher cloning options.
