keq 2.9.0 → 2.10.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+## [2.10.0](https://github.com/keq-request/keq/compare/v2.9.0...v2.10.0) (2026-11-07)
+
+
+### Features
+
+* add abort and abortWhen request methods ([29b4d9c](https://github.com/keq-request/keq/commit/29b4d9c668d0432944913e55043278efd09e05ce))
+
 ## [2.9.0](https://github.com/keq-request/keq/compare/v2.8.14...v2.9.0) (2026-06-17)
 
 

package/dist/esm/src/constant.d.ts

@@ -1,2 +1,4 @@
 export declare const OUTPUT_PROPERTY: unique symbol;
 export declare const ABORT_PROPERTY: unique symbol;
+export declare const SESSION_ABORTED_PROPERTY: unique symbol;
+export declare const SESSION_ABORT_CONTROLLER_PROPERTY: unique symbol;

package/dist/esm/src/constant.js

@@ -1,2 +1,4 @@
 export const OUTPUT_PROPERTY = Symbol('outputProperty');
 export const ABORT_PROPERTY = Symbol('abortProperty');
+export const SESSION_ABORTED_PROPERTY = Symbol('sessionAbortedProperty');
+export const SESSION_ABORT_CONTROLLER_PROPERTY = Symbol('sessionAbortControllerProperty');

package/dist/esm/src/core.d.ts

@@ -12,6 +12,18 @@ export declare class Core<OUTPUT> {
      */
     __identifier__: string;
     private requestPromise?;
+    /** Whether abort() has been called on this request. */
+    private __aborted__;
+    /** The reason passed to abort(). */
+    private __abortReason__;
+    /** The context of the running attempt, used to abort the in-flight fetch. */
+    private __activeContext__?;
+    /** Aborts as soon as abort() is called, used to interrupt retry delays. */
+    private __sessionAbortController__?;
+    /** Cleanup callbacks registered by abortWhen(). */
+    private __abortWhenCleanups__;
+    /** Whether the request has settled (resolved or rejected). */
+    private __settled__;
     protected requestContext: Omit<KeqContextRequest, 'abort' | '__url__'>;
     protected __listeners__: KeqListeners;
     protected __global__: Record<string, any>;
@@ -22,6 +34,24 @@ export declare class Core<OUTPUT> {
     prependMiddlewares(...middlewares: KeqMiddleware[]): this;
     appendMiddlewares(...middlewares: KeqMiddleware[]): this;
     on<K extends keyof KeqEvents>(event: K, listener: (data: KeqEvents[K]) => void): this;
+    /**
+     * Abort the request manually.
+     *
+     * The request rejects with the given reason (an AbortException by default),
+     * and no further retry is performed. It is safe to call abort() before the
+     * request is sent.
+     *
+     * @description 手动中止请求
+     */
+    abort(reason?: any): void;
+    /**
+     * Abort the request when the given AbortSignal aborts,
+     * or when the given Promise settles (resolves or rejects).
+     *
+     * @description 当 signal 中止或 promise 完成时终止请求
+     */
+    abortWhen(source: AbortSignal | PromiseLike<unknown>): this;
+    private __clearAbortWhenCleanups__;
     private run;
     end(): Promise<OUTPUT>;
     /**

package/dist/esm/src/core.js

@@ -1,8 +1,11 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import mitt from 'mitt';
+import { AbortException } from './exception/abort.exception.js';
 import { Exception } from './exception/exception.js';
+import { InvalidArgumentsExceptions } from './exception/invalid-arguments.exception.js';
+import { isAbortSignal } from './is/is-abort-signal.js';
 import { cloneBody } from './util/clone-body.js';
-import { ABORT_PROPERTY, OUTPUT_PROPERTY } from './constant.js';
+import { ABORT_PROPERTY, OUTPUT_PROPERTY, SESSION_ABORTED_PROPERTY, SESSION_ABORT_CONTROLLER_PROPERTY } from './constant.js';
 import { composeMiddleware } from './util/compose-middleware.js';
 import { shallowClone } from './util/shallow-clone.js';
 import { compileUrl } from './util/compile-url.js';
@@ -16,6 +19,18 @@ export class Core {
      */
     __identifier__;
     requestPromise;
+    /** Whether abort() has been called on this request. */
+    __aborted__ = false;
+    /** The reason passed to abort(). */
+    __abortReason__;
+    /** The context of the running attempt, used to abort the in-flight fetch. */
+    __activeContext__;
+    /** Aborts as soon as abort() is called, used to interrupt retry delays. */
+    __sessionAbortController__;
+    /** Cleanup callbacks registered by abortWhen(). */
+    __abortWhenCleanups__ = [];
+    /** Whether the request has settled (resolved or rejected). */
+    __settled__ = false;
     requestContext;
     __listeners__ = {};
     __global__;
@@ -50,7 +65,74 @@ export class Core {
         this.__listeners__[event].push(listener);
         return this;
     }
+    /**
+     * Abort the request manually.
+     *
+     * The request rejects with the given reason (an AbortException by default),
+     * and no further retry is performed. It is safe to call abort() before the
+     * request is sent.
+     *
+     * @description 手动中止请求
+     */
+    abort(reason = new AbortException('Request aborted')) {
+        if (this.__aborted__ || this.__settled__)
+            return;
+        this.__aborted__ = true;
+        this.__abortReason__ = reason;
+        const ctx = this.__activeContext__;
+        if (ctx)
+            ctx.abort(reason);
+        this.__clearAbortWhenCleanups__();
+    }
+    /**
+     * Abort the request when the given AbortSignal aborts,
+     * or when the given Promise settles (resolves or rejects).
+     *
+     * @description 当 signal 中止或 promise 完成时终止请求
+     */
+    abortWhen(source) {
+        if (this.__aborted__ || this.__settled__)
+            return this;
+        if (isAbortSignal(source)) {
+            const reason = () => source.reason ?? new AbortException('Request aborted by AbortSignal passed to abortWhen()');
+            if (source.aborted) {
+                this.abort(reason());
+                return this;
+            }
+            const onAbort = () => this.abort(reason());
+            source.addEventListener('abort', onAbort, { once: true });
+            this.__abortWhenCleanups__.push(() => source.removeEventListener('abort', onAbort));
+            return this;
+        }
+        if (typeof source === 'object' && source !== null && typeof source.then === 'function') {
+            const reason = new AbortException('Request aborted by Promise passed to abortWhen()');
+            let cancelled = false;
+            this.__abortWhenCleanups__.push(() => {
+                cancelled = true;
+            });
+            void Promise.resolve(source).then(() => {
+                if (!cancelled)
+                    this.abort(reason);
+            }, () => {
+                if (!cancelled)
+                    this.abort(reason);
+            });
+            return this;
+        }
+        throw new InvalidArgumentsExceptions();
+    }
+    __clearAbortWhenCleanups__() {
+        const cleanups = this.__abortWhenCleanups__;
+        this.__abortWhenCleanups__ = [];
+        for (const cleanup of cleanups)
+            cleanup();
+    }
     async run() {
+        if (this.__aborted__) {
+            this.__settled__ = true;
+            this.__clearAbortWhenCleanups__();
+            throw this.__abortReason__;
+        }
         const headers = new Headers();
         for (const [key, value] of this.requestContext.headers.entries()) {
             headers.append(key, value);
@@ -100,69 +182,98 @@ export class Core {
             },
             [ABORT_PROPERTY]: undefined,
             abort(reason) {
+                // Mark the request as aborted, so pending retries are stopped
+                this[SESSION_ABORTED_PROPERTY] = reason;
+                this[SESSION_ABORT_CONTROLLER_PROPERTY]?.abort(reason);
                 const abortController = this[ABORT_PROPERTY];
-                if (abortController) {
+                if (abortController)
                     abortController.abort(reason);
-                }
             },
         };
+        const sessionAbortController = new AbortController();
+        this.__sessionAbortController__ = sessionAbortController;
+        this.__activeContext__ = ctx;
+        ctx[SESSION_ABORT_CONTROLLER_PROPERTY] = sessionAbortController;
         const middleware = composeMiddleware([...this.__prepend_middlewares__, ...this.__append_middlewares__]);
-        await middleware(ctx, async function emptyNext() { });
-        const output = ctx[OUTPUT_PROPERTY];
-        if (ctx.options.resolveWithFullResponse || ctx.options.resolveWith === 'response') {
-            return ctx.response?.clone();
-        }
-        const response = ctx.response;
-        if (!response) {
-            return (OUTPUT_PROPERTY in ctx) ? output : undefined;
-        }
-        if (ctx.options.resolveWith === 'text') {
-            return await response.text();
-        }
-        else if (ctx.options.resolveWith === 'json') {
-            return unwrap(await response.json());
-        }
-        else if (ctx.options.resolveWith === 'form-data') {
-            return await response.formData();
-        }
-        else if (ctx.options.resolveWith === 'blob') {
-            return await response.blob();
-        }
-        else if (ctx.options.resolveWith === 'array-buffer') {
-            return await response.arrayBuffer();
-        }
-        if (OUTPUT_PROPERTY in ctx) {
-            return output;
-        }
-        if (response.status === 204) {
-            // 204: NO CONTENT
-            return undefined;
-        }
-        const contentType = response.headers.get('content-type') || '';
         try {
-            if (contentType.includes('application/json')) {
+            await middleware(ctx, async function emptyNext() { });
+            if (this.__aborted__)
+                throw this.__abortReason__;
+            const output = ctx[OUTPUT_PROPERTY];
+            if (ctx.options.resolveWithFullResponse || ctx.options.resolveWith === 'response') {
+                return ctx.response?.clone();
+            }
+            const response = ctx.response;
+            if (!response) {
+                return (OUTPUT_PROPERTY in ctx) ? output : undefined;
+            }
+            if (ctx.options.resolveWith === 'text') {
+                return await response.text();
+            }
+            else if (ctx.options.resolveWith === 'json') {
                 return unwrap(await response.json());
             }
-            else if (contentType.includes('multipart/form-data')) {
+            else if (ctx.options.resolveWith === 'form-data') {
                 return await response.formData();
             }
-            else if (contentType.includes('plain/text')) {
-                return await response.text();
+            else if (ctx.options.resolveWith === 'blob') {
+                return await response.blob();
+            }
+            else if (ctx.options.resolveWith === 'array-buffer') {
+                return await response.arrayBuffer();
+            }
+            if (OUTPUT_PROPERTY in ctx) {
+                return output;
             }
+            if (response.status === 204) {
+                // 204: NO CONTENT
+                return undefined;
+            }
+            const contentType = response.headers.get('content-type') || '';
+            try {
+                if (contentType.includes('application/json')) {
+                    return unwrap(await response.json());
+                }
+                else if (contentType.includes('multipart/form-data')) {
+                    return await response.formData();
+                }
+                else if (contentType.includes('plain/text')) {
+                    return await response.text();
+                }
+            }
+            catch (e) {
+                console.warn('Failed to auto parse response body', e);
+            }
+            /**
+             * Unable to parse response body
+             * Return undefined
+             * Enable users to discover the problem
+             * And modify the method of parsing response
+             */
+            return undefined;
         }
-        catch (e) {
-            console.warn('Failed to auto parse response body', e);
+        catch (error) {
+            if (this.__aborted__)
+                throw this.__abortReason__;
+            throw error;
+        }
+        finally {
+            if (this.__activeContext__ === ctx)
+                this.__activeContext__ = undefined;
+            if (this.__sessionAbortController__ === sessionAbortController)
+                this.__sessionAbortController__ = undefined;
+            this.__settled__ = true;
+            this.__clearAbortWhenCleanups__();
         }
-        /**
-         * Unable to parse response body
-         * Return undefined
-         * Enable users to discover the problem
-         * And modify the method of parsing response
-         */
-        return undefined;
     }
-    async end() {
-        return this.run();
+    end() {
+        if (!this.requestPromise) {
+            this.requestPromise = this.run();
+            // `end()` can be used to send the request without awaiting the result,
+            // mark the rejection as handled to avoid an unhandled rejection
+            void this.requestPromise.catch(() => { });
+        }
+        return this.requestPromise;
     }
     /**
      * Attaches callbacks for the resolution and/or rejection of the Promise.
@@ -171,9 +282,7 @@ export class Core {
      * @returns A Promise for the completion of which ever callback is executed.
      */
     then(onfulfilled, onrejected) {
-        if (!this.requestPromise)
-            this.requestPromise = this.end();
-        return this.requestPromise.then(onfulfilled, onrejected);
+        return this.end().then(onfulfilled, onrejected);
     }
     catch(onrejected) {
         return this.end().catch(onrejected);

package/dist/esm/src/exception/abort.exception.d.ts

@@ -0,0 +1,3 @@
+export declare class AbortException extends DOMException {
+    constructor(message?: string);
+}

package/dist/esm/src/exception/abort.exception.js

@@ -0,0 +1,6 @@
+export class AbortException extends DOMException {
+    constructor(message = 'Request aborted') {
+        super(message, 'AbortError');
+        Object.setPrototypeOf(this, AbortException.prototype);
+    }
+}

package/dist/esm/src/index.d.ts

@@ -1,3 +1,4 @@
+export { AbortException } from './exception/abort.exception.js';
 export { createRequest } from './create-request.js';
 export { Keq } from './keq.js';
 export { request } from './request.js';

package/dist/esm/src/index.js

@@ -1,3 +1,4 @@
+export { AbortException } from './exception/abort.exception.js';
 export { createRequest } from './create-request.js';
 export { Keq } from './keq.js';
 export { request } from './request.js';

package/dist/esm/src/is/is-abort-signal.d.ts

@@ -0,0 +1 @@
+export declare function isAbortSignal(value: unknown): value is AbortSignal;

package/dist/esm/src/is/is-abort-signal.js

@@ -0,0 +1,8 @@
+export function isAbortSignal(value) {
+    if (typeof AbortSignal !== 'undefined' && value instanceof AbortSignal)
+        return true;
+    return typeof value === 'object' && value !== null
+        && typeof value.aborted === 'boolean'
+        && typeof value.addEventListener === 'function'
+        && typeof value.removeEventListener === 'function';
+}

package/dist/esm/src/middlewares/fetch-arguments-middleware.js

@@ -1,5 +1,5 @@
 import { Exception } from '../exception/exception.js';
-import { ABORT_PROPERTY } from '../constant.js';
+import { ABORT_PROPERTY, SESSION_ABORTED_PROPERTY } from '../constant.js';
 import { isBuffer } from "../is/is-buffer.js";
 import { isBlob } from "../is/is-blob.js";
 import { isArrayBuffer } from "../is/is-array-buffer.js";
@@ -81,6 +81,10 @@ export function fetchArgumentsMiddleware() {
         }
         const abortController = new AbortController();
         ctx[ABORT_PROPERTY] = abortController;
+        // The request may have been aborted before the abort controller was created
+        const sessionAbortReason = ctx[SESSION_ABORTED_PROPERTY];
+        if (sessionAbortReason)
+            abortController.abort(sessionAbortReason);
         const requestInit = {
             method: request.method.toUpperCase(),
             headers: request.headers,

package/dist/esm/src/middlewares/retry-middleware.js

@@ -1,5 +1,16 @@
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+import { SESSION_ABORTED_PROPERTY, SESSION_ABORT_CONTROLLER_PROPERTY } from '../constant.js';
+function sleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => finish(), ms);
+        function finish() {
+            clearTimeout(timer);
+            signal?.removeEventListener('abort', finish);
+            resolve();
+        }
+        signal?.addEventListener('abort', finish, { once: true });
+    });
 }
 export function retryMiddleware() {
     return async function retryMiddleware(ctx, next) {
@@ -27,6 +38,9 @@ export function retryMiddleware() {
             retryOn: undefined,
         };
         for (let i = 0; i < retryTimes; i++) {
+            // The request has been aborted by user, stop retrying
+            if (ctx[SESSION_ABORTED_PROPERTY])
+                throw ctx[SESSION_ABORTED_PROPERTY];
             let err = null;
             try {
                 ctx.fetchArguments = undefined;
@@ -39,6 +53,9 @@ export function retryMiddleware() {
             catch (e) {
                 err = e;
             }
+            // The request has been aborted by user, stop retrying
+            if (ctx[SESSION_ABORTED_PROPERTY])
+                throw ctx[SESSION_ABORTED_PROPERTY];
             if (i === retryTimes - 1) {
                 if (err)
                     throw err;
@@ -53,7 +70,7 @@ export function retryMiddleware() {
             ctx.retry = { attempt: i, error: err, delay };
             ctx.emitter.emit('retry', ctx);
             if (delay > 0)
-                await sleep(delay);
+                await sleep(delay, ctx[SESSION_ABORT_CONTROLLER_PROPERTY]?.signal);
         }
     };
 }

package/dist/esm/src/middlewares/timeout-middleware.js

@@ -1,3 +1,4 @@
+import { ABORT_PROPERTY } from '../constant.js';
 export function timeoutMiddleware() {
     return async function timeoutMiddleware(ctx, next) {
         if (!ctx.options.timeout || ctx.options.timeout.millisecond <= 0) {
@@ -8,7 +9,8 @@ export function timeoutMiddleware() {
         ctx.emitter.on('fetch', (ctx) => {
             setTimeout(() => {
                 const err = new DOMException(`keq request timeout(${millisecond}ms)`, 'AbortError');
-                ctx.abort(err);
+                // Only abort the current attempt, so that the retry middleware can retry
+                ctx[ABORT_PROPERTY]?.abort(err);
             }, millisecond);
         });
         await next();

package/dist/esm/src/types/keq-context.d.ts

@@ -1,4 +1,4 @@
-import { ABORT_PROPERTY, OUTPUT_PROPERTY } from '../constant.js';
+import { ABORT_PROPERTY, OUTPUT_PROPERTY, SESSION_ABORTED_PROPERTY, SESSION_ABORT_CONTROLLER_PROPERTY } from '../constant.js';
 import type { Emitter } from 'mitt';
 import type { KeqOptionsParameter } from './keq-options.js';
 import type { KeqEvents } from './keq-events.js';
@@ -23,6 +23,15 @@ export interface KeqContext {
     };
     [ABORT_PROPERTY]?: AbortController;
     abort: (reason: any) => void;
+    /**
+     * The reason of the request being aborted by user (abort/abortWhen)
+     */
+    [SESSION_ABORTED_PROPERTY]?: any;
+    /**
+     * Aborts when the request is aborted (abort/abortWhen or context.abort()),
+     * used by middlewares (e.g. retry) to interrupt pending work
+     */
+    [SESSION_ABORT_CONTROLLER_PROPERTY]?: AbortController;
     /**
      * The unique identifier of the request's location in the code
      * @readonly

package/dist/esm/src/types/keq-context.js

@@ -1,2 +1,2 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
-import { ABORT_PROPERTY, OUTPUT_PROPERTY } from '../constant.js';
+import { ABORT_PROPERTY, OUTPUT_PROPERTY, SESSION_ABORTED_PROPERTY, SESSION_ABORT_CONTROLLER_PROPERTY } from '../constant.js';

package/dist/umd/src/constant.d.ts

@@ -1,2 +1,4 @@
 export declare const OUTPUT_PROPERTY: unique symbol;
 export declare const ABORT_PROPERTY: unique symbol;
+export declare const SESSION_ABORTED_PROPERTY: unique symbol;
+export declare const SESSION_ABORT_CONTROLLER_PROPERTY: unique symbol;

package/dist/umd/src/constant.js

@@ -9,7 +9,9 @@
 })(function (require, exports) {
     "use strict";
     Object.defineProperty(exports, "__esModule", { value: true });
-    exports.ABORT_PROPERTY = exports.OUTPUT_PROPERTY = void 0;
+    exports.SESSION_ABORT_CONTROLLER_PROPERTY = exports.SESSION_ABORTED_PROPERTY = exports.ABORT_PROPERTY = exports.OUTPUT_PROPERTY = void 0;
     exports.OUTPUT_PROPERTY = Symbol('outputProperty');
     exports.ABORT_PROPERTY = Symbol('abortProperty');
+    exports.SESSION_ABORTED_PROPERTY = Symbol('sessionAbortedProperty');
+    exports.SESSION_ABORT_CONTROLLER_PROPERTY = Symbol('sessionAbortControllerProperty');
 });

package/dist/umd/src/core.d.ts

@@ -12,6 +12,18 @@ export declare class Core<OUTPUT> {
      */
     __identifier__: string;
     private requestPromise?;
+    /** Whether abort() has been called on this request. */
+    private __aborted__;
+    /** The reason passed to abort(). */
+    private __abortReason__;
+    /** The context of the running attempt, used to abort the in-flight fetch. */
+    private __activeContext__?;
+    /** Aborts as soon as abort() is called, used to interrupt retry delays. */
+    private __sessionAbortController__?;
+    /** Cleanup callbacks registered by abortWhen(). */
+    private __abortWhenCleanups__;
+    /** Whether the request has settled (resolved or rejected). */
+    private __settled__;
     protected requestContext: Omit<KeqContextRequest, 'abort' | '__url__'>;
     protected __listeners__: KeqListeners;
     protected __global__: Record<string, any>;
@@ -22,6 +34,24 @@ export declare class Core<OUTPUT> {
     prependMiddlewares(...middlewares: KeqMiddleware[]): this;
     appendMiddlewares(...middlewares: KeqMiddleware[]): this;
     on<K extends keyof KeqEvents>(event: K, listener: (data: KeqEvents[K]) => void): this;
+    /**
+     * Abort the request manually.
+     *
+     * The request rejects with the given reason (an AbortException by default),
+     * and no further retry is performed. It is safe to call abort() before the
+     * request is sent.
+     *
+     * @description 手动中止请求
+     */
+    abort(reason?: any): void;
+    /**
+     * Abort the request when the given AbortSignal aborts,
+     * or when the given Promise settles (resolves or rejects).
+     *
+     * @description 当 signal 中止或 promise 完成时终止请求
+     */
+    abortWhen(source: AbortSignal | PromiseLike<unknown>): this;
+    private __clearAbortWhenCleanups__;
     private run;
     end(): Promise<OUTPUT>;
     /**