@enegalan/request-manager 1.0.3 → 1.1.0

package/README.md

@@ -3,15 +3,15 @@
 [![npm version](https://img.shields.io/npm/v/@enegalan/request-manager.svg)](https://www.npmjs.com/package/@enegalan/request-manager)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-RequestManager is a JavaScript library designed to manage and regulate HTTP requests efficiently. It allows you to use HTTP calls from any library (ajax, Ext.Ajax, axios, fetch, etc.) by accepting Promises as parameters.
+RequestManager is a JavaScript library designed to manage and regulate HTTP requests efficiently. It cancels duplicate in-flight calls and works with fetch, axios, jQuery.ajax, Ext.Ajax, raw XHR, and custom clients.
 
 ## Key Features
 
-- **Universal Compatibility**: Works with any HTTP library that returns a Promise (fetch, axios, Ext.Ajax, etc.)
-- **Automatic Cancellation**: When a request is repeated with the same `requestKey`, the previous request is automatically cancelled. This identifier is generated with `url` parameter or can be manually specified in `options`.
-- **Prioritizes Recent Requests**: The library ensures that only the most recent request is processed, cancelling older ones
-- **Simple API**: Easy to use and integrate into existing projects
-- **Adapt to your requirements**: The library supports `options` for custom request management
+- **Universal Compatibility**: Dedicated helpers for fetch, axios, ajax-style clients (jQuery / Ext.Ajax), and XMLHttpRequest — plus a low-level `request()` escape hatch
+- **Automatic Cancellation**: When a request is repeated with the same identifier, the previous request is automatically cancelled. The ID comes from the cleaned URL, or from `options.requestKey`
+- **Prioritizes Recent Requests**: Only the most recent request for a given ID is kept; older ones are aborted
+- **Simple API**: Prefer the helper that matches your HTTP client; wire cancel yourself only with `request()`
+- **Adapt to your requirements**: Shared options (`requestKey`, `noCancel`, `includeQuery`, ...) across helpers
 - **TypeScript Support**: Full TypeScript type definitions included
 - **Multiple Module Formats**: ESM, CommonJS, and UMD builds available
 
@@ -24,16 +24,19 @@ npm install @enegalan/request-manager
 ### Usage in Different Environments
 
 **ES Modules (recommended):**
+
 ```javascript
 import RequestManager from '@enegalan/request-manager';
 ```
 
 **CommonJS:**
+
 ```javascript
 const { RequestManager } = require('@enegalan/request-manager');
 ```
 
 **Browser (CDN):**
+
 ```html
 <!-- Using unpkg -->
 <script src="https://unpkg.com/@enegalan/request-manager/dist/request-manager.min.js"></script>
@@ -42,7 +45,7 @@ const { RequestManager } = require('@enegalan/request-manager');
 <script src="https://cdn.jsdelivr.net/npm/@enegalan/request-manager/dist/request-manager.min.js"></script>
 
 <script>
-  const requestManager = new RequestManager();
+    const requestManager = new RequestManager();
 </script>
 ```
 
@@ -61,66 +64,98 @@ const xhrResult: XhrResponse<{ name: string }> = await requestManager.xhr('/api/
 
 ## Usage
 
-### Basic Example with fetch()
+### Which method should I use?
 
-```javascript
-import RequestManager from '@enegalan/request-manager';
+Pick the **dedicated helper** for your HTTP client. Use `request()` only when none of the helpers fit.
 
-const requestManager = new RequestManager();
+| Client                            | Use this                                  | Why                                                                                                    |
+| --------------------------------- | ----------------------------------------- | ------------------------------------------------------------------------------------------------------ |
+| `fetch`                           | **`fetch(url, options)`**                 | Creates the AbortSignal and passes it to `fetch` for you                                               |
+| `axios`                           | **`axios(url, options, axiosInstance?)`** | Creates an `AbortSignal` and wires cancel for you (axios ≥ 0.22)                                       |
+| jQuery `.ajax`, Ext.Ajax, similar | **`ajax(ajaxFunction, url, options)`**    | Runs your ajax function, then wires abort for you (`req.abort`, `Ext.Ajax.abort(req)`, or `xhr.abort`) |
+| Raw `XMLHttpRequest`              | **`xhr(url, options)`**                   | Owns open/send and abort lifecycle                                                                     |
+| Custom / already-started Promise  | **`request(url, promiseOrFn, options)`**  | Escape hatch — **you** must pass `signal` / `cancelToken` / `addAbortListener`                         |
+
+**Rule of thumb**
+
+1. Known client → use its helper (`fetch` / `axios` / `ajax` / `xhr`).
+2. Helper already cancels the real network call — no manual abort wiring.
+3. `request()` is for edge cases (wrapping an existing Promise, exotic clients). Same cancellation _map_ as the helpers, but abort plumbing is your job.
 
-requestManager.fetch('/api/users')
-  .then(response => response.json())
-  .then(data => console.log(data))
-  .catch(error => {
-    if (error.message === 'Request was cancelled') {
-      console.log('Request was cancelled');
-    } else {
-      console.error('Request failed:', error);
-    }
-  });
+```javascript
+// Preferred
+requestManager.fetch('/api/users');
+requestManager.axios('/api/users');
+requestManager.ajax(({ url, ...opts }) => $.ajax({ url, ...opts }), '/api/users');
+requestManager.ajax(({ url, ...opts }) => Ext.Ajax.request({ url, ...opts }), '/api/users');
+requestManager.xhr('/api/users');
+
+// Escape hatch — you wire cancel yourself (see sandbox / API notes below)
+requestManager.request('/api/users', ({ options }) => fetch('/api/users', { signal: options.signal, ...options }));
 ```
 
-### POST Request with Options
+> [!IMPORTANT]
+> Calling `request(url, Ext.Ajax.request(...))` or `request(url, $.ajax(...))` **without** linking abort (via `addAbortListener` / `cancelToken` / `signal`) does **not** abort the browser request when a duplicate starts. Use **`ajax()`** for those clients.
+
+### Basic Example with fetch()
 
 ```javascript
 import RequestManager from '@enegalan/request-manager';
 
-const requestManager = new RequestManager();
+const requestManager = new RequestManager({ verbose: true });
 
-requestManager.fetch('/api/users', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ name: 'John' })
-})
-.then(response => response.json())
-.then(data => console.log(data));
+requestManager
+    .fetch('/api/users')
+    .then((response) => response.json())
+    .then((data) => console.log(data))
+    .catch((error) => {
+        if (error.message.includes('was cancelled')) {
+            console.log('Request was cancelled');
+        } else {
+            console.error('Request failed:', error);
+        }
+    });
 ```
 
-### Using request() with Promise
+### POST Request with Options
 
 ```javascript
 import RequestManager from '@enegalan/request-manager';
 
 const requestManager = new RequestManager();
 
-requestManager.request('/api/users', fetch('/api/users'))
-  .then(response => response.json())
-  .then(data => console.log(data));
+requestManager
+    .fetch('/api/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name: 'John' }),
+    })
+    .then((response) => response.json())
+    .then((data) => console.log(data));
 ```
 
-### Using request() with Function
+### Using request()
+
+`request()` is the low-level API when you already have a Promise or need custom wiring.
 
 ```javascript
 import RequestManager from '@enegalan/request-manager';
 
 const requestManager = new RequestManager();
 
-// Custom logic
-requestManager.request('/api/users', ({ options }) => {
-  return fetch('/api/users', options);
-})
-.then(response => response.json())
-.then(data => console.log(data));
+// Function form — options include signal; pass it into fetch (or prefer requestManager.fetch)
+requestManager
+    .request('/api/users', ({ options }) => {
+        return fetch('/api/users', { signal: options.signal, ...options });
+    })
+    .then((response) => response.json())
+    .then((data) => console.log(data));
+
+// Pre-created Promise — must also pass abortController / cancelToken or cancel is incomplete
+const abortController = requestManager.getAbortController();
+requestManager.request('/api/users', fetch('/api/users', { signal: abortController.signal }), {
+    abortController,
+});
 ```
 
 ### Automatic Cancellation with Same URL
@@ -132,17 +167,17 @@ const requestManager = new RequestManager();
 
 // By default, requests with the same URL (cleaned) will cancel previous ones
 // The URL is automatically cleaned (protocol and query params removed) to generate the request ID
-requestManager.fetch('/api/search?q=test')
-  .catch(error => {
+requestManager.fetch('/api/search?q=test').catch((error) => {
     console.log('First request cancelled:', error.message);
-  });
+});
 
 // This second request will automatically cancel the first one
 // because they share the same cleaned URL
 setTimeout(() => {
-  requestManager.fetch('/api/search?q=updated')
-    .then(response => response.json())
-    .then(data => console.log('Second request completed:', data));
+    requestManager
+        .fetch('/api/search?q=updated')
+        .then((response) => response.json())
+        .then((data) => console.log('Second request completed:', data));
 }, 100);
 ```
 
@@ -154,20 +189,22 @@ import RequestManager from '@enegalan/request-manager';
 const requestManager = new RequestManager();
 
 // You can use requestKey to override the default URL-based ID generation
-requestManager.fetch('/api/search?q=test', {
-  requestKey: 'search-users' // Custom key instead of cleaned URL
-})
-.catch(error => {
-  console.log('First request cancelled:', error.message);
-});
+requestManager
+    .fetch('/api/search?q=test', {
+        requestKey: 'search-users', // Custom key instead of cleaned URL
+    })
+    .catch((error) => {
+        console.log('First request cancelled:', error.message);
+    });
 
 // This second request will cancel the first one because they share the same requestKey
 setTimeout(() => {
-  requestManager.fetch('/api/search?q=updated', {
-    requestKey: 'search-users' // Same key = same request ID = cancellation
-  })
-  .then(response => response.json())
-  .then(data => console.log('Second request completed:', data));
+    requestManager
+        .fetch('/api/search?q=updated', {
+            requestKey: 'search-users', // Same key = same request ID = cancellation
+        })
+        .then((response) => response.json())
+        .then((data) => console.log('Second request completed:', data));
 }, 100);
 ```
 
@@ -180,9 +217,9 @@ const requestManager = new RequestManager();
 
 // You can use a function to generate the requestKey dynamically
 function searchUsers(query) {
-  return requestManager.fetch(`/api/search?q=${query}`, {
-    requestKey: () => `search-${query}` // Function that returns the key
-  });
+    return requestManager.fetch(`/api/search?q=${query}`, {
+        requestKey: () => `search-${query}`, // Function that returns the key
+    });
 }
 
 // Both calls will share the same requestKey and cancel each other
@@ -199,49 +236,46 @@ const requestManager = new RequestManager();
 
 // Use noCancel: true to allow multiple requests to execute concurrently
 // This is useful for lazy loading scenarios where you want all requests to complete
-requestManager.fetch('/api/lazy?load=1', { noCancel: true })
-  .then(response => response.json())
-  .then(data => console.log('Load 1:', data));
+requestManager
+    .fetch('/api/lazy?load=1', { noCancel: true })
+    .then((response) => response.json())
+    .then((data) => console.log('Load 1:', data));
 
-requestManager.fetch('/api/lazy?load=2', { noCancel: true })
-  .then(response => response.json())
-  .then(data => console.log('Load 2:', data));
+requestManager
+    .fetch('/api/lazy?load=2', { noCancel: true })
+    .then((response) => response.json())
+    .then((data) => console.log('Load 2:', data));
 
-requestManager.fetch('/api/lazy?load=3', { noCancel: true })
-  .then(response => response.json())
-  .then(data => console.log('Load 3:', data));
+requestManager
+    .fetch('/api/lazy?load=3', { noCancel: true })
+    .then((response) => response.json())
+    .then((data) => console.log('Load 3:', data));
 
 // All three requests will execute concurrently without canceling each other
 // Even though they share the same cleaned URL (without query params)
 ```
 
-### Using with Axios
+### Using includeQuery to Distinguish Query Strings
 
 ```javascript
-import axios from 'axios';
 import RequestManager from '@enegalan/request-manager';
 
 const requestManager = new RequestManager();
 
-const CancelToken = axios.CancelToken;
-const source = CancelToken.source();
-
-requestManager.request('/api/users', axios.get('/api/users', {
-  cancelToken: source.token
-}), {
-  cancelToken: () => source.cancel()
-})
-.then(response => console.log(response.data))
-.catch(error => {
-  if (axios.isCancel(error)) {
-    console.log('Request was cancelled');
-  } else {
-    console.error('Request failed:', error);
-  }
-});
+// By default, query params are stripped from the ID:
+// /api/users?page=1 and /api/users?page=2 share the same ID and cancel each other.
+
+// With includeQuery: true, the query string is part of the ID
+requestManager.fetch('/api/users?page=1', { includeQuery: true });
+requestManager.fetch('/api/users?page=2', { includeQuery: true });
+// Both run — different query = different ID
+
+// Same full URL still cancels the previous one
+requestManager.fetch('/api/users?page=1', { includeQuery: true });
+requestManager.fetch('/api/users?page=1', { includeQuery: true }); // cancels the previous page=1
 ```
 
-### Using with Axios and Function
+### Using with Axios
 
 ```javascript
 import axios from 'axios';
@@ -249,64 +283,73 @@ import RequestManager from '@enegalan/request-manager';
 
 const requestManager = new RequestManager();
 
-requestManager.request('/api/users', ({ options }) => {
-  const CancelToken = axios.CancelToken;
-  const source = CancelToken.source();
-  return axios.get('/api/users', { cancelToken: source.token });
-})
-.then(response => console.log(response.data))
-.catch(error => {
-  if (axios.isCancel(error)) {
-    console.log('Request was cancelled');
-  } else {
-    console.error('Request failed:', error);
-  }
-});
+requestManager
+    .axios('/api/users')
+    .then((response) => console.log(response.data))
+    .catch((error) => {
+        if (axios.isCancel(error)) {
+            console.log('Request was cancelled');
+        } else {
+            console.error('Request failed:', error);
+        }
+    });
 ```
 
-### Using with Other Libraries
+### Using with jQuery / Ext.Ajax (`ajax()`)
+
+`ajax()` invokes your function, inspects the returned request object, and registers abort automatically (`req.abort`, `Ext.Ajax.abort(req)`, or `xhr.abort`).
 
 ```javascript
 import RequestManager from '@enegalan/request-manager';
 
 const requestManager = new RequestManager();
 
-requestManager.request('/api/data', ({ options }) => {
-  return new Promise((resolve, reject) => {
-    const xhr = new XMLHttpRequest();
-    xhr.open('GET', '/api/data');
-    xhr.onload = () => resolve(xhr.responseText);
-    xhr.onerror = () => reject(new Error('Request failed'));
-    xhr.send();
-    
-    // Use signal to cancel if needed
-    options.signal.addEventListener('abort', () => {
-      xhr.abort();
-      reject(new Error('Request was cancelled'));
-    });
-  });
-})
-.then(data => console.log(data))
-.catch(error => console.error(error));
+// jQuery
+requestManager.ajax($.ajax.bind($), '/api/users', { method: 'GET' });
+
+// Ext.Ajax — return the Ext request object (not a Promise)
+requestManager.ajax(({ url, ...options }) => Ext.Ajax.request({ url, ...options }), '/api/users');
+
+// Or bind Ext.Ajax.request directly when options shape matches
+requestManager.ajax(Ext.Ajax.request.bind(Ext.Ajax), '/api/users');
+```
+
+Equivalent with `request()` (more boilerplate — not recommended):
+
+```javascript
+requestManager.request('/api/users', ({ options }) => {
+    const req = Ext.Ajax.request({ url: '/api/users', ...options });
+    requestManager.addAbortListener(() => Ext.Ajax.abort(req), options.signal);
+    return req;
+});
 ```
 
-### Using with Pre-created Promises
+### Using with Other Libraries
+
+If there is no dedicated helper, use `request()` and **must** abort on `options.signal` (or pass `cancelToken` / `addAbortListener`).
 
 ```javascript
 import RequestManager from '@enegalan/request-manager';
 
 const requestManager = new RequestManager();
 
-const existingPromise = fetch('/api/data');
-
-requestManager.request('/api/data', existingPromise, {
-  // You can still provide cancelToken if your library supports it
-  cancelToken: () => {
-    // Custom cancellation logic
-  }
-})
-.then(response => response.json())
-.then(data => console.log(data));
+requestManager
+    .request('/api/data', ({ options }) => {
+        return new Promise((resolve, reject) => {
+            const xhr = new XMLHttpRequest();
+            xhr.open('GET', '/api/data');
+            xhr.onload = () => resolve(xhr.responseText);
+            xhr.onerror = () => reject(new Error('Request failed'));
+            xhr.send();
+
+            options.signal.addEventListener('abort', () => {
+                xhr.abort();
+                reject(new Error('Request was cancelled'));
+            });
+        });
+    })
+    .then((data) => console.log(data))
+    .catch((error) => console.error(error));
 ```
 
 ## API Reference
@@ -316,10 +359,12 @@ requestManager.request('/api/data', existingPromise, {
 Creates a new RequestManager instance.
 
 **Parameters:**
+
 - `options` (Object, optional): Configuration options
-  - `verbose` (boolean, optional): If true, cancellation errors will include messages globally for all requests.
+    - `verbose` (boolean, optional): If true, cancellation rejects with a message that includes the request id. If false (default), cancellation is silent (wrapper promise does not settle; nothing is logged).
 
 **Example:**
+
 ```javascript
 // Create with verbose mode enabled
 const requestManager = new RequestManager({ verbose: true });
@@ -327,36 +372,40 @@ const requestManager = new RequestManager({ verbose: true });
 
 ### `request(url, requestPromise, options)`
 
-Executes an HTTP request, cancelling any previous request with the same identifier.
+Low-level entry point. Tracks the call by ID and cancels the previous one with the same ID — but **you** must connect abort to the underlying client (`signal`, `cancelToken`, or `addAbortListener`). Otherwise the manager drops the tracked entry while the HTTP request may keep running.
 
 **Parameters:**
+
 - `url` (string): The URL of the request (used to generate request ID from cleaned URL)
-- `requestPromise` (Promise|Function|string): The Promise returned by any HTTP library (fetch, axios, etc.), a Function that can receive `{ options }` and returns a Promise, or a URL string (which will be used with fetch internally)
+- `requestPromise` (Promise|Function|string): A Promise from any HTTP library, a Function that receives `{ options }` and returns a Promise/request object, or a URL string (fetch internally)
 - `options` (Object, optional): Configuration options
-  - `abortController` (AbortController): AbortController instance (created automatically if not provided)
-  - `cancelToken` (Function|Object): Cancel token or cancel function for other libraries
-  - `requestKey` (string|number|Function, optional): Key to identify duplicate requests. If provided, requests with the same key will share the same ID and cancel previous ones. If not provided, the cleaned URL is used as the key. Can be a string, number, or function that returns a key.
-  - `noCancel` (boolean): If true, this request will not cancel previous requests with the same ID, allowing concurrent requests. Useful for lazy loading scenarios where multiple requests should execute in parallel.
+    - `abortController` (AbortController): AbortController instance (created automatically if not provided)
+    - `cancelToken` (Function|Object): Cancel token or cancel function for other libraries
+    - `requestKey` (string|number|Function, optional): Key to identify duplicate requests. If provided, requests with the same key will share the same ID and cancel previous ones. If not provided, the cleaned URL is used as the key. Can be a string, number, or function that returns a key.
+    - `noCancel` (boolean): If true, this request will not cancel previous requests with the same ID, allowing concurrent requests. Useful for lazy loading scenarios where multiple requests should execute in parallel.
+    - `includeQuery` (boolean): If true, keeps the query string when generating the request ID from the URL.
 
 > [!TIP]
 > When `requestPromise` is a Function, you can pass custom properties in `options`. These will be accessible inside the callback via the `{ options }` parameter.
 
 **Returns:** Promise that resolves/rejects based on the most recent request
 
-**Note:** The request ID is automatically generated from the cleaned URL (protocol and query params removed) unless `requestKey` is specified. When `noCancel` is true, a unique ID is generated for each request to prevent cancellation. When `requestPromise` is a Function, it receives `{ options }` where `options` contains the `signal` (AbortSignal) and any other fetch options.
+**Note:** The request ID is automatically generated from the cleaned URL (protocol and hash removed; query params removed unless `includeQuery` is true) unless `requestKey` is specified. When `noCancel` is true, a unique ID is generated for each request to prevent cancellation. When `requestPromise` is a Function, it receives `{ options }` where `options` contains the `signal` (AbortSignal) and any other fetch options.
 
 ### `fetch(url, options)`
 
 Executes an HTTP request using fetch, cancelling any previous request with the same identifier.
 
 **Parameters:**
+
 - `url` (string): The URL to fetch
 - `options` (Object, optional): Configuration options (same as `request()` method)
-  - `requestKey` (string|number|Function, optional): Key to identify duplicate requests. If not provided, the cleaned URL is used as the key.
-  - `abortController` (AbortController): AbortController instance (created automatically if not provided)
-  - `cancelToken` (Function|Object): Cancel token or cancel function for other libraries
-  - `noCancel` (boolean): If true, this request will not cancel previous requests with the same ID, allowing concurrent requests
-  - Any other properties are passed as fetch options (method, headers, body, etc.)
+    - `requestKey` (string|number|Function, optional): Key to identify duplicate requests. If not provided, the cleaned URL is used as the key.
+    - `abortController` (AbortController): AbortController instance (created automatically if not provided)
+    - `cancelToken` (Function|Object): Cancel token or cancel function for other libraries
+    - `noCancel` (boolean): If true, this request will not cancel previous requests with the same ID, allowing concurrent requests
+    - `includeQuery` (boolean): If true, keeps the query string in the URL-based request ID
+    - Any other properties are passed as fetch options (method, headers, body, etc.)
 
 **Returns:** Promise that resolves/rejects based on the most recent request
 
@@ -367,18 +416,21 @@ Executes an HTTP request using fetch, cancelling any previous request with the s
 Executes an HTTP request using axios, cancelling any previous request with the same identifier.
 
 **Parameters:**
+
 - `url` (string): The URL to request
 - `options` (Object, optional): Configuration options
-  - `requestKey` (string|number|Function, optional): Key to identify duplicate requests. If provided, requests with the same key will cancel previous ones. Can be a string, number, or function that returns a key.
-  - `noCancel` (boolean): If true, this request will not cancel previous requests with the same ID, allowing concurrent requests
-  - Any other properties are passed as axios options (method, headers, params, data, etc.)
+    - `requestKey` (string|number|Function, optional): Key to identify duplicate requests. If provided, requests with the same key will cancel previous ones. Can be a string, number, or function that returns a key.
+    - `noCancel` (boolean): If true, this request will not cancel previous requests with the same ID, allowing concurrent requests
+    - `includeQuery` (boolean): If true, keeps the query string in the URL-based request ID
+    - Any other properties are passed as axios options (method, headers, params, data, etc.)
 - `axiosInstance` (Object, optional): Custom axios instance to use. If not provided, uses the global `axios` object.
 
 **Returns:** Promise that resolves/rejects based on the most recent request
 
-**Note:** This method automatically creates a CancelToken for axios cancellation. The request ID is automatically generated from the cleaned URL unless `requestKey` is specified. When `noCancel` is true, a unique ID is generated for each request.
+**Note:** This method automatically creates an AbortController and passes its `signal` in the axios config, so cancellation requires axios ≥ 0.22. The request ID is automatically generated from the cleaned URL unless `requestKey` is specified. When `noCancel` is true, a unique ID is generated for each request.
 
 **Example:**
+
 ```javascript
 import axios from 'axios';
 import RequestManager from '@enegalan/request-manager';
@@ -386,71 +438,69 @@ import RequestManager from '@enegalan/request-manager';
 const requestManager = new RequestManager();
 
 // Simple GET request (uses global axios)
-requestManager.axios('/api/users')
-  .then(response => console.log(response.data))
-  .catch(error => console.error(error));
+requestManager
+    .axios('/api/users')
+    .then((response) => console.log(response.data))
+    .catch((error) => console.error(error));
 
 // With custom axios instance
 const apiClient = axios.create({
-  baseURL: 'https://api.example.com',
-  timeout: 5000
+    baseURL: 'https://api.example.com',
+    timeout: 5000,
 });
 
-requestManager.axios('/users', {}, apiClient)
-  .then(response => console.log(response.data));
+requestManager.axios('/users', {}, apiClient).then((response) => console.log(response.data));
 
 // POST request with options
-requestManager.axios('/api/users', {
-  method: 'POST',
-  data: { name: 'John' },
-  headers: { 'Content-Type': 'application/json' }
-})
-.then(response => console.log(response.data));
+requestManager
+    .axios('/api/users', {
+        method: 'POST',
+        data: { name: 'John' },
+        headers: { 'Content-Type': 'application/json' },
+    })
+    .then((response) => console.log(response.data));
 ```
 
 ### `ajax(ajaxFunction, url, options)`
 
-Executes an HTTP request using a custom ajax method function, cancelling any previous request with the same identifier.
+Helper for **ajax-style clients** (jQuery.ajax, Ext.Ajax, etc.) that return a request object rather than (or in addition to) a Promise.
+
+Calls `ajaxFunction({ url, ...options })`, then auto-wires cancel by inspecting the returned object:
+
+1. `req.abort` if present (jQuery)
+2. else `Ext.Ajax.abort(req)` when Ext is available and `req.xhr` exists
+3. else `req.xhr.abort` / raw `XMLHttpRequest.abort`
 
 **Parameters:**
-- `ajaxFunction` (Function): A function that receives `{ url, ...options }` and returns a Promise. The function should accept an object with `url` and other options including the `signal` (AbortSignal).
+
+- `ajaxFunction` (Function): Receives `{ url, ...options }` and returns the library request object (or a Promise).
 - `url` (string): The URL to request
 - `options` (Object, optional): Configuration options
-  - `requestKey` (string|number|Function, optional): Key to identify duplicate requests. If provided, requests with the same key will cancel previous ones. Can be a string, number, or function that returns a key.
-  - `abortController` (AbortController): AbortController instance (created automatically if not provided)
-  - `cancelToken` (Function|Object): Cancel token or cancel function for other libraries
-  - `verbose` (boolean): If true, cancellation errors will include messages
-  - `noCancel` (boolean): If true, this request will not cancel previous requests with the same ID, allowing concurrent requests
-  - Any other properties are passed to the ajax method function
+    - `requestKey` (string|number|Function, optional): Key to identify duplicate requests. If provided, requests with the same key will cancel previous ones. Can be a string, number, or function that returns a key.
+    - `abortController` (AbortController): AbortController instance (created automatically if not provided)
+    - `cancelToken` (Function|Object): Cancel token or cancel function for other libraries
+    - `verbose` (boolean): If true, cancellation rejects with a message that includes the request id
+    - `noCancel` (boolean): If true, this request will not cancel previous requests with the same ID, allowing concurrent requests
+    - `includeQuery` (boolean): If true, keeps the query string in the URL-based request ID
+    - Any other properties are passed to the ajax method function
 
 **Returns:** Promise that resolves/rejects based on the most recent request
 
 **Example:**
+
 ```javascript
 import RequestManager from '@enegalan/request-manager';
 
 const requestManager = new RequestManager();
 
-// Using with jQuery.ajax
-requestManager.ajax(
-  ({ url, ...options }) => {
-    return new Promise((resolve, reject) => {
-      $.ajax({
-        url: url,
-        ...options,
-        success: resolve,
-        error: reject
-      });
-    });
-  },
-  '/api/users',
-  {
-    method: 'GET',
-    headers: { 'Content-Type': 'application/json' }
-  }
-)
-.then(data => console.log(data))
-.catch(error => console.error(error));
+// jQuery
+requestManager
+    .ajax($.ajax.bind($), '/api/users', { method: 'GET' })
+    .then((data) => console.log(data))
+    .catch((error) => console.error(error));
+
+// Ext.Ajax
+requestManager.ajax(({ url, ...options }) => Ext.Ajax.request({ url, ...options }), '/api/users');
 ```
 
 ### `xhr(url, options)`
@@ -458,45 +508,80 @@ requestManager.ajax(
 Executes an HTTP request using XMLHttpRequest, cancelling any previous request with the same identifier.
 
 **Parameters:**
+
 - `url` (string): The URL to request
 - `options` (Object, optional): Configuration options
-  - `method` (string): HTTP method (GET, POST, PUT, DELETE, etc.). Defaults to 'GET'.
-  - `headers` (Object): Headers object to set on the request
-  - `body` (string|FormData|Blob|ArrayBuffer): Request body
-  - `responseType` (string): Response type ('text', 'json', 'blob', 'arraybuffer', 'document'). Defaults to 'text'.
-  - `withCredentials` (boolean): Whether to send credentials with the request
-  - `timeout` (number): Request timeout in milliseconds
-  - `requestKey` (string|number|Function, optional): Key to identify duplicate requests. If provided, requests with the same key will cancel previous ones. Can be a string, number, or function that returns a key.
-  - `abortController` (AbortController): AbortController instance (created automatically if not provided)
-  - `verbose` (boolean): If true, cancellation errors will include messages
-  - `noCancel` (boolean): If true, this request will not cancel previous requests with the same ID, allowing concurrent requests
+    - `method` (string): HTTP method (GET, POST, PUT, DELETE, etc.). Defaults to 'GET'.
+    - `headers` (Object): Headers object to set on the request
+    - `body` (string|FormData|Blob|ArrayBuffer): Request body
+    - `responseType` (string): Response type ('text', 'json', 'blob', 'arraybuffer', 'document'). Defaults to 'text'.
+    - `withCredentials` (boolean): Whether to send credentials with the request
+    - `timeout` (number): Request timeout in milliseconds
+    - `requestKey` (string|number|Function, optional): Key to identify duplicate requests. If provided, requests with the same key will cancel previous ones. Can be a string, number, or function that returns a key.
+    - `abortController` (AbortController): AbortController instance (created automatically if not provided)
+    - `verbose` (boolean): If true, cancellation rejects with a message that includes the request id
+    - `noCancel` (boolean): If true, this request will not cancel previous requests with the same ID, allowing concurrent requests
+    - `includeQuery` (boolean): If true, keeps the query string in the URL-based request ID
 
 **Returns:** Promise that resolves/rejects based on the most recent request. The resolved value is an object with:
-  - `data`: The response data (automatically parsed as JSON if Content-Type is application/json)
-  - `status`: HTTP status code
-  - `statusText`: HTTP status text
-  - `headers`: Response headers string
-  - `xhr`: The XMLHttpRequest instance
+
+- `data`: The response data (automatically parsed as JSON if Content-Type is application/json)
+- `status`: HTTP status code
+- `statusText`: HTTP status text
+- `headers`: Response headers string
+- `xhr`: The XMLHttpRequest instance
 
 **Example:**
+
 ```javascript
 import RequestManager from '@enegalan/request-manager';
 
 const requestManager = new RequestManager();
 
 // Simple GET request
-requestManager.xhr('/api/users')
-  .then(response => console.log(response.data))
-  .catch(error => console.error(error));
+requestManager
+    .xhr('/api/users')
+    .then((response) => console.log(response.data))
+    .catch((error) => console.error(error));
 
 // POST request with options
-requestManager.xhr('/api/users', {
-  method: 'POST',
-  headers: { 'Content-Type': 'application/json' },
-  body: JSON.stringify({ name: 'John' }),
-  responseType: 'json'
-})
-.then(response => console.log(response.data));
+requestManager
+    .xhr('/api/users', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ name: 'John' }),
+        responseType: 'json',
+    })
+    .then((response) => console.log(response.data));
+```
+
+### `getRequestId(url, options)`
+
+Returns the request ID that RequestManager assigns for a URL and options.
+
+**Parameters:**
+
+- `url` (string): The URL used when starting the request
+- `options` (Object, optional): Same options used for the request
+    - `requestKey` (string|number|Function, optional): Key override
+    - `includeQuery` (boolean, optional): Keep query string in the URL-based ID
+    - `noCancel` (boolean, optional): If true, returns a **new** unique ID (will not match an already in-flight `noCancel` request)
+
+**Returns:** `string` — the request identifier
+
+**Example:**
+
+```javascript
+requestManager.fetch('/api/users');
+
+const id = requestManager.getRequestId('/api/users');
+if (requestManager.isActive(id)) {
+    requestManager.cancel(id);
+}
+
+// With the same options used for the request:
+const searchId = requestManager.getRequestId('/api/search?q=test', { requestKey: 'search-users' });
+requestManager.cancel(searchId);
 ```
 
 ### `cancel(requestId)`
@@ -504,6 +589,7 @@ requestManager.xhr('/api/users', {
 Cancels a specific request by its identifier.
 
 **Parameters:**
+
 - `requestId` (string): The unique identifier of the request to cancel
 
 **Returns:** `true` if the request was found and cancelled, `false` otherwise
@@ -519,6 +605,7 @@ Cancels all active requests.
 Checks if a request with the given identifier is currently active.
 
 **Parameters:**
+
 - `requestId` (string): The unique identifier to check
 
 **Returns:** `true` if the request is active, `false` otherwise
@@ -535,11 +622,12 @@ Clears all active requests without cancelling them. Use with caution - this will
 
 ### `getSignal()`
 
-Gets the AbortSignal from the current AbortController. Creates a new AbortController if one doesn't exist or if the current one is aborted.
+Creates a new AbortController and returns its signal for the next `request()` (one `getSignal` → one request). Do not use for parallel requests; use `fetch()`, `axios()`, or `request(url, ({ options }) => ...)` instead — they create their own signal.
 
-**Returns:** AbortSignal from the current AbortController
+**Returns:** AbortSignal from a new AbortController
 
 **Example:**
+
 ```javascript
 const signal = requestManager.getSignal();
 requestManager.request('/api/users', fetch('/api/users', { signal }));
@@ -547,11 +635,12 @@ requestManager.request('/api/users', fetch('/api/users', { signal }));
 
 ### `getAbortController()`
 
-Gets the current AbortController instance. Creates a new AbortController if one doesn't exist or if the current one is aborted.
+Creates a new AbortController for the next request handoff. Always returns a fresh controller (never reuses one from another in-flight request).
 
 **Returns:** AbortController instance
 
 **Example:**
+
 ```javascript
 const abortController = requestManager.getAbortController();
 requestManager.request('/api/users', fetch('/api/users', { signal: abortController.signal }));
@@ -568,17 +657,19 @@ Gets the manager options that were passed to the constructor or set via `setOpti
 Sets the manager options.
 
 **Parameters:**
+
 - `options` (Object): Configuration options
-  - `verbose` (boolean, optional): If true, cancellation errors will include messages
+    - `verbose` (boolean, optional): If true, cancellation rejects with a message that includes the request id. If false (default), cancellation is silent.
 
 **Example:**
+
 ```javascript
 const requestManager = new RequestManager();
 
-// Enable verbose mode at runtime
+// Enable verbose cancellation messages at runtime
 requestManager.setOptions({ verbose: true });
 
-// Disable verbose mode
+// Silent cancellation (default) — no rejection / no console noise
 requestManager.setOptions({ verbose: false });
 ```
 
@@ -587,10 +678,12 @@ requestManager.setOptions({ verbose: false });
 Links an abort signal with an HTTP client abort method. Useful for custom HTTP clients that only support the abort method to cancel requests.
 
 **Parameters:**
+
 - `abortMethod` (Function): The abort method to call when the signal is aborted
 - `signal` (AbortSignal): The signal to listen to
 
 **Example:**
+
 ```javascript
 const abortController = new AbortController();
 const req = $.ajax({ url });