@snail-js/api 0.1.27 → 1.0.0

package/dist/plugins/index.js

@@ -0,0 +1,2265 @@
+import { A as stableStringify, B as SnailError, L as isPlainObject, T as isAbsoluteURL, b as t, k as shortHash, n as createPlugin, z as SnailDecoratorError } from "../chunks/plugin-D3RDffDG.js";
+import { n as deferred } from "../chunks/object-Ct0w-h4i.js";
+import { i as looksLikeEnvelope, o as unwrapEnvelope, r as coerceJSONStringBody } from "../chunks/response-D-ubkAFl.js";
+import { C as getMetadata, V as createLogger, _ as SnailPluginError, a as customMetadataKey, b as collectMethodKeys, i as createPropertyDecorator, n as createMethodDecorator, o as getClassMetadata, s as getMethodMetadata, t as createClassDecorator, x as defineMetadata } from "../chunks/custom-UchOSg_s.js";
+import { AxiosHeaders } from "axios";
+//#region src/plugins/cache/adapters/indexeddb.ts
+/**
+* L2 adapter over IndexedDB.
+*
+* ## Why every method degrades instead of rejecting
+*
+* IndexedDB is absent in Node and can be unavailable in private browsing modes.
+* An L2 store is an optimisation: a request must succeed (and stay correct) when
+* it is missing. Every public method therefore resolves to "nothing stored" or a
+* no-op rather than throwing, and the connection is opened lazily so importing
+* this module — or constructing the adapter — never touches a global.
+*
+* ## Why the timeout is stored per record, not as an index
+*
+* A TTL index would make reads of an expired key need a second query anyway. The
+* record carries its own `expiresAt`, which makes the freshness check a pure
+* in-memory comparison on the value already fetched.
+*/
+var IndexedDBCacheAdapter = class {
+	constructor(options = {}) {
+		this.databaseName = options.databaseName ?? "snail-js-api";
+		this.storeName = options.storeName ?? "cache";
+		this.version = options.version ?? 1;
+	}
+	/** `false` when the environment has no IndexedDB at all. */
+	get available() {
+		try {
+			return typeof globalThis.indexedDB !== "undefined";
+		} catch {
+			return false;
+		}
+	}
+	async get(key) {
+		try {
+			const database = await this.open();
+			const record = await this.read(database, key);
+			if (record === void 0) return void 0;
+			if (record.expiresAt !== 0 && record.expiresAt <= Date.now()) {
+				await this.delete(key);
+				return;
+			}
+			return record.value;
+		} catch {
+			return;
+		}
+	}
+	async set(key, value, ttlSeconds) {
+		if (!this.available) return;
+		const database = await this.open();
+		const record = {
+			value,
+			expiresAt: ttlSeconds > 0 ? Date.now() + ttlSeconds * 1e3 : 0
+		};
+		await this.transaction(database, "readwrite", (store) => {
+			store.put(record, key);
+		});
+	}
+	async delete(key) {
+		try {
+			const database = await this.open();
+			await this.transaction(database, "readwrite", (store) => {
+				store.delete(key);
+			});
+		} catch {}
+	}
+	async clear() {
+		try {
+			const database = await this.open();
+			await this.transaction(database, "readwrite", (store) => {
+				store.clear();
+			});
+		} catch {}
+	}
+	async keys() {
+		try {
+			return (await requestToPromise((await this.open()).transaction(this.storeName, "readonly").objectStore(this.storeName).getAllKeys())).map(String);
+		} catch {
+			return [];
+		}
+	}
+	/**
+	* Open (once) and memoise the database connection.
+	*
+	* The in-flight promise is stored before it settles, so two concurrent
+	* requests cannot open the same database twice and leak a connection.
+	*/
+	open() {
+		if (this.database) return Promise.resolve(this.database);
+		if (this.opening) return this.opening;
+		this.opening = new Promise((resolve, reject) => {
+			const factory = globalThis.indexedDB;
+			if (!factory) {
+				reject(/* @__PURE__ */ new Error("[snail] IndexedDB is not available in this environment"));
+				return;
+			}
+			const request = factory.open(this.databaseName, this.version);
+			request.onupgradeneeded = () => {
+				const database = request.result;
+				if (!database.objectStoreNames.contains(this.storeName)) database.createObjectStore(this.storeName);
+			};
+			request.onsuccess = () => {
+				this.database = request.result;
+				resolve(request.result);
+			};
+			request.onerror = () => reject(request.error);
+			request.onblocked = () => reject(/* @__PURE__ */ new Error("[snail] IndexedDB upgrade is blocked"));
+		}).finally(() => {
+			this.opening = void 0;
+		});
+		return this.opening;
+	}
+	async read(database, key) {
+		const value = await requestToPromise(database.transaction(this.storeName, "readonly").objectStore(this.storeName).get(key));
+		if (value === void 0 || value === null || typeof value !== "object") return void 0;
+		if (!("value" in value) || !("expiresAt" in value)) return void 0;
+		return value;
+	}
+	transaction(database, mode, run) {
+		return new Promise((resolve, reject) => {
+			const transaction = database.transaction(this.storeName, mode);
+			run(transaction.objectStore(this.storeName));
+			transaction.oncomplete = () => resolve();
+			transaction.onerror = () => reject(transaction.error);
+			transaction.onabort = () => reject(transaction.error);
+		});
+	}
+};
+/** Bridge a one-shot `IDBRequest` into a promise. */
+function requestToPromise(request) {
+	return new Promise((resolve, reject) => {
+		request.onsuccess = () => resolve(request.result);
+		request.onerror = () => reject(request.error);
+	});
+}
+//#endregion
+//#region src/plugins/cache/adapters/memory.ts
+/** L1 capacity used whenever the configured one is missing or not positive. */
+var DEFAULT_L1_MAX_SIZE = 100;
+/**
+* The L1 store: a `Map` with TTL and LRU capacity.
+*
+* ## Why there is no sweep timer
+*
+* The pre-rewrite memory adapter ran a `setInterval` that (a) kept a Node
+* process alive forever and (b) made tests hang until vitest force-killed them.
+* Expiry is therefore swept *lazily*, at the start of every operation: at most
+* `maxSize` records are inspected, which is cheaper than the timer it replaces
+* for any realistic capacity, and it cannot outlive the store.
+*
+* ## Why a `Map` and not a `WeakMap`
+*
+* LRU needs enumeration and ordering. `Map` preserves insertion order, so
+* "least recently used" is simply "first key" and touching an entry is
+* delete + set — no linked list to keep in sync with the data.
+*/
+var MemoryCacheAdapter = class {
+	constructor(options = {}) {
+		this.records = /* @__PURE__ */ new Map();
+		const maxSize = options.maxSize;
+		this.maxSize = typeof maxSize === "number" && Number.isFinite(maxSize) && maxSize > 0 ? Math.floor(maxSize) : 100;
+		this.onEvict = options.onEvict;
+	}
+	/** Number of live entries. */
+	get size() {
+		this.sweep();
+		return this.records.size;
+	}
+	/** `true` when the key is present and still fresh. */
+	async has(key) {
+		return await this.get(key) !== void 0;
+	}
+	async get(key) {
+		this.sweep();
+		const record = this.records.get(key);
+		if (!record) return void 0;
+		this.records.delete(key);
+		this.records.set(key, record);
+		return record.value;
+	}
+	async set(key, value, ttlSeconds) {
+		this.sweep();
+		if (!this.records.delete(key)) this.evictForCapacity(1);
+		this.records.set(key, {
+			value,
+			expiresAt: ttlSeconds > 0 ? Date.now() + ttlSeconds * 1e3 : 0
+		});
+	}
+	async delete(key) {
+		this.records.delete(key);
+	}
+	async clear() {
+		this.records.clear();
+	}
+	async keys() {
+		this.sweep();
+		return [...this.records.keys()];
+	}
+	/** Drop expired records. Called before every operation, never on a timer. */
+	sweep() {
+		const now = Date.now();
+		for (const [key, record] of this.records) if (record.expiresAt !== 0 && record.expiresAt <= now) {
+			this.records.delete(key);
+			this.onEvict?.(key);
+		}
+	}
+	/** Make room for `incoming` new entries by dropping the oldest ones. */
+	evictForCapacity(incoming) {
+		while (this.records.size + incoming > this.maxSize) {
+			const oldest = this.records.keys().next();
+			if (oldest.done) return;
+			this.records.delete(oldest.value);
+			this.onEvict?.(oldest.value);
+		}
+	}
+};
+//#endregion
+//#region src/plugins/cache/adapters/web-storage.ts
+/**
+* L2 adapter over any Web Storage area.
+*
+* One class drives both `localStorage` and `sessionStorage`: they share the
+* `Storage` interface, and wrapping them twice would duplicate every guard below.
+*
+* ## Why the area is resolved through a getter
+*
+* `localStorage` does not exist in Node, and in a browser it *throws* on access
+* when the user has blocked site data. Reading it in the constructor would make
+* `import`-time behaviour environment-dependent — and a Node test could not even
+* construct the adapter to assert that it degrades. The getter is therefore
+* called per operation and its failure is swallowed; the store behaves as an
+* always-empty cache, which the manager turns into "L1 only".
+*/
+var WebStorageCacheAdapter = class {
+	constructor(resolveStorage, options = {}) {
+		this.resolveStorage = resolveStorage;
+		this.prefix = options.prefix ?? "[snail-cache]";
+		this.label = options.label ?? "web storage";
+	}
+	/** `false` when the backing area is missing — the manager then drops L2. */
+	get available() {
+		return this.storage() !== void 0;
+	}
+	async get(key) {
+		const storage = this.storage();
+		if (!storage) return void 0;
+		const raw = storage.getItem(this.key(key));
+		if (raw === null) return void 0;
+		const record = this.parse(raw);
+		if (record === void 0) {
+			storage.removeItem(this.key(key));
+			return;
+		}
+		if (record.expiresAt !== 0 && record.expiresAt <= Date.now()) {
+			storage.removeItem(this.key(key));
+			return;
+		}
+		return record.value;
+	}
+	async set(key, value, ttlSeconds) {
+		const storage = this.storage();
+		if (!storage) return;
+		const record = {
+			value,
+			expiresAt: ttlSeconds > 0 ? Date.now() + ttlSeconds * 1e3 : 0
+		};
+		storage.setItem(this.key(key), JSON.stringify(record));
+	}
+	async delete(key) {
+		this.storage()?.removeItem(this.key(key));
+	}
+	async clear() {
+		const storage = this.storage();
+		if (!storage) return;
+		for (const key of this.keysOf(storage)) storage.removeItem(key);
+	}
+	async keys() {
+		const storage = this.storage();
+		if (!storage) return [];
+		return this.keysOf(storage).map((key) => key.slice(this.prefix.length));
+	}
+	storage() {
+		try {
+			return this.resolveStorage();
+		} catch {
+			return;
+		}
+	}
+	key(key) {
+		return `${this.prefix}${key}`;
+	}
+	/** Every storage key this adapter owns, prefix included. */
+	keysOf(storage) {
+		const owned = [];
+		for (let index = 0; index < storage.length; index++) {
+			const key = storage.key(index);
+			if (key !== null && key.startsWith(this.prefix)) owned.push(key);
+		}
+		return owned;
+	}
+	parse(raw) {
+		try {
+			const parsed = JSON.parse(raw);
+			if (parsed === null || typeof parsed !== "object") return void 0;
+			if (!("value" in parsed) || !("expiresAt" in parsed)) return void 0;
+			return parsed;
+		} catch {
+			return;
+		}
+	}
+};
+//#endregion
+//#region src/plugins/cache/decorators.ts
+/**
+* `@Cacheable()` / `@NoCache()` / `@Invalidates()` / `@HitSource()` — the
+* declarative half of the cache plugin.
+*
+* All four work on a class and on a method. TypeScript distinguishes the two by
+* arity (a class decorator is called with the constructor alone), which is the
+* only signal available now that `emitDecoratorMetadata` emits nothing in TS 7.
+*
+* ## Why `@Invalidates` appends instead of replacing
+*
+* `@Invalidates("users", "orders")` is two decorator applications on one target.
+* Using the merging factory means the reader gets `["users", "orders"]` without
+* the plugin having to flatten a nested array — and two separate
+* `@Invalidates()` lines compose the same way, which is how a method that
+* touches several caches is naturally written.
+*/
+var CACHEABLE_KEY = "snail-cache/cacheable";
+var NO_CACHE_KEY = "snail-cache/disabled";
+var INVALIDATES_KEY = "snail-cache/invalidates";
+var addCacheableOnClass = createClassDecorator(CACHEABLE_KEY, false);
+var addCacheableOnMethod = createMethodDecorator(CACHEABLE_KEY, false);
+var addNoCacheOnClass = createClassDecorator(NO_CACHE_KEY, false);
+var addNoCacheOnMethod = createMethodDecorator(NO_CACHE_KEY, false);
+var addInvalidatesOnClass = createClassDecorator(INVALIDATES_KEY);
+var addInvalidatesOnMethod = createMethodDecorator(INVALIDATES_KEY);
+/** Fold a class application and a method application into one decorator. */
+function dualDecorator$1(applyToClass, applyToMethod) {
+	return ((target, propertyKey) => {
+		if (propertyKey === void 0) {
+			applyToClass(target);
+			return;
+		}
+		applyToMethod(target, propertyKey, void 0);
+	});
+}
+/** Reject the misuse that would otherwise only surface at request time. */
+function assertCacheableOptions(options) {
+	if (options.ttl !== void 0 && !(typeof options.ttl === "number" && options.ttl > 0)) throw new SnailDecoratorError("[snail] @Cacheable({ ttl }) must be a positive number of seconds");
+	if (options.key !== void 0 && (typeof options.key !== "string" || options.key.length === 0)) throw new SnailDecoratorError("[snail] @Cacheable({ key }) must be a non-empty string");
+	if (options.tags !== void 0) {
+		if (!Array.isArray(options.tags)) throw new SnailDecoratorError("[snail] @Cacheable({ tags }) must be an array of strings");
+		for (const tag of options.tags) if (typeof tag !== "string" || tag.length === 0) throw new SnailDecoratorError("[snail] @Cacheable({ tags }) must contain non-empty strings");
+	}
+}
+/**
+* Mark this method — or every method of this class — as cacheable.
+*
+* Passing the decorator is an explicit opt-in: it caches even a verb that
+* `CacheOptions.cacheFor` does not list. Without it, `cacheFor` decides, and the
+* reason is that "cache every POST of this class" is far too easy to write by
+* accident when the intent was only to attach tags.
+*
+* ```ts
+* @Api("/user")
+* @Cacheable({ tags: ["users"] })
+* class UserApi {
+*   @Get("/") list(): Promise<User[]> { return null!; }
+*
+*   @Get("/stats")
+*   @Cacheable({ ttl: 5 })
+*   stats(): Promise<Stats> { return null!; }
+* }
+* ```
+*/
+function Cacheable(options = {}) {
+	assertCacheableOptions(options);
+	const value = {
+		ttl: options.ttl,
+		key: options.key,
+		tags: options.tags === void 0 ? void 0 : [...options.tags]
+	};
+	return dualDecorator$1(addCacheableOnClass(value), addCacheableOnMethod(value));
+}
+/**
+* Opt this method — or this entire class — out of caching.
+*
+* A method-level `@NoCache()` beats a class-level `@Cacheable()`, and a
+* class-level `@NoCache()` beats the `cacheFor` default. Opting out is the one
+* decision that may never be overridden by a broader rule, because the cost of
+* being wrong is serving stale data.
+*/
+function NoCache() {
+	return dualDecorator$1(addNoCacheOnClass(true), addNoCacheOnMethod(true));
+}
+/**
+* Purge every cached entry carrying any of `tags` once this request succeeds.
+*
+* "Succeeds" means the HTTP round-trip did: the hook lives on the response path,
+* so a failed or cancelled request invalidates nothing. A method may invalidate a
+* tag it also stores under — the plugin purges before it stores, so the fresh
+* entry survives its own invalidation.
+*/
+function Invalidates(...tags) {
+	for (const tag of tags) if (typeof tag !== "string" || tag.length === 0) throw new SnailDecoratorError("[snail] @Invalidates(...tags) needs non-empty strings");
+	return ((target, propertyKey) => {
+		for (const tag of tags) if (propertyKey === void 0) addInvalidatesOnClass(tag)(target);
+		else addInvalidatesOnMethod(tag)(target, propertyKey, void 0);
+	});
+}
+/**
+* Legacy-compatible alias of {@link Invalidates} for a single source name.
+*
+* The pre-rewrite decorator was named after the *source* of a change rather than
+* the entries it purges; application code written against it keeps working, and
+* new code should prefer `@Invalidates`.
+*/
+function HitSource(name) {
+	return Invalidates(name);
+}
+/**
+* Read `@Cacheable(...)` from a method (when `methodName` is given) or a class.
+*
+* `undefined` means "not marked", which is different from `{}` ("marked, with no
+* overrides") — the plugin treats the two differently.
+*/
+function readCacheable(target, methodName) {
+	return methodName === void 0 ? getClassMetadata(CACHEABLE_KEY, target) : getMethodMetadata(CACHEABLE_KEY, target, methodName);
+}
+/** `true` when `@NoCache()` was applied to this method or class. */
+function readNoCache(target, methodName) {
+	return (methodName === void 0 ? getClassMetadata(NO_CACHE_KEY, target) : getMethodMetadata(NO_CACHE_KEY, target, methodName)) === true;
+}
+/** Tags listed by `@Invalidates(...)` / `@HitSource(...)`, in application order. */
+function readInvalidates(target, methodName) {
+	return (methodName === void 0 ? getClassMetadata(INVALIDATES_KEY, target) : getMethodMetadata(INVALIDATES_KEY, target, methodName)) ?? [];
+}
+//#endregion
+//#region src/plugins/cache/key.ts
+/**
+* Build the key used for one request.
+*
+* The readable part (`prefix:VERB`) is kept outside the hash so a misbehaving
+* cache can be diagnosed from a key alone; only the volatile signature is hashed,
+* which keeps keys short enough for `localStorage`.
+*/
+function buildCacheKey(input) {
+	const { prefix, request, methodType, explicitKey } = input;
+	if (explicitKey !== void 0 && explicitKey.length > 0) return `${prefix}:${explicitKey}`;
+	const method = (request.method ?? methodType).toUpperCase();
+	const signature = stableStringify({
+		method,
+		baseURL: request.baseURL ?? "",
+		url: request.url ?? "",
+		params: request.params ?? null,
+		data: request.data ?? null
+	});
+	return `${prefix}:${method}:${shortHash(signature)}`;
+}
+//#endregion
+//#region src/plugins/cache/manager.ts
+/** Verbs cached when `cacheFor` is not configured. */
+var DEFAULT_CACHE_FOR = ["GET"];
+/**
+* Storage engine behind the cache plugin.
+*
+* ## Layers
+*
+* - **L1** is a {@link MemoryCacheAdapter}: always present unless `l1: false`,
+*   bounded by `maxSize`, and the only place an L2 hit is promoted into.
+* - **L2** is any {@link CacheAdapter}, usually a persistent store.
+*
+* ## What the manager owns that the adapters do not
+*
+* TTL, LRU and tags are policy, not storage. Keeping them here means a custom L2
+* adapter only has to answer "get/set/delete" and never has to know what a tag
+* is — which is what makes the adapter interface small enough to implement over
+* anything (IndexedDB, `localStorage`, an HTTP cache).
+*
+* ## Freshness vs. `staleWhileRevalidate`
+*
+* Freshness is always decided by this class, using the `expiresAt` it records on
+* `set`. In stale-while-revalidate mode L1 is told "never expire" so the stale
+* copy survives to be served while the plugin refreshes it; otherwise L1 is
+* given the real TTL and sweeps the entry itself. L2 always receives the real TTL
+* so a second tab (which has no shared in-memory index) never reads a stale one.
+*/
+var CacheManager = class {
+	constructor(options = {}) {
+		this.expiry = /* @__PURE__ */ new Map();
+		this.tagIndex = /* @__PURE__ */ new Map();
+		this.keyTags = /* @__PURE__ */ new Map();
+		this.flight = /* @__PURE__ */ new Map();
+		this.logger = options.logger ?? createLogger("silent");
+		this.options = resolveOptions(options, this.logger);
+		this.l1 = this.options.l1 ? new MemoryCacheAdapter({
+			maxSize: this.options.maxSize,
+			onEvict: (key) => this.forgetKey(key)
+		}) : void 0;
+	}
+	/** Number of live **L1** entries. L2 is not enumerated, by design. */
+	get size() {
+		return this.l1?.size ?? 0;
+	}
+	/**
+	* Read a fresh value.
+	*
+	* A stale entry (kept alive only for stale-while-revalidate) is *not* returned:
+	* callers that must serve staleness ask {@link lookup} explicitly, so the
+	* common path cannot accidentally serve expired data.
+	*/
+	async get(key) {
+		return (await this.lookup(key))?.value;
+	}
+	/** `true` when a fresh value is stored under `key`. */
+	async has(key) {
+		return await this.get(key) !== void 0;
+	}
+	/**
+	* Read a value together with its freshness.
+	*
+	* `allowStale` is the plugin's `staleWhileRevalidate` switch: when the entry is
+	* past its TTL but still resident, it is returned with `stale: true` so the
+	* caller can serve it now and refresh afterwards.
+	*/
+	async lookup(key, allowStale = false) {
+		const fromL1 = await this.readL1(key);
+		if (fromL1.found) {
+			const stale = this.isStale(key);
+			if (!stale || allowStale) return {
+				value: fromL1.value,
+				stale
+			};
+		}
+		const fromL2 = await this.readL2(key);
+		if (!fromL2.found) return void 0;
+		this.markExpiry(key, this.options.ttl);
+		const l1Ttl = this.options.staleWhileRevalidate ? 0 : this.options.ttl;
+		await this.writeL1(key, fromL2.value, l1Ttl);
+		return {
+			value: fromL2.value,
+			stale: false
+		};
+	}
+	/**
+	* Store a value in L1 and L2.
+	*
+	* `ttlSeconds` defaults to the configured TTL and `tags` may be empty; a tag
+	* written here is what `@Invalidates("tag")` later purges.
+	*/
+	async set(key, value, ttlSeconds = this.options.ttl, tags = []) {
+		this.markExpiry(key, ttlSeconds);
+		this.rememberTags(key, tags);
+		await this.writeL1(key, value, this.options.staleWhileRevalidate ? 0 : ttlSeconds);
+		await this.writeL2(key, value, ttlSeconds);
+	}
+	/** Remove one entry from every layer. */
+	async delete(key) {
+		this.forgetKey(key);
+		await this.l1?.delete(key);
+		if (!this.options.l2) return;
+		try {
+			await this.options.l2.delete(key);
+		} catch (error) {
+			this.warnL2("delete", error);
+		}
+	}
+	/** Remove every entry this manager can see. */
+	async clear() {
+		await this.l1?.clear();
+		this.expiry.clear();
+		this.tagIndex.clear();
+		this.keyTags.clear();
+		if (!this.options.l2) return;
+		try {
+			await this.options.l2.clear();
+		} catch (error) {
+			this.warnL2("clear", error);
+		}
+	}
+	/**
+	* Purge every entry carrying any of `tags`.
+	*
+	* Used by `@Invalidates(...)` / `@HitSource(...)` after a successful request.
+	* Keys are collected first because deleting mutates the tags they came from.
+	*/
+	async invalidateTags(tags) {
+		const keys = /* @__PURE__ */ new Set();
+		for (const tag of tags) for (const key of this.tagIndex.get(tag) ?? []) keys.add(key);
+		for (const key of keys) await this.delete(key);
+	}
+	/** Alias of {@link clear}, spelled the way `@Invalidates("*")`-style callers expect. */
+	async invalidateAll() {
+		await this.clear();
+	}
+	/** The promise of the request currently being sent for `key`, if any. */
+	getInFlight(key) {
+		return this.flight.get(key);
+	}
+	/**
+	* Publish the promise of the request being sent for `key`.
+	*
+	* The entry removes itself when the promise settles, so a rejected shared
+	* promise cannot be picked up by a later, unrelated request. The rejection is
+	* also marked as observed: a leader that fails with no follower waiting would
+	* otherwise surface as an unhandled rejection in Node.
+	*/
+	setInFlight(key, promise) {
+		const tracked = promise.then((value) => {
+			this.flight.delete(key);
+			return value;
+		}, (error) => {
+			this.flight.delete(key);
+			throw error;
+		});
+		tracked.catch(() => void 0);
+		this.flight.set(key, tracked);
+	}
+	async readL1(key) {
+		if (!this.l1) return { found: false };
+		const value = await this.l1.get(key);
+		return value === void 0 ? { found: false } : {
+			found: true,
+			value
+		};
+	}
+	async readL2(key) {
+		const l2 = this.options.l2;
+		if (!l2) return { found: false };
+		try {
+			const value = await l2.get(key);
+			return value === void 0 ? { found: false } : {
+				found: true,
+				value
+			};
+		} catch (error) {
+			this.warnL2("read", error);
+			return { found: false };
+		}
+	}
+	async writeL1(key, value, ttlSeconds) {
+		if (!this.l1) return;
+		await this.l1.set(key, value, ttlSeconds);
+	}
+	async writeL2(key, value, ttlSeconds) {
+		const l2 = this.options.l2;
+		if (!l2) return;
+		try {
+			await l2.set(key, value, ttlSeconds);
+		} catch (error) {
+			this.warnL2("write", error);
+		}
+	}
+	markExpiry(key, ttlSeconds) {
+		this.expiry.set(key, ttlSeconds > 0 ? Date.now() + ttlSeconds * 1e3 : 0);
+	}
+	isStale(key) {
+		const expiresAt = this.expiry.get(key);
+		return expiresAt !== void 0 && expiresAt !== 0 && expiresAt <= Date.now();
+	}
+	rememberTags(key, tags) {
+		if (tags.length === 0) return;
+		const owned = this.keyTags.get(key) ?? /* @__PURE__ */ new Set();
+		for (const tag of tags) {
+			owned.add(tag);
+			const keys = this.tagIndex.get(tag) ?? /* @__PURE__ */ new Set();
+			keys.add(key);
+			this.tagIndex.set(tag, keys);
+		}
+		this.keyTags.set(key, owned);
+	}
+	forgetKey(key) {
+		this.expiry.delete(key);
+		const tags = this.keyTags.get(key);
+		if (!tags) return;
+		for (const tag of tags) {
+			const keys = this.tagIndex.get(tag);
+			if (!keys) continue;
+			keys.delete(key);
+			if (keys.size === 0) this.tagIndex.delete(tag);
+		}
+		this.keyTags.delete(key);
+	}
+	warnL2(operation, error) {
+		this.logger.warn(t("cache.warn.l2.failed", this.options.prefix, `${operation}: ${String(error)}`));
+	}
+};
+/** Apply every default and turn the L2 selector into a live adapter. */
+function resolveOptions(options, logger) {
+	const prefix = options.prefix ?? "[snail-cache]";
+	return {
+		ttl: positive(options.ttl, 60),
+		maxSize: positive(options.maxSize, 100),
+		l1: options.l1 ?? true,
+		l2: createL2(options.l2, prefix, logger),
+		cacheFor: normalizeCacheFor(options.cacheFor),
+		prefix,
+		staleWhileRevalidate: options.staleWhileRevalidate ?? false,
+		dedupe: options.dedupe ?? true
+	};
+}
+/**
+* Turn the `l2` selector into an adapter.
+*
+* A missing environment global becomes "no L2 at all" plus one warning, rather
+* than an adapter that silently misses on every read: the warning is the only
+* signal an application gets that its persistence intent was not honoured.
+*/
+function createL2(selector, prefix, logger) {
+	if (selector === void 0) return void 0;
+	if (typeof selector !== "string") return selector;
+	const normalized = selector.toLowerCase();
+	if (normalized === "localstorage" || normalized === "sessionstorage") {
+		const area = normalized === "localstorage" ? "localStorage" : "sessionStorage";
+		const adapter = new WebStorageCacheAdapter(() => globalThis[area], {
+			prefix,
+			label: area
+		});
+		if (!adapter.available) {
+			logger.warn(t("cache.warn.l2.unavailable", prefix, area));
+			return;
+		}
+		return adapter;
+	}
+	if (normalized === "indexeddb") {
+		const adapter = new IndexedDBCacheAdapter({ storeName: prefix });
+		if (!adapter.available) {
+			logger.warn(t("cache.warn.l2.unavailable", prefix, "indexedDB"));
+			return;
+		}
+		return adapter;
+	}
+	throw new SnailPluginError(t("error.plugin.cache.adapter", selector), { pluginName: "cache" });
+}
+/** Normalise `cacheFor` into `"all"` or an uppercase verb list. */
+function normalizeCacheFor(input) {
+	if (input === void 0) return DEFAULT_CACHE_FOR;
+	if (typeof input === "string") return input.toLowerCase() === "all" ? "all" : [input.toUpperCase()];
+	return input.map((verb) => String(verb).toUpperCase());
+}
+/** Coerce an optional count to a positive finite number, else `fallback`. */
+function positive(value, fallback) {
+	return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : fallback;
+}
+//#endregion
+//#region src/plugins/cache/plugin.ts
+/**
+* The cache plugin.
+*
+* ## Where it sits in the pipeline
+*
+* `priority: -100` is the reserved cache band, which buys two things the contract
+* spells out in `docs/guide/plugin-lifecycle.md` §2.2:
+*
+* - **last in forward order** — the interceptor (`100`) and every argument
+*   decorator have already run, so `ctx.request` holds the final url, params and
+*   body when the key is built. Hashing an earlier shape would key two different
+*   requests identically (or one request twice).
+* - **first in unwind order** — the raw envelope is stored before the validation
+*   and transformation plugins touch it, so a hit replays exactly what the server
+*   sent rather than a processed derivative.
+*
+* ## Stores what the server sent
+*
+* The entry holds `ctx.response.data`, not the `SnailResult`. The result is a
+* projection of the envelope onto the caller's envelope schema; caching it would
+* freeze one server's key names into another's cache.
+*/
+/** Plugin name; also the identity used by `Service.use()` / `Service.remove()`. */
+var CACHE_PLUGIN_NAME = "cache";
+/** The reserved cache priority band (see `docs/guide/plugin-lifecycle.md` §2.1). */
+var CACHE_PRIORITY = -100;
+/** `ctx.state` slot holding the {@link CachePlan} of the current send. */
+var CACHE_PLAN_STATE = "snail:cache:plan";
+/**
+* Create the cache plugin.
+*
+* ```ts
+* const cache = Cache({ ttl: 30, l2: "localStorage" });
+* Service.use(cache);
+* await cache.manager?.invalidateAll();
+* ```
+*/
+function Cache(options) {
+	let manager;
+	const base = createPlugin({
+		name: CACHE_PLUGIN_NAME,
+		priority: CACHE_PRIORITY,
+		setup(pluginOptions, api) {
+			const instance = new CacheManager({
+				...pluginOptions,
+				prefix: pluginOptions?.prefix ?? api.serverName,
+				logger: createLogger(api.serverOptions.logLevel)
+			});
+			manager = instance;
+			api.addMessages({
+				"cache.warn.l2.failed": "[%s] L2 cache %s failed; continuing without it",
+				"cache.warn.l2.unavailable": "[%s] %s is unavailable in this environment; the cache plugin uses L1 only",
+				"cache.warn.store.failed": "[%s] the response could not be cached: %s",
+				"cache.warn.revalidate.failed": "[%s] background revalidation failed: %s",
+				"info.cache.stale": "[%s] served a stale entry; revalidating in the background"
+			});
+			return {
+				beforeRequest: (ctx, next) => serveFromCache(instance, ctx, next),
+				afterResponse: (ctx, next) => storeResponse(instance, ctx, next)
+			};
+		}
+	})(options);
+	Object.defineProperty(base, "manager", {
+		enumerable: true,
+		configurable: true,
+		get: () => manager
+	});
+	return base;
+}
+/**
+* Serve a cache hit, or register this request as the one that will fill the gap.
+*
+* Three outcomes, in order of cost:
+*
+* 1. **fresh hit** — `ctx.interrupt(response)` and no `next()`, so axios is never
+*    reached;
+* 2. **stale hit** (only with `staleWhileRevalidate`) — the stale body is served
+*    immediately and the refresh happens out of band;
+* 3. **miss** — `next()` runs the request, and a follower of an identical
+*    in-flight request waits for its leader instead of sending a second one.
+*/
+async function serveFromCache(manager, ctx, next) {
+	const plan = resolveCachePlan(ctx, manager.options);
+	ctx.state.set(CACHE_PLAN_STATE, plan);
+	const key = plan.key;
+	if (key === void 0) return next();
+	const found = await manager.lookup(key, manager.options.staleWhileRevalidate);
+	if (found) {
+		ctx.markCacheHit();
+		ctx.interrupt(makeCachedResponse(found.value, ctx.request));
+		ctx.logger.debug(t("info.cache.hit", ctx.fullName));
+		if (found.stale) {
+			ctx.logger.debug(t("info.cache.stale", ctx.fullName));
+			revalidate(manager, ctx, plan, key);
+		}
+		return;
+	}
+	if (!manager.options.dedupe) return next();
+	const pending = manager.getInFlight(key);
+	if (pending) {
+		const shared = await pending.catch(() => void 0);
+		if (shared !== void 0) {
+			ctx.markCacheHit();
+			ctx.interrupt(makeCachedResponse(shared, ctx.request));
+			return;
+		}
+		return next();
+	}
+	const flight = deferred();
+	manager.setInFlight(key, flight.promise);
+	try {
+		await next();
+		flight.resolve(ctx.getResponse()?.data);
+	} catch (error) {
+		flight.reject(error);
+		throw error;
+	}
+}
+/**
+* Invalidate first, then store, then continue the chain.
+*
+* The order of the first two is load-bearing: a method that is both cacheable
+* and declares `@Invalidates` for one of its own tags stores *after* the purge,
+* so it cannot delete the entry it just wrote. Storing before `next()` is what
+* makes the cached value the raw envelope — later plugins see the response
+* afterwards, and the cache keeps what the server actually sent.
+*/
+async function storeResponse(manager, ctx, next) {
+	const plan = ctx.state.get(CACHE_PLAN_STATE);
+	if (plan && !ctx.isCacheHit) {
+		if (plan.invalidate.length > 0) {
+			await manager.invalidateTags(plan.invalidate);
+			ctx.logger.debug(t("info.cache.invalidate", ctx.fullName, plan.invalidate.join(", ")));
+		}
+		if (plan.key !== void 0 && ctx.response) try {
+			await manager.set(plan.key, snapshot(ctx.response.data), plan.ttl, plan.tags);
+			ctx.logger.debug(t("info.cache.set", ctx.fullName));
+		} catch (error) {
+			ctx.logger.warn(t("cache.warn.store.failed", ctx.fullName, String(error)));
+		}
+	}
+	await next();
+}
+/**
+* Decide what the cache should do with this request, from the decorators and the
+* configured verb list.
+*
+* Precedence, and why:
+*
+* 1. `@NoCache()` on the method — an explicit opt-out is never overridden;
+* 2. `@Cacheable()` on the method — an explicit opt-in beats a class-wide
+*    decision, in both directions (this is what "method-level wins" means);
+* 3. `@NoCache()` on the class;
+* 4. `@Cacheable()` on the class — every method of the class;
+* 5. otherwise, the verb must be listed in `cacheFor`, which defaults to `GET`.
+*
+* Tags from both levels are merged, class first, so a method can add its own
+* without losing the class's. `ttl` and `key` are *not* merged: the most specific
+* declaration wins outright.
+*/
+function resolveCachePlan(ctx, options) {
+	const classCacheable = readCacheable(ctx.apiClass);
+	const methodCacheable = readCacheable(ctx.apiClass, ctx.methodName);
+	const cacheable = readNoCache(ctx.apiClass, ctx.methodName) ? false : methodCacheable !== void 0 ? true : readNoCache(ctx.apiClass) ? false : classCacheable !== void 0 ? true : matchesCacheFor(ctx.methodType, options.cacheFor);
+	const explicitKey = methodCacheable?.key ?? classCacheable?.key;
+	return {
+		key: cacheable ? buildCacheKey({
+			prefix: options.prefix,
+			request: ctx.request,
+			methodType: ctx.methodType,
+			explicitKey
+		}) : void 0,
+		ttl: methodCacheable?.ttl ?? classCacheable?.ttl ?? options.ttl,
+		tags: [.../* @__PURE__ */ new Set([...classCacheable?.tags ?? [], ...methodCacheable?.tags ?? []])],
+		invalidate: [.../* @__PURE__ */ new Set([...readInvalidates(ctx.apiClass), ...readInvalidates(ctx.apiClass, ctx.methodName)])]
+	};
+}
+/** `true` when `cacheFor` covers this verb. */
+function matchesCacheFor(method, cacheFor) {
+	return cacheFor === "all" || cacheFor.includes(method);
+}
+/**
+* Wrap a cached body into the axios response a plugin must hand back.
+*
+* `headers` is empty on purpose: the stored entry is only the body, and inventing
+* headers would make downstream plugins react to values the server never sent.
+* `config` is the live request, so anything reading `response.config` sees the
+* request that produced the hit.
+*
+* The body is **copied**. Without that, the object handed to the caller would be
+* the very object the cache holds, so one `result.data.name = "x"` would silently
+* rewrite the cache entry — and, worse, a response transformer that hydrates the
+* payload in place would corrupt the stored value for every later hit.
+*/
+function makeCachedResponse(body, config) {
+	return {
+		data: snapshot(body),
+		status: 200,
+		statusText: "Cache Hit (snail)",
+		headers: {},
+		config
+	};
+}
+/**
+* Copy a value so the cache and the caller can never share a mutable reference.
+*
+* `structuredClone` is preferred because it preserves `Date`, `Map`, `Set` and
+* typed arrays, which a JSON round-trip flattens. JSON is the fallback for older
+* engines, and if both fail (a function-valued field, a class instance with
+* private state) the original reference is returned — a shared reference is a
+* far smaller problem than throwing inside a cache read.
+*/
+function snapshot(value) {
+	if (value === null || typeof value !== "object") return value;
+	const cloner = globalThis.structuredClone;
+	if (typeof cloner === "function") try {
+		return cloner(value);
+	} catch {}
+	try {
+		return JSON.parse(JSON.stringify(value));
+	} catch {
+		return value;
+	}
+}
+/**
+* Refresh an entry after serving stale data.
+*
+* The refresh deliberately does **not** call this request's `next()`: the caller
+* is still reading `ctx.response`, and a detached chain step would write the
+* fresh response into the very same context — corrupting the result the caller is
+* about to receive, or a later `send()` that reused the context. Instead the
+* final config is replayed through the server's own axios instance and the
+* response is normalised the same way `dispatch` normalises it, so the refreshed
+* entry is byte-for-byte what a normal miss would have stored.
+*/
+function revalidate(manager, ctx, plan, key) {
+	const config = ctx.server.pluginManager.reduce("requestInterceptor", ctx.request, ctx);
+	(async () => {
+		try {
+			let response = await ctx.server.axios.request(config);
+			response = coerceJSONStringBody(response, ctx.serverOptions.coerceJSONString);
+			response = ctx.server.pluginManager.reduce("responseInterceptor", response, ctx);
+			await manager.set(key, response.data, plan.ttl, plan.tags);
+		} catch (error) {
+			ctx.logger.warn(t("cache.warn.revalidate.failed", ctx.fullName, String(error)));
+		}
+	})();
+}
+//#endregion
+//#region src/plugins/interceptor/decorators.ts
+/**
+* `@BeforeRequest()` / `@AfterResponse()` — the decorator half of the
+* interceptor plugin.
+*
+* ## Storage
+*
+* Both targets share one metadata key per phase: a class application lands in the
+* class slot, a method application in that method's slot
+* (`src/core/metadata.ts` §storage model). Reading them back is therefore one
+* `getClassMetadata` plus one `getMethodMetadata`, with no "is this a class or a
+* proto" branching at the call site.
+*
+* ## Why the key name is namespaced
+*
+* `createClassDecorator` turns `"snail-interceptor/before"` into
+* `Symbol.for("@snail-js/api:custom:snail-interceptor/before")`. A `Symbol.for`
+* key survives the two-copies-of-the-package situation a monorepo creates, so a
+* decorator applied from the hoisted copy is still visible to a plugin loaded
+* from the nested one.
+*/
+var BEFORE_KEY = "snail-interceptor/before";
+var AFTER_KEY = "snail-interceptor/after";
+var addBeforeOnClass = createClassDecorator(BEFORE_KEY);
+var addBeforeOnMethod = createMethodDecorator(BEFORE_KEY);
+var addAfterOnClass = createClassDecorator(AFTER_KEY);
+var addAfterOnMethod = createMethodDecorator(AFTER_KEY);
+/**
+* Fold a class application and a method application into one decorator.
+*
+* TypeScript tells the two apart by arity: a class decorator is called with the
+* constructor alone, a method decorator with `(prototype, key, descriptor)`.
+* That is the only reliable signal available without `reflect-metadata`.
+*/
+function dualDecorator(applyToClass, applyToMethod) {
+	return ((target, propertyKey) => {
+		if (propertyKey === void 0) {
+			applyToClass(target);
+			return;
+		}
+		applyToMethod(target, propertyKey, void 0);
+	});
+}
+/** Reject the misuse that would otherwise fail silently at request time. */
+function assertCallback(value, decorator) {
+	if (typeof value !== "function") throw new SnailDecoratorError(`[snail] @${decorator}() needs a function; got ${typeof value}`);
+}
+/**
+* Run `onFulfilled` on the request config of this class / this method, in series
+* with every other request interceptor.
+*
+* ```ts
+* @Api("/user")
+* @BeforeRequest<UserConfig>((config) => { config.headers.set("x-trace", "1"); })
+* class UserApi {
+*   @Get("/")
+*   @BeforeRequest((config) => { config.timeout = 5000; })
+*   list(): Promise<User[]> { return null!; }
+* }
+* ```
+*
+* Class-level interceptors run before method-level ones, so a method may refine
+* what its class established. `onRejected` may recover a failure by returning a
+* replacement config; returning `undefined` (or throwing) lets the failure
+* through, and the request is then never sent.
+*/
+function BeforeRequest(onFulfilled, onRejected) {
+	assertCallback(onFulfilled, "BeforeRequest");
+	if (onRejected !== void 0) assertCallback(onRejected, "BeforeRequest");
+	const entry = {
+		onFulfilled,
+		onRejected
+	};
+	return dualDecorator(addBeforeOnClass(entry), addBeforeOnMethod(entry));
+}
+/**
+* Run `onFulfilled` against the response of this class / this method.
+*
+* The callback receives the axios response, **not** a `next`: unlike
+* `beforeRequest`, this phase is an unwind hook, so the response already exists
+* and nothing here decides whether the request happens. Return a replacement
+* response, or `undefined` to keep the one that was passed in.
+*/
+function AfterResponse(onFulfilled, onRejected) {
+	assertCallback(onFulfilled, "AfterResponse");
+	if (onRejected !== void 0) assertCallback(onRejected, "AfterResponse");
+	const entry = {
+		onFulfilled,
+		onRejected
+	};
+	return dualDecorator(addAfterOnClass(entry), addAfterOnMethod(entry));
+}
+/** Class-level `@BeforeRequest` entries, in application order. */
+function classBeforeEntries(target) {
+	return getClassMetadata(BEFORE_KEY, target) ?? [];
+}
+/** Method-level `@BeforeRequest` entries, in application order. */
+function methodBeforeEntries(target, methodName) {
+	return getMethodMetadata(BEFORE_KEY, target, methodName) ?? [];
+}
+/** Class-level `@AfterResponse` entries, in application order. */
+function classAfterEntries(target) {
+	return getClassMetadata(AFTER_KEY, target) ?? [];
+}
+/** Method-level `@AfterResponse` entries, in application order. */
+function methodAfterEntries(target, methodName) {
+	return getMethodMetadata(AFTER_KEY, target, methodName) ?? [];
+}
+//#endregion
+//#region src/plugins/interceptor/manager.ts
+/**
+* Runtime registry of programmatic interceptors.
+*
+* Decorators cover interceptors that are known at class-definition time. This
+* class covers the other half — an application that decides at runtime "from now
+* on, sign every request" — and it is also what the plugin uses internally to
+* hold the server-wide entries passed to `Interceptor({ request })`.
+*
+* Entries keep insertion order: that order *is* the execution order, since the
+* interceptor contract is deliberately sequential rather than priority based.
+*/
+var InterceptorManager = class {
+	constructor() {
+		this.registry = /* @__PURE__ */ new Map();
+		this.sequence = 0;
+	}
+	/** Register an entry. Returns the id {@link eject} needs to remove it again. */
+	use(entry) {
+		if (!entry || typeof entry.onFulfilled !== "function" && typeof entry.onRejected !== "function") throw new SnailPluginError("[snail] InterceptorManager.use() expects an entry with onFulfilled and/or onRejected", { pluginName: "interceptor" });
+		this.sequence += 1;
+		this.registry.set(this.sequence, entry);
+		return this.sequence;
+	}
+	/** Remove an entry by the id returned from {@link use}. Returns whether it existed. */
+	eject(id) {
+		return this.registry.delete(id);
+	}
+	/** Drop every entry. */
+	clear() {
+		this.registry.clear();
+	}
+	/** Registered entries, in execution order. */
+	get entries() {
+		return [...this.registry.values()];
+	}
+	/** Number of registered entries. */
+	get size() {
+		return this.registry.size;
+	}
+};
+//#endregion
+//#region src/plugins/interceptor/plugin.ts
+/**
+* The interceptor plugin.
+*
+* ## Where it sits in the pipeline
+*
+* `priority: 100` is the reserved interceptor band, so this plugin is the first
+* to see the request in forward order and the last to see the response in unwind
+* order. That is what lets `@BeforeRequest()` rewrite the config *before* the
+* cache plugin (`-100`) hashes the final url, params and body into a cache key.
+*
+* ## Request vs response
+*
+* `beforeRequest` is a chain hook: the interceptors run first, and only then
+* does the hook hand control on with `next()`. An interceptor that fails
+* unrecoverably therefore stops the request before anything reaches the network.
+*
+* `afterResponse` is an **unwind** hook. The response already exists when it
+* runs, so calling `next()` *first* would let later plugins observe a response
+* the interceptors had not rewritten yet. The interceptors run against
+* `ctx.response` first and the chain is advanced afterwards. The interceptor
+* callbacks themselves are not chain hooks — they receive the response rather
+* than a `next` — so nothing inside one of them can advance or stop the chain.
+*/
+/** Plugin name; also the identity used by `Service.use()` / `Service.remove()`. */
+var INTERCEPTOR_PLUGIN_NAME = "interceptor";
+/** The reserved interceptor priority band (see `docs/guide/plugin-lifecycle.md` §2.1). */
+var INTERCEPTOR_PRIORITY = 100;
+/**
+* Create the interceptor plugin.
+*
+* ```ts
+* const interceptors = Interceptor({
+*   request: [{ onFulfilled: (config) => { config.headers.set("x-app", "web"); } }]
+* });
+* Service.use(interceptors);
+* interceptors.request.use({ onFulfilled: (config, ctx) => ctx.logger.debug(ctx.fullName) });
+* ```
+*/
+function Interceptor(options) {
+	const request = new InterceptorManager();
+	const response = new InterceptorManager();
+	for (const entry of options?.request ?? []) request.use(entry);
+	for (const entry of options?.response ?? []) response.use(entry);
+	const base = createPlugin({
+		name: INTERCEPTOR_PLUGIN_NAME,
+		priority: 100,
+		setup(_pluginOptions, api) {
+			api.addMessages({
+				"info.interceptor.request": "[%s] %s request interceptor(s) applied",
+				"info.interceptor.response": "[%s] %s response interceptor(s) applied"
+			});
+			return {
+				beforeRequest: (ctx, next) => runRequestInterceptors(request, ctx, next),
+				afterResponse: (ctx, next) => runResponseInterceptors(response, ctx, next)
+			};
+		}
+	})(options);
+	return Object.assign(base, {
+		request,
+		response
+	});
+}
+/**
+* Run every request interceptor, then continue the chain.
+*
+* Order is class → method → server-wide, each list in its own application order.
+* One interceptor's failure is offered to that same interceptor's `onRejected`
+* before it is allowed to abort the request, which is the only recovery point in
+* the whole pipeline — `onError` merely observes.
+*/
+async function runRequestInterceptors(manager, ctx, next) {
+	const entries = [
+		...classBeforeEntries(ctx.apiClass),
+		...methodBeforeEntries(ctx.apiClass, ctx.methodName),
+		...manager.entries
+	];
+	if (entries.length > 0) ctx.logger.debug(t("info.interceptor.request", ctx.fullName, String(entries.length)));
+	for (const entry of entries) {
+		if (typeof entry.onFulfilled !== "function") continue;
+		try {
+			const replaced = await entry.onFulfilled(ctx.request, ctx);
+			if (replaced !== void 0) ctx.setRequest(replaced);
+		} catch (error) {
+			ctx.setRequest(await recover(entry, error, ctx));
+		}
+	}
+	await next();
+}
+/**
+* Run every response interceptor against the response that already exists.
+*
+* The callbacks are not chain hooks: they get the response, not a `next`, so a
+* response interceptor can rewrite but never interrupt. The plugin's own
+* `afterResponse` hook still advances the chain at the end, which is what lets
+* lower-priority plugins (validation, transformation) see the rewritten value.
+*/
+async function runResponseInterceptors(manager, ctx, next) {
+	const entries = [
+		...classAfterEntries(ctx.apiClass),
+		...methodAfterEntries(ctx.apiClass, ctx.methodName),
+		...manager.entries
+	];
+	if (entries.length > 0) ctx.logger.debug(t("info.interceptor.response", ctx.fullName, String(entries.length)));
+	for (const entry of entries) {
+		if (typeof entry.onFulfilled !== "function") continue;
+		try {
+			const replaced = await entry.onFulfilled(ctx.requireResponse(), ctx);
+			if (replaced !== void 0) ctx.setResponse(replaced);
+		} catch (error) {
+			ctx.setResponse(await recover(entry, error, ctx));
+		}
+	}
+	await next();
+}
+/**
+* Give an interceptor's `onRejected` a chance to recover from `error`.
+*
+* Only a *value* recovers: `undefined` means "I handled the notification but
+* have nothing to continue with", which must not silently produce an undefined
+* config. The original error is rethrown in that case, so the caller sees the
+* real cause rather than a downstream symptom.
+*/
+async function recover(entry, error, ctx) {
+	if (typeof entry.onRejected !== "function") throw error;
+	const recovered = await entry.onRejected(error, ctx);
+	if (recovered === void 0) throw error;
+	return recovered;
+}
+//#endregion
+//#region src/plugins/pool/type.ts
+/**
+* The error codes a request-pool refusal can carry.
+*
+* `isPoolError()` is the supported way to test them, but the strings are exported
+* so an application can switch on one precisely — for example to distinguish "the
+* queue was full, try again shortly" from "the user navigated away".
+*/
+var POOL_ERROR_CODES = {
+	/** `maxQueue` was reached; the request was never sent. */
+	queueFull: "SNAIL_POOL_QUEUE_FULL",
+	/** The request waited longer than `queueTimeout` and was dropped. */
+	queueTimeout: "SNAIL_POOL_QUEUE_TIMEOUT",
+	/** The request was cancelled while it was still waiting for a slot. */
+	aborted: "SNAIL_POOL_ABORTED",
+	/** The queue was cleared — usually because the plugin was uninstalled. */
+	cleared: "SNAIL_POOL_CLEARED"
+};
+/**
+* Raised when the pool refuses or drops a request.
+*
+* A dedicated class rather than a reuse of `SnailRequestError`: a pool refusal
+* means the request **never reached the network**, which is a materially different
+* situation from a transport failure. Retrying is safe and usually correct, the
+* payload is untouched, and no server state changed — a caller that cannot tell the
+* two apart will either retry a request the server already processed, or give up on
+* one that was merely queued behind a burst.
+*/
+var SnailPoolError = class extends SnailError {
+	constructor(message, code, options = {}) {
+		super(message, {
+			code,
+			cause: options.cause
+		});
+	}
+};
+//#endregion
+//#region src/plugins/pool/scheduler.ts
+/**
+* The scheduling core of the request pool.
+*
+* Deterministic and free of any request or plugin concept: it hands out `release`
+* callbacks and knows nothing about what they guard. That makes the hard part —
+* ordering, fairness and the guarantee that a slot is always returned — testable
+* on its own, without a server or a network.
+*
+* ## Messages come from the plugin
+*
+* The refusal messages are contributed by `RequestPool`'s `setup`, following the
+* plugin-owned-strings convention. Using this class **standalone** therefore yields
+* the raw message keys rather than translated text — the `code` on each
+* {@link SnailPoolError} is always correct, and that is what callers should branch
+* on. Registering a catalogue yourself is enough if you want the text too.
+*
+* ## The invariant that matters
+*
+* `active` must never drift from the number of outstanding tickets. Every failure
+* path (a queue that is full, a wait that times out, a request that is aborted,
+* a waiter dropped by `clear`) either never increments `active` or has already
+* been counted, and `release()` is idempotent so a double release from a `finally`
+* plus an abort listener cannot leak a slot. A leaked slot is invisible until the
+* pool permanently deadlocks at its ceiling, at which point every later request
+* hangs — which is why it is enforced here rather than at the call site.
+*/
+var RequestPoolScheduler = class {
+	constructor(options = {}) {
+		this.active = 0;
+		this.sequence = 0;
+		this.waiters = [];
+		const concurrency = Number.isFinite(options.concurrency) ? Math.floor(options.concurrency) : 6;
+		this.concurrency = Math.max(1, concurrency);
+		this.maxQueue = Number.isFinite(options.maxQueue) ? Math.max(0, Math.floor(options.maxQueue)) : Number.POSITIVE_INFINITY;
+		this.queueTimeout = Math.max(0, options.queueTimeout ?? 0);
+		this.priorityOf = options.priority;
+	}
+	/** Current counters. */
+	get stats() {
+		return {
+			active: this.active,
+			queued: this.waiters.length,
+			concurrency: this.concurrency
+		};
+	}
+	/** Change the ceiling at runtime; raising it immediately admits queued work. */
+	setConcurrency(value) {
+		if (!Number.isFinite(value)) return;
+		this.concurrency = Math.max(1, Math.floor(value));
+		this.pump();
+	}
+	/**
+	* Take a slot, or wait for one.
+	*
+	* Resolves with a ticket whose `release()` returns the slot. Rejects when the
+	* queue is full or the wait exceeds `queueTimeout`. `signal` lets an abandoned
+	* request leave the queue instead of holding a place it will never use.
+	*/
+	acquire(ctx, signal) {
+		if (signal?.aborted) return Promise.reject(this.abortError());
+		if (this.active < this.concurrency) return Promise.resolve(this.issue());
+		if (this.waiters.length >= this.maxQueue) return Promise.reject(new SnailPoolError(t("error.pool.queueFull", this.waiters.length), POOL_ERROR_CODES.queueFull));
+		return new Promise((resolve, reject) => {
+			let timer;
+			let onAbort;
+			let done = false;
+			const waiter = {
+				priority: this.priorityOfFor(ctx),
+				sequence: this.sequence++,
+				settle: (ticket) => {
+					if (done) return;
+					done = true;
+					waiter.dispose();
+					resolve(ticket);
+				},
+				fail: (error) => {
+					if (done) return;
+					done = true;
+					waiter.dispose();
+					reject(error);
+				},
+				dispose: () => {
+					if (timer) clearTimeout(timer);
+					if (onAbort) signal?.removeEventListener?.("abort", onAbort);
+				}
+			};
+			if (this.queueTimeout > 0) {
+				timer = setTimeout(() => {
+					remove(this.waiters, waiter);
+					waiter.fail(new SnailPoolError(t("error.pool.queueTimeout", this.queueTimeout), POOL_ERROR_CODES.queueTimeout));
+				}, this.queueTimeout);
+				timer.unref?.();
+			}
+			if (signal && typeof signal.addEventListener === "function") {
+				onAbort = () => {
+					remove(this.waiters, waiter);
+					waiter.fail(this.abortError());
+				};
+				signal.addEventListener("abort", onAbort, { once: true });
+			}
+			this.waiters.push(waiter);
+			this.sort();
+		});
+	}
+	/**
+	* Drop every waiter, rejecting each with `reason`.
+	*
+	* Used on uninstall: a queued request must not sit forever waiting for a pool
+	* that will never admit it.
+	*/
+	clear(reason) {
+		const pending = this.waiters.splice(0, this.waiters.length);
+		for (const waiter of pending) waiter.fail(reason ?? new SnailPoolError(t("error.pool.cleared"), POOL_ERROR_CODES.cleared));
+	}
+	/** Hand out one slot. */
+	issue() {
+		this.active += 1;
+		let released = false;
+		return { release: () => {
+			if (released) return;
+			released = true;
+			this.active = Math.max(0, this.active - 1);
+			this.pump();
+		} };
+	}
+	/** Admit as many waiters as there are free slots. */
+	pump() {
+		while (this.active < this.concurrency && this.waiters.length > 0) this.waiters.shift().settle(this.issue());
+	}
+	/** Lowest priority number first, then arrival order. */
+	sort() {
+		this.waiters.sort((a, b) => a.priority === b.priority ? a.sequence - b.sequence : a.priority - b.priority);
+	}
+	priorityOfFor(ctx) {
+		if (!this.priorityOf) return 0;
+		try {
+			const value = this.priorityOf(ctx);
+			return Number.isFinite(value) ? value : 0;
+		} catch {
+			return 0;
+		}
+	}
+	abortError() {
+		return new SnailPoolError(t("error.pool.aborted"), POOL_ERROR_CODES.aborted);
+	}
+};
+/** Remove one waiter by identity, wherever it sits in the queue. */
+function remove(waiters, waiter) {
+	const index = waiters.indexOf(waiter);
+	if (index !== -1) waiters.splice(index, 1);
+}
+//#endregion
+//#region src/plugins/pool/plugin.ts
+/** Plugin name; also the identity used by `Service.use()` / `Service.remove()`. */
+var POOL_PLUGIN_NAME = "pool";
+/**
+* Priority of the pool band.
+*
+* **Below** the cache (`-100`), which is the whole point: forward hooks run
+* highest-priority first, so the pool is the very last thing to run before the
+* transport. A request that the cache can answer never reaches the pool and never
+* consumes a slot. Putting the pool above the cache would let a handful of cached
+* reads occupy the entire pool and starve the real requests behind them.
+*/
+var POOL_PRIORITY = -150;
+/**
+* Bound how many requests are in flight at once.
+*
+* ```ts
+* Service.use(RequestPool({ concurrency: 4, maxQueue: 50, queueTimeout: 10_000 }));
+*
+* // `ctx.state` is readable from the priority callback, so an interactive request
+* // can jump ahead of a background prefetch.
+* Service.use(RequestPool({ concurrency: 4, priority: (ctx) => (ctx.state.get("prefetch") ? 100 : 0) }));
+* ```
+*
+* ## What problem this solves
+*
+* See {@link RequestPoolOptions} for why the browser's own queue is not enough.
+* In short: the built-in one is FIFO, invisible and unprioritised, so a burst from
+* one screen can starve the request the user is actually waiting for, and nothing
+* fails fast when the backlog grows without bound.
+*
+* ## Where it sits
+*
+* Last in forward order, immediately before the network call, and it holds its slot
+* only for the transport — `next()` resolves once the response has been received,
+* so validation, transformation and the caller's reactive updates happen after the
+* slot is already back in the pool.
+*
+* A cache hit short-circuits `beforeRequest` upstream of this plugin, so cached
+* reads cost no concurrency.
+*
+* ## One path it does not cover
+*
+* `useTokenAuth` replays a request that came back `401` by re-running the transport
+* directly, deliberately without re-entering `beforeRequest` (re-entering would
+* loop). Those replays therefore **do not pass through this pool** and are not
+* counted against `concurrency`.
+*
+* The practical impact is small — replays are bounded by the number of requests
+* that were in flight when the token expired, which were already uncapped — but it
+* is worth knowing before reaching for the pool to protect a backend from an auth
+* storm. If that matters, cap it at the source: use `useRequest`'s own concurrency
+* control, or let `useTokenAuth` refresh proactively rather than on the first 401.
+*/
+function RequestPool(options) {
+	let scheduler;
+	const base = createPlugin({
+		name: POOL_PLUGIN_NAME,
+		priority: POOL_PRIORITY,
+		setup(_pluginOptions, api) {
+			const instance = new RequestPoolScheduler(options);
+			scheduler = instance;
+			api.addMessages({
+				"error.pool.queueFull": "请求池队列已满（等待中 %s 个），请稍后重试",
+				"error.pool.queueTimeout": "请求池排队超时（已等待 %sms）",
+				"error.pool.cleared": "请求池已清空，排队的请求被取消",
+				"error.pool.aborted": "请求在排队期间被取消"
+			});
+			api.onDispose(() => instance.clear());
+			return { async beforeRequest(ctx, next) {
+				const signal = ctx.request.signal ?? void 0;
+				const ticket = await instance.acquire(ctx, signal);
+				try {
+					await next();
+				} finally {
+					ticket.release();
+				}
+			} };
+		}
+	})(options);
+	return Object.defineProperty(base, "scheduler", {
+		enumerable: true,
+		configurable: true,
+		get: () => scheduler
+	});
+}
+/** Read the live counters of an installed pool plugin, or `undefined`. */
+function poolStats(plugin) {
+	return plugin.scheduler?.stats;
+}
+/** Drop every queued request of an installed pool plugin. */
+function clearPool(plugin, reason) {
+	plugin.scheduler?.clear(reason);
+}
+/**
+* `true` when `error` came from the pool rather than from the transport.
+*
+* Lets a caller tell "refused before it was ever sent" — safe to retry later —
+* apart from a real network failure. Covers all four refusal paths: a full queue,
+* a queue wait that timed out, a request abandoned while waiting, and a queue
+* cleared by an uninstall.
+*/
+function isPoolError(error) {
+	return error instanceof SnailPoolError;
+}
+//#endregion
+//#region src/plugins/transform/decorators.ts
+/**
+* Transform decorators.
+*
+* `@Transform(DtoClass)` chooses the class a response is hydrated into;
+* `@PropertyType()` and `@ExposeName()` describe the shape of that class. All
+* three are metadata-only — they never touch a request or a server, so a DTO
+* shared between two api classes cannot leak state from one to the other.
+*/
+/** Metadata slot written by `@Transform`. */
+var TRANSFORM_KEY = customMetadataKey("transform/dto");
+/** Metadata slot written by `@PropertyType`. */
+var PROPERTY_TYPE_KEY = customMetadataKey("transform/property-type");
+/** Metadata slot written by `@ExposeName`. */
+var EXPOSE_NAME_KEY = customMetadataKey("transform/expose-name");
+/**
+* Choose the DTO a response payload is hydrated into.
+*
+* Applies to an api class and to a single method; the method wins, so one
+* endpoint can answer with a different shape than its siblings.
+*
+* ```ts
+* @Api("/user")
+* @Transform(UserDto)
+* class UserApi {
+*   @Get("/:id")
+*   getUser(@Params("id") id: string): Promise<UserDto> { return null!; }
+* }
+* ```
+*/
+function Transform$1(dto) {
+	if (typeof dto !== "function") throw new SnailDecoratorError("[snail] @Transform() expects a DTO class, not an instance or a plain object");
+	return ((target, propertyKey) => {
+		defineMetadata(TRANSFORM_KEY, dto, target, propertyKey);
+	});
+}
+var definePropertyType = createPropertyDecorator("transform/property-type");
+/**
+* Declare the runtime type of one DTO property.
+*
+* ```ts
+* class OrderDto {
+*   @PropertyType(() => UserDto) user!: UserDto;
+*   @PropertyType(() => ItemDto, { array: true }) items!: ItemDto[];
+*   @PropertyType(() => Date) createdAt!: Date;
+* }
+* ```
+*
+* A property without `@PropertyType` is assigned as-is, so primitives, plain
+* objects and arrays of primitives need no declaration — but they *do* need
+* something that makes the property known, otherwise the unknown-key rule drops
+* them.
+*/
+function PropertyType(type, options) {
+	if (typeof type !== "function") throw new SnailDecoratorError("[snail] @PropertyType() expects a lazy type resolver, e.g. @PropertyType(() => ChildDto)");
+	return definePropertyType(options ? {
+		type,
+		options
+	} : { type });
+}
+var defineExposeName = createPropertyDecorator("transform/expose-name");
+/**
+* Read a property from a differently-named JSON key.
+*
+* ```ts
+* class UserDto {
+*   @ExposeName("user_name") userName!: string;
+* }
+* // { "user_name": "ada" } → new UserDto().userName === "ada"
+* ```
+*
+* Excluding a key needs no decorator: undeclared JSON keys are already dropped.
+*/
+function ExposeName(jsonKey) {
+	if (typeof jsonKey !== "string" || jsonKey.length === 0) throw new SnailDecoratorError("[snail] @ExposeName() requires a non-empty JSON key");
+	return defineExposeName(jsonKey);
+}
+/** Read the DTO of one method: method first, then the api class. */
+function resolveDto(apiClass, methodName) {
+	return getMetadata(TRANSFORM_KEY, apiClass, methodName) ?? getMetadata(TRANSFORM_KEY, apiClass);
+}
+/** `true` for an own (not inherited) property. */
+function hasOwn(target, key) {
+	return Object.prototype.hasOwnProperty.call(target, key);
+}
+/**
+* Revive a JSON date.
+*
+* A string that `new Date()` rejects is returned unchanged: an `Invalid Date` is
+* truthy, serialises to `null` and fails every later check somewhere far from the
+* cause, so keeping the original string at least leaves the bug where it is.
+*/
+function reviveDate(value) {
+	if (value instanceof Date) return value;
+	if (typeof value !== "string" && typeof value !== "number") return value;
+	const date = new Date(value);
+	return Number.isNaN(date.getTime()) ? value : date;
+}
+/**
+* The property names a DTO declares.
+*
+* Two sources, and both are needed:
+* - the property decorators, which are the only way to see a `field!: T`
+*   declaration (TypeScript erases those at compile time);
+* - the instance's own keys, which cover initialised fields and constructor
+*   assignments and let a partially decorated DTO keep working.
+*
+* An empty result means the class declares nothing at all — see
+* {@link buildInstance}.
+*/
+function knownPropertyNames(DtoClass, instance) {
+	const names = /* @__PURE__ */ new Set([...collectMethodKeys(PROPERTY_TYPE_KEY, DtoClass), ...collectMethodKeys(EXPOSE_NAME_KEY, DtoClass)]);
+	for (const key of Object.keys(instance)) names.add(key);
+	return names;
+}
+/** Shallow-copy every own key of the JSON onto the instance. */
+function copyOwnKeys(target, source) {
+	for (const key of Object.keys(source)) target[key] = source[key];
+}
+/**
+* Hydrate one property value using the type declared for it.
+*
+* `childDepth` is the depth of `value` itself, so the depth guard in
+* {@link hydrateInto} can stop the descent before the stack does.
+*/
+function hydrateProperty(value, spec, options, childDepth, seen) {
+	if (!spec || value === null || value === void 0) return value;
+	const resolved = spec.type();
+	if (spec.options?.array === true) {
+		if (!Array.isArray(value)) return value;
+		return value.map((item) => hydrateValue(item, resolved, options, childDepth, seen));
+	}
+	return hydrateValue(value, resolved, options, childDepth, seen);
+}
+/**
+* Hydrate a single value against a resolved constructor.
+*
+* Primitives need no work — `JSON.parse` already produced the right JavaScript
+* type — and a non-function resolver is treated as "no type declared" rather than
+* a crash, because a typo in a decorator must not break every response.
+*/
+function hydrateValue(value, resolved, options, depth, seen) {
+	if (value === null || value === void 0) return value;
+	if (resolved === Date) return reviveDate(value);
+	if (resolved === String || resolved === Number || resolved === Boolean) return value;
+	if (typeof resolved !== "function") return value;
+	return hydrateInto(value, resolved, options, depth, seen);
+}
+/**
+* Build one instance, honouring `fromJSON`, the declared properties and
+* `keepUnknown`.
+*/
+function buildInstance(raw, DtoClass, options, depth, seen) {
+	if (typeof DtoClass.fromJSON === "function") return DtoClass.fromJSON(raw, options.ctx);
+	const instance = new DtoClass();
+	const known = knownPropertyNames(DtoClass, instance);
+	if (known.size === 0) {
+		copyOwnKeys(instance, raw);
+		return instance;
+	}
+	const consumed = /* @__PURE__ */ new Set();
+	for (const property of known) {
+		const jsonKey = getMetadata(EXPOSE_NAME_KEY, DtoClass, property) ?? property;
+		if (!hasOwn(raw, jsonKey)) continue;
+		consumed.add(jsonKey);
+		const spec = getMetadata(PROPERTY_TYPE_KEY, DtoClass, property);
+		instance[property] = hydrateProperty(raw[jsonKey], spec, options, depth + 1, seen);
+	}
+	if (options.keepUnknown) for (const key of Object.keys(raw)) {
+		if (consumed.has(key)) continue;
+		instance[key] = raw[key];
+	}
+	return instance;
+}
+/**
+* Recursive worker behind {@link hydrate}.
+*
+* Three guards, each fixing a way this could hang or lie:
+* - a non-object is returned unchanged, so a primitive payload passes through;
+* - `depth > maxDepth` stops a self-referencing `@PropertyType` chain;
+* - `seen` stops a *cyclic* JSON graph, which depth alone would only delay
+*   (branching recursion is exponential, not linear).
+*/
+function hydrateInto(raw, DtoClass, options, depth, seen) {
+	if (raw === null || typeof raw !== "object") return raw;
+	if (depth > options.maxDepth) return raw;
+	if (Array.isArray(raw)) return raw.map((item) => hydrateInto(item, DtoClass, options, depth + 1, seen));
+	if (seen.has(raw)) return raw;
+	seen.add(raw);
+	try {
+		return buildInstance(raw, DtoClass, options, depth, seen);
+	} finally {
+		seen.delete(raw);
+	}
+}
+/**
+* Turn a plain JSON payload into an instance of `DtoClass`.
+*
+* A primitive, `null`, an unknown class or an over-deep value is returned
+* unchanged rather than wrapped: the caller asked for a class, but a response that
+* does not look like one is more useful as-is than as an empty instance.
+*
+* ```ts
+* const user = hydrate(raw, UserDto);
+* user instanceof UserDto; // true
+* ```
+*/
+function hydrate(raw, DtoClass, options = {}) {
+	return hydrateInto(raw, DtoClass, {
+		keepUnknown: options.keepUnknown ?? false,
+		maxDepth: options.maxDepth ?? 32,
+		ctx: options.ctx
+	}, 0, /* @__PURE__ */ new WeakSet());
+}
+//#endregion
+//#region src/plugins/transform/plugin.ts
+/**
+* Hydrate the live response payload in place (by replacing the response body).
+*
+* A hydration failure must not corrupt the response: a throwing DTO constructor or
+* a broken `fromJSON` is reported and the raw JSON is left exactly as it arrived,
+* because a partially hydrated body is worse than an unhydrated one.
+*/
+function transformResponse(ctx, Dto, options) {
+	const response = ctx.getResponse();
+	if (!response) return;
+	const { dataKey } = ctx.serverOptions;
+	try {
+		const envelope = response.data;
+		const hydrated = hydrate(unwrapEnvelope(envelope, dataKey), Dto, {
+			keepUnknown: options.keepUnknown,
+			maxDepth: options.maxDepth,
+			ctx
+		});
+		ctx.setResponse({
+			...response,
+			data: looksLikeEnvelope(envelope, dataKey) ? {
+				...envelope,
+				[dataKey]: hydrated
+			} : hydrated
+		});
+	} catch (error) {
+		ctx.logger.warn(t("error.plugin.transform", ctx.fullName, String(error)));
+	}
+}
+/**
+* Create the transform plugin.
+*
+* ```ts
+* Service.use(Transform());
+*
+* @Api("/user")
+* @Transform(UserDto)
+* class UserApi {
+*   @Get("/:id")
+*   getUser(@Params("id") id: string): Promise<UserDto> { return null!; }
+* }
+* ```
+*
+* Without a DTO — no decorator and no `dto` option — the plugin is a no-op and the
+* payload stays the plain object JSON.parse produced.
+*/
+var transformPlugin = createPlugin({
+	name: "transform",
+	priority: 0,
+	setup(options) {
+		const fallbackDto = options?.dto;
+		const resolved = {
+			keepUnknown: options?.keepUnknown ?? false,
+			maxDepth: options?.maxDepth ?? 32
+		};
+		return { afterResponse(ctx, next) {
+			const Dto = resolveDto(ctx.apiClass, ctx.methodName) ?? fallbackDto;
+			if (Dto) transformResponse(ctx, Dto, resolved);
+			return next();
+		} };
+	}
+});
+//#endregion
+//#region src/plugins/transform/index.ts
+function Transform(input) {
+	return typeof input === "function" ? Transform$1(input) : transformPlugin(input);
+}
+//#endregion
+//#region src/plugins/validate/decorators.ts
+/**
+* `@Validate(schema)` / `@ValidateResponse(schema)` — attach a zod schema to a
+* request or to a response body.
+*
+* Both work on an api class and on a single method. A class-level schema applies
+* to every method of the class; a method-level one overrides it, which is the only
+* ordering that lets one endpoint deviate without redeclaring the class default on
+* every sibling.
+*/
+/** Metadata slot written by `@Validate`. */
+var REQUEST_SCHEMA_KEY = customMetadataKey("validate/request");
+/** Metadata slot written by `@ValidateResponse`. */
+var RESPONSE_SCHEMA_KEY = customMetadataKey("validate/response");
+/**
+* Build a class/method decorator that stores one schema.
+*
+* The value is checked at decoration time, not at request time: a typo like
+* `@Validate({})` would otherwise stay silent until a request ran, and then read
+* as "the payload is malformed" instead of "the decorator is wrong".
+*/
+function schemaDecorator(key, label) {
+	return (schema) => {
+		if (!schema || typeof schema.safeParse !== "function") throw new SnailDecoratorError(`[snail] @${label}() expects a zod schema with a safeParse() method`);
+		return ((target, propertyKey) => {
+			defineMetadata(key, schema, target, propertyKey);
+		});
+	};
+}
+var defineRequestSchema = schemaDecorator(REQUEST_SCHEMA_KEY, "Validate");
+var defineResponseSchema = schemaDecorator(RESPONSE_SCHEMA_KEY, "ValidateResponse");
+/**
+* Validate the outgoing request body (or query) against a zod schema.
+*
+* ```ts
+* @Post("/")
+* @Validate(z.object({ name: z.string().min(1) }))
+* create(@Data() body: CreateUser): Promise<User> { return null!; }
+* ```
+*/
+function Validate$1(schema) {
+	return defineRequestSchema(schema);
+}
+/**
+* Validate the response payload against a zod schema.
+*
+* Response validation only ever warns: the backend, not the caller, decides what
+* it sends, and throwing away a usable payload because one field is unexpected
+* turns a cosmetic backend drift into a broken page.
+*/
+function ValidateResponse(schema) {
+	return defineResponseSchema(schema);
+}
+/** Read the request schema of one method: method first, then the api class. */
+function resolveRequestSchema(apiClass, methodName) {
+	return getMetadata(REQUEST_SCHEMA_KEY, apiClass, methodName) ?? getMetadata(REQUEST_SCHEMA_KEY, apiClass);
+}
+/** Read the response schema of one method: method first, then the api class. */
+function resolveResponseSchema(apiClass, methodName) {
+	return getMetadata(RESPONSE_SCHEMA_KEY, apiClass, methodName) ?? getMetadata(RESPONSE_SCHEMA_KEY, apiClass);
+}
+//#endregion
+//#region src/plugins/validate/type.ts
+/**
+* Thrown when the request payload does not satisfy its schema.
+*
+* The request is abandoned **before** anything reaches the network, which is the
+* whole point of validating a request: an invalid body that is still sent produces
+* a backend error that looks like a server bug, and a `4xx` that pollutes the
+* application's error handling for what is really a programmer mistake.
+*
+* `issues` is zod's own list, kept verbatim so the application can render field
+* paths and messages instead of parsing a string.
+*/
+var SnailValidationError = class extends SnailError {
+	constructor(message, options) {
+		super(message, {
+			code: "SNAIL_VALIDATION_ERROR",
+			cause: options.cause
+		});
+		this.issues = options.issues;
+	}
+};
+//#endregion
+//#region src/plugins/validate/plugin.ts
+/**
+* Zod validation plugin.
+*
+* ## The asymmetry, and why it is deliberate
+*
+* **An invalid request aborts the call.** The request never reaches the network:
+* a body that fails its own schema is a programmer mistake, and the backend error
+* it would produce points at the wrong layer.
+*
+* **An invalid response only warns.** The response is already here and the caller
+* asked for it; throwing it away because the backend added, renamed or retyped a
+* field turns a cosmetic drift into a broken page. The warning carries zod's
+* issues so the drift is still visible in the console.
+*
+* ## Priority
+*
+* `-50` — the reserved validate band. In the forward phase it runs after the
+* version (`50`) and the adapters (`0`) have finished shaping the request, and
+* before the cache (`-100`) is asked for a key. On the unwind side it runs after
+* the cache and before the adapters, so the response is validated *before* the
+* transform plugin replaces the payload with class instances.
+*/
+/**
+* The value a request schema validates.
+*
+* Write verbs carry a body, read verbs carry query params. Validating the body
+* when there is one and the query otherwise means one decorator covers both, and
+* a request that carries neither (`undefined`) is left to the backend rather than
+* failing against an empty object.
+*/
+function requestTarget(ctx) {
+	return ctx.request.data !== void 0 ? ctx.request.data : ctx.request.params;
+}
+/**
+* Validate the outgoing request, throwing when `strict`.
+*
+* Never calls `next()` on failure: the chain ends, `send()` rejects with the
+* {@link SnailValidationError}, and no axios adapter is ever reached.
+*/
+function validateRequest(ctx, schema, strict, next) {
+	const target = requestTarget(ctx);
+	if (target === void 0) return next();
+	const parsed = schema.safeParse(target);
+	if (parsed.success) return next();
+	const message = t("error.plugin.validate.request", ctx.fullName);
+	if (!strict) {
+		ctx.logger.warn(message, parsed.error.issues);
+		return next();
+	}
+	throw new SnailValidationError(message, { issues: parsed.error.issues });
+}
+/**
+* Validate the response payload and warn about it.
+*
+* A throwing logger or a malformed schema must not fail the request, so the whole
+* check is defensive: the caller still receives the payload no matter what.
+*/
+function warnOnInvalidResponse(ctx, schema) {
+	try {
+		const response = ctx.getResponse();
+		if (!response) return;
+		const payload = unwrapEnvelope(response.data, ctx.serverOptions.dataKey);
+		const parsed = schema.safeParse(payload);
+		if (parsed.success) return;
+		ctx.logger.warn(t("error.plugin.validate.response", ctx.fullName), parsed.error.issues);
+	} catch (error) {
+		ctx.logger.warn(t("error.plugin.validate.response", ctx.fullName), error);
+	}
+}
+/**
+* Create the zod validation plugin.
+*
+* ```ts
+* Service.use(Validate({ strict: false }));
+* ```
+*
+* It is normally used without options, together with the decorators:
+* `Service.use(Validate())`.
+*/
+var validatePlugin = createPlugin({
+	name: "validate",
+	priority: -50,
+	setup(options) {
+		const fallbackRequest = options?.request;
+		const fallbackResponse = options?.response;
+		const strict = options?.strict ?? true;
+		return {
+			beforeRequest(ctx, next) {
+				const schema = resolveRequestSchema(ctx.apiClass, ctx.methodName) ?? fallbackRequest;
+				if (!schema) return next();
+				return validateRequest(ctx, schema, strict, next);
+			},
+			afterResponse(ctx, next) {
+				const schema = resolveResponseSchema(ctx.apiClass, ctx.methodName) ?? fallbackResponse;
+				if (schema) warnOnInvalidResponse(ctx, schema);
+				return next();
+			}
+		};
+	}
+});
+//#endregion
+//#region src/plugins/validate/index.ts
+function Validate(input) {
+	return isZodSchema(input) ? Validate$1(input) : validatePlugin(input);
+}
+/** `true` for a zod schema — the only shape the decorator overload accepts. */
+function isZodSchema(value) {
+	return typeof value?.safeParse === "function";
+}
+//#endregion
+//#region src/plugins/version/decorators.ts
+/**
+* `@Version(...)` — declare the api version of a class or of one method.
+*
+* Method wins over class, class wins over the plugin's `defaultVersion`, which is
+* the only ordering that lets one endpoint of a class deviate without forcing
+* every sibling to restate the class version.
+*
+* The decorator is intentionally metadata-only: it never touches the request or
+* the server, so decorating a class from a shared module cannot leak a version
+* into another server instance.
+*/
+/**
+* Metadata slot written by `@Version`.
+*
+* One key covers both levels: a class decorator stores under the class slot and a
+* method decorator under the method name, so a reader never has to know which
+* decorator wrote the value.
+*/
+var VERSION_KEY = customMetadataKey("versioning/version");
+/**
+* Declare the version of an api class or of a single request method.
+*
+* ```ts
+* @Api("/user")
+* @Version("1.2.0")
+* class UserApi {
+*   @Get("/legacy")
+*   @Version("0.9.0")
+*   legacy(): Promise<void> { return null!; }
+* }
+* ```
+*/
+function Version(version) {
+	if (typeof version !== "string" || version.length === 0) throw new SnailDecoratorError("[snail] @Version() requires a non-empty version string");
+	return ((target, propertyKey) => {
+		defineMetadata(VERSION_KEY, version, target, propertyKey);
+	});
+}
+/**
+* Read the version declared for one method.
+*
+* Reads the method slot first, then the class slot, and both walk the prototype
+* chain so a subclass inherits the version of its base api class.
+*/
+function resolveDeclaredVersion(apiClass, methodName) {
+	return getMetadata(VERSION_KEY, apiClass, methodName) ?? getMetadata(VERSION_KEY, apiClass);
+}
+//#endregion
+//#region src/plugins/version/plugin.ts
+/**
+* Version management plugin.
+*
+* ## What it rewrites
+*
+* Only the live request on the context — never `server.defaults.baseURL`, never
+* the shared axios instance.
+*
+* The pre-rewrite implementation baked the version into the server's `baseURL`
+* the first time any request ran. That leaked: the first method to run decided
+* the version of every later request on that server, so calling a `v2` endpoint
+* once silently moved the whole application to `v2`. Resolving the version per
+* request from the method/class metadata makes that unrepresentable.
+*
+* ## Priority
+*
+* `50` — inside the reserved version band. It runs after an interceptor (`100`)
+* so it sees the url the interceptor produced, and before the cache (`-100`) so
+* the cache hashes the versioned url instead of a url that changes under it.
+*/
+/**
+* Default key or url segment name per transport.
+*
+* `url` keeps the conventional `v` marker, so a bare
+* `Versioning({ type: "url", defaultVersion: "1.0.0" })` turns `/user/1` into
+* `/v1.0.0/user/1`. Pass `key: ""` for a bare `/1.0.0/user/1` segment.
+*/
+var DEFAULT_KEYS = {
+	url: "v",
+	header: "x-api-version",
+	query: "v"
+};
+/**
+* Validate and normalise the factory options.
+*
+* Runs once per server, inside `setup`. Throwing here rolls the registration back,
+* so a misconfigured plugin is never half-installed and silently doing nothing.
+*/
+function resolveVersioningOptions(options) {
+	const type = options?.type ?? "url";
+	if (type !== "url" && type !== "header" && type !== "query" && type !== "custom") throw new SnailPluginError(`[snail] Versioning() received an unknown type "${String(type)}"`, { pluginName: "versioning" });
+	const defaultVersion = options?.defaultVersion;
+	if (typeof defaultVersion !== "string" || defaultVersion.length === 0) throw new SnailPluginError("[snail] Versioning() requires a non-empty `defaultVersion`", { pluginName: "versioning" });
+	if (type === "custom" && typeof options?.extractor !== "function") throw new SnailPluginError("[snail] Versioning({ type: \"custom\" }) requires an `extractor` function", { pluginName: "versioning" });
+	return {
+		type,
+		defaultVersion,
+		key: type === "custom" ? options?.key ?? "" : options?.key ?? DEFAULT_KEYS[type],
+		extractor: options?.extractor
+	};
+}
+/**
+* The mutable header bag of the request, created when a plugin or a decorator
+* has not produced an `AxiosHeaders` yet.
+*/
+function headerBag(ctx) {
+	if (!(ctx.request.headers instanceof AxiosHeaders)) ctx.request.headers = AxiosHeaders.from(ctx.request.headers ?? {});
+	return ctx.request.headers;
+}
+/** `true` when `segment` already is one of the url's path segments. */
+function hasSegment(url, segment) {
+	return (url.split(/[?#]/, 1)[0] ?? "").split("/").includes(segment);
+}
+/**
+* Prepend `<key><version>` as the first path segment.
+*
+* Absolute urls are left untouched — prefixing them would corrupt the host — and
+* a url that already carries the segment is returned as-is, so a method whose path
+* hard-codes the version is not rewritten twice.
+*/
+function applyURLVersion(url, version, key) {
+	const segment = `${key}${version}`;
+	if (isAbsoluteURL(url) || hasSegment(url, segment)) return url;
+	if (url.length === 0) return `/${segment}`;
+	return `/${segment}${url.startsWith("/") ? "" : "/"}${url}`;
+}
+/** Write the version header, replacing any value the caller already set. */
+function applyHeaderVersion(ctx, version, key) {
+	headerBag(ctx).set(key, version);
+}
+/** Merge the version into the query params without dropping the existing ones. */
+function applyQueryVersion(ctx, version, key) {
+	const current = ctx.request.params;
+	ctx.request.params = {
+		...isPlainObject(current) ? current : {},
+		[key]: version
+	};
+}
+/** Delegate to the caller's extractor and merge whatever patch it returns. */
+function applyCustomVersion(ctx, version, extractor) {
+	const patch = extractor(version, ctx);
+	if (!patch) return;
+	if (typeof patch.url === "string") ctx.request.url = patch.url;
+	if (patch.headers) {
+		const headers = headerBag(ctx);
+		for (const [key, value] of Object.entries(patch.headers)) headers.set(key, value);
+	}
+	if (patch.params) {
+		const current = ctx.request.params;
+		ctx.request.params = {
+			...isPlainObject(current) ? current : {},
+			...patch.params
+		};
+	}
+}
+/**
+* Resolve the effective version and rewrite the live request.
+*
+* The default version is applied too, not skipped: the backend wants `/v1.0.0`
+* for an undeclared method, and nothing else in the pipeline knows that. Only the
+* *logging* distinguishes an explicit version from the default.
+*/
+function applyVersion(ctx, options) {
+	const version = resolveDeclaredVersion(ctx.apiClass, ctx.methodName) ?? options.defaultVersion;
+	if (version !== options.defaultVersion) {
+		ctx.logger.info(t("info.version.change", ctx.fullName, version));
+		ctx.logger.warn(t("warn.version.change", ctx.fullName, options.defaultVersion, version));
+	}
+	switch (options.type) {
+		case "url":
+			ctx.request.url = applyURLVersion(ctx.request.url ?? ctx.route, version, options.key);
+			return;
+		case "header":
+			applyHeaderVersion(ctx, version, options.key);
+			return;
+		case "query":
+			applyQueryVersion(ctx, version, options.key);
+			return;
+		case "custom":
+			applyCustomVersion(ctx, version, options.extractor);
+			return;
+	}
+}
+/**
+* Create the version management plugin.
+*
+* ```ts
+* Service.use(Versioning({ type: "url", defaultVersion: "1.0.0" }));
+* ```
+*
+* The rewrite happens in `beforeRequest`, so it is the last thing that can change
+* the url before the request is hashed, cached and sent.
+*/
+var Versioning = createPlugin({
+	name: "versioning",
+	priority: 50,
+	setup(options) {
+		const resolved = resolveVersioningOptions(options);
+		return { beforeRequest(ctx, next) {
+			applyVersion(ctx, resolved);
+			return next();
+		} };
+	}
+});
+//#endregion
+export { AfterResponse, BeforeRequest, CACHE_PLUGIN_NAME, CACHE_PRIORITY, Cache, CacheManager, Cacheable, DEFAULT_L1_MAX_SIZE, ExposeName, HitSource, INTERCEPTOR_PLUGIN_NAME, INTERCEPTOR_PRIORITY, IndexedDBCacheAdapter, Interceptor, InterceptorManager, Invalidates, MemoryCacheAdapter, NoCache, POOL_ERROR_CODES, POOL_PLUGIN_NAME, POOL_PRIORITY, PropertyType, RequestPool, RequestPoolScheduler, SnailPoolError, SnailValidationError, Transform, Validate, ValidateResponse, Version, Versioning, WebStorageCacheAdapter, buildCacheKey, classAfterEntries, classBeforeEntries, clearPool, hydrate, isPoolError, makeCachedResponse, methodAfterEntries, methodBeforeEntries, poolStats, readCacheable, readInvalidates, readNoCache };
+
+//# sourceMappingURL=index.js.map