keq 5.2.1 → 5.3.0

package/dist/index.js

@@ -32,8 +32,6 @@ let qs = require("qs");
 qs = __toESM(qs);
 let picomatch = require("picomatch");
 picomatch = __toESM(picomatch);
-let fastq = require("fastq");
-fastq = __toESM(fastq);
 //#region src/exception/exception.ts
 var Exception = class extends ts_custom_error.CustomError {
 	constructor(message) {
@@ -349,10 +347,6 @@ var GatewayTimeoutException = class extends RequestException {
 	}
 };
 //#endregion
-//#region src/utils/base64.ts
-const base64Encode = globalThis.btoa || ((str) => Buffer.from(str).toString("base64"));
-globalThis.atob;
-//#endregion
 //#region src/validator/validator.ts
 /**
 * Validator 类用于类型检查
@@ -437,6 +431,13 @@ var Validator = class Validator {
 		return Validator.isObject(obj) && Validator.isFunction(obj["append"]) && Validator.isFunction(obj["delete"]) && Validator.isFunction(obj["entries"]) && Validator.isFunction(obj["forEach"]) && Validator.isFunction(obj["get"]) && Validator.isFunction(obj["getAll"]) && Validator.isFunction(obj["has"]) && Validator.isFunction(obj["keys"]) && Validator.isFunction(obj["set"]) && Validator.isFunction(obj["values"]) && Validator.isFunction(obj["sort"]) && Validator.isFunction(obj["toString"]);
 	}
 	/**
+	* 检查是否为 AbortSignal
+	*/
+	static isAbortSignal(obj) {
+		if (typeof AbortSignal !== "undefined" && obj instanceof AbortSignal) return true;
+		return Validator.isObject(obj) && typeof obj["aborted"] === "boolean" && Validator.isFunction(obj["addEventListener"]) && Validator.isFunction(obj["removeEventListener"]);
+	}
+	/**
 	* 检查是否为合法的 Header 值
 	* 允许范围: HTAB(\t), 0x20-0x7E, 0x80-0xFF
 	* 禁止换行等控制字符
@@ -464,11 +465,6 @@ function shallowClone(obj) {
 	return obj;
 }
 //#endregion
-//#region src/utils/sleep.ts
-function sleep(ms) {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-//#endregion
 //#region src/request-init/utils/clone-body.ts
 function cloneBody(obj) {
 	if (Validator.isFormData(obj)) {
@@ -1105,7 +1101,14 @@ function fixContentType(contentType) {
 function getLocationId(depth = 0) {
 	const err = /* @__PURE__ */ new Error();
 	if (!err.stack) return "";
-	return err.stack.split("\n")[depth + 2].trim();
+	const lines = err.stack.split("\n");
+	const offset = depth + 2;
+	if (lines[offset]) return lines[offset].trim();
+	for (let i = lines.length - 1; i >= 0; i--) {
+		const line = lines[i].trim();
+		if (line) return line;
+	}
+	return "";
 }
 //#endregion
 //#region src/request/utils/resolve-with.ts
@@ -1227,6 +1230,15 @@ var Core = class extends Promise {
 		_defineProperty(this, "__reject__", void 0);
 		_defineProperty(this, "__triggered__", false);
 		_defineProperty(this, "__requestPromise__", void 0);
+		_defineProperty(this, "__aborted__", false);
+		_defineProperty(this, "__abortReason__", void 0);
+		_defineProperty(this, "__activeSharedContext__", void 0);
+		_defineProperty(this, "__resolveAbort__", void 0);
+		_defineProperty(this, "__abortPromise__", new Promise((resolve) => {
+			this.__resolveAbort__ = resolve;
+		}));
+		_defineProperty(this, "__abortWhenCleanups__", []);
+		_defineProperty(this, "__settled__", false);
 		_defineProperty(this, "requestInit", void 0);
 		_defineProperty(this, "__listeners__", {});
 		_defineProperty(this, "__global__", void 0);
@@ -1269,6 +1281,63 @@ var Core = class extends Promise {
 		for (const [key, value] of Object.entries(opts)) this.__options__[key] = value;
 		return this;
 	}
+	/**
+	* Abort the request manually.
+	*
+	* The request rejects with the given reason (an {@link AbortException} by default),
+	* the `abort` event is emitted, and no further retry is performed.
+	* It is safe to call `abort()` before the request is sent: the request will be
+	* aborted as soon as it starts.
+	*
+	* @description 手动中止请求
+	* @param reason Abort reason. Defaults to `new AbortException('Request aborted')`.
+	*/
+	abort(reason = new AbortException("Request aborted")) {
+		if (this.__aborted__) return;
+		this.__aborted__ = true;
+		this.__abortReason__ = reason;
+		this.__resolveAbort__(reason);
+		this.__activeSharedContext__?.request.abort(reason);
+		this.__clearAbortWhenCleanups__();
+	}
+	/**
+	* Abort the request when the given `AbortSignal` aborts,
+	* or when the given `Promise` settles (resolves or rejects).
+	*
+	* It is designed for the normal `await` flow, so business code
+	* does not need to call `.fire()` first:
+	* `await request.get('/api/cats').abortWhen(signal)`.
+	*
+	* @description 当 signal 中止或 promise 完成时终止请求
+	*/
+	abortWhen(source) {
+		if (this.__aborted__ || this.__settled__) return this;
+		if (Validator.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 (Validator.isObject(source) && typeof source.then === "function") {
+			const reason = new AbortException("Request aborted by Promise passed to abortWhen()");
+			let cancelled = false;
+			this.__abortWhenCleanups__.push(() => {
+				cancelled = true;
+			});
+			Promise.resolve(source).then(() => {
+				if (!cancelled) this.abort(reason);
+			}, () => {
+				if (!cancelled) this.abort(reason);
+			});
+			return this;
+		}
+		throw new TypeException("abortWhen() expects an AbortSignal or a Promise");
+	}
 	derive() {
 		const derived = new this.constructor(this.requestInit.url, {
 			method: this.requestInit.method,
@@ -1305,68 +1374,103 @@ var Core = class extends Promise {
 			const listeners = this.__listeners__[eventName];
 			for (const listener of listeners) coreContext.emitter.on(eventName, listener);
 		}
+		this.__activeSharedContext__ = coreContext;
+		if (this.__aborted__) coreContext.request.abort(this.__abortReason__);
 		return coreContext;
 	}
 	async run() {
 		let attempt;
-		while (true) {
-			const attemptWithDefault = attempt || 0;
-			const sharedContext = this.buildSharedContext();
-			const orchestrator = new KeqMiddlewareOrchestrator(sharedContext, this.__middlewares__);
-			if (attempt !== void 0) sharedContext.data.retry = { attempt };
-			if (attempt && attempt >= 1) sharedContext.emitter.emit("retry", { context: sharedContext });
-			let error = null;
-			try {
-				await orchestrator.execute();
-			} catch (err) {
-				error = err;
-			}
-			const retryOn = typeof sharedContext.options.retry?.on === "function" ? sharedContext.options.retry.on : (attempt, error) => {
-				if (error instanceof RequestException && error.fatal) return false;
-				return !!error;
-			};
-			let retryTimes = sharedContext.options.retry?.times || 0;
-			if (retryTimes) {
-				if (retryTimes < 0) retryTimes = 0;
-				else if (!Number.isInteger(retryTimes)) retryTimes = Math.floor(retryTimes);
-			}
-			if (attemptWithDefault >= retryTimes || await retryOn(attemptWithDefault, error, sharedContext) === false) {
-				if (error) {
+		try {
+			while (true) {
+				if (this.__aborted__ && attempt !== void 0) throw this.__abortReason__;
+				const attemptWithDefault = attempt || 0;
+				const sharedContext = this.buildSharedContext();
+				const orchestrator = new KeqMiddlewareOrchestrator(sharedContext, this.__middlewares__);
+				if (attempt !== void 0) sharedContext.data.retry = { attempt };
+				if (attempt && attempt >= 1) sharedContext.emitter.emit("retry", { context: sharedContext });
+				let error = null;
+				try {
+					await orchestrator.execute();
+				} catch (err) {
+					error = err;
+				}
+				if (this.__aborted__) {
+					const reason = error ?? this.__abortReason__;
 					sharedContext.emitter.emit("error", { context: sharedContext });
-					throw error;
+					throw reason;
+				}
+				const retryOn = typeof sharedContext.options.retry?.on === "function" ? sharedContext.options.retry.on : (attempt, error) => {
+					if (error instanceof RequestException && error.fatal) return false;
+					return !!error;
+				};
+				let retryTimes = sharedContext.options.retry?.times || 0;
+				if (retryTimes) {
+					if (retryTimes < 0) retryTimes = 0;
+					else if (!Number.isInteger(retryTimes)) retryTimes = Math.floor(retryTimes);
+				}
+				if (attemptWithDefault >= retryTimes || await retryOn(attemptWithDefault, error, sharedContext) === false) {
+					if (error) {
+						sharedContext.emitter.emit("error", { context: sharedContext });
+						throw error;
+					}
+					return sharedContext;
 				}
-				return sharedContext;
+				const retryDelay = typeof sharedContext.options.retry?.delay === "function" ? await sharedContext.options.retry.delay(attemptWithDefault, error, sharedContext) : sharedContext.options.retry?.delay || 0;
+				if (retryDelay) await new Promise((resolve) => {
+					const timer = setTimeout(resolve, retryDelay);
+					this.__abortPromise__.then(() => {
+						clearTimeout(timer);
+						resolve();
+					});
+				});
+				attempt = attemptWithDefault + 1;
 			}
-			const retryDelay = typeof sharedContext.options.retry?.delay === "function" ? await sharedContext.options.retry.delay(attemptWithDefault, error, sharedContext) : sharedContext.options.retry?.delay || 0;
-			if (retryDelay) await sleep(retryDelay);
-			attempt = attemptWithDefault + 1;
+		} finally {
+			this.__activeSharedContext__ = void 0;
 		}
 	}
 	__execute__() {
 		if (!this.__requestPromise__) this.__requestPromise__ = (async () => {
-			const coreContext = await this.run();
-			const resolveWithMode = coreContext.options.resolveWith;
-			if (resolveWithMode === "response") return coreContext.response?.clone();
-			const response = coreContext.response;
-			if (!resolveWithMode || resolveWithMode === "intelligent") {
-				const output = coreContext.output;
-				if (output !== void 0) return output;
-				return await intelligentParseResponse(response);
+			try {
+				const coreContext = await this.run();
+				const resolveWithMode = coreContext.options.resolveWith;
+				if (resolveWithMode === "response") return coreContext.response?.clone();
+				const response = coreContext.response;
+				if (!resolveWithMode || resolveWithMode === "intelligent") {
+					const output = coreContext.output;
+					if (output !== void 0) return output;
+					return await intelligentParseResponse(response);
+				}
+				if (!response) throw new Exception([
+					`Unable to process the response with '${resolveWithMode}'. Possible causes:`,
+					"1. The request was never initiated or sent",
+					"2. The request failed before a response was received."
+				].join("\n"));
+				return await resolveWith(response, resolveWithMode);
+			} finally {
+				this.__settled__ = true;
+				this.__clearAbortWhenCleanups__();
 			}
-			if (!response) throw new Exception([
-				`Unable to process the response with '${resolveWithMode}'. Possible causes:`,
-				"1. The request was never initiated or sent",
-				"2. The request failed before a response was received."
-			].join("\n"));
-			return await resolveWith(response, resolveWithMode);
 		})();
 		return this.__requestPromise__;
 	}
+	__clearAbortWhenCleanups__() {
+		const cleanups = this.__abortWhenCleanups__;
+		this.__abortWhenCleanups__ = [];
+		for (const cleanup of cleanups) cleanup();
+	}
+	/**
+	* Trigger the request without waiting for the result.
+	*
+	* Returns the request instance itself, so the handler can still be used later,
+	* for example `request.get('/api/cats').fire().abort()`.
+	*/
 	fire() {
 		if (!this.__triggered__) {
 			this.__triggered__ = true;
 			this.__execute__().then(this.__resolve__, this.__reject__);
 		}
+		return this;
 	}
 	/** @deprecated Await the Keq instance directly or use `.fire()` for fire-and-forget. */
 	end() {
@@ -1387,6 +1491,53 @@ var Core = class extends Promise {
 	}
 };
 //#endregion
+//#region src/utils/base64.ts
+const base64Encode = globalThis.btoa || ((str) => Buffer.from(str).toString("base64"));
+globalThis.atob;
+//#endregion
+//#region src/utils/semaphore.ts
+/**
+* Concurrency limiter that preserves the caller's async context.
+*
+* @description
+* 并发限流器。等待者 await 属于自己的 Promise，`release()` 仅负责 resolve，
+* 因此等待者在自己的 async context 中恢复 —— Node 的 AsyncLocalStorage
+* 上下文得以保留。这是它与 fastq 等「由前一个任务的完成回调驱动下一个任务」
+* 的队列实现的关键区别。
+*/
+var Semaphore = class {
+	constructor(concurrency) {
+		this.concurrency = concurrency;
+		_defineProperty(this, "running", 0);
+		_defineProperty(this, "waiters", []);
+		if (!Number.isInteger(concurrency) || concurrency < 1) throw new TypeError("Semaphore concurrency must be a positive integer");
+	}
+	/**
+	* Acquire a slot, waiting until one is released if the limit is reached.
+	*
+	* @description 获取一个名额。若已达并发上限，则等待直到有名额释放。
+	*/
+	async acquire() {
+		if (this.running < this.concurrency) {
+			this.running++;
+			return;
+		}
+		await new Promise((resolve) => {
+			this.waiters.push(resolve);
+		});
+	}
+	/**
+	* Release a slot, handing it directly to the next waiter when one exists.
+	*
+	* @description 释放名额。存在等待者时直接移交名额（不减计数），否则减少计数。
+	*/
+	release() {
+		const waiter = this.waiters.shift();
+		if (waiter) waiter();
+		else if (this.running > 0) this.running--;
+	}
+};
+//#endregion
 //#region src/request/keq.ts
 /**
 * extends Core to provide a fluent API for building HTTP requests
@@ -1768,10 +1919,14 @@ function keqSerialFlowControlMiddleware() {
 		const key = typeof signal === "string" ? signal : signal(ctx);
 		if (!ctx.global.core) ctx.global.core = {};
 		if (!ctx.global.core.serialFlowControl) ctx.global.core.serialFlowControl = {};
-		if (!ctx.global.core.serialFlowControl[key]) ctx.global.core.serialFlowControl[key] = fastq.promise(async ({ next }) => {
+		if (!ctx.global.core.serialFlowControl[key]) ctx.global.core.serialFlowControl[key] = new Semaphore(concurrent);
+		const semaphore = ctx.global.core.serialFlowControl[key];
+		await semaphore.acquire();
+		try {
 			await next();
-		}, concurrent);
-		await ctx.global.core.serialFlowControl[key].push({ next });
+		} finally {
+			semaphore.release();
+		}
 	};
 }
 //#endregion
@@ -1987,6 +2142,7 @@ exports.PreconditionFailedException = PreconditionFailedException;
 exports.ProxyAuthenticationRequiredException = ProxyAuthenticationRequiredException;
 exports.RequestException = RequestException;
 exports.RequestTimeoutException = RequestTimeoutException;
+exports.Semaphore = Semaphore;
 exports.ServiceUnavailableException = ServiceUnavailableException;
 exports.TimeoutException = TimeoutException;
 exports.TooManyRequestsException = TooManyRequestsException;