refactor: Replace queue manager with inflight manager for request handling; add timeNow utility for consistent timestamping

Author: MattCCC

src/cache-manager.ts

@@ -8,7 +8,7 @@ import type {
 } from './types/request-handler';
 import type { CacheEntry, MutationSettings } from './types/cache-manager';
 import { GET, STRING, UNDEFINED } from './constants';
-import { isObject, shallowSerialize, sortObject } from './utils';
+import { isObject, shallowSerialize, sortObject, timeNow } from './utils';
 import { revalidate } from './revalidator-manager';
 import { notifySubscribers } from './pubsub-manager';
 import type { DefaultPayload, DefaultParams, DefaultUrlParams } from './types';
@@ -158,7 +158,7 @@ function isCacheExpired(timestamp: number, maxStaleTime?: number): boolean {
   }
 
   // Check if the current time exceeds the timestamp by more than maxStaleTime seconds
-  return Date.now() - timestamp > maxStaleTime * 1000;
+  return timeNow() - timestamp > maxStaleTime * 1000;
 }
 
 /**
@@ -194,7 +194,7 @@ export function getCache<T>(
 export function setCache<T = unknown>(key: string, response: T): void {
   const cacheEntry: CacheEntry<T> = {
     data: response,
-    timestamp: Date.now(),
+    timestamp: timeNow(),
   };
 
   _cache.set(key, cacheEntry);

src/index.ts

@@ -24,7 +24,7 @@ export { createApiFetcher } from './api-handler';
 
 export { subscribe } from './pubsub-manager';
 
-export { abortRequest, getInFlightPromise } from './queue-manager';
+export { abortRequest, getInFlightPromise } from './inflight-manager';
 
 export {
   generateCacheKey,

src/inflight-manager.ts

@@ -1,52 +1,190 @@
 /**
  * @module inflight-manager
  *
- * Manages the "in-flight" state of asynchronous operations identified by a key.
+ * Manages in-flight asynchronous requests using unique keys to enable deduplication and cancellation.
+ *
+ * Provides utilities for:
+ * - Deduplication of requests within a configurable time window (`dedupeTime`)
+ * - Timeout management and automatic request abortion
+ * - AbortController lifecycle and cancellation logic
+ * - Concurrency control and request state tracking
+ * - In-flight promise deduplication to prevent duplicate network calls
  *
- * Provides utilities to mark a key as in-flight, unmark it, check its state,
- * subscribe to in-flight state changes, and execute functions with automatic
- * in-flight state management to prevent duplicate requests.
  * @remarks
+ * - Requests with the same key within the deduplication interval share the same AbortController and in-flight promise.
+ * - Supports cancellation of previous requests when a new one with the same key is issued, if `isCancellable` is enabled.
+ * - Timeout logic ensures requests are aborted after a specified duration, if enabled.
+ * - Internal queue state is managed via a Map, keyed by request identifier.
  * - Polled requests are also marked as "in-flight" to prevent duplicate requests.
- * - We use a Set and the isInFlight() check to track in-flight requests, instead of updating the cache directly with setCache(), to avoid affecting the cache's persistent data.
  */
 
-import { notifySubscribers } from './pubsub-manager';
+import { ABORT_ERROR, TIMEOUT_ERROR } from './constants';
+import type { InFlightItem } from './types/inflight-manager';
+import { timeNow } from './utils';
+
+const inFlight: Map<string, InFlightItem> = new Map();
+
+/**
+ * Adds a request to the queue if it's not already being processed within the dedupeTime interval.
+ *
+ * @param {string | null} key - Unique key for the request (e.g. cache key).
+ * @param {string} url - The request URL (for error messages/timeouts).
+ * @param {number} timeout - Timeout in milliseconds for the request.
+ * @param {number} dedupeTime - Deduplication time in milliseconds.
+ * @param {boolean} isCancellable - If true, then the previous request with same configuration should be aborted.
+ * @param {boolean} isTimeoutEnabled - Whether timeout is enabled.
+ * @returns {Promise<AbortController>} - A promise that resolves to an AbortController.
+ */
+export async function markInFlight(
+  key: string | null,
+  url: string,
+  timeout: number | undefined,
+  dedupeTime: number = 0,
+  isCancellable: boolean = false,
+  isTimeoutEnabled: boolean = true,
+): Promise<AbortController> {
+  if (!key) {
+    return new AbortController();
+  }
+
+  const item = inFlight.get(key);
+
+  if (item) {
+    const prevIsCancellable = item[3];
+    const previousController = item[0];
+    const timeoutId = item[1];
+
+    // If the request is already in the queue and within the dedupeTime, reuse the existing controller
+    if (!prevIsCancellable && dedupeTime && timeNow() - item[2] < dedupeTime) {
+      return previousController;
+    }
+
+    // If the request is too old, remove it and proceed to add a new one
+    // Abort previous request, if applicable, and continue as usual
+    if (prevIsCancellable) {
+      previousController.abort(
+        new DOMException('Aborted due to new request', ABORT_ERROR),
+      );
+    }
+
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+    }
+
+    inFlight.delete(key);
+  }
+
+  const controller = new AbortController();
+
+  const timeoutId = isTimeoutEnabled
+    ? setTimeout(() => {
+        const error = new DOMException(
+          `${url} aborted due to timeout`,
+          TIMEOUT_ERROR,
+        );
+
+        abortRequest(key, error);
+      }, timeout)
+    : null;
+
+  inFlight.set(key, [controller, timeoutId, timeNow(), isCancellable]);
+
+  return controller;
+}
+
+/**
+ * Removes a request from the queue and clears its timeout.
+ *
+ * @param key - Unique key for the request.
+ * @param {boolean} error - Error payload so to force the request to abort.
+ */
+export async function abortRequest(
+  key: string | null,
+  error: DOMException | null | string = null,
+): Promise<void> {
+  // If the key is not in the queue, there's nothing to remove
+  if (!key) {
+    return;
+  }
+
+  const item = inFlight.get(key);
 
-const inFlight = new Set<string>();
+  if (item) {
+    const controller = item[0];
+    const timeoutId = item[1];
 
-export function markInFlight(key: string) {
-  inFlight.add(key);
+    // If the request is not yet aborted, abort it with the provided error
+    if (error && !controller.signal.aborted) {
+      controller.abort(error);
+    }
 
-  notifySubscribers(key, { isFetching: true });
+    if (timeoutId !== null) {
+      clearTimeout(timeoutId);
+    }
+
+    inFlight.delete(key);
+  }
 }
 
-export function unmarkInFlight(key: string) {
-  inFlight.delete(key);
+/**
+ * Gets the AbortController for a request key.
+ *
+ * @param key - Unique key for the request.
+ * @returns {AbortController | undefined} - The AbortController or undefined.
+ */
+export async function getController(
+  key: string,
+): Promise<AbortController | undefined> {
+  const item = inFlight.get(key);
+
+  return item?.[0];
 }
 
-export function isInFlight(key: string) {
-  return inFlight.has(key);
+/**
+ * Adds helpers for in-flight promise deduplication.
+ *
+ * @param key - Unique key for the request.
+ * @param promise - The promise to store.
+ */
+export function setInFlightPromise(
+  key: string,
+  promise: Promise<unknown>,
+): void {
+  const item = inFlight.get(key);
+  if (item) {
+    // store the promise at index 4
+    item[4] = promise;
+
+    inFlight.set(key, item);
+  }
 }
 
 /**
- * Executes a function while marking a key as in-flight.
- * This is useful for preventing duplicate requests for the same resource.
+ * Retrieves the in-flight promise for a request key if it exists and is within the dedupeTime interval.
  *
- * @param {string} key - The key to mark as in-flight.
- * @param {() => T} fn - The function to execute.
- * @returns {Promise<T>} - The result of the function execution.
+ * @param key - Unique key for the request.
+ * @param dedupeTime - Deduplication time in milliseconds.
+ * @returns {Promise<T> | null} - The in-flight promise or null.
  */
-export async function withInFlight<T>(key: string, fn: () => T): Promise<T> {
+export function getInFlightPromise<T = unknown>(
+  key: string | null,
+  dedupeTime: number,
+): Promise<T> | null {
   if (!key) {
-    return fn();
+    return null;
   }
 
-  markInFlight(key);
+  const item = inFlight.get(key);
 
-  try {
-    return fn();
-  } finally {
-    unmarkInFlight(key);
+  if (
+    item &&
+    item[4] &&
+    timeNow() - item[2] < dedupeTime &&
+    // If one request is cancelled, ALL deduped requests get cancelled
+    !item[0].signal.aborted
+  ) {
+    return item[4] as Promise<T>;
   }
+
+  return null;
 }