@jaseeey/request-manager 2.0.4-alpha.2 → 2.1.1

package/README.md

@@ -14,7 +14,7 @@ Should you wish to extend the behaviour, or modify it for your own purposes, the
 
 ## Features
 
-- Prevents duplicate simultaneous requests to the same URL and method.
+- Prevents duplicate simultaneous requests to the same client instance, URL, and method.
 - Supports TypeScript for improved type safety and developer experience.
 - Allows for optional onSuccess and onError callbacks to handle responses.
 - Generates both CommonJS (CJS) and ECMAScript Module (ESM) distributions for broad compatibility.
@@ -31,52 +31,74 @@ npm install @jaseeey/request-manager
 
 Here's a basic example of how to use the RequestManager library:
 
-### With Callbacks
+### Recommended: Default Instance
 
 ```javascript
-import { RequestManager } from '@jaseeey/request-manager';
+import requestManager from '@jaseeey/request-manager';
 
 const client = axios.create();
 const url = 'https://example.com';
 const method = 'GET';
 
-RequestManager.call(client, method, url, null, null, res => {
-    // Handle your response here, any processing will only be run once.
-}, err => {
-    // Handle your error here
-});
+const response = await requestManager.call(client, method, url);
 ```
 
-### Without Callbacks
+### With Callbacks and Transforming Success Result
 
 ```javascript
-import { RequestManager } from '@jaseeey/request-manager';
+import requestManager from '@jaseeey/request-manager';
 
 const client = axios.create();
 const url = 'https://example.com';
-const method = 'GET';
 
-try {
-    const response = await RequestManager.call(client, method, url);
-    // Handle your response here, any processing will be run multiple times upon multiple requests.
-}
-catch (err) {
-    // Handle your error here
-}
+const result = await requestManager.call(
+    client,
+    'GET',
+    url,
+    {},
+    {},
+    res => res.data, // Returning a value changes the resolved result
+    err => {
+        // Handle your error here
+    }
+);
 ```
 
+### Creating Isolated Managers
+
+```javascript
+import { RequestManager } from '@jaseeey/request-manager';
+
+const client = axios.create();
+const scopedRequestManager = new RequestManager();
+
+const response = await scopedRequestManager.call(client, 'GET', 'https://example.com');
+```
+
+### Legacy Static API (Backward Compatibility)
+
+```javascript
+import { RequestManager } from '@jaseeey/request-manager';
+
+const response = await RequestManager.call(client, 'GET', 'https://example.com');
+```
+
+`RequestManager.call(...)` is supported for backward compatibility, but the default instance API is recommended.
+
 ## API Reference
 
-### `call(client, method, url, data, config, onSuccess, onError)`
+### `requestManager.call(client, method, url, data, config, onSuccess, onError)`
 
 - `client`: The HTTP client instance used for making requests.
 - `method`: The HTTP method (e.g., 'GET', 'POST').
 - `url`: The URL to which the request is sent.
 - `data` (optional): The data to be sent as the request body.
 - `config` (optional): The configuration options for the request.
-- `onSuccess` (optional): A callback function that is called when the request is successful.
+- `onSuccess` (optional): A callback function that is called when the request is successful. Returning a non-`undefined` value from this callback changes the resolved value of the `call()` promise.
 - `onError` (optional): A callback function that is called when the request fails.
 
+`RequestManager.call(...)` is also available as a static compatibility API and delegates to the shared default instance.
+
 ## Known Limitations
 
 ### Unified Callback Execution
@@ -89,7 +111,7 @@ Given that only the first set of callbacks are executed, managing state updates
 
 ### Request Differentiation
 
-The system identifies duplicate requests based solely on URL and method, potentially overlooking requests that differ in headers, query parameters, or POST bodies. Applications requiring differentiation based on these factors may need to extend the key generation logic within the RequestManager.
+The system identifies duplicate requests based on client instance, URL, and method, but still overlooks differences in headers, query parameters, or POST bodies for otherwise matching requests. Applications requiring differentiation based on those fields may need to extend the key generation logic within the RequestManager.
 
 ### Lifecycle Management
 

package/dist/cjs/request-manager/request-manager.d.ts

@@ -1,8 +1,9 @@
 import { AxiosInstance, AxiosRequestConfig, AxiosResponse, Method } from 'axios';
 type RequestKey = string;
-interface RequestPromise<T = any> {
-    original: Promise<AxiosResponse<T, any>>;
-    processed: Promise<AxiosResponse<T, any> | void>;
+type MaybePromise<T> = T | Promise<T>;
+interface RequestPromise {
+    original: Promise<AxiosResponse<unknown>>;
+    processed: Promise<unknown>;
 }
 /**
  * RequestManager
@@ -11,20 +12,39 @@ interface RequestPromise<T = any> {
  * concurrently. When a request to a specific URL and method is in progress, subsequent requests to the same URL and
  * method will return the same promise, preventing duplicate requests.
  */
-declare class RequestManager<T = any> {
+export declare class RequestManager<T = any> {
     /**
-     * A Map to store active requests, with each key being a combination of URL and HTTP method and its corresponding
-     * value being the Promise of the ongoing HTTP request.
+     * A Map to store active requests, with each key being a combination of client instance, URL, and HTTP method and
+     * its corresponding value being the Promise of the ongoing HTTP request.
      */
-    activeRequests: Map<RequestKey, RequestPromise<T>>;
+    activeRequests: Map<RequestKey, RequestPromise>;
+    private clientIds;
+    private nextClientId;
     /**
-     * Executes or retrieves an ongoing HTTP request based on the provided URL, method, payload, and configuration. It
-     * de-duplicates requests to the same URL with the same method by returning a previously stored promise if available.
-     * Upon completion of the request, it optionally invokes an onSuccess callback if the request is successful, or an
-     * onFailure callback if the request fails.
+     * Backward-compatible static API that delegates to the shared singleton instance.
+     *
+     * @deprecated Prefer the default exported instance (`requestManager.call(...)`).
      */
-    call(client: AxiosInstance, method: Method, url: string, data?: any, config?: AxiosRequestConfig | null, onSuccess?: ((result: AxiosResponse) => void) | null, onError?: ((error: any) => void) | null): Promise<AxiosResponse | void>;
+    static call<TResponse = any, TSuccess = never>(client: AxiosInstance, method: Method, url: string, data?: any, config?: AxiosRequestConfig | null, onSuccess?: ((result: AxiosResponse<TResponse>) => MaybePromise<TSuccess | undefined>) | null, onError?: ((error: unknown) => void) | null): Promise<AxiosResponse<TResponse> | TSuccess | void>;
+    /**
+     * Executes or retrieves an ongoing HTTP request based on the provided URL, method, payload, and configuration.
+     *
+     * Requests are de-duplicated only when they target the same client instance, method, and URL.
+     * If `onSuccess` returns a non-`undefined` value, that value becomes the resolved result.
+     *
+     * @param client Axios client used to execute the request.
+     * @param method HTTP method.
+     * @param url Target request URL.
+     * @param data Optional request payload.
+     * @param config Optional Axios request configuration.
+     * @param onSuccess Optional callback invoked on success. Returning a value overrides the resolved response.
+     * @param onError Optional callback invoked on error. If provided, the promise resolves to `void` after handling.
+     */
+    call<TResponse = T, TSuccess = never>(client: AxiosInstance, method: Method, url: string, data?: any, config?: AxiosRequestConfig | null, onSuccess?: ((result: AxiosResponse<TResponse>) => MaybePromise<TSuccess | undefined>) | null, onError?: ((error: unknown) => void) | null): Promise<AxiosResponse<TResponse> | TSuccess | void>;
+    /**
+     * Creates a stable in-memory key for de-duplication within this manager instance.
+     */
+    private buildRequestKey;
 }
 declare const requestManager: RequestManager<any>;
-export { RequestManager };
 export default requestManager;

package/dist/cjs/request-manager/request-manager.js

@@ -10,20 +10,38 @@ exports.RequestManager = void 0;
  */
 class RequestManager {
     /**
-     * A Map to store active requests, with each key being a combination of URL and HTTP method and its corresponding
-     * value being the Promise of the ongoing HTTP request.
+     * A Map to store active requests, with each key being a combination of client instance, URL, and HTTP method and
+     * its corresponding value being the Promise of the ongoing HTTP request.
      */
     activeRequests = new Map();
+    clientIds = new WeakMap();
+    nextClientId = 1;
     /**
-     * Executes or retrieves an ongoing HTTP request based on the provided URL, method, payload, and configuration. It
-     * de-duplicates requests to the same URL with the same method by returning a previously stored promise if available.
-     * Upon completion of the request, it optionally invokes an onSuccess callback if the request is successful, or an
-     * onFailure callback if the request fails.
+     * Backward-compatible static API that delegates to the shared singleton instance.
+     *
+     * @deprecated Prefer the default exported instance (`requestManager.call(...)`).
+     */
+    static call(client, method, url, data = {}, config = {}, onSuccess, onError) {
+        return requestManager.call(client, method, url, data, config, onSuccess, onError);
+    }
+    /**
+     * Executes or retrieves an ongoing HTTP request based on the provided URL, method, payload, and configuration.
+     *
+     * Requests are de-duplicated only when they target the same client instance, method, and URL.
+     * If `onSuccess` returns a non-`undefined` value, that value becomes the resolved result.
+     *
+     * @param client Axios client used to execute the request.
+     * @param method HTTP method.
+     * @param url Target request URL.
+     * @param data Optional request payload.
+     * @param config Optional Axios request configuration.
+     * @param onSuccess Optional callback invoked on success. Returning a value overrides the resolved response.
+     * @param onError Optional callback invoked on error. If provided, the promise resolves to `void` after handling.
      */
     async call(client, method, url, data = {}, config = {}, onSuccess, onError) {
         data ??= {};
         config ??= {};
-        const key = `${method.toLowerCase()}:${url}`;
+        const key = this.buildRequestKey(client, method, url);
         if (this.activeRequests.has(key)) {
             return this.activeRequests.get(key).processed;
         }
@@ -31,7 +49,7 @@ class RequestManager {
             try {
                 const requestResult = await responsePromise;
                 const callbackResult = onSuccess && typeof onSuccess === 'function'
-                    ? onSuccess(requestResult)
+                    ? await onSuccess(requestResult)
                     : undefined;
                 return callbackResult !== undefined
                     ? callbackResult
@@ -52,8 +70,18 @@ class RequestManager {
         this.activeRequests.set(key, { original: requestPromise, processed: processedPromise });
         return processedPromise;
     }
+    /**
+     * Creates a stable in-memory key for de-duplication within this manager instance.
+     */
+    buildRequestKey(client, method, url) {
+        let clientId = this.clientIds.get(client);
+        if (!clientId) {
+            clientId = this.nextClientId++;
+            this.clientIds.set(client, clientId);
+        }
+        return `${clientId}:${method.toLowerCase()}:${url}`;
+    }
 }
 exports.RequestManager = RequestManager;
-// Create default instance
 const requestManager = new RequestManager();
 exports.default = requestManager;

package/dist/esm/request-manager/request-manager.d.ts

@@ -1,8 +1,9 @@
 import { AxiosInstance, AxiosRequestConfig, AxiosResponse, Method } from 'axios';
 type RequestKey = string;
-interface RequestPromise<T = any> {
-    original: Promise<AxiosResponse<T, any>>;
-    processed: Promise<AxiosResponse<T, any> | void>;
+type MaybePromise<T> = T | Promise<T>;
+interface RequestPromise {
+    original: Promise<AxiosResponse<unknown>>;
+    processed: Promise<unknown>;
 }
 /**
  * RequestManager
@@ -11,20 +12,39 @@ interface RequestPromise<T = any> {
  * concurrently. When a request to a specific URL and method is in progress, subsequent requests to the same URL and
  * method will return the same promise, preventing duplicate requests.
  */
-declare class RequestManager<T = any> {
+export declare class RequestManager<T = any> {
     /**
-     * A Map to store active requests, with each key being a combination of URL and HTTP method and its corresponding
-     * value being the Promise of the ongoing HTTP request.
+     * A Map to store active requests, with each key being a combination of client instance, URL, and HTTP method and
+     * its corresponding value being the Promise of the ongoing HTTP request.
      */
-    activeRequests: Map<RequestKey, RequestPromise<T>>;
+    activeRequests: Map<RequestKey, RequestPromise>;
+    private clientIds;
+    private nextClientId;
     /**
-     * Executes or retrieves an ongoing HTTP request based on the provided URL, method, payload, and configuration. It
-     * de-duplicates requests to the same URL with the same method by returning a previously stored promise if available.
-     * Upon completion of the request, it optionally invokes an onSuccess callback if the request is successful, or an
-     * onFailure callback if the request fails.
+     * Backward-compatible static API that delegates to the shared singleton instance.
+     *
+     * @deprecated Prefer the default exported instance (`requestManager.call(...)`).
      */
-    call(client: AxiosInstance, method: Method, url: string, data?: any, config?: AxiosRequestConfig | null, onSuccess?: ((result: AxiosResponse) => void) | null, onError?: ((error: any) => void) | null): Promise<AxiosResponse | void>;
+    static call<TResponse = any, TSuccess = never>(client: AxiosInstance, method: Method, url: string, data?: any, config?: AxiosRequestConfig | null, onSuccess?: ((result: AxiosResponse<TResponse>) => MaybePromise<TSuccess | undefined>) | null, onError?: ((error: unknown) => void) | null): Promise<AxiosResponse<TResponse> | TSuccess | void>;
+    /**
+     * Executes or retrieves an ongoing HTTP request based on the provided URL, method, payload, and configuration.
+     *
+     * Requests are de-duplicated only when they target the same client instance, method, and URL.
+     * If `onSuccess` returns a non-`undefined` value, that value becomes the resolved result.
+     *
+     * @param client Axios client used to execute the request.
+     * @param method HTTP method.
+     * @param url Target request URL.
+     * @param data Optional request payload.
+     * @param config Optional Axios request configuration.
+     * @param onSuccess Optional callback invoked on success. Returning a value overrides the resolved response.
+     * @param onError Optional callback invoked on error. If provided, the promise resolves to `void` after handling.
+     */
+    call<TResponse = T, TSuccess = never>(client: AxiosInstance, method: Method, url: string, data?: any, config?: AxiosRequestConfig | null, onSuccess?: ((result: AxiosResponse<TResponse>) => MaybePromise<TSuccess | undefined>) | null, onError?: ((error: unknown) => void) | null): Promise<AxiosResponse<TResponse> | TSuccess | void>;
+    /**
+     * Creates a stable in-memory key for de-duplication within this manager instance.
+     */
+    private buildRequestKey;
 }
 declare const requestManager: RequestManager<any>;
-export { RequestManager };
 export default requestManager;

package/dist/esm/request-manager/request-manager.js

@@ -5,22 +5,40 @@
  * concurrently. When a request to a specific URL and method is in progress, subsequent requests to the same URL and
  * method will return the same promise, preventing duplicate requests.
  */
-class RequestManager {
+export class RequestManager {
     /**
-     * A Map to store active requests, with each key being a combination of URL and HTTP method and its corresponding
-     * value being the Promise of the ongoing HTTP request.
+     * A Map to store active requests, with each key being a combination of client instance, URL, and HTTP method and
+     * its corresponding value being the Promise of the ongoing HTTP request.
      */
     activeRequests = new Map();
+    clientIds = new WeakMap();
+    nextClientId = 1;
     /**
-     * Executes or retrieves an ongoing HTTP request based on the provided URL, method, payload, and configuration. It
-     * de-duplicates requests to the same URL with the same method by returning a previously stored promise if available.
-     * Upon completion of the request, it optionally invokes an onSuccess callback if the request is successful, or an
-     * onFailure callback if the request fails.
+     * Backward-compatible static API that delegates to the shared singleton instance.
+     *
+     * @deprecated Prefer the default exported instance (`requestManager.call(...)`).
+     */
+    static call(client, method, url, data = {}, config = {}, onSuccess, onError) {
+        return requestManager.call(client, method, url, data, config, onSuccess, onError);
+    }
+    /**
+     * Executes or retrieves an ongoing HTTP request based on the provided URL, method, payload, and configuration.
+     *
+     * Requests are de-duplicated only when they target the same client instance, method, and URL.
+     * If `onSuccess` returns a non-`undefined` value, that value becomes the resolved result.
+     *
+     * @param client Axios client used to execute the request.
+     * @param method HTTP method.
+     * @param url Target request URL.
+     * @param data Optional request payload.
+     * @param config Optional Axios request configuration.
+     * @param onSuccess Optional callback invoked on success. Returning a value overrides the resolved response.
+     * @param onError Optional callback invoked on error. If provided, the promise resolves to `void` after handling.
      */
     async call(client, method, url, data = {}, config = {}, onSuccess, onError) {
         data ??= {};
         config ??= {};
-        const key = `${method.toLowerCase()}:${url}`;
+        const key = this.buildRequestKey(client, method, url);
         if (this.activeRequests.has(key)) {
             return this.activeRequests.get(key).processed;
         }
@@ -28,7 +46,7 @@ class RequestManager {
             try {
                 const requestResult = await responsePromise;
                 const callbackResult = onSuccess && typeof onSuccess === 'function'
-                    ? onSuccess(requestResult)
+                    ? await onSuccess(requestResult)
                     : undefined;
                 return callbackResult !== undefined
                     ? callbackResult
@@ -49,9 +67,17 @@ class RequestManager {
         this.activeRequests.set(key, { original: requestPromise, processed: processedPromise });
         return processedPromise;
     }
+    /**
+     * Creates a stable in-memory key for de-duplication within this manager instance.
+     */
+    buildRequestKey(client, method, url) {
+        let clientId = this.clientIds.get(client);
+        if (!clientId) {
+            clientId = this.nextClientId++;
+            this.clientIds.set(client, clientId);
+        }
+        return `${clientId}:${method.toLowerCase()}:${url}`;
+    }
 }
-// Create default instance
 const requestManager = new RequestManager();
-// Export both the class and the default instance
-export { RequestManager };
 export default requestManager;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jaseeey/request-manager",
-    "version": "2.0.4-alpha.2",
+    "version": "2.1.1",
     "description": "A library to prevent multiple API requests when called simultaneously",
     "license": "MIT",
     "author": "Jason Ilicic <me@jasey.io>",
@@ -16,22 +16,21 @@
         "dist"
     ],
     "scripts": {
+        "prebuild": "rm -rf dist",
         "build:esm": "tsc -p tsconfig.esm.json && echo '{\"type\": \"module\"}' > dist/esm/package.json",
         "build:cjs": "tsc -p tsconfig.cjs.json && echo '{\"type\": \"commonjs\"}' > dist/cjs/package.json",
         "build": "npm run build:esm && npm run build:cjs",
-        "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+        "prepack": "npm run build",
+        "test": "vitest run --coverage"
     },
     "dependencies": {
-        "axios": "^1.11.0"
+        "axios": "^1.13.6"
     },
     "devDependencies": {
-        "@jest/globals": "^29.7.0",
-        "@types/axios": "^0.14.0",
-        "@types/jest": "^29.5.14",
+        "@vitest/coverage-v8": "^4.0.18",
         "braces": "^3.0.3",
-        "jest": "^29.7.0",
-        "ts-jest": "^29.2.5",
-        "typescript": "^5.7.2"
+        "typescript": "^5.9.3",
+        "vitest": "^4.0.18"
     },
     "main": "./dist/cjs/index.js",
     "module": "./dist/esm/index.js",