@jaseeey/request-manager 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Jason Ilicic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# RequestManager
+
+## Overview
+
+RequestManager is a JavaScript library designed to manage and regulate HTTP requests efficiently. It ensures that multiple requests to the same URL with the same method are not made concurrently, thus preventing duplicate requests. 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.
+
+## Background and Scope
+
+The RequestManager library was specifically written to address a particular issue encountered in my projects. It was not designed or intended to serve as a comprehensive request management solution. Instead, its primary aim is to tackle the specific challenges I faced, offering a targeted approach to prevent duplicate requests and manage HTTP calls more efficiently.
+
+Given its focused nature, there are a set of known limitations that have been accepted, as these constraints do not affect the scenarios for which the library was developed. While the library provides a solution to the identified issues, its functionality may not cover all use cases or requirements that might be expected from a full-fledged request manager.
+
+Users are encouraged to understand these known limitations and consider how they align with their specific needs before integrating the library into their projects.
+
+Should you wish to extend the behaviour, or modify it for your own purposes, then you are free to do so.
+
+## Features
+
+- Prevents duplicate simultaneous requests to the same URL and method.
+- Supports optional onSuccess and onError callbacks for regulated response handling.
+- Easy integration with any project that uses HTTP requests via Axios.
+
+## Usage
+
+Here's a basic example of how to use the RequestManager library:
+
+### With Callbacks
+
+```javascript
+import RequestManager from '@jaseeey/request-manager';
+
+const client = axios.create();
+const url = 'https://example.com';
+const method = 'GET';
+
+RequestManager.call(client, method, url).then(res => {
+    // Handle your response here, any processing will only be run once.
+}).catch(err => {
+    // Handle your error here
+});
+```
+
+### Without Callbacks
+
+```javascript
+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
+}
+```
+
+## API Reference
+
+### `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.
+- `onError` (optional): A callback function that is called when the request fails.
+
+## Known Limitations
+
+### Unified Callback Execution
+
+The RequestManager executes only the `onSuccess` or `onError` callbacks of the first request in the case of identical requests made concurrently. This design choice optimises network and computational resources but may limit individual response handling flexibility. Though, you could simply bypass the use of the callbacks and handle each response independently.
+
+### State and Error Handling
+
+Given that only the first set of callbacks are executed, managing state updates or performing granular error handling based on different parts of the application's needs could be challenging. This approach assumes a uniform handling strategy for success and error responses.
+
+### 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.
+
+### Lifecycle Management
+
+The centralised management of requests might complicate the handling of component lifecycles, such as cancelling requests when components unmount, especially in scenarios where multiple components depend on the outcome of a single request.
+
+### Singleton Design
+The RequestManager is implemented as a singleton, which inherently restricts the creation of multiple instances of the class. This design choice aligns with the library's goal to centrally manage and de-duplicate HTTP requests across the application. While this meets the requirements for which the library was developed, it may pose a limitation for scenarios where multiple, isolated request managers are needed. Users should consider this design aspect when planning to integrate the library into their applications, especially if there's a potential need for managing requests in isolated contexts.
+
+## Contributing
+
+Contributions to the RequestManager library are welcome. If you have suggestions or improvements, feel free to fork the repository and submit a pull request.
+
+## License
+
+RequestManager is released under the [MIT License](LICENSE).

package/index.js

@@ -0,0 +1,3 @@
+import RequestManager from './request-manager.js';
+
+export { RequestManager };

package/jest.config.mjs

@@ -0,0 +1,9 @@
+export default {
+    clearMocks: true,
+    collectCoverage: true,
+    coverageDirectory: 'coverage',
+    coverageProvider: 'v8',
+    setupFiles: [],
+    testEnvironment: 'node',
+    transform: {}
+};

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@jaseeey/request-manager",
+  "type": "module",
+  "version": "1.0.0",
+  "description": "A library to prevent multiple API requests when called simultaneously",
+  "main": "request-manager.js",
+  "license": "MIT",
+  "author": "Jason Ilicic <me@jasey.io>",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/jaseeey/request-manager.git"
+  },
+  "bugs": {
+    "url": "https://github.com/jaseeey/request-manager/issues"
+  },
+  "homepage": "https://github.com/jaseeey/request-manager#readme",
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js"
+  },
+  "devDependencies": {
+    "@jest/globals": "^29.7.0",
+    "jest": "^29.7.0"
+  }
+}

package/request-manager.js

@@ -0,0 +1,67 @@
+/**
+ * RequestManager
+ *
+ * Manages and regulates HTTP requests to ensure that multiple requests to the same URL and method are not made
+ * 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 {
+
+    /**
+     * 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.
+     *
+     * @type {Map<string, Promise>}
+     */
+    activeRequests = new Map();
+
+    /**
+     * 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.
+     *
+     * @param {AxiosInstance} client
+     * @param {string} method
+     * @param {string} url
+     * @param {Object|null} [data=null]
+     * @param {Object|null} [config=null]
+     * @param {Function|null} [onSuccess=null]
+     * @param {Function|null} [onError=null]
+     * @returns {Promise}
+     */
+    async call(client, method, url, data = null, config = null, onSuccess = null, onError = null) {
+        data ??= {};
+        config ??= {};
+        const key = `${method.toLowerCase()}:${url}`;
+        if (this.activeRequests.has(key)) {
+            return this.activeRequests.get(key).processed;
+        }
+        const processRequest = async (responsePromise) => {
+            try {
+                const requestResult = await responsePromise;
+                const callbackResult = onSuccess && typeof onSuccess === 'function'
+                    ? onSuccess(requestResult)
+                    : undefined;
+                return callbackResult !== undefined
+                    ? callbackResult
+                    : requestResult;
+            }
+            catch (err) {
+                if (onError && typeof onError === 'function') {
+                    onError(err);
+                    return;
+                }
+                throw err;
+            }
+        };
+        const requestPromise = client.request({ ...config, method, url, data }).finally(() => {
+            this.activeRequests.delete(key);
+        });
+        const processedPromise = processRequest(requestPromise);
+        this.activeRequests.set(key, { original: requestPromise, processed: processedPromise });
+        return processedPromise;
+    }
+}
+
+export default new RequestManager();

package/test/request-manager.spec.js

@@ -0,0 +1,97 @@
+import RequestManager from '../request-manager.js';
+import { afterEach, beforeEach, describe, expect, jest, test } from '@jest/globals';
+
+describe('RequestManager', () => {
+
+    let mockClient;
+
+    const mockURL1 = 'https://example.com';
+    const mockURL2 = 'https://example2.com';
+    const mockResponse1 = { data: 'response' };
+    const mockResponse2 = { data: 'response2' };
+
+    beforeEach(() => {
+        const mockRequests = new Map([
+            [ mockURL1, mockResponse1 ],
+            [ mockURL2, mockResponse2 ]
+        ]);
+        mockClient = {
+            request: jest.fn().mockImplementation(({ url }) => {
+                if (mockRequests.has(url)) {
+                    return Promise.resolve(mockRequests.get(url));
+                }
+                return Promise.reject(new Error('Mock URL not registered'));
+            })
+        };
+    });
+
+    afterEach(() => {
+        RequestManager.activeRequests.clear();
+    });
+
+    test('prevents duplicate simultaneous requests', async () => {
+        const [ firstResponse, secondResponse, thirdResponse ] = await Promise.all([
+            RequestManager.call(mockClient, 'GET', mockURL1),
+            RequestManager.call(mockClient, 'GET', mockURL1),
+            RequestManager.call(mockClient, 'GET', mockURL1)
+        ]);
+        expect(mockClient.request).toHaveBeenCalledTimes(1);
+        expect(firstResponse).toBe(secondResponse);
+        expect(firstResponse).toBe(thirdResponse);
+        expect(RequestManager.activeRequests.has(`post:${ mockURL1 }`)).toBeFalsy();
+    });
+
+    test('handles different requests independently', async () => {
+        const [ firstResponse, secondResponse, thirdResponse ] = await Promise.all([
+            RequestManager.call(mockClient, 'GET', mockURL1),
+            RequestManager.call(mockClient, 'GET', mockURL2),
+            RequestManager.call(mockClient, 'GET', mockURL2)
+        ])
+        expect(firstResponse).toBe(mockResponse1);
+        expect(secondResponse).toBe(mockResponse2);
+        expect(secondResponse).toBe(thirdResponse);
+        expect(mockClient.request).toHaveBeenCalledTimes(2);
+    });
+
+    test('calls onSuccess callback on successful request', async () => {
+        const onSuccessCb = jest.fn();
+        await RequestManager.call(mockClient, 'GET', mockURL1, null, null, onSuccessCb);
+        expect(onSuccessCb).toHaveBeenCalledWith(mockResponse1);
+    });
+
+    test('calls onError callback on request failure', async () => {
+        const error = new Error('Request failed');
+        mockClient.request.mockRejectedValueOnce(error);
+        const onErrorCb = jest.fn();
+        await RequestManager.call(mockClient, 'GET', mockURL1, null, null, null, onErrorCb);
+        expect(onErrorCb).toHaveBeenCalledWith(error);
+    });
+
+    test('returns the response when no callbacks are provided', async () => {
+        const result = await RequestManager.call(mockClient, 'GET', mockURL1);
+        expect(result).toBe(mockResponse1);
+    });
+
+    test('throws an error when the request fails and no onError callback is provided', async () => {
+        const error = new Error('Request failed');
+        mockClient.request.mockRejectedValueOnce(error);
+        await expect(RequestManager.call(mockClient, 'GET', mockURL1)).rejects.toThrow(error);
+    });
+
+    test('allows a new request after the previous one completes', async () => {
+        await RequestManager.call(mockClient, 'GET', mockURL1);
+        mockClient.request.mockClear();
+        await RequestManager.call(mockClient, 'GET', mockURL1);
+        expect(mockClient.request).toHaveBeenCalledTimes(1);
+    });
+
+    test('handles requests with case-insensitive method', async () => {
+        const [ firstResponse, secondResponse ] = await Promise.all([
+            RequestManager.call(mockClient, 'gET', mockURL1),
+            RequestManager.call(mockClient, 'gEt', mockURL1)
+        ])
+        expect(firstResponse).toBe(mockResponse1);
+        expect(secondResponse).toBe(secondResponse);
+        expect(mockClient.request).toHaveBeenCalledTimes(1);
+    });
+});