keq 5.0.0-beta.9 → 5.0.1

package/dist/index.mjs

@@ -37,6 +37,14 @@ var TimeoutException = class extends AbortException {
 	}
 };
 //#endregion
+//#region src/exception/mutex.exception.ts
+var MutexException = class extends Exception {
+	constructor(message) {
+		super(message);
+		Object.defineProperty(this, "name", { value: "MutexException" });
+	}
+};
+//#endregion
 //#region \0@oxc-project+runtime@0.127.0/helpers/typeof.js
 function _typeof(o) {
 	"@babel/helpers - typeof";
@@ -77,13 +85,18 @@ function _defineProperty(e, r, t) {
 //#endregion
 //#region src/exception/http-exceptions/request.exception.ts
 var RequestException = class extends Exception {
+	/** @deprecated Use `fatal` instead. `retry === true` is equivalent to `fatal === false`. */
+	get retry() {
+		return !this.fatal;
+	}
 	constructor(statusCode, message, options) {
 		super(message);
 		_defineProperty(this, "statusCode", void 0);
-		_defineProperty(this, "retry", void 0);
+		_defineProperty(this, "fatal", void 0);
 		_defineProperty(this, "response", void 0);
+		if (typeof options === "boolean") options = { fatal: !options };
 		this.statusCode = statusCode;
-		this.retry = !options?.fatal;
+		this.fatal = options?.fatal ?? false;
 		this.response = options?.response;
 		Object.defineProperty(this, "name", { value: "RequestException" });
 	}
@@ -849,6 +862,10 @@ var KeqSharedContext = class {
 	get locationId() {
 		return this[ContextLocationIdProperty];
 	}
+	/** @deprecated Use `locationId` instead */
+	get identifier() {
+		return this[ContextLocationIdProperty];
+	}
 	get request() {
 		return this[ContextRequestProperty];
 	}
@@ -1086,8 +1103,9 @@ async function intelligentParseResponse(response) {
 	try {
 		if (contentType.match(/^application\/(.+\+)?json/)) return resolveWith(response, "json");
 		else if (contentType.includes("multipart/form-data")) return resolveWith(response, "form-data");
-		else if (contentType.includes("plain/text")) return resolveWith(response, "text");
+		else if (contentType.startsWith("text/") && !contentType.includes("text/event-stream")) return resolveWith(response, "text");
 		else if (contentType.includes("text/event-stream")) return resolveWith(response, "sse");
+		else if (contentType.startsWith("image/") || contentType.startsWith("audio/") || contentType.startsWith("video/") || contentType.startsWith("font/") || contentType === "application/octet-stream" || contentType === "application/pdf") return resolveWith(response, "array-buffer");
 	} catch (err) {
 		console.warn(`Failed to intelligent parse response body: ${response.url}`, err);
 		throw err;
@@ -1277,7 +1295,7 @@ var Core = class extends Promise {
 				error = err;
 			}
 			const retryOn = typeof sharedContext.options.retry?.on === "function" ? sharedContext.options.retry.on : (attempt, error) => {
-				if (error instanceof RequestException && error.retry === false) return false;
+				if (error instanceof RequestException && error.fatal) return false;
 				return !!error;
 			};
 			let retryTimes = sharedContext.options.retry?.times || 0;
@@ -1323,6 +1341,16 @@ var Core = class extends Promise {
 			this.__execute__().then(this.__resolve__, this.__reject__);
 		}
 	}
+	/** @deprecated Await the Keq instance directly or use `.fire()` for fire-and-forget. */
+	end() {
+		if (!this.__triggered__) {
+			this.__triggered__ = true;
+			this.__execute__().then(this.__resolve__, this.__reject__);
+		}
+		return new Promise((resolve, reject) => {
+			super.then(resolve, reject);
+		});
+	}
 	then(onfulfilled, onrejected) {
 		if (!this.__triggered__) {
 			this.__triggered__ = true;
@@ -1498,6 +1526,9 @@ function keqMethodRoute(method) {
 }
 //#endregion
 //#region src/router/keq-module-route.ts
+/**
+* @deprecated This function exists solely for backward compatibility with v2.
+*/
 function keqModuleRoute(moduleName) {
 	if (!moduleName) throw new Exception("Module name should not be empty");
 	return (ctx) => ctx.options.module?.name === moduleName;
@@ -1512,6 +1543,9 @@ function keqPathnameRoute(pathname) {
 }
 //#endregion
 //#region src/router/keq-router.ts
+/**
+* @deprecated Use `request.apply(...middlewares).forRoutes(...)` instead.
+*/
 var KeqRouter = class KeqRouter {
 	constructor(middlewares = []) {
 		this.middlewares = middlewares;
@@ -1592,6 +1626,83 @@ var KeqRouter = class KeqRouter {
 	}
 };
 //#endregion
+//#region src/router/utils/build-route.ts
+function buildRoute(pattern) {
+	const routes = [];
+	if (pattern.host) routes.push(keqHostRoute(pattern.host));
+	if (pattern.method) routes.push(keqMethodRoute(pattern.method));
+	if (pattern.pathname) routes.push(keqPathnameRoute(pattern.pathname));
+	if (routes.length === 0) {
+		const always = () => true;
+		always.__keqRouteName__ = "always";
+		return always;
+	}
+	if (routes.length === 1) return routes[0];
+	return composeRoute(routes);
+}
+//#endregion
+//#region src/router/utils/not-route.ts
+function notRoute(route) {
+	const negated = async (ctx) => !await route(ctx);
+	negated.__keqRouteName__ = `not(${route.__keqRouteName__ || route.name || "anonymous"})`;
+	return negated;
+}
+//#endregion
+//#region src/router/utils/or-route.ts
+function orRoute(routes) {
+	if (!routes.length) throw new Exception("At least one route");
+	const combined = async (ctx) => {
+		return (await Promise.all(routes.map((route) => route(ctx)))).some((result) => result === true);
+	};
+	combined.__keqRouteName__ = `or(${routes.map((r) => r.__keqRouteName__ || r.name || "anonymous").join(", ")})`;
+	return combined;
+}
+//#endregion
+//#region src/router/keq-middleware-applicator.ts
+function normalizeTarget(target) {
+	if (typeof target === "function") return target;
+	return buildRoute(target);
+}
+var KeqMiddlewareApplicator = class {
+	constructor(middlewares, registeredMiddlewares, returnValue) {
+		this.middlewares = middlewares;
+		this.registeredMiddlewares = registeredMiddlewares;
+		this.returnValue = returnValue;
+		_defineProperty(this, "excludedTargets", []);
+	}
+	exclude(...routes) {
+		this.excludedTargets.push(...routes);
+		return this;
+	}
+	forRoutes(...routes) {
+		const inclusionRoutes = routes.map(normalizeTarget);
+		const inclusionRoute = inclusionRoutes.length === 1 ? inclusionRoutes[0] : orRoute(inclusionRoutes);
+		let finalRoute;
+		if (this.excludedTargets.length > 0) {
+			const exclusionRoutes = this.excludedTargets.map(normalizeTarget);
+			finalRoute = composeRoute([inclusionRoute, notRoute(exclusionRoutes.length === 1 ? exclusionRoutes[0] : orRoute(exclusionRoutes))]);
+		} else finalRoute = inclusionRoute;
+		const composedMiddleware = this.middlewares.length > 1 ? composeMiddleware(this.middlewares) : this.middlewares[0];
+		this.registeredMiddlewares.push(async function routeApply(ctx, next) {
+			if (await finalRoute(ctx)) await composedMiddleware(ctx, next);
+			else await next();
+		});
+		return this.returnValue;
+	}
+	forAllRoutes() {
+		const composedMiddleware = this.middlewares.length > 1 ? composeMiddleware(this.middlewares) : this.middlewares[0];
+		if (this.excludedTargets.length > 0) {
+			const exclusionRoutes = this.excludedTargets.map(normalizeTarget);
+			const finalRoute = notRoute(exclusionRoutes.length === 1 ? exclusionRoutes[0] : orRoute(exclusionRoutes));
+			this.registeredMiddlewares.push(async function routeApply(ctx, next) {
+				if (await finalRoute(ctx)) await composedMiddleware(ctx, next);
+				else await next();
+			});
+		} else this.registeredMiddlewares.push(composedMiddleware);
+		return this.returnValue;
+	}
+};
+//#endregion
 //#region src/middlewares/timeout-middleware/index.ts
 function keqTimeoutMiddleware() {
 	return async function timeoutMiddleware(ctx, next) {
@@ -1660,9 +1771,34 @@ function keqAbortFlowControlMiddleware() {
 	};
 }
 //#endregion
+//#region src/middlewares/flow-control-middleware/mutex-flow-control-middleware.ts
+function keqMutexFlowControlMiddleware() {
+	return async function mutexFlowControlMiddleware(ctx, next) {
+		if (!ctx.options.flowControl || ctx.options.flowControl.mode !== "mutex") {
+			await next();
+			return;
+		}
+		const { signal } = ctx.options.flowControl;
+		const key = typeof signal === "string" ? signal : signal(ctx);
+		if (!ctx.global.core) ctx.global.core = {};
+		if (!ctx.global.core.mutexFlowControl) ctx.global.core.mutexFlowControl = /* @__PURE__ */ new Set();
+		if (ctx.global.core.mutexFlowControl.has(key)) throw new MutexException(`Request rejected by MutexFlowControl: a request with key "${key}" is already in-flight`);
+		ctx.global.core.mutexFlowControl.add(key);
+		try {
+			await next();
+		} finally {
+			ctx.global.core.mutexFlowControl.delete(key);
+		}
+	};
+}
+//#endregion
 //#region src/middlewares/flow-control-middleware/index.ts
 function keqFlowControlMiddleware() {
-	return composeMiddleware([keqSerialFlowControlMiddleware(), keqAbortFlowControlMiddleware()], { name: "flowControlMiddleware" });
+	return composeMiddleware([
+		keqMutexFlowControlMiddleware(),
+		keqSerialFlowControlMiddleware(),
+		keqAbortFlowControlMiddleware()
+	], { name: "flowControlMiddleware" });
 }
 //#endregion
 //#region src/middlewares/fetch-middleware/index.ts
@@ -1684,34 +1820,39 @@ function keqFetchMiddleware() {
 * Keq instance factory class,
 * and shares global data and middlewares across requests
 */
-var KeqRequest = class {
+var KeqRequest = class KeqRequest {
 	constructor(options) {
 		_defineProperty(this, "baseOrigin", void 0);
 		_defineProperty(this, "qs", void 0);
 		_defineProperty(this, "global", {});
-		_defineProperty(this, "preMiddlewares", []);
-		_defineProperty(this, "postMiddlewares", []);
+		_defineProperty(this, "middlewares", []);
+		_defineProperty(this, "__terminalMiddlewares__", []);
+		_defineProperty(this, "__parent__", void 0);
 		if (options?.baseOrigin) this.baseOrigin = options.baseOrigin;
 		else this.baseOrigin = Validator.isBrowser() ? location.origin : "http://127.0.0.1";
 		this.qs = options?.qs;
-		this.postMiddlewares = options?.postMiddlewares || [
+		this.__terminalMiddlewares__ = options?.terminalMiddlewares || [
 			keqFlowControlMiddleware(),
 			keqTimeoutMiddleware(),
 			keqFetchMiddleware()
 		];
-		this.preMiddlewares = options?.preMiddlewares || [];
+		this.middlewares = options?.middlewares || [];
 	}
 	__formatUrl__(url) {
 		if (typeof url === "string") return new URL(url, this.baseOrigin);
 		return new URL(url.href);
 	}
+	resolveMiddlewares() {
+		if (!this.__parent__) return this.middlewares;
+		return [...this.__parent__.resolveMiddlewares(), ...this.middlewares];
+	}
 	__fetch__(url, init, locationId) {
 		return new Keq(this.__formatUrl__(url), {
 			...init,
 			locationId,
 			global: this.global,
 			qs: this.qs,
-			middlewares: [...this.preMiddlewares, ...this.postMiddlewares]
+			middlewares: [...this.resolveMiddlewares(), ...this.__terminalMiddlewares__]
 		});
 	}
 	fetch(url, init) {
@@ -1742,11 +1883,37 @@ var KeqRequest = class {
 		return this.__fetch__(url, { method: "options" }, getLocationId(1));
 	}
 	use(firstMiddleware, ...middleware) {
-		this.preMiddlewares.push(firstMiddleware, ...middleware);
+		this.middlewares.push(firstMiddleware, ...middleware);
 		return this;
 	}
+	apply(middleware, ...additionalMiddlewares) {
+		return new KeqMiddlewareApplicator(Array.isArray(middleware) ? middleware : [middleware, ...additionalMiddlewares], this.middlewares, this);
+	}
+	/**
+	* @deprecated Use `request.apply(...middlewares).forRoutes(...)` instead.
+	*/
 	useRouter() {
-		return new KeqRouter(this.preMiddlewares);
+		return new KeqRouter(this.middlewares);
+	}
+	fork(options) {
+		const child = new KeqRequest({
+			baseOrigin: options?.baseOrigin ?? this.baseOrigin,
+			qs: options?.qs ?? (this.qs ? { ...this.qs } : void 0)
+		});
+		child.__parent__ = this;
+		return child;
+	}
+	inherit(parent) {
+		this.__parent__ = parent;
+		return this;
+	}
+	adopt(child) {
+		child.__parent__ = this;
+		return this;
+	}
+	/** @deprecated Use `middlewares` instead */
+	get preMiddlewares() {
+		return this.middlewares;
 	}
 	on(event, listener) {
 		const middleware = async (context, next) => {
@@ -1768,6 +1935,6 @@ function createRequest(options) {
 	return new KeqRequest(options);
 }
 //#endregion
-export { AbortException, BadGatewayException, BadRequestException, ConflictException, ContentTooLargeException, Exception, ForbiddenException, GatewayTimeoutException, ImATeapotException, InternalServerErrorException, Keq, KeqExecutionContext, KeqMiddlewareExecutor, KeqMiddlewareOrchestrator, KeqRequest, KeqSharedContext, MethodNotAllowedException, NotAcceptableException, NotFoundedException, NotImplementedException, PreconditionFailedException, ProxyAuthenticationRequiredException, RequestException, RequestTimeoutException, ServiceUnavailableException, TimeoutException, TooManyRequestsException, TypeException, UnauthorizedException, UnsupportedMediaTypeException, UriTooLongException, composeMiddleware, composeRoute, createProxyResponse, createRequest, request };
+export { AbortException, BadGatewayException, BadRequestException, ConflictException, ContentTooLargeException, Exception, ForbiddenException, GatewayTimeoutException, ImATeapotException, InternalServerErrorException, Keq, KeqExecutionContext, KeqMiddlewareApplicator, KeqMiddlewareExecutor, KeqMiddlewareOrchestrator, KeqRequest, KeqSharedContext, MethodNotAllowedException, NotAcceptableException, NotFoundedException, NotImplementedException, PreconditionFailedException, ProxyAuthenticationRequiredException, RequestException, RequestTimeoutException, ServiceUnavailableException, TimeoutException, TooManyRequestsException, TypeException, UnauthorizedException, UnsupportedMediaTypeException, UriTooLongException, composeMiddleware, composeRoute, createProxyResponse, createRequest, request };
 
 //# sourceMappingURL=index.mjs.map