@enegalan/request-manager 1.0.3 → 1.1.0

package/index.d.ts

@@ -9,65 +9,108 @@
 export type RequestKeyFunction = () => string | number | null | undefined;
 
 /**
- * Request key type - can be a string, number, or a function that returns a dynamic key
+ * Request key type - can be a plain value, or a function that returns a dynamic key
  */
 export type RequestKey = string | number | RequestKeyFunction;
 
 /**
- * Cancel token type (axios compatibility) - can be a function or an object with a cancel method
+ * Cancel token type - can be a function or an object with a cancel method
  */
 export type CancelToken = (() => void) | { cancel: () => void };
 
 /**
- * Manager options passed to the RequestManager constructor
+ * Active request data interface stored by the RequestManager
  */
-export interface ManagerOptions {
+export interface ActiveRequest<T = any> {
     /**
-     * If true, cancellation errors will include messages globally for all requests
+     * The original request: a promise or a request object (XHR, Ext.Ajax, etc.)
+     */
+    promise: any;
+
+    /**
+     * AbortController instance used to abort the request
+     */
+    abortController: AbortController;
+
+    /**
+     * Cancel token for custom HTTP clients that only support manual cancellation
+     */
+    cancelToken: CancelToken | null;
+
+    /**
+     * Function to resolve the wrapper promise
+     */
+    resolveWrapper: (value: T | PromiseLike<T>) => void;
+
+    /**
+     * Function to reject the wrapper promise
+     */
+    rejectWrapper: (reason?: any) => void;
+
+    /**
+     * Whether the request has been cancelled
+     */
+    isCancelled: boolean;
+}
+
+/**
+ * RequestManager global options interface
+ */
+export interface Options {
+    /**
+     * If true, cancellation rejects the wrapper promise with a message that includes the request identifier.
+     * If false, cancellation is silent: the wrapper promise does not settle and nothing is logged.
+     * @default false
      */
     verbose?: boolean;
 }
 
 /**
- * Base request options shared by all request methods
+ * Base request options interface shared by all request methods
  */
 export interface BaseRequestOptions {
     /**
-     * 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.
+     * @type {RequestKey}
      */
     requestKey?: RequestKey;
 
     /**
-     * AbortController instance (created automatically if not provided)
+     * @type {AbortController}
      */
     abortController?: AbortController;
 
     /**
-     * Cancel token (axios compatibility)
+     * Cancel token for custom HTTP clients that only support manual cancellation
+     * @type {CancelToken}
      */
     cancelToken?: CancelToken;
 
     /**
-     * If true, this request will not cancel previous requests with the same ID,
+     * If true, this request will not cancel previous requests with the same identifier,
      * allowing concurrent requests.
+     * @default false
      */
     noCancel?: boolean;
+
+    /**
+     * If true, the query string is kept when generating the request identifier from the URL.
+     * @default false
+     */
+    includeQuery?: boolean;
 }
 
 /**
- * Options for the request() method
+ * Options interface for the request() method
  */
 export interface RequestOptions extends BaseRequestOptions, Omit<RequestInit, 'signal'> {}
 
 /**
- * Options for the fetch() method
+ * Options interface for the fetch() method
  */
 export interface FetchOptions extends BaseRequestOptions, Omit<RequestInit, 'signal'> {}
 
 /**
- * Options for the axios() method
+ * Options interface for the axios() method
  */
 export interface AxiosRequestOptions extends BaseRequestOptions {
     /**
@@ -117,11 +160,11 @@ export interface AxiosRequestOptions extends BaseRequestOptions {
 }
 
 /**
- * Options for the xhr() method
+ * Options interface for the xhr() method
  */
 export interface XhrOptions extends BaseRequestOptions {
     /**
-     * HTTP method (GET, POST, PUT, DELETE, etc.). Defaults to 'GET'.
+     * HTTP method
      */
     method?: string;
 
@@ -136,7 +179,8 @@ export interface XhrOptions extends BaseRequestOptions {
     body?: string | FormData | Blob | ArrayBuffer | null;
 
     /**
-     * Response type ('text', 'json', 'blob', 'arraybuffer', 'document'). Defaults to 'text'.
+     * Response type
+     * @default 'text'
      */
     responseType?: XMLHttpRequestResponseType;
 
@@ -152,7 +196,7 @@ export interface XhrOptions extends BaseRequestOptions {
 }
 
 /**
- * Response from the xhr() method
+ * Response interface from the xhr() method
  */
 export interface XhrResponse<T = any> {
     /**
@@ -182,7 +226,7 @@ export interface XhrResponse<T = any> {
 }
 
 /**
- * Options passed to the request function callback
+ * Options interface passed to the request function callback
  */
 export interface RequestFunctionOptions {
     /**
@@ -192,17 +236,19 @@ export interface RequestFunctionOptions {
 }
 
 /**
- * A function that receives options and returns a Promise
+ * Function type that receives options and returns a Promise
  */
 export type RequestFunction<T = any> = (params: RequestFunctionOptions) => Promise<T>;
 
 /**
  * Ajax function type
  */
-export type AjaxFunction<T = any> = (params: { url: string; signal?: AbortSignal } & Record<string, any>) => Promise<T> & { abort?: () => void };
+export type AjaxFunction<T = any> = (
+    params: { url: string; signal?: AbortSignal } & Record<string, any>
+) => Promise<T> & { abort?: () => void };
 
 /**
- * Axios instance interface (minimal definition for compatibility)
+ * Axios instance interface
  */
 export interface AxiosInstance {
     get<T = any>(url: string, config?: any): Promise<T>;
@@ -216,16 +262,10 @@ export interface AxiosInstance {
     postForm<T = any>(url: string, data?: any, config?: any): Promise<T>;
     putForm<T = any>(url: string, data?: any, config?: any): Promise<T>;
     patchForm<T = any>(url: string, data?: any, config?: any): Promise<T>;
-    CancelToken: {
-        source(): {
-            token: any;
-            cancel: (message?: string) => void;
-        };
-    };
 }
 
 /**
- * Axios static interface (for global axios)
+ * Axios static interface
  */
 export interface AxiosStatic extends AxiosInstance {
     create(config?: any): AxiosInstance;
@@ -243,51 +283,43 @@ declare class RequestManager {
     /**
      * Map to store active requests by their unique identifier
      */
-    activeRequests: Map<string, any>;
-
-    /**
-     * Verbose mode: if true, cancellation errors will include messages
-     */
-    verbose: boolean;
+    activeRequests: Map<string, ActiveRequest>;
 
     /**
      * Manager options that were passed to the constructor
      */
-    managerOptions: ManagerOptions;
-
-    /**
-     * Options for the current request (flushed after each request)
-     */
-    options: Record<string, any>;
+    options: Options;
 
     /**
-     * AbortController instance for the current request
+     * One-shot AbortController handoff from getAbortController()/getSignal().
+     * Consumed by the next request that does not pass options.abortController.
      */
     abortController: AbortController | null;
 
     /**
      * Creates a new RequestManager instance
-     * @param managerOptions - Configuration options for the manager
+     * @param options - Configuration options for the manager
      */
-    constructor(managerOptions?: ManagerOptions);
+    constructor(options?: Options);
 
     /**
      * Sets the manager options
      * @param options - The manager options to set
      */
-    setOptions(options: ManagerOptions): void;
+    setOptions(options: Options): void;
 
     /**
      * Gets the manager options
      * @returns The manager options
      */
-    getOptions(): ManagerOptions;
+    getOptions(): Options;
 
     /**
-     * Creates an AbortController and returns its signal.
-     * The AbortController is stored internally and will be used by the next request() call.
+     * 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 The signal from a new AbortController
-     * 
+     *
      * @example
      * const signal = requestManager.getSignal();
      * requestManager.request('/api/users', fetch('/api/users', { signal }));
@@ -295,28 +327,28 @@ declare class RequestManager {
     getSignal(): AbortSignal;
 
     /**
-     * Gets the current AbortController instance.
-     * Creates a new AbortController if none exists or if the current one is aborted.
-     * @returns The current AbortController instance
+     * Creates a new AbortController for the next request handoff.
+     * Always returns a fresh controller (never reuses one from another in-flight request).
+     * @returns A new AbortController instance
      */
     getAbortController(): AbortController;
 
     /**
      * Executes an HTTP request, cancelling any previous request with the same identifier.
-     * 
+     *
      * @param url - The URL to request
      * @param requestPromise - The request promise, function that returns a promise, or URL string
      * @param options - Optional configuration
      * @returns A Promise that resolves/rejects based on the most recent request
-     * 
+     *
      * @example
      * // Request with Promise
      * requestManager.request('/api/users', axios.get('/api/users'));
-     * 
+     *
      * @example
      * // Request with Function
      * requestManager.request('/api/users', ({ options }) => fetch('/api/users', options));
-     * 
+     *
      * @example
      * // Request with noCancel for concurrent requests
      * requestManager.request('/api/lazy', fetch('/api/lazy'), { noCancel: true });
@@ -329,15 +361,15 @@ declare class RequestManager {
 
     /**
      * Executes an HTTP request using fetch, cancelling any previous request with the same identifier.
-     * 
+     *
      * @param url - The URL to fetch
      * @param options - Optional configuration (fetch options + RequestManager options)
      * @returns A Promise that resolves/rejects based on the most recent request
-     * 
+     *
      * @example
      * // Simple GET request
      * requestManager.fetch('/api/users');
-     * 
+     *
      * @example
      * // POST request with options
      * requestManager.fetch('/api/users', {
@@ -350,21 +382,21 @@ declare class RequestManager {
 
     /**
      * Executes an HTTP request using axios, cancelling any previous request with the same identifier.
-     * 
+     *
      * @param url - The URL to request
      * @param options - Optional configuration (axios options + RequestManager options)
      * @param axiosInstance - Optional axios instance to use. If not provided, uses global axios.
      * @returns A Promise that resolves/rejects based on the most recent request
-     * 
+     *
      * @example
      * // Simple GET request (uses global axios)
      * requestManager.axios('/api/users');
-     * 
+     *
      * @example
      * // With custom axios instance
      * const myAxios = axios.create({ baseURL: 'https://api.example.com' });
      * requestManager.axios('/users', {}, myAxios);
-     * 
+     *
      * @example
      * // POST request with options
      * requestManager.axios('/api/users', {
@@ -380,12 +412,12 @@ declare class RequestManager {
 
     /**
      * Executes an HTTP request using a custom ajax method, cancelling any previous request with the same identifier.
-     * 
+     *
      * @param ajaxFunction - A function that receives { url, ...options } and returns a Promise
      * @param url - The URL to request
      * @param options - Optional configuration
      * @returns A Promise that resolves/rejects based on the most recent request
-     * 
+     *
      * @example
      * // Using with jQuery.ajax
      * requestManager.ajax(
@@ -402,15 +434,15 @@ declare class RequestManager {
 
     /**
      * Executes an HTTP request using XMLHttpRequest, cancelling any previous request with the same identifier.
-     * 
+     *
      * @param url - The URL to request
      * @param options - Optional configuration
      * @returns A Promise that resolves/rejects based on the most recent request
-     * 
+     *
      * @example
      * // Simple GET request
      * requestManager.xhr('/api/users');
-     * 
+     *
      * @example
      * // POST request with options
      * requestManager.xhr('/api/users', {
@@ -421,9 +453,21 @@ declare class RequestManager {
      */
     xhr<T = any>(url: string, options?: XhrOptions): Promise<XhrResponse<T>>;
 
+    /**
+     * Returns the request ID that RequestManager would assign for a URL and options.
+     *
+     * Note: with noCancel => true each call generates a new unique ID, so the value
+     * returned here will not match an already in-flight noCancel request.
+     *
+     * @param url - The URL used when starting the request
+     * @param options - Same options used for the request
+     * @returns The request identifier
+     */
+    getRequestId(url: string, options?: Pick<BaseRequestOptions, 'requestKey' | 'includeQuery' | 'noCancel'>): string;
+
     /**
      * Cancels a specific request by its identifier.
-     * 
+     *
      * @param requestId - The unique identifier of the request to cancel
      * @returns True if the request was found and cancelled, false otherwise
      */
@@ -432,7 +476,7 @@ declare class RequestManager {
     /**
      * Link abort signal with HTTP client abort method.
      * Useful for custom HTTP clients that only support the abort method to cancel requests.
-     * 
+     *
      * @param abortMethod - The abort method to call when the signal is aborted
      * @param signal - The signal to listen to
      */
@@ -440,14 +484,14 @@ declare class RequestManager {
 
     /**
      * Cancels all active requests.
-     * 
+     *
      * @returns The number of requests that were cancelled
      */
     cancelAll(): number;
 
     /**
      * Checks if a request with the given identifier is currently active.
-     * 
+     *
      * @param requestId - The unique identifier to check
      * @returns True if the request is active, false otherwise
      */
@@ -455,7 +499,7 @@ declare class RequestManager {
 
     /**
      * Gets the number of active requests.
-     * 
+     *
      * @returns The number of currently active requests
      */
     getActiveCount(): number;