@snail-js/api 0.1.28 → 1.0.0

package/dist/chunks/plugin-D3RDffDG.js

@@ -0,0 +1,742 @@
+import { AxiosHeaders } from "axios";
+//#region src/error/base.ts
+/**
+* Base class of every error `@snail-js/api` throws.
+*
+* A stable `code` is attached to each subclass so application code can branch
+* on `error.code` without importing the class, and so the localization layer can
+* render a translated message.
+*/
+var SnailError = class SnailError extends Error {
+	constructor(message, options = {}) {
+		super(message);
+		this.name = new.target.name;
+		this.code = options.code ?? "SNAIL_ERROR";
+		this.cause = options.cause;
+		if (typeof Error.captureStackTrace === "function") Error.captureStackTrace(this, new.target);
+	}
+	/** `true` for every error originating from this library. */
+	static isSnailError(value) {
+		return value instanceof SnailError;
+	}
+};
+//#endregion
+//#region src/error/decorator.ts
+/**
+* Thrown when a decorator is applied incorrectly — two request-method decorators
+* on one method, a parameter decorator on a constructor, and so on.
+*
+* These are programmer errors and always surface eagerly, as early as the
+* decorated class is evaluated.
+*/
+var SnailDecoratorError = class extends SnailError {
+	constructor(message, options = {}) {
+		super(message, {
+			code: "SNAIL_DECORATOR_ERROR",
+			cause: options.cause
+		});
+	}
+};
+//#endregion
+//#region src/utils/is.ts
+/** Runtime type predicates shared across the library. */
+/** `true` for a non-null object (including arrays, dates, class instances). */
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* `true` for a plain object literal — not an array, `Date`, `Map`, `FormData`,
+* `Blob`, class instance, and so on.
+*
+* Used to decide whether a `@Query()` / `@Data()` argument should be spread
+* into the outgoing payload.
+*/
+function isPlainObject(value) {
+	if (Object.prototype.toString.call(value) !== "[object Object]") return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === null || prototype === Object.prototype;
+}
+/** `true` for a callable value. */
+function isFunction(value) {
+	return typeof value === "function";
+}
+/** `true` for a thenable. */
+function isPromise(value) {
+	return isObject(value) && isFunction(value.then);
+}
+/** `true` when `value` is neither `null` nor `undefined`. */
+function isDefined(value) {
+	return value !== null && value !== void 0;
+}
+/** `true` when a `Response`-like body should be passed through untouched. */
+function isBinaryBody(value) {
+	if (typeof Blob !== "undefined" && value instanceof Blob) return true;
+	if (typeof ArrayBuffer !== "undefined" && value instanceof ArrayBuffer) return true;
+	if (typeof FormData !== "undefined" && value instanceof FormData) return true;
+	if (typeof URLSearchParams !== "undefined" && value instanceof URLSearchParams) return true;
+	if (typeof ReadableStream !== "undefined" && value instanceof ReadableStream) return true;
+	return false;
+}
+/** `true` when the code is executing in a DOM-capable browser. */
+function isBrowser() {
+	return typeof window !== "undefined" && typeof document !== "undefined";
+}
+//#endregion
+//#region src/utils/url.ts
+/** Uppercase the first character, leaving the rest untouched. */
+function capitalize(value) {
+	return value.length === 0 ? value : value[0].toUpperCase() + value.slice(1);
+}
+/** `true` when the url carries its own scheme or protocol-relative prefix. */
+function isAbsoluteURL(url) {
+	return /^([a-z][a-z\d+\-.]*:)?\/\//i.test(url);
+}
+/** Drop trailing slashes without touching a bare `"/"`. */
+function trimEndSlash(url) {
+	return url.replace(/\/+$/, "");
+}
+/** Drop leading slashes, keeping a bare `"/"` intact. */
+function trimStartSlash(url) {
+	return url.replace(/^\/+/, "");
+}
+/**
+* Join url segments into one path, normalising the slashes between them.
+*
+* An absolute `segment` wins outright, matching axios' `baseURL` semantics.
+*
+* ```ts
+* joinURL("/api/", "/user/", "/list") // "/api/user/list"
+* joinURL("/api", "https://cdn.x/y")  // "https://cdn.x/y"
+* ```
+*/
+function joinURL(...segments) {
+	const parts = segments.filter((segment) => typeof segment === "string" && segment.length > 0);
+	if (parts.length === 0) return "";
+	let result = parts[0];
+	for (const part of parts.slice(1)) {
+		if (isAbsoluteURL(part)) {
+			result = part;
+			continue;
+		}
+		if (result.length === 0) {
+			result = part;
+			continue;
+		}
+		result = `${trimEndSlash(result)}/${trimStartSlash(part)}`;
+	}
+	return result.replace(/([^:]\/)\/+/g, "$1");
+}
+/** Matches `:id` style placeholders, ignoring a leading `::` escape. */
+var PATH_PARAM_PATTERN = /:([A-Za-z_$][\w$]*)/g;
+/** Names of every `:placeholder` present in a route template. */
+function pathParamNames(route) {
+	const names = [];
+	for (const match of route.matchAll(PATH_PARAM_PATTERN)) names.push(match[1]);
+	return names;
+}
+/**
+* Substitute `:placeholder` segments with values.
+*
+* Values are URL-encoded. A placeholder with no value throws, because silently
+* leaving `:id` in a request path produces a confusing 404 far from the cause —
+* the pre-rewrite code logged to `console.error` and then threw anyway.
+*/
+function replacePathParams(route, values, onMissing) {
+	return route.replace(PATH_PARAM_PATTERN, (match, name) => {
+		const value = values[name];
+		if (value === void 0 || value === null) {
+			if (onMissing) onMissing(name);
+			return match;
+		}
+		return encodeURIComponent(String(value));
+	});
+}
+/** Build a full url, appending absolute urls verbatim. */
+function buildRequestURL(baseURL, url) {
+	if (isAbsoluteURL(url)) return url;
+	return joinURL(baseURL, url);
+}
+/** Strip the query string and hash, for logging. */
+function stripQuery(url) {
+	return url.split(/[?#]/, 1)[0];
+}
+/**
+* Deterministic, recursively stable JSON serialisation.
+*
+* Object keys are sorted so two logically identical payloads always produce the
+* same string — essential for cache keys and for request de-duplication.
+*/
+function stableStringify(value) {
+	const seen = /* @__PURE__ */ new WeakSet();
+	const walk = (input) => {
+		if (input === null) return "null";
+		const type = typeof input;
+		if (type === "number") return Number.isFinite(input) ? String(input) : "null";
+		if (type === "boolean") return String(input);
+		if (type === "bigint") return `"${String(input)}"`;
+		if (type === "string") return JSON.stringify(input);
+		if (type === "undefined") return "undefined";
+		if (type === "function" || type === "symbol") return "undefined";
+		if (input instanceof Date) return `"${input.toISOString()}"`;
+		if (input instanceof RegExp) return `"${input.toString()}"`;
+		if (Array.isArray(input)) return `[${input.map(walk).join(",")}]`;
+		if (isPlainObject(input)) {
+			const object = input;
+			if (seen.has(object)) return "\"[Circular]\"";
+			seen.add(object);
+			const body = Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${walk(object[key])}`).join(",");
+			seen.delete(object);
+			return `{${body}}`;
+		}
+		return JSON.stringify(String(input));
+	};
+	return walk(value);
+}
+/**
+* 32-bit FNV-1a hash rendered as base36.
+*
+* Cheap, allocation-light and stable across runs — used to turn a long request
+* signature into a compact in-memory cache key. It is *not* a security hash.
+*/
+function shortHash(input) {
+	let hash = 2166136261;
+	for (let index = 0; index < input.length; index++) {
+		hash ^= input.charCodeAt(index);
+		hash = Math.imul(hash, 16777619);
+	}
+	return (hash >>> 0).toString(36);
+}
+//#endregion
+//#region src/locale/en.ts
+/** English message catalogue. */
+var en = {
+	"error.decorator.method.duplicate": "method [%s] already has a request-method decorator (@Get/@Post/...)",
+	"error.decorator.method.missing": "method [%s] has no request-method decorator (@Get/@Post/...), cannot send a request",
+	"error.decorator.param.context": "@%s may only be used on an instance method parameter",
+	"error.decorator.param.empty": "bad parameter on method [%s]: a key-less @%s argument must be a plain object",
+	"error.decorator.param.untyped": "@%s needs a string key, or no key at all to spread the whole object",
+	"error.decorator.class.target": "@%s may only be applied to a class",
+	"error.decorator.server.notFound": "api class [%s] is missing the @Api() decorator",
+	"error.decorator.stream.duplicate": "class [%s] already has a connection decorator (@Sse/@WebSocket)",
+	"error.options.server.missing": "server class [%s] is missing the @Server() decorator",
+	"error.options.server.baseURL": "@Server() baseURL must be a non-empty string",
+	"error.options.api.url": "@Api() url must be a string",
+	"error.options.plugin.notFound": "plugin [%s] is not registered on server [%s]",
+	"error.options.plugin.missing": "plugin [%s] depends on [%s], which has not been registered yet — call use() first",
+	"error.options.plugin.exists": "plugin [%s] is already registered on server [%s]",
+	"error.hook.next.multiple": "plugin [%s] called next() more than once inside the %s hook",
+	"error.hook.unknown": "unknown plugin lifecycle hook [%s]",
+	"error.request.failed": "[%s] request failed: %s",
+	"error.request.timeout": "[%s] request timed out (%sms)",
+	"error.request.cancelled": "[%s] request cancelled",
+	"error.response.code": "[%s] business status code rejected: code=%s",
+	"error.response.shape": "[%s] response does not match the agreed envelope: missing [%s]",
+	"error.response.json": "[%s] failed to parse the JSON response: %s",
+	"error.path.missing": "route [%s] has no value for placeholder [:%s] — add @Params('%s') to the method parameter",
+	"error.plugin.validate.request": "[%s] request payload failed validation",
+	"error.plugin.validate.response": "[%s] response payload failed validation",
+	"error.plugin.transform": "[%s] payload transform failed: %s",
+	"error.plugin.cache.adapter": "unknown cache adapter [%s]; expected one of memory, localStorage, sessionStorage, indexedDB",
+	"info.request.start": "→ %s %s [%s]",
+	"info.request.success": "← %s %s [%s] %s",
+	"info.request.codeError": "← %s %s [%s] bad business code %s",
+	"info.request.error": "← %s %s [%s] %s",
+	"info.cache.hit": "[%s] cache hit",
+	"info.cache.set": "[%s] cached",
+	"info.cache.invalidate": "[%s] cache invalidated (source: %s)",
+	"info.version.default": "[%s] using default version %s",
+	"info.version.change": "[%s] version switched to %s",
+	"warn.version.change": "[%s] version differs from the default: %s → %s",
+	"info.sse.open": "[%s] SSE connection opened",
+	"info.sse.close": "[%s] SSE connection closed",
+	"info.ws.open": "[%s] WebSocket connection opened",
+	"info.ws.close": "[%s] WebSocket connection closed (code=%s)"
+};
+//#endregion
+//#region src/locale/zh.ts
+/** Chinese (zh-CN) message catalogue. */
+var zh = {
+	"error.decorator.method.duplicate": "方法[%s]上只能使用一个请求方式装饰器（@Get/@Post/...）",
+	"error.decorator.method.missing": "方法[%s]缺少请求方式装饰器（@Get/@Post/...），无法发送请求",
+	"error.decorator.param.context": "@%s 只能用于类的实例方法参数，不能用于构造函数或静态成员",
+	"error.decorator.param.empty": "方法[%s]的参数标记错误：未传入 key 时该参数必须是普通对象",
+	"error.decorator.param.untyped": "参数装饰器 @%s 需要一个字符串 key，或省略 key 以展开整个对象",
+	"error.decorator.class.target": "@%s 只能用于类",
+	"error.decorator.server.notFound": "接口类[%s]缺少 @Api() 装饰器",
+	"error.decorator.stream.duplicate": "类[%s]上只能使用一个连接类装饰器（@Sse/@WebSocket）",
+	"error.options.server.missing": "服务类[%s]缺少 @Server() 装饰器",
+	"error.options.server.baseURL": "@Server() 的 baseURL 必须是非空字符串",
+	"error.options.api.url": "@Api() 的 url 必须是字符串",
+	"error.options.plugin.notFound": "插件[%s]未在服务[%s]上注册",
+	"error.options.plugin.missing": "插件[%s]依赖的插件[%s]尚未注册，请先 use() 它",
+	"error.options.plugin.exists": "插件[%s]已在服务[%s]上注册，请勿重复注册",
+	"error.hook.next.multiple": "插件[%s]的 %s 钩子多次调用了 next()",
+	"error.hook.unknown": "未知的插件生命周期钩子[%s]",
+	"error.request.failed": "[%s] 请求失败：%s",
+	"error.request.timeout": "[%s] 请求超时（%sms）",
+	"error.request.cancelled": "[%s] 请求已取消",
+	"error.response.code": "[%s] 业务状态码校验未通过：code=%s",
+	"error.response.shape": "[%s] 服务端返回数据不符合约定结构：缺少字段[%s]",
+	"error.response.json": "[%s] 服务端返回的 JSON 解析失败：%s",
+	"error.path.missing": "路由[%s]中的占位符[:%s]没有对应的参数值，请在方法参数上添加 @Params('%s')",
+	"error.plugin.validate.request": "[%s] 请求数据校验失败",
+	"error.plugin.validate.response": "[%s] 响应数据校验失败",
+	"error.plugin.transform": "[%s] 数据转换失败：%s",
+	"error.plugin.cache.adapter": "未知的缓存适配器[%s]，可选：memory、localStorage、sessionStorage、indexedDB",
+	"info.request.start": "→ %s %s [%s]",
+	"info.request.success": "← %s %s [%s] %s",
+	"info.request.codeError": "← %s %s [%s] 业务码异常 %s",
+	"info.request.error": "← %s %s [%s] %s",
+	"info.cache.hit": "[%s] 缓存命中",
+	"info.cache.set": "[%s] 写入缓存",
+	"info.cache.invalidate": "[%s] 缓存失效（失效源：%s）",
+	"info.version.default": "[%s] 使用默认版本 %s",
+	"info.version.change": "[%s] 版本切换到 %s",
+	"warn.version.change": "[%s] 版本与默认版本不一致：%s → %s",
+	"info.sse.open": "[%s] SSE 连接已建立",
+	"info.sse.close": "[%s] SSE 连接已关闭",
+	"info.ws.open": "[%s] WebSocket 连接已建立",
+	"info.ws.close": "[%s] WebSocket 连接已关闭（code=%s）"
+};
+//#endregion
+//#region src/locale/index.ts
+var BUILT_IN = {
+	zh,
+	en
+};
+/**
+* Detects the ambient language without assuming a browser.
+*
+* The pre-rewrite implementation read `navigator.language` unconditionally,
+* which threw a `ReferenceError` in Node, in a worker and during SSR. Every
+* probe here is guarded, and the fallback is `en`.
+*/
+function detectLanguage() {
+	const globals = globalThis;
+	const fromNavigator = globals.navigator?.languages?.[0] ?? globals.navigator?.language;
+	if (typeof fromNavigator === "string" && fromNavigator.length > 0) return fromNavigator;
+	const fromEnv = globals.process?.env?.SNAIL_LOCALE ?? globals.process?.env?.LC_ALL ?? globals.process?.env?.LC_MESSAGES ?? globals.process?.env?.LANG;
+	if (typeof fromEnv === "string" && fromEnv.length > 0) return fromEnv;
+	return "en";
+}
+function isCatalogue(value) {
+	return typeof value === "object" && value !== null;
+}
+/** Resolve `zh-CN` / `zh_TW` / `en-US` down to a shipped catalogue. */
+function resolveBuiltIn(language) {
+	const normalized = language.toLowerCase().replace("_", "-");
+	if (normalized.startsWith("zh")) return zh;
+	if (normalized.startsWith("en")) return en;
+}
+/**
+* Tiny message catalogue with `%s` placeholders.
+*
+* A single shared instance backs the module-level `t()` helper, so plugins can
+* contribute their own messages with `registerMessages()`.
+*/
+var Localization = class {
+	constructor(language) {
+		this.language = "en";
+		this.catalogue = en;
+		this.setLocale(language ?? detectLanguage());
+	}
+	/** Currently active language tag or catalogue name. */
+	get locale() {
+		return this.language;
+	}
+	/**
+	* Switch language.
+	*
+	* - `"zh"`, `"zh-CN"`, `"en-US"` → pick a shipped catalogue
+	* - a message object → merge over the current catalogue (great for plugins
+	*   and for applications that want their own wording)
+	*/
+	setLocale(input) {
+		if (typeof input === "string") {
+			this.language = input;
+			const builtIn = resolveBuiltIn(input);
+			if (builtIn) this.catalogue = builtIn;
+			return this;
+		}
+		if (isCatalogue(input)) {
+			this.catalogue = {
+				...this.catalogue,
+				...input
+			};
+			return this;
+		}
+		return this;
+	}
+	/** Merge extra messages into the active catalogue. */
+	registerMessages(messages) {
+		this.catalogue = {
+			...this.catalogue,
+			...messages
+		};
+		return this;
+	}
+	/** Current catalogue contents (a snapshot copy). */
+	get messages() {
+		return { ...this.catalogue };
+	}
+	/**
+	* Translate `key`, replacing each `%s` with the matching extra argument.
+	*
+	* A missing key returns the key itself rather than an empty string: the old
+	* implementation returned `""`, which silently swallowed typos and produced
+	* blank error messages.
+	*/
+	t(key, ...args) {
+		const template = this.catalogue[key];
+		if (template === void 0) return key;
+		let index = 0;
+		return template.replace(/%s/g, () => {
+			const value = args[index++];
+			return value === void 0 ? "" : String(value);
+		});
+	}
+};
+/** Shared catalogue instance used by the whole library. */
+var localization = new Localization();
+/**
+* Translate a message using the shared catalogue.
+*
+* @example
+* ```ts
+* t("info.cache.hit", "default.UserApi.list"); // "[…] cache hit"
+* ```
+*/
+function t(key, ...args) {
+	return localization.t(key, ...args);
+}
+/** Switch the language of the shared catalogue. */
+function setLocale(input) {
+	localization.setLocale(input);
+}
+/** Read the active language of the shared catalogue. */
+function getLocale() {
+	return localization.locale;
+}
+/** Contribute extra messages to the shared catalogue (used by plugins). */
+function registerMessages(messages) {
+	localization.registerMessages(messages);
+}
+var languages = Object.keys(BUILT_IN);
+//#endregion
+//#region src/core/args.ts
+/**
+* Built-in parameter resolvers.
+*
+* Each one mutates the live request on the context, which keeps the argument
+* decorators free of any knowledge about how the request is eventually sent.
+*
+* A key-less decorator (`@Query() query: SomeShape`) spreads the whole object;
+* a keyed one (`@Query("page") page: number`) places a single value. Getting
+* that wrong is a programmer error and throws immediately, with a message that
+* names the method and the offending parameter.
+*/
+function assertPlainObject(input, source) {
+	if (!isPlainObject(input.value)) throw new SnailDecoratorError(t("error.decorator.param.empty", `${input.methodName}.${source}`));
+}
+/** Place a value into the mutable header bag, creating it when absent. */
+function headerBag(ctx) {
+	if (!(ctx.request.headers instanceof AxiosHeaders)) ctx.request.headers = AxiosHeaders.from(ctx.request.headers ?? {});
+	return ctx.request.headers;
+}
+/** `@Params()` — fills `:placeholder` values used to build the final url. */
+var resolvePathParams = (input) => {
+	if (input.key !== void 0) {
+		input.ctx.pathParams[input.key] = input.value;
+		return;
+	}
+	assertPlainObject(input, "params");
+	Object.assign(input.ctx.pathParams, input.value);
+};
+/** `@Query()` — merges into the query string. */
+var resolveQuery = (input) => {
+	const current = input.ctx.request.params;
+	if (input.key !== void 0) {
+		input.ctx.request.params = {
+			...isPlainObject(current) ? current : {},
+			[input.key]: input.value
+		};
+		return;
+	}
+	assertPlainObject(input, "query");
+	input.ctx.request.params = {
+		...isPlainObject(current) ? current : {},
+		...input.value
+	};
+};
+/**
+* `@Data()` — builds the request body.
+*
+* With a key the value is merged into an object body. Without a key a plain
+* object is merged, while anything else (`FormData`, `Blob`, a raw string,
+* an array) *replaces* the body so non-JSON uploads stay possible.
+*/
+var resolveBody = (input) => {
+	const current = input.ctx.request.data;
+	if (input.key !== void 0) {
+		const base = isPlainObject(current) ? current : {};
+		input.ctx.request.data = {
+			...base,
+			[input.key]: input.value
+		};
+		return;
+	}
+	if (isPlainObject(input.value)) {
+		const base = isPlainObject(current) ? current : {};
+		input.ctx.request.data = {
+			...base,
+			...input.value
+		};
+		return;
+	}
+	input.ctx.request.data = input.value;
+};
+/** `@Header()` — merges into the request headers. */
+var resolveHeader = (input) => {
+	const headers = headerBag(input.ctx);
+	if (input.key !== void 0) {
+		headers.set(input.key, input.value);
+		return;
+	}
+	assertPlainObject(input, "header");
+	for (const [key, value] of Object.entries(input.value)) headers.set(key, value);
+};
+/**
+* The resolver registry.
+*
+* `createParamDecorator` looks sources up here, so a plugin can either reuse a
+* built-in source or register its own.
+*/
+var paramResolvers = {
+	params: resolvePathParams,
+	query: resolveQuery,
+	data: resolveBody,
+	header: resolveHeader
+};
+/** Register a resolver under a custom source name. */
+function registerParamResolver(source, resolver) {
+	paramResolvers[source] = resolver;
+}
+/** Human-readable label used in decorator error messages. */
+function sourceLabel(source) {
+	return capitalize(source);
+}
+/** `true` when `source` has a registered resolver. */
+function hasParamResolver(source) {
+	return typeof paramResolvers[source] === "function";
+}
+/** Names of every registered parameter source. */
+function paramSources() {
+	return Object.keys(paramResolvers);
+}
+/**
+* Apply every decorated argument to the request.
+*
+* Descriptors run in ascending parameter-index order so `@Data("a") a` followed
+* by `@Data("b") b` produces `{ a, b }` regardless of decorator evaluation order
+* (TypeScript applies parameter decorators in *reverse* index order).
+*/
+function applyParamDescriptors(ctx, args) {
+	if (ctx.descriptors.length === 0) return;
+	const ordered = [...ctx.descriptors].sort((a, b) => a.index - b.index);
+	for (const descriptor of ordered) descriptor.resolve({
+		ctx,
+		value: args[descriptor.index],
+		key: descriptor.key,
+		options: descriptor.options,
+		index: descriptor.index,
+		methodName: ctx.methodName
+	});
+}
+/**
+* Substitute `:placeholder` segments and write the final url onto the request.
+*
+* Runs after the argument decorators, because the whole point is to have their
+* values available.
+*/
+function finalizeRequestURL(ctx) {
+	const route = ctx.route;
+	if (!route.includes(":")) {
+		ctx.request.url = route;
+		return;
+	}
+	const missing = [];
+	const resolved = replacePathParams(route, ctx.pathParams, (name) => {
+		missing.push(name);
+		throw new SnailDecoratorError(t("error.path.missing", route, name, name));
+	});
+	if (missing.length === 0) ctx.request.url = resolved;
+}
+//#endregion
+//#region src/error/response.ts
+/**
+* Thrown when the backend answered with HTTP success but a business status code
+* that the configured {@link ServerOptions.validateCode} rule rejected.
+*
+* The whole parsed body is preserved on `payload`, so an application error
+* handler can still read `payload.message` / `payload.data`.
+*/
+var SnailResponseError = class extends SnailError {
+	constructor(message, options) {
+		super(message, {
+			code: "SNAIL_RESPONSE_ERROR",
+			cause: options.cause
+		});
+		this.businessCode = options.businessCode;
+		this.payload = options.payload;
+	}
+};
+/**
+* Thrown when the transport failed: non-2xx status, network failure, timeout or
+* abort. `status` is present only when a response actually came back.
+*/
+var SnailHttpError = class extends SnailError {
+	constructor(message, options = {}) {
+		super(message, {
+			code: options.code ?? "SNAIL_HTTP_ERROR",
+			cause: options.cause
+		});
+		this.status = options.status;
+		this.statusText = options.statusText;
+		this.payload = options.payload;
+	}
+};
+//#endregion
+//#region src/error/hook.ts
+/**
+* Thrown when a plugin lifecycle chain is driven illegally — calling `next()`
+* twice from one hook, or calling `next()` after the chain already settled.
+*
+* This is the Koa `compose` invariant, and it catches a very common plugin bug:
+* a hook that both `await next()` *and* falls through into a second `next()`.
+*/
+var SnailHookError = class extends SnailError {
+	constructor(hook, message) {
+		super(message, { code: "SNAIL_HOOK_ERROR" });
+		this.hook = hook;
+	}
+};
+//#endregion
+//#region src/core/plugin.ts
+/**
+* Plugin machinery.
+*
+* ## Everything is a plugin
+*
+* The core ships *no* optional behaviour: caching, versioning, interceptors,
+* validation, transformation and framework adapters are all plugins. Core owns
+* exactly three things — the metadata written by decorators, the request
+* pipeline, and this plugin lifecycle.
+*
+* ## Two kinds of hook
+*
+* - **Chain hooks** (`beforeRequest`, `afterResponse`) are Koa-style middleware:
+*   a hook receives `next`, may `await` it, and may decline to call it to stop
+*   the request. This is what makes cross-cutting concerns composable.
+* - **Effect hooks** (`initMeta`, `beforeCreate`, `onError`, `afterRequest`) run
+*   sequentially and cannot influence control flow.
+*/
+/** Identity helper that preserves the option type of a plugin factory. */
+function definePlugin(factory) {
+	return factory;
+}
+/**
+* Create a third-party plugin.
+*
+* This is the supported entry point for plugin authors. It validates the name,
+* wires `install`/`uninstall`, exposes a scoped {@link PluginSetupApi} and keeps
+* the hook object fully typed.
+*
+* @example
+* ```ts
+* interface TraceOptions { header?: string }
+*
+* export const Trace = createPlugin<TraceOptions, { onSend?: (url: string) => void }>({
+*   name: "trace",
+*   priority: 20,
+*   setup(options, api) {
+*     const header = options?.header ?? "x-trace-id";
+*     api.addMessages({ "trace.missing": "trace header %s is missing" });
+*     return {
+*       beforeRequest(ctx) {
+*         ctx.request.headers.set(header, crypto.randomUUID());
+*       }
+*     };
+*   }
+* });
+*
+* Service.use(Trace({ header: "x-trace-id" }));
+* ```
+*/
+function createPlugin(definition) {
+	if (!definition || typeof definition.name !== "string" || definition.name.length === 0) throw new TypeError("[snail] createPlugin() requires a non-empty `name`");
+	const { name, priority = 0, dependsOn, setup } = definition;
+	return (options) => {
+		const disposers = [];
+		const plugin = {
+			name,
+			priority,
+			dependsOn,
+			options,
+			install(installCtx) {
+				if (!setup) return;
+				const hooks = setup(options, {
+					serverName: installCtx.serverName,
+					serverOptions: installCtx.serverOptions,
+					installedPlugins: installCtx.pluginNames,
+					defineParamSource: registerParamResolver,
+					addMessages: registerMessages,
+					onDispose: (dispose) => {
+						disposers.push(dispose);
+					}
+				});
+				if (hooks) Object.assign(plugin, hooks);
+			},
+			async uninstall() {
+				while (disposers.length > 0) await disposers.pop()();
+			}
+		};
+		return plugin;
+	};
+}
+/**
+* Compose chain hooks into a single Koa-style function.
+*
+* The returned function runs `entries[0]` first (they are pre-sorted by the
+* manager), handing each hook a `next` that advances the chain. When the chain
+* is exhausted, `downstream` runs — that is where the manager splices in the
+* actual HTTP request between `beforeRequest` and `afterResponse`.
+*
+* Calling `next()` twice from one hook throws {@link SnailHookError}; without
+* that guard the second call silently re-runs the rest of the chain.
+*/
+function composeChain(hookName, entries) {
+	return async function runChain(ctx, downstream) {
+		let lastIndex = -1;
+		const dispatch = async (index) => {
+			if (index <= lastIndex) throw new SnailHookError(hookName, t("error.hook.next.multiple", entries[Math.max(lastIndex, 0)]?.pluginName ?? "unknown", hookName));
+			lastIndex = index;
+			const entry = entries[index];
+			if (!entry) {
+				await downstream?.();
+				return;
+			}
+			let advanced = false;
+			const next = async () => {
+				if (advanced) throw new SnailHookError(hookName, t("error.hook.next.multiple", entry.pluginName, hookName));
+				advanced = true;
+				await dispatch(index + 1);
+			};
+			await entry.hook(ctx, next);
+		};
+		await dispatch(0);
+	};
+}
+//#endregion
+export { stableStringify as A, SnailError as B, buildRequestURL as C, pathParamNames as D, joinURL as E, isFunction as F, isObject as I, isPlainObject as L, isBinaryBody as M, isBrowser as N, replacePathParams as O, isDefined as P, isPromise as R, en as S, isAbsoluteURL as T, localization as _, SnailHttpError as a, t as b, finalizeRequestURL as c, paramSources as d, registerParamResolver as f, languages as g, getLocale as h, SnailHookError as i, stripQuery as j, shortHash as k, hasParamResolver as l, Localization as m, createPlugin as n, SnailResponseError as o, sourceLabel as p, definePlugin as r, applyParamDescriptors as s, composeChain as t, paramResolvers as u, registerMessages as v, capitalize as w, zh as x, setLocale as y, SnailDecoratorError as z };
+
+//# sourceMappingURL=plugin-D3RDffDG.js.map